kxco-post-quantum 1.4.0 → 1.4.1

package/BENCHMARKS.md

@@ -0,0 +1,124 @@
+# Performance
+
+Per-algorithm latency and memory, reported as tail latency rather than a mean.
+
+A mean hides the tail, and the tail is what a request budget has to absorb. For
+ML-DSA that distinction is not cosmetic: signing uses rejection sampling, so it
+loops until the candidate signature falls in range, and the slow tail is inherent
+to the algorithm rather than measurement noise. Anyone sizing a timeout from a
+mean will size it wrong.
+
+Reproduce with:
+
+```
+node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/primitives.json
+```
+
+Every parameter set the package can reach is measured, not only the five it wraps
+in its own helpers.
+
+## Signatures
+
+Milliseconds. 100 iterations except where the `n` column says otherwise.
+
+| Algorithm | Operation | n | median | p95 | p99 | ops/s |
+|---|---|---:|---:|---:|---:|---:|
+| ML-DSA-44 | keygen | 100 | 1.695 | 2.847 | 3.317 | 545 |
+| ML-DSA-44 | sign | 100 | 8.880 | 24.104 | 30.193 | 91 |
+| ML-DSA-44 | verify | 100 | 1.554 | 3.000 | 3.650 | 552 |
+| ML-DSA-65 | keygen | 100 | 3.394 | 9.058 | 11.699 | 238 |
+| ML-DSA-65 | sign | 100 | 11.308 | 36.752 | 51.084 | 64 |
+| ML-DSA-65 | verify | 100 | 3.456 | 5.032 | 5.553 | 288 |
+| ML-DSA-87 | keygen | 100 | 5.226 | 8.270 | 9.635 | 194 |
+| ML-DSA-87 | sign | 100 | 13.148 | 33.932 | 42.381 | 62 |
+| ML-DSA-87 | verify | 100 | 4.877 | 11.119 | 21.760 | 167 |
+| SLH-DSA-SHA2-128f | sign | 20 | 151.319 | 194.915 | 205.881 | 7 |
+| SLH-DSA-SHA2-128f | verify | 20 | 6.412 | 10.672 | 30.298 | 121 |
+| SLH-DSA-SHA2-192s | sign | 3 | 6788.860 | 7229.209 | 7229.209 | 0 |
+| SLH-DSA-SHA2-192s | verify | 10 | 4.997 | 62.287 | 62.287 | 89 |
+| SLH-DSA-SHAKE-256f | sign | 5 | 3333.195 | 3786.271 | 3786.271 | 0 |
+| SLH-DSA-SHAKE-256f | verify | 10 | 72.219 | 86.779 | 86.779 | 14 |
+
+**Two numbers to design around.**
+
+**ML-DSA signing has a long tail.** ML-DSA-65 signs in 11 ms at the median and
+51 ms at p99, a factor of 4.5. Rejection sampling means an unlucky signature does
+several more rounds. Size request budgets from p99, not the median.
+
+**SLH-DSA-SHA2-192s signs in about 6.8 seconds.** That is the set `slhDsa` wraps,
+and it is not a per-request operation. It suits infrequent, high-value signatures
+such as firmware or root attestations. Verification is cheap, around 5 ms, so an
+SLH-DSA signature is expensive to make and cheap to check. The `f` variants trade
+signature size for signing speed: SHA2-128f signs in 151 ms.
+
+## Key encapsulation
+
+| Algorithm | Operation | n | median | p95 | p99 | ops/s |
+|---|---|---:|---:|---:|---:|---:|
+| ML-KEM-512 | keygen | 100 | 0.338 | 0.969 | 1.277 | 2222 |
+| ML-KEM-512 | encapsulate | 100 | 0.512 | 1.043 | 1.617 | 1720 |
+| ML-KEM-512 | decapsulate | 100 | 0.845 | 2.133 | 2.561 | 965 |
+| ML-KEM-768 | keygen | 100 | 0.645 | 1.357 | 1.757 | 1344 |
+| ML-KEM-768 | encapsulate | 100 | 0.822 | 2.050 | 5.067 | 971 |
+| ML-KEM-768 | decapsulate | 100 | 1.292 | 2.750 | 4.048 | 674 |
+| ML-KEM-1024 | keygen | 100 | 1.062 | 2.043 | 2.776 | 860 |
+| ML-KEM-1024 | encapsulate | 100 | 1.066 | 1.902 | 10.844 | 641 |
+| ML-KEM-1024 | decapsulate | 100 | 0.917 | 1.813 | 2.169 | 918 |
+
+ML-KEM is sub-millisecond at the median across all three sets. Moving from
+Category 3 to Category 5 costs well under a millisecond per operation, so the
+migration cost of ML-KEM-1024 is its 1568-byte keys and ciphertexts, not its
+speed. See [MIGRATION.md](MIGRATION.md).
+
+## Wrapper overhead
+
+The package helpers derive keys from a master secret through HKDF, which the raw
+primitives do not. That is the only overhead they add:
+
+| Helper | median | raw keygen median | HKDF cost |
+|---|---:|---:|---:|
+| `mlDsa.keypairFromMaster` | 3.945 | 3.394 | ~0.55 ms |
+| `mlKem.keypairFromMaster` | 1.129 | 0.645 | ~0.48 ms |
+
+Signing and verification go straight through, so they carry no wrapper cost
+beyond hex encoding.
+
+## Memory
+
+Heap growth per operation, in bytes, from `process.memoryUsage().heapUsed` across
+a batch:
+
+| Algorithm | keygen | sign or encapsulate |
+|---|---:|---:|
+| ML-KEM-768 | ~11.7 kB | ~13.0 kB |
+| ML-KEM-1024 | ~20.6 kB | ~6.1 kB |
+| ML-DSA-65 | ~12.9 kB | ~21.0 kB |
+| ML-DSA-87 | ~3.3 kB | ~11.4 kB |
+| SLH-DSA-SHA2-128f | ~143 kB | |
+| SLH-DSA-SHA2-192s | ~192 kB | |
+| SLH-DSA-SHAKE-256f | ~864 kB | |
+
+SLH-DSA allocates one to three orders of magnitude more than the lattice schemes,
+which is consistent with building a hypertree per key. The lattice figures are
+tens of kilobytes and are not a constraint at these rates.
+
+**Read these as orders of magnitude, not exact allocations.** Garbage collection
+can run mid-batch, so a figure smaller than a sibling's does not reliably mean
+less allocation. ML-DSA-87 keygen reading lower than ML-DSA-65 is an artefact of
+collection timing, not evidence that the larger parameter set allocates less.
+
+## What these figures are not
+
+- **One machine, one run.** Node v26.1.0 on win32-x64. Absolute numbers move with
+  hardware and runtime; the ratios between operations are the portable part.
+- **Not a cross-vendor comparison.** Nothing here was measured against another
+  implementation, so it says nothing about how this compares to a native or
+  hardware-backed stack. It will be slower than both.
+- **Reduced samples where marked.** SLH-DSA slow variants take 3 to 20 samples
+  rather than 100, because 100 signatures at 6.8 seconds each is not a benchmark,
+  it is an afternoon. Where n is small, p95 and p99 collapse onto the maximum and
+  are reported that way rather than dressed up.
+- **Not a side-channel measurement.** Timing here is throughput, gathered without
+  any attempt to detect secret-dependent variation, and it must not be read as
+  evidence about constant-time behaviour. See [THREAT-MODEL.md](THREAT-MODEL.md),
+  which states plainly that no such property is claimed.

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 1.4.1
+
+Evidence and documentation only. **No `src/` module changed**, no export was
+added or removed, and the dependency set is unchanged, so no call site can
+behave differently than it did on 1.4.0.
+
+**liboqs is now a third interop implementation.** The cross-implementation
+matrix ran against two peers and now runs against three: liboqs 0.16.0 (C),
+Bouncy Castle 1.85.2 (Java) and dilithium-py 1.4.0 / kyber-py 1.2.0 (Python).
+**225 checks passed, 0 failed, 42 not applicable, across 38 rows**, up from
+156/0/10 across 24. The previous figures are reproduced exactly when the new
+peer is excluded, so nothing about the existing evidence moved.
+
+SLH-DSA had one peer and now has two. liboqs runs from a container built from
+source at a tag pinned in `peers-lock.json`, and CI builds it, so the version
+tested is the version named.
+
+A peer that cannot do something now records as not-applicable rather than as a
+disagreement. The 42 not-applicable are itemised in CONFORMANCE.md: ten from our
+own hedged signing, thirty-two from two liboqs API limits.
+
+**AUDIT.md corrections.** The reviewer checklist told anyone doing due diligence
+to fetch an endpoint that returns 500. Verification now goes to Armature L1 over
+public JSON-RPC, with the calldata layout documented and a named article page
+for the other half of the join. Both documented commands were run verbatim
+against production before publishing.
+
+Two false claims in the same file are withdrawn. It said we pin
+`@noble/post-quantum@0.6.1`, "the exact version covered by the maintainer's own
+self-audit"; we ship `0.7.0`, the self-audit covers `0.6.1`, and **the version we
+ship is covered by no audit at all**. It also described the dependency as
+"itself audited", contradicting its own section 1.
+
+**Supply chain.** Each release now publishes its CycloneDX SBOM as a GitHub
+Release asset at `releases/download/<tag>/sbom.cyclonedx.json`, a permanent
+unauthenticated URL. It was previously generated but retained only as an
+expiring Actions artifact, which is not a published SBOM. The dependency policy
+is now stated in SECURITY.md rather than living only in `dependabot.yml`.
+
 ## 1.4.0
 
 Adds the Security Category 5 parameter sets, and publishes conformance and

