kxco-post-quantum 1.7.8 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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
+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.

package/README.md

@@ -291,6 +291,8 @@ and the operator selects, as the next section shows.
 
 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-65 key signs `ml-dsa-65=<hex>`, and an ML-DSA-87 key signs `ml-dsa-87=<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.
+
 ---
 
 ## Requiring the native backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.7.8",
+  "version": "1.8.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/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",

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
@@ -89,8 +93,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

@@ -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()
@@ -41,6 +54,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.
@@ -74,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)
 }
 
 /**
@@ -113,10 +142,13 @@ 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'])
 
   // 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