Clavem

Verify a Clavem license token offline in a VS Code extension

On the desktop extension host, verify the signature with node:crypto and the public key as a JWK. In a web extension host, where node:crypto does not exist, use the bundled noble-ed25519. Then check the claims, and compare the token's fp claim with this machine's fingerprint.

The token format and the claim checks are in the offline verification reference, which has a JavaScript isLicensed function. Use its checks as they are. This page covers what is specific to VS Code: choosing the signature routine for the extension host you run in, binding a token to one machine, and where the state lives. The call that fetches the token is in license key validation in a VS Code extension.

One verifier, two engines

An extension can run in a Node extension host on desktop, or in a web extension host in vscode.dev and github.dev. They share the language and not the standard library. The code below picks the engine at run time and checks the same things in both:

// src/token.js
import * as ed from '@noble/ed25519';

const ALPHABET = /^[A-Za-z0-9_-]+$/;
const bytes = (s) => (ALPHABET.test(s) ? Uint8Array.from(atob(s.replaceAll('-', '+').replaceAll('_', '/')), (c) => c.charCodeAt(0)) : null);

/** Desktop extension host (Node): no dependency. The key's x member is the base64url string from your product page. */
async function verifyNode(publicKey, message, signature) {
  const { createPublicKey, verify } = await import('node:crypto');
  const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey }, format: 'jwk' });
  return verify(null, Buffer.from(message), key, Buffer.from(signature));
}

/** Web extension host: there is no node:crypto, so use noble. */
async function verifyWeb(publicKey, message, signature) {
  return ed.verifyAsync(signature, message, bytes(publicKey));
}

const isNode = typeof process !== 'undefined' && !!process.versions?.node;

/** Claims when the signature is good, otherwise 'malformed' or 'bad-signature'. */
export async function claims(token, publicKey) {
  const parts = typeof token === 'string' ? token.split('.') : [];
  if (parts.length !== 3 || parts[0] !== 'sgt1') return 'malformed';
  const signature = bytes(parts[2]), payload = bytes(parts[1]), key = bytes(publicKey.trim());
  if (!signature || signature.length !== 64 || !payload || !key || key.length !== 32) return 'malformed';
  const message = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
  const ok = isNode ? await verifyNode(publicKey.trim(), message, signature) : await verifyWeb(publicKey.trim(), message, signature);
  if (!ok) return 'bad-signature';
  try { const c = JSON.parse(new TextDecoder().decode(payload)); return c && typeof c === 'object' ? c : 'malformed'; } catch { return 'malformed'; }
}

/** The documented checks, plus binding to this machine through the fp claim. */
export async function check(token, { publicKey, productId, fingerprint, highestIat = 0, now = Date.now() / 1000 }) {
  const c = await claims(token, publicKey);
  if (typeof c === 'string') return c;
  if (c.v !== 1) return 'malformed';
  if (c.pid !== productId) return 'wrong-product';
  if (c.valid !== true) return 'not-valid';
  if (c.fp !== undefined && c.fp !== fingerprint) return 'other-machine';
  if (c.exp !== undefined && c.exp <= now) return 'expired';
  if (now < highestIat) return 'clock-set-back';
  if (!(c.refresh_by > now)) return 'stale';
  return 'ok';
}

Bundle the extension with esbuild once for each target, and mark node:crypto as external in the desktop build. Keep the dynamic import('node:crypto') out of the web build, or the bundler tries to resolve it.

Test results

Tokens signed with a throwaway key in the documented sgt1 format, with a verifier holding its public half. Both engines gave the same answers on every token:

node:crypto path: good=ok expiredExp=expired stale=stale notValid=not-valid wrongProduct=wrong-product signedByOtherKey=bad-signature tampered=bad-signature garbage=malformed realDemoSignedByClavem=bad-signature
noble path:       good=ok expiredExp=expired stale=stale notValid=not-valid wrongProduct=wrong-product signedByOtherKey=bad-signature tampered=bad-signature garbage=malformed realDemoSignedByClavem=bad-signature

tampered is a good token whose payload was edited to extend exp, with the old signature. realDemoSignedByClavem is the live demo token. It decodes, but Clavem signed it with its own key, so a verifier holding any other public key has to refuse it.

Bind the token to this machine

When you activate with a fingerprint, Clavem puts it in the token as fp. The extension compares it with the same hash it computes locally, a salted SHA-256 of vscode.env.machineId. A token file copied to another computer verifies on the signature and fails here:

token fp matches this machine: true
token with another fp -> other-machine

This does not stop someone who copies the whole extension state to another machine and also fakes the machine id, and it is not meant to. It stops the casual copy. If you do not send a fingerprint at activation, fp is absent and the check is skipped.

The clock guard and storage

Keep the highest iat you have verified in context.globalState, which is plain data and fine for a number:

const highest = context.globalState.get('highestIat', 0);
const result = await check(saved.token, { publicKey: PUBLIC_KEY, productId: PRODUCT_ID, fingerprint: await fingerprint(), highestIat: highest });
if (result === 'ok') {
  const { iat } = await claims(saved.token, PUBLIC_KEY);
  if (iat > highest) await context.globalState.update('highestIat', iat);
}

A user can reset the extension’s state, and nothing offline can prevent that. The guard stops the casual date change. Store the token in context.secrets with the key, since it holds the buyer’s email in readable form.

Traps in VS Code

  • The check is client code. Anyone can edit an installed extension. The signature stops forged tokens, refresh_by stops old ones, and neither stops a patched extension.
  • import('node:crypto') throws in a web host. The isNode test keeps the call unreachable there.
  • Do not verify at module load. Run the check after activate returns, and publish the result with setContext, as on the validation page.
  • Pin @noble/ed25519. A major version can rename functions.

Doing this with Clavem

Each product has its own key pair. The public half is on the product page and in GET /v1/admin/products, and every activate and validate response carries a token signed with the private half. See the API reference for the endpoints.

Questions

Does a VS Code extension need a crypto library for Ed25519?

Not on desktop. The extension host is Node, and node:crypto verifies Ed25519 with createPublicKey and crypto.verify. A web extension host has no node:crypto, so bundle noble-ed25519 for that target.

What does the fp claim in the token do?

It carries the fingerprint sent at activation. If your extension compares it with the hash of vscode.env.machineId on this machine, a token copied from another computer fails the comparison, even though its signature is valid.

Where should the token be stored?

In context.secrets next to the key, for simplicity. A token is signed, not secret, so globalState also works, but the token holds the buyer's email in readable form, so SecretStorage is the better default.

Sources

  1. VS Code API reference, env.machineId and ExtensionContext (checked November 2026)