kxco-verify 1.3.3 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.4.1
+
+Documentation. No source change.
+
+The package description, the opening of the README and the keywords now say
+what 1.4.0 already does: it verifies ML-DSA-87 signatures as well as ML-DSA-65.
+The description now fits the 255 characters the npm registry keeps, so it no
+longer ends mid-sentence. `ml-dsa-87` joins the keywords.
+
+## 1.4.0
+ML-DSA-87 manifests verify alongside ML-DSA-65. parseManifest accepts
+`"ML-DSA-87"` where all three alg fields name it, and requires the public key
+and signature to be exactly that set's sizes: 2592 and 4627 bytes for
+ML-DSA-87, 1952 and 3309 for ML-DSA-65. A manifest whose alg fields disagree,
+or whose key is the size of the other set, is refused with `invalid_field`.
+verifyManifest verifies under the manifest's set and reports it as
+`algorithm`.
+
+verifySignature takes an optional fourth argument, `alg`. Without it the public
+key decides the set by its length; with it, a key or signature of the other set
+returns false, and an algorithm it does not speak throws a TypeError. Every
+ML-DSA-65 manifest and call that verified before verifies unchanged.
+
+The ML-DSA-87 path uses `ml_dsa87` from the same exactly pinned
+`@noble/post-quantum` 0.7.0, so the runtime dependency is unchanged.
+
 ## 1.3.3
 
 A manifest body that is valid JSON but not an object is refused with

package/README.md

