The verifier
A Clavem token is sgt1.<payload>.<signature>. The signature is Ed25519 over the ASCII text of the first two parts joined by a dot, exactly as received. Offline verification describes the format and each claim. This is the Deno version, in TypeScript, with the claims typed.
// token.ts: verifies a Clavem sgt1 token with Web Crypto. Needs no permissions.
import { decodeBase64Url } from "jsr:@std/encoding@1/base64url";
export interface Claims {
v: number;
lid: number;
pid: number;
kh: string;
status: "active" | "inactive" | "expired" | "disabled";
valid: boolean;
iid?: string;
fp?: string;
email?: string;
iat: number;
exp?: number;
refresh_by: number;
}
/** Returns the claims when the signature is valid, otherwise null. */
export async function verifyToken(token: unknown, publicKey: string): Promise<Claims | null> {
if (typeof token !== "string") return null;
const parts = token.split(".");
if (parts.length !== 3 || parts[0] !== "sgt1") return null;
try {
// decodeBase64Url throws on anything that is not base64url, unlike Node's Buffer.
const key = await crypto.subtle.importKey("raw", decodeBase64Url(publicKey), { name: "Ed25519" }, false, ["verify"]);
const signed = new TextEncoder().encode(parts[0] + "." + parts[1]); // the text as received
if (!await crypto.subtle.verify({ name: "Ed25519" }, key, decodeBase64Url(parts[2]), signed)) return null;
return JSON.parse(new TextDecoder().decode(decodeBase64Url(parts[1]))) as Claims;
} catch {
return null; // malformed token or key
}
}
/** The checks your app should make on a verified token. */
export function isLicensed(claims: Claims | null, productId: number, now = Date.now() / 1000): boolean {
return (
claims !== null &&
claims.v === 1 &&
claims.pid === productId &&
claims.valid === true &&
(claims.exp === undefined || claims.exp > now) &&
claims.refresh_by > now
);
}
/** Optional: confirms the token was issued for the key the customer typed. */
export async function matchesKey(claims: Claims, licenseKey: string): Promise<boolean> {
const trimmed = licenseKey.trim();
const native = /^[0-9A-Za-z]{5}(?:-[0-9A-Za-z]{5}){4}$/.test(trimmed);
const normalized = native
? trimmed.toUpperCase().replace(/[IL]/g, "1").replace(/O/g, "0").replace(/U/g, "V")
: trimmed.toLowerCase();
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(normalized));
const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
return hex.slice(0, 16) === claims.kh;
}
as Claims is a cast, not a check. Nothing validates the shape of a payload that passed the signature, so isLicensed compares every field it relies on, and a missing refresh_by fails the comparison instead of passing it.
Zero permissions
Verification does not touch the network, the disk or the environment, so it runs with no allow flag at all. We ran the test file with deno run --no-prompt and the standard-library import resolved without --allow-net, because Deno loads modules from the static import graph without consulting the permission system. Tokens were signed with a throwaway Ed25519 key in the documented format, with PRODUCT_ID 75:
| Token | Result |
|---|---|
| Fresh and active | Signature ok, licensed |
pid edited after signing |
Signature rejected |
refresh_by six days ago |
Signature ok, not licensed |
Expired license, valid: false |
Signature ok, not licensed |
Signed for product 99, v: 2, or exp in the past |
Signature ok, not licensed |
| Signed by another key pair | Signature rejected |
| Not a string, or a garbage public key | null |
matchesKey returned true for the demo key typed in capitals and for the same key in lowercase with spaces around it. Its output, 7e0e4148136b6dae, is the kh claim the live demo license carries. We could not verify the demo license’s real signature, because the demo product’s public key is not available to us. deno check passed on the file.
Strict decoding
The standard-library decoder is strict. It threw a TypeError on a signature with two junk characters appended, where Node’s Buffer would have ignored the characters. A signature cut short by four characters fails the verify. One difference to know about: it accepted a trailing =, which Clavem never sends.
If you would rather add no dependency, atob does the job. It also rejects junk, and it accepts base64url once - and _ are swapped back:
const bytes = (b64url: string) =>
Uint8Array.from(atob(b64url.replaceAll("-", "+").replaceAll("_", "/")), (c) => c.charCodeAt(0));
Use bytes where decodeBase64Url appears above. We ran this variant on the same vectors with the same verdicts, and deno check accepts it.
If you keep the import, the @1 pins a major version. Commit deno.lock so a build next year resolves to the same files.
Where the public key goes
A string constant in the source works. For a tool you compile, a JSON file imported with an attribute keeps the key and the product id in one place:
import product from "./product.json" with { type: "json" }; // { "publicKey": "...", "productId": 75 }
A static import is part of the module graph, so it needs no --allow-read. We compiled a test file that imports its vectors this way and ran the executable from the root folder: it did not need the file next to it, because deno compile embeds the graph. Do not read the key from an environment variable. That costs an --allow-env entry and lets the customer’s shell replace the key.
What the check cannot do
The public key is inside your executable, and the script is embedded in it. Someone who edits the executable can replace the key or the check. Offline verification stops forged and altered tokens and lets honest customers work offline. It does not stop a patched program. The other limits, including how long a disabled license keeps verifying, are listed under what a token cannot tell you.
Where the token is stored, and the online call that replaces it every 14 days, are on the validation page.
Doing this with Clavem
Each Clavem product has its own Ed25519 key pair. The private half stays with Clavem; the public half is on the product page and in GET /v1/admin/products. The Ed25519 key generator is there if you want to practice the encoding with keys of your own.
Questions
Does verifying a token in Deno need any permission?
No. The check is pure computation on strings. We ran it under deno run --no-prompt with no allow flags and it verified, rejected and checked claims normally. Only the network call that fetches a fresh token needs --allow-net.
Can I use Web Crypto without the standard library?
Yes. A four-line helper built on atob decodes base64url, and crypto.subtle does the rest. The standard-library decoder is optional and is pinned to a major version in the sample.