cursedbelt 2.6.1 → 2.7.0

package/src/server/sync/status.spec.ts

@@ -0,0 +1,92 @@
+/**
+ * The status reporter's ONE durable field.
+ *
+ * These specs exist because of a live defect: prod's vault badge read "Awaiting
+ * first sync" over a vault the owner had used for weeks, because the peer-contact
+ * stamp lived in the server process and prod restarts on every deploy and sleeps
+ * nightly. The failure path — restart, and the fact is gone — is what is pinned.
+ */
+import { describe, expect, test } from "bun:test";
+import { PEER_CONTACT_WRITE_MS, createSyncStatusReporter, type SyncStatusStore } from "./status";
+
+function fakeStore(initial: number | null = null): SyncStatusStore & { saved: number[] } {
+	let value = initial;
+	const saved: number[] = [];
+	return {
+		saved,
+		loadPeerContactAt: () => value,
+		savePeerContactAt: (at) => {
+			value = at;
+			saved.push(at);
+		},
+	};
+}
+
+describe("createSyncStatusReporter", () => {
+	test("with no store it is exactly the in-memory reporter it always was", () => {
+		const s = createSyncStatusReporter();
+		expect(s.read().lastPeerContactAt).toBeNull();
+		s.update({ lastPeerContactAt: 1000 });
+		expect(s.read().lastPeerContactAt).toBe(1000);
+	});
+
+	test("🔴 a peer contact SURVIVES the restart that used to erase it", () => {
+		const store = fakeStore();
+		const before = createSyncStatusReporter({ role: "receiver" }, store);
+		before.update({ lastPeerContactAt: 1_700_000_000_000 });
+
+		// The deploy / the nightly sleep / a crash — a brand-new process, same database.
+		const after = createSyncStatusReporter({ role: "receiver" }, store);
+		expect(after.read().lastPeerContactAt).toBe(1_700_000_000_000);
+		expect(after.read().role).toBe("receiver");
+	});
+
+	test("only the contact stamp is restored — the rest describes THIS process", () => {
+		// A restored `consecutiveFailures: 3` would claim failures that never happened.
+		const store = fakeStore(1_700_000_000_000);
+		const s = createSyncStatusReporter(undefined, store);
+		const status = s.read();
+		expect(status.lastPeerContactAt).toBe(1_700_000_000_000);
+		expect(status.consecutiveFailures).toBe(0);
+		expect(status.lastAttemptAt).toBeNull();
+		expect(status.lastOutcome).toBeNull();
+	});
+
+	test("an explicit `initial` still wins over the stored value", () => {
+		const s = createSyncStatusReporter({ lastPeerContactAt: 5 }, fakeStore(9));
+		expect(s.read().lastPeerContactAt).toBe(5);
+	});
+
+	test("a sync run's several requests cost ONE durable write", () => {
+		const store = fakeStore();
+		const s = createSyncStatusReporter(undefined, store);
+		const t0 = 1_700_000_000_000;
+		for (const offset of [0, 100, 250, 900]) s.update({ lastPeerContactAt: t0 + offset });
+		expect(store.saved).toEqual([t0]);
+		// …and the next run, past the window, writes again.
+		s.update({ lastPeerContactAt: t0 + PEER_CONTACT_WRITE_MS });
+		expect(store.saved).toEqual([t0, t0 + PEER_CONTACT_WRITE_MS]);
+		// The in-memory value is always current regardless of what was written.
+		expect(s.read().lastPeerContactAt).toBe(t0 + PEER_CONTACT_WRITE_MS);
+	});
+
+	test("a failing store can never fail the sync request it rode in on", () => {
+		const store: SyncStatusStore = {
+			loadPeerContactAt: () => null,
+			savePeerContactAt: () => {
+				throw new Error("disk full");
+			},
+		};
+		const s = createSyncStatusReporter(undefined, store);
+		expect(() => s.update({ lastPeerContactAt: 42 })).not.toThrow();
+		expect(s.read().lastPeerContactAt).toBe(42);
+	});
+
+	test("a corrupt or absent stored value reads as 'never', not as NaN", () => {
+		const s = createSyncStatusReporter(undefined, {
+			loadPeerContactAt: () => null,
+			savePeerContactAt: () => {},
+		});
+		expect(s.read().lastPeerContactAt).toBeNull();
+	});
+});