package/CONFORMANCE.md

@@ -5,7 +5,7 @@ Two claims, each with a harness in this repository that anyone can run:
 1. **This package computes what FIPS 203, 204 and 205 say it should.** Evidenced
    against NIST's own ACVP test vectors.
 2. **Independent implementations can consume what it produces, and it can
-   consume theirs.** Evidenced against Bouncy Castle (Java) and
+   consume theirs.** Evidenced against liboqs (C), Bouncy Castle (Java) and
    dilithium-py / kyber-py (Python), in both directions.
 
 The second claim is the one that matters in deployment and the one that vector
@@ -93,18 +93,26 @@ Peers, both pinned in
 
 | Peer | Implementation | Language | Covers |
 |---|---|---|---|
+| `liboqs` | `liboqs` 0.16.0 with binding 0.16.0, built from source | C | ML-DSA, ML-KEM, SLH-DSA |
 | `bouncycastle` | `org.bouncycastle:bcprov-jdk18on:1.85.2`, SHA-256 pinned | Java | ML-DSA, ML-KEM, SLH-DSA |
 | `python` | `dilithium-py==1.4.0`, `kyber-py==1.2.0` | Python | ML-DSA, ML-KEM |
 
-SLH-DSA is covered by Bouncy Castle only, because no maintained pure-Python
-implementation was available to pin. That is a narrower base than the other two
-families and is stated rather than averaged away.
+SLH-DSA is covered by liboqs and Bouncy Castle, not by the Python pair, because
+no maintained pure-Python implementation was available to pin. That is a
+narrower base than the other two families and is stated rather than averaged
+away.
 
