cursedbelt-server 1.0.0

package/dist/server/guard/kdfWorker.js

@@ -0,0 +1,301 @@
+/**
+ * The off-thread KDF (05 §B6) — a long-lived worker that owns every byte of key
+ * material it produces.
+ *
+ * ## The problem
+ *
+ * argon2id at the platform parameters is ~150–250 ms of *pure CPU*. The KDF seam
+ * is synchronous by design (see `Argon2idDeriver` — the async bindings return
+ * un-zeroizable PHC strings), so that time is spent on the event loop with
+ * nothing else able to run. There is no race and no correctness bug; there is a
+ * hard throughput ceiling. A saas node handling a burst of logins serializes
+ * them AND stalls every unrelated request for the duration, so one tenant's
+ * login storm is every other tenant's latency spike.
+ *
+ * ## The design, and the one thing that makes it worth building
+ *
+ * The naive off-thread KDF derives in a worker and posts the KEY BACK. That
+ * moves the CPU but weakens custody: the key crosses a structured-clone boundary
+ * (a copy the sender cannot zeroize, because clone semantics leave the original
+ * behind and the receiver adopts a second allocation), and it lands in a host
+ * that must remember to destroy it.
+ *
+ * **Nothing here posts a key.** The worker runs the SHIPPED
+ * `sealPasswordVerifier` / `verifyPasswordEnvelope` — the same functions, the
+ * same envelope format, the same one KDF — so the derived key is born, used and
+ * zeroized entirely inside the worker thread. What crosses back is a boolean or
+ * the sealed *ciphertext*. The password crosses inward, because it arrives from
+ * the request and must; the worker zeroizes its copy on every path, and the host
+ * zeroizes its own.
+ *
+ * That is why this is a worker for the whole VERIFY rather than a worker for the
+ * derivation: relocating the derivation alone would have traded a throughput
+ * problem for a custody problem.
+ *
+ * ## Long-lived, never per-call
+ *
+ * Thread startup plus module load (a native argon2 binding!) is tens of
+ * milliseconds, and a spawn-per-login design lets a login storm fork unbounded
+ * OS threads — which is the same denial of service the ceiling above, only
+ * worse. One thread, multiplexed by request id. This is the mistake
+ * `createMarshalWorkerClient` documents in `core/wire/marshalWorker.ts`; it is
+ * repeated here deliberately in the same shape so both read alike.
+ */
+import { AppError } from '../errors';
+import { createInProcessPasswordVerifier, sealPasswordVerifier, verifyPasswordEnvelope, } from './passwordVerifier';
+import { registerNodeRsArgon2id } from './argon2Binding';
+/** Raised when the worker thread dies, fails to start, or is disposed mid-flight. */
+export const GUARD_KDF_WORKER_FAILED = 'GUARD_KDF_WORKER_FAILED';
+/** Raised when the worker does not answer within the configured budget. */
+export const GUARD_KDF_WORKER_TIMEOUT = 'GUARD_KDF_WORKER_TIMEOUT';
+/**
+ * Default per-request ceiling. Generous relative to a ~250 ms derivation on
+ * purpose: this is a liveness backstop for a wedged thread, not a latency SLO,
+ * and a tight budget here would turn a loaded machine into a login outage.
+ */
+export const KDF_WORKER_DEFAULT_TIMEOUT_MS = 15_000;
+const nodeWorkerScope = async () => {
+    const { parentPort } = await import('node:worker_threads');
+    if (parentPort === null)
+        throw new Error('serveKdfWorker() was called outside a worker thread.');
+    return {
+        postMessage: (data) => parentPort.postMessage(data),
+        onMessage: (handler) => parentPort.on('message', handler),
+    };
+};
+/**
+ * Run the KDF worker's message loop. A worker entry module is this call and
+ * nothing else (see `kdfWorkerEntry.ts`).
+ *
+ * `register` is injectable so the spec can drive the loop with a cheap fake
+ * binding — registering the real native argon2 in a test that only checks
+ * message plumbing would pay 250 ms per case to prove nothing about the
+ * plumbing. The DEFAULT is the real binding, because a worker that silently ran
+ * a fake KDF would be a catastrophe rather than a bug.
+ */
+export async function serveKdfWorker(options = {}) {
+    const scope = options.scope ?? (await nodeWorkerScope());
+    // Registration happens ONCE, at worker start, before any request is served —
+    // not lazily per request, or the first login of every thread pays a native
+    // module load inside its own timeout budget.
+    await (options.register ?? registerNodeRsArgon2id)();
+    scope.onMessage((data) => {
+        const request = data;
+        if (typeof request?.id !== 'number')
+            return;
+        // The password arrives as a structured-clone copy owned by THIS thread.
+        // Re-wrap anything that is not already a Uint8Array rather than trusting the
+        // wire type — a plain `{0:..,1:..}` would silently derive from the wrong
+        // bytes instead of failing — but keep the inbound view too, because it is a
+        // second plaintext copy this thread is responsible for.
+        const inbound = request.password;
+        const password = inbound instanceof Uint8Array ? inbound : new Uint8Array(inbound);
+        try {
+            const value = request.kind === 'seal'
+                ? sealPasswordVerifier(request.userId, password)
+                : verifyPasswordEnvelope(request.userId, request.envelopeJson, password);
+            scope.postMessage({ id: request.id, ok: true, value });
+        }
+        catch (error) {
+            // Only the CODE and message cross back. An error `context` in this module
+            // can hold envelope fields, so the envelope itself never leaves.
+            scope.postMessage({
+                id: request.id,
+                ok: false,
+                code: (error instanceof AppError ? error.code : undefined) ?? GUARD_KDF_WORKER_FAILED,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            // Both `sealPasswordVerifier` and `verifyPasswordEnvelope` consume (and so
+            // zeroize) the buffer they are handed — but they are the far side of a
+            // contract, and a throw BEFORE they are reached (a malformed envelope, an
+            // unregistered deriver) leaves a plaintext password in worker RAM. Clearing
+            // again is idempotent and costs a memset.
+            //
+            // EVERY view, not just the one that was used: when the wire type is wrong
+            // the re-wrap above makes a second allocation, and zeroizing only the copy
+            // we derived from would leave the structured clone this thread was handed
+            // sitting in memory for the life of the worker.
+            password.fill(0);
+            if (inbound !== password && inbound instanceof Uint8Array)
+                inbound.fill(0);
+        }
+    });
+}
+function spawnHostWorker(entry) {
+    // Callers await `settled` rather than seeing the construction race. It is
+    // RESOLVED, never rejected, on every exit path including a failed spawn: a
+    // rejection here would surface as an unhandled rejection on a request that the
+    // error handler below is already failing properly.
+    let realPost = null;
+    let markSettled = () => undefined;
+    const settled = new Promise((resolve) => {
+        markSettled = resolve;
+    });
+    let terminated = false;
+    const messageHandlers = [];
+    const errorHandlers = [];
+    let terminateReal = null;
+    void (async () => {
+        try {
+            const { Worker } = await import('node:worker_threads');
+            if (terminated)
+                return;
+            const worker = new Worker(entry);
+            worker.on('message', (data) => {
+                for (const handler of messageHandlers)
+                    handler(data);
+            });
+            worker.on('error', (error) => {
+                for (const handler of errorHandlers)
+                    handler(error);
+            });
+            // ANY exit is a failure: this worker is long-lived by design, so it should
+            // outlive every request. A cleanly-exited thread that went unnoticed would
+            // leave each in-flight login waiting out its full timeout, and every later
+            // one posting into a dead thread to do the same.
+            worker.on('exit', (code) => {
+                const how = code === 0 ? 'exited cleanly while still in use' : `exited with code ${code}`;
+                for (const handler of errorHandlers)
+                    handler(new Error(`KDF worker ${how}`));
+            });
+            realPost = (data) => worker.postMessage(data);
+            terminateReal = () => void worker.terminate();
+        }
+        catch (error) {
+            for (const handler of errorHandlers)
+                handler(error);
+        }
+        finally {
+            markSettled();
+        }
+    })();
+    return {
+        async post(data) {
+            if (realPost === null)
+                await settled;
+            // Still null ⇒ the spawn failed or we were disposed mid-construction. The
+            // error handler has already failed (or will fail) the request; dropping
+            // the message is correct, and the caller may now zeroize.
+            realPost?.(data);
+        },
+        onMessage: (handler) => messageHandlers.push(handler),
+        onError: (handler) => errorHandlers.push(handler),
+        terminate: () => {
+            terminated = true;
+            markSettled();
+            terminateReal?.();
+        },
+    };
+}
+/**
+ * A {@link PasswordVerifierPort} backed by one long-lived worker thread.
+ *
+ * Hand it to `createAccountService({ passwords })` on a host that expects login
+ * concurrency. Local single-user hosts should NOT — they would pay a thread and
+ * a native module load to serialize a workload that was never contended.
+ */
+export function createKdfWorkerPasswordVerifier(options) {
+    const timeoutMs = options.timeoutMs ?? KDF_WORKER_DEFAULT_TIMEOUT_MS;
+    const worker = (options.spawn ?? spawnHostWorker)(options.entry);
+    const pending = new Map();
+    let nextId = 1;
+    let disposed = false;
+    const settle = (id, apply) => {
+        const entry = pending.get(id);
+        if (!entry)
+            return; // already timed out — a late reply is discarded
+        pending.delete(id);
+        clearTimeout(entry.timer);
+        apply(entry);
+    };
+    const failure = (message, code, status) => new AppError(message, { code, status, category: 'security', context: { worker: String(options.entry) } });
+    worker.onMessage((data) => {
+        const response = data;
+        if (typeof response?.id !== 'number')
+            return;
+        settle(response.id, (p) => {
+            if (response.ok) {
+                p.resolve(response.value);
+                return;
+            }
+            // Preserve the worker's own code: `SECRET_ENVELOPE_*` failures are a
+            // corrupt row, not a dead thread, and a caller distinguishing them must
+            // still be able to.
+            p.reject(failure(response.message, response.code, 500));
+        });
+    });
+    // A dead worker takes every request in flight with it — failing them now beats
+    // each one waiting out its own timeout.
+    worker.onError((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        for (const id of [...pending.keys()])
+            settle(id, (p) => p.reject(failure(`KDF worker failed: ${message}`, GUARD_KDF_WORKER_FAILED, 500)));
+    });
+    /**
+     * Post the request, zeroize the host's copy of the password as soon as the
+     * thread has it, then await the verdict.
+     *
+     * The zeroize placement is the point. The worker holds a structured-clone
+     * copy, so the host's buffer is dead weight the instant the post lands —
+     * and the await that follows lasts the whole ~250 ms derivation, which is
+     * exactly the window in which a heap snapshot, a core dump or a crash reporter
+     * would capture a plaintext password. Clearing it before the await instead of
+     * in a `finally` after it removes that window entirely.
+     */
+    const send = async (build, password) => {
+        if (disposed)
+            throw failure('The KDF worker has been disposed.', GUARD_KDF_WORKER_FAILED, 500);
+        const id = nextId++;
+        const answer = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(failure(`The KDF worker did not answer within ${timeoutMs}ms.`, GUARD_KDF_WORKER_TIMEOUT, 504));
+            }, timeoutMs);
+            pending.set(id, { resolve, reject, timer });
+        });
+        try {
+            await worker.post(build(id));
+        }
+        finally {
+            password.fill(0);
+        }
+        return await answer;
+    };
+    return {
+        async seal(userId, password) {
+            const value = await send((id) => ({ id, kind: 'seal', userId, password }), password);
+            if (typeof value !== 'string')
+                throw failure('The KDF worker returned a non-string envelope for seal().', GUARD_KDF_WORKER_FAILED, 500);
+            return value;
+        },
+        async verify(userId, envelopeJson, password) {
+            const value = await send((id) => ({ id, kind: 'verify', userId, envelopeJson, password }), password);
+            if (typeof value !== 'boolean')
+                throw failure('The KDF worker returned a non-boolean verdict for verify().', GUARD_KDF_WORKER_FAILED, 500);
+            return value;
+        },
+        async dispose() {
+            disposed = true;
+            for (const id of [...pending.keys()])
+                settle(id, (p) => p.reject(failure('The KDF worker was disposed while a request was in flight.', GUARD_KDF_WORKER_FAILED, 503)));
+            worker.terminate();
+        },
+    };
+}
+/**
+ * The URL of the entry module {@link createKdfWorkerPasswordVerifier} spawns.
+ *
+ * Resolved relative to THIS module rather than hard-coded by the host, so an app
+ * never has to know where inside the package the entry lives:
+ *
+ *   createKdfWorkerPasswordVerifier({ entry: kdfWorkerEntryUrl() })
+ *
+ * Under the `bun` export condition this resolves to the TypeScript source, which
+ * is what every first-party consumer runs (see the monorepo's zero-build-lag
+ * contract). A non-Bun host consuming built `dist/` names its own built entry.
+ */
+export const kdfWorkerEntryUrl = () => new URL('./kdfWorkerEntry.ts', import.meta.url);
+/** Re-exported so a host wiring the guard tier needs one import. */
+export { createInProcessPasswordVerifier };

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

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