package/src/server/sync/status.ts

@@ -0,0 +1,108 @@
+/**
+ * The status surface — vault's `SyncStatus` generalized verbatim, because its shape
+ * is the product of a real defect: `enabled: false` alone was read as "not syncing"
+ * on a receiving half that was in step the whole time. `role` is what tells the
+ * receiving half apart from a scratch instance, and anything reasoning about "is
+ * this instance syncing" must read `role`, not `enabled`.
+ */
+
+export interface SyncStatus {
+	/** Does THIS instance dial out at all? */
+	enabled: boolean;
+	/** dialer — runs the loop · receiver — answers the sync surface for a dialer ·
+	 *  none — neither (a dev shell on its own scratch database). */
+	role: "dialer" | "receiver" | "none";
+	/** The peer's ORIGIN — never the bearer token. Null when unlinked. */
+	peer: string | null;
+	lastAttemptAt: number | null;
+	lastSuccessAt: number | null;
+	lastOutcome: "ok" | "unreachable" | "paused" | "error" | null;
+	/** Set while the push is version-skew paused (`blockedBy`) — names the op kind the
+	 *  peer cannot take yet, i.e. "the peer needs deploying", the true statement. */
+	pausedOn: string | null;
+	consecutiveFailures: number;
+	/** Local writes the peer has not acknowledged yet — 0 means "fully in step". */
+	pending: number;
+	/** RECEIVER: when a dialing peer last authenticated against the sync surface. */
+	lastPeerContactAt: number | null;
+	/** RECEIVER: when someone last pressed "Sync now" here (the dialer polls it). */
+	syncRequestedAt: number | null;
+}
+
+export const OFFLINE_STATUS: SyncStatus = {
+	enabled: false,
+	role: "none",
+	peer: null,
+	lastAttemptAt: null,
+	lastSuccessAt: null,
+	lastOutcome: null,
+	pausedOn: null,
+	consecutiveFailures: 0,
+	pending: 0,
+	lastPeerContactAt: null,
+	syncRequestedAt: null,
+};
+
+export interface SyncStatusReporter {
+	read(): SyncStatus;
+	/** The timer's / receiver hooks' writer half — nothing else should call it. */
+	update(patch: Partial<SyncStatus>): void;
+}
+
+/**
+ * Somewhere to keep the ONE field that is a fact about the DATA rather than about
+ * this process.
+ *
+ * 🔴 Why only `lastPeerContactAt`. Every other field describes the live process and
+ * SHOULD reset with it: a dialer that has not attempted anything since boot has
+ * genuinely not attempted anything, and a restored `consecutiveFailures: 3` would be
+ * a claim about failures that did not happen. But "a peer authenticated here" is
+ * something that happened to the database, and forgetting it produced the owner's
+ * 2026-08-16 report — prod saying *"Awaiting first sync"* over a vault he had used
+ * for weeks. The badge's own words are "your Mac has not dialled since this server
+ * last restarted", which is true and which nobody reads as anything but "this has
+ * never synced". A receiver restarts on every deploy, and the dialer runs every 5
+ * minutes only while the Mac is awake — so the window in which a perfectly converged
+ * pair reads as never-synced is wide. It was wider still when the receiver was the
+ * `prod-ec2` box (decommissioned since), which also slept 12am–10am CT: most of a
+ * morning, every morning. In-memory was the wrong home for it.
+ */
+export interface SyncStatusStore {
+	/** The stored contact stamp, or null if a peer has genuinely never called. */
+	loadPeerContactAt(): number | null;
+	/** Persist a newer stamp. Called at most once per {@link PEER_CONTACT_WRITE_MS}. */
+	savePeerContactAt(at: number): void;
+}
+
+/** A dialer makes several requests per run; one durable write per this window is
+ *  enough to answer "when did a peer last call" to the nearest half-minute. */
+export const PEER_CONTACT_WRITE_MS = 30_000;
+
+export function createSyncStatusReporter(
+	initial?: Partial<SyncStatus>,
+	store?: SyncStatusStore,
+): SyncStatusReporter {
+	const restored = store?.loadPeerContactAt() ?? null;
+	let current: SyncStatus = {
+		...OFFLINE_STATUS,
+		...(restored === null ? {} : { lastPeerContactAt: restored }),
+		...initial,
+	};
+	let lastWrittenAt = restored ?? 0;
+	return {
+		read: () => ({ ...current }),
+		update: (patch) => {
+			current = { ...current, ...patch };
+			const at = patch.lastPeerContactAt;
+			if (store && typeof at === "number" && at - lastWrittenAt >= PEER_CONTACT_WRITE_MS) {
+				lastWrittenAt = at;
+				// A status write must never be able to fail the sync request it rode in on.
+				try {
+					store.savePeerContactAt(at);
+				} catch {
+					/* the in-memory value still answers; the next contact retries the write */
+				}
+			}
+		},
+	};
+}