-Neither shares code with this package's backend. Bouncy Castle is a widely
-deployed independent implementation; the Python pair are independent
+None of the three shares code with this package's backend. liboqs is the
+reference C implementation the wider ecosystem tests against; Bouncy Castle is a
+widely deployed independent implementation; the Python pair are independent
 spec-derived implementations.
 
-**Result: 156 checks passed, 0 failed, 10 not applicable, across 24 rows.**
+liboqs needs a C toolchain, so its peer runs in a container built from
+[conformance/interop/peers/liboqs.Dockerfile](conformance/interop/peers/liboqs.Dockerfile)
+rather than requiring every contributor to install one. If the image is absent
+the peer reports unavailable, which is not a failure but is also not evidence.
+
+**Result: 225 checks passed, 0 failed, 42 not applicable, across 38 rows.**
 
 Per row, in both directions:
 
@@ -130,17 +138,40 @@ Each parameter set this package publishes a helper for is run twice: once
 through that helper (`wrapper`) and once through the primitive (`backend`), so
 the evidence covers the published API and not only its dependency.
 
-### The ten not-applicable checks
-
-`bytes` on the five `wrapper` rows, in each of two context modes. This package's
-`sign` is hedged: it draws fresh randomness per signature, which FIPS 204 permits
-and recommends, so its output is deliberately not reproducible. Byte equality is
-asserted on the `backend` rows for the same parameter sets, so determinism is
-still evidenced everywhere it is meaningful. Reasoning is in
-[THREAT-MODEL.md](THREAT-MODEL.md).
-
-The five wrapper rows are the five parameter sets this package publishes helpers
-for: ML-DSA-65, ML-DSA-87, ML-KEM-768, ML-KEM-1024 and SLH-DSA-SHA2-192s.
+### The forty-two not-applicable checks
+
+A check is recorded as not applicable when a peer says it cannot do something,
+never when a peer disagrees with us. A peer that cannot honour a request answers
+`unsupported` and the matrix records N/A; any other error is a failure and is
+counted as one.
+
+**Ten from hedged signing.** This package's `sign` is hedged: it draws fresh
+randomness per signature, which FIPS 204 permits and recommends, so its output is
+deliberately not reproducible. Byte equality is asserted on the `backend` rows
+for the same parameter sets, so determinism is still evidenced everywhere it is
+meaningful. Reasoning is in [THREAT-MODEL.md](THREAT-MODEL.md).
+
+They are the `bytes` check on each signature `wrapper` row, in each of two
+context modes: three such rows against Bouncy Castle (ML-DSA-65, ML-DSA-87,
+SLH-DSA-SHA2-192s) and two against the Python pair, which has no SLH-DSA. The
+KEM wrapper rows carry no `bytes` check, because a KEM produces a fresh
+ciphertext by design and byte equality is not defined for it.
+
+**Thirty-two from two liboqs API limits**, both properties of that library
+rather than of this one:
+
+- `keys` on all fourteen liboqs rows. liboqs exposes no seed-derived keygen, so
+  it cannot rebuild a key from a FIPS 203 / FIPS 204 seed the way the other
+  peers do. It is addressed by encoded secret key instead, which still tests
+  something real: the private key encodings are themselves standardised, so a
+  key of ours that failed to load into liboqs and produce interoperable output
+  would be a genuine defect.
+- `bytes` on all eighteen liboqs signature checks. liboqs signs hedged and
+  exposes no deterministic mode through its Python binding, so byte equality
+  against it is not defined. Bouncy Castle and the Python pair both cover it.
+
+Everything else is exercised against liboqs, in both directions, including FIPS
+204 context strings and both negative controls.
 
 ---
 

