kxco-post-quantum 1.7.9 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

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.9",
+  "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

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)
 }
 
 /**