cursedbelt-server 1.0.0

package/src/server/errors.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import { ApiError, isApiError, toErrorEnvelope } from './errors';
+
+/** ISO-8601 timestamp check + strip, so the dynamic field doesn't break equality. */
+const withoutTimestamp = (env: ReturnType<typeof toErrorEnvelope>) => {
+  expect(env.error.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/);
+  const { timestamp: _timestamp, ...error } = env.error;
+  return { ...env, error };
+};
+
+describe('ApiError + toErrorEnvelope', () => {
+  test('carries status, message, code, context', () => {
+    const err = new ApiError(422, 'bad input', {
+      code: 'validation_failed',
+      context: { issues: [{ path: 'name', message: 'required' }] },
+    });
+    expect(err.status).toBe(422);
+    expect(err.message).toBe('bad input');
+    expect(err.name).toBe('ApiError');
+    expect(isApiError(err)).toBe(true);
+    expect(err instanceof Error).toBe(true);
+  });
+
+  test('minimal ApiError → rich envelope (name/status/isOperational/timestamp), no undefined keys', () => {
+    expect(withoutTimestamp(toErrorEnvelope(new ApiError(404, 'not found')))).toEqual({
+      success: false,
+      error: { name: 'ApiError', message: 'not found', status: 404, isOperational: true },
+    });
+  });
+
+  test('full ApiError → message + code + context + rich metadata', () => {
+    const env = toErrorEnvelope(
+      new ApiError(422, 'invalid', { code: 'validation_failed', context: { issues: ['x'] } }),
+    );
+    expect(withoutTimestamp(env)).toEqual({
+      success: false,
+      error: {
+        name: 'ApiError',
+        message: 'invalid',
+        code: 'validation_failed',
+        status: 422,
+        context: { issues: ['x'] },
+        isOperational: true,
+      },
+    });
+  });
+
+  test('correlationId, when supplied, rides alongside the error', () => {
+    const env = toErrorEnvelope(new ApiError(404, 'nope'), { correlationId: 'req-1' });
+    expect(env.correlationId).toBe('req-1');
+  });
+
+  test('plain Error / non-error → sanitized generic 500 (internals never leak)', () => {
+    expect(withoutTimestamp(toErrorEnvelope(new Error('boom')))).toEqual({
+      success: false,
+      error: { name: 'Error', message: 'Internal Server Error', status: 500, isOperational: false },
+    });
+    expect(withoutTimestamp(toErrorEnvelope('nope'))).toEqual({
+      success: false,
+      error: { name: 'Error', message: 'Internal Server Error', status: 500, isOperational: false },
+    });
+  });
+
+  test('exposeMessage surfaces a non-AppError message (opt-in)', () => {
+    expect(toErrorEnvelope(new Error('boom'), { exposeMessage: true }).error.message).toBe('boom');
+  });
+
+  test('preserves cause for server-side logging without serializing it', () => {
+    const cause = new Error('root');
+    const err = new ApiError(500, 'wrapped', { cause });
+    expect(err.cause).toBe(cause);
+    const env = toErrorEnvelope(err);
+    expect(env.error.message).toBe('wrapped');
+    expect(JSON.stringify(env)).not.toContain('root');
+  });
+});

package/src/server/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-side re-export of the canonical error primitives, which now live in the
+ * framework-free {@link ../shared/errors} module so cursedshell's plugin-pure layer
+ * can import the SAME `ApiError` + envelope without pulling any server code
+ * (`cursedbelt-core/errors` subpath). Server modules keep importing from `./errors`.
+ */
+export {
+  AppError,
+  type AppErrorSummary,
+  ApiError,
+  type ApiErrorOptions,
+  type ErrorEnvelope,
+  isAppError,
+  isApiError,
+  type ToErrorEnvelopeOptions,
+  toErrorEnvelope,
+  type ValidationIssue,
+  VALIDATION_ERROR_CODE,
+  VALIDATION_STATUS,
+  toValidationIssues,
+  validationEnvelope,
+} from 'cursedbelt-core/errors';

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

