kxco-post-quantum 1.6.3 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.7.0
+
+Additive. No existing export changes shape, no wire format moves, and the
+default behaviour of the package is unchanged.
+
+**`requireNativeBackend([algorithms])`.** The package picks OpenSSL where the
+runtime has the FIPS 203/204/205 primitives and the JavaScript implementation
+otherwise. Both produce identical bytes, so the fallback is right nearly always.
+It is wrong under a control that says cryptography must execute inside a
+validated module: there the fallback means the control is not in force and
+nothing says so. This throws `ERR_KXCO_PQ_BACKEND` instead, carrying `actual`,
+`missing` and `available` so the failure says which requirement was not met.
+
+**`KXCO_PQ_REQUIRE_NATIVE=1`.** The same requirement from the environment,
+because the team under the control is usually not the team calling the library.
+A process that has landed on the JavaScript backend then fails at import rather
+than at its first signature.
+
+It asserts, it does not switch. There is still no way to force a backend, for
+the reason there never was: a flag that changed which implementation signed
+would change what a customer's evidence means. This only refuses to continue on
+the wrong one.
+
+It also claims only what it can see. Whether the OpenSSL underneath is a
+FIPS-validated module is a property of the operator's build; no library can
+determine that from the inside, and this does not pretend to. It removes the
+silent fallback, which is the part this package owns.
+
+Tested on both backends without mocking: CI runs Node 20 and 22, which have no
+native primitives and exercise the refusal, and Node 24, which exercises the
+accept path.
+
+## 1.6.4
+
+Documentation. The npm description said "2,103 NIST ACVP vectors and 225
+interop checks, 0 failed", which reads as 2,103 passing. The evidence records
+2,103 tested, 1,793 passed, 0 failed, 310 skipped, and CONFORMANCE.md says a
+skip is not a pass.
+
+Twelve sibling READMEs were corrected for this yesterday and this package's own
+README has been right for months. The description was the one place it
+survived, and a description only changes when the package is published, so it
+needed a release rather than a commit. It is the first thing anyone reads.
+
+Also corrects the count of what the downloadable bundle contains, from 1,479
+to the 1,551 actually present in the published v1.6.3 assets.
+
 ## 1.6.3
 
 Release plumbing only. No source change.

package/README.md

@@ -36,7 +36,7 @@ languages are **JavaScript and C** (OpenSSL 3.5 on Node 24+).
 
 **Evidence, not adjectives:**
 
-- [CONFORMANCE.md](./CONFORMANCE.md): NIST ACVP vectors for FIPS 203/204/205: **2,103 vectors, 1,793 passed, 0 failed, 310 skipped**, where every skip is this library refusing a pre-hash weaker than the parameter set and is listed individually with its reason. CONFORMANCE.md says a skip is not a pass, so the headline says so too. Of those, **1,479 vectors are in the downloadable evidence bundle**; the remaining 624 are SLH-DSA signature generation, which signs in seconds per operation and so is reproduced on demand with `node conformance/run-acvp.mjs --set SLH-DSA-sigGen-FIPS205` rather than shipped. The bundle names that gap rather than leaving it to be noticed. Plus 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`.
+- [CONFORMANCE.md](./CONFORMANCE.md): NIST ACVP vectors for FIPS 203/204/205: **2,103 vectors, 1,793 passed, 0 failed, 310 skipped**, where every skip is this library refusing a pre-hash weaker than the parameter set and is listed individually with its reason. CONFORMANCE.md says a skip is not a pass, so the headline says so too. Of those, **1,551 are in the downloadable evidence bundle**, measured from the published v1.6.3 assets: 855 in `02-conformance-acvp.json`, 624 in `02b-conformance-acvp-fips205.json` and a 72-vector sample of SLH-DSA signature generation in `02d-conformance-acvp-fips205-siggen.json`. Signature generation is sampled rather than shipped whole because it signs in seconds per operation; the full set is reproduced on demand with `node conformance/run-acvp.mjs --set SLH-DSA-sigGen-FIPS205`. The bundle names that gap rather than leaving it to be noticed. Plus 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 on both backends and on x86-64 and arm64, plus memory. Two figures worth designing around: ML-DSA signing keeps a rejection-sampling tail on either backend (5.1x median-to-p99 in JavaScript, 3.5x on OpenSSL), and SLH-DSA-SHA2-192s signs in seconds rather than milliseconds (4.3 s and 1.7 s).
 - [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.
@@ -271,6 +271,46 @@ Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `v
 
 ---
 
+## Requiring the native backend
+
+This package picks its implementation at import time: OpenSSL 3.5 where the
+runtime provides the FIPS 203/204/205 primitives, the JavaScript implementation
+otherwise. Both produce identical wire bytes, so falling back is the right
+default and nothing about a signature changes.
+
+It is the wrong default in one situation: a deployment under a control that says
+cryptography must execute inside a validated module. There, a silent fallback
+means the control is not in force and nothing says so.
+
+```js
+import { requireNativeBackend } from 'kxco-post-quantum'
+
+requireNativeBackend(['ML-DSA-65', 'ML-KEM-768'])
+```
+
+It throws `ERR_KXCO_PQ_BACKEND` if the JavaScript backend is live, or if the
+OpenSSL present cannot provide a parameter set you named. The error carries
+`actual`, `missing` and `available` so a failure says which, rather than only
+that.
+
+Operators can enforce it without touching application code, which matters
+because the team under the control is usually not the team calling the library:
+
+```
+KXCO_PQ_REQUIRE_NATIVE=1
+```
+
+Set that and a process which has landed on the JavaScript backend fails at
+import, before its first signature rather than after.
+
+**What this does and does not claim.** It asserts that OpenSSL is doing the
+maths. Whether that OpenSSL is a FIPS-validated module is a property of your
+build, not of this package, and no library can see it from the inside. What it
+removes is the silent fallback, which is the part this package is responsible
+for. It is an assertion, never a switch: it cannot change which backend runs,
+because a flag that changed which implementation signed would change what your
+evidence means.
+
 ## Where this fits
 
 This is the primitive layer, and it stays that: keys, signatures, encapsulation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.6.3",
