kxco-post-quantum 1.7.7 → 1.7.9

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.7.9
+
+verifyDelivery reads each header only as a string. A header that arrives as an
+array, as some frameworks deliver a repeated header, counts as missing, so the
+result reports the failed check where an array signature header used to throw.
+
+## 1.7.8
+
+verifyDelivery accepts an X-KXCO-Timestamp header only as decimal digits.
+
+Hex signatures and keys are accepted only as hex digits, across ML-DSA-65,
+ML-DSA-87, SLH-DSA, fingerprint and the JWS helpers. verifyJws, signJws and the
+seed helpers resolve algorithm names from their own tables only, and verifyJws
+reports a header kid that is not a string without throwing.
+
+slhDsa.sign falls back to the JavaScript backend on a Node build that generates
+SLH-DSA keys but cannot import one as a JWK, such as 24.15.0, where it threw.
+CI now tests 24.15.0.
+
+The npm page gives each parameter set its own label in the examples, so no two
+share seed bytes, and maps each EO 14412 and OMB M-26-15 requirement to the
+export that answers it.
+
+The dependency audit reviews the dev tree the way it reviews the production
+tree, so the property tests' fast-check no longer fails the conformance workflow.
+
 ## 1.7.7
 
 Documentation. No source change.

package/README.md

