kxco-post-quantum 1.4.1 → 1.5.1

package/BENCHMARKS.md

@@ -15,7 +15,51 @@ node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/prim
 ```
 
 Every parameter set the package can reach is measured, not only the five it wraps
-in its own helpers.
+in its own helpers. The OpenSSL rows appear only on a runtime that provides those
+primitives, so run it on Node 24 or later to reproduce the comparison below and
+on Node 22 for the JavaScript figures alone.
+
+## Two backends
+
+Since 1.5.0 this package runs the FIPS primitives in OpenSSL 3.5 where the
+runtime provides them (Node 24 and later) and in JavaScript everywhere else.
+Those are different implementations, so one set of numbers cannot describe both.
+The harness measures whichever are available and labels every row, and the
+tables below the comparison are the JavaScript figures.
+
+| Algorithm | Operation | OpenSSL p50 | JavaScript p50 | OpenSSL p99 | JavaScript p99 | faster by |
+|---|---|---:|---:|---:|---:|---:|
+| ML-DSA-44 | sign | 1.125 | 5.116 | 4.619 | 21.325 | 4.5x |
+| ML-DSA-44 | verify | 0.241 | 1.373 | 0.725 | 2.451 | 5.7x |
+| ML-DSA-65 | sign | 1.293 | 8.074 | 4.562 | 40.840 | 6.2x |
+| ML-DSA-65 | verify | 0.288 | 2.249 | 0.652 | 3.803 | 7.8x |
+| ML-DSA-87 | sign | 1.879 | 11.031 | 7.128 | 39.404 | 5.9x |
+| ML-DSA-87 | verify | 0.613 | 3.363 | 1.831 | 5.843 | 5.5x |
+| ML-KEM-1024 | encapsulate | 0.126 | 0.708 | 0.278 | 1.986 | 5.6x |
+| ML-KEM-1024 | decapsulate | 0.230 | 0.919 | 0.339 | 1.630 | 4.0x |
+| ML-KEM-512 | encapsulate | 0.079 | 0.378 | 0.212 | 1.008 | 4.8x |
+| ML-KEM-512 | decapsulate | 0.236 | 0.461 | 0.380 | 1.498 | 2.0x |
+| ML-KEM-768 | encapsulate | 0.148 | 0.558 | 0.256 | 1.288 | 3.8x |
+| ML-KEM-768 | decapsulate | 0.183 | 0.874 | 0.523 | 5.378 | 4.8x |
+| SLH-DSA-SHA2-128f | sign | 68.639 | 97.791 | 165.092 | 173.466 | 1.4x |
+| SLH-DSA-SHA2-128f | verify | 3.459 | 6.082 | 4.303 | 27.278 | 1.8x |
+| SLH-DSA-SHA2-192s | sign | 1710.954 | 4342.105 | 1938.773 | 4628.987 | 2.5x |
+| SLH-DSA-SHA2-192s | verify | 1.263 | 7.457 | 2.405 | 40.920 | 5.9x |
+| SLH-DSA-SHAKE-256f | sign | 161.358 | 2158.272 | 179.655 | 3510.503 | 13.4x |
+| SLH-DSA-SHAKE-256f | verify | 5.599 | 66.177 | 6.774 | 98.654 | 11.8x |
+
+The speedup column is the headline, but for a document about tail latency the
+p99 columns matter more. ML-DSA-65 signing goes from a 40.8 ms p99 to 4.6 ms:
+the rejection-sampling tail that the opening of this document warns about is
+still there in the OpenSSL path, but it is roughly nine times tighter, so a
+timeout sized off it can be far smaller.
+
+SLH-DSA-SHAKE-256f is the largest single change, 2158 ms down to 161 ms for a
+signature. SLH-DSA-SHA2-192s remains slow in absolute terms at 1.7 seconds and
+no backend makes a hash-based signature cheap; it is 2.5x rather than fast.
+
+Neither column is a side-channel claim. See
+[THREAT-MODEL.md](THREAT-MODEL.md).
 
 ## Signatures
 

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.5.1
+
+Dependency bump: `@noble/post-quantum` 0.7.0 to **0.7.1**, published 2026-08-27.
+Exact pin as always, never a range.
+
+Worth taking rather than waiting for the scheduled Dependabot run, because one of
+its changes touches how this package calls it: 0.7.1 snapshots options on entry
+so a caller's object cannot be mutated afterwards. Every FIPS 204 context string
+this package passes goes in as an options object, so that hardening is directly
+on our path.
+
+It also adds a WebCrypto wrapper for ML-KEM upstream. Nothing here uses it yet,
+but it is worth knowing that the backend is converging on the same thing this
+package did in 1.5.0: use the platform's implementation where the platform has
+one.
+
+Verified before merging, on all three runtimes: 39 pinned vectors bit-for-bit and
+53 tests on Node 20 and 22 (the JavaScript path, where this bump actually
+applies) and on Node 24+ (the OpenSSL path).
+
+AUDIT.md carries the new pin and its integrity hash. The conservative bound is
+unchanged and restated: the maintainer's self-audit covers 0.6.1, we ship 0.7.1,
+so **the version we ship is covered by no audit at all**.
+
+## 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

package/CONFORMANCE.md

@@ -102,7 +102,19 @@ 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.
 
-None of the three shares code with this package's backend. liboqs is the
+### 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.

package/README.md

@@ -11,7 +11,7 @@ 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 (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`.
+- [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.

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.1",
+  "version": "1.5.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",
@@ -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",
@@ -106,7 +112,7 @@
   },
   "dependencies": {
     "@noble/hashes": "2.3.0",
-    "@noble/post-quantum": "0.7.0"
+    "@noble/post-quantum": "0.7.1"
   },
   "scripts": {
     "test": "node --test test/basic.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",

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 })