@@ -0,0 +1,117 @@
+/**
+ * The argon2id binding adapter, against the REAL native module (02 §2-tail).
+ *
+ * `registerNodeRsArgon2id` existed for a whole arc with no caller and no test —
+ * and it was broken: `@node-rs/argon2`'s `version` option is a NAPI enum
+ * (`V0x10 = 0`, `V0x13 = 1`), not the argon2 version number `0x13` the envelope
+ * records, so every derivation threw `InvalidArg` from the native layer. Nothing
+ * caught it because nothing had ever registered the binding for real. Now the
+ * local host does at boot, so this suite drives the actual module: register,
+ * derive, and check the bytes.
+ *
+ * `@node-rs/argon2` is an OPTIONAL peer of this package (a generated app without
+ * a GuardEngine surface should not carry a native module) and a devDependency
+ * here, which is what lets the shipping path be proven rather than asserted.
+ */
+import { afterEach, describe, expect, it } from 'bun:test';
+import {
+  CC_ARGON2ID_VERSION,
+  deriveArgon2idKey,
+  hasArgon2idDeriver,
+  resolveArgon2idDeriver,
+  setArgon2idDeriver,
+} from 'cwip/guard';
+import { argon2idDeriverFrom, nodeRsArgon2idBinding, type RawArgon2idBinding, registerNodeRsArgon2id } from './argon2Binding';
+
+/** Cheap parameters — this suite proves the WIRING, not the cost calibration. */
+const FAST = { m: 8_192, t: 1, p: 1 };
+const SALT = new Uint8Array(16).fill(7);
+const password = (value: string): Uint8Array => new TextEncoder().encode(value);
+
+// The seam is process-wide; never leak a registration into another suite.
+afterEach(() => setArgon2idDeriver(null));
+
+describe('nodeRsArgon2idBinding — the version-vocabulary translation', () => {
+  const calls: Array<Record<string, unknown>> = [];
+  const spy: RawArgon2idBinding = {
+    hashRawSync(_password, options) {
+      calls.push({ ...options });
+      return new Uint8Array(options.outputLen);
+    },
+  };
+
+  it('maps the argon2 version number the envelope records onto node-rs’s enum', () => {
+    calls.length = 0;
+    const binding = nodeRsArgon2idBinding(spy);
+    binding.hashRawSync(password('x'), { salt: SALT, memoryCost: 8, timeCost: 1, parallelism: 1, outputLen: 32, version: 0x13 });
+    binding.hashRawSync(password('x'), { salt: SALT, memoryCost: 8, timeCost: 1, parallelism: 1, outputLen: 32, version: 0x10 });
+    // 0x13 → 1, 0x10 → 0. Passing 0x13 straight through is the `InvalidArg` bug.
+    expect(calls.map((call) => call.version)).toEqual([1, 0]);
+  });
+
+  it('defaults to the platform version when the caller names none', () => {
+    calls.length = 0;
+    nodeRsArgon2idBinding(spy).hashRawSync(password('x'), {
+      salt: SALT,
+      memoryCost: 8,
+      timeCost: 1,
+      parallelism: 1,
+      outputLen: 32,
+    });
+    expect(CC_ARGON2ID_VERSION).toBe(0x13);
+    expect(calls[0]?.version).toBe(1);
+  });
+
+  it('refuses a version the binding cannot implement instead of silently deriving different bytes', () => {
+    expect(() =>
+      nodeRsArgon2idBinding(spy).hashRawSync(password('x'), {
+        salt: SALT,
+        memoryCost: 8,
+        timeCost: 1,
+        parallelism: 1,
+        outputLen: 32,
+        version: 0x11,
+      }),
+    ).toThrow(/not one @node-rs\/argon2 implements/);
+  });
+});
+
+describe('registerNodeRsArgon2id — the real native binding, end to end', () => {
+  it('arms the process-wide seam and derives raw bytes of the requested length', async () => {
+    expect(hasArgon2idDeriver()).toBe(false);
+    await registerNodeRsArgon2id();
+    expect(hasArgon2idDeriver()).toBe(true);
+
+    // Straight through the SAME entry point every envelope/verifier uses. Before
+    // the version fix this threw `InvalidArg` here, on the first derivation.
+    const key = deriveArgon2idKey({ password: password('correct horse'), salt: SALT, params: FAST, keyLength: 32, label: 'test' });
+    const bytes = key.use((raw) => new Uint8Array(raw));
+    expect(bytes.byteLength).toBe(32);
+    expect(bytes.some((byte) => byte !== 0)).toBe(true);
+    key.destroy();
+  });
+
+  it('is deterministic for the same inputs and diverges on the password, the salt and the version', async () => {
+    await registerNodeRsArgon2id();
+    const deriver = resolveArgon2idDeriver();
+    const hex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex');
+
+    const base = hex(deriver({ password: password('pw-one'), salt: SALT, params: FAST, keyLength: 32, version: 0x13 }));
+    // Re-deriving must reproduce the key, or no sealed envelope could ever be opened.
+    expect(hex(deriver({ password: password('pw-one'), salt: SALT, params: FAST, keyLength: 32, version: 0x13 }))).toBe(base);
+    expect(hex(deriver({ password: password('pw-two'), salt: SALT, params: FAST, keyLength: 32, version: 0x13 }))).not.toBe(base);
+    expect(
+      hex(deriver({ password: password('pw-one'), salt: new Uint8Array(16).fill(9), params: FAST, keyLength: 32, version: 0x13 })),
+    ).not.toBe(base);
+    // The reason the envelope records `ver` at all: 0x10 and 0x13 are different
+    // functions of the same inputs, and this is the proof the binding honors it.
+    expect(hex(deriver({ password: password('pw-one'), salt: SALT, params: FAST, keyLength: 32, version: 0x10 }))).not.toBe(base);
+  });
+
+  it('refuses a binding that hands back a string — key material that cannot be zeroized', () => {
+    const stringy = { hashRawSync: () => 'deadbeef' } as unknown as RawArgon2idBinding;
+    expect(() =>
+      argon2idDeriverFrom(stringy)({ password: password('x'), salt: SALT, params: FAST, keyLength: 32 }),
+    ).toThrow(/must be raw bytes/);
+  });
+});

