kxco-post-quantum 1.6.4 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 1.7.1
+
+Release integrity. No source change to the library.
+
+Release assets are now signed with ML-DSA-65 through this package's own signing
+path, and each release carries a SLSA provenance file. Until now the npm tarball
+had provenance and the GitHub release, where the evidence bundle is actually
+downloaded from, had neither a signature nor a statement of where it was built.
+
+The public key is committed as release-signing-key.pub.hex and published with
+each release. The signing script refuses to run if the seed in CI stops deriving
+that key, and verifies every signature immediately after producing it.
+
+## 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

package/README.md

@@ -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
@@ -304,3 +344,29 @@ Apache-2.0. See [LICENSE](./LICENSE).
 ## Maintainers
 
 Shayne Heffernan and John Heffernan — [KXCO by Knightsbridge](https://kxco.ai)
+
+## Verifying a release
+
+Every release asset is signed with ML-DSA-65 by this package's own signing path,
+and carries a SLSA provenance file recording the workflow that built it.
+
+```
+manifest-node24.x.json          the bundle's manifest
+evidence-node24.x.zip           the bundle
+evidence-node24.x.zip.sig       ML-DSA-65 signature over the zip, hex
+evidence.intoto.jsonl           SLSA provenance
+release-signing-key.pub.hex     the public key, also committed to this repository
+```
+
+```js
+import { readFileSync } from 'node:fs'
+import { mlDsa } from 'kxco-post-quantum'
+
+const pub = Buffer.from(readFileSync('release-signing-key.pub.hex', 'utf8').trim(), 'hex')
+const sig = readFileSync('evidence-node24.x.zip.sig', 'utf8').trim()
+mlDsa.verify(pub, readFileSync('evidence-node24.x.zip'), sig)   // true
+```
+
+Compare the public key against the copy in this repository before trusting a
+signature: a key served alongside the artefact it signs proves only that the
+same party produced both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.6.4",
+  "version": "1.7.1",
   "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",
@@ -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'