kxco-post-quantum 1.4.0 → 1.5.0

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,89 @@
 # Changelog
 
+## 1.5.0
+
+**The FIPS primitives now run in OpenSSL where the runtime has them.** On Node 24
+and later this package uses OpenSSL 3.5 for ML-KEM, ML-DSA and SLH-DSA. On Node
+20 and 22, in browsers, and on any runtime without them, the JavaScript backend
+is used exactly as before.
+
+Additive. No export changed, no signature changed, no key format changed, and
+`@noble/post-quantum` is still a dependency and still the backend on every
+runtime that lacks the native primitives. Nothing is removed.
+
+**Both backends are checked against each other rather than assumed to agree.**
+The interoperability matrix runs in full on both, against liboqs, Bouncy Castle
+and dilithium-py / kyber-py, and both return **225 passed, 0 failed, 42 not
+applicable across 38 rows**. CI runs both legs. Every generated report now
+records which backend produced it under `wrapperBackend`, because a run that
+does not say is not evidence about either one.
+
+Keys and signatures are unchanged on the wire, which is what makes this safe to
+do silently: a signature made by one backend verifies under the other, in both
+directions, for all nine parameter sets. Existing keys keep working. Nothing
+needs migrating.
+
+Measured on the development machine:
+
+| | OpenSSL | JavaScript | |
+|---|---|---|---|
+| ML-DSA-65 sign | 1.34 ms | 11.54 ms | 8.6x |
+| ML-DSA-65 verify | 0.28 ms | 2.22 ms | 7.9x |
+| SLH-DSA-SHA2-192s sign | 1595 ms | 4717 ms | 3.0x |
+
+**A FIPS 204 context string keeps the JavaScript path.** Node's `sign` and
+`verify` take no context argument, and signing without the caller's context
+would produce a signature that verifies against nothing. That is a deliberate
+fallback, not a gap.
+
+**THREAT-MODEL.md is updated, and the change is narrower than it looks.** That
+document argued the timing and cache attacker was out of scope *structurally*,
+because the property cannot be established from inside JavaScript. On the
+OpenSSL path that argument no longer applies. It does not follow that this
+package is constant-time: we have published no timing measurements, and
+OpenSSL's side-channel posture is theirs to state rather than ours to assert.
+The honest position is that the attacker moves from structurally out of scope to
+**unmeasured** on Node 24+, and stays out of scope everywhere else.
+
+## 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,38 @@ 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
+### Which backend the matrix exercised
+
+From 1.5.0 this package has two backends: OpenSSL 3.5 where the runtime provides
+the FIPS primitives (Node 24 and later) and JavaScript everywhere else. They are
+different implementations, so a matrix run against one is not evidence about the
+other. CI therefore runs the whole matrix on **both**, and every generated report
+records which one it used under `wrapperBackend`. A report that does not say is
+not evidence.
+
+Both produce the same result: **225 passed, 0 failed, 42 not applicable**. That
+is the point of running both.
+
+None of the three peers shares code with either of this package's backends. 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 +150,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), run against both backends. 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/THREAT-MODEL.md

@@ -70,8 +70,34 @@ layout, memory placement or cache behaviour; the JIT may specialise a hot path
 on the values flowing through it; the garbage collector may copy secret bytes to
 places the caller cannot reach and cannot clear. Constant-time execution cannot
 be established, let alone maintained across engine versions, from inside the
-language. The backend states this about itself in plain terms: *"There is no
-protection against side-channel attacks."*
+language. The JavaScript backend states this about itself in plain terms:
+*"There is no protection against side-channel attacks."*
+
+**Since 1.5.0 that paragraph no longer describes every deployment, and the
+difference should not be overstated.** On Node 24 and later this package runs
+the FIPS 203/204/205 primitives in OpenSSL 3.5 rather than in JavaScript, so the
+argument above stops applying to the primitive path: the code doing the
+arithmetic is C, compiled ahead of time, outside the JIT and outside the
+collector.
+
+What that does and does not buy:
+
+- It **does** remove the structural impossibility. The reasoning above was that
+  the property could not be established from inside the language at all. On the
+  OpenSSL path it can, in principle, be established.
+- It **does not** amount to a constant-time claim from us. We have published no
+  timing measurements of either backend, and OpenSSL's post-quantum
+  implementations carry their own side-channel posture which is theirs to state,
+  not ours to assert on their behalf.
+- It **does not** apply to Node 20 or 22, to browsers, or to any runtime without
+  those primitives. Those keep the JavaScript backend and everything above
+  applies to them unchanged.
+- It **does not** cover power or electromagnetic analysis on any path.
+
+So the honest position is narrower than "we fixed side channels": the timing and
+cache attacker moves from *structurally out of scope* to *unmeasured* on Node
+24+, and stays out of scope everywhere else. Treat it as unmeasured until
+measurements exist.
 
 Two consequences worth being blunt about:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "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",
