Clavem

Verify an Ed25519 license token offline in a Raycast extension

Raycast runs extensions in Node, so node:crypto can import the Ed25519 public key as a JWK and verify the signature with no dependency. Check v, pid, valid, exp and refresh_by, tie the token to the key in preferences, and keep it in LocalStorage.

Why node:crypto

Raycast’s security page says it starts one child Node.js process and runs each extension in its own V8 isolate on a worker thread, with a Node runtime that Raycast manages. node:crypto is part of that runtime. Using it means the extension adds no package for Ed25519, which also means one fewer dependency for a reviewer to read.

The token format is sgt1.<payload>.<signature>, described in the offline verification reference. The product’s public key is 32 raw bytes in base64url. A JWK for an Ed25519 key stores the same bytes in its x field, so the key from your product page goes into the JWK as it is.

The code

import { createHash, createPublicKey, verify } from 'node:crypto';
import { LocalStorage } from '@raycast/api';

const PUBLIC_KEY = 'YOUR_PUBLIC_KEY'; // from your product page: 32 raw bytes, base64url
const PRODUCT_ID = 75; // from your product page

export interface Claims {
  v: number; lid: number; pid: number; kh: string; status: string; valid: boolean;
  iid?: string; fp?: string; email?: string; iat: number; exp?: number; refresh_by: number;
}

/** Returns the claims when the signature is good, otherwise null. */
export function verifyToken(token: string): Claims | null {
  const [prefix, body, signature, extra] = token.split('.');
  if (prefix !== 'sgt1' || !body || !signature || extra !== undefined) return null;
  try {
    const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: PUBLIC_KEY }, format: 'jwk' });
    // The signed text is the first two parts exactly as received. The algorithm argument is null for Ed25519.
    if (!verify(null, Buffer.from(`${prefix}.${body}`), key, Buffer.from(signature, 'base64url'))) return null;
    return JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Claims;
  } catch {
    return null; // malformed token or key
  }
}

/** The checks your extension should make on a verified token. */
export function isLicensed(claims: Claims | null, now = Date.now() / 1000): boolean {
  return (
    claims !== null && claims.v === 1 && claims.pid === PRODUCT_ID && claims.valid === true &&
    (claims.exp === undefined || claims.exp > now) && claims.refresh_by > now
  );
}

/** Was this token issued for the key in the preferences? */
export function matchesKey(claims: Claims, licenseKey: string): boolean {
  const key = licenseKey.trim();
  const native = /^[0-9A-Za-z]{5}(?:-[0-9A-Za-z]{5}){4}$/.test(key);
  const normalized = native ? key.toUpperCase().replace(/[IL]/g, '1').replace(/O/g, '0').replace(/U/g, 'V') : key.toLowerCase();
  return createHash('sha256').update(normalized).digest('hex').slice(0, 16) === claims.kh;
}

/** A clock set back to keep a token fresh shows up as "now" earlier than an iat we have already seen. */
export async function clockWentBack(claims: Claims, now = Date.now() / 1000): Promise<boolean> {
  const seen = Number((await LocalStorage.getItem<string>('highest-iat')) ?? 0);
  if (claims.iat > seen) await LocalStorage.setItem('highest-iat', String(claims.iat));
  return now + 300 < Math.max(seen, claims.iat); // five minutes of slack for ordinary drift
}

In the command, combine the checks: isLicensed(claims) && matchesKey(claims, key) && !(await clockWentBack(claims)).

What I ran

The real demo product’s public key is not published, so the tokens were signed with a throwaway key pair in Clavem’s format.

Token or input Result
Fresh, valid, product 75 licensed
Payload edited after signing signature fails
Signed by another key signature fails
refresh_by in the past not licensed
valid: false not licensed
pid of another product not licensed
v: 2 not licensed
exp in the past not licensed
sgt1.a.b, or a public key of the wrong length null
demo key against the token’s kh matchesKey true; a different key false
clock two days behind the highest iat clockWentBack true; ordinary drift false

Raycast traps

  • Wrong key size throws. createPublicKey throws ERR_CRYPTO_INVALID_JWK when x is not 32 bytes of base64url, and the placeholder YOUR_PUBLIC_KEY triggers it. The try turns that into null, so a forgotten placeholder makes every customer look unlicensed. Test with a real key before you submit.
  • Short signatures return false. verify with a signature of the wrong length returns false, it does not throw, so the length check from other languages is not needed here.
  • Lenient decoding. Buffer.from(x, 'base64url') ignores characters that are not base64url. That is safe here, because the signature must still verify over the exact text, but it means the decode step is not a validity check.
  • Token in LocalStorage. Raycast’s security page says LocalStorage lives in its local encrypted database, readable only by the extension. The Cache docs describe least-recently-used eviction, so keep tokens out of it.
  • Do not log it. The payload is signed, not encrypted, and holds the buyer’s email address. A console.log of the token ends up in your developer console and in bug reports.
  • The source is public. Store extensions are open source, so the public key and the checks are visible. That is fine for the key. It means the checks can be edited out.
  • 14 days. After refresh_by, the extension should say it needs to connect once rather than fail silently. Raycast users on a laptop in a tunnel are who this window is for.

Doing this with Clavem

Each product has its own key pair, shown on the product page. The token decoder prints the claims of a token you paste, and the validation guide is where the token comes from.

Questions

Do I need a crypto package for Ed25519 in a Raycast extension?

No. node:crypto imports an Ed25519 public key from a JWK and verifies the signature. Clavem's public key is already the base64url of the 32 raw bytes, which is what the JWK x field holds, so there is no DER or PEM step.

Why compare the token to the key in preferences?

Preferences are editable. If the user pastes a different key, the stored token still verifies, but it belongs to the old key. The kh claim lets the extension notice.

Sources

  1. Raycast developer docs, security (runtime model and data storage; checked November 2026)
  2. Raycast developer docs, storage (LocalStorage; checked November 2026)
  3. Raycast developer docs, cache (checked November 2026)