package/dist/server/guard/kdfWorkerEntry.js

@@ -0,0 +1,15 @@
+/**
+ * The SHIPPED KDF worker entry (05 §B6).
+ *
+ * Unlike a marshalling worker — where every marshaller declares its own entry
+ * because every marshaller has its own schema — there is exactly ONE password
+ * KDF in the platform (Law #7), so there is exactly one entry and the framework
+ * ships it. A host does not write this file; it points
+ * `createKdfWorkerPasswordVerifier({ entry: kdfWorkerEntryUrl() })` at it.
+ *
+ * The whole module is one call on purpose: everything a worker entry does that
+ * is not "start the loop" is code running on a thread with a live argon2id
+ * binding and a plaintext password in scope.
+ */
+import { serveKdfWorker } from './kdfWorker';
+await serveKdfWorker();

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

@@ -0,0 +1,65 @@
+import { type Argon2idDeriver } from 'cwip/guard';
+/**
+ * Seal a password verifier for `userId`, returning the serialized `SecretEnvelope`
+ * to store in `users.pw_envelope`. **Consumes `password`** (zeroized before return).
+ *
+ * A fresh per-user KDF salt is minted for each call, so two users with the same
+ * password produce different envelopes and re-deriving one never helps the other.
+ */
+export declare function sealPasswordVerifier(userId: string, password: Uint8Array, deriver?: Argon2idDeriver): string;
+/**
+ * Check `password` against the stored `envelopeJson` for `userId`. **Consumes
+ * `password`** (zeroized before return). Returns `true` iff the password is
+ * correct; `false` for a wrong password (GCM authentication failure). A malformed
+ * stored envelope is corruption, not a wrong password, and re-throws.
+ *
+ * The comparison is constant-time in the sensitive part: argon2id derivation
+ * dominates the timing, and GCM tag verification plus the final `timingSafeEqual`
+ * are constant-time, so a right and a wrong password of equal length are
+ * indistinguishable by timing.
+ */
+export declare function verifyPasswordEnvelope(userId: string, envelopeJson: string, password: Uint8Array, deriver?: Argon2idDeriver): boolean;
+/**
+ * Where password derivation RUNS (05 §B6).
+ *
+ * The two functions above are synchronous on purpose — the KDF seam is, and for
+ * the reason documented on `Argon2idDeriver`: every async argon2id binding hands
+ * back a promise AND a base64/PHC *string*, which is key material that cannot be
+ * zeroized. The cost is that one derivation is ~150–250 ms of pure CPU on the
+ * event loop, so concurrent logins SERIALIZE and stall every unrelated request
+ * on the process for that window. A single-user local app never notices; a saas
+ * node taking a burst of logins does, and so does every tenant sharing it.
+ *
+ * This port is the seam that lets a host move that burn off the request thread
+ * WITHOUT introducing a second KDF, a second envelope format, or an async
+ * deriver. Both implementations call the exact same `sealPasswordVerifier` /
+ * `verifyPasswordEnvelope` above; they differ only in which thread runs them.
+ *
+ *   local / default   {@link createInProcessPasswordVerifier} — direct calls,
+ *                     byte-for-byte the behavior that shipped before this port
+ *                     existed.
+ *   saas / opt-in     `createKdfWorkerPasswordVerifier` (`./kdfWorker`) — a
+ *                     long-lived worker thread. **No key material crosses the
+ *                     thread boundary in either direction**: the password goes
+ *                     in, the derived key is born, used and zeroized inside the
+ *                     worker, and only a boolean (or the sealed ciphertext)
+ *                     comes back.
+ *
+ * Both entry points CONSUME `password` — ownership transfers on the call, and
+ * the buffer is zeroized on every path including a throw.
+ */
+export interface PasswordVerifierPort {
+    /** Seal a verifier for `userId`, returning the serialized envelope. Consumes `password`. */
+    seal(userId: string, password: Uint8Array): Promise<string>;
+    /** `true` iff `password` matches `envelopeJson`. Consumes `password`. */
+    verify(userId: string, envelopeJson: string, password: Uint8Array): Promise<boolean>;
+    /** Release any thread/handle the implementation owns. In-process: a no-op. */
+    dispose?(): Promise<void>;
+}
+/**
+ * The default port: derive on the calling thread, exactly as every caller did
+ * before the port existed. Nothing about the crypto changes — this is the same
+ * two functions behind a promise, so a host that never opts into the worker
+ * path pays no async penalty beyond one already-resolved microtask.
+ */
+export declare function createInProcessPasswordVerifier(deriver?: Argon2idDeriver): PasswordVerifierPort;