@@ -52,6 +52,12 @@
   "sideEffects": false,
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
+  "imports": {
+    "#native": {
+      "node": "./src/_native.node.js",
+      "default": "./src/_native.stub.js"
+    }
+  },
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -95,6 +101,7 @@
     "README.md",
     "LICENSE",
     "CONFORMANCE.md",
+    "BENCHMARKS.md",
     "THREAT-MODEL.md",
     "MIGRATION.md",
     "SECURITY.md",
@@ -115,7 +122,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,

package/src/_native.node.js

@@ -0,0 +1,204 @@
+// OpenSSL-backed primitives, used when the runtime provides them.
+//
+// Node 24 and later expose the FIPS 203/204/205 parameter sets through OpenSSL
+// 3.5. Where that is available this module supplies the primitives and the
+// JavaScript backend is not called; on Node 20 and 22, and on any runtime
+// without them, `native` is null and nothing changes.
+//
+// Why prefer it. The C implementation is the one the wider ecosystem tests
+// against, it carries a constant-time story no JavaScript implementation can
+// make, and it removes the runtime dependency from the signing path entirely on
+// Node 24+. It is also faster by a wide margin, measured on this machine:
+//
+//   ML-DSA-65 sign          1.34 ms   against 11.54 ms   (8.6x)
+//   ML-DSA-65 verify        0.28 ms   against  2.22 ms   (7.9x)
+//   SLH-DSA-SHA2-192s sign  1595 ms   against  4717 ms   (3.0x)
+//
+// The two implementations are interchangeable on the wire, which is checked
+// rather than assumed: the interoperability matrix runs every parameter set
+// against both backends in both directions, and `npm run conformance:interop`
+// reproduces it.
+//
+// Keys cross the boundary in the encodings this package already uses. Private
+// keys go in as PKCS8 carrying the expanded key, or as a JWK for SLH-DSA, whose
+// private key is not seed-derived in OpenSSL's representation. Public keys go in
+// as SPKI wrapping the raw bytes. Every one of those was verified against the
+// JavaScript backend before this module was written; none of it is inferred
+// from the specification.
+
+import crypto from 'node:crypto'
+
+// FIPS 204 section 5.2 context strings are not reachable through Node's sign and
+// verify, which take no context argument. A call that uses one falls back to the
+// JavaScript backend rather than being signed without it: a signature made
+// without the caller's context verifies against nothing and would look like a
+// cross-implementation disagreement rather than a missing feature.
+
+const DER_SEQUENCE = 0x30
+const DER_OCTET_STRING = 0x04
+const DER_BIT_STRING = 0x03
+
+function derLength(length) {
+  if (length < 0x80) return Buffer.from([length])
+  if (length < 0x100) return Buffer.from([0x81, length])
+  return Buffer.from([0x82, length >> 8, length & 0xff])
+}
+
+function der(tag, payload) {
+  return Buffer.concat([Buffer.from([tag]), derLength(payload.length), payload])
+}
+
+// The AlgorithmIdentifier is read back off a key OpenSSL generates itself rather
+// than hard-coded from the OID registry, so a build that spells one differently
+// cannot produce a subtly wrong encoding here.
+function algorithmIdentifier(nodeName) {
+  const { privateKey } = crypto.generateKeyPairSync(nodeName)
+  const pkcs8 = privateKey.export({ format: 'der', type: 'pkcs8' })
+  const headerLength = pkcs8[1] & 0x80 ? 2 + (pkcs8[1] & 0x7f) : 2
+  const start = headerLength + 3 // skip the version INTEGER
+  return pkcs8.subarray(start, start + 2 + pkcs8[start + 1])
+}
+
+function toPkcs8(algid, privateBytes) {
+  const body = Buffer.concat([
+    Buffer.from('020100', 'hex'),
+    algid,
+    der(DER_OCTET_STRING, der(DER_OCTET_STRING, Buffer.from(privateBytes))),
+  ])
+  return der(DER_SEQUENCE, body)
+}
+
+function toSpki(algid, publicBytes) {
+  const bits = der(DER_BIT_STRING, Buffer.concat([Buffer.from([0x00]), Buffer.from(publicBytes)]))
+  return der(DER_SEQUENCE, Buffer.concat([algid, bits]))
+}
+
+const base64url = (bytes) => Buffer.from(bytes).toString('base64url')
+
+// Each entry records how this package's representation maps onto OpenSSL's.
+// `privateForm` is the difference that matters: ML-DSA and ML-KEM accept the
+// expanded private key inside PKCS8, while OpenSSL keys SLH-DSA by its full
+// private key through a JWK.
+const ALGORITHMS = {
+  'ML-DSA-44': { nodeName: 'ml-dsa-44', kind: 'sig', privateForm: 'pkcs8' },
+  'ML-DSA-65': { nodeName: 'ml-dsa-65', kind: 'sig', privateForm: 'pkcs8' },
+  'ML-DSA-87': { nodeName: 'ml-dsa-87', kind: 'sig', privateForm: 'pkcs8' },
+  'ML-KEM-512': { nodeName: 'ml-kem-512', kind: 'kem', privateForm: 'pkcs8' },
+  'ML-KEM-768': { nodeName: 'ml-kem-768', kind: 'kem', privateForm: 'pkcs8' },
+  'ML-KEM-1024': { nodeName: 'ml-kem-1024', kind: 'kem', privateForm: 'pkcs8' },
+  'SLH-DSA-SHA2-128f': { nodeName: 'slh-dsa-sha2-128f', kind: 'sig', privateForm: 'jwk' },
+  'SLH-DSA-SHA2-192s': { nodeName: 'slh-dsa-sha2-192s', kind: 'sig', privateForm: 'jwk' },
+  'SLH-DSA-SHAKE-256f': { nodeName: 'slh-dsa-shake-256f', kind: 'sig', privateForm: 'jwk' },
+}
+
+// Probed once, by actually generating a key. Asking the Node version would be a
+// guess about which build shipped which OpenSSL; generating a key is the fact.
+function probe() {
+  const table = new Map()
+  for (const [name, spec] of Object.entries(ALGORITHMS)) {
+    try {
+      // jwkAlg is the FIPS name: SLH-DSA goes in as a JWK, which names the
+      // algorithm in the payload rather than in an AlgorithmIdentifier.
+      table.set(name, { ...spec, jwkAlg: name, algid: algorithmIdentifier(spec.nodeName) })
+    } catch {
+      // Not in this build. The JavaScript backend covers it.
+    }
+  }
+  return table
+}
+
+const SUPPORTED = probe()
+
+function privateKeyObject(spec, secretKey, publicKey) {
+  if (spec.privateForm === 'jwk') {
+    // FIPS 205 lays the private key out as SK.seed || SK.prf || PK.seed ||
+    // PK.root, and the public key is PK.seed || PK.root, so the public half is
+    // the back half of the private key. Callers that already hold it pass it;
+    // this package's sign() does not, and recovering it here is exact rather
+    // than a reconstruction.
+    const pub = publicKey ?? secretKey.subarray(secretKey.length / 2)
+    return crypto.createPrivateKey({
+      key: {
+        kty: 'AKP',
+        alg: spec.jwkAlg,
+        pub: base64url(pub),
+        priv: base64url(secretKey),
+      },
+      format: 'jwk',
+    })
+  }
+  return crypto.createPrivateKey({
+    key: toPkcs8(spec.algid, secretKey),
+    format: 'der',
+    type: 'pkcs8',
+  })
+}
+
+function publicKeyObject(spec, publicKey) {
+  return crypto.createPublicKey({
+    key: toSpki(spec.algid, publicKey),
+    format: 'der',
+    type: 'spki',
+  })
+}
+
+export const native = SUPPORTED.size === 0 ? null : {
+  /** Parameter sets this build can do. Anything else falls through to JS.
+   *
+   * The Buffer check is not defensive padding. This package's browser-mode
+   * tests simulate a browser by removing Buffer from the global scope, and a
+   * real browser resolves `#native` to the stub and never reaches this module
+   * at all. Without this, those tests would exercise the OpenSSL path while
+   * claiming to cover the browser one, which is a false pass rather than a
+   * crash: the very thing the suite exists to catch.
+   */
+  supports(alg) {
+    return typeof Buffer !== 'undefined' && SUPPORTED.has(alg)
+  },
+
+  /** Names of the supported sets, for the conformance report to record. */
+  algorithms() {
+    return [...SUPPORTED.keys()].sort()
+  },
+
+  openssl: process.versions.openssl,
+
+  sign(alg, secretKey, message, publicKey) {
+    const spec = SUPPORTED.get(alg)
+    if (!spec) return null
+    return crypto.sign(null, Buffer.from(message), privateKeyObject(spec, secretKey, publicKey))
+  },
+
+  verify(alg, publicKey, message, signature) {
+    const spec = SUPPORTED.get(alg)
+    if (!spec) return null
+    try {
+      return crypto.verify(
+        null,
+        Buffer.from(message),
+        publicKeyObject(spec, publicKey),
+        Buffer.from(signature)
+      )
+    } catch {
+      // A malformed key or signature is a failed verification, not a crash,
+      // which matches what the JavaScript backend does with the same input.
+      return false
+    }
+  },
+
+  encapsulate(alg, publicKey) {
+    const spec = SUPPORTED.get(alg)
+    if (!spec || spec.kind !== 'kem') return null
+    // Node names these sharedKey and ciphertext; this package has always called
+    // them sharedSecret and cipherText, so the rename happens here rather than
+    // leaking a second vocabulary into the public API.
+    const { sharedKey, ciphertext } = crypto.encapsulate(publicKeyObject(spec, publicKey))
+    return { cipherText: ciphertext, sharedSecret: sharedKey }
+  },
+
+  decapsulate(alg, cipherText, secretKey) {
+    const spec = SUPPORTED.get(alg)
+    if (!spec || spec.kind !== 'kem') return null
+    return crypto.decapsulate(privateKeyObject(spec, secretKey), Buffer.from(cipherText))
+  },
+}

