Clavem

Verify an Ed25519 license token offline in Node.js

Node's built-in node:crypto can verify the Ed25519 signature on a Clavem token with no package at all. Import the 32-byte public key as a JWK, verify the text "sgt1.<payload>" as received, then check v, pid, valid, exp and refresh_by.

The verifier

A Clavem token is sgt1.<payload>.<signature>. The signature is Ed25519 over the ASCII text of the first two parts, joined by the dot, exactly as received. The payload is base64url JSON. The format and every claim are described on offline verification; this page is the Node.js version, and it needs only node:crypto.

// token.mjs: verifies a Clavem sgt1 token with node:crypto. Node 16 or later, no dependencies.
import { createHash, createPublicKey, verify } from 'node:crypto';

/** Returns the claims when the signature is valid, otherwise null. */
export function verifyToken(token, publicKey) {
  if (typeof token !== 'string') return null;
  const parts = token.split('.');
  if (parts.length !== 3 || parts[0] !== 'sgt1') return null;
  try {
    // The public key is the 32 raw bytes, base64url. JWK import takes it as is.
    const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey }, format: 'jwk' });
    const signature = Buffer.from(parts[2], 'base64url');
    if (signature.length !== 64) return null; // Buffer ignores bad characters, so check the length
    const signed = Buffer.from(parts[0] + '.' + parts[1]); // the text as received, not the decoded payload
    if (!verify(null, signed, key, signature)) return null; // Ed25519 takes no digest: pass null
    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
  } catch {
    return null; // malformed token or key
  }
}

/** The checks your app should make on a verified token. */
export function isLicensed(claims, productId, now = Date.now() / 1000) {
  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 function matchesKey(claims, licenseKey) {
  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();
  return createHash('sha256').update(normalized).digest('hex').slice(0, 16) === claims.kh;
}

Keep the public key from your product page in your source as a string constant. It is not a secret. verifyToken returns null for a bad signature and for anything malformed, so one null check covers both.

What the checks stop

Check Stops
Signature A token that was edited, or made by someone who has no private key.
v === 1 A future format your code does not understand.
pid equals your product A genuine token from your other product, or another seller’s.
valid === true An expired or disabled license. Those still get signed tokens, marked valid: false.
exp in the future A subscription past its three days of grace. Absent for perpetual licenses.
refresh_by in the future A token older than 14 days. Time to ask the server again.
matchesKey A token pasted next to a different key than the one it was issued for.

Test results

The tokens below were signed with a throwaway Ed25519 key in the documented format, because the demo product’s private key is not available to us. They ran on Node 26 against verifyToken and isLicensed with PRODUCT_ID set to 75.

Token Signature Licensed
Fresh, active valid yes
Payload edited after signing (pid changed) rejected no
refresh_by six days ago valid no, ask the server
Expired license, valid: false valid no
Signed for product 99 valid no
v: 2 valid no
exp ten seconds ago valid no
Signed by a different key pair rejected no
Not a string, two parts, prefix sgt2, garbage public key null no

matchesKey returned true for the demo key typed in capitals, and for the same key in lowercase with spaces around it. The demo license’s real token carries kh 7e0e4148136b6dae, which is what the function computes for that key, so the normalization matches the server’s. Its payload decodes to lid 1 and pid 1. We could not check that token’s signature, since that needs the demo product’s public key.

Node traps

  • Lenient base64url. A signature with = padding, or with two junk characters appended, still verified, because Buffer drops characters it does not know. That is harmless for security, since the bytes that matter are unchanged, but it means Buffer is not a validator. A truncated signature fails the length check.
  • The signed text. Verify parts[0] + '.' + parts[1] as received. Re-serializing the parsed payload changes key order or spacing and breaks the signature.
  • Digest argument. crypto.verify takes null as the algorithm for Ed25519. Passing 'sha256' throws.
  • Web Crypto. On Node 20 and later crypto.subtle also verifies Ed25519, as in the JavaScript example. It is asynchronous, which node:crypto is not here, so the code above can sit in a synchronous startup path.

Clock and copying

A customer can move the system clock back to keep a token inside its 14 days. Store the highest iat you have seen next to the token and treat a clock behind it as stale:

// Call after verifyToken. Persist maxIat with the rest of the license file.
export function clockSetBack(claims, saved, now = Date.now() / 1000) {
  const maxIat = Math.max(saved.maxIat ?? 0, claims.iat);
  return { setBack: now < maxIat, maxIat };
}

A copied license file carries a valid token to another machine. If the activation sent a fingerprint, the token carries it back as fp, so compare it with the fingerprint function from device activation and refuse the token when they differ.

Be clear about the limit. Your JavaScript, and the public key inside it, ships in readable form, also when you bundle it into a single executable. A buyer who edits the code can skip the check. Offline verification stops forged and altered tokens, and keeps honest customers working offline; it does not make a determined patch impossible. The other limits, revocation within the 14 days among them, are in what a token cannot tell you.

Doing this with Clavem

Clavem signs a token on every activate and validate response, one Ed25519 key pair per product. The token decoder shows the claims of any token you paste.

Questions

Do I need a package like tweetnacl or jose to verify Ed25519 in Node?

No. node:crypto verifies Ed25519 with crypto.verify(null, data, key, signature). Import the raw public key through a JWK with kty OKP and crv Ed25519, so no PEM or DER wrapping is needed.

Why does the code check that the signature is 64 bytes?

Buffer.from(value, 'base64url') silently skips characters that are not base64url. A damaged string can decode to a different length without any error, so the length check turns that into a clean rejection.

Sources

  1. Node.js documentation, crypto.verify and key import (checked November 2026)