Clavem

Verify an Ed25519 license token offline in Flutter

Split the token on dots, decode the parts with base64Url.normalize, verify the Ed25519 signature over the text "sgt1.<payload>" with package:cryptography, then check v, pid, valid, exp and refresh_by. No network call is needed.

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.decode throws on it, so every part goes through normalize first.
  • Speed. The cryptography package is pure Dart, so it needs no platform setup. cryptography_flutter adds 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'] == 1 still 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 kh claim, 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.

Sources

  1. cryptography package, Ed25519 class (checked November 2026)
  2. cryptography_flutter on pub.dev (checked November 2026)