package/src/server/sync/timer.spec.ts

@@ -0,0 +1,150 @@
+/**
+ * Fake-clock tests: capture scheduled callbacks, fire them by hand. The timer's
+ * contract is vault's — single-flight, unreachable-is-quiet, sync-now fast lane,
+ * peer re-resolved every tick.
+ */
+import { describe, expect, test } from "bun:test";
+import { createSyncStatusReporter } from "./status";
+import { startSyncTimer, type SyncTimerDeps } from "./timer";
+import type { SyncSummary } from "./types";
+
+interface Scheduled {
+	fn: () => void;
+	ms: number;
+}
+
+function harness(overrides: Partial<SyncTimerDeps> = {}) {
+	const scheduled: Scheduled[] = [];
+	// Start the clock at a realistic epoch: the timer's `lastAttempt: 0` initial state
+	// means "never ran" and must read as ancient, exactly as it does under Date.now().
+	let now = 1_000_000_000;
+	const runs: number[] = [];
+	let outcome: () => Promise<SyncSummary> = async () => ({
+		remoteId: "peer",
+		pushed: 1,
+		pulled: 0,
+		conflicts: 0,
+		held: 0,
+	});
+	const status = createSyncStatusReporter();
+	const deps: SyncTimerDeps = {
+		resolvePeer: () => ({ basePath: "http://peer/api/sync", token: "t" }),
+		sync: () => {
+			runs.push(now);
+			return outcome();
+		},
+		head: () => 0,
+		status,
+		requestPollMs: 0, // the fast lane has its own test
+		now: () => now,
+		setTimer: (fn, ms) => {
+			const entry = { fn: fn as () => void, ms };
+			scheduled.push(entry);
+			return entry;
+		},
+		clearTimer: (handle) => {
+			const i = scheduled.indexOf(handle as Scheduled);
+			if (i >= 0) scheduled.splice(i, 1);
+		},
+		log: () => {},
+		warn: () => {},
+		...overrides,
+	};
+	const handle = startSyncTimer(deps);
+	/** Fire the most recently scheduled callback, advancing the clock by its delay. */
+	const fire = async () => {
+		const entry = scheduled.pop();
+		if (!entry) throw new Error("nothing scheduled");
+		now += entry.ms;
+		entry.fn();
+		// Let the sync promise chain settle.
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+	};
+	return {
+		scheduled,
+		runs,
+		status,
+		handle,
+		fire,
+		setOutcome: (fn: typeof outcome) => {
+			outcome = fn;
+		},
+		clock: () => now,
+	};
+}
+
+describe("sync timer", () => {
+	test("kickoff runs shortly after start and reports ok", async () => {
+		const h = harness();
+		expect(h.scheduled).toHaveLength(1);
+		await h.fire();
+		expect(h.runs).toHaveLength(1);
+		expect(h.status.read().lastOutcome).toBe("ok");
+		expect(h.status.read().role).toBe("dialer");
+		// The next steady tick is booked.
+		expect(h.scheduled).toHaveLength(1);
+	});
+
+	test("a failure backs off and reports unreachable quietly", async () => {
+		const h = harness();
+		h.setOutcome(async () => {
+			throw new Error("fetch failed");
+		});
+		await h.fire(); // kickoff → fails
+		expect(h.status.read().lastOutcome).toBe("unreachable");
+		expect(h.status.read().consecutiveFailures).toBe(1);
+		await h.fire(); // backoff wait tick → plan says run (clock advanced past step)
+		expect(h.status.read().consecutiveFailures).toBe(2);
+	});
+
+	test("a version-skew pause reports pausedOn without counting as a failure", async () => {
+		const h = harness();
+		h.setOutcome(async () => ({
+			remoteId: "peer",
+			pushed: 0,
+			pulled: 0,
+			conflicts: 0,
+			held: 0,
+			blockedBy: "doc.set",
+		}));
+		await h.fire();
+		const s = h.status.read();
+		expect(s.lastOutcome).toBe("paused");
+		expect(s.pausedOn).toBe("doc.set");
+		expect(s.consecutiveFailures).toBe(0);
+	});
+
+	test("syncNow forces an immediate run", async () => {
+		const h = harness();
+		await h.fire(); // kickoff
+		expect(h.runs).toHaveLength(1);
+		h.handle.syncNow();
+		await h.fire();
+		expect(h.runs).toHaveLength(2);
+	});
+
+	test("an unlinked peer is a quiet no-op re-checked next tick", async () => {
+		const h = harness({ resolvePeer: () => null });
+		await h.fire();
+		expect(h.runs).toHaveLength(0);
+		expect(h.scheduled).toHaveLength(1); // re-check booked
+	});
+
+	test("markDirty schedules a prompt run (debounced by the planner)", async () => {
+		let head = 0;
+		const h = harness({ head: () => head });
+		await h.fire(); // kickoff
+		head = 3;
+		h.handle.markDirty();
+		await h.fire(); // the dirty tick — planner may debounce once
+		if (h.runs.length === 1) await h.fire();
+		expect(h.runs.length).toBeGreaterThanOrEqual(2);
+	});
+
+	test("stop() cancels everything", async () => {
+		const h = harness();
+		h.handle.stop();
+		expect(h.scheduled).toHaveLength(0);
+	});
+});

