cursedbelt-server 1.0.0

package/dist/server/guard/revocationStore.js

@@ -0,0 +1,211 @@
+/**
+ * The one revocation store, in two shapes for two hot paths (DEDUP-7).
+ *
+ * "Was this session/token withdrawn early?" is a single concern, but it is
+ * consulted from two verify paths whose constraints do not meet in the middle,
+ * so this file settles ONE contract per constraint and gives the async one a
+ * bridge back to the sync one:
+ *
+ *   • {@link RevocationStore} — SYNCHRONOUS (`isRevoked`/`revoke`/`sweep`, epoch
+ *     **milliseconds**). The single-owner satellites' `createOwnerAuth` consults
+ *     it inside `isAuthenticated`, which is called on every request and cannot
+ *     become a promise without turning every route async. Its durable
+ *     implementation is a local sqlite file — the denylist a redeploy must not
+ *     forget (`apps/roms`'s deploy smoke caught a logout that did not log out).
+ *
+ *   • {@link AsyncRevocationStore} — ASYNCHRONOUS (`set`/`get`/`prune`, epoch
+ *     **seconds**). The cross-node seam (03 §4a, audit G6): a Redis hash or a
+ *     Postgres row that every node in a saas deployment reads, so a `lock()` on
+ *     node A closes the token on node B too. `createSessionSigner` consumes THIS
+ *     one and keeps its own read-through cache so its `verify` stays sync.
+ *
+ * Before DEDUP-7 these lived in two packages, BOTH exporting a
+ * `createMemoryRevocationStore` of a different shape — a live footgun the moment
+ * a file imported from the wrong one. They are one file now; `satellite-kit`
+ * re-exports the sync half so its callers are unchanged.
+ *
+ * The bridge between them is {@link createAsyncBackedRevocationStore}: a SYNC
+ * store whose durable backing is an async cross-node store, using the same
+ * read-through-cache trick the signer does. It is what lets a satellite opt into
+ * the cross-node seam without its `isAuthenticated` becoming a promise.
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { assertCcPragmas } from 'cwip/sqlite';
+/**
+ * An in-memory sync {@link RevocationStore}.
+ *
+ * For tests, and for a single-process caller that does not need durability.
+ * NOT for a deployed satellite: an in-memory table would be worse than none —
+ * sign out, redeploy, and the session works again, which reads as the feature
+ * being broken rather than absent. Give a deployed door
+ * {@link createSqliteRevocationStore} (durable) or nothing.
+ */
+export function createMemoryRevocationStore() {
+    const entries = new Map();
+    return {
+        isRevoked: (id) => entries.has(id),
+        revoke: (id, expiresAtMs) => void entries.set(id, expiresAtMs),
+        sweep: (nowMs) => {
+            for (const [id, expiresAt] of entries)
+                if (expiresAt <= nowMs)
+                    entries.delete(id);
+        },
+        size: () => entries.size,
+    };
+}
+/**
+ * A durable sync {@link RevocationStore} backed by a sqlite file.
+ *
+ * Because an in-memory table would be worse than none (see above), and the
+ * deploy engine persists each release's data directory, so durability costs one
+ * file. The table is self-limiting: an entry is meaningless once the session it
+ * names would have expired anyway, and `sweep` drops those on logout — rare,
+ * cheap, and exactly when the table has just grown, so there is no background
+ * timer to own.
+ *
+ * Its OWN file, not a table in an app's database: keeping a credential surface
+ * out of an app's data file bounds the blast radius of a corrupt or deleted
+ * file to "everyone signs in again".
+ */
+export function createSqliteRevocationStore(dbPath) {
+    if (dbPath !== ':memory:' && !dbPath.startsWith('file:')) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    const db = new Database(dbPath, { create: true });
+    // Route pragmas through cwip's one controller (applies WAL + busy_timeout +
+    // foreign_keys + wal_autocheckpoint and re-reads to prove each took), rather
+    // than hand-rolling a lone `journal_mode = WAL` the pragma sweep rejects.
+    assertCcPragmas(db);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS revoked_sessions (
+      id         TEXT PRIMARY KEY,
+      expires_at INTEGER NOT NULL
+    )
+  `);
+    const has = db.query('SELECT id FROM revoked_sessions WHERE id = ?');
+    const insert = db.query('INSERT OR REPLACE INTO revoked_sessions (id, expires_at) VALUES (?, ?)');
+    const prune = db.query('DELETE FROM revoked_sessions WHERE expires_at <= ?');
+    return {
+        isRevoked: (id) => has.get(id) !== null,
+        revoke: (id, expiresAtMs) => void insert.run(id, expiresAtMs),
+        sweep: (nowMs) => void prune.run(nowMs),
+        close: () => db.close(),
+    };
+}
+/**
+ * An in-memory {@link AsyncRevocationStore}.
+ *
+ * Two uses: a single-process saas test that wants the seam exercised without a
+ * real Redis, and — crucially — the **two-signer replay probe**, where one
+ * shared instance is handed to signer A and signer B so "revoke on A, verify on
+ * B" becomes provable in one process (V7.3). It is NOT a cross-process store:
+ * two OS processes do not share this Map, which is the whole reason a real
+ * deployment injects Redis/Postgres instead.
+ *
+ * (Named `…Async…` to stand apart from the sync {@link createMemoryRevocationStore};
+ * before DEDUP-7 both shapes shared the bare name across two packages and that
+ * collision was the footgun this file exists to remove.)
+ */
+export function createMemoryAsyncRevocationStore() {
+    const revoked = new Map();
+    return {
+        async set(jti, expEpochSeconds) {
+            const existing = revoked.get(jti);
+            // Keep the later exp: two nodes revoking the same jti with slightly
+            // different clocks must not shorten the window.
+            if (existing === undefined || expEpochSeconds > existing)
+                revoked.set(jti, expEpochSeconds);
+        },
+        async get(jti) {
+            return revoked.get(jti) ?? null;
+        },
+        async prune(nowEpochSeconds) {
+            let removed = 0;
+            for (const [jti, exp] of revoked) {
+                if (exp <= nowEpochSeconds) {
+                    revoked.delete(jti);
+                    removed += 1;
+                }
+            }
+            return removed;
+        },
+        size() {
+            return revoked.size;
+        },
+    };
+}
+/**
+ * A SYNC {@link RevocationStore} whose durable backing is an async cross-node
+ * {@link AsyncRevocationStore} — the bridge that gives a satellite the cross-node
+ * seam without its `isAuthenticated` becoming a promise.
+ *
+ * It is the same read-through-cache trick {@link createSessionSigner} keeps
+ * internally, packaged so a plain sync consumer can use it: `revoke` writes
+ * through fire-and-forget and caches locally so the id is refused HERE the
+ * instant it returns; `isRevoked` answers from the cache and schedules a refresh
+ * when the entry is missing or older than `cacheTtlMs`, never blocking. Ids and
+ * expiries cross the ms↔seconds boundary here (the sync contract is ms, the
+ * async one seconds).
+ *
+ * {@link flush} settles the fire-and-forget work — for shutdown/handover (a node
+ * draining must not lose an unwritten revocation) and for tests that need the
+ * cross-node state to have settled.
+ */
+export function createAsyncBackedRevocationStore(backing, options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const cacheTtlMs = options.cacheTtlMs ?? 5000;
+    const onError = options.onError ?? (() => undefined);
+    /** id → the last backing verdict (exp in ms, or null) and when it was read. */
+    const cache = new Map();
+    const pending = new Set();
+    /** Reads in flight per id, so a burst of `isRevoked` coalesces into one read. */
+    const inflightReads = new Map();
+    const track = (work) => {
+        pending.add(work);
+        void work.finally(() => pending.delete(work));
+    };
+    const refresh = (id) => {
+        if (inflightReads.has(id))
+            return;
+        const read = backing
+            .get(id)
+            .then((expSec) => {
+            cache.set(id, { expMs: expSec === null ? null : expSec * 1000, readAtMs: now() });
+        })
+            .catch((error) => onError('get', error))
+            .finally(() => inflightReads.delete(id));
+        inflightReads.set(id, read);
+        track(read);
+    };
+    return {
+        isRevoked(id) {
+            const cached = cache.get(id);
+            if (cached === undefined || now() - cached.readAtMs >= cacheTtlMs)
+                refresh(id);
+            // A fresh cached exp still in the future ⇒ revoked. An expired cached exp
+            // is treated as not-revoked: the token's own expiry already refuses it, so
+            // the denylist has nothing left to add.
+            return cached?.expMs != null && cached.expMs > now();
+        },
+        revoke(id, expiresAtMs) {
+            // Cache locally FIRST so this node refuses the id the instant this returns,
+            // regardless of whether the write-through has propagated yet.
+            cache.set(id, { expMs: expiresAtMs, readAtMs: now() });
+            track(backing.set(id, Math.ceil(expiresAtMs / 1000)).catch((error) => onError('set', error)));
+        },
+        sweep(nowMs) {
+            for (const [id, cached] of cache)
+                if (cached.expMs !== null && cached.expMs <= nowMs)
+                    cache.delete(id);
+            track(backing.prune(Math.floor(nowMs / 1000)).catch((error) => onError('prune', error)));
+        },
+        async flush() {
+            // Settle in-flight work, then whatever it scheduled (a read can resolve
+            // after we snapshot), so the caller sees a fully-quiesced state.
+            while (pending.size > 0)
+                await Promise.allSettled([...pending]);
+        },
+    };
+}

package/dist/server/guard/sessionSigner.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The production session signer (02 §4.2) — Ed25519-signed `CCUserClaims` plus
+ * the jti denylist that makes `lock()` mean something.
+ *
+ * The verify harness ships an HMAC stand-in because a probe suite tests the
+ * DECISION table (signature validity, expiry, revocation), not the algorithm.
+ * This is the real one, and the differences are the parts a stand-in cannot
+ * model:
+ *
+ *   * **Asymmetric.** Only the server that holds the private key can mint a
+ *     session. A verifier can be handed the public key alone, so a read-only
+ *     replica or an edge worker can verify without being able to forge.
+ *   * **Revocation is bounded, not unbounded.** A denylist that only ever grows
+ *     is a memory leak wearing a security hat. An entry is dropped once its
+ *     token would have expired anyway, because after `exp` the signature check
+ *     already refuses it.
+ *   * **Expiry before revocation.** An expired token is expired whether or not
+ *     anyone bothered to revoke it — checking in the other order makes the
+ *     denylist load-bearing for a case it does not need to cover.
+ */
+import { type KeyObject } from 'node:crypto';
+import { type CCUserClaims } from 'cursedbelt-core/session/claims';
+import type { GuardVerifier } from './verifier';
+import type { AsyncRevocationStore } from './revocationStore';
+export interface SessionSignerOptions {
+    /**
+     * Ed25519 private key (PEM/DER/`KeyObject`). Omitted ⇒ an ephemeral pair is
+     * generated, which is correct ONLY for a single-process dev server: every
+     * restart invalidates every session, and a second process cannot verify.
+     */
+    privateKey?: KeyObject | string | Buffer;
+    /** Public half, when the verifier is separate from the minter. */
+    publicKey?: KeyObject | string | Buffer;
+    /** Default session lifetime. `guard.features.sessionTtlMinutes` feeds this. */
+    ttlSeconds?: number;
+    /** Clock injection for deterministic tests. */
+    now?: () => number;
+    /** Id generator for `jti`. */
+    mintJti?: () => string;
+    /**
+     * The cross-node denylist (03 §4a). Absent ⇒ the in-process `Map` is the whole
+     * story, which is correct for the local profile. Present (saas) ⇒ a `revoke`
+     * ALSO writes through to the shared store, and `verify` consults it for jtis
+     * revoked on OTHER nodes — so `lock()` on node A closes the token everywhere,
+     * not just where the request landed.
+     */
+    revocationStore?: AsyncRevocationStore;
+    /**
+     * How long a store verdict is trusted before `verify` re-reads it (ms). This is
+     * the cross-node revocation LATENCY BOUND: a jti revoked on another node is
+     * seen here within this window (plus the store's own read latency), because
+     * `verify` stays synchronous — it answers from the cache and refreshes it off
+     * the hot path rather than awaiting a network round trip on every route.
+     * Default 5000 (03 §4a's ≤5s). Ignored when no `revocationStore` is set.
+     */
+    revocationCacheTtlMs?: number;
+    /**
+     * Reports a store read/write that failed. A failed write-through means a
+     * revocation did not reach other nodes — the local Map still refuses the token
+     * HERE, but the host needs to know propagation failed (and may retry). Default:
+     * swallow, because a signer must never throw out of `verify`/`revoke` on the
+     * request path.
+     */
+    onRevocationStoreError?: (op: 'get' | 'set' | 'prune', error: unknown) => void;
+}
+/**
+ * One live session this signer minted (02 §4) — the `(userId, tenantId,
+ * deviceLabel)` association the spec asks for, keyed by `jti`.
+ *
+ * The device label is deliberately NOT a claim: `CCUserClaimsSchema` is
+ * `.strict()`, and widening the SIGNED payload with a human-readable string a
+ * client supplies would put attacker-controlled text inside the token every
+ * verifier parses. It is display metadata for "your devices", so it lives here,
+ * server-side, beside the jti it describes.
+ */
+export interface SessionRecord {
+    jti: string;
+    userId: string;
+    tenantId: string;
+    /** What the client called itself (`x-cc-device`), if anything. */
+    deviceLabel?: string;
+    /** Epoch SECONDS, matching `exp`'s unit. */
+    issuedAt: number;
+    exp: number;
+}
+/** Non-claim session metadata recorded at mint time (02 §4). */
+export interface SessionMintMeta {
+    /** Free-text device name for the sessions panel. Never signed, never trusted. */
+    deviceLabel?: string;
+}
+export interface SessionSigner extends GuardVerifier {
+    /** Mint a signed session token. `exp`/`jti` are stamped here, never by a caller. */
+    mint(claims: Omit<CCUserClaims, 'exp' | 'jti'> & Partial<Pick<CCUserClaims, 'exp' | 'jti'>>, meta?: SessionMintMeta): {
+        token: string;
+        claims: CCUserClaims;
+    };
+    /**
+     * Revoke every live session this signer minted for `userId`, returning the
+     * jtis it closed. The primitive behind a role/permission change taking effect
+     * NOW (02 §3 — authorization is decided from the token's claims, so a grant
+     * change that leaves the old token alive is a grant change that did not
+     * happen) and behind "log out everywhere" (02 §4).
+     *
+     * Node-local by construction: it can only enumerate what THIS process minted.
+     * Each revocation still writes through to the shared `revocationStore`, so the
+     * jtis it does know about die fleet-wide; a session minted on another node is
+     * closed when that node calls this (or by its own next login).
+     */
+    revokeUser(userId: string): readonly string[];
+    /**
+     * The live sessions this signer minted for `userId`, newest first — the
+     * "your devices" list (02 §4). Node-local for the same reason `revokeUser` is:
+     * a process can only enumerate what it minted. Expired and revoked entries are
+     * dropped, so what it returns is what a request would still be accepted on.
+     */
+    sessionsOf(userId: string): readonly SessionRecord[];
+    /** Revoked-but-not-yet-expired jtis. Exposed for the shutdown/handover path. */
+    activeRevocations(): readonly string[];
+    /** The public half, for a verifier in another process. */
+    publicKeyPem(): string;
+    /**
+     * Settle every pending revocation-store read and write, then prune the store.
+     *
+     * The store writes on `revoke` and the read-through refreshes on `verify` are
+     * fire-and-forget so neither blocks the request path. This awaits them — for
+     * the shutdown/handover path (a node draining must not lose an unwritten
+     * revocation), for the two-signer replay probe, and for any test that needs the
+     * cross-node state to have settled. A no-op when no `revocationStore` is wired.
+     */
+    flushRevocations(): Promise<void>;
+}
+export declare const createSessionSigner: (options?: SessionSignerOptions) => SessionSigner;

package/dist/server/guard/sessionSigner.js

@@ -0,0 +1,303 @@
+/**
+ * The production session signer (02 §4.2) — Ed25519-signed `CCUserClaims` plus
+ * the jti denylist that makes `lock()` mean something.
+ *
+ * The verify harness ships an HMAC stand-in because a probe suite tests the
+ * DECISION table (signature validity, expiry, revocation), not the algorithm.
+ * This is the real one, and the differences are the parts a stand-in cannot
+ * model:
+ *
+ *   * **Asymmetric.** Only the server that holds the private key can mint a
+ *     session. A verifier can be handed the public key alone, so a read-only
+ *     replica or an edge worker can verify without being able to forge.
+ *   * **Revocation is bounded, not unbounded.** A denylist that only ever grows
+ *     is a memory leak wearing a security hat. An entry is dropped once its
+ *     token would have expired anyway, because after `exp` the signature check
+ *     already refuses it.
+ *   * **Expiry before revocation.** An expired token is expired whether or not
+ *     anyone bothered to revoke it — checking in the other order makes the
+ *     denylist load-bearing for a case it does not need to cover.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { CCUserClaimsSchema } from 'cursedbelt-core/session/claims';
+import { AppError } from '../errors';
+const b64url = (input) => Buffer.from(input).toString('base64url');
+/** Ceiling on a client-supplied device label — display text, not a payload. */
+const MAX_DEVICE_LABEL = 64;
+let jtiSequence = 0;
+const defaultJti = () => {
+    jtiSequence += 1;
+    return `jti_${Date.now().toString(36)}_${jtiSequence.toString(36)}`;
+};
+export const createSessionSigner = (options = {}) => {
+    const now = options.now ?? (() => Date.now());
+    const mintJti = options.mintJti ?? defaultJti;
+    const ttlSeconds = options.ttlSeconds ?? 30 * 60;
+    let privateKey = null;
+    let publicKey;
+    if (options.privateKey !== undefined) {
+        privateKey =
+            typeof options.privateKey === 'string' || Buffer.isBuffer(options.privateKey)
+                ? createPrivateKey(options.privateKey)
+                : options.privateKey;
+        publicKey =
+            options.publicKey === undefined
+                ? createPublicKey(privateKey)
+                : typeof options.publicKey === 'string' || Buffer.isBuffer(options.publicKey)
+                    ? createPublicKey(options.publicKey)
+                    : options.publicKey;
+    }
+    else if (options.publicKey !== undefined) {
+        publicKey =
+            typeof options.publicKey === 'string' || Buffer.isBuffer(options.publicKey)
+                ? createPublicKey(options.publicKey)
+                : options.publicKey;
+    }
+    else {
+        const pair = generateKeyPairSync('ed25519');
+        privateKey = pair.privateKey;
+        publicKey = pair.publicKey;
+    }
+    /** jti → the epoch-seconds `exp` after which the entry is pointless. */
+    const revoked = new Map();
+    /**
+     * Live jtis this signer minted, per user — the index behind
+     * {@link SessionSigner.revokeUser} (02 §3's role change, 02 §4's "log out
+     * everywhere"). Deliberately NOT the cross-node picture: a node can only
+     * enumerate what it minted, so under saas the authority for "is this token
+     * dead" stays the shared `revocationStore` that `revokeUser` writes through
+     * to. Entries are dropped as they expire (`pruneMinted`), so this is bounded
+     * by live sessions, not by all sessions ever.
+     */
+    const mintedByUser = new Map();
+    /** jti → its minter, so a revoke can drop the record without scanning users. */
+    const userByJti = new Map();
+    const rememberMinted = (record) => {
+        const forUser = mintedByUser.get(record.userId) ?? new Map();
+        forUser.set(record.jti, record);
+        mintedByUser.set(record.userId, forUser);
+        userByJti.set(record.jti, record.userId);
+    };
+    /**
+     * Drop a jti from the live index. Called on every revoke, so a revoked session
+     * stops being a live one for BOTH `sessionsOf` (the panel) and `revokeUser`
+     * (whose count is then "sessions actually closed", not "jtis ever minted").
+     */
+    const forgetMinted = (jti) => {
+        const userId = userByJti.get(jti);
+        if (userId === undefined)
+            return;
+        userByJti.delete(jti);
+        const forUser = mintedByUser.get(userId);
+        forUser?.delete(jti);
+        if (forUser && forUser.size === 0)
+            mintedByUser.delete(userId);
+    };
+    const pruneMinted = () => {
+        const cutoff = Math.floor(now() / 1000);
+        for (const [userId, sessions] of mintedByUser) {
+            for (const [jti, record] of sessions)
+                if (record.exp <= cutoff) {
+                    sessions.delete(jti);
+                    userByJti.delete(jti);
+                }
+            if (sessions.size === 0)
+                mintedByUser.delete(userId);
+        }
+    };
+    // ── the cross-node denylist (03 §4a) ────────────────────────────────────────
+    const store = options.revocationStore;
+    const cacheTtlMs = options.revocationCacheTtlMs ?? 5000;
+    const onStoreError = options.onRevocationStoreError ?? (() => undefined);
+    /** jti → the last store verdict and when it was read, so `verify` stays sync. */
+    const storeCache = new Map();
+    /** In-flight async work, so `flushRevocations` (and shutdown) can await it. */
+    const pending = new Set();
+    /** Reads in flight per jti, so a burst of verifies coalesces into one store read. */
+    const inflightReads = new Map();
+    const track = (work) => {
+        pending.add(work);
+        void work.finally(() => pending.delete(work));
+    };
+    /** Read the store for `jti` off the hot path and fold the verdict into the cache. */
+    const refreshFromStore = (jti) => {
+        if (!store || inflightReads.has(jti))
+            return;
+        const read = store
+            .get(jti)
+            .then((exp) => {
+            storeCache.set(jti, { exp, readAtMs: now() });
+            // A confirmed revocation is promoted into the authoritative Map so every
+            // later verify is instant and `activeRevocations()` (the handover set)
+            // includes jtis this node learned about from its peers.
+            if (exp !== null) {
+                revoked.set(jti, exp);
+                // A peer revoked it, so it is no longer a live session here either.
+                forgetMinted(jti);
+            }
+        })
+            .catch((error) => onStoreError('get', error))
+            .finally(() => inflightReads.delete(jti));
+        inflightReads.set(jti, read);
+        track(read);
+    };
+    /**
+     * Is `jti` revoked, per the shared store? Answered synchronously from the cache;
+     * a stale or missing entry schedules a refresh but does NOT block. The bound on
+     * how stale the answer can be is `cacheTtlMs` — the cross-node latency the seam
+     * documents.
+     */
+    const storeSaysRevoked = (jti) => {
+        if (!store)
+            return false;
+        const cached = storeCache.get(jti);
+        if (cached === undefined || now() - cached.readAtMs >= cacheTtlMs)
+            refreshFromStore(jti);
+        // A fresh cached exp that is still in the future ⇒ revoked. An expired cached
+        // exp is treated as not-revoked: the signature check already refuses the
+        // token past `exp`, so the denylist has nothing left to add.
+        return cached?.exp != null && cached.exp * 1000 > now();
+    };
+    /**
+     * The one revocation write path — a free function rather than a method so
+     * `revokeUser` cannot depend on `this` (a destructured `const { revokeUser } =
+     * signer` would silently lose it, and losing a revocation is the one bug this
+     * seam must not have).
+     */
+    const revokeJti = (jti) => {
+        pruneRevocations();
+        // An unknown jti is still recorded: `lock()` may revoke a token this
+        // process never minted (another node in the fleet did), and refusing to
+        // remember it would let that token keep working here.
+        const exp = Math.floor(now() / 1000) + ttlSeconds;
+        revoked.set(jti, exp);
+        forgetMinted(jti);
+        // Write through so every OTHER node sees it too. Fire-and-forget: `revoke`
+        // is called on the request path (a `lock`), and the local Map already
+        // refuses the token HERE the instant this returns — propagation is what the
+        // store adds, and `flushRevocations`/the error hook cover its durability.
+        if (store) {
+            storeCache.set(jti, { exp, readAtMs: now() });
+            track(store.set(jti, exp).catch((error) => onStoreError('set', error)));
+        }
+    };
+    const pruneRevocations = () => {
+        const cutoff = Math.floor(now() / 1000);
+        for (const [jti, exp] of revoked)
+            if (exp <= cutoff)
+                revoked.delete(jti);
+        for (const [jti, cached] of storeCache)
+            if (cached.exp !== null && cached.exp <= cutoff)
+                storeCache.delete(jti);
+    };
+    return {
+        mint(input, meta) {
+            if (privateKey === null)
+                throw new AppError('This session signer holds only a public key and cannot mint tokens.', {
+                    code: 'GUARD_SIGNER_READONLY',
+                    status: 500,
+                    category: 'security',
+                    isOperational: false,
+                });
+            const claims = CCUserClaimsSchema.parse({
+                ...input,
+                exp: input.exp ?? Math.floor(now() / 1000) + ttlSeconds,
+                jti: input.jti ?? mintJti(),
+            });
+            const payload = b64url(JSON.stringify(claims));
+            const signature = b64url(sign(null, Buffer.from(payload), privateKey));
+            pruneMinted();
+            rememberMinted({
+                jti: claims.jti,
+                userId: claims.userId,
+                tenantId: claims.tenantId,
+                // A label is truncated rather than rejected: it is display text, and a
+                // login must never fail because a browser sent a long device string.
+                ...(meta?.deviceLabel ? { deviceLabel: meta.deviceLabel.slice(0, MAX_DEVICE_LABEL) } : {}),
+                issuedAt: Math.floor(now() / 1000),
+                exp: claims.exp,
+            });
+            return { token: `${payload}.${signature}`, claims };
+        },
+        verify(token) {
+            if (!token)
+                return { ok: false, failure: 'missing' };
+            const dot = token.indexOf('.');
+            if (dot <= 0 || dot === token.length - 1)
+                return { ok: false, failure: 'malformed' };
+            const payload = token.slice(0, dot);
+            const signature = token.slice(dot + 1);
+            let valid = false;
+            try {
+                valid = verify(null, Buffer.from(payload), publicKey, Buffer.from(signature, 'base64url'));
+            }
+            catch {
+                // A signature that is not even decodable is malformed, not merely wrong.
+                return { ok: false, failure: 'malformed' };
+            }
+            if (!valid)
+                return { ok: false, failure: 'invalid-signature' };
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+            }
+            catch {
+                return { ok: false, failure: 'malformed' };
+            }
+            const parsed = CCUserClaimsSchema.safeParse(parsedJson);
+            // `.strict()`: an unknown claim key is a forged or version-skewed token,
+            // and silently ignoring it is how a `permissions` typo becomes a grant.
+            if (!parsed.success)
+                return { ok: false, failure: 'malformed' };
+            if (parsed.data.exp * 1000 <= now())
+                return { ok: false, failure: 'expired' };
+            // Local Map first (this node's own revokes, and peers' revokes it has
+            // already learned) — always authoritative and free. Then the shared store,
+            // consulted through the sync cache, for a jti revoked on another node.
+            if (revoked.has(parsed.data.jti) || storeSaysRevoked(parsed.data.jti))
+                return { ok: false, failure: 'revoked' };
+            return { ok: true, claims: parsed.data };
+        },
+        revoke(jti) {
+            revokeJti(jti);
+        },
+        revokeUser(userId) {
+            pruneMinted();
+            const jtis = [...(mintedByUser.get(userId)?.keys() ?? [])];
+            for (const jti of jtis)
+                revokeJti(jti);
+            mintedByUser.delete(userId);
+            return jtis;
+        },
+        sessionsOf(userId) {
+            pruneMinted();
+            pruneRevocations();
+            return [...(mintedByUser.get(userId)?.values() ?? [])]
+                // A revoked-but-unexpired jti is a dead session; listing it would invite
+                // "log this device out" on a device that is already out.
+                .filter((record) => !revoked.has(record.jti) && !storeSaysRevoked(record.jti))
+                .sort((left, right) => right.issuedAt - left.issuedAt);
+        },
+        isRevoked(jti) {
+            pruneRevocations();
+            return revoked.has(jti) || storeSaysRevoked(jti);
+        },
+        activeRevocations() {
+            pruneRevocations();
+            return [...revoked.keys()];
+        },
+        async flushRevocations() {
+            // Settle in-flight work, then whatever it scheduled (a read can resolve
+            // after we snapshot), so the caller sees a fully-quiesced state.
+            while (pending.size > 0)
+                await Promise.allSettled([...pending]);
+            if (store)
+                track(store.prune(Math.floor(now() / 1000)).catch((error) => onStoreError('prune', error)));
+            while (pending.size > 0)
+                await Promise.allSettled([...pending]);
+        },
+        publicKeyPem() {
+            return publicKey.export({ type: 'spki', format: 'pem' }).toString();
+        },
+    };
+};

package/dist/server/guard/verifier.d.ts

@@ -0,0 +1,21 @@
+import type { CCUserClaims } from 'cursedbelt-core/session/claims';
+/** Why a presented session token was refused. Mapped to status by `guardVerify`. */
+export type GuardFailure = 'missing' | 'malformed' | 'invalid-signature' | 'expired' | 'revoked';
+export type GuardVerification = {
+    ok: true;
+    claims: CCUserClaims;
+} | {
+    ok: false;
+    failure: GuardFailure;
+};
+/**
+ * Per-request token verification (02 §4.2). The wire only signals; this is what
+ * decides. `verify` is called on every private or mutating route — a pane's
+ * unlock is never cached for another pane's request.
+ */
+export interface GuardVerifier {
+    verify(token: string | undefined): GuardVerification;
+    /** Revoke a jti until its `exp` — what lock does, across every tab. */
+    revoke(jti: string): void;
+    isRevoked(jti: string): boolean;
+}

package/dist/server/guard/verifier.js

@@ -0,0 +1 @@
+export {};