@quantakrypto/sieve 0.1.0

package/README.md

@@ -0,0 +1,227 @@
+# @quantakrypto/sieve
+
+**Conformance battery for ML-KEM (FIPS 203), ML-DSA (FIPS 204), and SLH-DSA
+(FIPS 205) implementations.** Sieve drives *any* implementation through a small
+stdin/stdout JSON protocol and reports where it deviates from the standard.
+
+Zero runtime dependencies — Node built-ins only. Node ≥ 20, ESM.
+
+## What Sieve is (and is not)
+
+Sieve **tests other people's implementations**. It deliberately does **not**
+implement ML-KEM/ML-DSA/SLH-DSA, and it **never fabricates** cryptographic
+Known-Answer-Test values. Its power comes from two honest sources:
+
+1. **Tests that need no external vectors** — self-consistency, structural, and
+   negative/robustness checks that every conforming implementation must pass.
+2. **A loader for official NIST ACVP / KAT vectors you supply** — exact-value
+   checks whose expected bytes come from *your* downloaded NIST files, not from
+   Sieve. See [`vectors/README.md`](./vectors/README.md).
+
+The only hard-coded cryptographic constants in Sieve are the **public,
+standardized parameter sizes** (e.g. ML-KEM-768 public key = 1184 bytes;
+SLH-DSA-SHA2-128f signature = 17088 bytes, FIPS 205 Table 2). Those are not
+secrets and not KAT values.
+
+## Install
+
+Within the `quantakrypto-tools` monorepo it builds with the workspace:
+
+```bash
+npm install
+npm run build            # tsc -b across the workspace
+```
+
+The package exposes a `sieve` bin and a programmatic API.
+
+## How it works
+
+Sieve spawns your implementation (the **SUT**) as a child process and exchanges
+newline-delimited JSON: one request per line in, one response per line out, all
+byte fields base64. Full spec: [`PROTOCOL.md`](./PROTOCOL.md).
+
+```
+sieve  ──request (NDJSON)──▶  your SUT process
+       ◀─response (NDJSON)──  (ML-KEM / ML-DSA)
+```
+
+## Quick start (against the mock)
+
+`examples/mock-sut.ts` is a **non-cryptographic** reference SUT used only to
+exercise the harness. It satisfies the protocol with deterministic, correctly
+sized fake bytes — **it provides no security; never use it for anything real.**
+
+```bash
+# run the full ML-KEM-768 battery against the mock
+node --import tsx src/cli.ts \
+  --impl "node --import tsx examples/mock-sut.ts" \
+  --param ml-kem-768 --iterations 32
+```
+
+After `npm run build` the bin runs directly:
+
+```bash
+sieve --impl "node ./my-impl.js" --param ml-kem-768 --iterations 64 --json
+```
+
+## Pointing Sieve at a REAL implementation
+
+Write a thin **adapter** that speaks the protocol and calls a vetted library.
+The adapter is the SUT; Sieve never bundles a crypto implementation.
+
+Example sketch using a Node binding (e.g. a WASM/native ML-KEM library):
+
+```js
+// my-impl.js  — adapter only; the crypto comes from a vetted dependency.
+import { createInterface } from "node:readline";
+import { mlKem768 } from "some-vetted-pqc-lib";   // <- you choose & audit this
+
+const b64 = (u8) => Buffer.from(u8).toString("base64");
+const un  = (s)  => new Uint8Array(Buffer.from(s, "base64"));
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return;
+  const r = JSON.parse(line);
+  const out = (o) => process.stdout.write(JSON.stringify({ id: r.id, ok: true, ...o }) + "\n");
+  const err = (code, message) => process.stdout.write(JSON.stringify({ id: r.id, ok: false, code, message }) + "\n");
+  try {
+    if (r.op === "keygen")  { const { publicKey, secretKey } = mlKem768.keygen(); return out({ pk: b64(publicKey), sk: b64(secretKey) }); }
+    if (r.op === "encaps")  { const { cipherText, sharedSecret } = mlKem768.encapsulate(un(r.pk)); return out({ ct: b64(cipherText), ss: b64(sharedSecret) }); }
+    if (r.op === "decaps")  { const ss = mlKem768.decapsulate(un(r.ct), un(r.sk)); return out({ ss: b64(ss) }); }
+    return err("unsupported", `op ${r.op}`);
+  } catch (e) { err("error", String(e?.message ?? e)); }
+});
+```
+
+Then:
+
+```bash
+sieve --impl "node ./my-impl.js" --param ml-kem-768
+```
+
+For exact-value KAT, also pass `--vectors <dir>` with official NIST files.
+
+## CLI
+
+```
+sieve --impl "<command...>" --param <set> [options]
+
+  --impl  "<cmd...>"   command Sieve spawns and drives (quote the whole thing)
+  --param <set>        ml-kem-512 | ml-kem-768 | ml-kem-1024 |
+                       ml-dsa-44  | ml-dsa-65  | ml-dsa-87  |
+                       slh-dsa-{sha2,shake}-{128,192,256}{s,f}  (12 sets)
+  --iterations <N>     randomized iterations (default 32)
+  --vectors <dir>      official NIST ACVP vector dir for KAT (else SKIPPED)
+  --timing             include the advisory decaps-timing probe
+  --only <a,b,...>     run only these categories
+  --timeout-ms <N>     per-request timeout (default 10000)
+  --pipeline-depth <N> max concurrent in-flight requests for independent-iteration
+                       categories (default 16; 1 = strictly serial)
+  --inherit-env        pass the FULL parent env to the SUT (DANGEROUS; see below)
+  --json               machine-readable report
+
+exit: 0 = PASS, 1 = FAIL, 2 = usage error
+```
+
+## Programmatic API
+
+```ts
+import { runSieve, formatHuman } from "@quantakrypto/sieve";
+
+const report = await runSieve({
+  command: ["node", "./my-impl.js"],
+  param: "ml-kem-768",
+  iterations: 64,
+  // vectorsDir: "./vectors/ml-kem-768",
+});
+console.log(formatHuman(report));
+process.exit(report.overall === "PASS" ? 0 : 1);
+```
+
+## Category catalog
+
+| Category             | Family  | Bug class | What it checks |
+|----------------------|---------|-----------|----------------|
+| `correctness`        | ML-KEM  | —         | keygen→encaps(pk)→decaps(sk,ct) ⇒ `ss_encaps === ss_decaps` over N iterations. |
+| `determinism`        | ML-KEM  | —         | repeated `decaps(sk, ct)` returns identical `ss`. |
+| `implicit-rejection` | ML-KEM  | **AF-02** | `decaps` of a corrupted ct returns a valid-length `ss` with **no error/crash**, is deterministic, and differs from the honest `ss`. No exact-value assertions. |
+| `sizes`              | ML-KEM  | **AF-05** | emitted pk/sk/ct/ss lengths match the set; wrong-length pk/ct/sk are rejected with a defined error; **FIPS 203 §7.2 ek modulus-range check** — a correctly-sized-but-out-of-range encapsulation key (`t̂` coefficient ≥ q) is rejected. |
+| `robustness`         | ML-KEM  | AF-05     | empty / non-base64 / oversized inputs ⇒ defined error, never crash/silent-accept. |
+| `dsa`                | ML-DSA  | AF-05     | sign→verify ⇒ true; tampered message/signature ⇒ false; wrong message ⇒ false; pk/sk/sig sizes for ml-dsa-44/65/87; wrong-length verify input rejected; **deterministic-vs-hedged signing advisory** (surfaced, never fails). |
+| `slh-dsa`            | SLH-DSA | AF-05     | same self-consistency surface as `dsa` for the 12 FIPS 205 parameter sets: sign→verify, tamper checks, pk/sk/sig sizes, signing-mode advisory, wrong-length verify rejection. |
+| `kat`                | all     | —         | **SKIPPED** unless `--vectors <dir>` of official ACVP files is given; then checks decaps/seeded-keygen/seeded-encaps/sigVer against those exact expected values. Never fabricated. |
+| `timing`             | ML-KEM  | (AF-02)   | **ADVISORY only.** Coarse decaps timing for valid vs. invalid ct. Reports a signal but never changes the verdict — cross-process timing is noisy and not proof of (non-)constant-time behavior. |
+
+The overall verdict is **FAIL** if any non-advisory category fails, else
+**PASS**. A `skip` (e.g. KAT with no vectors) never causes a failure.
+
+## Honest stance on KAT vectors
+
+Sieve ships **no** test vectors. Hard-coding "expected" ciphertext or
+shared-secret bytes would be both a maintenance hazard and a correctness lie if
+ever mistyped. Instead:
+
+- Self-consistency and structural categories give strong coverage with no
+  external data.
+- For exact-value conformance, download the **official NIST ACVP vectors** and
+  pass `--vectors`. The loader (`src/vectors.ts`) parses the standard ACVP JSON.
+
+See [`vectors/README.md`](./vectors/README.md) for sources and the file format.
+
+## Bug classes
+
+- **AF-02** — implicit-rejection / Fujisaki–Okamoto reject-path mistakes
+  (erroring on bad ct, constant/unkeyed reject secrets, non-determinism).
+- **AF-05** — size/format confusion (accepting or emitting wrong-length
+  artifacts, crashing on malformed input, accepting an out-of-range `ek`).
+
+## Security: the SUT runs with a scrubbed environment
+
+The SUT is **code you point Sieve at** — frequently a third-party or candidate
+implementation. Sieve drives it with the harness's own OS privileges, so by
+default Sieve spawns it with a **scrubbed, minimal environment**: only a small
+allow-list (`PATH`, `HOME`, `LANG`, locale/temp vars, plus Windows spawn
+essentials) is copied from the parent process. Harness secrets in the parent env
+— CI tokens, `NPM_TOKEN`, cloud credentials, signing keys — are **not**
+forwarded, so an untrusted SUT cannot read them.
+
+- Pass explicit variables your SUT needs with `env` (programmatic) — these are
+  layered on top of the scrubbed base.
+- Widen the allow-list with `envAllowlist` (copy named parent vars).
+- `--inherit-env` / `inheritEnv: true` restores the **full** parent environment.
+  Use it only for trusted, local implementations you control.
+
+Treat any non-trusted SUT as you would untrusted code generally — sandbox it
+(container / seccomp) if its provenance is unknown.
+
+## Throughput: bounded-concurrency pipelining
+
+The SUT protocol is **id-correlated** (each response echoes its request `id`), so
+independent requests can be in flight at once. Categories whose iterations are
+mutually independent (`correctness`, `determinism`, `dsa`, `slh-dsa`) pipeline up
+to `--pipeline-depth` (default 16) requests against the single SUT process; the
+results are reassembled in request order so the verdict is identical to a serial
+run. Dependent steps within one iteration (e.g. keygen→encaps→decaps for a single
+key) and order-sensitive categories (`timing`) stay strictly serial. Set
+`--pipeline-depth 1` to force the legacy serial behavior.
+
+## Algorithm scope
+
+Sieve drives the three **stateless** NIST PQC schemes: ML-KEM (FIPS 203), ML-DSA
+(FIPS 204), and SLH-DSA (FIPS 205). The 12 standardized SLH-DSA parameter sets
+(`slh-dsa-{sha2,shake}-{128,192,256}{s,f}`) are supported with size and
+self-consistency categories; their public byte sizes come from FIPS 205 Table 2.
+
+**Out of scope: SP 800-208 stateful hash signatures (LMS / XMSS / HSS).** These
+are deliberately *not* supported. Their security depends on **one-time use of
+each leaf key** — the signer must persist and advance secret state across signing
+operations, and reusing state catastrophically breaks the scheme. A stateless,
+request/response conformance harness like Sieve cannot model or verify the
+state-management guarantees that dominate SP 800-208 correctness; doing so safely
+requires a different, state-aware harness with durable per-key state tracking.
+LMS/XMSS are also intended for narrow uses (firmware/boot signing), not the
+general PQC migration Sieve targets.
+
+## License
+
+Apache-2.0.

