kxco-post-quantum 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,82 +1,97 @@
 # Changelog
 
-All notable changes to `kxco-post-quantum` are documented here. This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.3] — 2026-05-21
+
+First release ships with SLSA Level 2 provenance attestation tied to a
+public GitHub Actions workflow run. No cryptographic surface changes
+vs `1.0.2` — every diff is metadata, types, CI, and hygiene.
+
+### Added
+- SLSA Level 2 provenance on every published release via GitHub Actions OIDC
+  (`publishConfig.provenance: true`)
+- `.github/workflows/publish.yml` triggered by `v*` tags — runs tests then
+  `npm publish --provenance --access public`
+- `.github/workflows/ci.yml` matrix over Node 18 / 20 / 22 on every push and PR
+- Hand-written TypeScript declarations (`.d.ts`) for all six modules; wired
+  into `exports[*].types` so TypeScript consumers get full typings without
+  any build step
+- `.github/dependabot.yml` — weekly npm + github-actions ecosystem checks
+- `sideEffects: false` for tree-shaking
+- `funding` field in `package.json`
+- Top-level `"types"` field in `package.json` pointing at `./src/index.d.ts`
+
+### Changed
+- `package.json` `files` allowlist tightened to `["src", "README.md", "LICENSE",
+  "SECURITY.md", "CHANGELOG.md"]` — locks down what ships to npm
+- `package.json` `exports` now declares per-subpath `types` + `import` keys
+- `SECURITY.md` rewritten in the standard short-form template with explicit
+  in-scope / out-of-scope split delegating primitive bugs upstream to
+  `@noble/post-quantum`
+- All third-party actions in workflows pinned by 40-char commit SHA, never
+  floating tags
+- README badge row trimmed to four (`npm`, `license`, `Socket`, `production-live`)
+  and a 60-second live-verify quickstart added under the title
+
+### Security
+- No cryptographic code changed in this release — every change is metadata,
+  types, CI, and documentation. Production behaviour is bit-for-bit identical
+  to `1.0.2`.
 
 ## [1.0.2] — 2026-05-21
 
 ### Changed
-- Repository URL on the npm package now points to `github.com/JackKXCO/kxco-post-quantum`. No code change.
+- Repository URL on the npm package metadata now points to
+  `github.com/JackKXCO/kxco-post-quantum`. No code change.
 
 ## [1.0.1] — 2026-05-21
 
-Substance additions to the v1.0 release. No API changes. Same code on the cryptographic path; auditability and reproducibility infrastructure expanded.
-
 ### Added