package/src/server/sync/timer.ts

@@ -0,0 +1,207 @@
+/**
+ * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
+ * half only; a failure NEVER takes the host daemon down (an unsynced instance still
+ * serves and still accepts writes — that is the point of two independently-writable
+ * instances). The timer is `unref`'d so it never holds the process open.
+ *
+ * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
+ * effect without a restart. The "Sync now" fast lane polls the receiver's request
+ * stamp every ~20s while healthy, so a button press on the far side means seconds,
+ * not "sometime in the next interval".
+ */
+import {
+	isUnreachable,
+	DEFAULT_LOOP,
+	planNextSync,
+	type SyncLoopConfig,
+	type SyncLoopState,
+} from "./planner";
+import type { SyncStatusReporter } from "./status";
+import type { SyncSummary } from "./types";
+
+export const REQUEST_POLL_MS = 20_000;
+const KICKOFF_MS = 5_000;
+
+export interface SyncTimerDeps {
+	/** Re-read every tick: null = not linked (quiet no-op, re-checked next tick). */
+	resolvePeer: () => { basePath: string; token: string } | null;
+	/** Run one full reconciliation against the resolved peer. */
+	sync: (peer: { basePath: string; token: string }) => Promise<SyncSummary>;
+	/** The local op-log head — a head beyond the last synced one marks dirty. */
+	head: () => number;
+	/** Ask the peer whether its "Sync now" was pressed; null on any failure. */
+	checkRequest?: (peer: { basePath: string; token: string }) => Promise<number | null>;
+	status?: SyncStatusReporter;
+	loop?: SyncLoopConfig;
+	requestPollMs?: number;
+	now?: () => number;
+	setTimer?: (fn: () => void, ms: number) => unknown;
+	clearTimer?: (handle: unknown) => void;
+	log?: (msg: string) => void;
+	warn?: (msg: string) => void;
+	/** Display origin for the status line; defaults to URL origin parsing. */
+	peerLabel?: (basePath: string) => string | null;
+}
+
+export interface SyncTimerHandle {
+	stop(): void;
+	/** Run the next tick immediately (the "Sync now" button on the dialing half). */
+	syncNow(): void;
+	/** Mark local writes pending (call after any local op) — debounces a burst. */
+	markDirty(): void;
+}
+
+function defaultPeerLabel(basePath: string): string | null {
+	try {
+		return new URL(basePath).origin;
+	} catch {
+		return null;
+	}
+}
+
+export function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle {
+	const now = deps.now ?? Date.now;
+	const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+	const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+	const loop = deps.loop ?? DEFAULT_LOOP;
+	const log = deps.log ?? ((m: string) => console.log(m));
+	const warn = deps.warn ?? ((m: string) => console.error(m));
+	const status = deps.status;
+	const peerLabel = deps.peerLabel ?? defaultPeerLabel;
+	const requestPollMs = deps.requestPollMs ?? REQUEST_POLL_MS;
+	status?.update({ enabled: true, role: "dialer" });
+
+	const state: SyncLoopState = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: null };
+	let syncedHead = deps.head();
+	let stopped = false;
+	let handle: unknown = null;
+	let reportedUnreachable = false;
+	let forceRun = false;
+	let handledRequestAt = 0;
+	let probing = false;
+	let inFlight = false;
+
+	const schedule = (ms: number): void => {
+		if (stopped) return;
+		if (handle !== null) clearTimer(handle);
+		handle = setTimer(tick, ms);
+		(handle as { unref?: () => void })?.unref?.();
+	};
+
+	const sleepFor = (waitMs: number): number => {
+		const healthy = state.consecutiveFailures === 0 && requestPollMs > 0;
+		return Math.max(1, healthy ? Math.min(waitMs, requestPollMs) : waitMs);
+	};
+
+	const probeRequest = (peer: { basePath: string; token: string }): void => {
+		if (probing || requestPollMs === 0 || !deps.checkRequest) return;
+		probing = true;
+		void deps
+			.checkRequest(peer)
+			.then((requestedAt) => {
+				if (stopped || requestedAt === null || requestedAt <= handledRequestAt) return;
+				handledRequestAt = requestedAt;
+				log("[sync] sync requested from the peer — running now.");
+				forceRun = true;
+				schedule(1);
+			})
+			.finally(() => {
+				probing = false;
+			});
+	};
+
+	const tick = (): void => {
+		if (stopped) return;
+		if (inFlight) return; // two concurrent runs share cursors and would double-push
+		const head = deps.head();
+		if (head > syncedHead && state.dirtySince === null) state.dirtySince = now();
+
+		const peer = deps.resolvePeer();
+		status?.update({
+			peer: peer === null ? null : peerLabel(peer.basePath),
+			pending: Math.max(0, head - syncedHead),
+		});
+		if (peer === null) {
+			schedule(loop.intervalMs);
+			return;
+		}
+
+		const plan = planNextSync(state, now(), loop);
+		if (!plan.runNow && !forceRun) {
+			const linkedAndHealthy = state.consecutiveFailures === 0 && requestPollMs > 0;
+			schedule(sleepFor(plan.waitMs));
+			if (linkedAndHealthy) probeRequest(peer);
+			return;
+		}
+
+		forceRun = false;
+		state.lastAttempt = now();
+		status?.update({ lastAttemptAt: state.lastAttempt });
+		const headAtAttempt = head;
+		inFlight = true;
+		deps
+			.sync(peer)
+			.then((s) => {
+				state.consecutiveFailures = 0;
+				state.dirtySince = null;
+				syncedHead = headAtAttempt;
+				reportedUnreachable = false;
+				status?.update({
+					lastSuccessAt: now(),
+					lastOutcome: s.blockedBy ? "paused" : "ok",
+					pausedOn: s.blockedBy ?? null,
+					consecutiveFailures: 0,
+					pending: Math.max(0, deps.head() - syncedHead),
+				});
+				if (s.pushed > 0 || s.pulled > 0 || s.conflicts > 0) {
+					log(
+						`[sync] ↑${s.pushed} ↓${s.pulled}` +
+							(s.conflicts > 0 ? ` (${s.conflicts} conflicts)` : ""),
+					);
+				}
+				if (s.blockedBy) {
+					log(
+						`[sync] push paused before "${s.blockedBy}" — the peer cannot take it yet (deploy pending?).`,
+					);
+				}
+			})
+			.catch((err) => {
+				state.consecutiveFailures += 1;
+				status?.update({
+					lastOutcome: isUnreachable(err) ? "unreachable" : "error",
+					consecutiveFailures: state.consecutiveFailures,
+				});
+				if (isUnreachable(err)) {
+					if (!reportedUnreachable) {
+						log(`[sync] peer unreachable — will retry. This is normal (nightly window / offline).`);
+						reportedUnreachable = true;
+					}
+				} else {
+					warn(`[sync] failed (ignored): ${err instanceof Error ? err.message : err}`);
+				}
+			})
+			.finally(() => {
+				inFlight = false;
+				if (forceRun) schedule(1);
+				else schedule(sleepFor(Math.max(1_000, planNextSync(state, now(), loop).waitMs)));
+			});
+	};
+
+	schedule(KICKOFF_MS);
+	return {
+		stop: () => {
+			stopped = true;
+			if (handle !== null) clearTimer(handle);
+		},
+		syncNow: () => {
+			if (stopped) return;
+			forceRun = true;
+			schedule(1);
+		},
+		markDirty: () => {
+			if (stopped) return;
+			if (state.dirtySince === null) state.dirtySince = now();
+			schedule(1);
+		},
+	};
+}

