The token in one paragraph
Every activate and validate response carries token: sgt1.<payload>.<signature>. The payload is base64url JSON, the signature is 64 bytes of Ed25519 over the ASCII text sgt1.<payload> exactly as received, and the product’s public key is 32 raw bytes in base64url. The format and claims are on the offline verification reference. This page is the Dart.
Verify and check
// pubspec.yaml: cryptography
import 'dart:convert';
import 'dart:typed_data';
import 'package:cryptography/cryptography.dart';
const publicKey = 'YOUR_PUBLIC_KEY'; // from your product page
const productId = 75; // from your product page
Uint8List? _b64url(String s) {
try {
// Dart's decoder insists on padding. normalize() adds it.
return base64Url.decode(base64Url.normalize(s));
} on FormatException {
return null;
}
}
/// Claims when the signature is good, otherwise null.
Future<Map<String, dynamic>?> verifyToken(String token, String publicKeyB64) async {
final parts = token.split('.');
if (parts.length != 3 || parts[0] != 'sgt1') return null;
final key = _b64url(publicKeyB64), sig = _b64url(parts[2]), body = _b64url(parts[1]);
if (key == null || sig == null || body == null || key.length != 32 || sig.length != 64) return null;
final ok = await Ed25519().verify(
utf8.encode('${parts[0]}.${parts[1]}'), // the text as received, not the decoded JSON
signature: Signature(sig, publicKey: SimplePublicKey(key, type: KeyPairType.ed25519)),
);
if (!ok) return null;
try {
final claims = jsonDecode(utf8.decode(body));
return claims is Map<String, dynamic> ? claims : null;
} on FormatException {
return null;
}
}
bool isLicensed(Map<String, dynamic>? c, int pid, int now) {
if (c == null) return false;
final exp = c['exp'], refreshBy = c['refresh_by'];
return c['v'] == 1 &&
c['pid'] == pid &&
c['valid'] == true &&
(exp == null || (exp is num && exp > now)) &&
refreshBy is num &&
refreshBy > now;
}
verifyToken returns null for every failure: wrong shape, bad base64, wrong key length, bad signature, broken JSON. isLicensed is the five checks from the reference. A token for another product verifies against its own key, not yours, but check pid anyway.
Wire it to the launch check
LicenseService from the validation page calls tokenIsFresh(token) when it gets no answer. Add the clock guard here:
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
const _store = FlutterSecureStorage();
const _slack = 600; // seconds of clock error to forgive
Future<bool> tokenIsFresh(String token) async {
final claims = await verifyToken(token, publicKey);
if (claims == null) return false;
final now = DateTime.now().millisecondsSinceEpoch ~/ 1000;
final seen = int.tryParse(await _store.read(key: 'clavem.high_iat') ?? '') ?? 0;
if (now + _slack < seen) return false; // the clock is behind a time the server already stamped
final iat = claims['iat'];
if (iat is int && iat > seen) await _store.write(key: 'clavem.high_iat', value: '$iat');
return isLicensed(claims, productId, now);
}
refresh_by is iat plus 14 days. A user who sets the clock back keeps a token fresh. Storing the highest iat you have seen shuts the cheapest version of that. It does not stop someone who deletes the stored value, so treat it as a speed bump.
Test it without Clavem’s key
Your tests need no real token. Make a throwaway key pair, mint tokens in the same format, and pass its public key to verifyToken:
Future<String> mint(SimpleKeyPair pair, Map<String, Object?> claims) async {
String enc(List<int> b) => base64Url.encode(b).replaceAll('=', '');
final head = 'sgt1.${enc(utf8.encode(jsonEncode(claims)))}';
final sig = await Ed25519().sign(utf8.encode(head), keyPair: pair);
return '$head.${enc(sig.bytes)}';
}
// final pair = await Ed25519().newKeyPair();
// final pub = base64Url.encode((await pair.extractPublicKey()).bytes).replaceAll('=', '');
Mint these and assert the result:
| Token | Expected |
|---|---|
Good claims, refresh_by in 14 days |
licensed |
Payload edited after signing (pid changed) |
verifyToken returns null |
| Signed by a different key pair | verifyToken returns null |
refresh_by a day ago |
not licensed: connect once |
valid: false, status: expired |
not licensed |
pid of another product |
not licensed |
v: 2 |
not licensed |
exp in the past |
not licensed |
I ran these steps in Node.js with node:crypto against tokens signed by a throwaway key, and every row came out as listed. The Dart code above has not been executed.
Flutter specifics
- Padding. The reference docs use unpadded base64url.
base64Url.decodethrows on it, so every part goes throughnormalizefirst. - Speed. The
cryptographypackage is pure Dart, so it needs no platform setup.cryptography_flutteradds operating system implementations on Android, iOS and macOS. I have not timed either, and one verification a launch is unlikely to need it. - Web. JSON numbers become JavaScript numbers, so
c['v'] == 1still holds. Everything a web build stores is readable by the user, so the signature, not secrecy, is what protects the token. - The key and the token travel together in secure storage. The
khclaim, the first 16 hex characters of the SHA-256 of the normalized key, ties a token to the key the customer typed, if you want that check.
Doing this with Clavem
Each product has its own key pair. Copy the public key from the product page, or read public_key from GET /v1/admin/products. Tokens already on customers’ machines stay valid until refresh_by, whatever happens to the service.
Questions
Do I need cryptography_flutter?
No. The cryptography package verifies Ed25519 in pure Dart with no platform setup. cryptography_flutter swaps in operating system implementations on Android, iOS and macOS if you want them.
Where does the public key go?
In a constant in your Dart code. It is not a secret, and shipping it is the intended use. A user who patches your binary could swap it, which no client-side check can prevent.