package/README.md

@@ -11,10 +11,11 @@ ML-DSA-65 (FIPS 204) and SLH-DSA-SHA2-192s (FIPS 205) signatures, ML-KEM-768 (FI
 
 **Evidence, not adjectives:**
 
-- [CONFORMANCE.md](./CONFORMANCE.md) — NIST ACVP vectors for FIPS 203/204/205, and a cross-implementation interop matrix against Bouncy Castle and two pure-Python implementations. 134 interop checks, both directions, with negative controls. Reproducible: `npm run conformance:acvp`, `npm run conformance:interop`.
-- [THREAT-MODEL.md](./THREAT-MODEL.md) — what this defends against and what it does not. Read the side-channel section before deciding where a signing key lives.
-- [MIGRATION.md](./MIGRATION.md) — moving an RSA or ECDSA system across, and moving between versions of this package.
-- [SECURITY.md](./SECURITY.md) — reporting, and release integrity.
+- [CONFORMANCE.md](./CONFORMANCE.md): NIST ACVP vectors for FIPS 203/204/205 (2,103 tests, 0 failed), and a cross-implementation interop matrix against liboqs, Bouncy Castle and two pure-Python implementations (225 checks, 0 failed, both directions, with negative controls). Reproducible: `npm run conformance:acvp`, `npm run conformance:interop`.
+- [BENCHMARKS.md](./BENCHMARKS.md): per-algorithm latency at p95/p99, plus memory. Two figures worth designing around: ML-DSA signing has a 4.5x tail between median and p99, and SLH-DSA-SHA2-192s signs in about 6.8 seconds.
+- [THREAT-MODEL.md](./THREAT-MODEL.md): what this defends against and what it does not. Read the side-channel section before deciding where a signing key lives.
+- [MIGRATION.md](./MIGRATION.md): moving an RSA or ECDSA system across, and moving between versions of this package.
+- [SECURITY.md](./SECURITY.md): reporting, and release integrity.
 
 ---
 

package/SECURITY.md

@@ -36,6 +36,28 @@ Out of scope (report upstream to https://github.com/paulmillr/noble-post-quantum
 - HMAC-SHA-256
 - HKDF-SHA-512 (RFC 5869)
 
+## Dependency policy
+Both runtime dependencies are pinned to an exact version, never a range:
+`@noble/post-quantum` and `@noble/hashes`. A range would let the code that runs
+the cryptography change without a release of this package, which is not a
+property we are willing to give up for convenience. Every GitHub Action in our
+workflows is pinned by 40-character commit SHA for the same reason.
+
+Updates are proposed, never automatic. Dependabot opens pull requests weekly for
+both npm and GitHub Actions, and Dependabot security updates are enabled at the
+repository level so an advisory does not wait for the Monday run. The
+configuration is in [.github/dependabot.yml](.github/dependabot.yml).
+
+A dependency bump is not merged on the strength of a green test run alone. A
+change to `@noble/post-quantum` is a change to the primitives themselves, so it
+is gated on the full conformance evidence regenerating clean: the NIST ACVP
+vectors and the cross-implementation interoperability matrix, both described in
+[CONFORMANCE.md](CONFORMANCE.md).
+
+Each release publishes a CycloneDX SBOM as a GitHub Release asset, at
+`releases/download/<tag>/sbom.cyclonedx.json`, generated from the tree that was
+actually installed for that build.
+
 ## Disclosure
 We follow coordinated disclosure with a 90-day default window.
 For actively-exploited issues we ship a patch release within 48 hours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s primitives with key fingerprinting. The base layer for all kxco-pq-* packages.",
   "keywords": [
     "post-quantum",
@@ -95,6 +95,7 @@
     "README.md",
     "LICENSE",
     "CONFORMANCE.md",
+    "BENCHMARKS.md",
     "THREAT-MODEL.md",
     "MIGRATION.md",
     "SECURITY.md",
@@ -115,7 +116,8 @@
     "conformance:fetch": "node conformance/fetch-vectors.mjs",
     "conformance:acvp": "node conformance/run-acvp.mjs --json conformance/results/acvp.json",
     "conformance:interop": "node conformance/interop/run-interop.mjs --json conformance/results/interop.json",
-    "sbom": "npm sbom --sbom-format cyclonedx --sbom-type library"
+    "sbom": "npm sbom --sbom-format cyclonedx --sbom-type library",
+    "bench:primitives": "node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/primitives.json"
   },
   "publishConfig": {
     "provenance": true,