kxco-post-quantum 1.7.1 → 1.7.3

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,67 @@
 # Changelog
 
+## 1.7.3
+
+One resolution fix that consumers could hit, plus the ACVTS tooling and two
+maturity documents. No change to any algorithm, key format or wire format.
+
+**Every export subpath now carries a `default` condition.** All twelve declared
+only `types` and `import`, so a consumer resolving outside an import context got
+`ERR_PACKAGE_PATH_NOT_EXPORTED` and could not load the package at all. That is a
+packaging defect rather than a library one: nothing about the code changed, only
+what Node is willing to resolve. It was found from the other side, in a project
+that had to pass `--conditions=import` on every test invocation to work around
+it, and that workaround can come out once this is published.
+
+The addition is purely additive. A subpath that resolved before resolves to the
+same file now.
+
+**ACVTS tooling is committed rather than kept locally.** The selftest, the
+validation printer and the demo certificate verifier were written against the
+NIST demo submission and existed only on one machine, which makes them evidence
+nobody else can re-run.
+
+**Two PQCMM gaps closed and Level 3 re-declared**, against the PKI Consortium's
+Post-Quantum Cryptography Maturity Model, with the self-assessment written down
+rather than asserted.
+
+## 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/CRYPTO-INVENTORY.md

@@ -0,0 +1,227 @@
+# Cryptographic inventory
+
+Every use case in this package where cryptography is applied, mapped onto the
+ten categories of the PKI Consortium PQCMM cryptographic inventory taxonomy.
+
+The model requires that no category is omitted. A category that does not apply
+is marked not applicable with a written reason, because "we do not do that" and
+"we did not look" are indistinguishable from the outside unless the reason is
+recorded. Four of the ten genuinely do not apply to a library with no sockets
+and no persistent state, and saying so in one line each is the honest answer
+rather than a padded one.
+
+Scope: `kxco-post-quantum` 1.7.2. `BOUNDARY.md` is the companion document and
+explains the difference between cryptography this package performs, depends on,
+and merely offers to a caller. The distinction matters here: a caller can use
+this package inside a category that the package itself does not implement.
+
+## 1. Data in transit
+
+**Not applicable to the library. Applicable to its delivery.**
+
+Nothing in `src/` opens a socket. The library performs no network operation at
+any point: no licence check, no telemetry, no key server, no call home. There
+is no transport for it to protect.
+
+Its own delivery is a different matter and is not quantum-safe. Fetching the
+package is classical TLS to the npm registry or to GitHub, as was the transport
+that delivered any git clone. That residual is stated in `BOUNDARY.md` and is
+mitigated by an ML-DSA-65 signature over every release asset plus a second copy
+of the public key committed to the repository, so that a verifier is not
+trusting the same channel twice. Mitigated, not eliminated.
+
+What the package offers a caller for this category is the ML-KEM key
+encapsulation below, from which a caller may build a transport. Offering a
+primitive is not the same as protecting a transport, and the two should not be
+reported as one.
+
+| Use | Algorithm | Quantum-safe |
+|---|---|---|
+| Package delivery | TLS to registry and GitHub, classical | No, mitigated by signature |
+| Primitive offered to callers | ML-KEM-768, ML-KEM-1024 | Yes |
+
+## 2. Data at rest
+
+**Not applicable.** The package writes no files and keeps no state between
+calls. There is no disk, database or object storage in its boundary to encrypt.
+
+A caller who persists a key or a seed produced by this package is performing
+data-at-rest protection in their own system, with their own choice of
+algorithm, and this package neither sees nor constrains it. The one supported
+route that removes the question is `kxco-pq-hsm`, which generates ML-DSA keys
+on a PKCS#11 token with `CKA_EXTRACTABLE=false`, after which this package
+handles verification only and touches no secret.
+
+## 3. Identity, authentication and certificates
+
+**Applicable, and quantum-safe within the package.**
+
+No X.509. No certificate chain, no path validation, no revocation. Identity
+here is a raw key plus a key identifier, and the package deliberately does not
+pretend to be a PKI.
+
+| Use | Algorithm | Quantum-safe |
+|---|---|---|
+| Signature and verification | ML-DSA-65, ML-DSA-87 (FIPS 204) | Yes |
+| Hash-based alternative | SLH-DSA, ten parameter sets (FIPS 205) | Yes |
+| Key identifier | SHA-256 over the public key, truncated to 16 hex characters (`kid.js`) | Yes, second-preimage bound |
+| Key interchange | JWK `kty: AKP` per RFC 9964, and PKCS#8 seed export | Format, not an algorithm |
+| JWS signing | ML-DSA over the JWS signing input (`jws.js`) | Yes |
+| Webhook delivery signing | HMAC-SHA-256 **and** ML-DSA-65, both (`webhook.js`) | Yes, hybrid |
+
+The `kid` is a truncated SHA-256, so it is a 64-bit identifier and not a
+security boundary. It identifies which key to try; it does not authenticate
+anything. Grover halves the preimage work on SHA-256 and the truncation
+dominates that anyway, which is why nothing in the package makes a trust
+decision on a `kid` alone.
+
+## 4. Code, firmware and update signing
+
+**Applicable, and quantum-safe.**
+
+Every release asset is signed with ML-DSA-65 by this package's own signing
+path, which means the signing of the package is performed by the thing being
+signed. The public key is committed to the repository at
+`release-signing-key.pub.hex` and published as a release asset, so a verifier
+can obtain it by a path other than the one that delivered the artefact.
+Verification is four lines and is in `README.md`.
+
+No firmware. The package ships no binary and no native build of its own; the
+native path calls the OpenSSL already present in the host runtime.
+
+| Use | Algorithm | Quantum-safe |
+|---|---|---|
+| Release asset signing | ML-DSA-65 | Yes |
+| Signature over the evidence bundle | ML-DSA-65, `.sig` beside each bundle | Yes |
+
+## 5. Key wrapping and key-encryption keys
+
+**Applicable in a limited form, and quantum-safe.**
+
+The package wraps no keys. It has no KEK hierarchy, no envelope encryption and
+no key store.
+
+What it does have is deterministic derivation, which occupies the same place in
+a design without being key wrapping. `keypairFromMaster` derives a per-purpose
+seed from a caller-held master secret using HKDF-SHA-512 with an empty salt and
+a caller-chosen `info` string, then generates the keypair from that seed. A
+master secret therefore stands in the position a KEK would occupy, and its
+protection is entirely the caller's.
+
+| Use | Algorithm | Quantum-safe |
+|---|---|---|
+| Seed derivation from a master secret | HKDF-SHA-512 (`derive.js`) | Yes, symmetric |
+| Key encapsulation offered to callers | ML-KEM-768, ML-KEM-1024 (FIPS 203) | Yes |
+| Hybrid key establishment | `deriveSeed` combines an ML-KEM shared secret with a classical secret through the KDF | Yes, holds if either half holds |
+
+## 6. Random number generation and entropy sources
+
+**Applicable, and this is the entry a reader should not skim.**
+
+**This package generates no randomness in its JavaScript backend.** There is no
+`randomBytes`, no `getRandomValues`, no `randomFillSync` anywhere in `src/`
+outside the native path. Every keypair is produced from a seed the caller
+supplies, either directly through `keypairFromSeed` or derived from a
+caller-held master through `keypairFromMaster`. Seed length is enforced against
+the FIPS parameter set and a wrong length is a `RangeError`, not a silent pad.
+
+The consequence is worth stating plainly: **in the JavaScript backend, the
+quality of every private key in this system is a property of the caller's
+entropy source, not of this package.** A caller who supplies a low-entropy seed
+gets a low-entropy key and the library cannot detect it. This is a deliberate
+design choice, because deterministic derivation is what makes the keys
+reproducible and the conformance vectors pinnable, but it relocates a security
+property rather than solving it.
+
+The native backend is different. `crypto.generateKeyPairSync` in `_native.node.js`
+delegates to Node and thence to the OpenSSL DRBG, so on that path entropy comes
+from the operating system.
+
+| Path | Entropy source | Whose responsibility |
+|---|---|---|
+| JavaScript backend | Caller-supplied seed | The caller |
+| JavaScript backend, derived | HKDF-SHA-512 over a caller-supplied master | The caller |
+| Native backend keygen | OpenSSL DRBG via `crypto.generateKeyPairSync` | The operating system |
+
+No category of quantum attack applies to a DRBG in the way it applies to a
+public-key primitive; the risk here is classical and it is entropy starvation.
+
+## 7. Telemetry, logging and audit-trail integrity
+
+**Not applicable.** The package emits no telemetry and writes no log. It keeps
+no state between calls, so there is no audit trail of its own to protect.
+
+Log integrity in the wider KXCO estate is `kxco-pq-audit`, a separate package:
+SHA-256 hash-chained entries, each signed with ML-DSA-65, with periodic seals
+anchored on Armature L1 so that a verifier who does not trust the log operator
+still has an independent time bound. What this package contributes to that is
+the signature primitive and nothing else.
+
+## 8. Build, CI/CD and supply-chain signing
+
+**Applicable, and quantum-safe for what we sign, classical for what GitHub and
+npm sign.** This split is the honest answer and collapsing it would be an
+overclaim.
+
+| Use | Algorithm | Quantum-safe |
+|---|---|---|
+| Release assets and evidence bundle | ML-DSA-65, ours | Yes |
+| SLSA provenance attestation | Sigstore, classical (ECDSA and the Fulcio and Rekor chain) | **No** |
+| npm registry signature and provenance | npm's own, classical | **No** |
+| Reproducible build | Not a signature. The published tarball rebuilds bit-for-bit from its own tag, verified in CI on every run | Not applicable |
+| CycloneDX SBOM | Generated by `npm sbom` from the published tree; integrity carried by the ML-DSA signature over the release | Yes, via the release signature |
+
+The reproducible build is the part of this category that does not depend on any
+signature algorithm at all, and it is the reason the classical rows above are a
+weaker residual than they look: a verifier who rebuilds from source is not
+trusting Sigstore, npm or us.
+
+## 9. Attestation and remote attestation
+
+**Applicable in the supply-chain sense only.**
+
+There is no hardware attestation, no TPM quote, no confidential-computing
+report and no remote-attestation protocol in this package.
+
+What exists is build attestation: an in-toto statement at
+`evidence.intoto.jsonl` and an evidence manifest that pins the commit, the
+toolchain, the backend, the dependency versions and every step with its exact
+command, result and duration, with a SHA-256 for each file in the bundle. The
+in-toto and SLSA layer is signed classically by Sigstore, as row 2 of category
+8 records. The manifest and bundle are additionally signed with ML-DSA-65 by us.
+
+## 10. Backup, archival and long-term storage
+
+**Applicable as a stated gap, and this is the weakest category.**
+
+Verification of old records holds: 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 the control that would catch a change breaking them.
+
+Long-term trust does not hold and is a different question. This package has no
+notion of key validity windows, no revocation and no trusted timestamps. It can
+tell you a signature is arithmetically valid. It cannot tell you the key was
+still trusted when the signature was made. Anything that has to hold for years
+needs a time anchor outside the signature. Inside the KXCO estate that anchor
+is `kxco-pq-audit`'s on-chain seals. Outside it, this is a gap the deployment
+has to close, and this package should not be cited as closing it.
+
+## Summary
+
+| # | Category | Status |
+|---|---|---|
+| 1 | Data in transit | Library N/A; delivery is classical TLS, signature-mitigated |
+| 2 | Data at rest | N/A, no persistence |
+| 3 | Identity, authentication, certificates | Quantum-safe, no X.509 |
+| 4 | Code, firmware, update signing | Quantum-safe |
+| 5 | Key wrapping and KEKs | Quantum-safe, no wrapping; master secret is the caller's |
+| 6 | RNG and entropy | **Relocated to the caller** in the JavaScript backend |
+| 7 | Telemetry, logging, audit integrity | N/A, separate package |
+| 8 | Build, CI/CD, supply chain | Split: ours quantum-safe, Sigstore and npm classical |
+| 9 | Attestation | Build attestation only, classically signed at the Sigstore layer |
+| 10 | Backup, archival, long-term | **Gap.** No timestamps, validity windows or revocation |
+
+Three residuals carry forward into `PQCMM.md` and `HNDL.md` rather than being
+recorded only here: classical release transport, the classical Sigstore and npm
+signature layer, and the absence of long-term validation.