package/dist/categories/correctness.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Correctness category (ML-KEM).
+ *
+ * The fundamental KEM round-trip: for N independent key pairs,
+ *   keygen -> encaps(pk) -> decaps(sk, ct)
+ * must yield ss_encaps === ss_decaps. This needs no external vectors: it is a
+ * self-consistency property every conforming implementation must satisfy.
+ *
+ * (ML-DSA correctness — sign then verify === true — lives in dsa.ts.)
+ */
+import { type Category } from "./types.js";
+export declare const correctness: Category;
+//# sourceMappingURL=correctness.d.ts.map

package/dist/categories/correctness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correctness.d.ts","sourceRoot":"","sources":["../../src/categories/correctness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,QAAQ,EAAuD,MAAM,YAAY,CAAC;AAkBhG,eAAO,MAAM,WAAW,EAAE,QA6EzB,CAAC"}

package/dist/categories/correctness.js

@@ -0,0 +1,78 @@
+/**
+ * Correctness category (ML-KEM).
+ *
+ * The fundamental KEM round-trip: for N independent key pairs,
+ *   keygen -> encaps(pk) -> decaps(sk, ct)
+ * must yield ss_encaps === ss_decaps. This needs no external vectors: it is a
+ * self-consistency property every conforming implementation must satisfy.
+ *
+ * (ML-DSA correctness — sign then verify === true — lives in dsa.ts.)
+ */
+import { fail, pass, rollUp } from "./types.js";
+import { bytesEqual, kemDecaps, kemEncaps, kemKeygen, mapBounded, requireKem, UnexpectedResponse, } from "./helpers.js";
+import { toB64 } from "../protocol.js";
+export const correctness = async (ctx) => {
+    const checks = [];
+    if (ctx.sizes.family !== "ml-kem") {
+        return {
+            category: "correctness",
+            status: "skip",
+            checks: [],
+            summary: "correctness round-trip is defined for ML-KEM; see DSA category for ML-DSA",
+        };
+    }
+    const km = requireKem(ctx.sizes);
+    const param = km.id;
+    let mismatches = 0;
+    let errored = 0;
+    // Iterations are mutually independent (each builds its own keypair), so run
+    // several chains concurrently bounded by pipelineDepth. The keygen→encaps→
+    // decaps steps WITHIN an iteration stay serial (they are dependent).
+    const outcomes = await mapBounded(ctx.iterations, ctx.pipelineDepth ?? 16, async () => {
+        try {
+            const { pk, sk } = await kemKeygen(ctx.runner, param);
+            const { ct, ss: ssEncaps } = await kemEncaps(ctx.runner, param, toB64(pk));
+            const ssDecaps = await kemDecaps(ctx.runner, param, toB64(sk), toB64(ct));
+            if (!bytesEqual(ssEncaps, ssDecaps)) {
+                return {
+                    kind: "mismatch",
+                    detail: `shared secrets differ: encaps ss != decaps ss ` +
+                        `(encaps=${toB64(ssEncaps).slice(0, 12)}…, decaps=${toB64(ssDecaps).slice(0, 12)}…)`,
+                };
+            }
+            return { kind: "ok" };
+        }
+        catch (err) {
+            const detail = err instanceof UnexpectedResponse
+                ? `SUT returned an unexpected response: ${err.message}`
+                : `harness error: ${err.message}`;
+            return { kind: "error", detail };
+        }
+    });
+    for (let i = 0; i < outcomes.length; i++) {
+        const o = outcomes[i];
+        if (o.kind === "mismatch") {
+            mismatches++;
+            if (mismatches <= 3)
+                checks.push(fail(`roundtrip[${i}]`, o.detail));
+        }
+        else if (o.kind === "error") {
+            errored++;
+            if (errored <= 3)
+                checks.push(fail(`roundtrip[${i}]`, o.detail));
+        }
+    }
+    if (mismatches === 0 && errored === 0) {
+        checks.push(pass("roundtrip", `${ctx.iterations}/${ctx.iterations} keygen→encaps→decaps round-trips produced matching shared secrets`));
+    }
+    const status = rollUp(checks);
+    return {
+        category: "correctness",
+        status,
+        checks,
+        summary: status === "pass"
+            ? `${ctx.iterations} round-trips OK`
+            : `${mismatches} mismatch(es), ${errored} error(s) over ${ctx.iterations} iterations`,
+    };
+};
+//# sourceMappingURL=correctness.js.map