package/src/_native.stub.js

@@ -0,0 +1,13 @@
+// Non-Node backend selector.
+//
+// Resolved by the "#native" subpath import in package.json for every runtime
+// that is not Node: browsers, Deno's browser-ish targets, bundlers. There is no
+// OpenSSL to reach for there, so the wrapper uses its JavaScript backend and
+// nothing about its behaviour changes.
+//
+// Keeping this as a separate file rather than a runtime check is deliberate: a
+// bundler that saw `import('node:crypto')` anywhere in the graph would either
+// fail to resolve it or ship a polyfill, and this package is documented as
+// working unmodified in a browser.
+
+export const native = null

package/src/ml-dsa-87.js

@@ -31,6 +31,7 @@
 import { ml_dsa87 } from '@noble/post-quantum/ml-dsa.js'
 import { deriveSeed } from './derive.js'
 import { normalizeContext, MAX_CONTEXT_BYTES } from './_context.js'
+import { native } from '#native'
 
 export { MAX_CONTEXT_BYTES }
 
@@ -57,6 +58,15 @@ function wrap(bytes) {
   return HAS_BUFFER ? Buffer.from(bytes) : bytes
 }
 
+// Where the runtime provides the FIPS primitives through OpenSSL (Node 24 and
+// later) they are used in place of the JavaScript backend. Everywhere else,
+// including every browser, `native` is null and nothing about this module
+// changes. The two backends are checked against each other for this parameter
+// set in both directions by the interoperability matrix.
+const NATIVE_ALG = 'ML-DSA-87'
+const usesNative = (context) =>
+  context === undefined && native !== null && native.supports(NATIVE_ALG)
+
 /**
  * Generate an ML-DSA-87 keypair from a master + domain-separation info.
  *
@@ -88,6 +98,9 @@ export function keypairFromMaster(master, info = 'ml-dsa-87-v1') {
  */
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
+  if (usesNative(context)) {
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+  }
   const sig = context === undefined
     ? ml_dsa87.sign(toBytes(message), secretKey)
     : ml_dsa87.sign(toBytes(message), secretKey, { context })