package/HNDL.md

@@ -0,0 +1,84 @@
+# HNDL exposure register
+
+Harvest-now-decrypt-later exposure for `kxco-post-quantum` 1.7.2, as required
+at Level 3 of the PKI Consortium PQCMM: which data flows handled by the product
+carry a long-lived confidentiality requirement, and which algorithm protects
+each.
+
+## What HNDL is, and why most of this register is short
+
+HNDL is a confidentiality attack. An adversary records ciphertext today and
+decrypts it once a cryptographically relevant quantum computer exists. It
+applies to data whose confidentiality must outlast that machine.
+
+It does **not** apply to signatures in the same way. A signature forged in 2040
+is worthless against a document verified in 2026, because the verification
+already happened. The quantum risk to a signature scheme is forgery of *future*
+verifications, which is an integrity and non-repudiation problem with a
+different shape and a different deadline. Registers that fold the two together
+overstate their own exposure, and this one keeps them apart.
+
+**This package is predominantly a signing library.** Most of what it handles is
+therefore outside HNDL by nature, and the register is short for a real reason
+rather than an incomplete one. Where confidentiality genuinely is at stake, the
+rows below say so.
+
+## Register
+
+| # | Data flow | Long-lived confidentiality? | Protected by | Quantum-safe | Residual |
+|---|---|---|---|---|---|
+| 1 | Private keys and seeds held in caller memory | **Yes, for the key's whole life** | Nothing in this package. Caller's process isolation | Not a cryptographic control | **The primary exposure.** See below |
+| 2 | Master secret used by `keypairFromMaster` | **Yes, and it is worse than a single key** | Nothing in this package. Caller's storage | Not a cryptographic control | Compromise derives every child key, past and future |
+| 3 | ML-KEM shared secret, in transit | Depends entirely on the caller's use | ML-KEM-768 or ML-KEM-1024 (FIPS 203) | **Yes** | The classical half of a hybrid pairing, if the caller adds one |
+| 4 | Payload a caller encrypts under an ML-KEM-derived key | Caller's to determine | The caller's AEAD, not ours | Symmetric, so Grover only | Key size is the caller's choice; this package does not perform the encryption |
+| 5 | Package delivery over TLS to npm or GitHub | **No** | Classical TLS | No | Confidentiality is irrelevant: the package is public. Integrity is the concern and ML-DSA-65 covers it |
+| 6 | Signatures, JWS, webhook envelopes | **No** | ML-DSA-65 or SLH-DSA, plus HMAC-SHA-256 on webhooks | Yes | Integrity risk, not HNDL. Recorded here only so its absence is deliberate |
+| 7 | Evidence bundle and SBOM | **No** | Published deliberately | Not applicable | Public by design |
+| 8 | Keys held on a PKCS#11 token via `kxco-pq-hsm` | Yes, but outside this boundary | `CKA_EXTRACTABLE=false` | Hardware control | The vendor's channel to the token is the vendor's, per `BOUNDARY.md` |
+
+## The two rows that matter
+
+**Rows 1 and 2 are the real HNDL exposure of this product, and neither is
+solved by a post-quantum algorithm.**
+
+A private key is confidential for its entire life, which is exactly the
+long-lived requirement HNDL describes. An adversary who harvests a stored
+ML-DSA private key today does not need a quantum computer at all; they need the
+key. The algorithm being post-quantum protects the signature against
+cryptanalysis, not the key against theft. So the strongest post-quantum
+posture in this package does nothing for its largest confidentiality asset.
+
+Row 2 is worse in one specific way. A master secret under HKDF-SHA-512
+regenerates every derived keypair, for every `info` string, past and future. It
+is a single point whose compromise is not bounded in time. That is the correct
+tradeoff for reproducible keys and pinnable conformance vectors, and it is the
+right design, but the concentration of risk should be visible rather than
+implied.
+
+Neither row has a cryptographic mitigation available inside a library. What
+exists is the escape in row 8: `kxco-pq-hsm` generates keys on a PKCS#11 token
+with `CKA_EXTRACTABLE=false`, after which this package handles verification
+only and touches no secret. **A deployment with a long-lived confidentiality
+requirement on its keys should be using that path, and this register exists in
+part to say so.**
+
+## What this register does not cover
+
+Callers. This package has no visibility into what a caller encrypts, how long
+they need it confidential, or where they put a key. Rows 3 and 4 are marked as
+the caller's to determine because they genuinely are, and a register claiming
+otherwise would be inventing knowledge it does not have.
+
+The absence of long-term validation, recorded as category 10 of
+`CRYPTO-INVENTORY.md`, is an adjacent gap rather than an HNDL one. No
+timestamps, no validity windows, no revocation. It bears on whether an old
+signature can still be trusted, not on whether old ciphertext can be read.
+
+## Review
+
+This register is a claim about a shipped version and it ages. It should be
+re-read whenever a new cryptographic use case enters the package, whenever a
+category in `CRYPTO-INVENTORY.md` changes status, and on any change to how
+seeds or master secrets are handled.
+
+Last reviewed against 1.7.2 on 2026-09-09.

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/PQCMM.md