@@ -25,6 +25,19 @@
 - **United States:** [Executive Order 14412](https://www.federalregister.gov/documents/2026/06/25/2026-12909/securing-the-nation-against-advanced-cryptographic-attacks), signed on 22 June 2026, moves federal high-value and high-impact systems to post-quantum key establishment by 31 December 2030 and to post-quantum signatures by 31 December 2031. [OMB M-26-15](https://www.whitehouse.gov/wp-content/uploads/2026/06/M-26-15-Execution-of-the-Migration-to-Post-Quantum-Cryptography.pdf) requires PQC-agile libraries for all new applications.
 - **United Kingdom:** the [NCSC](https://www.ncsc.gov.uk/guidance/pqc-migration-timelines) sets 2028, 2031 and 2035 as its migration milestones.
 
+**Each requirement has an export.**
+
+| 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 |
+| "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 |
+| "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 |
+
+**TLS has already moved, so this is the rest.** A stock Node.js client on 22.23.3, 24.21.0 and 26.1.0 negotiates X25519MLKEM768, the hybrid of X25519 and ML-KEM-768, with no options set (measured 30 September 2026). What TLS never reaches is what your application signs, issues and stores, and that is this package. The walkthrough, with every block run against this package: [The 2030 Post-Quantum Deadline in Code](https://www.livetradingnews.com/the-2030-post-quantum-deadline-in-code-6-changes-and-the-test-for-each).
+
 This is the primitive layer every other `kxco-pq-*` package builds on.
 
 [Conformance](./CONFORMANCE.md) · [Benchmarks](./BENCHMARKS.md) · [Migration](./MIGRATION.md) · [Threat model](./THREAT-MODEL.md) · [Changelog](./CHANGELOG.md) · [For institutions](#for-institutions) · [kxco.ai](https://kxco.ai)
@@ -47,12 +60,12 @@ Requires Node.js 20.19+. ESM-only.
 import { mlDsa, mlKem, slhDsa, fingerprint, kidEquals } from 'kxco-post-quantum'
 
 // ML-DSA-65: sign and verify
-const { publicKey, secretKey } = mlDsa.keypairFromMaster(masterSecret, 'signing-v1')
+const { publicKey, secretKey } = mlDsa.keypairFromMaster(masterSecret, 'signing-65-v1')
 const sig = mlDsa.sign(secretKey, 'hello')
 const ok  = mlDsa.verify(publicKey, 'hello', sig)  // true
 
 // SLH-DSA-SHA2-192s: hash-based signatures (same API shape as mlDsa)
-const slh = slhDsa.keypairFromMaster(masterSecret, 'signing-v1')
+const slh = slhDsa.keypairFromMaster(masterSecret, 'signing-slh-v1')
 const slhSig = slhDsa.sign(slh.secretKey, 'hello')
 const slhOk  = slhDsa.verify(slh.publicKey, 'hello', slhSig)  // true
 
@@ -69,6 +82,8 @@ const recovered = mlKem.decapsulate(ciphertext, kemKeys.secretKey)
 
 `masterSecret` is a Node Buffer or typed array (Uint8Array) with at least 16 bytes of entropy (typically 32–64 bytes from an env var or KMS).
 
+**One label per key.** The label is the domain separation: one master under one label yields the same seed bytes, whichever parameter set reads them. Give every parameter set and every purpose its own label, as above, and version it (`-v1`, `-v2`) so a rotation is a new label.
+
 ### Category 5 parameter sets
 
 `mlDsa87` (ML-DSA-87) and `mlKem1024` (ML-KEM-1024) have the same API as `mlDsa`
@@ -79,7 +94,7 @@ Category 3.
 ```js
 import { mlDsa87, mlKem1024 } from 'kxco-post-quantum'
 
-const { publicKey, secretKey } = mlDsa87.keypairFromMaster(masterSecret, 'signing-v1')
+const { publicKey, secretKey } = mlDsa87.keypairFromMaster(masterSecret, 'signing-87-v1')
 const sig = mlDsa87.sign(secretKey, 'hello')      // 4627 bytes, 9254 hex chars
 mlDsa87.verify(publicKey, 'hello', sig)           // true
 ```
@@ -90,8 +105,8 @@ mlDsa87.verify(publicKey, 'hello', sig)           // true
 | Key encapsulation | `mlKem`: pk 1184, ct 1088 | `mlKem1024`: pk 1568, ct 1568 |
 
 The two sets do not mix, deliberately. Default derivation info differs, so one
-master yields unrelated keys for each; and a signature from one set does not
-verify under the other. Sizes are the migration cost, so check any fixed-width
+master yields unrelated keys for each, and so does a distinct label of your own;
+a signature from one set does not verify under the other. Sizes are the migration cost, so check any fixed-width
 signature or key field before mixing sets in one system.
 
 **CNSA 2.0 names ML-DSA-87 and ML-KEM-1024**, so moving a deployment to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.7.7",
+  "version": "1.7.9",
   "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/run-vectors.js",
+    "test": "node --test test/basic.test.js && node --test test/backend.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/edge-cases.test.js && node --test test/seed.test.js && node --test test/browser-smoke.test.js && node --test test/property.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",
@@ -177,5 +177,8 @@
   "publishConfig": {
     "provenance": true,
     "access": "public"
+  },
+  "devDependencies": {
+    "fast-check": "4.10.2"
   }
 }

package/src/_native.node.js

@@ -113,8 +113,7 @@ function der(tag, payload) {
 // The AlgorithmIdentifier is read back off a key OpenSSL generates itself rather
 // than hard-coded from the OID registry, so a build that spells one differently
 // cannot produce a subtly wrong encoding here.
-function algorithmIdentifier(nodeName) {
-  const { privateKey } = crypto.generateKeyPairSync(nodeName)
+function algorithmIdentifier(privateKey) {
   const pkcs8 = privateKey.export({ format: 'der', type: 'pkcs8' })
   const headerLength = pkcs8[1] & 0x80 ? 2 + (pkcs8[1] & 0x7f) : 2
   const start = headerLength + 3 // skip the version INTEGER
@@ -155,13 +154,23 @@ const ALGORITHMS = {
 
 // Probed once, by actually generating a key. Asking the Node version would be a
 // guess about which build shipped which OpenSSL; generating a key is the fact.
+//
+// For the JWK form, generating is not the whole fact. Node 24.15.0 generates
+// SLH-DSA keys but refuses one as a JWK, which is the only way sign() can load
+// it, so every SLH-DSA signature threw there instead of falling back. The
+// import sign() makes is probed too, in the exact shape it makes it.
 function probe() {
   const table = new Map()
   for (const [name, spec] of Object.entries(ALGORITHMS)) {
     try {
+      const { privateKey } = crypto.generateKeyPairSync(spec.nodeName)
+      if (spec.privateForm === 'jwk') {
+        const { pub, priv } = privateKey.export({ format: 'jwk' })
+        crypto.createPrivateKey({ key: { kty: 'AKP', alg: name, pub, priv }, format: 'jwk' })
+      }
       // jwkAlg is the FIPS name: SLH-DSA goes in as a JWK, which names the
       // algorithm in the payload rather than in an AlgorithmIdentifier.
-      table.set(name, { ...spec, jwkAlg: name, algid: algorithmIdentifier(spec.nodeName) })
+      table.set(name, { ...spec, jwkAlg: name, algid: algorithmIdentifier(privateKey) })
     } catch {
       // Not in this build. The JavaScript backend covers it.
     }

package/src/jws.js

@@ -39,6 +39,13 @@ const ALGORITHMS = {
 /** JWS `alg` values this module will sign or verify. */
 export const JWS_ALGORITHMS = Object.keys(ALGORITHMS)
 
+// Own keys only, and only a string: a name the table inherits, such as
+// `constructor`, is not an algorithm, and neither is an array that happens to
+// stringify to one.
+function algorithmFor(alg) {
+  return typeof alg === 'string' && Object.hasOwn(ALGORITHMS, alg) ? ALGORITHMS[alg] : undefined
+}
+
 const DEFAULT_ALG = 'ML-DSA-65'
 
 function b64url(bytes) {
@@ -78,6 +85,7 @@ function bytesToHex(bytes) {
 }
 
 function hexToBytes(hex) {
+  if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-fA-F]*$/.test(hex)) throw new Error('invalid hex')
   const b = new Uint8Array(hex.length / 2)
   for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
   return b
@@ -106,7 +114,7 @@ export function signJws(payload, secretKey, opts = {}) {
     throw new TypeError('expected an options object such as { kid, alg }')
   }
   const alg = opts.alg ?? DEFAULT_ALG
-  const spec = ALGORITHMS[alg]
+  const spec = algorithmFor(alg)
   if (!spec) {
     throw new Error(`unsupported JWS alg '${alg}' — this module signs ${JWS_ALGORITHMS.join(' and ')}`)
   }
@@ -181,15 +189,21 @@ export function verifyJws(token, publicKey, opts = {}) {
     return { valid: false, error: 'malformed JWS: header is not an object' }
   }
 
-  const spec = ALGORITHMS[header.alg]
+  const spec = algorithmFor(header.alg)
   if (!spec) {
-    return { valid: false, error: `unsupported JWS alg '${header.alg}'` }
+    // A header alg that is not a string is named as JSON, which cannot throw
+    // on anything JSON.parse produced; interpolating it could.
+    const named = typeof header.alg === 'string' ? header.alg : JSON.stringify(header.alg)
+    return { valid: false, error: `unsupported JWS alg '${named}'` }
   }
   if (opts.alg !== undefined && header.alg !== opts.alg) {
     return { valid: false, error: `alg mismatch: expected '${opts.alg}', token declares '${header.alg}'` }
   }
   if (opts.kid !== undefined && header.kid !== opts.kid) {
-    return { valid: false, error: `kid mismatch: expected '${opts.kid}', token declares '${header.kid ?? '(none)'}'` }
+    // Named as JSON when it is not a string, for the same reason as alg above.
+    const declared = header.kid === undefined ? '(none)'
+      : typeof header.kid === 'string' ? header.kid : JSON.stringify(header.kid)
+    return { valid: false, error: `kid mismatch: expected '${opts.kid}', token declares '${declared}'` }
   }
 
   // RFC 7515 section 4.1.11: a verifier that does not understand every member

package/src/kid.js

@@ -12,6 +12,7 @@ import { sha256 } from '@noble/hashes/sha2.js'
 
 function hexToBytes(hex) {
   if (hex.length % 2) throw new Error('odd hex length')
+  if (!/^[0-9a-fA-F]*$/.test(hex)) throw new Error('invalid hex')
   const b = new Uint8Array(hex.length / 2)
   for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
   return b

package/src/ml-dsa-87.js

@@ -44,7 +44,7 @@ function toBytes(input) {
   throw new Error('expected Uint8Array or string')
 }
 function hexToBytes(hex) {
-  if (typeof hex !== 'string' || hex.length % 2) throw new Error('invalid hex')
+  if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-fA-F]*$/.test(hex)) throw new Error('invalid hex')
   const b = new Uint8Array(hex.length / 2)
   for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
   return b

package/src/ml-dsa.js

@@ -42,7 +42,7 @@ function toBytes(input) {
   throw new Error('expected Uint8Array or string')
 }
 function hexToBytes(hex) {
-  if (typeof hex !== 'string' || hex.length % 2) throw new Error('invalid hex')
+  if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-fA-F]*$/.test(hex)) throw new Error('invalid hex')
   const b = new Uint8Array(hex.length / 2)
   for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
   return b

package/src/seed.js

@@ -71,7 +71,9 @@ const PARAMS = {
 export const SEED_ALGORITHMS = Object.keys(PARAMS)
 
 function paramsFor(alg) {
-  const p = PARAMS[alg]
+  // Own keys only, so a name the table inherits, such as `constructor`, is an
+  // unsupported algorithm rather than a parameter set with no sizes.
+  const p = typeof alg === 'string' && Object.hasOwn(PARAMS, alg) ? PARAMS[alg] : undefined
   if (!p) {
     throw new Error(
       `unsupported algorithm '${alg}' — seed form is defined for ${SEED_ALGORITHMS.join(', ')}`,
@@ -166,8 +168,9 @@ export function seedFromMaster(alg, master, info) {
  * Export an AKP JWK (RFC 9964).
  *
  * With `seed`, the result is a private JWK carrying the seed in `priv` and is
- * accepted directly by `crypto.createPrivateKey({ format: 'jwk' })` on Node
- * 24+. Without it, the result is a public JWK.
+ * accepted directly by `crypto.createPrivateKey({ format: 'jwk' })` on a Node
+ * build that imports AKP JWKs for that set. Node 24.15.0 does for ML-DSA and
+ * not for ML-KEM. Without it, the result is a public JWK.
  *
  * An expanded secret key is NOT accepted in place of a seed: RFC 9964 has no
  * encoding for one, and silently deriving something else would produce a JWK

package/src/slh-dsa.js

@@ -29,7 +29,7 @@ function toBytes(input) {
   throw new Error('expected Uint8Array or string')
 }
 function hexToBytes(hex) {
-  if (typeof hex !== 'string' || hex.length % 2) throw new Error('invalid hex')
+  if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-fA-F]*$/.test(hex)) throw new Error('invalid hex')
   const b = new Uint8Array(hex.length / 2)
   for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
   return b

package/src/webhook.d.ts

@@ -89,8 +89,11 @@ export interface SignDeliveryHeaders {
 export function signDelivery(args: SignDeliveryArgs): SignDeliveryHeaders
 
 export interface VerifyDeliveryArgs {
-  /** HTTP headers with LOWERCASE keys */
-  headers: Record<string, string | undefined>
+  /**
+   * HTTP headers with LOWERCASE keys. Each KXCO header is read only as a
+   * string; a header that arrives as an array counts as missing.
+   */
+  headers: Record<string, string | string[] | undefined>
   /** The EXACT request body bytes as received */
   rawBody: string | Buffer
   /** Optional: enable HMAC verification by providing the shared secret */

package/src/webhook.js

@@ -41,6 +41,9 @@ function constTimeEqualStrings(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
   return diff === 0
 }
+function headerString(value) {
+  return typeof value === 'string' ? value : undefined
+}
 
 /**
  * Build the canonical signed envelope: timestamp + "." + raw body string.
@@ -113,12 +116,19 @@ export function signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, event, d
  * Verify a webhook delivery on the receiving side.
  */
 export function verifyDelivery({ headers, rawBody, hmacSecret, pqPublicKey, pinnedKid, windowSeconds = 300 }) {
-  const ts      = headers['x-kxco-timestamp']
-  const sigHmac = headers['x-kxco-signature']
-  const sigPq   = headers['x-kxco-pq-signature']
-  const kid     = headers['x-kxco-pq-kid']
+  // Each header is read only as a string. Some frameworks hand a repeated
+  // header over as an array; that counts as missing rather than being coerced,
+  // so a header of any other type fails its check instead of throwing.
+  const ts      = headerString(headers['x-kxco-timestamp'])
+  const sigHmac = headerString(headers['x-kxco-signature'])
+  const sigPq   = headerString(headers['x-kxco-pq-signature'])
+  const kid     = headerString(headers['x-kxco-pq-kid'])
 
-  const tsNum = parseInt(ts, 10)
+  // Both signatures cover the header exactly as it arrives, so it is read
+  // only as the decimal digits it is specified to be. parseInt alone would
+  // take the leading digits of `1700000000.{"a":1` and leave the rest of the
+  // header to be signed, which lets the start of a body move into it.
+  const tsNum = /^[0-9]+$/.test(ts) ? parseInt(ts, 10) : NaN
   const timestampOk = Number.isFinite(tsNum) &&
     Math.abs(Date.now() / 1000 - tsNum) <= windowSeconds