package/dist/categories/correctness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correctness.js","sourceRoot":"","sources":["../../src/categories/correctness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAkD,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,EACV,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAQvC,MAAM,CAAC,MAAM,WAAW,GAAa,KAAK,EAAE,GAAG,EAA2B,EAAE;IAC1E,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO;YACL,QAAQ,EAAE,aAAa;YACvB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,2EAA2E;SACrF,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC;IACpB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,4EAA4E;IAC5E,2EAA2E;IAC3E,qEAAqE;IACrE,MAAM,QAAQ,GAAG,MAAM,UAAU,CAC/B,GAAG,CAAC,UAAU,EACd,GAAG,CAAC,aAAa,IAAI,EAAE,EACvB,KAAK,IAAsB,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACtD,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3E,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1E,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACpC,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,MAAM,EACJ,gDAAgD;wBAChD,WAAW,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI;iBACvF,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GACV,GAAG,YAAY,kBAAkB;gBAC/B,CAAC,CAAC,wCAAwC,GAAG,CAAC,OAAO,EAAE;gBACvD,CAAC,CAAC,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC;YACjD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACnC,CAAC;IACH,CAAC,CACF,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAY,CAAC;QACjC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC1B,UAAU,EAAE,CAAC;YACb,IAAI,UAAU,IAAI,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACtE,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC;YACV,IAAI,OAAO,IAAI,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,IAAI,UAAU,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CACT,IAAI,CACF,WAAW,EACX,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU,oEAAoE,CACxG,CACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO;QACL,QAAQ,EAAE,aAAa;QACvB,MAAM;QACN,MAAM;QACN,OAAO,EACL,MAAM,KAAK,MAAM;YACf,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,iBAAiB;YACpC,CAAC,CAAC,GAAG,UAAU,kBAAkB,OAAO,kBAAkB,GAAG,CAAC,UAAU,aAAa;KAC1F,CAAC;AACJ,CAAC,CAAC"}

