cursedbelt-server 1.0.0

package/src/server/guard/kdfWorker.ts

@@ -0,0 +1,367 @@
+/**
+ * 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,
+  type PasswordVerifierPort,
+  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;
+
+/* ------------------------------------------------------------- the protocol */
+
+export type KdfWorkerRequest =
+  | { id: number; kind: 'seal'; userId: string; password: Uint8Array }
+  | { id: number; kind: 'verify'; userId: string; envelopeJson: string; password: Uint8Array };
+
+export type KdfWorkerResponse =
+  | { id: number; ok: true; value: string | boolean }
+  | { id: number; ok: false; code: string; message: string };
+
+/* ---------------------------------------------------------- the worker side */
+
+/** The subset of a worker-thread global this module needs, in either runtime. */
+interface WorkerScope {
+  postMessage(data: unknown): void;
+  onMessage(handler: (data: unknown) => void): void;
+}
+
+const nodeWorkerScope = async (): Promise<WorkerScope> => {
+  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: { scope?: WorkerScope; register?: () => Promise<void> } = {}): Promise<void> {
+  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: unknown) => {
+    const request = data as KdfWorkerRequest;
+    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 } satisfies KdfWorkerResponse);
+    } 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),
+      } satisfies KdfWorkerResponse);
+    } 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);
+    }
+  });
+}
+
+/* ------------------------------------------------------------- the host side */
+
+/**
+ * The subset of both runtimes' Worker the client needs.
+ *
+ * `post` RESOLVES ONCE THE DATA HAS BEEN HANDED TO THE THREAD, and that is not a
+ * stylistic choice. A worker is constructed asynchronously, so early requests
+ * are queued; the queue holds the caller's `Uint8Array` by reference. A client
+ * that zeroized the password right after a fire-and-forget `post()` would blank
+ * the buffer the queue is still holding, and the worker would then derive a key
+ * from 32 zero bytes — accepting every wrong password that happened to be
+ * presented during startup. Awaiting the post is what makes "zeroize as early as
+ * possible" and "send the real bytes" compatible.
+ */
+interface HostWorker {
+  post(data: unknown): Promise<void>;
+  onMessage(handler: (data: unknown) => void): void;
+  onError(handler: (error: unknown) => void): void;
+  terminate(): void;
+}
+
+export interface KdfWorkerOptions {
+  /** Module specifier / URL of an entry that calls {@link serveKdfWorker}. */
+  entry: string | URL;
+  /** Per-request ceiling. Defaults to {@link KDF_WORKER_DEFAULT_TIMEOUT_MS}. */
+  timeoutMs?: number;
+  /** Spawn override — the spec uses it to drive the protocol without a real thread. */
+  spawn?: (entry: string | URL) => HostWorker;
+}
+
+function spawnHostWorker(entry: string | URL): HostWorker {
+  // 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: ((data: unknown) => void) | null = null;
+  let markSettled: () => void = () => undefined;
+  const settled = new Promise<void>((resolve) => {
+    markSettled = resolve;
+  });
+  let terminated = false;
+  const messageHandlers: ((data: unknown) => void)[] = [];
+  const errorHandlers: ((error: unknown) => void)[] = [];
+  let terminateReal: (() => void) | null = null;
+
+  void (async () => {
+    try {
+      const { Worker } = await import('node:worker_threads');
+      if (terminated) return;
+      const worker = new Worker(entry as string | URL);
+      worker.on('message', (data: unknown) => {
+        for (const handler of messageHandlers) handler(data);
+      });
+      worker.on('error', (error: unknown) => {
+        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: number) => {
+        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: KdfWorkerOptions): PasswordVerifierPort {
+  const timeoutMs = options.timeoutMs ?? KDF_WORKER_DEFAULT_TIMEOUT_MS;
+  const worker = (options.spawn ?? spawnHostWorker)(options.entry);
+
+  interface Pending {
+    resolve(value: string | boolean): void;
+    reject(error: unknown): void;
+    timer: ReturnType<typeof setTimeout>;
+  }
+  const pending = new Map<number, Pending>();
+  let nextId = 1;
+  let disposed = false;
+
+  const settle = (id: number, apply: (p: Pending) => void): void => {
+    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: string, code: string, status: number): AppError =>
+    new AppError(message, { code, status, category: 'security', context: { worker: String(options.entry) } });
+
+  worker.onMessage((data) => {
+    const response = data as KdfWorkerResponse;
+    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: (id: number) => KdfWorkerRequest, password: Uint8Array): Promise<string | boolean> => {
+    if (disposed) throw failure('The KDF worker has been disposed.', GUARD_KDF_WORKER_FAILED, 500);
+    const id = nextId++;
+    const answer = new Promise<string | boolean>((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 = (): URL => new URL('./kdfWorkerEntry.ts', import.meta.url);
+
+/** Re-exported so a host wiring the guard tier needs one import. */
+export { createInProcessPasswordVerifier, type PasswordVerifierPort };

package/src/server/guard/kdfWorkerEntry.ts

@@ -0,0 +1,16 @@
+/**
+ * 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/src/server/guard/passwordVerifier.spec.ts

@@ -0,0 +1,71 @@
+/**
+ * Password verifiers over the ONE KDF (02 §2).
+ *
+ * Proves the verifier IS a `SecretEnvelope`: a right password opens it, a wrong
+ * one fails GCM authentication (→ `false`, not a throw), the envelope is bound to
+ * its user (a lifted envelope is refused), a malformed row is corruption (throws),
+ * and every entry point CONSUMES the password buffer (byte custody, 01 §3.4).
+ */
+import { describe, expect, it } from 'bun:test';
+import type { Argon2idDeriver } from 'cwip/guard';
+import { sealPasswordVerifier, verifyPasswordEnvelope } from './passwordVerifier';
+
+// A deterministic, PASSWORD-SENSITIVE stand-in for argon2id (the real seam mixes
+// far more): the output must depend on the password, or a "wrong password" would
+// derive the same key and the verifier would be meaningless.
+const stubDeriver: Argon2idDeriver = ({ password, salt, keyLength }) => {
+  const out = new Uint8Array(keyLength);
+  for (let i = 0; i < keyLength; i += 1)
+    out[i] = ((password[i % password.length] ?? 0) ^ (salt[i % salt.length] ?? 0) ^ (i & 0xff)) & 0xff;
+  return out;
+};
+
+const bytes = (value: string): Uint8Array => new TextEncoder().encode(value);
+const allZero = (buffer: Uint8Array): boolean => buffer.every((b) => b === 0);
+
+describe('passwordVerifier', () => {
+  it('round-trips: the sealed password verifies', () => {
+    const envelope = sealPasswordVerifier('u_ann', bytes('correct horse battery'), stubDeriver);
+    expect(verifyPasswordEnvelope('u_ann', envelope, bytes('correct horse battery'), stubDeriver)).toBe(true);
+  });
+
+  it('rejects a wrong password with false (not a throw)', () => {
+    const envelope = sealPasswordVerifier('u_ann', bytes('correct horse battery'), stubDeriver);
+    expect(verifyPasswordEnvelope('u_ann', envelope, bytes('wrong password here!!'), stubDeriver)).toBe(false);
+  });
+
+  it('is bound to its user — a lifted envelope is refused, not silently accepted', () => {
+    const envelope = sealPasswordVerifier('u_ann', bytes('shared-secret-value'), stubDeriver);
+    // Same password, wrong user id: the AAD (`cc-pw:u_ann`) no longer matches, so
+    // the envelope refuses rather than authenticating u_eve with u_ann's verifier.
+    expect(() => verifyPasswordEnvelope('u_eve', envelope, bytes('shared-secret-value'), stubDeriver)).toThrow(
+      /bound to|relocated|SecretEnvelope/i,
+    );
+  });
+
+  it('two users with the same password get different envelopes (fresh per-user salt)', () => {
+    const a = sealPasswordVerifier('u_a', bytes('identical-pw'), stubDeriver);
+    const b = sealPasswordVerifier('u_b', bytes('identical-pw'), stubDeriver);
+    expect(a).not.toEqual(b);
+  });
+
+  it('throws on a malformed stored envelope (corruption, never "wrong password")', () => {
+    expect(() => verifyPasswordEnvelope('u_ann', '{"not":"an envelope"}', bytes('pw'), stubDeriver)).toThrow();
+  });
+
+  it('CONSUMES the password buffer on seal, on a correct verify, and on a wrong verify', () => {
+    const p1 = bytes('to-be-sealed-pw');
+    sealPasswordVerifier('u_ann', p1, stubDeriver);
+    expect(allZero(p1)).toBe(true);
+
+    const envelope = sealPasswordVerifier('u_ann', bytes('to-be-sealed-pw'), stubDeriver);
+
+    const p2 = bytes('to-be-sealed-pw');
+    verifyPasswordEnvelope('u_ann', envelope, p2, stubDeriver);
+    expect(allZero(p2)).toBe(true);
+
+    const p3 = bytes('the-wrong-password');
+    verifyPasswordEnvelope('u_ann', envelope, p3, stubDeriver);
+    expect(allZero(p3)).toBe(true);
+  });
+});

package/src/server/guard/passwordVerifier.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 {
+  type Argon2idDeriver,
+  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: string): { appId: string; key: string } => ({ 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: string, password: Uint8Array, deriver?: Argon2idDeriver): string {
+  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: string,
+  envelopeJson: string,
+  password: Uint8Array,
+  deriver?: Argon2idDeriver,
+): boolean {
+  let envelope: ReturnType<typeof parseSecretEnvelope>;
+  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: Uint8Array | null = 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 port */
+
+/**
+ * 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 function createInProcessPasswordVerifier(deriver?: Argon2idDeriver): PasswordVerifierPort {
+  return {
+    async seal(userId, password) {
+      return sealPasswordVerifier(userId, password, deriver);
+    },
+    async verify(userId, envelopeJson, password) {
+      return verifyPasswordEnvelope(userId, envelopeJson, password, deriver);
+    },
+  };
+}