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.
createPublicKeythrowsERR_CRYPTO_INVALID_JWKwhenxis not 32 bytes of base64url, and the placeholderYOUR_PUBLIC_KEYtriggers it. Thetryturns that intonull, so a forgotten placeholder makes every customer look unlicensed. Test with a real key before you submit. - Short signatures return false.
verifywith a signature of the wrong length returnsfalse, 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.logof 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.