cursedbelt-server 1.0.0

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

@@ -0,0 +1,390 @@
+/**
+ * The GuardEngine server wiring: the Ed25519 session signer and the argon2id
+ * binding adapter that arms cwip's KDF seam.
+ *
+ * The KDF tests use a FAKE binding on purpose. A real known-answer vector needs
+ * a real argon2id, and cwip ships none by contract (`@node-rs/argon2` is an
+ * optional peer) — so what is testable here is the ADAPTER's contract: that the
+ * envelope's parameters and version reach the binding unchanged, and that a
+ * binding returning a string is refused rather than accepted as key material.
+ * The known-answer test lands with the binding, in the app that installs it.
+ */
+import { generateKeyPairSync } from 'node:crypto';
+import { afterEach, describe, expect, it } from 'bun:test';
+import { deriveArgon2idKey, hasArgon2idDeriver, setArgon2idDeriver } from 'cwip/guard';
+import { ARGON2ID_ALGORITHM, argon2idDeriverFrom, registerArgon2idBinding, type RawArgon2idBinding } from './argon2Binding';
+import { createMemoryAsyncRevocationStore } from './revocationStore';
+import { createSessionSigner } from './sessionSigner';
+
+afterEach(() => {
+  setArgon2idDeriver(null);
+});
+
+/** Records what the adapter passed through, and returns deterministic bytes. */
+const recordingBinding = (): RawArgon2idBinding & { calls: Record<string, unknown>[] } => {
+  const calls: Record<string, unknown>[] = [];
+  return {
+    calls,
+    hashRawSync(password, options) {
+      calls.push({ ...options, passwordLength: password.byteLength });
+      return new Uint8Array(options.outputLen).fill(7);
+    },
+  };
+};
+
+describe('argon2idDeriverFrom', () => {
+  it('passes the envelope’s parameters and version through unchanged', () => {
+    const binding = recordingBinding();
+    const key = deriveArgon2idKey(
+      {
+        password: new Uint8Array([1, 2, 3]),
+        salt: new Uint8Array(16),
+        params: { m: 1024, t: 2, p: 1 },
+        keyLength: 32,
+        version: 0x10,
+        label: 'test',
+      },
+      argon2idDeriverFrom(binding),
+    );
+
+    expect(binding.calls[0]).toMatchObject({
+      memoryCost: 1024,
+      timeCost: 2,
+      parallelism: 1,
+      outputLen: 32,
+      algorithm: ARGON2ID_ALGORITHM,
+      // 0x10 and 0x13 produce DIFFERENT bytes; honoring the envelope's value is
+      // the whole reason the version is recorded per envelope.
+      version: 0x10,
+    });
+    expect(key.byteLength).toBe(32);
+    key.destroy();
+  });
+
+  it('defaults to argon2 v1.3 when the caller pins no version', () => {
+    const binding = recordingBinding();
+    deriveArgon2idKey(
+      { password: new Uint8Array([1]), salt: new Uint8Array(16), params: { m: 8, t: 1, p: 1 }, keyLength: 32, label: 'x' },
+      argon2idDeriverFrom(binding),
+    ).destroy();
+    expect(binding.calls[0]?.version).toBe(0x13);
+  });
+
+  it('refuses a binding that hands back a string', () => {
+    const stringy = {
+      hashRawSync: () => '$argon2id$v=19$m=65536,t=3,p=1$...' as unknown as Uint8Array,
+    } satisfies RawArgon2idBinding;
+
+    expect(() =>
+      deriveArgon2idKey(
+        { password: new Uint8Array([1]), salt: new Uint8Array(16), params: { m: 8, t: 1, p: 1 }, keyLength: 32, label: 'x' },
+        argon2idDeriverFrom(stringy),
+      ),
+    ).toThrow(/raw bytes/);
+  });
+
+  it('registerArgon2idBinding arms the seam and proves it', () => {
+    expect(hasArgon2idDeriver()).toBe(false);
+    registerArgon2idBinding(recordingBinding());
+    expect(hasArgon2idDeriver()).toBe(true);
+  });
+});
+
+describe('createSessionSigner', () => {
+  const identity = {
+    tenantId: 't_a',
+    userId: 'u_1',
+    role: 'OWNER' as const,
+    permissions: ['infra:write'],
+    privateScope: true,
+  };
+
+  it('mints a token its own verifier accepts', () => {
+    const signer = createSessionSigner();
+    const { token, claims } = signer.mint(identity);
+
+    const result = signer.verify(token);
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.claims.jti).toBe(claims.jti);
+  });
+
+  it('rejects a token signed by a different key', () => {
+    const a = createSessionSigner();
+    const b = createSessionSigner();
+    const { token } = a.mint(identity);
+
+    expect(b.verify(token)).toMatchObject({ ok: false, failure: 'invalid-signature' });
+  });
+
+  it('rejects a tampered payload', () => {
+    const signer = createSessionSigner();
+    const { token } = signer.mint({ ...identity, permissions: [] });
+    const [, signature] = token.split('.');
+    const forged = Buffer.from(JSON.stringify({ ...identity, exp: 9_999_999_999, jti: 'x' })).toString('base64url');
+
+    expect(signer.verify(`${forged}.${signature}`)).toMatchObject({ ok: false, failure: 'invalid-signature' });
+  });
+
+  it('reports missing and malformed tokens distinctly', () => {
+    const signer = createSessionSigner();
+    expect(signer.verify(undefined)).toMatchObject({ failure: 'missing' });
+    expect(signer.verify('no-dot')).toMatchObject({ failure: 'malformed' });
+  });
+
+  it('treats expiry as expiry, whether or not anyone revoked it', () => {
+    let now = 1_000_000_000_000;
+    const signer = createSessionSigner({ ttlSeconds: 60, now: () => now });
+    const { token } = signer.mint(identity);
+
+    now += 61_000;
+    expect(signer.verify(token)).toMatchObject({ ok: false, failure: 'expired' });
+  });
+
+  it('honors a revoked jti until it would have expired, then forgets it', () => {
+    let now = 1_000_000_000_000;
+    const signer = createSessionSigner({ ttlSeconds: 60, now: () => now });
+    const { token, claims } = signer.mint(identity);
+
+    signer.revoke(claims.jti);
+    expect(signer.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+    expect(signer.activeRevocations()).toContain(claims.jti);
+
+    // Past the horizon the entry is pointless — the signature check refuses the
+    // token anyway, so keeping it would be an unbounded leak.
+    now += 121_000;
+    expect(signer.activeRevocations()).toEqual([]);
+  });
+
+  it('records a revocation for a jti it never minted', () => {
+    // Another node in the fleet locked; this process must honor it.
+    const signer = createSessionSigner();
+    signer.revoke('jti_from_elsewhere');
+    expect(signer.isRevoked('jti_from_elsewhere')).toBe(true);
+  });
+
+  it('rejects a token carrying an unknown claim key', () => {
+    const signer = createSessionSigner();
+    const { token } = signer.mint(identity);
+    const [payload, signature] = token.split('.');
+    const decoded = JSON.parse(Buffer.from(payload as string, 'base64url').toString('utf8')) as Record<string, unknown>;
+    decoded.isAdmin = true;
+    const tampered = Buffer.from(JSON.stringify(decoded)).toString('base64url');
+
+    // Signature fails first here, but the `.strict()` parse is the backstop that
+    // stops a version-skewed token from smuggling an unrecognized grant.
+    expect(signer.verify(`${tampered}.${signature}`).ok).toBe(false);
+  });
+
+  it('a public-key-only signer verifies but refuses to mint', () => {
+    const minter = createSessionSigner();
+    const { token } = minter.mint(identity);
+    const verifier = createSessionSigner({ publicKey: minter.publicKeyPem() });
+
+    expect(verifier.verify(token).ok).toBe(true);
+    expect(() => verifier.mint(identity)).toThrow(/only a public key/);
+  });
+});
+
+describe('createSessionSigner — cross-node revocation store (03 §4a)', () => {
+  const identity = {
+    tenantId: 't_a',
+    userId: 'u_1',
+    role: 'OWNER' as const,
+    permissions: ['infra:write'],
+    privateScope: true,
+  };
+
+  it('the two-signer replay: revoke on A, verify refuses on B through the shared store (V7.3)', async () => {
+    // The exact window the consolidation promised closed: node A locks a session,
+    // node B is still serving requests with the same token. One shared store,
+    // two signers over one keypair, in one process.
+    const store = createMemoryAsyncRevocationStore();
+    const pair = generateKeyPairSync('ed25519');
+    const nodeA = createSessionSigner({ privateKey: pair.privateKey, revocationStore: store });
+    const nodeB = createSessionSigner({ publicKey: pair.publicKey, revocationStore: store });
+
+    const { token, claims } = nodeA.mint(identity);
+
+    nodeA.revoke(claims.jti); // the lock lands on A
+    await nodeA.flushRevocations(); // the write reaches the shared store
+
+    // B's very FIRST sight of the now-revoked jti is a cache miss: it answers
+    // from what it can prove locally (a valid signature, not yet known revoked)
+    // and reads the store off the hot path. This one-request window IS the seam's
+    // documented latency, asserted rather than hidden.
+    expect(nodeB.verify(token).ok).toBe(true);
+    await nodeB.flushRevocations(); // the read settles → B has learned it
+
+    // From here B refuses it, and keeps refusing without touching the store again.
+    expect(nodeB.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+    expect(nodeB.isRevoked(claims.jti)).toBe(true);
+  });
+
+  it('revokeUser closes every session it minted for a user, fleet-wide through the store (02 §3)', async () => {
+    // The primitive behind a role change taking effect NOW: routes authorize
+    // from the token's claims, so a demotion that leaves the user's live tokens
+    // alive is a demotion that did not happen. Two devices here, plus a second
+    // node that must learn about both.
+    const store = createMemoryAsyncRevocationStore();
+    const pair = generateKeyPairSync('ed25519');
+    const nodeA = createSessionSigner({ privateKey: pair.privateKey, revocationStore: store });
+    const nodeB = createSessionSigner({ publicKey: pair.publicKey, revocationStore: store });
+
+    const laptop = nodeA.mint(identity);
+    const phone = nodeA.mint(identity);
+    const someoneElse = nodeA.mint({ ...identity, userId: 'u_2' });
+
+    const closed = nodeA.revokeUser('u_1');
+    expect([...closed].sort()).toEqual([laptop.claims.jti, phone.claims.jti].sort());
+    expect(nodeA.verify(laptop.token)).toMatchObject({ ok: false, failure: 'revoked' });
+    expect(nodeA.verify(phone.token)).toMatchObject({ ok: false, failure: 'revoked' });
+    // Another user's session is untouched — this is a per-user revoke, not a purge.
+    expect(nodeA.verify(someoneElse.token).ok).toBe(true);
+
+    // Each revoked jti wrote through, so the other node refuses them too.
+    await nodeA.flushRevocations();
+    nodeB.verify(laptop.token);
+    nodeB.verify(phone.token);
+    await nodeB.flushRevocations();
+    expect(nodeB.verify(laptop.token)).toMatchObject({ ok: false, failure: 'revoked' });
+    expect(nodeB.verify(phone.token)).toMatchObject({ ok: false, failure: 'revoked' });
+
+    // A user with no live session is a no-op, not a throw.
+    expect(nodeA.revokeUser('u_nobody')).toEqual([]);
+  });
+
+  it('sessionsOf lists the live sessions per device, dropping expired and revoked ones (02 §4)', () => {
+    let now = 1_700_000_000_000;
+    const signer = createSessionSigner({ ttlSeconds: 300, now: () => now });
+
+    const laptop = signer.mint(identity, { deviceLabel: 'laptop' });
+    now += 1000;
+    const phone = signer.mint(identity, { deviceLabel: 'phone' });
+    // A label is DISPLAY metadata, never a claim: the signed payload is exactly
+    // the strict claims schema, so a client-supplied string cannot ride inside it.
+    expect(Object.keys(laptop.claims)).not.toContain('deviceLabel');
+    // …and an over-long one is truncated rather than rejected (a login must not
+    // fail because a browser sent a long device string).
+    const verbose = signer.mint({ ...identity, userId: 'u_2' }, { deviceLabel: 'x'.repeat(200) });
+    expect(signer.sessionsOf('u_2')[0]?.deviceLabel).toHaveLength(64);
+    expect(verbose.claims.userId).toBe('u_2');
+
+    // Newest first, and only this user's.
+    expect(signer.sessionsOf('u_1').map((s) => s.deviceLabel)).toEqual(['phone', 'laptop']);
+    expect(signer.sessionsOf('u_1').every((s) => s.tenantId === identity.tenantId)).toBe(true);
+
+    // A revoked session is a dead session — listing it would offer "log this
+    // device out" on a device that is already out.
+    signer.revoke(phone.claims.jti);
+    expect(signer.sessionsOf('u_1').map((s) => s.jti)).toEqual([laptop.claims.jti]);
+
+    // And an expired one drops out on its own.
+    now += 400_000;
+    expect(signer.sessionsOf('u_1')).toEqual([]);
+  });
+
+  it('write-through: a revoke reaches the shared store, refused HERE immediately regardless', async () => {
+    const store = createMemoryAsyncRevocationStore();
+    const signer = createSessionSigner({ revocationStore: store });
+    const { token, claims } = signer.mint(identity);
+
+    signer.revoke(claims.jti);
+    // Local refusal is synchronous — the store write has not even resolved yet.
+    expect(signer.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+
+    await signer.flushRevocations();
+    expect(await store.get(claims.jti)).not.toBeNull();
+  });
+
+  it('bounds cross-node staleness by the cache TTL, then re-reads', async () => {
+    let now = 1_000_000_000_000;
+    const store = createMemoryAsyncRevocationStore();
+    const verifier = createSessionSigner({
+      publicKey: createSessionSigner().publicKeyPem(), // any key — signature isn't the subject here
+      revocationStore: store,
+      revocationCacheTtlMs: 5000,
+      now: () => now,
+    });
+    // A token minted by a matching minter.
+    const minterPair = generateKeyPairSync('ed25519');
+    const minter = createSessionSigner({ privateKey: minterPair.privateKey, now: () => now });
+    const reader = createSessionSigner({
+      publicKey: minterPair.publicKey,
+      revocationStore: store,
+      revocationCacheTtlMs: 5000,
+      now: () => now,
+    });
+    const { token, claims } = minter.mint({ ...identity, exp: Math.floor(now / 1000) + 3600 });
+
+    // First verify populates a "not revoked" cache entry at t0.
+    expect(reader.verify(token).ok).toBe(true);
+    await reader.flushRevocations();
+
+    // A peer revokes directly in the store (as node A would, via its own signer).
+    await store.set(claims.jti, Math.floor(now / 1000) + 3600);
+
+    // WITHIN the TTL the cached "not revoked" verdict still stands — this is the
+    // bounded-staleness window the seam documents, not a bug.
+    now += 4000;
+    expect(reader.verify(token).ok).toBe(true);
+    await reader.flushRevocations();
+    expect(reader.verify(token).ok).toBe(true);
+
+    // PAST the TTL the next verify re-reads the store and picks up the revocation.
+    now += 2000; // total 6s > 5s TTL
+    expect(reader.verify(token).ok).toBe(true); // the triggering verify still answers from stale cache
+    await reader.flushRevocations(); // the re-read settles
+    expect(reader.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+
+    void verifier; // constructed to prove the option shape; the reader is the subject
+  });
+
+  it('prunes the shared store of entries past their exp', async () => {
+    let now = 1_000_000_000_000;
+    const store = createMemoryAsyncRevocationStore();
+    const signer = createSessionSigner({ ttlSeconds: 60, revocationStore: store, now: () => now });
+
+    signer.revoke('jti_short');
+    await signer.flushRevocations();
+    expect(store.size()).toBe(1);
+
+    // Past the horizon, flush prunes the shared store just as the local Map is
+    // pruned — a denylist that only grows is a leak wearing a security hat.
+    now += 121_000;
+    await signer.flushRevocations();
+    expect(store.size()).toBe(0);
+  });
+
+  it('surfaces a failing store write without throwing out of revoke', async () => {
+    const errors: string[] = [];
+    const brokenStore = {
+      async set() {
+        throw new Error('redis down');
+      },
+      async get() {
+        return null;
+      },
+      async prune() {
+        return 0;
+      },
+    };
+    const signer = createSessionSigner({
+      revocationStore: brokenStore,
+      onRevocationStoreError: (op) => errors.push(op),
+    });
+    const { token, claims } = signer.mint(identity);
+
+    // revoke must never throw on the request path — the local Map still refuses.
+    expect(() => signer.revoke(claims.jti)).not.toThrow();
+    expect(signer.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+    await signer.flushRevocations();
+    expect(errors).toContain('set');
+  });
+
+  it('behaves exactly as before when no store is wired (local profile)', () => {
+    const signer = createSessionSigner();
+    const { token, claims } = signer.mint(identity);
+    signer.revoke(claims.jti);
+    expect(signer.verify(token)).toMatchObject({ ok: false, failure: 'revoked' });
+  });
+});

package/src/server/guard/index.ts

@@ -0,0 +1,6 @@
+// The GuardEngine server wiring (02 §4): the argon2id binding adapter that arms
+// cwip's KDF seam, and the Ed25519 session signer that mints and revokes.
+export * from './argon2Binding';
+export * from './verifier';
+export * from './revocationStore';
+export * from './sessionSigner';

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

@@ -0,0 +1,283 @@
+/**
+ * The off-thread KDF path (05 §B6).
+ *
+ * Three things have to be true, and only the first is obvious:
+ *
+ *  1. the worker computes the SAME answer as the in-process path — an envelope
+ *     sealed on one must open on the other, or turning the worker on would lock
+ *     every existing user out;
+ *  2. no key material crosses the thread boundary, and the password does not
+ *     outlive the post on either side;
+ *  3. the failure modes are loud. A worker that dies, hangs, or is disposed
+ *     mid-flight must reject — the alternative is a login that never answers,
+ *     which is indistinguishable from a hung request until the socket times out.
+ *
+ * The protocol cases drive an injected fake worker (no thread, no native argon2)
+ * because they are about plumbing, and paying a 250 ms derivation per case to
+ * test message routing would buy nothing. The interoperability case uses a REAL
+ * OS thread and the REAL binding, because that is the claim that matters and a
+ * fake cannot make it.
+ */
+import { describe, expect, it } from 'bun:test';
+import { setArgon2idDeriver } from 'cwip/guard';
+import {
+  createKdfWorkerPasswordVerifier,
+  GUARD_KDF_WORKER_FAILED,
+  GUARD_KDF_WORKER_TIMEOUT,
+  type KdfWorkerRequest,
+  type KdfWorkerResponse,
+  kdfWorkerEntryUrl,
+  serveKdfWorker,
+} from './kdfWorker';
+import { createInProcessPasswordVerifier, verifyPasswordEnvelope } from './passwordVerifier';
+import { registerNodeRsArgon2id } from './argon2Binding';
+
+const password = (value: string): Uint8Array => new TextEncoder().encode(value);
+
+/**
+ * A fake worker whose behavior the case chooses. `handle` returning `undefined`
+ * models a thread that never answers.
+ */
+const fakeWorker = (handle: (request: KdfWorkerRequest) => KdfWorkerResponse | undefined) => {
+  const messageHandlers: ((data: unknown) => void)[] = [];
+  const errorHandlers: ((error: unknown) => void)[] = [];
+  const seen: KdfWorkerRequest[] = [];
+  return {
+    seen,
+    fail: (error: unknown) => {
+      for (const handler of errorHandlers) handler(error);
+    },
+    /** Push a reply in whatever order the case wants. */
+    deliver: (response: KdfWorkerResponse) => {
+      for (const handler of messageHandlers) handler(response);
+    },
+    spawn: () => ({
+      async post(data: unknown) {
+        const request = data as KdfWorkerRequest;
+        seen.push(request);
+        const response = handle(request);
+        if (response) for (const handler of messageHandlers) handler(response);
+      },
+      onMessage: (handler: (data: unknown) => void) => messageHandlers.push(handler),
+      onError: (handler: (error: unknown) => void) => errorHandlers.push(handler),
+      terminate: () => undefined,
+    }),
+  };
+};
+
+describe('createKdfWorkerPasswordVerifier — the protocol', () => {
+  it('zeroizes the host’s password copy once the thread has it, not when the verdict returns', async () => {
+    // The whole reason `HostWorker.post` is awaitable. The buffer the caller
+    // handed over must be blank by the time this assertion runs, which is while
+    // the derivation would still be in flight on a real thread — that window is
+    // where a heap snapshot or a crash dump would otherwise catch a plaintext
+    // password.
+    const buffer = password('hunter2-hunter2');
+    let observedByWorker: Uint8Array | null = null;
+    const fake = fakeWorker((request) => {
+      observedByWorker = new Uint8Array(request.password);
+      return { id: request.id, ok: true, value: true };
+    });
+
+    const port = createKdfWorkerPasswordVerifier({ entry: 'unused', spawn: fake.spawn });
+    await port.verify('u1', '{}', buffer);
+
+    expect(buffer.every((byte) => byte === 0)).toBe(true);
+    // …and the worker saw the REAL bytes, not the zeroed ones. Without the
+    // awaitable post this assertion is what fails: the queue would have handed
+    // over a buffer the client had already blanked, and every password would
+    // have derived from zeros.
+    expect(observedByWorker).not.toBeNull();
+    expect(new TextDecoder().decode(observedByWorker as unknown as Uint8Array)).toBe('hunter2-hunter2');
+  });
+
+  it('routes each verdict to its own caller when replies arrive OUT OF ORDER', async () => {
+    // One thread serving many logins is the entire point of a long-lived worker,
+    // and derivations do not finish in the order they started. A client that
+    // matched replies by arrival order rather than by id would hand one user's
+    // login the other user's verdict — an authentication bypass, not a mix-up.
+    // So: two requests, replies delivered in reverse, opposite answers.
+    const held: KdfWorkerRequest[] = [];
+    const fake = fakeWorker((request) => {
+      held.push(request);
+      return undefined;
+    });
+    const port = createKdfWorkerPasswordVerifier({ entry: 'unused', spawn: fake.spawn });
+
+    const first = port.verify('right-password', '{}', password('a'));
+    const second = port.verify('wrong-password', '{}', password('b'));
+    await Promise.resolve();
+    expect(held).toHaveLength(2);
+
+    for (const request of [...held].reverse())
+      fake.deliver({ id: request.id, ok: true, value: request.userId === 'right-password' });
+
+    expect(await first).toBe(true);
+    expect(await second).toBe(false);
+  });
+
+  it('rejects every request in flight when the thread dies', async () => {
+    const fake = fakeWorker(() => undefined);
+    const port = createKdfWorkerPasswordVerifier({ entry: 'unused', spawn: fake.spawn });
+
+    const inFlight = port.verify('u1', '{}', password('x'));
+    await Promise.resolve();
+    fake.fail(new Error('worker exited with code 1'));
+
+    await expect(inFlight).rejects.toThrow(/KDF worker failed/);
+  });
+
+  it('times out rather than hanging a login forever', async () => {
+    const port = createKdfWorkerPasswordVerifier({
+      entry: 'unused',
+      timeoutMs: 10,
+      spawn: fakeWorker(() => undefined).spawn,
+    });
+    await expect(port.verify('u1', '{}', password('x'))).rejects.toThrow(/did not answer within 10ms/);
+  });
+
+  it('refuses new work after dispose, and fails what was already in flight', async () => {
+    const port = createKdfWorkerPasswordVerifier({ entry: 'unused', spawn: fakeWorker(() => undefined).spawn });
+    const inFlight = port.verify('u1', '{}', password('x'));
+    await Promise.resolve();
+
+    await port.dispose?.();
+
+    await expect(inFlight).rejects.toThrow(/disposed while a request was in flight/);
+    await expect(port.verify('u1', '{}', password('y'))).rejects.toThrow(/has been disposed/);
+  });
+
+  it('preserves the worker’s own error code instead of flattening it to a thread failure', async () => {
+    // A corrupt stored envelope and a dead thread are different incidents with
+    // different responses; a client that reported both as GUARD_KDF_WORKER_FAILED
+    // would send an operator chasing a worker that is perfectly healthy.
+    const port = createKdfWorkerPasswordVerifier({
+      entry: 'unused',
+      spawn: fakeWorker((request) => ({
+        id: request.id,
+        ok: false,
+        code: 'SECRET_ENVELOPE_MALFORMED',
+        message: 'not an envelope',
+      })).spawn,
+    });
+
+    await expect(port.verify('u1', 'garbage', password('x'))).rejects.toMatchObject({
+      code: 'SECRET_ENVELOPE_MALFORMED',
+    });
+    expect(GUARD_KDF_WORKER_FAILED).toBe('GUARD_KDF_WORKER_FAILED');
+    expect(GUARD_KDF_WORKER_TIMEOUT).toBe('GUARD_KDF_WORKER_TIMEOUT');
+  });
+
+  it('refuses a reply of the wrong shape rather than handing a caller a lie', async () => {
+    // `verify` promising `boolean` and returning a string would be truthy at
+    // every call site in the product — i.e. a universal password accept.
+    const port = createKdfWorkerPasswordVerifier({
+      entry: 'unused',
+      spawn: fakeWorker((request) => ({ id: request.id, ok: true, value: 'yes' })).spawn,
+    });
+    await expect(port.verify('u1', '{}', password('x'))).rejects.toThrow(/non-boolean verdict/);
+  });
+});
+
+describe('serveKdfWorker — the worker loop', () => {
+  /** Drive the loop directly, with a fake scope and a cheap fake KDF. */
+  const driveLoop = async (): Promise<{
+    send: (request: KdfWorkerRequest) => Promise<KdfWorkerResponse>;
+  }> => {
+    let onMessage: ((data: unknown) => void) | null = null;
+    const outbox: KdfWorkerResponse[] = [];
+    await serveKdfWorker({
+      scope: {
+        postMessage: (data) => outbox.push(data as KdfWorkerResponse),
+        onMessage: (handler) => {
+          onMessage = handler;
+        },
+      },
+      // A deterministic stand-in: the loop under test is the message plumbing
+      // and the zeroize, not argon2 itself (which the KAT covers).
+      register: async () => {
+        setArgon2idDeriver(({ password: pw, salt, keyLength }) => {
+          const out = new Uint8Array(keyLength);
+          for (let i = 0; i < keyLength; i += 1) out[i] = ((pw[i % pw.length] ?? 0) ^ (salt[i % salt.length] ?? 0)) & 0xff;
+          return out;
+        });
+      },
+    });
+    return {
+      send: async (request) => {
+        outbox.length = 0;
+        (onMessage as unknown as (data: unknown) => void)(request);
+        return outbox[0] as KdfWorkerResponse;
+      },
+    };
+  };
+
+  it('seals and verifies, and a wrong password is a false rather than a throw', async () => {
+    const loop = await driveLoop();
+
+    const sealed = await loop.send({ id: 1, kind: 'seal', userId: 'u1', password: password('right') });
+    expect(sealed.ok).toBe(true);
+    const envelopeJson = (sealed as { value: string }).value;
+
+    const good = await loop.send({ id: 2, kind: 'verify', userId: 'u1', envelopeJson, password: password('right') });
+    expect(good).toMatchObject({ id: 2, ok: true, value: true });
+
+    const bad = await loop.send({ id: 3, kind: 'verify', userId: 'u1', envelopeJson, password: password('wrong') });
+    expect(bad).toMatchObject({ id: 3, ok: true, value: false });
+
+    setArgon2idDeriver(null);
+  });
+
+  it('zeroizes its own copy of the password even when the verify throws', async () => {
+    const loop = await driveLoop();
+    const buffer = password('secret-value');
+    // A malformed envelope is corruption, not a wrong password: it throws, and
+    // that is precisely the path on which a `finally`-less loop would leave a
+    // plaintext password sitting in worker RAM.
+    const response = await loop.send({ id: 1, kind: 'verify', userId: 'u1', envelopeJson: 'not json', password: buffer });
+    expect(response.ok).toBe(false);
+    expect(buffer.every((byte) => byte === 0)).toBe(true);
+    setArgon2idDeriver(null);
+  });
+
+  it('ignores a message with no request id instead of crashing the thread', async () => {
+    const loop = await driveLoop();
+    const response = await loop.send({ kind: 'verify' } as unknown as KdfWorkerRequest);
+    expect(response).toBeUndefined();
+    setArgon2idDeriver(null);
+  });
+});
+
+describe('the real thread — interoperability with the in-process path', () => {
+  it('opens an envelope the in-process path sealed, and vice versa', async () => {
+    // THE claim that makes this option safe to turn on in production: the worker
+    // is a different thread, not a different KDF. If these two ever disagreed,
+    // enabling the worker would reject every existing user's password and
+    // sealing on it would produce envelopes the local path cannot open.
+    await registerNodeRsArgon2id();
+    const inProcess = createInProcessPasswordVerifier();
+    const worker = createKdfWorkerPasswordVerifier({ entry: kdfWorkerEntryUrl(), timeoutMs: 30_000 });
+
+    try {
+      const sealedHere = await inProcess.seal('u-shared', new TextEncoder().encode('correct horse'));
+      expect(await worker.verify('u-shared', sealedHere, new TextEncoder().encode('correct horse'))).toBe(true);
+      expect(await worker.verify('u-shared', sealedHere, new TextEncoder().encode('wrong horse'))).toBe(false);
+
+      const sealedThere = await worker.seal('u-shared', new TextEncoder().encode('battery staple'));
+      expect(verifyPasswordEnvelope('u-shared', sealedThere, new TextEncoder().encode('battery staple'))).toBe(true);
+
+      // The user binding survives the trip: the envelope the WORKER sealed is
+      // bound to `cc-pw:u-shared` by its AAD, so reading it for another user is
+      // refused outright rather than answered `false`. That distinction is
+      // deliberate upstream — a relocated envelope is tampering, not a wrong
+      // password — and a worker that dropped `userId` on the wire would have
+      // sealed it to the wrong subject with nothing here to notice.
+      expect(() => verifyPasswordEnvelope('u-other', sealedThere, new TextEncoder().encode('battery staple'))).toThrow(
+        /bound to "cc-pw:u-shared"/,
+      );
+    } finally {
+      await worker.dispose?.();
+      setArgon2idDeriver(null);
+    }
+  }, 60_000);
+});