cursedbelt-server 1.0.0

package/src/server/guard/revocationStore.spec.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  createAsyncBackedRevocationStore,
+  createMemoryAsyncRevocationStore,
+  createMemoryRevocationStore,
+  createSqliteRevocationStore,
+} from './revocationStore';
+
+describe('sync memory revocation store', () => {
+  it('records, answers, and sweeps by ms expiry', () => {
+    const store = createMemoryRevocationStore();
+    expect(store.isRevoked('a')).toBe(false);
+    store.revoke('a', 10_000);
+    expect(store.isRevoked('a')).toBe(true);
+    expect(store.size()).toBe(1);
+    // sweep drops entries whose expiry has passed, keeps the rest
+    store.revoke('b', 30_000);
+    store.sweep(20_000);
+    expect(store.isRevoked('a')).toBe(false);
+    expect(store.isRevoked('b')).toBe(true);
+    expect(store.size()).toBe(1);
+  });
+});
+
+describe('sqlite revocation store', () => {
+  it('records, answers, sweeps, and closes', () => {
+    const store = createSqliteRevocationStore(':memory:');
+    try {
+      store.revoke('sess-1', 50_000);
+      expect(store.isRevoked('sess-1')).toBe(true);
+      expect(store.isRevoked('sess-2')).toBe(false);
+      store.sweep(60_000); // past the expiry → gone
+      expect(store.isRevoked('sess-1')).toBe(false);
+    } finally {
+      store.close();
+    }
+  });
+
+  it('re-revoking an id is idempotent (INSERT OR REPLACE)', () => {
+    const store = createSqliteRevocationStore(':memory:');
+    try {
+      store.revoke('id', 10_000);
+      store.revoke('id', 20_000);
+      expect(store.isRevoked('id')).toBe(true);
+      store.sweep(15_000); // the second, later expiry wins → still revoked
+      expect(store.isRevoked('id')).toBe(true);
+    } finally {
+      store.close();
+    }
+  });
+});
+
+describe('async-backed revocation store (the cross-node bridge)', () => {
+  it('refuses an id synchronously the instant revoke() returns, before the write settles', () => {
+    const backing = createMemoryAsyncRevocationStore();
+    let clock = 1_000_000;
+    const store = createAsyncBackedRevocationStore(backing, { now: () => clock });
+    store.revoke('jti', clock + 60_000);
+    // No await: the local cache must already refuse it.
+    expect(store.isRevoked('jti')).toBe(true);
+  });
+
+  it('a revoke on node A is seen on node B through the shared backing (V7.3-style)', async () => {
+    const shared = createMemoryAsyncRevocationStore();
+    let clock = 2_000_000;
+    const now = () => clock;
+    const nodeA = createAsyncBackedRevocationStore(shared, { now });
+    const nodeB = createAsyncBackedRevocationStore(shared, { now });
+
+    nodeA.revoke('jti', clock + 60_000);
+    await nodeA.flush(); // the write reaches the shared backing
+
+    // B has not read it yet → still allowed. The read is scheduled, not awaited.
+    expect(nodeB.isRevoked('jti')).toBe(false);
+    await nodeB.flush(); // the scheduled read settles → B has learned it
+    expect(nodeB.isRevoked('jti')).toBe(true);
+
+    // ms→s conversion round-trips: the backing holds epoch SECONDS.
+    expect(await shared.get('jti')).toBe(Math.ceil((clock + 60_000) / 1000));
+  });
+
+  it('a stale cache entry triggers a background refresh past cacheTtlMs', async () => {
+    const shared = createMemoryAsyncRevocationStore();
+    let clock = 3_000_000;
+    const reader = createAsyncBackedRevocationStore(shared, { now: () => clock, cacheTtlMs: 5_000 });
+
+    expect(reader.isRevoked('jti')).toBe(false); // schedules first read (miss)
+    await reader.flush();
+
+    // A peer revokes directly in the shared backing.
+    await shared.set('jti', Math.ceil((clock + 60_000) / 1000));
+
+    // Within the cache window the reader still trusts its cached miss.
+    clock += 4_000;
+    expect(reader.isRevoked('jti')).toBe(false);
+
+    // Past the window it re-reads.
+    clock += 2_000;
+    expect(reader.isRevoked('jti')).toBe(false); // returns cached, schedules refresh
+    await reader.flush();
+    expect(reader.isRevoked('jti')).toBe(true);
+  });
+
+  it('sweep prunes the shared backing and drops expired local cache entries', async () => {
+    const shared = createMemoryAsyncRevocationStore();
+    let clock = 4_000_000;
+    const store = createAsyncBackedRevocationStore(shared, { now: () => clock });
+    store.revoke('old', clock + 1_000);
+    store.revoke('new', clock + 60_000);
+    await store.flush();
+    expect(shared.size()).toBe(2);
+
+    clock += 30_000;
+    store.sweep(clock);
+    await store.flush();
+    expect(shared.size()).toBe(1); // 'old' pruned from the shared backing
+    expect(store.isRevoked('new')).toBe(true);
+  });
+
+  it('a backing failure is reported, never thrown out of the request path', async () => {
+    const ops: string[] = [];
+    const boom: import('./revocationStore').AsyncRevocationStore = {
+      set: () => Promise.reject(new Error('set failed')),
+      get: () => Promise.reject(new Error('get failed')),
+      prune: () => Promise.reject(new Error('prune failed')),
+    };
+    const store = createAsyncBackedRevocationStore(boom, { onError: (op) => ops.push(op) });
+    expect(() => store.revoke('x', 10_000)).not.toThrow();
+    // A different, uncached id so `isRevoked` actually schedules a backing read.
+    expect(() => store.isRevoked('y')).not.toThrow();
+    expect(() => store.sweep(10_000)).not.toThrow();
+    await store.flush();
+    expect(ops.sort()).toEqual(['get', 'prune', 'set']);
+  });
+});