package/src/server/guard/argon2Binding.ts

@@ -0,0 +1,195 @@
+/**
+ * Wiring a REAL argon2id into the KDF seam (01 §3.3/§3.4, finding 1.2).
+ *
+ * cwip ships no KDF — it is zero-dependency by contract — so
+ * `setArgon2idDeriver` sat inert: nothing registered a binding, and every
+ * `unlock()` would have thrown `GUARD_KDF_UNAVAILABLE` the first time a real
+ * user tried it in production. `assertArgon2idReady()` converts that into a boot
+ * failure; this module is the other half — the adapter that makes registering a
+ * binding a one-liner, and the reason a host has no excuse to hand-roll one.
+ *
+ * The requirements on a binding are not negotiable, and the adapter enforces
+ * them rather than documenting them:
+ *
+ *   * **Raw bytes out.** A binding that returns a PHC/base64 STRING is a
+ *     `key-material-as-string` violation regardless of how strong the KDF is —
+ *     a JS string is immutable and GC-managed, so the key lingers in
+ *     unallocated RAM until the collector happens to overwrite it.
+ *   * **Caller-supplied salt.** Anything that generates its own salt (e.g.
+ *     `Bun.password`) cannot re-derive the key for an existing envelope, so it
+ *     cannot open a secret it sealed yesterday.
+ *   * **Synchronous.** The seam is sync on purpose and its throughput ceiling is
+ *     documented on `Argon2idDeriver`; an async binding would hand back a
+ *     promise AND (usually) a string.
+ */
+import {
+  type Argon2idDeriver,
+  type Argon2idInput,
+  assertArgon2idReady,
+  CC_ARGON2ID_VERSION,
+  setArgon2idDeriver,
+} from 'cwip/guard';
+import { AppError } from '../errors';
+
+/**
+ * The shape of a raw, synchronous argon2id binding, in the REFERENCE
+ * implementation's vocabulary: `algorithm` is the argon2 variant number
+ * (2 = argon2id) and `version` is the argon2 algorithm version as the spec
+ * writes it (`0x10` / `0x13`) — the same number the envelope's `kdf.ver`
+ * records.
+ *
+ * `@node-rs/argon2`'s `hashRawSync` is shape-compatible but NOT
+ * vocabulary-compatible: its `version` is a NAPI enum (`Version.V0x10 = 0`,
+ * `Version.V0x13 = 1`), so handing it `0x13` is an `InvalidArg` throw on every
+ * single derivation. {@link nodeRsArgon2idBinding} is the (tiny) translation,
+ * and {@link registerNodeRsArgon2id} applies it — libsodium's `crypto_pwhash`
+ * needs a comparable shim.
+ */
+export interface RawArgon2idBinding {
+  hashRawSync(
+    password: Uint8Array,
+    options: {
+      salt: Uint8Array;
+      /** Memory cost in KiB. */
+      memoryCost: number;
+      /** Time cost (iterations). */
+      timeCost: number;
+      /** Parallelism (lanes). */
+      parallelism: number;
+      /** Output length in bytes. */
+      outputLen: number;
+      /** argon2 variant: 2 = argon2id. */
+      algorithm?: number;
+      /** argon2 algorithm version (0x10 | 0x13). */
+      version?: number;
+    },
+  ): Uint8Array;
+}
+
+/** argon2id's variant number in the `@node-rs/argon2` / reference-implementation vocabulary. */
+export const ARGON2ID_ALGORITHM = 2;
+
+/**
+ * Build a deriver from a raw binding, checking the two properties that make it
+ * usable as key material. The length check is not paranoia: a binding that
+ * silently truncates would weaken every secret sealed under it, and the failure
+ * would look like nothing at all.
+ */
+export const argon2idDeriverFrom = (binding: RawArgon2idBinding): Argon2idDeriver => {
+  return (input: Argon2idInput): Uint8Array => {
+    const output = binding.hashRawSync(input.password, {
+      salt: input.salt,
+      memoryCost: input.params.m,
+      timeCost: input.params.t,
+      parallelism: input.params.p,
+      outputLen: input.keyLength,
+      algorithm: ARGON2ID_ALGORITHM,
+      // Honor the version the ENVELOPE was sealed with, not the binding's
+      // compile-time default: 0x10 and 0x13 produce different bytes for
+      // identical m/t/p/salt/password, which is why the envelope records it.
+      version: input.version ?? CC_ARGON2ID_VERSION,
+    });
+
+    if (typeof output === 'string')
+      throw new AppError(
+        'The registered argon2id binding returned a string. Key material must be raw bytes — a string cannot be zeroized (01 §3.4).',
+        { code: 'GUARD_KDF_BINDING_INVALID', status: 500, category: 'security', isOperational: false },
+      );
+    if (!(output instanceof Uint8Array))
+      throw new AppError('The registered argon2id binding did not return a Uint8Array.', {
+        code: 'GUARD_KDF_BINDING_INVALID',
+        status: 500,
+        category: 'security',
+        isOperational: false,
+      });
+    return output;
+  };
+};
+
+/**
+ * `@node-rs/argon2`'s `Version` enum, keyed by the argon2 version number the
+ * ENVELOPE records. Held here rather than imported so the adapter never has to
+ * load the optional native module to know how to talk to it.
+ */
+// 0x10 and 0x13 ARE the Argon2 version identifiers: the spec, the reference
+// implementation and every envelope on disk write them in hex. Biome's autofix
+// rewrites them as 16 and 19 — the same map and a worse one, because nobody
+// reading an `$argon2id$v=19$` record would recognise the decimal.
+// biome-ignore lint/complexity/useSimpleNumberKeys: see above — hex IS the spec's spelling
+const NODE_RS_VERSION: Readonly<Record<number, number>> = { 0x10: 0, 0x13: 1 };
+
+/**
+ * Translate a `@node-rs/argon2` module into a {@link RawArgon2idBinding}.
+ *
+ * The whole translation is the `version` field, and skipping it is not a
+ * cosmetic bug: node-rs validates the enum, so an unmapped `0x13` throws
+ * `InvalidArg` from the native layer on EVERY derivation — the first unlock, the
+ * first login, every password verify. That failure is invisible until a host
+ * actually registers this binding, which is exactly what the local host now does
+ * at boot.
+ */
+export const nodeRsArgon2idBinding = (module: RawArgon2idBinding): RawArgon2idBinding => ({
+  hashRawSync(password, options) {
+    const declared = options.version ?? CC_ARGON2ID_VERSION;
+    const mapped = NODE_RS_VERSION[declared];
+    if (mapped === undefined)
+      throw new AppError(
+        `argon2 version 0x${declared.toString(16)} is not one @node-rs/argon2 implements (0x10 or 0x13). The envelope asking for it cannot be opened by this binding — reseal it, or register a binding that supports the version.`,
+        {
+          code: 'GUARD_KDF_BINDING_INVALID',
+          status: 500,
+          category: 'security',
+          isOperational: false,
+          context: { version: declared },
+        },
+      );
+    return module.hashRawSync(password, { ...options, version: mapped });
+  },
+});
+
+/** Register a raw binding as the process-wide deriver, then prove the seam is armed. */
+export const registerArgon2idBinding = (binding: RawArgon2idBinding): void => {
+  setArgon2idDeriver(argon2idDeriverFrom(binding));
+  // Fail here rather than at the first unlock: this call is the whole point.
+  assertArgon2idReady();
+};
+
+/**
+ * Register `@node-rs/argon2` if the host installed it.
+ *
+ * It is an OPTIONAL peer dependency: a generated app with no GuardEngine surface
+ * should not carry a native module, and an app that has one must make the choice
+ * explicitly. The specifier is held in a variable so bundlers and `tsc` do not
+ * try to resolve a package that may not be there.
+ *
+ * @throws {AppError} `GUARD_KDF_BINDING_MISSING` naming the install command —
+ * an unhelpful `ERR_MODULE_NOT_FOUND` at boot is exactly the failure this
+ * module exists to prevent.
+ *
+ * The same indirection that hides the specifier from a bundler hides it from
+ * every static import walker, so the guard's peer map would report
+ * this edge as absent. The pragma is what puts it back.
+ *
+ * @peer @node-rs/argon2
+ */
+export const registerNodeRsArgon2id = async (): Promise<void> => {
+  const specifier = '@node-rs/argon2';
+  let loaded: { hashRawSync?: unknown };
+  try {
+    loaded = (await import(specifier)) as { hashRawSync?: unknown };
+  } catch (cause) {
+    throw new AppError(
+      'GuardEngine needs an argon2id binding and `@node-rs/argon2` is not installed. Run `bun add @node-rs/argon2` in the app, or call registerArgon2idBinding(...) with your own raw, synchronous binding.',
+      { code: 'GUARD_KDF_BINDING_MISSING', status: 500, category: 'security', isOperational: false, cause },
+    );
+  }
+  if (typeof loaded.hashRawSync !== 'function')
+    throw new AppError('`@node-rs/argon2` is installed but exposes no `hashRawSync` — it is too old for the raw-bytes seam.', {
+      code: 'GUARD_KDF_BINDING_INVALID',
+      status: 500,
+      category: 'security',
+      isOperational: false,
+    });
+
+  registerArgon2idBinding(nodeRsArgon2idBinding(loaded as unknown as RawArgon2idBinding));
+};

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

