kxco-post-quantum 1.7.9 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 1.9.0 (2026-10-07)
+
+`jws.signJws` takes its default from the key, and the default is ML-DSA-87.
+Without `opts.alg`, a 4032-byte ML-DSA-65 secret key signs `ML-DSA-65`, as it
+always has, and every other key signs `ML-DSA-87`. An ML-DSA-87 key no longer
+needs `alg` named, where before it threw. The key is measured by its byte
+length, so a key held as an ArrayBuffer is read as its own set. A token signed
+by 1.8.0 verifies unchanged, which a fixture now tests.
+
+To keep the old behaviour, name the set:
+`signJws(payload, secretKey, { alg: 'ML-DSA-65' })`. An existing ML-DSA-65 key
+needs no change, because its size already selects ML-DSA-65.
+
+The README leads with ML-DSA-87. The quick start, the examples and the API
+section use `mlDsa87`, and `mlDsa` is described as the ML-DSA-65 namespace kept
+for keys that already exist. Its name and exports do not change. MIGRATION.md
+and the source comments recommend ML-DSA-87 for every new signing key.
+
+**Each release carries a CycloneDX 1.6 CBOM**, at
+`releases/latest/download/cbom.cyclonedx.json` and inside the signed evidence
+bundle as `05b-cbom.cyclonedx.json`. It lists every algorithm the package offers
+(ML-DSA-65, ML-DSA-87, ML-KEM-768, ML-KEM-1024, SLH-DSA-SHA2-192s, HKDF-SHA-512,
+HMAC-SHA-256, SHA-256), the four the native backend runs only to probe OpenSSL,
+and the classical ECDSA of the npm registry and Sigstore signatures. Each carries
+its OID, NIST category, purpose, protocol context, key and signature sizes in
+bits, and the file and line where the source uses it.
+
+`scripts/build-cbom.mjs` reconciles the CBOM against `src/`, and `npm test` and
+the evidence build fail if the source uses an algorithm the CBOM does not
+declare. PQCMM Level 4 criterion 1 moves to met; Level 4 as a whole stays not
+met while zero-legacy capability is undetermined.
+
+`PQCMM.md` and `CRYPTO-INVENTORY.md` said SLH-DSA was offered in ten parameter
+sets. The API offers one, SLH-DSA-SHA2-192s, and the conformance suite checks the
+underlying implementation for all twelve. Both documents now say so.
+
+## 1.8.0
+The webhook helpers sign and verify with ML-DSA-87 keys. The key decides the
+X-KXCO-PQ-Signature form: pqSign and signDelivery give `ml-dsa-87=<hex>` for
+an ML-DSA-87 secret key and `ml-dsa-65=<hex>` for an ML-DSA-65 one, unchanged.
+verifyPq and verifyDelivery verify under the set of the public key they are
+given and accept only that set's prefix, so a header naming the other set
+fails. An ML-DSA-65 key still accepts the bare hex value, and a delivery signed
+by 1.7.9 verifies unchanged, which a fixture now tests. The webhook contract in
+`spec/` describes the `ml-dsa-87=` form.
+
 ## 1.7.9
 
 verifyDelivery reads each header only as a string. A header that arrives as an

package/CRYPTO-INVENTORY.md