-  "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s with key fingerprinting. OpenSSL 3.5 primitives on Node 24+, JavaScript elsewhere. 2,103 NIST ACVP vectors and 225 cross-implementation interop checks, 0 failed. Reproducible builds and SLSA provenance.",
+  "version": "1.7.0",
+  "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s with key fingerprinting. OpenSSL 3.5 primitives on Node 24+, JavaScript elsewhere. 2,103 NIST ACVP vectors: 1,793 passed, 0 failed, 310 skipped. 225 interop checks, 0 failed. Reproducible builds and provenance.",
   "keywords": [
     "post-quantum",
     "pqc",
@@ -129,7 +129,7 @@
     "@noble/post-quantum": "0.7.0"
   },
   "scripts": {
-    "test": "node --test test/basic.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/edge-cases.test.js && node --test test/seed.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
+    "test": "node --test test/basic.test.js && node --test test/backend.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/edge-cases.test.js && node --test test/seed.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
     "test:vectors": "node test/run-vectors.js",
     "generate:vectors": "node test/generate-vectors.js > test/vectors.json",
     "bench": "node bench/bench.js",

package/src/backend.js

@@ -10,9 +10,31 @@
 // backend from here: the two produce identical wire bytes, and a runtime flag
 // that changed which one signed would be a flag that changes what a customer's
 // evidence means.
+//
+// `requireNativeBackend` at the bottom is not an exception to that. It cannot
+// change which backend runs. It refuses to let the process continue on the
+// wrong one, which is a different thing, and the thing a deployment under a
+// validated-module control actually needs.
 
 import { native } from '#native'
 
+// An operator control. A deployment under a validated-module requirement is
+// usually not the same team as the one calling this library, so the
+// requirement has to be enforceable from the environment rather than only from
+// application code. Set KXCO_PQ_REQUIRE_NATIVE=1 and a process that has landed
+// on the JavaScript backend fails at import, not at its first signature.
+//
+// Read defensively: this module is also loaded in browsers, where `process`
+// does not exist.
+const REQUIRE_NATIVE = (() => {
+  try {
+    const v = globalThis.process?.env?.KXCO_PQ_REQUIRE_NATIVE
+    return v === '1' || v === 'true'
+  } catch {
+    return false
+  }
+})()
+
 /**
  * Describe the active backend.
  *
@@ -46,3 +68,54 @@ export function backend() {
 export function isNative(alg) {
   return native !== null && native.supports(alg)
 }
+
+/**
+ * Refuse to run unless the cryptography is executing in the native backend.
+ *
+ * This is an assertion, not a switch. It cannot change which implementation
+ * signs, for the reason given at the top of this file. What it does is stop a
+ * process that has silently landed on the JavaScript backend when the operator
+ * required otherwise, before it produces its first signature rather than after.
+ *
+ * The default behaviour of this package is to fall back, and that default is
+ * correct: the two backends produce identical wire bytes. It is wrong in one
+ * specific situation, which is a deployment under a control that says the
+ * cryptography must execute inside a validated module. There, a silent fallback
+ * means the control is not in force and nothing says so.
+ *
+ * Note what this does and does not claim. It asserts that OpenSSL is doing the
+ * maths. Whether that OpenSSL is a FIPS-validated module is a property of the
+ * operator's build, not of this package, and this function cannot see it. It
+ * removes the fallback, which is the part we can be responsible for.
+ *
+ * @param {string[]} [algorithms] — parameter sets that must run natively.
+ *   Omit to require only that the native backend is present at all.
+ * @throws {Error} with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
+ */
+export function requireNativeBackend(algorithms) {
+  const b = backend()
+  if (b.kind !== 'openssl') {
+    throw backendError(
+      `the native backend is required and is not present: ${b.reason}`,
+      { required: 'openssl', actual: b.kind, reason: b.reason },
+    )
+  }
+  const missing = (algorithms ?? []).filter((a) => !isNative(a))
+  if (missing.length) {
+    throw backendError(
+      `the native backend is required for ${missing.join(', ')}, ` +
+        `and this OpenSSL does not provide ${missing.length > 1 ? 'them' : 'it'}`,
+      { required: 'openssl', actual: b.kind, missing, available: b.parameterSets },
+    )
+  }
+  return b
+}
+
+function backendError(message, detail) {
+  const err = new Error(message)
+  err.code = 'ERR_KXCO_PQ_BACKEND'
+  Object.assign(err, detail)
+  return err
+}
+
+if (REQUIRE_NATIVE) requireNativeBackend()

package/src/index.js

@@ -37,4 +37,4 @@ export * as jws  from './jws.js'
 
 // Reports which backend is doing the maths in this process, for evidence
 // bundles and support. It reports; it never switches.
-export { backend, isNative } from './backend.js'
+export { backend, isNative, requireNativeBackend } from './backend.js'