package/dist/categories/determinism.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Determinism category (ML-KEM).
+ *
+ * Decapsulation is a deterministic function of (sk, ct): calling decaps twice
+ * with identical inputs must return identical shared secrets. A SUT that mixes
+ * fresh randomness into decaps (a real-world implementation smell) fails here.
+ *
+ * This is a self-consistency property; no external vectors are required.
+ */
+import { type Category } from "./types.js";
+export declare const determinism: Category;
+//# sourceMappingURL=determinism.d.ts.map

package/dist/categories/determinism.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.d.ts","sourceRoot":"","sources":["../../src/categories/determinism.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,QAAQ,EAAuD,MAAM,YAAY,CAAC;AAiBhG,eAAO,MAAM,WAAW,EAAE,QAkFzB,CAAC"}

package/dist/categories/determinism.js

@@ -0,0 +1,78 @@
+/**
+ * Determinism category (ML-KEM).
+ *
+ * Decapsulation is a deterministic function of (sk, ct): calling decaps twice
+ * with identical inputs must return identical shared secrets. A SUT that mixes
+ * fresh randomness into decaps (a real-world implementation smell) fails here.
+ *
+ * This is a self-consistency property; no external vectors are required.
+ */
+import { fail, pass, rollUp } from "./types.js";
+import { bytesEqual, kemDecaps, kemEncaps, kemKeygen, mapBounded, requireKem, UnexpectedResponse, } from "./helpers.js";
+import { toB64 } from "../protocol.js";
+const REPEATS = 3;
+export const determinism = async (ctx) => {
+    const checks = [];
+    if (ctx.sizes.family !== "ml-kem") {
+        return {
+            category: "determinism",
+            status: "skip",
+            checks: [],
+            summary: "decaps-determinism is defined for ML-KEM",
+        };
+    }
+    const param = requireKem(ctx.sizes).id;
+    let nondeterministic = 0;
+    let errored = 0;
+    // Iterations are independent → run concurrently (bounded). The REPEATS decaps
+    // calls within an iteration MUST stay serial: determinism is a property of
+    // repeated identical calls, so we issue them one after another on purpose.
+    const outcomes = await mapBounded(ctx.iterations, ctx.pipelineDepth ?? 16, async () => {
+        try {
+            const { pk, sk } = await kemKeygen(ctx.runner, param);
+            const { ct } = await kemEncaps(ctx.runner, param, toB64(pk));
+            const skB64 = toB64(sk);
+            const ctB64 = toB64(ct);
+            const first = await kemDecaps(ctx.runner, param, skB64, ctB64);
+            for (let r = 1; r < REPEATS; r++) {
+                const again = await kemDecaps(ctx.runner, param, skB64, ctB64);
+                if (!bytesEqual(first, again))
+                    return { kind: "unstable" };
+            }
+            return { kind: "ok" };
+        }
+        catch (err) {
+            const detail = err instanceof UnexpectedResponse
+                ? `SUT returned an unexpected response: ${err.message}`
+                : `harness error: ${err.message}`;
+            return { kind: "error", detail };
+        }
+    });
+    for (let i = 0; i < outcomes.length; i++) {
+        const o = outcomes[i];
+        if (o.kind === "unstable") {
+            nondeterministic++;
+            if (nondeterministic <= 3) {
+                checks.push(fail(`decaps-stable[${i}]`, `decaps(sk, ct) returned different shared secrets across ${REPEATS} identical calls`));
+            }
+        }
+        else if (o.kind === "error") {
+            errored++;
+            if (errored <= 3)
+                checks.push(fail(`decaps-stable[${i}]`, o.detail));
+        }
+    }
+    if (nondeterministic === 0 && errored === 0) {
+        checks.push(pass("decaps-stable", `decaps was deterministic across ${REPEATS} repeats for all ${ctx.iterations} ciphertexts`));
+    }
+    const status = rollUp(checks);
+    return {
+        category: "determinism",
+        status,
+        checks,
+        summary: status === "pass"
+            ? `decaps deterministic over ${ctx.iterations} ciphertexts`
+            : `${nondeterministic} non-deterministic, ${errored} error(s)`,
+    };
+};
+//# sourceMappingURL=determinism.js.map