package/src/server/guard/revocationStore.ts

@@ -0,0 +1,291 @@
+/**
+ * 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';
+
+/* ============================================================ sync contract */
+
+/**
+ * Somewhere to record the session/token ids that must no longer be accepted,
+ * answered synchronously.
+ *
+ * Deliberately tiny, and deliberately not a session store: the token still
+ * carries its own expiry and signature, so this only ever answers "was this one
+ * withdrawn early". `sweep` exists so the table cannot grow forever — every
+ * entry becomes meaningless the moment its session would have expired anyway.
+ *
+ * Epoch **milliseconds** throughout, matching `Date.now()` and the satellites'
+ * cookie expiry. (The cross-node {@link AsyncRevocationStore} works in seconds,
+ * matching the signer's `exp`; {@link createAsyncBackedRevocationStore} bridges
+ * the two.)
+ */
+export interface RevocationStore {
+  /** Has this id been revoked? Called on every authenticated request. */
+  isRevoked(id: string): boolean;
+  /** Record a revocation until `expiresAtMs`, after which it is moot. */
+  revoke(id: string, expiresAtMs: number): void;
+  /** Drop entries whose sessions have expired. Called opportunistically. */
+  sweep(nowMs: number): void;
+}
+
+/**
+ * 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(): RevocationStore & { size(): number } {
+  const entries = new Map<string, number>();
+  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: string): RevocationStore & { close(): void } {
+  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<{ id: string }, [string]>('SELECT id FROM revoked_sessions WHERE id = ?');
+  const insert = db.query<unknown, [string, number]>(
+    'INSERT OR REPLACE INTO revoked_sessions (id, expires_at) VALUES (?, ?)',
+  );
+  const prune = db.query<unknown, [number]>('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(),
+  };
+}
+
+/* ================================================ async cross-node contract */
+
+/**
+ * Where revoked jtis live so every node sees them (03 §4a). Local profile:
+ * unused (a per-process `Map` is enough for one process). SaaS: a Redis hash
+ * with per-entry TTL, or a row in the shared Postgres — the contract is
+ * identical, which is the point.
+ *
+ * Only `set`/`get`/`prune` and no bulk `list`, because the consumer's hot path
+ * is a SYNCHRONOUS `verify` (see {@link createSessionSigner}) that consults the
+ * store read-through by id off the hot path — never a full scan on every verify.
+ *
+ * Epoch **seconds** throughout, matching a token's own `exp`.
+ */
+export interface AsyncRevocationStore {
+  /**
+   * Record `jti` as revoked until `expEpochSeconds`. Idempotent; a re-revoke of
+   * the same jti is a no-op (or extends the exp, which is harmless — a denylist
+   * entry that outlives its token only wastes a little space until `prune`).
+   */
+  set(jti: string, expEpochSeconds: number): Promise<void>;
+  /** The `exp` of a revoked jti (epoch seconds), or `null` when it is not revoked. */
+  get(jti: string): Promise<number | null>;
+  /** Drop every entry whose `exp <= nowEpochSeconds`. Returns the count removed. */
+  prune(nowEpochSeconds: number): Promise<number>;
+}
+
+/**
+ * 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(): AsyncRevocationStore & { size(): number } {
+  const revoked = new Map<string, number>();
+  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;
+    },
+  };
+}
+
+/* ==================================================== the bridge: async → sync */
+
+export interface AsyncBackedRevocationStoreOptions {
+  /** Injected clock in **milliseconds** (default `Date.now`), for tests. */
+  now?: () => number;
+  /**
+   * How long a store verdict is trusted before `isRevoked` re-reads it (ms).
+   * This is the cross-node revocation LATENCY BOUND: a revocation written by
+   * another node is seen here within this window (plus the store's own read
+   * latency), because `isRevoked` stays synchronous — it answers from the cache
+   * and refreshes it off the hot path rather than awaiting a round trip. Default
+   * 5000 (03 §4a's ≤5s).
+   */
+  cacheTtlMs?: number;
+  /**
+   * Reports a backing read/write that failed. A failed write-through means a
+   * revocation did not reach other nodes — the local cache still refuses the id
+   * HERE, but the host may want to retry or alarm. Default: swallow, because a
+   * sync store must never throw out of `isRevoked`/`revoke` on the request path.
+   */
+  onError?: (op: 'get' | 'set' | 'prune', error: unknown) => void;
+}
+
+/**
+ * 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: AsyncRevocationStore,
+  options: AsyncBackedRevocationStoreOptions = {},
+): RevocationStore & { flush(): Promise<void> } {
+  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<string, { expMs: number | null; readAtMs: number }>();
+  const pending = new Set<Promise<unknown>>();
+  /** Reads in flight per id, so a burst of `isRevoked` coalesces into one read. */
+  const inflightReads = new Map<string, Promise<void>>();
+
+  const track = (work: Promise<unknown>): void => {
+    pending.add(work);
+    void work.finally(() => pending.delete(work));
+  };
+
+  const refresh = (id: string): void => {
+    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]);
+    },
+  };
+}