@@ -0,0 +1,250 @@
+/**
+ * argon2id KNOWN-ANSWER TESTS (05 §B6).
+ *
+ * Every other guard suite in this repo injects a FAKE deriver — `guard.spec.ts`
+ * says so in its header — and `argon2Binding.spec.ts` drives the real native
+ * module but only asserts SHAPE properties: right length, non-zero, deterministic,
+ * diverges on password/salt/version. All of that is equally true of a wrong
+ * KDF. Until this file existed, "does the KDF produce a CORRECT key" had zero
+ * evidence anywhere in the monorepo — a binding that computed argon2i, or the
+ * wrong argon2 version, or silently ignored the parallelism lane count would
+ * have passed every gate we had while sealing every envelope in the product with
+ * keys no other argon2 implementation can reproduce.
+ *
+ * That failure mode is not hypothetical and it is not recoverable. Key material
+ * is written into envelopes at rest; by the time an interoperability problem
+ * surfaces, the secrets sealed under the wrong function are the customer's, and
+ * "reseal everything" needs the plaintext we no longer have.
+ *
+ * Two independent kinds of evidence, because each covers the other's blind spot:
+ *
+ *  1. **Reference vectors** (`REFERENCE_VECTORS`) — fixed inputs and fixed
+ *     outputs from the argon2 REFERENCE implementation's own test suite
+ *     (`phc-winner-argon2`, `src/test.c`, the `ARGON2_VERSION_NUMBER = 0x13`
+ *     block). These pin the absolute function: no implementation of ours can
+ *     satisfy them by being self-consistent.
+ *  2. **Cross-implementation agreement** (the last describe) — Bun's built-in
+ *     argon2id against the registered `@node-rs/argon2` binding on the SAME salt
+ *     and parameters. Two unrelated codebases (Zig/C vs Rust) agreeing bit for
+ *     bit is what catches a vector transcription error, which a fixed table
+ *     cannot catch about itself.
+ *
+ * The negative controls matter as much as the positives: argon2**i** and version
+ * **0x10** are wrong answers that are otherwise indistinguishable from right
+ * ones — same length, same determinism, same divergence behavior — so the
+ * vectors assert they produce DIFFERENT bytes. Without those two rows a binding
+ * defaulting to the wrong variant or the wrong version passes this file.
+ *
+ * Everything runs through `deriveArgon2idKey`, the entry point every envelope,
+ * row signature and password verify uses — not against the module directly.
+ * A KAT that bypasses the shipped seam proves the library and not the product.
+ */
+import { afterEach, describe, expect, it } from 'bun:test';
+import { deriveArgon2idKey, resolveArgon2idDeriver, setArgon2idDeriver } from 'cwip/guard';
+import { type Algorithm, hashRawSync, type Version } from '@node-rs/argon2';
+
+import { argon2idDeriverFrom, nodeRsArgon2idBinding, registerNodeRsArgon2id } from './argon2Binding';
+/*
+ * `Algorithm` and `Version` are declared as AMBIENT CONST ENUMS in the binding's
+ * `.d.ts`, and `verbatimModuleSyntax` refuses to read a member off one — the
+ * import that would carry it is erased, so TypeScript cannot prove the object
+ * survives to runtime. It does: napi-rs emits both onto `module.exports`, which
+ * is why these lines have always RUN correctly and only ever failed to compile.
+ *
+ * So the enums come in as TYPES and the ordinals are named here, checked against
+ * the binding below. **The ordinals are NOT the argon2 wire constants** —
+ * `Version.V0x13` is `1`, not `19` — which is exactly the mistake a reader
+ * inlining "0x13" from the member's name would make, and it would quietly
+ * compute a different KDF rather than fail.
+ */
+const ARGON2ID = 2 as Algorithm;
+const ARGON2I = 1 as Algorithm;
+const V0X13 = 1 as Version;
+const V0X10 = 0 as Version;
+
+
+const enc = new TextEncoder();
+const hex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex');
+
+// The seam is process-wide; never leak a registration into another suite.
+afterEach(() => setArgon2idDeriver(null));
+
+/**
+ * argon2id, version 0x13, password `"password"`, salt `"somesalt"`, 32-byte tag —
+ * the reference implementation's own `hashtest(version, t, log2(m), p, …)` rows.
+ *
+ * The `m` column is written as the KiB value the envelope records, which is
+ * `2^log2m` in the reference suite's vocabulary: 2^8 = 256, 2^16 = 65536,
+ * 2^18 = 262144. Getting that exponent↔value translation wrong is precisely the
+ * kind of mistake this table exists to catch, so it is spelled out rather than
+ * computed.
+ */
+const REFERENCE_VECTORS: readonly { m: number; t: number; p: number; tag: string }[] = [
+  { m: 65_536, t: 2, p: 1, tag: '09316115d5cf24ed5a15a31a3ba326e5cf32edc24702987c02b6566f61913cf7' },
+  { m: 262_144, t: 2, p: 1, tag: '78fe1ec91fb3aa5657d72e710854e4c3d9b9198c742f9616c2f085bed95b2e8c' },
+  { m: 256, t: 2, p: 1, tag: '9dfeb910e80bad0311fee20f9c0e2b12c17987b4cac90c2ef54d5b3021c68bfe' },
+  { m: 256, t: 2, p: 2, tag: '6d093c501fd5999645e0ea3bf620d7b8be7fd2db59c20d9fff9539da2bf57037' },
+  { m: 65_536, t: 1, p: 1, tag: 'f6a5adc1ba723dddef9b5ac1d464e180fcd9dffc9d1cbf76cca2fed795d9ca98' },
+  { m: 65_536, t: 4, p: 1, tag: '9025d48e68ef7395cca9079da4c4ec3affb3c8911fe4f86d1a2520856f63172c' },
+];
+
+const PASSWORD = enc.encode('password');
+const SALT = enc.encode('somesalt');
+
+describe('argon2id known-answer vectors — the shipped seam computes argon2id 0x13', () => {
+  for (const { m, t, p, tag } of REFERENCE_VECTORS) {
+    it(`m=${m} t=${t} p=${p} reproduces the reference tag`, async () => {
+      await registerNodeRsArgon2id();
+
+      // Through `deriveArgon2idKey`, so the KAT covers the parameter validation,
+      // the version default and the length check as well as the primitive.
+      const key = deriveArgon2idKey({
+        password: PASSWORD,
+        salt: SALT,
+        params: { m, t, p },
+        keyLength: 32,
+        label: 'kat',
+      });
+      const derived = key.use((raw) => hex(raw));
+      key.destroy();
+
+      expect(derived).toBe(tag);
+    });
+  }
+
+  it('is NOT argon2i — the variant selector reaches the binding', () => {
+    // Same inputs as the first reference row. argon2i is a real, strong KDF that
+    // fails no shape assertion in `argon2Binding.spec.ts`; only a vector tells
+    // the two apart, and `algorithm: 2` is the single field that decides which
+    // one every envelope in the product is sealed with.
+    const argon2i = hashRawSync(PASSWORD, {
+      salt: SALT,
+      memoryCost: 65_536,
+      timeCost: 2,
+      parallelism: 1,
+      outputLen: 32,
+      algorithm: ARGON2I,
+      version: V0X13,
+    });
+    expect(hex(argon2i)).not.toBe(REFERENCE_VECTORS[0]?.tag);
+  });
+
+  it('is NOT version 0x10 — the envelope’s recorded version reaches the binding', () => {
+    // The whole reason `kdf.ver` is recorded per envelope (see CC_ARGON2ID_VERSION).
+    // 0x10 and 0x13 are different functions of identical inputs, and a binding
+    // that ignored the field would seal secrets no 0x13 reader can open.
+    const v0x10 = hashRawSync(PASSWORD, {
+      salt: SALT,
+      memoryCost: 65_536,
+      timeCost: 2,
+      parallelism: 1,
+      outputLen: 32,
+      algorithm: ARGON2ID,
+      version: V0X10,
+    });
+    expect(hex(v0x10)).not.toBe(REFERENCE_VECTORS[0]?.tag);
+  });
+});
+
+describe('cross-implementation agreement — Bun’s argon2id vs the registered binding', () => {
+  /**
+   * The vectors above are transcribed by a human; this test is not. Bun ships
+   * its own argon2id (a different language, a different codebase, no shared
+   * lineage with the Rust `argon2` crate behind `@node-rs/argon2`), and its PHC
+   * output RECORDS the salt it chose — which is what makes the comparison
+   * possible at all, since `Bun.password` generates its own salt and cannot be
+   * asked to re-derive.
+   *
+   * So: let Bun hash, read back the salt and parameters it used, and drive the
+   * registered binding with them. Two implementations landing on the same 32
+   * bytes is independent of anything either this file or the adapter believes.
+   */
+  const parsePhc = (
+    phc: string,
+  ): { version: number; m: number; t: number; p: number; salt: Uint8Array; tag: Uint8Array } => {
+    const match = /^\$argon2id\$v=(\d+)\$m=(\d+),t=(\d+),p=(\d+)\$([^$]+)\$([^$]+)$/.exec(phc);
+    if (match === null) throw new Error(`Bun produced a PHC string this test cannot parse: ${phc}`);
+    // PHC uses unpadded base64url.
+    const b64 = (value: string): Uint8Array =>
+      new Uint8Array(
+        Buffer.from(value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4), 'base64'),
+      );
+    return {
+      version: Number(match[1]),
+      m: Number(match[2]),
+      t: Number(match[3]),
+      p: Number(match[4]),
+      salt: b64(match[5] as string),
+      tag: b64(match[6] as string),
+    };
+  };
+
+  it('derives byte-identical keys from the same password, salt and parameters', async () => {
+    const phc = await Bun.password.hash('correct horse battery staple', {
+      algorithm: 'argon2id',
+      memoryCost: 2_048,
+      timeCost: 2,
+    });
+    const { version, m, t, p, salt, tag } = parsePhc(phc);
+    // 19 === 0x13. If Bun ever defaults to something else, the comparison below
+    // would be against a different function and must not silently pass.
+    expect(version).toBe(0x13);
+
+    await registerNodeRsArgon2id();
+    const ours = resolveArgon2idDeriver()({
+      password: enc.encode('correct horse battery staple'),
+      salt,
+      params: { m, t, p },
+      keyLength: tag.byteLength,
+      version,
+    });
+
+    expect(hex(ours)).toBe(hex(tag));
+  });
+
+  it('disagrees when the salt differs — proving the agreement above is not vacuous', async () => {
+    // A comparison that passes no matter what is worse than no comparison. If
+    // the binding ignored the salt (or the parser handed it the wrong bytes),
+    // the previous test would still be green; this one would not.
+    const phc = await Bun.password.hash('correct horse battery staple', {
+      algorithm: 'argon2id',
+      memoryCost: 2_048,
+      timeCost: 2,
+    });
+    const { m, t, p, salt, tag } = parsePhc(phc);
+
+    const tampered = new Uint8Array(salt);
+    tampered[0] = (tampered[0] ?? 0) ^ 0xff;
+
+    // Through the same translation the shipping path uses — node-rs's `version`
+    // is a NAPI enum, so a raw `{ hashRawSync }` would throw `InvalidArg`.
+    const deriver = argon2idDeriverFrom(nodeRsArgon2idBinding({ hashRawSync }));
+    const ours = deriver({
+      password: enc.encode('correct horse battery staple'),
+      salt: tampered,
+      params: { m, t, p },
+      keyLength: tag.byteLength,
+      version: 0x13,
+    });
+
+    expect(hex(ours)).not.toBe(hex(tag));
+  });
+
+  /*
+   * The ordinals above are inlined because `verbatimModuleSyntax` cannot read a
+   * member off an ambient const enum. That is a copy, and a copy needs a gate: if
+   * a napi-rs regeneration ever renumbers `Algorithm` or `Version`, every KAT
+   * above would keep passing while silently exercising a different variant.
+   * Reading the RUNTIME objects here is what makes the copy safe.
+   */
+  it('the inlined enum ordinals still match the binding', async () => {
+    const binding = (await import('@node-rs/argon2')) as unknown as {
+      Algorithm: Record<string, number>;
+      Version: Record<string, number>;
+    };
+    expect(binding.Algorithm.Argon2id).toBe(ARGON2ID as unknown as number);
+    expect(binding.Algorithm.Argon2i).toBe(ARGON2I as unknown as number);
+    expect(binding.Version.V0x13).toBe(V0X13 as unknown as number);
+    expect(binding.Version.V0x10).toBe(V0X10 as unknown as number);
+  });
+});