kxco-post-quantum 1.7.1 → 1.7.2

package/AGILITY.md

@@ -0,0 +1,115 @@
+# Cryptographic agility
+
+What has to change, and what does not, when the algorithm changes.
+
+"Crypto-agility" is used for three different things: a plan to replace an
+algorithm, a mechanism that performs the replacement, and a transition that
+peers can follow without breaking. They are not the same claim and this
+document keeps them apart. Where the answer is "we do not have that", it says
+so.
+
+## 1. A replacement plan
+
+[MIGRATION.md](MIGRATION.md) carries the plan, in four stages: verify both,
+sign both, require both, drop the classical signature. The rule it exists to
+enforce is *do not swap, add then remove*, because a one-release swap strands
+everything signed before it and every peer you do not control.
+
+The same shape covers a move between post-quantum parameter sets, with one
+difference: there is no classical side to retire, so stage 4 is reached as soon
+as every consumer verifies the new set.
+
+For key establishment the plan is not optional in the same way. Combine the
+ML-KEM shared secret with a classical secret through a KDF, so the session
+holds if either does. `deriveSeed` is what that HKDF step is for.
+
+## 2. An implemented mechanism
+
+Three mechanisms exist in this package today.
+
+**Parameter set selection.** Five sets are published helpers with their own
+entry points: ML-DSA-65, ML-DSA-87, ML-KEM-768, ML-KEM-1024 and
+SLH-DSA-SHA2-192s. Category 5 is not a future item; `mlDsa87` and `mlKem1024`
+ship today. Changing set is an import change at the call site rather than a
+redesign, because every set is reached through the same function shapes.
+
+Be precise about the difference between those five and what the backend can
+express. `backend().parameterSets` reports nine on OpenSSL 3.5, including
+ML-DSA-44, ML-KEM-512 and two further SLH-DSA sets, and
+[BENCHMARKS.md](BENCHMARKS.md) measures all of them. Reporting a set is not the
+same as wrapping it: a set outside the five is visible to an evidence bundle
+and is not an API this package offers.
+
+**Two interchangeable backends.** The primitives run in OpenSSL 3.5 where the
+runtime provides them and in JavaScript everywhere else. They produce identical
+wire bytes, which is what makes the substitution safe: a signature made on one
+verifies on the other, and the interoperability matrix in
+[CONFORMANCE.md](CONFORMANCE.md) is what establishes that rather than an
+assertion here.
+
+**One abstraction, enforced.** [`eslint-plugin-kxco-pq`](https://www.npmjs.com/package/eslint-plugin-kxco-pq)
+fails a build that reaches past the wrapper into `.ml_dsa65` or `.ml_kem768` on
+the underlying library. The point is not style. A call site bound to a
+primitive is a call site that a backend or parameter-set change has to rewrite
+by hand, and the rule is what keeps the abstraction from being quietly holed.
+
+The mechanism reports its own state. `backend()` returns which implementation
+is doing the maths, its OpenSSL version and the sets it can express, so an
+evidence bundle or a support ticket records the answer rather than inferring it
+from `process.version`. It reports and does not switch, deliberately: a runtime
+flag that changed which implementation signed would be a flag that changed what
+a customer's evidence means.
+
+The one operator control is the opposite of a switch. `requireNativeBackend()`,
+or `KXCO_PQ_REQUIRE_NATIVE=1` in the environment, refuses to let a process
+continue on the JavaScript backend when the deployment is under a control that
+says the cryptography must execute inside a validated module. It fails at
+import rather than at the first signature. It cannot make OpenSSL appear, and
+it does not claim that the OpenSSL it found is a validated module, which is a
+property of the operator's build.
+
+## 3. An interoperable transition
+
+**Algorithm identifiers on the wire.** The JWS module resolves the
+implementation from its own allowlist using the header `alg`, and rejects
+anything outside it. That is what lets a verifier accept two algorithms during
+a transition without becoming vulnerable to the algorithm-confusion failure
+that has broken JWT libraries repeatedly. `JWS_ALGORITHMS` is the allowlist;
+the RFC 9964 names are used, not private ones.
+
+**Key identifiers.** `fingerprint()` gives a key a stable kid, and both signing
+and verification take one, so a consumer can be pinned to a specific key while
+the algorithm around it moves.
+
+**Two signatures over identical bytes.** The webhook envelope signs
+`${timestamp}.${rawBody}` with HMAC-SHA-256 and with ML-DSA-65, both covering
+exactly the same bytes. A receiver that verifies only one cannot be tricked
+into treating it as covering a different message. This is stage 2 and stage 3
+of the plan, already built.
+
+**Evidence that peers accept the output.** The transition claim is only worth
+the interoperability behind it. Bouncy Castle, liboqs, two independent Python
+implementations and OpenSSL 3.5 verify what this package produces, and it
+verifies theirs, both directions, pinned by version, in
+[CONFORMANCE.md](CONFORMANCE.md).
+
+## What this package does not give you
+
+- **No runtime negotiation protocol.** Nothing here discovers what a peer
+  supports. The JWS allowlist lets a verifier accept more than one algorithm;
+  it does not ask a peer which one to use.
+- **No automatic downgrade, ever.** There is no path that silently drops to a
+  weaker set when the stronger one is unavailable. A missing set is an error.
+- **The set list is fixed at release.** A parameter set this package does not
+  wrap needs a release of this package, not a configuration change. That is the
+  honest ceiling of the abstraction.
+- **The JWS allowlist is ML-DSA only.** SLH-DSA and ML-KEM are reached at the
+  key and signature layer, not through `alg`.
+- **No TLS group negotiation.** Channel-level agility is not this package's
+  surface. See `kxco-pq-tls`.
+
+## Correcting this document
+
+Every mechanism above is in `src/` and every evidence claim is in
+[CONFORMANCE.md](CONFORMANCE.md). If a statement here does not match the code,
+that is a defect worth reporting through [SECURITY.md](SECURITY.md).

package/BOUNDARY.md

@@ -0,0 +1,111 @@
+# Product boundary
+
+Which cryptography this package performs, which it depends on, and which it
+merely offers to a caller. The three are routinely collapsed into one claim,
+and collapsing them is how "quantum-safe" gets asserted for a product whose own
+update path is classical.
+
+## What the assessed thing is
+
+A library. It has no server, no console and no runtime service connections:
+nothing in `src/` opens a socket. That is a narrow boundary and it makes most
+of the questions below short, but the short answers are the point.
+
+Record the configuration alongside any claim, because the answers differ by
+runtime. `backend()` returns it: implementation, OpenSSL version, and the
+parameter sets that implementation can express.
+
+## Start and update
+
+**Quantum-safe.** Every release asset is signed with ML-DSA-65 by this
+package's own signing path, and the public key is committed to the repository
+rather than served only beside the artefact. Verification is four lines and is
+in [README.md](README.md#verifying-a-release). Releases also carry SLSA
+provenance recording the workflow that built them, and npm provenance is on.
+
+**The classical part, stated.** Fetching the release is TLS to the npm registry
+or to GitHub, and that TLS is classical. So is the transport that delivered the
+git clone. This is outside our control and it is a real residual: an attacker
+who could break that transport today could serve a different artefact, and the
+ML-DSA signature is what would catch it, provided the verifier has the key from
+a second path. That proviso is why the key is in the repository and why the
+README says to compare the two copies.
+
+## Operate
+
+**No required service connections.** The library performs no network operation
+at any point. There is no licence check, no telemetry, no key server and no
+call home. Nothing in the operating path can be a classical dependency, because
+there is no operating path outside the caller's process.
+
+**Key management is the caller's, with one supported escape.** Keys live in the
+caller's memory unless the caller puts them somewhere better. `kxco-pq-hsm`
+generates ML-DSA keys on a PKCS#11 token with `CKA_EXTRACTABLE=false`, at which
+point this library handles verification only and touches no secret. The channel
+to that token is the HSM vendor's, not ours, and its own post-quantum posture
+is a question for the vendor.
+
+**Storage and diagnostics.** Neither exists here. The package writes no files
+and keeps no state between calls.
+
+## Protect records
+
+Not this package's role, and it does not pretend otherwise. Log integrity and
+timestamping in the KXCO estate are `kxco-pq-audit`: SHA-256 hash-chained
+entries, each ML-DSA-65 signed, with periodic seals anchored on Armature L1 so
+a verifier who does not trust the log operator has an independent time bound.
+
+What this package contributes to that is the signature primitive and nothing
+else.
+
+## Enforce policy
+
+A prohibited fallback can be rejected. The package's default is to fall back
+from OpenSSL to JavaScript, and that default is correct for almost everyone
+because both produce identical wire bytes. It is wrong in one situation: a
+deployment under a control requiring the cryptography to execute inside a
+validated module, where a silent fallback means the control is not in force and
+nothing says so.
+
+`KXCO_PQ_REQUIRE_NATIVE=1`, or `requireNativeBackend([...])` in code, fails the
+process at import instead. Note the limit of the assertion: it establishes that
+OpenSSL is doing the maths, not that the OpenSSL it found is a validated
+module. That is a property of the operator's build and this package cannot see
+it.
+
+## Retain history
+
+**Verification of old records: yes.** A signature made by any version of this
+package verifies under any later version. Wire formats have not changed and the
+conformance evidence is regenerated against pinned vectors on every dependency
+bump, which is what would catch a change that broke them.
+
+**Long-term trust: not solved here, and it is not the same question.** This
+package has no notion of key validity windows, revocation or trusted
+timestamps, so it can tell you a signature is arithmetically valid and cannot
+tell you the key was still trusted when it was made. Anything that has to hold
+for years needs a time anchor outside the signature. In the KXCO estate that is
+`kxco-pq-audit`'s on-chain seals. For a deployment outside it, that is a gap
+the deployment has to close.
+
+## Customer-selected outputs
+
+The library will sign at whatever parameter set the caller selects, Category 1
+included, and will verify Category 1 signatures from a peer. That is a customer
+output, not a statement about this package's own operation, and the two should
+not be reported as one number.
+
+The KXCO estate itself signs at Category 3 with ML-DSA-65, including Armature
+L1 from block 0 and every issued KXCO ID. Support for ML-DSA-87 and ML-KEM-1024
+is a support claim and not a CNSA 2.0 compliance claim, for the reasons set out
+in [CONFORMANCE.md](CONFORMANCE.md#what-this-evidence-does-not-cover).
+
+## The gaps, collected
+
+Repeated here so they are not spread across six sections:
+
+1. Release transport is classical TLS, mitigated by an ML-DSA signature and a
+   second copy of the key, not eliminated.
+2. The PKCS#11 channel to an HSM is the vendor's, and outside our assessment.
+3. No long-term validation: no timestamps, no validity windows, no revocation.
+4. `requireNativeBackend` asserts OpenSSL, not a validated OpenSSL.

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.7.2
+
+Documentation, and one typing fix. No source change to the library and no wire
+format change.
+
+**Three documents the package needed and did not have.** Buyer readiness
+assessments ask what the product boundary is, what cryptographic agility it
+actually has, and what constrains its lifecycle. All three had real answers in
+the code and the evidence. None was written down, and an answer that exists
+only in a maintainer's head is not evidence.
+
+BOUNDARY.md separates what this package performs from what it depends on and
+what it merely offers a caller. Nothing in src/ opens a socket, so the
+operating path has no classical service dependency at all. Release signing is
+ML-DSA-65 with the key committed here; the transport that delivers the release
+is classical TLS, and that is stated rather than folded into the claim.
+
+AGILITY.md separates the three things the term is used for: a replacement plan,
+an implemented mechanism, and an interoperable transition. It also names the
+four kinds of agility this package does not give you, including that a
+parameter set outside the published five needs a release rather than a
+configuration change.
+
+LIFECYCLE.md carries supported versions, the runtime ceiling, and the blocking
+supplier dependency with its mitigations ranked. The end-of-support window is
+marked not yet decided rather than invented.
+
+All three are copied into the evidence bundle. An assessor reads the bundle,
+not the repository.
+
+**requireNativeBackend is now in the typings.** 1.7.0 shipped it, and shipped
+it exported from index.js and documented in the README while declared in
+neither backend.d.ts nor index.d.ts. A TypeScript caller therefore could not
+reach the one control in this package that enforces a no-fallback policy, which
+is precisely the deployment the feature exists for. Runtime behaviour was
+always correct; the type surface hid it.
+
 ## 1.7.1
 
 Release integrity. No source change to the library.

package/LIFECYCLE.md

@@ -0,0 +1,124 @@
+# Lifecycle, ceiling and dependencies
+
+The questions a buyer needs answered before committing to a migration date,
+rather than after. Maturity describes what has been achieved; none of it says
+whether the thing will still be maintained, how far it can go without new
+hardware, or what could block it. Those are here.
+
+## Guidance followed
+
+FIPS 203, 204 and 205 for the primitives, verified against NIST's own ACVP
+vectors rather than asserted. RFC 9964 for the JWS algorithm names. RFC 5869
+for HKDF. Where a standard is supported but compliance is a property of a
+deployment rather than of this package, the distinction is stated instead of
+blurred: see the CNSA 2.0 entry in
+[CONFORMANCE.md](CONFORMANCE.md#what-this-evidence-does-not-cover).
+
+Risk review happened before the evidence, not after it:
+[THREAT-MODEL.md](THREAT-MODEL.md) names what is in scope, what is out, and
+where the residual risk actually sits, which is a long-lived signing key in the
+memory of a general-purpose process.
+
+Update and agility needs are in [AGILITY.md](AGILITY.md), including the
+mechanisms this package does not have.
+
+## Supported versions
+
+One line, moving forward. Releases run v1.x in sequence with no maintenance
+branches, and fixes land in the next release rather than being backported.
+Anyone on an older 1.x upgrades forward to receive a fix.
+
+Upgrading forward is intended to be cheap and is treated as a compatibility
+obligation: signatures made by earlier versions verify under later ones, and
+[MIGRATION.md](MIGRATION.md#migrating-between-versions) records what changed at
+each step where a caller had to do anything.
+
+**Not yet decided:** a formal end-of-support window, expressed in months rather
+than in practice. Until it is decided, the honest statement is the one above,
+which describes what happens rather than what is promised. A buyer who needs a
+contractual window should ask for one rather than infer it.
+
+## Ceiling without hardware replacement
+
+There is no hardware ceiling in this package. It is software, the highest
+parameter sets are already shipped rather than planned, and Category 5 needs no
+different machine than Category 3: `mlDsa87` and `mlKem1024` are published
+entry points today.
+
+The ceiling that does exist is the runtime, and it is a performance ceiling
+rather than a capability one:
+
+| Runtime | Backend | Effect |
+|---|---|---|
+| Node 24 and later | OpenSSL 3.5 primitives | Roughly 4x to 8x faster, measured per operation in [BENCHMARKS.md](BENCHMARKS.md) |
+| Node 20.19 to 23, browsers | JavaScript | Every algorithm available, identical wire bytes, slower |
+
+Nothing becomes unavailable on the slower path. If a request budget cannot
+absorb the JavaScript figures, the fix is a Node upgrade, which is not a
+hardware replacement.
+
+Two real ceilings sit outside this package and belong to whatever it is
+deployed with. An HSM can only perform the algorithms its firmware implements,
+and firmware is where hardware replacement genuinely appears; that question
+belongs to `kxco-pq-hsm` and the token vendor. Signature size is the other:
+ML-DSA-65 signatures are far larger than ECDSA, and a protocol with a fixed
+field or an MTU assumption may need changing. [MIGRATION.md](MIGRATION.md) puts
+proving that at stage 1 for exactly this reason.
+
+## Blocking supplier dependency
+
+**The dependency.** `@noble/post-quantum`, pinned at exactly 0.7.0, supplies
+the FIPS 203/204/205 arithmetic. This package does not reimplement it.
+
+**Why it is a blocker and not just a dependency.** It is the one package in the
+tree with no independent review. The maintainer's own self-audit covers 0.6.1,
+which is not the version shipped. Version 0.7.1 regressed nine NIST SLH-DSA
+verification vectors that 0.7.0 passes, shipped in this package's 1.5.1 and was
+reverted in 1.5.2. So the supply risk here is demonstrated rather than
+theoretical.
+
+**Mitigations, in the order they actually help.**
+
+1. *Evidence instead of trust.* Every parameter set is checked against NIST's
+   ACVP vectors and cross-checked against liboqs, Bouncy Castle and two Python
+   implementations in both directions. That regression was caught by this
+   harness within hours of the dependency's release, which is the concrete
+   demonstration that the control works.
+2. *A second implementation on the same wire format.* On Node 24 and later the
+   OpenSSL backend performs ML-DSA, ML-KEM and SLH-DSA for the sets OpenSSL
+   expresses, and the dependency is not doing that arithmetic at all. The
+   exception is precise and worth stating: a FIPS 204 context string takes the
+   JavaScript path, because OpenSSL does not express it. So the dependency is
+   reduced on modern runtimes rather than removed.
+3. *An exact pin, enforced.* No ranges in `dependencies`, and the audit harness
+   fails the build on one. 0.7.1 is separately blocked in dependabot so it
+   cannot return through an automated bump.
+4. *A conformance gate on every bump.* A change to this dependency is a change
+   to the primitives, so it is not merged on a green test run. The full ACVP
+   and interoperability evidence has to regenerate clean.
+
+**Milestone.** The route off this being a single point of review is external
+audit, and that is on the roadmap rather than done. See below.
+
+**Second-order dependency, disclosed.** `@noble/curves` is not imported by name
+anywhere in this package and is on the hot path regardless: both ML-DSA and
+ML-KEM reach it through the primitives. That was established by a reachability
+walk rather than by reading manifests, and it is in
+[DEPENDENCIES.md](DEPENDENCIES.md). It is the most heavily reviewed package in
+the tree.
+
+## Roadmap status, beside the maturity result
+
+The commitments and what has not happened yet are in
+[AUDIT.md](AUDIT.md#3-audit-roadmap): an external auditor for the wrapper
+integration patterns, a public bug bounty, and a FIPS 140-3 CMVP application
+for a module deployment using this library with an HSM. Dates depend on
+capacity; the order is committed.
+
+Read that table beside any maturity claim, not after it. Nothing on it has been
+delivered, and a roadmap entry is a vendor commitment rather than a result.
+
+## Correcting this document
+
+If a figure or a pin here does not match the tree, that is a defect worth
+reporting through [SECURITY.md](SECURITY.md).

package/README.md

@@ -41,6 +41,9 @@ languages are **JavaScript and C** (OpenSSL 3.5 on Node 24+).
 - [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, release integrity, and the dependency policy.
+- [AGILITY.md](./AGILITY.md): what has to change when the algorithm changes. The replacement plan, the mechanisms that exist today, the transition peers can follow, and the four kinds of agility this package does not give you.
+- [BOUNDARY.md](./BOUNDARY.md): which cryptography this package performs, which it depends on, and which it merely offers to a caller. Release signing is ML-DSA-65; the transport that delivers the release is classical TLS, and that is stated rather than folded into the claim.
+- [LIFECYCLE.md](./LIFECYCLE.md): supported versions, the runtime ceiling, and the one blocking supplier dependency with its mitigations. Read the roadmap beside a maturity claim, not after it.
 - **Every release is reproducible and attested.** The published tarball rebuilds bit-for-bit from its own tag, verified in CI on every run, and each release carries a SLSA provenance attestation plus a CycloneDX SBOM at a permanent unauthenticated URL. A provenance attestation says a build happened in CI; the reproducible build says the artefact is the source. They are different claims and both are checkable without asking us for anything.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "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",
@@ -109,12 +109,15 @@
     }
   },
   "files": [
+    "AGILITY.md",
     "BENCHMARKS.md",
+    "BOUNDARY.md",
     "CHANGELOG.md",
     "CONFORMANCE.md",
     "DEPENDENCIES.md",
     "LICENCE-PRODUCT.md",
     "LICENSE",
+    "LIFECYCLE.md",
     "MIGRATION.md",
     "README.md",
     "SECURITY.md",
@@ -129,6 +132,7 @@
     "@noble/post-quantum": "0.7.0"
   },
   "scripts": {
+    "fuzz": "node fuzz/fuzz.mjs",
     "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",

package/src/backend.d.ts

@@ -14,3 +14,21 @@ export function backend(): BackendReport
 
 /** Whether a parameter set runs natively here, e.g. isNative('ML-DSA-65'). */
 export function isNative(alg: string): boolean
+
+/**
+ * Refuse to run unless the cryptography is executing in the native backend.
+ *
+ * An assertion, not a switch: it cannot change which implementation signs, it
+ * stops a process that has silently landed on the JavaScript backend when the
+ * operator required otherwise. Also settable from the environment with
+ * `KXCO_PQ_REQUIRE_NATIVE=1`, which applies the check at import.
+ *
+ * Asserts that OpenSSL is doing the maths. Whether that OpenSSL is a
+ * FIPS-validated module is a property of the operator's build and is not
+ * visible from here.
+ *
+ * @param algorithms Parameter sets that must run natively. Omit to require
+ *   only that the native backend is present.
+ * @throws Error with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
+ */
+export function requireNativeBackend(algorithms?: string[]): BackendReport

package/src/index.d.ts

@@ -16,4 +16,4 @@ export * as webhook from './webhook.js'
 export * as seed from './seed.js'
 /** Compact JWS using the RFC 9964 algorithm names. Format only, no network. */
 export * as jws from './jws.js'
-export { backend, isNative } from './backend.js'
+export { backend, isNative, requireNativeBackend } from './backend.js'