package/dist/categories/determinism.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.js","sourceRoot":"","sources":["../../src/categories/determinism.ts"],"names":[],"mappings":"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"}

package/dist/categories/dsa.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ML-DSA self-consistency category (FIPS 204).
+ *
+ * Thin binding over the shared signature driver in signature.ts. ML-DSA and
+ * SLH-DSA present the same black-box surface (keygen / sign / verify), so the
+ * driver is shared; this category fixes the family to "ml-dsa". It covers:
+ *   - pk/sk/sig size conformance for ml-dsa-44/65/87,
+ *   - sign→verify correctness round-trips,
+ *   - verify rejects a tampered signature and a wrong message,
+ *   - a deterministic-vs-hedged signing advisory probe,
+ *   - wrong-length verify inputs rejected with a defined error (AF-05).
+ *
+ * Exact-value KAT (sigVer vectors) is handled separately by the kat category.
+ */
+import type { Category } from "./types.js";
+export declare const dsa: Category;
+//# sourceMappingURL=dsa.d.ts.map

package/dist/categories/dsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsa.d.ts","sourceRoot":"","sources":["../../src/categories/dsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,eAAO,MAAM,GAAG,EAAE,QAAiD,CAAC"}

package/dist/categories/dsa.js

@@ -0,0 +1,17 @@
+/**
+ * ML-DSA self-consistency category (FIPS 204).
+ *
+ * Thin binding over the shared signature driver in signature.ts. ML-DSA and
+ * SLH-DSA present the same black-box surface (keygen / sign / verify), so the
+ * driver is shared; this category fixes the family to "ml-dsa". It covers:
+ *   - pk/sk/sig size conformance for ml-dsa-44/65/87,
+ *   - sign→verify correctness round-trips,
+ *   - verify rejects a tampered signature and a wrong message,
+ *   - a deterministic-vs-hedged signing advisory probe,
+ *   - wrong-length verify inputs rejected with a defined error (AF-05).
+ *
+ * Exact-value KAT (sigVer vectors) is handled separately by the kat category.
+ */
+import { makeSignatureCategory } from "./signature.js";
+export const dsa = makeSignatureCategory("dsa", "ml-dsa");
+//# sourceMappingURL=dsa.js.map