package/src/server/sync/tokens.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { createTokenStore } from "./tokens";
+
+describe("device tokens", () => {
+	test("mint → verify (scope-checked) → revoke", () => {
+		const tokens = createTokenStore(new Database(":memory:"));
+		const plaintext = tokens.mint("mac", "sync");
+		expect(plaintext.length).toBeGreaterThan(30);
+		expect(tokens.verify(plaintext, "sync")?.name).toBe("mac");
+		expect(tokens.verify(plaintext, "other-scope")).toBeNull();
+		expect(tokens.verify("nonsense", "sync")).toBeNull();
+		expect(tokens.verify("", "sync")).toBeNull();
+		expect(tokens.revoke("mac")).toBe(true);
+		expect(tokens.verify(plaintext, "sync")).toBeNull();
+		expect(tokens.revoke("mac")).toBe(false); // already revoked
+	});
+
+	test("re-minting a name rotates: the old plaintext dies with the new mint", () => {
+		const tokens = createTokenStore(new Database(":memory:"));
+		const first = tokens.mint("mac", "sync");
+		const second = tokens.mint("mac", "sync");
+		expect(tokens.verify(first, "sync")).toBeNull();
+		expect(tokens.verify(second, "sync")?.name).toBe("mac");
+		expect(tokens.list().filter((t) => t.name === "mac")).toHaveLength(1);
+	});
+
+	test("only sha256 digests are at rest — the table never holds the plaintext", () => {
+		const db = new Database(":memory:");
+		const tokens = createTokenStore(db);
+		const plaintext = tokens.mint("mac", "sync");
+		const rows = db.prepare("SELECT token_sha256 FROM sync_tokens").all() as {
+			token_sha256: Uint8Array;
+		}[];
+		const stored = Buffer.from(rows[0]?.token_sha256 ?? new Uint8Array()).toString("utf8");
+		expect(stored).not.toContain(plaintext);
+	});
+});