-- `AUDIT.md` — self-attested audit posture, including explicit roadmap for third-party review (Q3 2026), bug bounty (Q4 2026), and FIPS 140-3 CMVP application (2027)
-- `test/vectors.json` — 29 deterministic test vectors pinning every primitive's output bit-for-bit
-- `test/run-vectors.js` — runner that verifies the library's output against `vectors.json` (exit code 0 = match)
-- `test/generate-vectors.js` — vector generator (run only when the library's output behaviour changes)
-- `npm test` — now runs both functional tests and vector verification
-- `npm run test:vectors` — vector check only
-- Production deployment proof: the wallet at `chain.kxco.ai` now imports `kxco-post-quantum` directly via npm. Real-world download count starts here.
+- `AUDIT.md` — self-attested audit posture with roadmap (external audit
+  Q3 2026, public bug bounty Q4 2026, FIPS 140-3 CMVP application 2027)
+- `test/vectors.json` — 29 deterministic test vectors pinning every primitive
+  output bit-for-bit
+- `test/run-vectors.js` — runner anyone can use to verify reproducibility
+- `npm test` runs both the functional tests and vector verification
+- `npm run test:vectors` for vector check only
 
 ### Changed
-- `SECURITY.md` — sharpened with explicit threat model, in-scope vs out-of-scope responsibilities, pinned `@noble/post-quantum@0.2.1` integrity hash, Cure53 audit reference, FIPS posture clarification, replay-window and side-channel limitations
-- `README.md` — added "Used in production at" section with file refs to the live deployment
+- `SECURITY.md` sharpened with explicit threat model and pinned upstream
+  `@noble/post-quantum@0.2.1` integrity hash
+- `README.md` "Used in production at" section with file refs to chain.kxco.ai
 
-### Why a patch and not a feature release
-No API surface changes. Same exports, same signatures, same behaviour. The diff is documentation, vectors, and infrastructure that lets reviewers verify the library without trusting the publisher.
+No API changes from `1.0.0`.
 
 ## [1.0.0] — 2026-05-21
 
-First stable release. The public API below is committed to: future minor and patch releases will not break it without a major version bump.
-
-### Committed public API
-
-```js
-import {
-  mlDsa,        // namespace
-  mlKem,        // namespace
-  deriveSeed,
-  fingerprint,
-  kidEquals,
-  webhook,      // namespace
-} from 'kxco-post-quantum'
-```
-
-| Export | Signature | Notes |
-|---|---|---|
-| `mlDsa.keypairFromMaster(master, info='ml-dsa-65-v1')` | → `{ publicKey: Buffer, secretKey: Buffer }` | Deterministic. Stable across versions. |
-| `mlDsa.sign(secretKey, message)` | → hex string (6618 chars) | `message` accepts Buffer or string |
-| `mlDsa.verify(publicKey, message, sigHex)` | → boolean | Catches exceptions, returns false |
-| `mlDsa.ml_dsa65` | re-export | Raw `@noble/post-quantum` primitive |
-| `mlKem.keypairFromMaster(master, info='ml-kem-768-v1')` | → `{ publicKey, secretKey }` | Deterministic |
-| `mlKem.encapsulate(publicKey)` | → `{ ciphertext, sharedSecret, cipherText }` | `cipherText` (camelCase) alias for noble compatibility |
-| `mlKem.decapsulate(ciphertext, secretKey)` | → Buffer (32 bytes) | |
-| `mlKem.ml_kem768` | re-export | Raw primitive |
-| `deriveSeed(master, info, length)` | → Buffer | HKDF-SHA-512 with empty salt; requires `master.length ≥ 16` |
-| `fingerprint(publicKey)` | → 16-hex string | First 8 bytes of SHA-256(pubkey) |
-| `kidEquals(a, b)` | → boolean | Constant-time string compare |
-| `webhook.envelope(timestamp, rawBody)` | → Buffer | `timestamp + "." + rawBody` |
-| `webhook.hmacHex(secret, timestamp, rawBody)` | → hex string | HMAC-SHA-256 over envelope |
-| `webhook.verifyHmac(secret, timestamp, rawBody, sigHeader)` | → boolean | Constant-time. Accepts `sha256=` prefix. |
-| `webhook.pqSign(secretKey, timestamp, rawBody)` | → `ml-dsa-65=<hex>` | Ready-to-send header value |
-| `webhook.verifyPq(publicKey, timestamp, rawBody, sigHeader)` | → boolean | Accepts `ml-dsa-65=` prefix |
-| `webhook.signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, event?, deliveryId? })` | → HTTP header map | Full sender helper |
-| `webhook.verifyDelivery({ headers, rawBody, hmacSecret?, pqPublicKey?, pinnedKid?, windowSeconds=300 })` | → `{ hmacOk, pqOk, timestampOk, kidOk }` | Receiver helper. Either signature can be omitted to skip that check. |
-
-### What "committed" means
-We will not break any of the above signatures in a 1.x release. We will not change algorithm choices in a 1.x release. We will not change the envelope format `${timestamp}.${rawBody}` in a 1.x release. We may add new exports; existing ones won't move.
-
-### Verified at release
-- 9/9 functional tests pass (sign/verify, encapsulate/decapsulate, hybrid delivery, replay rejection, tamper rejection)
-- 29/29 test vectors pass
-- Underlying primitives: `@noble/post-quantum@0.2.1` (audited by Cure53, 2024)
-- Node.js 18+ ESM-only
-
-### Initial release notes
-ESM-only. Node.js 18+. FIPS-aligned (implements FIPS 203/204 algorithms). Not CMVP-validated as a module. TLS guidance: use OpenSSL 3.5+ for `X25519MLKEM768` hybrid at the edge — this package does not handle TLS.
+First stable release. Committed public API surface:
+
+- `mlDsa.keypairFromMaster(master, info?)`, `mlDsa.sign`, `mlDsa.verify`
+- `mlKem.keypairFromMaster(master, info?)`, `mlKem.encapsulate`, `mlKem.decapsulate`
+- `deriveSeed(master, info, length)`
+- `fingerprint(publicKey)`, `kidEquals(a, b)`
+- `webhook.envelope`, `webhook.hmacHex`, `webhook.verifyHmac`,
+  `webhook.pqSign`, `webhook.verifyPq`, `webhook.signDelivery`,
+  `webhook.verifyDelivery`
+
+Verified at release: 9/9 functional tests + 29/29 vector checks pass.
+
+Underlying primitives via `@noble/post-quantum@^0.2.1` (audited by Cure53, 2024).
+ESM-only. Node.js 18+.
 
 ## [0.1.0] — 2026-05-21
 
-Initial pre-release. Same surface as 1.0.0; promoted to 1.0.0 after verifying clean install and round-trip on a fresh environment.
+Initial pre-release.
+
+[Unreleased]: https://github.com/JackKXCO/kxco-post-quantum/compare/v1.0.3...HEAD
+[1.0.3]:      https://github.com/JackKXCO/kxco-post-quantum/compare/v1.0.2...v1.0.3
+[1.0.2]:      https://github.com/JackKXCO/kxco-post-quantum/compare/v1.0.1...v1.0.2
+[1.0.1]:      https://github.com/JackKXCO/kxco-post-quantum/compare/v1.0.0...v1.0.1
+[1.0.0]:      https://github.com/JackKXCO/kxco-post-quantum/compare/v0.1.0...v1.0.0
+[0.1.0]:      https://github.com/JackKXCO/kxco-post-quantum/releases/tag/v0.1.0

package/README.md

@@ -1,14 +1,49 @@
-# @kxco/post-quantum
+# kxco-post-quantum
 
 **Production-tested post-quantum cryptography patterns.** Deterministic key derivation, hybrid webhook signing, and kid fingerprinting — the integration patterns KXCO uses in production across KnightsVault, KXCO Bank, KnightsBot, The Exchequer, and Armature L1.
 
-[![npm](https://img.shields.io/npm/v/@kxco/post-quantum?color=d4a017)](https://www.npmjs.com/package/@kxco/post-quantum)
-[![license](https://img.shields.io/npm/l/@kxco/post-quantum)](./LICENSE)
-[![FIPS 203](https://img.shields.io/badge/FIPS%20203-ML--KEM--768-1e3a8a)](https://csrc.nist.gov/pubs/fips/203/final)
-[![FIPS 204](https://img.shields.io/badge/FIPS%20204-ML--DSA--65-1e3a8a)](https://csrc.nist.gov/pubs/fips/204/final)
+[![CI](https://github.com/JackKXCO/kxco-post-quantum/actions/workflows/ci.yml/badge.svg)](https://github.com/JackKXCO/kxco-post-quantum/actions/workflows/ci.yml)
+[![Socket](https://socket.dev/api/badge/npm/package/kxco-post-quantum)](https://socket.dev/npm/package/kxco-post-quantum)
+[![npm provenance](https://img.shields.io/npm/v/kxco-post-quantum?label=npm%20%E2%9C%93%20provenance)](https://www.npmjs.com/package/kxco-post-quantum)
+[![live verifier](https://img.shields.io/website?url=https%3A%2F%2Fchain.kxco.ai%2Fwallet%2Fverify&up_message=live&up_color=brightgreen&down_message=down&down_color=red&label=production)](https://chain.kxco.ai/wallet/verify)
 
 ---
 
+## 60-second quickstart
+
+Install the package, fetch a freshly signed test vector from the live KXCO platform, post it back to verify — **200 OK**. The same code path every production webhook runs.
+
+```bash
+# 1. Install
+npm install kxco-post-quantum
+
+# 2. Fetch a freshly signed test vector from the live KXCO platform
+curl -s https://chain.kxco.ai/wallet/api/verify-demo > vector.json
+
+# 3. Post it back — the server verifies HMAC + ML-DSA-65 against the live key
+node --input-type=module -e '
+  import fs from "node:fs"
+  const v = JSON.parse(fs.readFileSync("vector.json", "utf8"))
+  const h = v.headers
+  const res = await fetch("https://chain.kxco.ai/wallet/api/verify-demo", {
+    method:  "POST",
+    headers: { "Content-Type": "application/json" },
+    body:    JSON.stringify({
+      timestamp:  h["X-KXCO-Timestamp"],
+      body:       v.body,
+      hmacSecret: v.hmacSecret,
+      hmacSig:    h["X-KXCO-Signature"],
+      pqSig:      h["X-KXCO-PQ-Signature"].replace(/^ml-dsa-65=/, ""),
+      pqKid:      h["X-KXCO-PQ-Kid"],
+    }),
+  })
+  console.log(res.status, await res.json())
+'
+# → 200 { kidMatch: true, hmac: { ok: true }, pq: { ok: true }, ... }
+```
+
+The platform signs every fetch fresh — no cached fixtures, no replay. `verify-demo` exposes the HMAC secret for the demo only; in production the HMAC secret never leaves the receiving server.
+
 ## Used in production at
 
 This is not a sample library. It runs in production at KXCO across multiple products. You can verify this yourself without any cooperation from us:

package/SECURITY.md

@@ -1,94 +1,27 @@
 # Security Policy
 
 ## Reporting a vulnerability
-
-Email **security@kxco.ai** with details. Do not open public GitHub issues for vulnerabilities.
-
-- Acknowledgement within 48 hours
-- Initial triage of critical findings within 5 business days
-- Coordinated disclosure: we patch first, credit the reporter, publish a CVE / GHSA
+Email **security@kxco.ai**. Do not open public issues for security reports.
+PGP key available on request. We respond within 48 hours and credit reporters
+in `CHANGELOG.md` unless they request otherwise.
 
 ## Scope
-
-This package's surface is the **integration patterns**: deterministic key derivation, kid fingerprinting, envelope construction, hybrid HMAC + ML-DSA-65 webhook signing, replay-window enforcement. Vulnerabilities in the **underlying NIST primitives** belong upstream.
-
-| Layer | Where it lives | Where to report |
-|---|---|---|
-| ML-DSA-65 / ML-KEM-768 algorithm bugs | `@noble/post-quantum` | https://github.com/paulmillr/noble-post-quantum/security |
-| HKDF-SHA-512 / HMAC-SHA-256 / SHA-256 | Node.js `crypto` module | https://github.com/nodejs/node/security |
-| Integration patterns (this library) | this repo | security@kxco.ai |
-
-## Cryptographic posture
-
-### Algorithms and standards
-
-| Primitive | Standard | Security level |
-|---|---|---|
-| ML-DSA-65 (Dilithium3) | [NIST FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) | Category 3 (≈ AES-192) |
-| ML-KEM-768 (Kyber768) | [NIST FIPS 203](https://csrc.nist.gov/pubs/fips/203/final) | Category 3 (≈ AES-192) |
-| HKDF-SHA-512 | [NIST SP 800-56C](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Cr2.pdf), [RFC 5869](https://datatracker.ietf.org/doc/html/rfc5869) | n/a (KDF) |
-| HMAC-SHA-256 | [FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) | Post-quantum safe as MAC |
-| SHA-256 (for kid) | [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) | Truncated to 8 bytes |
-
-### Pinned upstream
-
-This package is pinned to:
-
-```
-@noble/post-quantum@0.2.1
-integrity: sha512-ImgfMp9notXSEocz464o1AefYfFWEkkszKMGO+ZiTn73yIBFeNyEHKQUMS+SheJwSNymldSts6YyVcQDjcnVVg==
-```
-
-`@noble/post-quantum` was independently audited by **Cure53** in 2024. Audit report: https://github.com/paulmillr/noble-post-quantum#security
-
-### FIPS posture (be honest)
-
-- ✅ Algorithms implemented are NIST FIPS-standardised (203, 204).
-- ❌ This module is **not** FIPS 140-3 CMVP-validated. There is no FIPS module certificate.
-- ⚠️ "FIPS-aligned" is the correct way to describe this package; "FIPS-certified" is not.
-
-For deployments where FIPS 140-3 module validation is mandatory, run cryptographic operations inside a validated HSM (AWS CloudHSM, Thales Luna, YubiHSM 2, etc.) and use this library only for envelope construction, kid generation, and verification of incoming signatures.
-
-## Threat model
-
-What this library defends against and what it does not.
-
-### In scope
-
-- ✅ **Quantum adversary against signature non-repudiation** — ML-DSA-65 is the FIPS 204 standard for this.
-- ✅ **Quantum adversary against confidentiality of new sessions** — ML-KEM-768 (FIPS 203) for KEM; combine with AES-256-GCM (or equivalent AEAD) for the symmetric envelope.
-- ✅ **Forgery of webhook deliveries** — hybrid HMAC + ML-DSA defends against both classical and quantum forgery. ML-DSA adds non-repudiation HMAC cannot give.
-- ✅ **Replay attacks** — `webhook.verifyDelivery` enforces a default 5-minute timestamp window.
-- ✅ **Tampering with body** — both signatures cover the exact `timestamp + "." + raw_body` envelope.
-- ✅ **Wrong-key acceptance** — `pinnedKid` check fails fast before any signature verification.
-
-### Out of scope (caller's responsibility)
-
-- ❌ **Master secret storage**. Keep `KXCO_KEY_MASTER` (or equivalent) in environment variables, a KMS, or an HSM. This library does not store secrets.
-- ❌ **Key rotation procedures**. Rotating the master changes every derived keypair; downstream consumers must refresh their pinned kid.
-- ❌ **TLS / transport encryption**. Use hybrid `X25519MLKEM768` at the public edge — outside this library's scope.
-- ❌ **Receiving raw bodies byte-for-byte**. If you re-stringify JSON before verifying, you will mangle the signature input. Use Express `express.raw({ type: 'application/json' })` or equivalent.
-- ❌ **Domain separation hygiene**. If you reuse the same `info` string for signing and encryption keypairs, you create a cross-protocol attack surface. Use distinct `info` per purpose.
-- ❌ **Constant-time comparison of secrets outside this library**. We provide `kidEquals` and `verifyHmac`; if you compare HMAC tags yourself with `===`, that's on you.
-
-### Acknowledged limitations
-
-- **Default replay window is 300 seconds**. Configurable via `windowSeconds`. Tighten for high-security paths.
-- **`fingerprint` uses 8 bytes (16 hex)**. SHA-256 truncation. Collision-resistant for the scale of keys in use today (one platform key, occasionally rotated). If you anticipate billions of distinct keys, extend to a longer prefix.
-- **Side-channel posture**. `@noble/post-quantum` targets constant-time execution; this wrapper adds constant-time string comparisons. Higher-assurance deployments should run operations inside a hardware boundary.
-- **`signDelivery` calls `Date.now()`**. If your system clock is wrong, verifiers will reject your deliveries. Run NTP.
-
-## Reproducibility
-
-Test vectors in `test/vectors.json` pin the library's outputs bit-for-bit. Anyone can run `npm test` to verify the library produces identical outputs to the recorded vectors. If a future release changes any output, the run-vectors check fails — this is a deliberate tripwire on cryptographic regressions.
-
-## Disclosure history
-
-None yet. This is a v1 release. Vulnerabilities will be disclosed here as GHSA advisories with CVE numbers where applicable.
-
-## Versioning and support
-
-- We support the latest minor release on the latest major (currently 1.x).
-- Critical security fixes are backported to the previous minor for 6 months.
-- Major version bumps (2.x → 3.x) only occur when the cryptographic primitives or signed envelope format changes; minor bumps add features without breaking the API.
-- `npm install kxco-post-quantum` always pulls the supported version.
+In scope:
+- Cryptographic correctness of the wrappers in this package
+- Constant-time guarantees on signature/HMAC comparison
+- Replay-window enforcement in `webhook.verify`
+- HKDF domain separation in `derive`
+- Kid fingerprint collision behaviour
+
+Out of scope (report upstream to https://github.com/paulmillr/noble-post-quantum):
+- Bugs in the underlying ML-DSA-65, ML-KEM-768, or HKDF primitives
+
+## Algorithms used
+- ML-DSA-65 — NIST FIPS 204 (lattice signatures)
+- ML-KEM-768 — NIST FIPS 203 (key encapsulation)
+- HMAC-SHA-256
+- HKDF-SHA-512 (RFC 5869)
+
+## Disclosure
+We follow coordinated disclosure with a 90-day default window.
+For actively-exploited issues we ship a patch release within 48 hours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Production-tested post-quantum cryptography patterns: deterministic key derivation, hybrid webhook signing, and kid fingerprinting. Built on @noble/post-quantum. Used in production at KXCO.",
   "keywords": [
     "post-quantum",
@@ -19,6 +19,7 @@
   "license": "MIT",
   "author": "KXCO by Knightsbridge <hello@kxco.ai>",
   "homepage": "https://kxco.ai",
+  "funding": "https://kxco.ai",
   "repository": {
     "type": "git",
     "url": "https://github.com/JackKXCO/kxco-post-quantum.git"
@@ -27,23 +28,40 @@
     "url": "https://github.com/JackKXCO/kxco-post-quantum/issues"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".":          "./src/index.js",
-    "./ml-dsa":   "./src/ml-dsa.js",
-    "./ml-kem":   "./src/ml-kem.js",
-    "./derive":   "./src/derive.js",
-    "./webhook":  "./src/webhook.js",
-    "./kid":      "./src/kid.js"
+    ".": {
+      "types":  "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./ml-dsa": {
+      "types":  "./src/ml-dsa.d.ts",
+      "import": "./src/ml-dsa.js"
+    },
+    "./ml-kem": {
+      "types":  "./src/ml-kem.d.ts",
+      "import": "./src/ml-kem.js"
+    },
+    "./derive": {
+      "types":  "./src/derive.d.ts",
+      "import": "./src/derive.js"
+    },
+    "./webhook": {
+      "types":  "./src/webhook.d.ts",
+      "import": "./src/webhook.js"
+    },
+    "./kid": {
+      "types":  "./src/kid.d.ts",
+      "import": "./src/kid.js"
+    }
   },
   "files": [
-    "src/",
-    "test/vectors.json",
-    "test/run-vectors.js",
+    "src",
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "AUDIT.md",
     "CHANGELOG.md"
   ],
   "engines": {
@@ -56,5 +74,9 @@
     "test":             "node --test test/basic.test.js && node test/run-vectors.js",
     "test:vectors":     "node test/run-vectors.js",
     "generate:vectors": "node test/generate-vectors.js > test/vectors.json"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
   }
 }

package/src/derive.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+
+/**
+ * Derive a deterministic seed from a master secret + an info string,
+ * using HKDF-SHA-512 with an empty salt.
+ *
+ * Same `master + info + length` always produces the same seed.
+ *
+ * @param master — high-entropy input keying material (≥16 bytes)
+ * @param info   — domain separation tag (eg. 'kxco-platform-ml-dsa-65-v1')
+ * @param length — output seed length in bytes (32 for ML-DSA, 64 for ML-KEM)
+ *
+ * @throws {Error} if `master` is shorter than 16 bytes
+ * @throws {Error} if `info` is empty or not a string
+ */
+export function deriveSeed(
+  master: Buffer | Uint8Array,
+  info:   string,
+  length: number,
+): Buffer

package/src/index.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="node" />
+
+export * as mlDsa  from './ml-dsa.js'
+export * as mlKem  from './ml-kem.js'
+export * from './derive.js'
+export * from './kid.js'
+export * as webhook from './webhook.js'

package/src/kid.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="node" />
+
+/**
+ * Compute a 16-hex-character fingerprint of a public key:
+ * the first 8 bytes of `SHA-256(public_key)`, hex-encoded.
+ *
+ * Stable for the lifetime of the keypair. Used to identify which
+ * platform key signed an outbound delivery without including the
+ * full 1952-byte public key in every request.
+ *
+ * @param publicKey — raw bytes or hex string
+ */
+export function fingerprint(publicKey: Buffer | Uint8Array | string): string
+
+/**
+ * Constant-time comparison of two kid strings.
+ *
+ * Use this instead of `===` when comparing kids that may be
+ * influenced by untrusted input — eg. an `X-KXCO-PQ-Kid` header.
+ */
+export function kidEquals(a: string, b: string): boolean

package/src/ml-dsa.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="node" />
+
+export interface MlDsaKeypair {
+  /** 1952-byte public key */
+  publicKey: Buffer
+  /** 4032-byte secret key */
+  secretKey: Buffer
+}
+
+/**
+ * Generate an ML-DSA-65 (NIST FIPS 204) keypair deterministically
+ * from a master + domain-separation info string.
+ *
+ * Same inputs always produce the same keypair — no state, no DB row.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlDsaKeypair
+
+/**
+ * Sign a message under an ML-DSA-65 secret key. Returns the signature
+ * as a hex string (3309 bytes = 6618 hex characters).
+ */
+export function sign(
+  secretKey: Buffer | Uint8Array,
+  message:   Buffer | string,
+): string
+
+/**
+ * Verify a hex-encoded ML-DSA-65 signature against a public key + message.
+ * Returns `false` on any error (invalid hex, wrong length, mismatch).
+ */
+export function verify(
+  publicKey: Buffer | Uint8Array,
+  message:   Buffer | string,
+  sigHex:    string,
+): boolean
+
+/**
+ * Raw `@noble/post-quantum` ML-DSA-65 primitive, re-exported for callers
+ * who want the lower-level API. The wrapper functions above are
+ * recommended for production use.
+ */
+export const ml_dsa65: typeof import('@noble/post-quantum/ml-dsa').ml_dsa65

package/src/ml-kem.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+
+export interface MlKemKeypair {
+  /** 1184-byte public key */
+  publicKey: Buffer
+  /** 2400-byte secret key */
+  secretKey: Buffer
+}
+
+export interface MlKemEncapsulation {
+  /** 1088-byte KEM ciphertext to transmit to the recipient */
+  ciphertext: Buffer
+  /** Alias for `ciphertext` (mirrors @noble/post-quantum's camelCase) */
+  cipherText: Buffer
+  /** 32-byte shared secret to use as a symmetric AEAD key */
+  sharedSecret: Buffer
+}
+
+/**
+ * Generate an ML-KEM-768 (NIST FIPS 203) keypair deterministically
+ * from a master + domain-separation info string.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlKemKeypair
+
+/**
+ * Encapsulate a shared secret to the recipient's ML-KEM-768 public key.
+ *
+ * The recipient calls `decapsulate(ciphertext, secretKey)` to recover
+ * the same shared secret. Use the shared secret as a symmetric AEAD
+ * key (eg. AES-256-GCM).
+ */
+export function encapsulate(publicKey: Buffer | Uint8Array): MlKemEncapsulation
+
+/**
+ * Decapsulate: recover the shared secret from a KEM ciphertext
+ * using the recipient's secret key.
+ */
+export function decapsulate(
+  ciphertext: Buffer | Uint8Array,
+  secretKey:  Buffer | Uint8Array,
+): Buffer
+
+/**
+ * Raw `@noble/post-quantum` ML-KEM-768 primitive, re-exported.
+ */
+export const ml_kem768: typeof import('@noble/post-quantum/ml-kem').ml_kem768

package/src/webhook.d.ts

@@ -0,0 +1,119 @@
+/// <reference types="node" />
+
+/**
+ * Build the canonical signed envelope: `timestamp + "." + raw_body`.
+ *
+ * Receivers MUST construct the envelope from the timestamp header and the
+ * RAW request body bytes as received. Re-serialising a parsed JSON object
+ * will not produce the same bytes and signature verification will fail.
+ */
+export function envelope(
+  timestamp: string | number,
+  rawBody:   string | Buffer,
+): Buffer
+
+/**
+ * Compute the hex HMAC-SHA-256 of the envelope using the shared secret.
+ * Returns the hex value WITHOUT the `sha256=` prefix.
+ */
+export function hmacHex(
+  secret:    string | Buffer,
+  timestamp: string | number,
+  rawBody:   string | Buffer,
+): string
+
+/**
+ * Constant-time verify of the X-KXCO-Signature header.
+ * Accepts the header value with or without the `sha256=` prefix.
+ */
+export function verifyHmac(
+  secret:    string | Buffer,
+  timestamp: string | number,
+  rawBody:   string | Buffer,
+  sigHeader: string,
+): boolean
+
+/**
+ * Produce the X-KXCO-PQ-Signature header value: the hex ML-DSA-65
+ * signature over the envelope, prefixed with `ml-dsa-65=`.
+ */
+export function pqSign(
+  secretKey: Buffer | Uint8Array,
+  timestamp: string | number,
+  rawBody:   string | Buffer,
+): string
+
+/**
+ * Verify a hex ML-DSA-65 signature header.
+ * Accepts the value with or without the `ml-dsa-65=` prefix.
+ */
+export function verifyPq(
+  publicKey: Buffer | Uint8Array,
+  timestamp: string | number,
+  rawBody:   string | Buffer,
+  sigHeader: string,
+): boolean
+
+export interface SignDeliveryArgs {
+  /** The exact body bytes that will be transmitted */
+  rawBody:     string | Buffer
+  /** Per-endpoint shared secret for HMAC */
+  hmacSecret:  string | Buffer
+  /** Raw ML-DSA-65 secret key */
+  pqSecretKey: Buffer | Uint8Array
+  /** 16-hex kid fingerprint of the matching public key */
+  pqKid:       string
+  /** Optional event name (eg. "payment.settled") */
+  event?:      string
+  /** Optional delivery / idempotency identifier */
+  deliveryId?: string
+}
+
+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-Kid':        string
+  'X-KXCO-Event'?:        string
+  'X-KXCO-Delivery'?:     string
+}
+
+/**
+ * Sign a webhook delivery. Returns the full set of headers a sender
+ * should attach to the HTTP request.
+ *
+ * The caller is responsible for sending `rawBody` byte-for-byte
+ * unchanged. The receiver verifies against the bytes as transmitted.
+ */
+export function signDelivery(args: SignDeliveryArgs): SignDeliveryHeaders
+
+export interface VerifyDeliveryArgs {
+  /** HTTP headers with LOWERCASE keys */
+  headers: Record<string, string | undefined>
+  /** The EXACT request body bytes as received */
+  rawBody: string | Buffer
+  /** Optional: enable HMAC verification by providing the shared secret */
+  hmacSecret?: string | Buffer
+  /** Optional: enable PQ verification by providing the platform public key */
+  pqPublicKey?: Buffer | Uint8Array
+  /** Required when `pqPublicKey` is provided */
+  pinnedKid?: string
+  /** Replay-window in seconds. Default 300 (5 minutes). */
+  windowSeconds?: number
+}
+
+export interface VerifyDeliveryResult {
+  hmacOk:      boolean
+  pqOk:        boolean
+  timestampOk: boolean
+  kidOk:       boolean
+}
+
+/**
+ * Verify a webhook delivery on the receiving side.
+ *
+ * Returns a breakdown of which predicates passed. A delivery is
+ * acceptable when `(hmacOk || pqOk) && timestampOk && kidOk`.
+ */
+export function verifyDelivery(args: VerifyDeliveryArgs): VerifyDeliveryResult

package/AUDIT.md

@@ -1,110 +0,0 @@
-# Audit Posture
-
-**Status as of v1.0.1 release (2026-05-21).** Self-attested. No third-party audit of this wrapper library has been performed yet. This document exists to make our posture **legible to reviewers** so the right questions get asked of the right party.
-
-If you are doing institutional due diligence, read this end-to-end before the README.
-
----
-
-## 1. What has been audited (upstream)
-
-**`@noble/post-quantum@0.2.1`** — the underlying NIST primitives we wrap — has been independently audited.
-
-| Auditor | Year | Scope | Report |
-|---|---|---|---|
-| **Cure53** | 2024 | `@noble/post-quantum` cryptographic primitives | https://github.com/paulmillr/noble-post-quantum#security |
-
-This audit covers the actual cryptographic operations: ML-DSA-65 sign/verify, ML-KEM-768 keygen/encapsulate/decapsulate, the constant-time properties, the test vector compliance with NIST's reference outputs.
-
-When you `npm install kxco-post-quantum`, the audited code is what runs the math. This wrapper does not reimplement the primitives.
-
-The exact upstream we pin:
-
-```
-@noble/post-quantum@0.2.1
-integrity: sha512-ImgfMp9notXSEocz464o1AefYfFWEkkszKMGO+ZiTn73yIBFeNyEHKQUMS+SheJwSNymldSts6YyVcQDjcnVVg==
-```
-
-## 2. What has NOT been audited (this wrapper)
-
-The integration patterns in this package — `pqSigner` derivation, kid fingerprinting, webhook envelope construction, hybrid HMAC + ML-DSA signing, timestamp replay enforcement — have not been independently audited.
-
-What we have done:
-
-- **Internal review** by the KXCO engineering team and KXCO Cybersecurity (lead: Sean O'Coiligh, 30+ years cybersecurity, formerly led Offensive Cyber at the DTCC Cyber Threat Fusion Center)
-- **Reproducible test vectors** in `test/vectors.json` covering every primitive — anyone running `npm test` gets the same outputs the maintainers see
-- **Production deployment** across the KXCO platform (KnightsVault, KXCO Bank, KnightsBot, The Exchequer, Armature L1) since November 2025
-- **Public verifiable proof** of the signing identity at https://chain.kxco.ai/wallet/api/.well-known/kxco-pq-pubkey — anyone can fetch the kid, install this library, and verify signatures from the production fleet
-
-What we have **not** done:
-
-- ❌ Engaged a third-party auditor for this wrapper
-- ❌ Held a public security review window with bug bounty
-- ❌ Obtained CMVP FIPS 140-3 module certification
-- ❌ Submitted to ENISA / NCSC / BSI evaluation schemes
-
-## 3. Audit roadmap
-
-| Milestone | Target | Owner |
-|---|---|---|
-| Engage external auditor for wrapper integration patterns | Q3 2026 | KXCO Engineering |
-| Public bug bounty programme | Q4 2026 | KXCO Security |
-| Apply for FIPS 140-3 CMVP validation of a cryptographic module deployment using this library + an HSM | 2027 | KXCO Compliance |
-| NIST PQC Workshop presentation (production lessons) | When workshop opens for 2026/27 | Shayne Heffernan + Sean O'Coiligh |
-
-The exact dates depend on engineering and budget capacity. The order is committed.
-
-## 4. Reproducibility checks (run these yourself)
-
-You do not have to trust us. Run these to verify:
-
-```bash
-# Clone and install
-git clone https://github.com/JackKXCO/kxco-post-quantum
-npm install
-
-# Run the full test suite — primitives + vectors
-npm test
-
-# Run vector verification only
-npm run test:vectors
-
-# Fetch the live production platform key and verify offline
-curl https://chain.kxco.ai/wallet/api/.well-known/kxco-pq-pubkey
-```
-
-Expected: `npm test` reports `✓ All 29 checks pass — library output matches pinned vectors bit-for-bit.`
-
-## 5. Threat model summary
-
-See [SECURITY.md](./SECURITY.md) for the full threat model. In short:
-
-- **In scope:** quantum signature non-repudiation, quantum-safe KEM, webhook forgery resistance, replay rejection, body tamper detection, wrong-key rejection.
-- **Out of scope:** master secret storage (use KMS/HSM), TLS termination (use OpenSSL 3.5+), receiving raw bodies byte-for-byte (use `express.raw` or equivalent), key rotation procedures (caller's responsibility).
-
-## 6. Bug-finding signals
-
-If you are evaluating this library, look at:
-
-- **Test coverage:** 9 functional tests + 29 vector checks = 38 distinct assertions covering every export
-- **Code size:** ~280 source lines across 6 modules — small enough to review end-to-end in an afternoon
-- **Dependency surface:** one runtime dependency (`@noble/post-quantum`), itself audited
-- **Determinism:** every output is reproducible from inputs — no hidden state, no globals beyond a lazy cache, no network
-- **API stability:** v1.0 commits to the public surface listed in CHANGELOG.md
-
-## 7. Reviewer checklist
-
-For institutional reviewers, the smallest version of "did they actually do the work":
-
-- [ ] `npm view kxco-post-quantum dist.signatures` returns a signed package
-- [ ] `npm test` passes after fresh clone + install
-- [ ] `npm run test:vectors` matches the pinned vectors
-- [ ] `curl https://chain.kxco.ai/wallet/api/.well-known/kxco-pq-pubkey` returns a valid ML-DSA-65 public key
-- [ ] The kid (`kid` field above) matches `fingerprint()` of the returned `publicKey` field
-- [ ] An outbound webhook from `chain.kxco.ai` verifies with `webhook.verifyDelivery` against the pinned kid
-
-All six are reproducible without any cooperation from KXCO. That's the standard we hold ourselves to.
-
----
-
-**Contact:** security@kxco.ai for vulnerability reports. audit@kxco.ai for due-diligence and review requests.

package/test/run-vectors.js

@@ -1,155 +0,0 @@
-// Run-vectors — verifies every entry in test/vectors.json against the library.
-//
-// Anyone can `git clone && npm install && node test/run-vectors.js` and see
-// the same bit-for-bit outputs. This is the reproducibility claim.
-//
-// Exit code 0 = all pass. Exit code 1 = at least one mismatch.
-
-import { readFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
-
-import {
-  mlDsa, mlKem, deriveSeed, fingerprint, webhook,
-} from '../src/index.js'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const vectors = JSON.parse(readFileSync(join(here, 'vectors.json'), 'utf8'))
-
-const sha256hex = (b) => createHash('sha256').update(b).digest('hex')
-
-let pass = 0
-let fail = 0
-const failures = []
-
-function check(group, name, expected, actual) {
-  const ok = expected === actual ||
-    (typeof expected === 'boolean' && expected === actual) ||
-    (typeof expected === 'number'  && expected === actual)
-  if (ok) {
-    pass++
-  } else {
-    fail++
-    failures.push({ group, name, expected, actual })
-  }
-}
-
-// deriveSeed
-for (const v of vectors.deriveSeed) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const got = deriveSeed(master, v.info, v.length).toString('hex')
-  check('deriveSeed', v.name, v.expect_hex, got)
-}
-
-// mlDsa keypairFromMaster — pin SHA-256 of pub + secret bytes
-for (const v of vectors.mlDsa_keypairFromMaster) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const kp = mlDsa.keypairFromMaster(master, v.info)
-  check('mlDsa.keypairFromMaster', v.name + ' [publicKey_sha256]', v.publicKey_sha256, sha256hex(kp.publicKey))
-  check('mlDsa.keypairFromMaster', v.name + ' [secretKey_sha256]', v.secretKey_sha256, sha256hex(kp.secretKey))
-  check('mlDsa.keypairFromMaster', v.name + ' [publicKey_bytes]',  v.publicKey_bytes,  kp.publicKey.length)
-  check('mlDsa.keypairFromMaster', v.name + ' [secretKey_bytes]',  v.secretKey_bytes,  kp.secretKey.length)
-}
-
-// mlDsa sign round-trip
-for (const v of vectors.mlDsa_sign_roundtrip) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const kp = mlDsa.keypairFromMaster(master, v.info)
-  const sig = mlDsa.sign(kp.secretKey, v.message_utf8)
-  const verified = mlDsa.verify(kp.publicKey, v.message_utf8, sig)
-  check('mlDsa.sign_roundtrip', v.name + ' [verify]', v.expect_verify, verified)
-  check('mlDsa.sign_roundtrip', v.name + ' [sig_hex_length]', v.expect_sig_hex_length, sig.length)
-}
-
-// mlKem keypairFromMaster
-for (const v of vectors.mlKem_keypairFromMaster) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const kp = mlKem.keypairFromMaster(master, v.info)
-  check('mlKem.keypairFromMaster', v.name + ' [publicKey_sha256]', v.publicKey_sha256, sha256hex(kp.publicKey))
-  check('mlKem.keypairFromMaster', v.name + ' [secretKey_sha256]', v.secretKey_sha256, sha256hex(kp.secretKey))
-  check('mlKem.keypairFromMaster', v.name + ' [publicKey_bytes]',  v.publicKey_bytes,  kp.publicKey.length)
-  check('mlKem.keypairFromMaster', v.name + ' [secretKey_bytes]',  v.secretKey_bytes,  kp.secretKey.length)
-}
-
-// mlKem encapsulate round-trip
-for (const v of vectors.mlKem_encapsulate_roundtrip) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const kp = mlKem.keypairFromMaster(master, v.info)
-  const { ciphertext, sharedSecret } = mlKem.encapsulate(kp.publicKey)
-  const recovered = mlKem.decapsulate(ciphertext, kp.secretKey)
-  check('mlKem.encapsulate_roundtrip', v.name + ' [secret_bytes]', v.expect_sharedSecret_bytes, sharedSecret.length)
-  check('mlKem.encapsulate_roundtrip', v.name + ' [ct_bytes]',     v.expect_ciphertext_bytes,   ciphertext.length)
-  check('mlKem.encapsulate_roundtrip', v.name + ' [recovered_eq]', sha256hex(sharedSecret),     sha256hex(recovered))
-}
-
-// fingerprint
-for (const v of vectors.fingerprint) {
-  let input
-  if (v.input_hex)       input = Buffer.from(v.input_hex, 'hex')
-  else if (v.input_utf8) input = Buffer.from(v.input_utf8, 'utf8')
-  else if (v.input_source && v.input_source.includes('mlDsa.keypairFromMaster')) {
-    input = mlDsa.keypairFromMaster(Buffer.from('00'.repeat(32), 'hex'), 'platform-v1').publicKey
-  }
-  const got = fingerprint(input)
-  check('fingerprint', v.name, v.expect_kid, got)
-}
-
-// webhook envelope
-for (const v of vectors.webhook_envelope) {
-  const got = webhook.envelope(v.timestamp, v.body_utf8).toString('hex')
-  check('webhook.envelope', v.name, v.expect_envelope_hex, got)
-}
-
-// webhook hmac
-for (const v of vectors.webhook_hmac) {
-  const got = webhook.hmacHex(v.secret_utf8, v.timestamp, v.body_utf8)
-  check('webhook.hmac', v.name, v.expect_hmac_hex, got)
-}
-
-// webhook hybrid round-trip with FRESH timestamp (vector's timestamp is stale on purpose; we use Date.now() here)
-for (const v of vectors.webhook_hybrid_roundtrip) {
-  const master = Buffer.from(v.master_hex, 'hex')
-  const kp = mlDsa.keypairFromMaster(master, v.info)
-  const kid = fingerprint(kp.publicKey)
-  const freshTs = Math.floor(Date.now() / 1000).toString()
-  const headers = webhook.signDelivery({
-    rawBody:     v.body_utf8,
-    hmacSecret:  v.hmac_secret_utf8,
-    pqSecretKey: kp.secretKey,
-    pqKid:       kid,
-  })
-  const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]))
-  const r = webhook.verifyDelivery({
-    headers:     lower,
-    rawBody:     v.body_utf8,
-    hmacSecret:  v.hmac_secret_utf8,
-    pqPublicKey: kp.publicKey,
-    pinnedKid:   kid,
-  })
-  check('webhook.hybrid_roundtrip', v.name + ' [hmac_ok]', v.expect_hmac_ok, r.hmacOk)
-  check('webhook.hybrid_roundtrip', v.name + ' [pq_ok]',   v.expect_pq_ok,   r.pqOk)
-  check('webhook.hybrid_roundtrip', v.name + ' [ts_ok]',   v.expect_timestamp_ok_when_fresh, r.timestampOk)
-}
-
-// Report
-console.log('')
-console.log(`kxco-post-quantum test vectors`)
-console.log(`Generated:  ${vectors.generated_at}`)
-console.log(`Library:    ${vectors.library}`)
-console.log(`Underlying: ${vectors.underlying_primitive}`)
-console.log('')
-
-if (fail === 0) {
-  console.log(`✓ All ${pass} checks pass — library output matches pinned vectors bit-for-bit.`)
-  process.exit(0)
-} else {
-  console.log(`✗ ${fail} failed, ${pass} passed.`)
-  for (const f of failures) {
-    console.log(`\n  GROUP:    ${f.group}`)
-    console.log(`  NAME:     ${f.name}`)
-    console.log(`  EXPECTED: ${f.expected}`)
-    console.log(`  ACTUAL:   ${f.actual}`)
-  }
-  process.exit(1)
-}

package/test/vectors.json

@@ -1,137 +0,0 @@
-{
-  "version": "1.0",
-  "generated_at": "2026-05-20T18:58:39.432Z",
-  "description": "Deterministic test vectors for kxco-post-quantum. Run test/run-vectors.js to verify these match the library output bit-for-bit.",
-  "library": "kxco-post-quantum",
-  "underlying_primitive": "@noble/post-quantum",
-  "notes": [
-    "ML-DSA-65 signatures are randomized — we cannot pin signature bytes. We pin keypair hashes and verify round-trip.",
-    "ML-KEM encapsulation is randomized — we pin keypair hashes and verify decapsulate round-trip in the runner.",
-    "All hex is lowercase. All UTF-8 strings are explicit."
-  ],
-  "deriveSeed": [
-    {
-      "name": "zero master, info=role-a, length=32",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "role-a",
-      "length": 32,
-      "expect_hex": "873c6de3e076daede530be45f1f7953a29fec20648557429d2607e08c3ad8d7c"
-    },
-    {
-      "name": "zero master, info=role-b, length=32 (different info → different seed)",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "role-b",
-      "length": 32,
-      "expect_hex": "80f852c16846b2a44c64c7742cd8df83f9b1a98f969dd0496904c3bdd08cd8cc"
-    },
-    {
-      "name": "0x11 master, info=platform-v1, length=64",
-      "master_hex": "1111111111111111111111111111111111111111111111111111111111111111",
-      "info": "platform-v1",
-      "length": 64,
-      "expect_hex": "a9df8abe6efa342d56b911f8eeea67bb553d675e4411ea046b9aca2fa409fcc2b92166b6117606627faed0a66f890403ad2fa6d9d3dadc69bd5559f3da92eec3"
-    }
-  ],
-  "mlDsa_keypairFromMaster": [
-    {
-      "name": "zero master, info=platform-v1",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "platform-v1",
-      "publicKey_sha256": "dc29825b2f9cc9f1671ca499c27d013c2b4ac86e1c6ce365f40556ec82916e57",
-      "publicKey_bytes": 1952,
-      "secretKey_sha256": "fad19856458d742f62d79dbd772cfaea7ad2e432111a9663d159b079d15f51eb",
-      "secretKey_bytes": 4032
-    },
-    {
-      "name": "0xff master, info=test",
-      "master_hex": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
-      "info": "test",
-      "publicKey_sha256": "b5efe3602d7d87e29ce642ff44a682ded5408e43b965b2a22e5aedec0d8ab9aa",
-      "publicKey_bytes": 1952,
-      "secretKey_sha256": "abd46a2431e7e82249e798e7ca634785ba1f43e052e4649a4e0e02536db47770",
-      "secretKey_bytes": 4032
-    }
-  ],
-  "mlDsa_sign_roundtrip": [
-    {
-      "name": "sign known message with keypair from zero master; verify true",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "platform-v1",
-      "message_utf8": "hello kxco",
-      "expect_verify": true,
-      "expect_sig_hex_length": 6618
-    }
-  ],
-  "mlKem_keypairFromMaster": [
-    {
-      "name": "zero master, info=platform-v1",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "platform-v1",
-      "publicKey_sha256": "8393aadd8e9070c8b43b65a1e05eb43f9c9e7e32ba7880261a2cbcabda58c188",
-      "publicKey_bytes": 1184,
-      "secretKey_sha256": "8d21f316efc198ba3cab8e7c9270f57efe351bed4d0f66c66f6d454d4282423e",
-      "secretKey_bytes": 2400
-    }
-  ],
-  "mlKem_encapsulate_roundtrip": [
-    {
-      "name": "encapsulate to keypair from zero master; decapsulate recovers same secret",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "platform-v1",
-      "expect_sharedSecret_bytes": 32,
-      "expect_ciphertext_bytes": 1088
-    }
-  ],
-  "fingerprint": [
-    {
-      "name": "fingerprint of 32 zero bytes",
-      "input_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "expect_kid": "66687aadf862bd77"
-    },
-    {
-      "name": "fingerprint of 32 0xff bytes",
-      "input_hex": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
-      "expect_kid": "af9613760f72635f"
-    },
-    {
-      "name": "fingerprint of UTF-8 string 'kxco'",
-      "input_utf8": "kxco",
-      "expect_kid": "00932b8f81e33fa2"
-    },
-    {
-      "name": "fingerprint of ML-DSA-65 platform pubkey from zero master",
-      "input_source": "mlDsa.keypairFromMaster(0x00*32, \"platform-v1\").publicKey",
-      "expect_kid": "dc29825b2f9cc9f1"
-    }
-  ],
-  "webhook_envelope": [
-    {
-      "name": "envelope concatenation",
-      "timestamp": "1748000000",
-      "body_utf8": "{\"event\":\"payment.settled\",\"amount\":1000}",
-      "expect_envelope_hex": "313734383030303030302e7b226576656e74223a227061796d656e742e736574746c6564222c22616d6f756e74223a313030307d"
-    }
-  ],
-  "webhook_hmac": [
-    {
-      "name": "HMAC-SHA-256 over envelope",
-      "secret_utf8": "shared-secret-bytes",
-      "timestamp": "1748000000",
-      "body_utf8": "{\"event\":\"payment.settled\",\"amount\":1000}",
-      "expect_hmac_hex": "63ed31450be6c8771c2eb9a92888aecd814431360ac06aaac95faa94cf5bd665"
-    }
-  ],
-  "webhook_hybrid_roundtrip": [
-    {
-      "name": "sign + verify with platform keypair from zero master",
-      "master_hex": "0000000000000000000000000000000000000000000000000000000000000000",
-      "info": "platform-v1",
-      "timestamp": "1748000000",
-      "body_utf8": "{\"event\":\"payment.settled\",\"amount\":1000}",
-      "hmac_secret_utf8": "shared-secret-bytes",
-      "expect_hmac_ok": true,
-      "expect_pq_ok": true,
-      "expect_timestamp_ok_when_fresh": true
-    }
-  ]
-}