@@ -11,7 +11,7 @@
 [![node](https://img.shields.io/node/v/kxco-verify.svg)](https://nodejs.org)
 [![verify.kxco.ai](https://img.shields.io/badge/verify.kxco.ai-live-22c55e)](https://verify.kxco.ai)
 
-Standalone post-quantum credential and attestation verifier for KXCO ML-DSA-65 signed documents. One dependency, pinned exactly. Works in any modern browser and in Node.js 20.19 and later.
+Standalone post-quantum credential and attestation verifier for KXCO ML-DSA-87 and ML-DSA-65 signed documents. One dependency, pinned exactly. Works in any modern browser and in Node.js 20.19 and later.
 
 - **No KXCO server in the trust path.** `verifyManifest()` makes no network request at all, and `verifyUrl()` contacts only the attestation URL you pass and the key endpoint the manifest names.
 - **Runs in the browser as shipped.** No `Buffer`, no `process` and SHA-256 from WebCrypto, which is how [verify.kxco.ai](https://verify.kxco.ai) checks a signature entirely in the tab.
@@ -159,7 +159,7 @@ All exports are re-exported from the main entry point (`import ... from 'kxco-ve
 
 ### `verifyUrl(attestationUrl, opts?) → Promise<VerifyResult>`
 
-Fetches the attestation at `attestationUrl`, verifies the ML-DSA-65 signature, then fetches the live well-known pubkey endpoint declared in the manifest (`publicKey.pinAt`) to detect key rotation. May return `"rotated"` if the live endpoint now serves a different key identifier.
+Fetches the attestation at `attestationUrl`, verifies the signature under the parameter set the manifest names (ML-DSA-65 or ML-DSA-87), then fetches the live well-known pubkey endpoint declared in the manifest (`publicKey.pinAt`) to detect key rotation. May return `"rotated"` if the live endpoint now serves a different key identifier.
 
 ```ts
 verifyUrl(
@@ -186,7 +186,7 @@ verifyManifest(manifestBody: string | object): Promise<VerifyResult>
 ```ts
 interface VerifyResult {
   state:           'valid' | 'rotated' | 'invalid' | 'error'
-  algorithm?:      'ML-DSA-65'
+  algorithm?:      'ML-DSA-65' | 'ML-DSA-87'
   manifestKid?:    string                    // key identifier declared in the manifest
   livePubkeyKid?:  string                    // key identifier currently at the well-known endpoint
   site?:           string                    // site identifier declared by the manifest
@@ -212,22 +212,23 @@ These are exported for callers who want to compose their own verification logic.
 
 #### `parseManifest(input) → ParseResult`
 
-Parse and validate a raw manifest body without running signature verification.
+Parse and validate a raw manifest body without running signature verification. `manifest.alg`, `signature.alg` and `publicKey.alg` must name the same parameter set, `ML-DSA-65` or `ML-DSA-87`, and the public key and signature must be exactly that set's sizes (1952 and 3309 bytes for ML-DSA-65, 2592 and 4627 for ML-DSA-87). A key of one set labelled as the other is refused.
 
 ```ts
 parseManifest(input: string | object): ParseResult
 // ParseResult is { ok: true; manifest: ParsedManifest } | { ok: false; error: ParseError }
 ```
 
-#### `verifySignature(publicKey, message, signature) → boolean`
+#### `verifySignature(publicKey, message, signature, alg?) → boolean`
 
-Run ML-DSA-65 signature verification directly.
+Run ML-DSA-65 or ML-DSA-87 signature verification directly. The public key decides the parameter set: 1952 bytes is ML-DSA-65 and 2592 is ML-DSA-87. Pass `alg` to require a set, and a key or signature of the other set returns `false`. An `alg` other than these two throws a `TypeError`.
 
 ```ts
 verifySignature(
   publicKey: Uint8Array | string,   // hex or bytes
   message:   Uint8Array | string,   // UTF-8 string or bytes
   signature: Uint8Array | string,   // hex or bytes
+  alg?:      'ML-DSA-65' | 'ML-DSA-87',
 ): boolean
 ```
 
@@ -321,7 +322,7 @@ version, and every GitHub Action is pinned by commit SHA.
 
 ## Security
 
-**ML-DSA-65** (NIST FIPS 204) via [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) 0.7.0, pinned exactly. No custom cryptography.
+**ML-DSA-87** and **ML-DSA-65** (NIST FIPS 204) via [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) 0.7.0, pinned exactly. No custom cryptography.
 
 Evidenced, and reproducible on your own machine:
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "kxco-verify",
-  "version": "1.3.3",
-  "description": "Free, browser-safe verifier for KXCO ML-DSA-65 post-quantum signatures, with no KXCO server in the trust path. An auditor, regulator or counterparty confirms a signature from the artefact alone, years later, and can check the key is still live against the on-chain registry.",
+  "version": "1.4.1",
+  "description": "Free, browser-safe verifier for KXCO ML-DSA-87 and ML-DSA-65 signatures, with no KXCO server in the trust path. An auditor, regulator or counterparty confirms a signature from the artefact alone, years later, and can check the key is still live on chain.",
   "keywords": [
     "post-quantum",
     "pqc",
     "ml-dsa",
+    "ml-dsa-87",
     "dilithium",
     "nist",
     "fips-204",
@@ -83,8 +84,8 @@
     "@noble/post-quantum": "0.7.0"
   },
   "scripts": {
-    "test": "node --test --test-reporter=spec test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js test/property.test.js",
-    "test:cov": "node --test --experimental-test-coverage test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js",
+    "test": "node --test --test-reporter=spec test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js test/ml-dsa-87.test.js test/property.test.js",
+    "test:cov": "node --test --experimental-test-coverage test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js test/ml-dsa-87.test.js",
     "smoke": "node scripts/smoke.js",
     "lint": "node -c src/index.js && node -c src/parse.js && node -c src/verify.js && node -c src/fetch.js"
   },

package/src/index.d.ts

@@ -11,7 +11,7 @@ export interface VerifyResultError {
 
 export interface VerifyResult {
   state: VerifyState
-  algorithm?: 'ML-DSA-65'
+  algorithm?: 'ML-DSA-65' | 'ML-DSA-87'
   /** kid as declared inside the manifest itself */
   manifestKid?: string
   /** kid currently served at the live well-known pubkey endpoint (when fetched) */

package/src/index.js

@@ -11,8 +11,9 @@
 //     is trustworthy.
 //   - Maintain a registry of approved (domain, kid) pairs. That is a future
 //     phase of kxco-post-quantum / verify.kxco.ai and not in this library.
-//   - Speak any algorithm other than ML-DSA-65 with hex encoding in this
-//     release. SLH-DSA-128s and hybrid envelopes are deferred.
+//   - Speak any algorithm other than ML-DSA-65 or ML-DSA-87 with hex
+//     encoding in this release. SLH-DSA-128s and hybrid envelopes are
+//     deferred.
 //
 // The result envelope is intentionally three-valued so the UI can distinguish
 // signature failure from in-flight key rotation:
@@ -41,7 +42,7 @@ import { getJsonBody }       from './fetch.js'
  *
  * @typedef {Object} VerifyResult
  * @property {VerifyState} state
- * @property {string=}     algorithm        — e.g. "ML-DSA-65"
+ * @property {string=}     algorithm        — "ML-DSA-65" or "ML-DSA-87"
  * @property {string=}     manifestKid      — kid the manifest declared
  * @property {string=}     livePubkeyKid    — kid currently served at the well-known endpoint (only present when fetched)
  * @property {string=}     site             — site identifier as declared by the manifest
@@ -88,7 +89,10 @@ export async function verifyManifest(manifestBody) {
     }
   }
 
-  const sigValid = verifySignature(m.publicKeyHex, m.signedMessage, m.signatureHex)
+  // The manifest's algorithm, which parseManifest has already bound to the
+  // key and signature sizes, is required here as well, so verification runs
+  // under that parameter set and no other.
+  const sigValid = verifySignature(m.publicKeyHex, m.signedMessage, m.signatureHex, m.alg)
   return {
     state:       sigValid ? 'valid' : 'invalid',
     algorithm:   m.alg,

package/src/parse.d.ts

@@ -1,6 +1,6 @@
 export interface ParsedManifest {
   site: string
-  alg: 'ML-DSA-65'
+  alg: 'ML-DSA-65' | 'ML-DSA-87'
   kid: string
   signedMessage: string
   signatureHex: string

package/src/parse.js

@@ -21,15 +21,27 @@
 //   "publicKey": { "alg": "ML-DSA-65", "encoding": "hex", "value": "<3904 hex chars>", "kid": "<same as manifest.kid>", "pinAt": "<relative URL>" }
 // }
 //
-// We accept only ML-DSA-65 with hex encoding in this version. SLH-DSA-128s
-// and Ed25519+ML-DSA hybrid envelopes are reserved for later.
+// We accept ML-DSA-65 and ML-DSA-87 with hex encoding. The three alg fields
+// must name the same parameter set, and the public key and signature must be
+// exactly that set's sizes, so the algorithm is bound to the key rather than
+// taken from a label. SLH-DSA-128s and Ed25519+ML-DSA hybrid envelopes are
+// reserved for later.
 
 const HEX_RE = /^[0-9a-f]+$/i
 
+// FIPS 204 sizes in bytes. A manifest whose key is the size of one set and
+// whose alg names the other is refused here, before any verification.
+const ML_DSA_SIZES = {
+  'ML-DSA-65': { publicKey: 1952, signature: 3309 },
+  'ML-DSA-87': { publicKey: 2592, signature: 4627 },
+}
+const SUPPORTED = Object.keys(ML_DSA_SIZES)
+const isSupported = (alg) => typeof alg === 'string' && Object.hasOwn(ML_DSA_SIZES, alg)
+
 /**
  * @typedef {Object} ParsedManifest
  * @property {string}  site
- * @property {string}  alg                — must be "ML-DSA-65" in this version
+ * @property {string}  alg                — "ML-DSA-65" or "ML-DSA-87", matching the key and signature sizes
  * @property {string}  kid
  * @property {string}  signedMessage      — the exact bytes the signature covers
  * @property {string}  signatureHex
@@ -78,11 +90,16 @@ export function parseManifest(input) {
   if (!s  || typeof s  !== 'object') return err_('missing_field', 'top-level "signature" is missing or not an object', 'signature')
   if (!pk || typeof pk !== 'object') return err_('missing_field', 'top-level "publicKey" is missing or not an object', 'publicKey')
 
-  // We only verify ML-DSA-65 with hex-encoded signature + pubkey in this
-  // release. Anything else is a feature we deferred to a later version.
-  if (m.alg  !== 'ML-DSA-65') return err_('unsupported_algorithm', `manifest.alg must be "ML-DSA-65" (got ${JSON.stringify(m.alg)})`,  'manifest.alg')
-  if (s.alg  !== 'ML-DSA-65') return err_('unsupported_algorithm', `signature.alg must be "ML-DSA-65" (got ${JSON.stringify(s.alg)})`, 'signature.alg')
-  if (pk.alg !== 'ML-DSA-65') return err_('unsupported_algorithm', `publicKey.alg must be "ML-DSA-65" (got ${JSON.stringify(pk.alg)})`, 'publicKey.alg')
+  // We verify ML-DSA-65 and ML-DSA-87 with hex-encoded signature + pubkey.
+  // Anything else is a feature we deferred to a later version.
+  const allowed = SUPPORTED.map((a) => `"${a}"`).join(' or ')
+  if (!isSupported(m.alg))  return err_('unsupported_algorithm', `manifest.alg must be ${allowed} (got ${JSON.stringify(m.alg)})`,  'manifest.alg')
+  if (!isSupported(s.alg))  return err_('unsupported_algorithm', `signature.alg must be ${allowed} (got ${JSON.stringify(s.alg)})`, 'signature.alg')
+  if (!isSupported(pk.alg)) return err_('unsupported_algorithm', `publicKey.alg must be ${allowed} (got ${JSON.stringify(pk.alg)})`, 'publicKey.alg')
+  // One parameter set per manifest: a signature or key labelled as the other
+  // set is a manifest that disagrees with itself.
+  if (s.alg  !== m.alg) return err_('invalid_field', `signature.alg (${JSON.stringify(s.alg)}) must match manifest.alg (${JSON.stringify(m.alg)})`, 'signature.alg')
+  if (pk.alg !== m.alg) return err_('invalid_field', `publicKey.alg (${JSON.stringify(pk.alg)}) must match manifest.alg (${JSON.stringify(m.alg)})`, 'publicKey.alg')
   if (s.encoding  && s.encoding  !== 'hex') return err_('unsupported_encoding', `signature.encoding must be "hex" (got ${JSON.stringify(s.encoding)})`,  'signature.encoding')
   if (pk.encoding && pk.encoding !== 'hex') return err_('unsupported_encoding', `publicKey.encoding must be "hex" (got ${JSON.stringify(pk.encoding)})`, 'publicKey.encoding')
 
@@ -93,10 +110,12 @@ export function parseManifest(input) {
   if (typeof pk.value !== 'string' || !HEX_RE.test(pk.value)) return err_('invalid_field', 'publicKey.value must be a hex string', 'publicKey.value')
   if (typeof pk.kid   !== 'string' || !HEX_RE.test(pk.kid))   return err_('invalid_field', 'publicKey.kid must be a hex string',   'publicKey.kid')
 
-  // ML-DSA-65 size sanity. Don't trust the message saying "ML-DSA-65" —
-  // verify the byte counts match the spec. Catches malformed payloads early.
-  if (pk.value.length !== 3904) return err_('invalid_field', `publicKey.value must be 1952 bytes (3904 hex chars); got ${pk.value.length / 2}`, 'publicKey.value')
-  if (s.value.length  !== 6618) return err_('invalid_field', `signature.value must be 3309 bytes (6618 hex chars); got ${s.value.length / 2}`,  'signature.value')
+  // Size sanity, per parameter set. Don't trust the label saying which set it
+  // is: the byte counts must be that set's, so an ML-DSA-65 key labelled
+  // ML-DSA-87 (or the reverse) is refused here. Catches malformed payloads early.
+  const size = ML_DSA_SIZES[m.alg]
+  if (pk.value.length !== size.publicKey * 2) return err_('invalid_field', `publicKey.value must be ${size.publicKey} bytes (${size.publicKey * 2} hex chars) for ${m.alg}; got ${pk.value.length / 2}`, 'publicKey.value')
+  if (s.value.length  !== size.signature * 2) return err_('invalid_field', `signature.value must be ${size.signature} bytes (${size.signature * 2} hex chars) for ${m.alg}; got ${s.value.length / 2}`,  'signature.value')
 
   return {
     ok: true,

package/src/verify.d.ts

@@ -13,11 +13,18 @@ export function utf8(s: string): Uint8Array
  */
 export function computeKid(publicKey: Uint8Array | string): Promise<string>
 
-/** Verify an ML-DSA-65 signature. */
+/**
+ * Verify an ML-DSA-65 or ML-DSA-87 signature.
+ *
+ * The public key decides the parameter set: 1952 bytes is ML-DSA-65, 2592 is
+ * ML-DSA-87. Pass `alg` to require a set; a key or signature that is not that
+ * set's size returns false. An unsupported `alg` throws a TypeError.
+ */
 export function verifySignature(
   publicKey: Uint8Array | string,
   message:   Uint8Array | string,
   signature: Uint8Array | string,
+  alg?:      'ML-DSA-65' | 'ML-DSA-87',
 ): boolean
 
 /** Length-equal hex comparison. */

package/src/verify.js

@@ -5,7 +5,15 @@
 // from the Web Crypto API where available (browser, Node 20+), fallback to
 // node:crypto's createHash where SubtleCrypto.digest is not present.
 
-import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js'
+import { ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa.js'
+
+// The parameter sets this verifier speaks, with their FIPS 204 public-key sizes.
+// The key decides which one a signature is checked under: its length picks
+// the set, and a key that is not exactly a set's size verifies nothing.
+const ML_DSA = {
+  'ML-DSA-65': { primitive: ml_dsa65, publicKey: 1952 },
+  'ML-DSA-87': { primitive: ml_dsa87, publicKey: 2592 },
+}
 
 /**
  * Hex string → Uint8Array. Throws on malformed input.
@@ -68,21 +76,41 @@ export async function computeKid(publicKey) {
   return bytesToHex(hashBytes.subarray(0, 8))
 }
 
+// The ML-DSA parameter set a public key's bytes belong to, by length, or null.
+const algorithmOfKey = (pk) => Object.keys(ML_DSA).find((alg) => ML_DSA[alg].publicKey === pk?.length) ?? null
+
 /**
- * Verify an ML-DSA-65 signature.
- * @param {string|Uint8Array} publicKey   — 1952 bytes (3904 hex chars)
+ * Verify an ML-DSA-65 or ML-DSA-87 signature.
+ *
+ * The public key decides the parameter set: 1952 bytes is ML-DSA-65 and 2592
+ * is ML-DSA-87. Pass `alg` to require a set; a key or signature that is not
+ * that set's size then returns false, so a key of one set is never checked
+ * as the other. An `alg` this verifier does not speak throws, as malformed
+ * hex does, because it is a caller error rather than a failed signature.
+ *
+ * @param {string|Uint8Array} publicKey   — 1952 or 2592 bytes (3904 or 5184 hex chars)
  * @param {string|Uint8Array} message     — string (utf8'd) or raw bytes
- * @param {string|Uint8Array} signature   — 3309 bytes (6618 hex chars)
+ * @param {string|Uint8Array} signature   — 3309 or 4627 bytes (6618 or 9254 hex chars)
+ * @param {'ML-DSA-65'|'ML-DSA-87'} [alg] — the set the caller requires
  * @returns {boolean}
  */
-export function verifySignature(publicKey, message, signature) {
+export function verifySignature(publicKey, message, signature, alg) {
+  if (alg !== undefined && !(typeof alg === 'string' && Object.hasOwn(ML_DSA, alg))) {
+    throw new TypeError(`unsupported algorithm ${JSON.stringify(alg)}: expected "ML-DSA-65" or "ML-DSA-87"`)
+  }
   const pk  = typeof publicKey === 'string' ? hexToBytes(publicKey) : publicKey
   const sig = typeof signature === 'string' ? hexToBytes(signature) : signature
   const msg = typeof message   === 'string' ? utf8(message)         : message
+  const set = ML_DSA[alg ?? algorithmOfKey(pk)]
+  if (!set) return false
+  // Checked here, not left to the primitive: a named set must match the key.
+  if (pk?.length !== set.publicKey) return false
   // @noble/post-quantum ≥0.6 signature order: (signature, message, publicKey).
-  // Matches the canonical wrapper in kxco-post-quantum/src/ml-dsa.js.
+  // Matches the canonical wrapper in kxco-post-quantum/src/ml-dsa.js. The
+  // primitive refuses a key or signature that is not its set's length, so a
+  // key of one set is never checked as the other.
   try {
-    return ml_dsa65.verify(sig, msg, pk)
+    return set.primitive.verify(sig, msg, pk)
   } catch {
     return false
   }