package/dist/server/guard/passwordVerifier.js

@@ -0,0 +1,122 @@
+/**
+ * Password verifiers over the ONE KDF (02 §2, Law #7).
+ *
+ * A login password check needs a *verifier* — something stored per user that a
+ * presented password can be checked against — WITHOUT introducing a second hash
+ * function or a second at-rest secret format. The platform already ships exactly
+ * one of each: the argon2id seam (`cwip/.../guard/kdf.ts`) and the
+ * `SecretEnvelope` (`cwip/.../guard/secretEnvelope.ts`). This module builds the
+ * verifier out of those, adding nothing.
+ *
+ * The trick: a verifier is a `SecretEnvelope` that seals a FIXED known plaintext
+ * under a key argon2id-derived from the user's password. To check a password,
+ * re-derive the one-shot key from the presented password and try to open the
+ * envelope — GCM's authentication tag IS the password check. A wrong password
+ * derives a wrong key and GCM refuses (`SECRET_ENVELOPE_AUTH_FAILED`), which we
+ * translate to `false`; a right password opens and the recovered plaintext
+ * matches the known constant. No password hash is ever stored, compared, or even
+ * computed outside the KDF, and the envelope is the same `pw_envelope` string the
+ * registry `users.pw_envelope` column already types.
+ *
+ * Two properties that are not incidental:
+ *
+ *   - **The verifier is bound to its user.** The envelope AAD is `cc-pw:<userId>`,
+ *     so a `pw_envelope` lifted out of user A's row into user B's fails GCM
+ *     authentication rather than letting B log in with A's password (the same
+ *     swap defense `SecretEnvelope` gives every secret).
+ *   - **Byte custody (01 §3.4).** Both entry points CONSUME the password buffer:
+ *     the underlying manager zeroizes it the moment the KDF is done with it, on
+ *     every path including a thrown KDF. Callers hand over ownership and must not
+ *     touch the buffer afterwards.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { createSecretEnvelopeManager, mintEnvelopeSalt, parseSecretEnvelope, serializeSecretEnvelope, zeroize, } from 'cwip/guard';
+import { isAppError } from '../errors';
+/**
+ * The reserved AAD app namespace for password verifiers. `SecretEnvelope` forbids
+ * a ':' in the appId (it separates the AAD fields), so this is a plain token; the
+ * userId rides the AAD `key` half.
+ */
+const PW_APP = 'cc-pw';
+/** The fixed plaintext every verifier seals — its recovery on open is the success signal. */
+const VERIFIER_PLAINTEXT = new TextEncoder().encode('cc-guard-pw-verifier-v1');
+/** Bind an envelope to one user: AAD becomes `cc-pw:<userId>`. */
+const refFor = (userId) => ({ appId: PW_APP, key: userId });
+/**
+ * Seal a password verifier for `userId`, returning the serialized `SecretEnvelope`
+ * to store in `users.pw_envelope`. **Consumes `password`** (zeroized before return).
+ *
+ * A fresh per-user KDF salt is minted for each call, so two users with the same
+ * password produce different envelopes and re-deriving one never helps the other.
+ */
+export function sealPasswordVerifier(userId, password, deriver) {
+    const manager = createSecretEnvelopeManager({ salt: mintEnvelopeSalt(), deriver });
+    try {
+        // unlock derives the master key from (password, salt) and zeroizes `password`
+        // in its own finally — including if the KDF throws.
+        manager.unlock(password);
+        return serializeSecretEnvelope(manager.seal(refFor(userId), VERIFIER_PLAINTEXT));
+    }
+    finally {
+        manager.lock();
+    }
+}
+/**
+ * Check `password` against the stored `envelopeJson` for `userId`. **Consumes
+ * `password`** (zeroized before return). Returns `true` iff the password is
+ * correct; `false` for a wrong password (GCM authentication failure). A malformed
+ * stored envelope is corruption, not a wrong password, and re-throws.
+ *
+ * The comparison is constant-time in the sensitive part: argon2id derivation
+ * dominates the timing, and GCM tag verification plus the final `timingSafeEqual`
+ * are constant-time, so a right and a wrong password of equal length are
+ * indistinguishable by timing.
+ */
+export function verifyPasswordEnvelope(userId, envelopeJson, password, deriver) {
+    let envelope;
+    try {
+        envelope = parseSecretEnvelope(envelopeJson);
+    }
+    catch (error) {
+        // A stored envelope that will not parse is a tampered/corrupt row — never
+        // silently treat it as "wrong password". Zeroize the buffer we were handed
+        // before propagating (the manager never got a chance to).
+        zeroize(password);
+        throw error;
+    }
+    const manager = createSecretEnvelopeManager({ salt: mintEnvelopeSalt(), deriver });
+    let opened = null;
+    try {
+        // openWithPassphrase re-derives a one-shot key from the envelope's own salt +
+        // the presented password, opens, and zeroizes `password` on every path.
+        opened = manager.openWithPassphrase(envelope, refFor(userId), password);
+        return opened.byteLength === VERIFIER_PLAINTEXT.byteLength && timingSafeEqual(opened, VERIFIER_PLAINTEXT);
+    }
+    catch (error) {
+        // GCM's rejection is the wrong-password verdict — the ONLY error we swallow.
+        if (isAppError(error) && error.code === 'SECRET_ENVELOPE_AUTH_FAILED')
+            return false;
+        throw error;
+    }
+    finally {
+        if (opened)
+            zeroize(opened);
+        manager.lock();
+    }
+}
+/**
+ * The default port: derive on the calling thread, exactly as every caller did
+ * before the port existed. Nothing about the crypto changes — this is the same
+ * two functions behind a promise, so a host that never opts into the worker
+ * path pays no async penalty beyond one already-resolved microtask.
+ */
+export function createInProcessPasswordVerifier(deriver) {
+    return {
+        async seal(userId, password) {
+            return sealPasswordVerifier(userId, password, deriver);
+        },
+        async verify(userId, envelopeJson, password) {
+            return verifyPasswordEnvelope(userId, envelopeJson, password, deriver);
+        },
+    };
+}

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

@@ -0,0 +1,132 @@
+/**
+ * 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 declare function createMemoryRevocationStore(): RevocationStore & {
+    size(): number;
+};
+/**
+ * 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 declare function createSqliteRevocationStore(dbPath: string): RevocationStore & {
+    close(): void;
+};
+/**
+ * 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 declare function createMemoryAsyncRevocationStore(): AsyncRevocationStore & {
+    size(): number;
+};
+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 declare function createAsyncBackedRevocationStore(backing: AsyncRevocationStore, options?: AsyncBackedRevocationStoreOptions): RevocationStore & {
+    flush(): Promise<void>;
+};