@@ -0,0 +1,164 @@
+# PQC Maturity Model self-assessment
+
+PKI Consortium PQC Maturity Model (PQCMM), assessed against the model as
+published at <https://pkic.org/wg/pqc/pqcmm/>.
+
+**Declared level: 3 (Advanced).**
+
+A self-assessment is indicative, not authoritative. It is the vendor's own view
+and it has not been independently verified. The model says relying parties
+should treat a self-assessed level as a signal rather than a guarantee, and that
+is how this document should be read. Where a criterion is not met, this document
+says so and names what is missing rather than reporting a partial as a pass.
+
+## Scope
+
+| Field | Value |
+|---|---|
+| Product | `kxco-post-quantum` |
+| Version assessed | 1.7.2 |
+| Commit | `90b5778b4d19ed0f78715e143a6a50b9170b70f9`, clean tree |
+| Registry | <https://www.npmjs.com/package/kxco-post-quantum> |
+| Licence | Apache-2.0 |
+| Assurance method | Self-assessment |
+| Date | 2026-09-09 |
+
+A PQCMM assessment applies to a single product. The other `kxco-pq-*` packages
+depend on this one and are not covered here; each needs its own assessment.
+
+## Evidence available to an assessor
+
+Everything cited below is a permanent unauthenticated URL. No account, no
+request to us, no expiring artifact.
+
+| Artefact | Path under the release |
+|---|---|
+| Evidence manifest | `releases/latest/download/manifest-node24.x.json` |
+| Evidence bundle | `releases/latest/download/evidence-node24.x.zip` |
+| CycloneDX SBOM | `releases/latest/download/sbom.cyclonedx.json` |
+| In-toto attestation | `releases/latest/download/evidence.intoto.jsonl` |
+| Release signing key | `releases/latest/download/release-signing-key.pub.hex` |
+
+Base: `https://github.com/KnightsbridgeAIQ/kxco-post-quantum/`
+
+Two documents in the repository carry the Level 3 evidence and are cited
+throughout: `CRYPTO-INVENTORY.md` for the ten-category cryptographic inventory,
+and `HNDL.md` for the harvest-now-decrypt-later exposure register.
+
+The manifest pins the commit, the toolchain (Node 24.20.0, OpenSSL 3.5.7), the
+backend, the dependency versions, and every step with its exact command, its
+result and its duration. Each file in the bundle carries its SHA-256. The
+conformance and interop runs are reproducible from the commands recorded in the
+manifest rather than taken on our word.
+
+## Level 1, Initial: MET
+
+| # | Criterion | Answer | Evidence |
+|---|---|---|---|
+| 1 | A quantum-safe algorithm in a released build | Yes | ML-DSA-65 (FIPS 204), ML-KEM-768 (FIPS 203), SLH-DSA-SHA2-192s (FIPS 205) in 1.7.2 on the public npm stable channel. Category 5 sets ML-DSA-87 and ML-KEM-1024 also ship. |
+| 2 | The feature can be enabled | Yes | Available on import. No flag, no custom build, no source modification. |
+| 3 | Documented for evaluation | Yes | `README.md`, with a per-function API reference. |
+
+Release channel is stable and public, available to all consumers, with no
+programme enrolment. Ten SLH-DSA parameter sets are exposed, not one.
+
+## Level 2, Foundational: MET
+
+| # | Criterion | Answer | Evidence |
+|---|---|---|---|
+| 1 | Quantum-safe algorithms in core production functionality | Yes | Signing, key encapsulation, key derivation and fingerprinting are the product's core, not a preview channel. |
+| 2 | Compatibility with a published standard from a recognised body | Yes | NIST FIPS 203, 204 and 205. |
+| 3a | Standards-conformance testing | Yes | 2,103 NIST ACVP vectors: 1,793 passed, 0 failed, 310 skipped. Every skip is this library refusing a pre-hash weaker than the parameter set, listed individually with its reason. A skip is not counted as a pass. See `CONFORMANCE.md` and manifest steps `acvp`, `acvp-fips205`, `acvp-fips205-siggen`. |
+| 3b | Interoperability against an independent conformant implementation | Yes, four of them | 225 cross-implementation checks, 0 failed, both directions, with negative controls, against liboqs, Bouncy Castle and two pure-Python implementations. Run against both backends. Manifest step `interop`. |
+| 3c | Functional security testing as configured for production | Yes | `npm test` recorded in the manifest, plus the fuzz corpus under `fuzz/`. |
+| 3d | Smoke performance test under representative load | Yes | `BENCHMARKS.md`: per-algorithm p95 and p99 on both backends, on x86-64 and arm64, plus memory. |
+| 4 | Documented for production use including known limitations | Yes | `THREAT-MODEL.md` for what is and is not defended, `BOUNDARY.md` for which cryptography this package performs versus depends on versus offers, plus `LIFECYCLE.md` and `MIGRATION.md`. |
+
+Level 2 asks for CAVP or ACVTS results "or equivalent". Ours are the NIST ACVP
+vectors run by us and published with the commands to reproduce them. That is
+equivalent evidence, not a NIST certificate. **There is no CAVP certificate
+number for this product.** An assessor checking the CAVP or CMVP database will
+find nothing, and should record that.
+
+## Level 3, Advanced: MET
+
+| # | Criterion | Answer | Evidence |
+|---|---|---|---|
+| 1 | Full cryptographic inventory across every applicable taxonomy category | Yes | `CRYPTO-INVENTORY.md` covers all ten categories. Four are marked not applicable with a written reason; none is omitted. |
+| 2 | Non-quantum-safe features documented and flagged | Yes | `BOUNDARY.md`, "The gaps, collected", and the classical rows of `CRYPTO-INVENTORY.md` categories 1, 8 and 9. |
+| 3 | SBOM or equivalent component inventory | Yes | CycloneDX SBOM as a release asset at a permanent URL, generated by `npm sbom` from the tree that was published. Manifest step `sbom`. |
+| 4 | Crypto agility, two algorithms selectable in the same role | Yes | ML-DSA-65 and SLH-DSA-SHA2-192s are both available in the signature role by configuration, which is two different algorithms rather than two parameter sets of one. `AGILITY.md` separates the replacement plan, the implemented mechanism and the interoperable transition, and states what the package does not give you. |
+| 5 | Documented HNDL exposure register | Yes | `HNDL.md`. Eight data flows, each with its confidentiality horizon, its protecting algorithm and its residual. |
+
+Writing the inventory against the taxonomy produced two findings that this
+package's own audit documents had not stated, and both are recorded rather than
+smoothed over.
+
+**The library generates no randomness in its JavaScript backend.** Every
+keypair comes from a caller-supplied seed, or from a master secret through
+HKDF-SHA-512. So in that backend the entropy quality of every private key is a
+property of the caller, not of this package, and the package cannot detect a
+weak seed. The native backend differs: `crypto.generateKeyPairSync` uses the
+OpenSSL DRBG. `CRYPTO-INVENTORY.md` category 6.
+
+**The largest HNDL exposure in this product has no post-quantum mitigation.**
+Private keys and, more sharply, the master secret behind `keypairFromMaster`
+are confidential for their whole life, which is precisely the long-lived
+requirement HNDL describes. A post-quantum algorithm protects the signature
+against cryptanalysis and does nothing for the key against theft. The available
+answer is the PKCS#11 path in `kxco-pq-hsm`, not an algorithm choice here.
+`HNDL.md`, rows 1 and 2.
+
+## Level 4, Managed: NOT MET
+
+| # | Criterion | Answer | Evidence or gap |
+|---|---|---|---|
+| 1 | CBOM maintained | **No** | The product publishes an SBOM, not a CBOM. `CRYPTO-INVENTORY.md` now records each algorithm with its protocol context and usage purpose, which is the human-readable half of what a CBOM carries, but it is prose rather than a machine-readable CBOM and key sizes are stated by parameter set rather than per field. Closing this means emitting a CycloneDX CBOM as a release asset, which is a build change rather than a document. |
+| 2 | Zero-legacy capability across every in-scope component | **Not determined** | Not assessed against the model's wording, which extends to boot, firmware update signing, hardware-bound operations and internal diagnostics. Claiming it without that determination would be an overclaim. |
+| 3 | Symmetric and hash strengths adequate beyond CRQC availability | Yes | SHA-256 for key identifiers and webhook HMAC, SHA-512 under HKDF for seed derivation, via `@noble/hashes` 2.4.0. Per-use detail in `CRYPTO-INVENTORY.md`. |
+| 4 | Hybrid and composite support documented, with contexts | Partial | Hybrid is documented: `webhook` performs HMAC plus ML-DSA-65 delivery signing, and `deriveSeed` exists to combine an ML-KEM shared secret with a classical secret through a KDF. Composite, in the algorithm-fused sense, is not supported and is not currently stated as unsupported. |
+
+## Level 5, Optimized: NOT MET
+
+| # | Criterion | Answer | Evidence or gap |
+|---|---|---|---|
+| 1 | Quantum-safe by default, legacy requires explicit enablement | Yes | There is no classical algorithm to fall back to. The default parameter set is Category 3. |
+| 2 | Benchmarked and tuned against operational requirements | Yes | `BENCHMARKS.md`. Two figures stated rather than hidden: ML-DSA signing keeps a rejection-sampling tail on either backend, and SLH-DSA-SHA2-192s signs in seconds rather than milliseconds. |
+| 3 | Primarily follows standards from a recognised body | Yes | FIPS 203, 204 and 205. |
+| 4 | **Independently verified or certified** | **No** | No FIPS 140 validation. No Common Criteria evaluation. The underlying `@noble/post-quantum` 0.7.0 has no published third-party formal security analysis covering the implemented PQC algorithms, so the library-based route in the model's wording is not available either. |
+
+Criterion 4 is the binding constraint and it cannot be closed by documentation.
+It requires a paid engagement: a CAVP or CMVP validation through an accredited
+laboratory, a Common Criteria evaluation, or a published independent audit of
+the cryptographic implementation.
+
+## Assessment methodology record
+
+The model requires this record to accompany an assessment.
+
+- **Evidence method.** Documentation review, plus the published evidence
+  manifest, plus verification of the licence state of every published package
+  against the public npm registry on 2026-09-09.
+- **Cryptographic library.** `@noble/post-quantum` 0.7.0 and `@noble/hashes`
+  2.4.0 in the JavaScript backend; `node:crypto` on OpenSSL 3.5.7 in the native
+  backend. Both versions are recorded in the manifest. `@noble/post-quantum` is
+  maintained, and its PQC support is confirmed from its public repository. It
+  has **not** been independently audited. Version 0.7.1 is deliberately not
+  adopted because it regressed SLH-DSA, so the dependency is pinned at 0.7.0.
+- **Reproduction attempts.** All conformance, interop, test and SBOM steps in
+  the manifest ran in CI from a clean tree at commit `90b5778`, on Node
+  24.20.0, linux-x64, on 2026-09-08. Every step reports `ok: true`, and
+  `sampling.full` is `true`.
+- **Public database checks.** npm registry, all sixteen published `kxco-*`
+  packages, 2026-09-09: every one reports `Apache-2.0`. NIST CAVP and CMVP: no
+  certificate exists for this product, confirmed rather than assumed.
+- **Unverified claims.** Every criterion answered Yes above is vendor-stated and
+  not independently verified. That is what a self-assessment is. The manifest
+  and the bundle exist so that an assessor can convert these into verified
+  findings without asking us for anything.
+
+## Corrections
+
+If any statement here is wrong, it should be corrected here first, and the
+correction dated. Facts about this package that are commonly recorded wrongly,
+with the one-line check for each, are listed at the top of `README.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.
 
 ---
@@ -333,7 +336,7 @@ Install this package directly when you need ML-DSA or ML-KEM without the rest of
 
 ## Security
 
-Cryptographic operations delegate entirely to [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) and [`@noble/hashes`](https://github.com/paulmillr/noble-hashes) — this package does not reimplement any NIST primitive. `@noble/hashes` falls under Cure53's 2023 audit of the `@noble` ecosystem (`ciphers`, `curves`, `hashes`); `@noble/post-quantum` was **not** in that audit's scope and has been self-audited by its maintainer. See [AUDIT.md](./AUDIT.md) for the full posture.
+Cryptographic operations delegate entirely to [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) and [`@noble/hashes`](https://github.com/paulmillr/noble-hashes); this package does not reimplement any NIST primitive. `@noble/post-quantum` has never been audited by a third party. It has been self-audited by its maintainer (v0.6.1, April 2026). The other Noble packages were audited separately, at different dates, and none of those engagements covered the post-quantum package: `@noble/hashes` by Cure53 in January 2022, `@noble/curves` by Trail of Bits in February 2023, Kudelski Security in September 2023 and Cure53 in September 2024, and `@noble/ciphers` by Cure53 in September 2024. See [AUDIT.md](./AUDIT.md) for the full posture.
 
 To report a vulnerability: [open a private security advisory](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/security/advisories/new) or email **john@knightsbridgelaw.com**. Acknowledgement within 2 business days, triage decision within 5. Full policy, including safe harbour for good-faith research: <https://kxco.ai/security>.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.7.1",
+  "version": "1.7.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: 1,793 passed, 0 failed, 310 skipped. 225 interop checks, 0 failed. Reproducible builds and provenance.",
   "keywords": [
     "post-quantum",
@@ -12,6 +12,7 @@
     "dilithium",
     "kyber",
     "nist",
+    "acvp",
     "fips-203",
     "fips-204",
     "fips-205",
@@ -61,61 +62,79 @@
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
-      "import": "./src/index.js"
+      "import": "./src/index.js",
+      "default": "./src/index.js"
     },
     "./ml-dsa": {
       "types": "./src/ml-dsa.d.ts",
-      "import": "./src/ml-dsa.js"
+      "import": "./src/ml-dsa.js",
+      "default": "./src/ml-dsa.js"
     },
     "./ml-dsa-87": {
       "types": "./src/ml-dsa-87.d.ts",
-      "import": "./src/ml-dsa-87.js"
+      "import": "./src/ml-dsa-87.js",
+      "default": "./src/ml-dsa-87.js"
     },
     "./ml-kem": {
       "types": "./src/ml-kem.d.ts",
-      "import": "./src/ml-kem.js"
+      "import": "./src/ml-kem.js",
+      "default": "./src/ml-kem.js"
     },
     "./ml-kem-1024": {
       "types": "./src/ml-kem-1024.d.ts",
-      "import": "./src/ml-kem-1024.js"
+      "import": "./src/ml-kem-1024.js",
+      "default": "./src/ml-kem-1024.js"
     },
     "./slh-dsa": {
       "types": "./src/slh-dsa.d.ts",
-      "import": "./src/slh-dsa.js"
+      "import": "./src/slh-dsa.js",
+      "default": "./src/slh-dsa.js"
     },
     "./derive": {
       "types": "./src/derive.d.ts",
-      "import": "./src/derive.js"
+      "import": "./src/derive.js",
+      "default": "./src/derive.js"
     },
     "./webhook": {
       "types": "./src/webhook.d.ts",
-      "import": "./src/webhook.js"
+      "import": "./src/webhook.js",
+      "default": "./src/webhook.js"
     },
     "./kid": {
       "types": "./src/kid.d.ts",
-      "import": "./src/kid.js"
+      "import": "./src/kid.js",
+      "default": "./src/kid.js"
     },
     "./seed": {
       "types": "./src/seed.d.ts",
-      "import": "./src/seed.js"
+      "import": "./src/seed.js",
+      "default": "./src/seed.js"
     },
     "./jws": {
       "types": "./src/jws.d.ts",
-      "import": "./src/jws.js"
+      "import": "./src/jws.js",
+      "default": "./src/jws.js"
     },
     "./backend": {
       "types": "./src/backend.d.ts",
-      "import": "./src/backend.js"
+      "import": "./src/backend.js",
+      "default": "./src/backend.js"
     }
   },
   "files": [
+    "AGILITY.md",
     "BENCHMARKS.md",
+    "BOUNDARY.md",
     "CHANGELOG.md",
     "CONFORMANCE.md",
+    "CRYPTO-INVENTORY.md",
     "DEPENDENCIES.md",
+    "HNDL.md",
     "LICENCE-PRODUCT.md",
     "LICENSE",
+    "LIFECYCLE.md",
     "MIGRATION.md",
+    "PQCMM.md",
     "README.md",
     "SECURITY.md",
     "THREAT-MODEL.md",
@@ -129,6 +148,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'