@@ -116,6 +129,9 @@ export function verify(publicKey, message, sigHex, opts) {
   // Outside the try: misuse must surface, not be swallowed as "invalid".
   const context = normalizeContext(opts)
   try {
+    if (usesNative(context)) {
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+    }
     return context === undefined
       ? ml_dsa87.verify(hexToBytes(sigHex), toBytes(message), publicKey)
       : ml_dsa87.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })

package/src/ml-dsa.js

@@ -9,9 +9,24 @@
 import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js'
 import { deriveSeed } from './derive.js'
 import { normalizeContext, MAX_CONTEXT_BYTES } from './_context.js'
+import { native } from '#native'
 
 export { MAX_CONTEXT_BYTES }
 
+// Where the runtime provides the FIPS 204 primitives through OpenSSL (Node 24
+// and later) they are used in place of the JavaScript backend. Everywhere else,
+// including every browser, `native` is null and nothing about this module
+// changes. The two backends are checked against each other for every parameter
+// set in both directions by the interoperability matrix, so this is a swap
+// between two implementations known to agree, not an assumption that they do.
+//
+// A context string forces the JavaScript path: Node's sign and verify take no
+// context argument, and signing without the caller's context would produce a
+// signature that verifies against nothing.
+const NATIVE_ALG = 'ML-DSA-65'
+const usesNative = (context) =>
+  context === undefined && native !== null && native.supports(NATIVE_ALG)
+
 const HAS_BUFFER = typeof Buffer !== 'undefined'
 const enc = new TextEncoder()
 