package/dist/categories/dsa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsa.js","sourceRoot":"","sources":["../../src/categories/dsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,CAAC,MAAM,GAAG,GAAa,qBAAqB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC"}

package/dist/categories/helpers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Helpers shared by the test categories: typed request wrappers that drive a
+ * Runner, plus small byte utilities. No cryptography — these just move bytes.
+ */
+import { type Response } from "../protocol.js";
+import type { Runner } from "../runner.js";
+import type { KemSizes, ParamSet } from "../sizes.js";
+/** A response we expected to succeed but did not. */
+export declare class UnexpectedResponse extends Error {
+    readonly response: Response;
+    constructor(message: string, response: Response);
+}
+/** ML-KEM keygen, returning decoded pk/sk bytes. Throws on error/wrong shape. */
+export declare function kemKeygen(runner: Runner, param: ParamSet, seed?: string): Promise<{
+    pk: Uint8Array;
+    sk: Uint8Array;
+}>;
+/** ML-KEM encapsulate, returning decoded ct/ss. Throws on error/wrong shape. */
+export declare function kemEncaps(runner: Runner, param: ParamSet, pkB64: string, coins?: string): Promise<{
+    ct: Uint8Array;
+    ss: Uint8Array;
+}>;
+/** ML-KEM decapsulate, returning decoded ss. Throws on error/wrong shape. */
+export declare function kemDecaps(runner: Runner, param: ParamSet, skB64: string, ctB64: string): Promise<Uint8Array>;
+/** Raw decaps that returns the full response (used by categories that expect errors). */
+export declare function kemDecapsRaw(runner: Runner, param: ParamSet, skB64: string, ctB64: string): Promise<Response>;
+/** Raw encaps returning the full response (for error-path tests). */
+export declare function kemEncapsRaw(runner: Runner, param: ParamSet, pkB64: string): Promise<Response>;
+/** Constant-ish byte equality (length then content). Not security-critical. */
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** Base64 of `n` bytes, all zero — a deterministic wrong-but-valid blob. */
+export declare function zerosB64(n: number): string;
+/** Flip one bit in a base64 blob, returning new base64. Used to corrupt ct. */
+export declare function flipBitB64(b64: string, byteIndex?: number, bit?: number): string;
+/** Assert a value is a KEM size record (narrowing). */
+export declare function requireKem(s: {
+    family: string;
+}): KemSizes;
+/**
+ * Run `task(i)` for i in [0, count) with at most `limit` running concurrently,
+ * returning results in index order. Used by categories whose ITERATIONS are
+ * mutually independent (each builds its own keypair), so several iteration
+ * chains can be in flight against the id-correlated SUT at once. Dependent
+ * steps WITHIN a single iteration remain serial inside `task`.
+ *
+ * `limit <= 1` degrades to strictly serial execution. See
+ * docs/audits/performance.md §7.1.
+ */
+export declare function mapBounded<T>(count: number, limit: number, task: (i: number) => Promise<T>): Promise<T[]>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/categories/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/categories/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,qDAAqD;AACrD,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,QAAQ,EAAE,QAAQ;gBADlC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,QAAQ;CAKrC;AAED,iFAAiF;AACjF,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAAC,CAW7C;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAAC,CAY7C;AAED,6EAA6E;AAC7E,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE9F;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAMhE;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,GAAG,SAAI,GAAG,MAAM,CAMtE;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAK1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,EAAE,CAAC,CAyBd"}