@@ -63,7 +63,7 @@ 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 |
+| Hash-based alternative | SLH-DSA-SHA2-192s (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 |
@@ -170,6 +170,7 @@ overclaim.
 | 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 |
+| CycloneDX CBOM | This inventory in machine-readable form, built by `scripts/build-cbom.mjs` and reconciled against `src/` on every build; integrity carried by the ML-DSA signature over the evidence bundle that contains it | 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

package/MIGRATION.md

@@ -15,8 +15,8 @@ Two separate problems, in order:
 
 | You need | Use | Why |
 |---|---|---|
-| Signatures, general use | `mlDsa` (ML-DSA-65) | Category 3. Fast, 3309-byte signatures. The default. |
-| Signatures, Category 5 required | `mlDsa87` (ML-DSA-87) | When a counterparty specifies Category 5 or names ML-DSA-87. Signatures are 4627 bytes. |
+| Signatures, new keys | `mlDsa87` (ML-DSA-87) | Category 5. 4627-byte signatures. The default, and what `jws.signJws` signs with unless the key is an ML-DSA-65 one. |
+| Signatures, existing ML-DSA-65 keys | `mlDsa` (ML-DSA-65) | Category 3. 3309-byte signatures. Kept so the keys and signatures that already exist keep working. |
 | Signatures, no lattice assumption | `slhDsa` (SLH-DSA-SHA2-192s) | Hash-based, so it does not share ML-DSA's underlying assumption. Signatures are 16 KB and signing takes seconds. |
 | Key establishment | `mlKem` (ML-KEM-768) | Category 3, matching ML-DSA-65. |
 | Key establishment, Category 5 required | `mlKem1024` (ML-KEM-1024) | Public key and ciphertext are 1568 bytes each. The shared secret stays 32 bytes. |
@@ -24,9 +24,10 @@ Two separate problems, in order:
 **On CNSA 2.0.** It names ML-DSA-87 and ML-KEM-1024, and both are available
 here. Availability is not compliance: CNSA 2.0 compliance is a property of a
 deployment, and picking `mlDsa87` for one call path does not confer it on a
-system whose other signatures, identities and anchors are Category 3. Use the
-Category 5 sets when someone asks for the parameter set. Do not use their
-presence as the basis for a compliance statement.
+system whose other signatures, identities and anchors are Category 3. Use
+ML-DSA-87 for every new signing key, and ML-KEM-1024 when someone asks for the
+parameter set. Do not use their presence as the basis for a compliance
+statement.
 
 Two points that catch people out:
 

package/PQCMM.md

@@ -36,6 +36,7 @@ request to us, no expiring artifact.
 | 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` |
+| CycloneDX CBOM | `releases/latest/download/cbom.cyclonedx.json` |
 | In-toto attestation | `releases/latest/download/evidence.intoto.jsonl` |
 | Release signing key | `releases/latest/download/release-signing-key.pub.hex` |
 
@@ -60,7 +61,9 @@ manifest rather than taken on our word.
 | 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.
+programme enrolment. One SLH-DSA parameter set is offered, SLH-DSA-SHA2-192s,
+and the conformance suite checks the underlying implementation against NIST's
+vectors for all twelve.
 
 ## Level 2, Foundational: MET
 
@@ -113,7 +116,7 @@ answer is the PKCS#11 path in `kxco-pq-hsm`, not an algorithm choice here.
 
 | # | 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. |
+| 1 | CBOM maintained | Yes, from 1.9.0 | A CycloneDX 1.6 CBOM ships on every release from 1.9.0 at `releases/latest/download/cbom.cyclonedx.json` and inside the ML-DSA-signed evidence bundle. It carries each algorithm with its OID, NIST category, usage purpose and protocol context; key, signature, ciphertext and seed sizes per field, in bits; and the file and line where the source uses it. It includes what the package executes but does not offer (the native backend's capability probes) and the classical release layer (the npm registry and Sigstore signatures, both ECDSA). It is maintained by construction: `scripts/build-cbom.mjs` reconciles it against `src/` and the build fails if the source uses an algorithm it does not declare, or if a declared use has gone. |
 | 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. |

package/README.md

@@ -11,12 +11,12 @@
 [![conformance](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/actions/workflows/conformance.yml/badge.svg)](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/actions/workflows/conformance.yml)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
-- **All three NIST standards.** ML-KEM-768 (FIPS 203), ML-DSA-65 (FIPS 204) and SLH-DSA-SHA2-192s (FIPS 205), all at NIST Category 3.
-- **The CNSA 2.0 parameter sets ship.** ML-DSA-87 and ML-KEM-1024 at Category 5, with the same API as the defaults.
+- **All three NIST standards.** ML-DSA-87 and ML-DSA-65 (FIPS 204), ML-KEM-768 (FIPS 203) and SLH-DSA-SHA2-192s (FIPS 205). ML-DSA-87 is the signature set for new keys, and ML-DSA-65 stays for keys that already exist.
+- **The CNSA 2.0 parameter sets ship.** ML-DSA-87 and ML-KEM-1024 at Category 5, with the same API as the Category 3 sets.
 - **1,793 NIST ACVP vectors passed, 0 failed.** The other 310 are pairings the library refuses as weaker than the parameter set. See [CONFORMANCE.md](./CONFORMANCE.md).
 - **Interoperable by test.** 225 checks against liboqs, Bouncy Castle and the Python reference implementations, in both directions, 0 failed. See [CONFORMANCE.md](./CONFORMANCE.md).
 - **Native speed on Node 24.** The maths runs in OpenSSL 3.5 on Node 24 and later, and in JavaScript on Node 20, Node 22 and in browsers, with identical bytes on the wire.
-- **Speaks the formats your stack already parses.** Compact JWS and AKP JWK under the `ML-DSA-65` and `ML-DSA-87` algorithm names, and PKCS#8 seed-form keys.
+- **Speaks the formats your stack already parses.** Compact JWS and AKP JWK under the `ML-DSA-87` and `ML-DSA-65` algorithm names, and PKCS#8 seed-form keys.
 - **A supply chain you can check.** Reproducible builds verified in CI, with SLSA provenance and a CycloneDX SBOM on every release since 1.4.1. Apache-2.0, with no licence check and nothing that phones home.
 
 **The migration has dates.**
@@ -30,9 +30,9 @@
 | The requirement | What answers it |
 |---|---|
 | Post-quantum key establishment by 31 Dec 2030, EO 14412 s.4(b)(ii) | `mlKem.encapsulate` and `mlKem.decapsulate`, ML-KEM-768 |
-| Post-quantum signatures by 31 Dec 2031, EO 14412 s.4(b)(iii) | `mlDsa.sign` and `mlDsa.verify`, ML-DSA-65 |
+| Post-quantum signatures by 31 Dec 2031, EO 14412 s.4(b)(iii) | `mlDsa87.sign` and `mlDsa87.verify`, ML-DSA-87 |
 | "PQC-agile libraries for all new applications", OMB M-26-15 | `mlDsa87` and `mlKem1024` behind the same API: Category 5 is a change of import |
-| "API gateways and application workloads must be configured to issue and validate PQC-signed tokens", OMB M-26-15 | `jws.signJws` and `jws.verifyJws`: compact JWS under ML-DSA-65 or ML-DSA-87, algorithm pinned at the verifier |
+| "API gateways and application workloads must be configured to issue and validate PQC-signed tokens", OMB M-26-15 | `jws.signJws` and `jws.verifyJws`: compact JWS under ML-DSA-87 or ML-DSA-65, algorithm pinned at the verifier |
 | "re-encrypting long-lived sensitive data using keys protected by PQC mechanisms", OMB M-26-15 | [`kxco-pq-vault`](https://www.npmjs.com/package/kxco-pq-vault) |
 | Minimum elements for a cryptographic bill of materials, in CISA guidance due by 19 Mar 2027, EO 14412 s.5(d) | [`kxco-pq-scan`](https://www.npmjs.com/package/kxco-pq-scan) `--cbom`: a CycloneDX 1.6 CBOM today, ready to check against those elements when CISA publishes them |
 
@@ -57,14 +57,14 @@ Requires Node.js 20.19+. ESM-only.
 ## Quick start
 
 ```js
-import { mlDsa, mlKem, slhDsa, fingerprint, kidEquals } from 'kxco-post-quantum'
+import { mlDsa87, mlKem, slhDsa, fingerprint, kidEquals } from 'kxco-post-quantum'
 
-// ML-DSA-65: sign and verify
-const { publicKey, secretKey } = mlDsa.keypairFromMaster(masterSecret, 'signing-65-v1')
-const sig = mlDsa.sign(secretKey, 'hello')
-const ok  = mlDsa.verify(publicKey, 'hello', sig)  // true
+// ML-DSA-87: sign and verify
+const { publicKey, secretKey } = mlDsa87.keypairFromMaster(masterSecret, 'signing-87-v1')
+const sig = mlDsa87.sign(secretKey, 'hello')
+const ok  = mlDsa87.verify(publicKey, 'hello', sig)  // true
 
-// SLH-DSA-SHA2-192s: hash-based signatures (same API shape as mlDsa)
+// SLH-DSA-SHA2-192s: hash-based signatures (same API shape as mlDsa87)
 const slh = slhDsa.keypairFromMaster(masterSecret, 'signing-slh-v1')
 const slhSig = slhDsa.sign(slh.secretKey, 'hello')
 const slhOk  = slhDsa.verify(slh.publicKey, 'hello', slhSig)  // true
@@ -86,10 +86,11 @@ const recovered = mlKem.decapsulate(ciphertext, kemKeys.secretKey)
 
 ### Category 5 parameter sets
 
-`mlDsa87` (ML-DSA-87) and `mlKem1024` (ML-KEM-1024) have the same API as `mlDsa`
-and `mlKem`, one security category higher. Reach for them when a counterparty
-specifies Category 5 or names the parameter set. The KXCO default stays
-Category 3.
+`mlDsa87` (ML-DSA-87) is the signature set for new keys. `mlDsa` (ML-DSA-65) has
+the same API, one security category lower, and stays for the keys that already
+exist, whose signatures keep verifying. `mlKem1024` (ML-KEM-1024) has the same
+API as `mlKem`, one security category higher. Reach for it when a counterparty
+specifies Category 5 or names the parameter set.
 
 ```js
 import { mlDsa87, mlKem1024 } from 'kxco-post-quantum'
@@ -99,10 +100,10 @@ const sig = mlDsa87.sign(secretKey, 'hello')      // 4627 bytes, 9254 hex chars
 mlDsa87.verify(publicKey, 'hello', sig)           // true
 ```
 
-| | Category 3 (default) | Category 5 |
+| | Category 5 | Category 3 |
 |---|---|---|
-| Signatures | `mlDsa`: pk 1952, sig 3309 | `mlDsa87`: pk 2592, sig 4627 |
-| Key encapsulation | `mlKem`: pk 1184, ct 1088 | `mlKem1024`: pk 1568, ct 1568 |
+| Signatures | `mlDsa87`: pk 2592, sig 4627, for new keys | `mlDsa`: pk 1952, sig 3309, for existing keys |
+| Key encapsulation | `mlKem1024`: pk 1568, ct 1568 | `mlKem`: pk 1184, ct 1088 |
 
 The two sets do not mix, deliberately. Default derivation info differs, so one
 master yields unrelated keys for each, and so does a distinct label of your own;
@@ -120,16 +121,16 @@ signature made under a context does not verify without it, or under a different
 one.
 
 ```js
-const sig = mlDsa.sign(secretKey, 'hello', { context: 'kxco-nexus-v1' })
+const sig = mlDsa87.sign(secretKey, 'hello', { context: 'kxco-nexus-v1' })
 
-mlDsa.verify(publicKey, 'hello', sig, { context: 'kxco-nexus-v1' })  // true
-mlDsa.verify(publicKey, 'hello', sig)                                // false
-mlDsa.verify(publicKey, 'hello', sig, { context: 'other-v1' })       // false
+mlDsa87.verify(publicKey, 'hello', sig, { context: 'kxco-nexus-v1' })  // true
+mlDsa87.verify(publicKey, 'hello', sig)                                // false
+mlDsa87.verify(publicKey, 'hello', sig, { context: 'other-v1' })       // false
 ```
 
 The parameter is optional and defaults to no context, so every existing call
-site is unaffected. An empty context is identical to omitting it. `slhDsa` takes
-the same option.
+site is unaffected. An empty context is identical to omitting it. `mlDsa` and
+`slhDsa` take the same option.
 
 **Context separates at the signature level; `keypairFromMaster(master, info)`
 separates at the key level.** They are complementary. Use a context when one key
@@ -143,8 +144,8 @@ characters. Over-length or wrongly typed input throws (`RangeError` /
 a bad signature:
 
 ```js
-mlDsa.sign(secretKey, 'hello', 'kxco-nexus-v1')  // throws TypeError
-                                                 // (needs { context: ... })
+mlDsa87.sign(secretKey, 'hello', 'kxco-nexus-v1')  // throws TypeError
+                                                   // (needs { context: ... })
 ```
 
 That last case is worth guarding: without the throw it would silently sign with
@@ -176,8 +177,25 @@ between free and paid is set out in [LICENCE-PRODUCT.md](./LICENCE-PRODUCT.md).
 
 ## API
 
+### `mlDsa87`: ML-DSA-87 signatures (NIST FIPS 204)
+
+The signature set for new keys. Security Category 5.
+
+| Export | Signature | Description |
+|---|---|---|
+| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey, seed }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-dsa-87-v1'`. `seed` is the 32 bytes the pair was expanded from. See [`seed`](#seed-seed-form-keys-rfc-9964-lamps). |
+| `sign` | `(secretKey, message) → string` | Signs a message. Returns a hex-encoded signature (9254 chars). |
+| `verify` | `(publicKey, message, sigHex) → boolean` | Verifies a hex-encoded signature. Returns `false` on any failure. |
+| `ml_dsa87` | raw primitive | The underlying `@noble/post-quantum` primitive, re-exported. |
+
+`publicKey` is 2592 bytes. `secretKey` is 4896 bytes. `message` accepts `Buffer`, `Uint8Array`, or `string`.
+
 ### `mlDsa`: ML-DSA-65 signatures (NIST FIPS 204)
 
+The ML-DSA-65 namespace, kept for keys that already exist. Same API as
+`mlDsa87`, at Security Category 3. Its name and exports are unchanged, and every
+signature it has made keeps verifying.
+
 | Export | Signature | Description |
 |---|---|---|
 | `keypairFromMaster` | `(master, info?) → { publicKey, secretKey, seed }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-dsa-65-v1'`. `seed` is the 32 bytes the pair was expanded from. See [`seed`](#seed-seed-form-keys-rfc-9964-lamps). |
@@ -189,7 +207,7 @@ between free and paid is set out in [LICENCE-PRODUCT.md](./LICENCE-PRODUCT.md).
 
 ### `slhDsa`: SLH-DSA-SHA2-192s signatures (NIST FIPS 205)
 
-Hash-based, stateless signatures. Security Category 3 (matching ML-DSA-65), with security resting only on the SHA-2 hash function: no lattice or number-theoretic assumptions. Use it as a conservative hedge alongside `mlDsa`. Signatures are 16,224 bytes against 3,309 for ML-DSA-65, per [FIPS 205](https://csrc.nist.gov/pubs/fips/205/final) and [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final), so `mlDsa` stays the default for high-volume signing.
+Hash-based, stateless signatures. Security Category 3 (matching ML-DSA-65), with security resting only on the SHA-2 hash function: no lattice or number-theoretic assumptions. Use it as a conservative hedge alongside `mlDsa87`. Signatures are 16,224 bytes against 4,627 for ML-DSA-87 and 3,309 for ML-DSA-65, per [FIPS 205](https://csrc.nist.gov/pubs/fips/205/final) and [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final), so ML-DSA stays the choice for high-volume signing.
 
 | Export | Signature | Description |
 |---|---|---|
@@ -251,24 +269,24 @@ OpenSSL writes, for every parameter set, and skips with a reason where there is
 no native backend to compare against.
 
 ```js
-import { mlDsa, seed } from 'kxco-post-quantum'
+import { mlDsa87, seed } from 'kxco-post-quantum'
 
-const key = mlDsa.keypairFromMaster(process.env.KXCO_MASTER_KEY)
-const jwk = seed.exportJwk('ML-DSA-65', key, { kid: fingerprint(key.publicKey) })
-// { kty: 'AKP', alg: 'ML-DSA-65', pub: '...', priv: '<32-byte seed>', kid: '...' }
+const key = mlDsa87.keypairFromMaster(process.env.KXCO_MASTER_KEY)
+const jwk = seed.exportJwk('ML-DSA-87', key, { kid: fingerprint(key.publicKey) })
+// { kty: 'AKP', alg: 'ML-DSA-87', pub: '...', priv: '<32-byte seed>', kid: '...' }
 ```
 
 ### `jws`: compact JWS with the RFC 9964 algorithm names
 
 Format only. A token signed here verifies in any process holding the public
 key, offline, with no configuration and no licence. RFC 9964 registered
-`ML-DSA-65` and `ML-DSA-87` as JWS algorithms so a post-quantum signature can
+`ML-DSA-87` and `ML-DSA-65` as JWS algorithms so a post-quantum signature can
 travel the path an institution's gateway, IdP and partner verifier already
 parse.
 
 | Export | Signature | Description |
 |---|---|---|
-| `signJws` | `(payload, secretKey, opts?) → string` | Compact JWS. Objects are JSON-serialised. `opts.alg` defaults to `ML-DSA-65`. |
+| `signJws` | `(payload, secretKey, opts?) → string` | Compact JWS. Objects are JSON-serialised. Without `opts.alg` the key decides: an ML-DSA-65 secret key signs `ML-DSA-65`, and every other key `ML-DSA-87`, the default. |
 | `verifyJws` | `(token, publicKey, opts?) → { valid, ... }` | Fails closed. `{ alg }` and `{ kid }` pin what the header may declare. |
 | `decodeJwsHeader` | `(token) → object \| null` | Unauthenticated read, for choosing which key to fetch. |
 
@@ -277,7 +295,7 @@ token, so a token cannot name its own verification routine. `crit` and `b64`
 headers are refused rather than ignored, and the public key's length must match
 the algorithm the header declares.
 
-The JWS algorithms are ML-DSA-65 and ML-DSA-87, the parameter sets sized for a
+The JWS algorithms are ML-DSA-87 and ML-DSA-65, the parameter sets sized for a
 request path.
 
 ### `backend()` and `isNative(alg)`
@@ -287,9 +305,11 @@ with its version and parameter sets, or `javascript` with the reason the native
 backend is unavailable. For evidence bundles and support tickets. It reports,
 and the operator selects, as the next section shows.
 
-### `webhook`: hybrid HMAC + ML-DSA-65 delivery signing
+### `webhook`: hybrid HMAC + ML-DSA delivery signing
+
+Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `verifyHmac`, `pqSign`, `verifyPq`, `signDelivery`, `verifyDelivery`. HMAC-SHA-256 gives symmetric verification with no library dependency; ML-DSA adds non-repudiation over the same `${timestamp}.${body}` envelope. The full identity/credential surface lives in `kxco-pq-sdk`.
 
-Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `verifyHmac`, `pqSign`, `verifyPq`, `signDelivery`, `verifyDelivery`. HMAC-SHA-256 gives symmetric verification with no library dependency; ML-DSA-65 adds non-repudiation over the same `${timestamp}.${body}` envelope. The full identity/credential surface lives in `kxco-pq-sdk`.
+The key decides the PQ header form. An ML-DSA-87 key signs `ml-dsa-87=<hex>`, and an ML-DSA-65 key signs `ml-dsa-65=<hex>` over the same envelope. `verifyPq` and `verifyDelivery` accept only the form that matches the public key they are given: a header whose prefix names the other set fails, and an ML-DSA-87 key takes no bare-hex form.
 
 ---
 
@@ -306,7 +326,7 @@ validated module, make the native backend a requirement:
 ```js
 import { requireNativeBackend } from 'kxco-post-quantum'
 
-requireNativeBackend(['ML-DSA-65', 'ML-KEM-768'])
+requireNativeBackend(['ML-DSA-87', 'ML-KEM-768'])
 ```
 
 It throws `ERR_KXCO_PQ_BACKEND` if the JavaScript backend is live, or if the
@@ -344,7 +364,7 @@ KXCO_PQ_BACKEND=openssl       prefer OpenSSL, which is the default anyway
 import { requireBackend } from 'kxco-post-quantum'
 
 requireBackend('javascript')                            // the JS certificate
-requireBackend('openssl', ['ML-DSA-65', 'ML-KEM-768'])  // the native one
+requireBackend('openssl', ['ML-DSA-87', 'ML-KEM-768'])  // the native one
 ```
 
 A value that is neither throws at import, so a misspelled pin is caught before
@@ -428,24 +448,25 @@ npm view kxco-post-quantum license          # Apache-2.0
 npm audit signatures --json                 # assert invalid:0 and missing:0
 ```
 
-Every release asset is signed with ML-DSA-65 by this package's own signing path,
+Every release asset is signed with ML-DSA-87 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-node24.x.zip.sig       ML-DSA-87 signature over the zip, hex
 evidence.intoto.jsonl           SLSA provenance
-release-signing-key.pub.hex     the public key, also committed to this repository
+release-signing-key-87.pub.hex  the ML-DSA-87 public key, also committed to this repository
+release-signing-key.pub.hex     the ML-DSA-65 key that signed releases before 1.9.0
 ```
 
 ```js
 import { readFileSync } from 'node:fs'
-import { mlDsa } from 'kxco-post-quantum'
+import { mlDsa87 } from 'kxco-post-quantum'
 
-const pub = Buffer.from(readFileSync('release-signing-key.pub.hex', 'utf8').trim(), 'hex')
+const pub = Buffer.from(readFileSync('release-signing-key-87.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
+mlDsa87.verify(pub, readFileSync('evidence-node24.x.zip'), sig)   // true
 ```
 
 Compare the public key with the copy committed to this repository, so the key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.7.9",
+  "version": "1.9.0",
   "description": "NIST post-quantum cryptography for Node.js and browsers: ML-DSA, ML-KEM and SLH-DSA (FIPS 203, 204, 205). 1,793 NIST ACVP vectors passed, 0 failed. OpenSSL 3.5 native on Node 24+, the CNSA 2.0 parameter sets, reproducible builds with provenance.",
   "keywords": [
     "post-quantum",
@@ -159,7 +159,7 @@
   },
   "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 test/property.test.js && node test/run-vectors.js",
+    "test": "node --test test/basic.test.js && node --test test/webhook-ml-dsa-87.test.js && node --test test/jws-ml-dsa-87-default.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 test/property.test.js && node --test test/cbom.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",
@@ -169,6 +169,7 @@
     "conformance:protocol": "node conformance/protocol/run-protocol.mjs --json conformance/results/protocol.json",
     "audit:deps": "node audit/run-audit.mjs --json audit/results/dependencies.json",
     "sbom": "npm sbom --sbom-format cyclonedx --sbom-type library",
+    "cbom": "node scripts/build-cbom.mjs",
     "bench:timing": "node --expose-gc bench/timing.mjs --iterations 20000 --json bench/results/timing.json",
     "bench:primitives": "node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/primitives.json",
     "evidence": "node scripts/build-evidence.mjs",
@@ -179,6 +180,8 @@
     "access": "public"
   },
   "devDependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
     "fast-check": "4.10.2"
   }
 }

package/src/index.js

@@ -18,9 +18,10 @@ export * as mlDsa  from './ml-dsa.js'
 export * as mlKem  from './ml-kem.js'
 export * as slhDsa from './slh-dsa.js'
 
-// Category 5 parameter sets, for callers who are given ML-DSA-87 or
-// ML-KEM-1024 as a requirement. The KXCO default stays Category 3
-// (mlDsa / mlKem). Supporting these sets is not a CNSA 2.0 compliance claim;
+// Category 5 parameter sets. mlDsa87 is the signature set for new keys, and
+// mlDsa stays for the ML-DSA-65 keys that already exist. mlKem1024 is for
+// callers given ML-KEM-1024 as a requirement, and mlKem stays the default for
+// key establishment. Supporting these sets is not a CNSA 2.0 compliance claim;
 // see the notes at the top of each module and CONFORMANCE.md.
 export * as mlDsa87   from './ml-dsa-87.js'
 export * as mlKem1024 from './ml-kem-1024.js'

package/src/jws.d.ts

@@ -13,7 +13,10 @@ export interface JwsHeader {
 }
 
 export interface SignJwsOptions {
-  /** Defaults to 'ML-DSA-65'. */
+  /**
+   * Without it the secret key decides: a 4032-byte ML-DSA-65 key signs
+   * 'ML-DSA-65', and every other key 'ML-DSA-87', the default.
+   */
   alg?: JwsAlgorithm
   /** Key identifier, e.g. the 16-hex `fingerprint()` of the public key. */
   kid?: string

package/src/jws.js

@@ -32,8 +32,8 @@ const dec = new TextDecoder()
 // and nowhere else, so a token cannot name its own verification routine — the
 // alg-confusion failure that has broken JWT libraries repeatedly.
 const ALGORITHMS = {
-  'ML-DSA-65': { mod: mlDsa,   publicKeyBytes: 1952, signatureBytes: 3309 },
-  'ML-DSA-87': { mod: mlDsa87, publicKeyBytes: 2592, signatureBytes: 4627 },
+  'ML-DSA-65': { mod: mlDsa,   publicKeyBytes: 1952, secretKeyBytes: 4032, signatureBytes: 3309 },
+  'ML-DSA-87': { mod: mlDsa87, publicKeyBytes: 2592, secretKeyBytes: 4896, signatureBytes: 4627 },
 }
 
 /** JWS `alg` values this module will sign or verify. */
@@ -46,7 +46,16 @@ function algorithmFor(alg) {
   return typeof alg === 'string' && Object.hasOwn(ALGORITHMS, alg) ? ALGORITHMS[alg] : undefined
 }
 
-const DEFAULT_ALG = 'ML-DSA-65'
+// Without opts.alg the secret key decides: its size names the set it belongs
+// to, so an ML-DSA-65 key that already exists keeps signing ML-DSA-65 tokens.
+// A key of neither size gets the default, ML-DSA-87. The size is the byte
+// length, so a key held as an ArrayBuffer is measured too.
+const DEFAULT_ALG = 'ML-DSA-87'
+
+function algorithmForSecretKey(secretKey) {
+  const size = secretKey?.byteLength ?? secretKey?.length
+  return JWS_ALGORITHMS.find((alg) => ALGORITHMS[alg].secretKeyBytes === size)
+}
 
 function b64url(bytes) {
   if (HAS_BUFFER) return Buffer.from(bytes).toString('base64url')
@@ -104,6 +113,9 @@ function payloadBytes(payload) {
 /**
  * Sign a payload into a compact JWS.
  *
+ * Without `opts.alg` the key decides: a 4032-byte ML-DSA-65 secret key signs
+ * ML-DSA-65, and every other key ML-DSA-87.
+ *
  * @param {object|string|Uint8Array} payload — objects are JSON-serialised
  * @param {Buffer|Uint8Array} secretKey
  * @param {{ alg?: string, kid?: string, typ?: string, header?: object }} [opts]
@@ -113,7 +125,7 @@ export function signJws(payload, secretKey, opts = {}) {
   if (opts === null || typeof opts !== 'object') {
     throw new TypeError('expected an options object such as { kid, alg }')
   }
-  const alg = opts.alg ?? DEFAULT_ALG
+  const alg = opts.alg ?? algorithmForSecretKey(secretKey) ?? DEFAULT_ALG
   const spec = algorithmFor(alg)
   if (!spec) {
     throw new Error(`unsupported JWS alg '${alg}' — this module signs ${JWS_ALGORITHMS.join(' and ')}`)

package/src/ml-dsa-87.js

@@ -4,9 +4,9 @@
 // bytes, secret key 4896 bytes, signature 4627 bytes. Resistant to attacks by
 // quantum computers.
 //
-// Same API as ./ml-dsa.js, one security category higher. Use this where a
-// counterparty specifies Category 5 or names ML-DSA-87. ML-DSA-65 remains the
-// default for the KXCO stack; see the note on parameter choice below.
+// Same API as ./ml-dsa.js, one security category higher. This is the set for
+// new keys and signatures. ML-DSA-65 (./ml-dsa.js) stays for keys that already
+// exist; see the note on parameter choice below.
 //
 // Isomorphic: works in Node and modern browsers. Returns Buffer on Node
 // (backwards compatible), Uint8Array in browsers.

package/src/slh-dsa.js

@@ -7,7 +7,7 @@
 // hedge alongside ML-DSA-65.
 //
 // Tradeoff: signatures are ~5x larger than ML-DSA-65 (16224 vs 3309 bytes) and
-// signing is slower. Use ML-DSA-65 as the default; reach for SLH-DSA when you
+// signing is slower. Use ML-DSA-87 as the default; reach for SLH-DSA when you
 // want a signature whose security does not depend on lattice hardness.
 //
 // Isomorphic: works in Node and modern browsers. Returns Buffer on Node

package/src/webhook.d.ts

@@ -34,8 +34,10 @@ export function verifyHmac(
 ): boolean
 
 /**
- * Produce the X-KXCO-PQ-Signature header value: the hex ML-DSA-65
- * signature over the envelope, prefixed with `ml-dsa-65=`.
+ * Produce the X-KXCO-PQ-Signature header value: the hex ML-DSA signature
+ * over the envelope, prefixed with its parameter set. The key decides it: an
+ * ML-DSA-87 secret key (4896 bytes) gives `ml-dsa-87=<hex>`, and an
+ * ML-DSA-65 key gives `ml-dsa-65=<hex>` as it always has.
  */
 export function pqSign(
   secretKey: Buffer | Uint8Array,
@@ -44,8 +46,10 @@ export function pqSign(
 ): string
 
 /**
- * Verify a hex ML-DSA-65 signature header.
- * Accepts the value with or without the `ml-dsa-65=` prefix.
+ * Verify a hex ML-DSA signature header under the set `publicKey` belongs to.
+ * An ML-DSA-65 key accepts the value with or without the `ml-dsa-65=` prefix.
+ * An ML-DSA-87 key (2592 bytes) accepts only `ml-dsa-87=<hex>`. A prefix
+ * naming the other set returns false.
  */
 export function verifyPq(
   publicKey: Buffer | Uint8Array,
@@ -59,7 +63,7 @@ export interface SignDeliveryArgs {
   rawBody:     string | Buffer
   /** Per-endpoint shared secret for HMAC */
   hmacSecret:  string | Buffer
-  /** Raw ML-DSA-65 secret key */
+  /** Raw ML-DSA-65 or ML-DSA-87 secret key. The key decides the header form. */
   pqSecretKey: Buffer | Uint8Array
   /** 16-hex kid fingerprint of the matching public key */
   pqKid:       string
@@ -73,7 +77,7 @@ export interface SignDeliveryHeaders {
   'Content-Type':         'application/json'
   'X-KXCO-Timestamp':     string
   'X-KXCO-Signature':     string   // sha256=<hex>
-  'X-KXCO-PQ-Signature':  string   // ml-dsa-65=<hex>
+  'X-KXCO-PQ-Signature':  string   // ml-dsa-65=<hex>, or ml-dsa-87=<hex> for an ML-DSA-87 key
   'X-KXCO-PQ-Kid':        string
   'X-KXCO-Event'?:        string
   'X-KXCO-Delivery'?:     string

package/src/webhook.js

@@ -17,6 +17,19 @@
 import { hmac } from '@noble/hashes/hmac.js'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { sign as mlDsaSign, verify as mlDsaVerify } from './ml-dsa.js'
+import { sign as mlDsa87Sign, verify as mlDsa87Verify } from './ml-dsa-87.js'
+
+// The PQ signature header names its parameter set: `ml-dsa-65=<hex>`, or
+// `ml-dsa-87=<hex>` for an ML-DSA-87 key. The key decides which: an ML-DSA-87
+// key (4896-byte secret, 2592-byte public) signs and verifies the -87 form,
+// and every other key the -65 form, exactly as before -87 existed. A header
+// whose prefix names the other set fails, so a key is never checked as the
+// set it is not.
+const ML_DSA_65 = { prefix: 'ml-dsa-65=', sign: mlDsaSign, verify: mlDsaVerify }
+const ML_DSA_87 = { prefix: 'ml-dsa-87=', sign: mlDsa87Sign, verify: mlDsa87Verify }
+const ML_DSA_87_SECRET_KEY_BYTES = 4896
+const ML_DSA_87_PUBLIC_KEY_BYTES = 2592
+const ML_DSA_65_PUBLIC_KEY_BYTES = 1952
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'
 const enc = new TextEncoder()
@@ -77,21 +90,34 @@ export function verifyHmac(secret, timestamp, rawBody, sigHeader) {
 }
 
 /**
- * Produce the X-KXCO-PQ-Signature header value.
+ * Produce the X-KXCO-PQ-Signature header value: `ml-dsa-65=<hex>`, or
+ * `ml-dsa-87=<hex>` when `secretKey` is an ML-DSA-87 key.
  */
 export function pqSign(secretKey, timestamp, rawBody) {
-  const sig = mlDsaSign(secretKey, envelope(timestamp, rawBody))
-  return `ml-dsa-65=${sig}`
+  const set = secretKey?.length === ML_DSA_87_SECRET_KEY_BYTES ? ML_DSA_87 : ML_DSA_65
+  const sig = set.sign(secretKey, envelope(timestamp, rawBody))
+  return `${set.prefix}${sig}`
 }
 
 /**
- * Verify a hex ML-DSA-65 signature header.
+ * Verify a hex ML-DSA signature header under the set `publicKey` belongs to.
+ *
+ * An ML-DSA-65 key takes `ml-dsa-65=<hex>` or, as it always has, the bare hex.
+ * An ML-DSA-87 key takes only `ml-dsa-87=<hex>`. A prefix naming the other set
+ * is false.
  */
 export function verifyPq(publicKey, timestamp, rawBody, sigHeader) {
-  const hex = sigHeader.startsWith('ml-dsa-65=')
-    ? sigHeader.slice('ml-dsa-65='.length)
-    : sigHeader
-  return mlDsaVerify(publicKey, envelope(timestamp, rawBody), hex)
+  const is87 = publicKey?.length === ML_DSA_87_PUBLIC_KEY_BYTES
+  // A key of neither set's size is refused here, not left to the primitive.
+  if (!is87 && publicKey?.length !== ML_DSA_65_PUBLIC_KEY_BYTES) return false
+  const set = is87 ? ML_DSA_87 : ML_DSA_65
+  // Only the key's own prefix is stripped. A header naming the other set is
+  // then neither that prefix nor bare hex, and fails.
+  if (sigHeader.startsWith(set.prefix)) {
+    return set.verify(publicKey, envelope(timestamp, rawBody), sigHeader.slice(set.prefix.length))
+  }
+  if (is87) return false
+  return set.verify(publicKey, envelope(timestamp, rawBody), sigHeader)
 }
 
 /**