package/src/server/sync/tokens.ts

@@ -0,0 +1,94 @@
+/**
+ * Scoped device tokens — notes' mint/verify/revoke generalized (vault runs a single
+ * static env secret; the token TABLE is the better half: revocable per device, scoped
+ * per capability, sha256 at rest so a database read never yields a usable credential).
+ *
+ * The plaintext token is returned exactly once, at mint. Verification compares sha256
+ * digests via `timingSafeEqual` — length-independent, no oracle.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+export interface DeviceToken {
+	name: string;
+	scope: string;
+	createdAt: number;
+	revokedAt: number | null;
+}
+
+export interface TokenStore {
+	/** Mint a token for `name`+`scope`; returns the plaintext ONCE. Re-minting a name
+	 *  revokes the previous token of that name (one live credential per device name). */
+	mint(name: string, scope: string): string;
+	/** Null when unknown, revoked, or out of scope. */
+	verify(presented: string, scope: string): DeviceToken | null;
+	revoke(name: string): boolean;
+	list(): DeviceToken[];
+}
+
+const sha256 = (value: string): Buffer => createHash("sha256").update(value).digest();
+
+export function createTokenStore(db: Database): TokenStore {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS sync_tokens (
+			name TEXT PRIMARY KEY,
+			scope TEXT NOT NULL,
+			token_sha256 BLOB NOT NULL,
+			created_at INTEGER NOT NULL,
+			revoked_at INTEGER
+		);
+	`);
+	const upsert = db.prepare(
+		"INSERT INTO sync_tokens (name, scope, token_sha256, created_at, revoked_at) VALUES (?, ?, ?, ?, NULL) ON CONFLICT(name) DO UPDATE SET scope = excluded.scope, token_sha256 = excluded.token_sha256, created_at = excluded.created_at, revoked_at = NULL",
+	);
+	const allLive = db.prepare(
+		"SELECT name, scope, token_sha256, created_at, revoked_at FROM sync_tokens WHERE revoked_at IS NULL",
+	);
+	const all = db.prepare(
+		"SELECT name, scope, token_sha256, created_at, revoked_at FROM sync_tokens ORDER BY created_at DESC",
+	);
+	const revokeStmt = db.prepare(
+		"UPDATE sync_tokens SET revoked_at = ? WHERE name = ? AND revoked_at IS NULL",
+	);
+
+	interface Row {
+		name: string;
+		scope: string;
+		token_sha256: Uint8Array;
+		created_at: number;
+		revoked_at: number | null;
+	}
+	const toToken = (r: Row): DeviceToken => ({
+		name: r.name,
+		scope: r.scope,
+		createdAt: r.created_at,
+		revokedAt: r.revoked_at,
+	});
+
+	return {
+		mint(name, scope) {
+			const token = randomBytes(32).toString("base64url");
+			upsert.run(name, scope, sha256(token), Date.now());
+			return token;
+		},
+		verify(presented, scope) {
+			if (!presented) return null;
+			const got = sha256(presented);
+			// Scan live rows and compare digests constant-time each. The fleet holds a
+			// handful of devices; a table scan is simpler than an index that would make
+			// the lookup timing depend on the presented value.
+			for (const raw of allLive.all() as Row[]) {
+				const want = Buffer.from(raw.token_sha256);
+				if (want.length === got.length && timingSafeEqual(want, got)) {
+					if (raw.scope !== scope) return null;
+					return toToken(raw);
+				}
+			}
+			return null;
+		},
+		revoke(name) {
+			return revokeStmt.run(Date.now(), name).changes > 0;
+		},
+		list: () => (all.all() as Row[]).map(toToken),
+	};
+}