@@ -64,6 +79,9 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
  */
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
+  if (usesNative(context)) {
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+  }
   const sig = context === undefined
     ? ml_dsa65.sign(toBytes(message), secretKey)
     : ml_dsa65.sign(toBytes(message), secretKey, { context })
@@ -91,6 +109,9 @@ export function verify(publicKey, message, sigHex, opts) {
   // Outside the try: misuse must surface, not be swallowed as "invalid".
   const context = normalizeContext(opts)
   try {
+    if (usesNative(context)) {
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+    }
     return context === undefined
       ? ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
       : ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })

package/src/ml-kem-1024.js

@@ -31,6 +31,7 @@
 
 import { ml_kem1024 } from '@noble/post-quantum/ml-kem.js'
 import { deriveSeed } from './derive.js'
+import { native } from '#native'
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'
 
@@ -38,6 +39,15 @@ function wrap(bytes) {
   return HAS_BUFFER ? Buffer.from(bytes) : bytes
 }
 
+// Where the runtime provides the FIPS primitives through OpenSSL (Node 24 and
+// later) they are used in place of the JavaScript backend. Everywhere else,
+// including every browser, `native` is null and nothing about this module
+// changes. The two backends are checked against each other for this parameter
+// set in both directions by the interoperability matrix.
+const NATIVE_ALG = 'ML-KEM-1024'
+const usesNative = () =>
+  native !== null && native.supports(NATIVE_ALG)
+
 /**
  * Generate an ML-KEM-1024 keypair from a master + domain-separation info.
  *
@@ -63,7 +73,9 @@ export function keypairFromMaster(master, info = 'ml-kem-1024-v1') {
  * @returns {{ ciphertext: Buffer|Uint8Array, cipherText: Buffer|Uint8Array, sharedSecret: Buffer|Uint8Array }}
  */
 export function encapsulate(publicKey) {
-  const r = ml_kem1024.encapsulate(publicKey)
+  const r = usesNative()
+    ? native.encapsulate(NATIVE_ALG, publicKey)
+    : ml_kem1024.encapsulate(publicKey)
   const ct = wrap(r.cipherText ?? r.ciphertext)
   return {
     ciphertext:   ct,
@@ -84,6 +96,9 @@ export function encapsulate(publicKey) {
  * @returns {Buffer|Uint8Array} shared secret (32 bytes)
  */
 export function decapsulate(ciphertext, secretKey) {
+  if (usesNative()) {
+    return wrap(native.decapsulate(NATIVE_ALG, ciphertext, secretKey))
+  }
   return wrap(ml_kem1024.decapsulate(ciphertext, secretKey))
 }
 

package/src/ml-kem.js

@@ -9,6 +9,7 @@
 
 import { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
 import { deriveSeed } from './derive.js'
+import { native } from '#native'
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'
 
@@ -16,6 +17,15 @@ function wrap(bytes) {
   return HAS_BUFFER ? Buffer.from(bytes) : bytes
 }
 
+// Where the runtime provides the FIPS primitives through OpenSSL (Node 24 and
+// later) they are used in place of the JavaScript backend. Everywhere else,
+// including every browser, `native` is null and nothing about this module
+// changes. The two backends are checked against each other for this parameter
+// set in both directions by the interoperability matrix.
+const NATIVE_ALG = 'ML-KEM-768'
+const usesNative = () =>
+  native !== null && native.supports(NATIVE_ALG)
+
 /**
  * Generate an ML-KEM-768 keypair from a master + domain-separation info.
  *
@@ -38,7 +48,9 @@ export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
  * @returns {{ ciphertext: Buffer|Uint8Array, cipherText: Buffer|Uint8Array, sharedSecret: Buffer|Uint8Array }}
  */
 export function encapsulate(publicKey) {
-  const r = ml_kem768.encapsulate(publicKey)
+  const r = usesNative()
+    ? native.encapsulate(NATIVE_ALG, publicKey)
+    : ml_kem768.encapsulate(publicKey)
   const ct = wrap(r.cipherText ?? r.ciphertext)
   return {
     ciphertext:   ct,
@@ -55,6 +67,9 @@ export function encapsulate(publicKey) {
  * @returns {Buffer|Uint8Array} shared secret (32 bytes)
  */
 export function decapsulate(ciphertext, secretKey) {
+  if (usesNative()) {
+    return wrap(native.decapsulate(NATIVE_ALG, ciphertext, secretKey))
+  }
   return wrap(ml_kem768.decapsulate(ciphertext, secretKey))
 }
 

package/src/slh-dsa.js

@@ -16,6 +16,7 @@
 import { slh_dsa_sha2_192s } from '@noble/post-quantum/slh-dsa.js'
 import { deriveSeed } from './derive.js'
 import { normalizeContext, MAX_CONTEXT_BYTES } from './_context.js'
+import { native } from '#native'
 
 export { MAX_CONTEXT_BYTES }
 
@@ -45,6 +46,15 @@ function wrap(bytes) {
 // Seed length for SLH-DSA-SHA2-192s keygen (FIPS 205: SK.seed || SK.prf || PK.seed).
 const SEED_BYTES = slh_dsa_sha2_192s.lengths.seed
 
+// Where the runtime provides the FIPS primitives through OpenSSL (Node 24 and
+// later) they are used in place of the JavaScript backend. Everywhere else,
+// including every browser, `native` is null and nothing about this module
+// changes. The two backends are checked against each other for this parameter
+// set in both directions by the interoperability matrix.
+const NATIVE_ALG = 'SLH-DSA-SHA2-192s'
+const usesNative = (context) =>
+  context === undefined && native !== null && native.supports(NATIVE_ALG)
+
 /**
  * Generate an SLH-DSA-SHA2-192s keypair from a master + domain-separation info.
  *
@@ -74,6 +84,9 @@ export function keypairFromMaster(master, info = 'slh-dsa-sha2-192s-v1') {
  */
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
+  if (usesNative(context)) {
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+  }
   const sig = context === undefined
     ? slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
     : slh_dsa_sha2_192s.sign(toBytes(message), secretKey, { context })
@@ -95,6 +108,9 @@ export function sign(secretKey, message, opts) {
 export function verify(publicKey, message, sigHex, opts) {
   const context = normalizeContext(opts)
   try {
+    if (usesNative(context)) {
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+    }
     return context === undefined
       ? slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)
       : slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })