Pick the Ed25519 implementation
The token is the string sgt1.<payload>.<signature>. The offline verification reference defines the format, and the validation guide gets the token. Verifying it needs an Ed25519 implementation, and an Obsidian plugin has to run on desktop and mobile.
| Option | Where it works | Cost |
|---|---|---|
Web Crypto Ed25519 |
Chrome 137 and later, Safari and iOS 17 and later, Firefox 129 and later, and webviews that follow them | none |
@noble/curves |
everywhere JavaScript runs | bundled into main.js by esbuild |
Node’s crypto module |
desktop only | crashes on mobile, where the docs say Node APIs are not available |
Which row applies depends on the browser engine inside the user’s app, not on your plugin. So the code tries Web Crypto and falls back. It does not sniff the user agent. Do not use Node’s crypto: the mobile guide says Node APIs are not available there, so the import fails at run time on a phone.
The code
Run npm install @noble/curves. The import path ends in .js in the current release. Passing zip215: false makes the fallback as strict as RFC 8032 and as Web Crypto, rather than its more permissive default.
import { ed25519 } from '@noble/curves/ed25519.js';
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;
}
// atob and TextDecoder exist on desktop and mobile. Buffer does not exist on mobile.
function fromBase64Url(value: string): Uint8Array {
const b64 = value.replace(/-/g, '+').replace(/_/g, '/');
const bin = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
return Uint8Array.from(bin, (c) => c.charCodeAt(0));
}
async function signatureIsGood(key: Uint8Array, signature: Uint8Array, signed: Uint8Array): Promise<boolean> {
try {
const publicKey = await crypto.subtle.importKey('raw', key, { name: 'Ed25519' }, false, ['verify']);
return await crypto.subtle.verify({ name: 'Ed25519' }, publicKey, signature, signed);
} catch {
try {
return ed25519.verify(signature, signed, key, { zip215: false });
} catch {
return false;
}
}
}
/** Returns the claims when the signature is good, otherwise null. */
export async function verifyToken(token: string): Promise<Claims | null> {
const parts = token.split('.');
if (parts.length !== 3 || parts[0] !== 'sgt1') return null;
try {
const key = fromBase64Url(PUBLIC_KEY);
const signature = fromBase64Url(parts[2]);
if (key.length !== 32 || signature.length !== 64) return null;
// The signed text is the first two parts exactly as received.
const signed = new TextEncoder().encode(parts[0] + '.' + parts[1]);
if (!(await signatureIsGood(key, signature, signed))) return null;
return JSON.parse(new TextDecoder().decode(fromBase64Url(parts[1]))) as Claims;
} catch {
return null;
}
}
/** The checks your plugin 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
);
}
A Web Crypto failure is not always a missing feature: a malformed key also throws. That is fine here, because the fallback then rejects it too and the function returns false.
Results on test tokens
The real demo product’s public key is not published, so I signed eight tokens with a throwaway key pair in Clavem’s format and ran both paths under Node 26. Web Crypto and @noble/curves agreed on every row.
| Token | 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: connect once |
valid: false |
not licensed |
pid of another product |
not licensed |
v: 2 |
not licensed |
exp in the past |
not licensed |
This ran outside Obsidian, with a stub for its API.
Where the token and the clock live
Keep the token with the instance id in device-local storage, as in the validation guide, not in data.json. A token is not bound to a device, and data.json can travel with the vault.
To catch a clock set back, store the highest iat you have seen and compare:
import type { App } from 'obsidian';
export function clockWentBack(app: App, claims: Claims, now = Date.now() / 1000): boolean {
const seen = Number(app.loadLocalStorage('inkwell-highest-iat') ?? 0);
if (claims.iat > seen) app.saveLocalStorage('inkwell-highest-iat', claims.iat);
return now + 300 < Math.max(seen, claims.iat); // five minutes of slack for ordinary drift
}
Obsidian traps
- Bundlers add Node. A dependency that pulls in
Bufferorcryptoworks on desktop and breaks on mobile. Trythis.app.emulateMobile(true)in the developer console, which the mobile guide describes, but a real phone remains the test for the fallback. - The public key is readable. It is meant to be. Nothing in the plugin is secret, so no obfuscation helps, and the community directory does not allow it.
- 14 days is the window. A writer on a long flight keeps working until
refresh_by. After that the plugin should ask the user to connect once, not lock the vault.
Doing this with Clavem
Each product has its own Ed25519 key pair. Copy the public key from the product page. The token decoder shows the claims of a token you paste, which helps when a check fails and you want to see why.
Questions
Does Obsidian on a phone support Ed25519 in Web Crypto?
It depends on the engine under the app. Compatibility data lists Ed25519 in Safari and iOS from version 17 and in Chrome and Android WebView from 137. Older phones and older desktop builds need the fallback, which is why the code tries Web Crypto first and catches the failure.
Can a user remove the check from my plugin?
Yes. main.js is a plain file in their vault and they can edit it. The developer policies for the community directory forbid obfuscating code, so treat the check as a way to keep honest users honest.