package/dist/categories/helpers.js

@@ -0,0 +1,127 @@
+/**
+ * Helpers shared by the test categories: typed request wrappers that drive a
+ * Runner, plus small byte utilities. No cryptography — these just move bytes.
+ */
+import { fromB64 } from "../protocol.js";
+/** A response we expected to succeed but did not. */
+export class UnexpectedResponse extends Error {
+    response;
+    constructor(message, response) {
+        super(message);
+        this.response = response;
+        this.name = "UnexpectedResponse";
+    }
+}
+/** ML-KEM keygen, returning decoded pk/sk bytes. Throws on error/wrong shape. */
+export async function kemKeygen(runner, param, seed) {
+    const resp = await runner.send({
+        family: "ml-kem",
+        param,
+        op: "keygen",
+        ...(seed ? { seed } : {}),
+    });
+    if (resp.ok !== true || !("pk" in resp) || !("sk" in resp)) {
+        throw new UnexpectedResponse("expected keygen pk/sk result", resp);
+    }
+    return { pk: fromB64(resp.pk), sk: fromB64(resp.sk) };
+}
+/** ML-KEM encapsulate, returning decoded ct/ss. Throws on error/wrong shape. */
+export async function kemEncaps(runner, param, pkB64, coins) {
+    const resp = await runner.send({
+        family: "ml-kem",
+        param,
+        op: "encaps",
+        pk: pkB64,
+        ...(coins ? { coins } : {}),
+    });
+    if (resp.ok !== true || !("ct" in resp) || !("ss" in resp)) {
+        throw new UnexpectedResponse("expected encaps ct/ss result", resp);
+    }
+    return { ct: fromB64(resp.ct), ss: fromB64(resp.ss) };
+}
+/** ML-KEM decapsulate, returning decoded ss. Throws on error/wrong shape. */
+export async function kemDecaps(runner, param, skB64, ctB64) {
+    const resp = await runner.send({ family: "ml-kem", param, op: "decaps", sk: skB64, ct: ctB64 });
+    if (resp.ok !== true || !("ss" in resp)) {
+        throw new UnexpectedResponse("expected decaps ss result", resp);
+    }
+    return fromB64(resp.ss);
+}
+/** Raw decaps that returns the full response (used by categories that expect errors). */
+export function kemDecapsRaw(runner, param, skB64, ctB64) {
+    return runner.send({ family: "ml-kem", param, op: "decaps", sk: skB64, ct: ctB64 });
+}
+/** Raw encaps returning the full response (for error-path tests). */
+export function kemEncapsRaw(runner, param, pkB64) {
+    return runner.send({ family: "ml-kem", param, op: "encaps", pk: pkB64 });
+}
+/** Constant-ish byte equality (length then content). Not security-critical. */
+export function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** Base64 of `n` bytes, all zero — a deterministic wrong-but-valid blob. */
+export function zerosB64(n) {
+    return Buffer.alloc(n).toString("base64");
+}
+/** Flip one bit in a base64 blob, returning new base64. Used to corrupt ct. */
+export function flipBitB64(b64, byteIndex = 0, bit = 0) {
+    const buf = Buffer.from(b64, "base64");
+    if (buf.length === 0)
+        return b64;
+    const idx = byteIndex % buf.length;
+    buf[idx] = buf[idx] ^ (1 << (bit & 7));
+    return buf.toString("base64");
+}
+/** Assert a value is a KEM size record (narrowing). */
+export function requireKem(s) {
+    if (s.family !== "ml-kem") {
+        throw new Error(`expected an ML-KEM parameter set, got ${s.family}`);
+    }
+    return s;
+}
+/**
+ * Run `task(i)` for i in [0, count) with at most `limit` running concurrently,
+ * returning results in index order. Used by categories whose ITERATIONS are
+ * mutually independent (each builds its own keypair), so several iteration
+ * chains can be in flight against the id-correlated SUT at once. Dependent
+ * steps WITHIN a single iteration remain serial inside `task`.
+ *
+ * `limit <= 1` degrades to strictly serial execution. See
+ * docs/audits/performance.md §7.1.
+ */
+export async function mapBounded(count, limit, task) {
+    const n = Math.max(0, count);
+    const cap = Math.max(1, Math.floor(limit));
+    const out = new Array(n);
+    let next = 0;
+    let firstError;
+    const worker = async () => {
+        while (firstError === undefined) {
+            const i = next++;
+            if (i >= n)
+                return;
+            try {
+                out[i] = await task(i);
+            }
+            catch (err) {
+                if (firstError === undefined)
+                    firstError = err;
+                return;
+            }
+        }
+    };
+    const workers = [];
+    for (let w = 0; w < Math.min(cap, n); w++)
+        workers.push(worker());
+    await Promise.all(workers);
+    if (firstError !== undefined)
+        throw firstError;
+    return out;
+}
+//# sourceMappingURL=helpers.js.map