kxco-post-quantum 1.0.2 → 1.1.0

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-dsa.js

@@ -3,24 +3,47 @@
 // Module-lattice signatures. Security Category 3 (≈ AES-192). Public key 1952
 // bytes, signature 3309 bytes. Resistant to attacks by quantum computers.
 //
-// This module wraps @noble/post-quantum with deterministic keygen-from-seed
-// and ergonomic buffer-in/hex-out helpers used throughout KXCO production.
+// Isomorphic: works in Node and modern browsers. Returns Buffer on Node
+// (backwards compatible), Uint8Array in browsers.
 
 import { ml_dsa65 } from '@noble/post-quantum/ml-dsa'
 import { deriveSeed } from './derive.js'
 
+const HAS_BUFFER = typeof Buffer !== 'undefined'
+const enc = new TextEncoder()
+
+function toBytes(input) {
+  if (input instanceof Uint8Array) return input
+  if (typeof input === 'string') return enc.encode(input)
+  throw new Error('expected Uint8Array or string')
+}
+function hexToBytes(hex) {
+  if (typeof hex !== 'string' || hex.length % 2) 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
+}
+function bytesToHex(bytes) {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0')
+  return s
+}
+function wrap(bytes) {
+  return HAS_BUFFER ? Buffer.from(bytes) : bytes
+}
+
 /**
  * Generate an ML-DSA-65 keypair from a master + domain-separation info.
- * Same inputs always produce the same keypair — no state, no DB row.
  *
- * @returns {{ publicKey: Buffer, secretKey: Buffer }}
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
  */
 export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
   const seed = deriveSeed(master, info, 32)
-  const k = ml_dsa65.keygen(seed)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_dsa65.keygen(seedU8)
   return {
-    publicKey: Buffer.from(k.publicKey),
-    secretKey: Buffer.from(k.secretKey),
+    publicKey: wrap(k.publicKey),
+    secretKey: wrap(k.secretKey),
   }
 }
 
@@ -28,31 +51,28 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
  * Sign a message. Returns the signature as a hex string.
  *
  * @param {Buffer|Uint8Array} secretKey
- * @param {Buffer|string}      message
+ * @param {Buffer|Uint8Array|string} message
  * @returns {string} hex-encoded signature (6618 chars)
  */
 export function sign(secretKey, message) {
-  const msg = Buffer.isBuffer(message) ? message : Buffer.from(message, 'utf8')
-  const sig = ml_dsa65.sign(secretKey, msg)
-  return Buffer.from(sig).toString('hex')
+  const sig = ml_dsa65.sign(secretKey, toBytes(message))
+  return bytesToHex(sig)
 }
 
 /**
  * Verify a hex-encoded signature.
  *
  * @param {Buffer|Uint8Array} publicKey
- * @param {Buffer|string}      message
- * @param {string}             sigHex
+ * @param {Buffer|Uint8Array|string} message
+ * @param {string} sigHex
  * @returns {boolean}
  */
 export function verify(publicKey, message, sigHex) {
-  const msg = Buffer.isBuffer(message) ? message : Buffer.from(message, 'utf8')
   try {
-    return ml_dsa65.verify(publicKey, msg, Buffer.from(sigHex, 'hex'))
+    return ml_dsa65.verify(publicKey, toBytes(message), hexToBytes(sigHex))
   } catch {
     return false
   }
 }
 
-// Re-export the raw noble primitive for callers who want the lower-level API.
 export { 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/ml-kem.js

@@ -4,25 +4,30 @@
 // key 1184 bytes, ciphertext 1088 bytes, shared secret 32 bytes. Resistant
 // to attacks by quantum computers.
 //
-// Encapsulate to a recipient's public key: returns a ciphertext to transmit
-// and a shared secret to use as a symmetric key. Decapsulate with the secret
-// key to recover the same shared secret.
+// Isomorphic: works in Node and modern browsers. Returns Buffer on Node
+// (backwards compatible), Uint8Array in browsers.
 
 import { ml_kem768 } from '@noble/post-quantum/ml-kem'
 import { deriveSeed } from './derive.js'
 
+const HAS_BUFFER = typeof Buffer !== 'undefined'
+
+function wrap(bytes) {
+  return HAS_BUFFER ? Buffer.from(bytes) : bytes
+}
+
 /**
  * Generate an ML-KEM-768 keypair from a master + domain-separation info.
- * Deterministic — same inputs always produce the same keypair.
  *
- * @returns {{ publicKey: Buffer, secretKey: Buffer }}
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
  */
 export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
   const seed = deriveSeed(master, info, 64)
-  const k = ml_kem768.keygen(seed)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_kem768.keygen(seedU8)
   return {
-    publicKey: Buffer.from(k.publicKey),
-    secretKey: Buffer.from(k.secretKey),
+    publicKey: wrap(k.publicKey),
+    secretKey: wrap(k.secretKey),
   }
 }
 
@@ -30,18 +35,15 @@ export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
  * Encapsulate a shared secret to the recipient's public key.
  *
  * @param {Buffer|Uint8Array} publicKey
- * @returns {{ ciphertext: Buffer, sharedSecret: Buffer }}
- *   — transmit ciphertext to the recipient; use sharedSecret as a symmetric key
+ * @returns {{ ciphertext: Buffer|Uint8Array, cipherText: Buffer|Uint8Array, sharedSecret: Buffer|Uint8Array }}
  */
 export function encapsulate(publicKey) {
   const r = ml_kem768.encapsulate(publicKey)
-  // @noble/post-quantum exposes `cipherText` (camelCase). Normalise to the
-  // more standard `ciphertext` for callers; both fields are returned.
-  const ct = Buffer.from(r.cipherText ?? r.ciphertext)
+  const ct = wrap(r.cipherText ?? r.ciphertext)
   return {
     ciphertext:   ct,
     cipherText:   ct,
-    sharedSecret: Buffer.from(r.sharedSecret),
+    sharedSecret: wrap(r.sharedSecret),
   }
 }
 
@@ -50,10 +52,10 @@ export function encapsulate(publicKey) {
  *
  * @param {Buffer|Uint8Array} ciphertext
  * @param {Buffer|Uint8Array} secretKey
- * @returns {Buffer} shared secret (32 bytes)
+ * @returns {Buffer|Uint8Array} shared secret (32 bytes)
  */
 export function decapsulate(ciphertext, secretKey) {
-  return Buffer.from(ml_kem768.decapsulate(ciphertext, secretKey))
+  return wrap(ml_kem768.decapsulate(ciphertext, secretKey))
 }
 
 export { 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/src/webhook.js

@@ -9,50 +9,72 @@
 //     private key — even if the HMAC secret has been leaked to a third party.
 //
 // Both signatures cover EXACTLY the same envelope: `${timestamp}.${rawBody}`.
-// Receivers can verify either or both; verifying both is defence-in-depth.
+//
+// Isomorphic: HMAC and SHA-256 come from @noble/hashes, constant-time
+// compare is a portable byte loop. No node:crypto dependency. Runs in Node
+// and modern browsers.
 
-import { createHmac, timingSafeEqual } from 'node:crypto'
+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'
 
+const HAS_BUFFER = typeof Buffer !== 'undefined'
+const enc = new TextEncoder()
+
+function toBytes(input) {
+  if (input instanceof Uint8Array) return input
+  if (typeof input === 'string') return enc.encode(input)
+  throw new Error('expected Uint8Array or string')
+}
+function bytesToHex(bytes) {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0')
+  return s
+}
+function wrap(bytes) {
+  return HAS_BUFFER ? Buffer.from(bytes) : bytes
+}
+// Portable constant-time string compare (Node + browser).
+function constTimeEqualStrings(a, b) {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}
+
 /**
  * Build the canonical signed envelope: timestamp + "." + raw body string.
- *
- * @param {string|number} timestamp  — Unix seconds (string or number)
- * @param {string|Buffer} rawBody    — the EXACT request body as transmitted
- * @returns {Buffer}
  */
 export function envelope(timestamp, rawBody) {
-  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8')
-  return Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body])
+  const bodyBytes = toBytes(rawBody)
+  const prefixBytes = enc.encode(`${timestamp}.`)
+  const out = new Uint8Array(prefixBytes.length + bodyBytes.length)
+  out.set(prefixBytes, 0)
+  out.set(bodyBytes, prefixBytes.length)
+  return wrap(out)
 }
 
 /**
  * Compute the hex HMAC-SHA-256 of the envelope using a shared secret.
- *
- * @returns {string} hex-encoded HMAC (no `sha256=` prefix)
  */
 export function hmacHex(secret, timestamp, rawBody) {
-  return createHmac('sha256', secret).update(envelope(timestamp, rawBody)).digest('hex')
+  const env = envelope(timestamp, rawBody)
+  const envBytes = env instanceof Uint8Array ? env : new Uint8Array(env)
+  const key = toBytes(secret)
+  return bytesToHex(hmac(sha256, key, envBytes))
 }
 
 /**
- * Verify the HMAC signature in constant time. The signature header may be
- * passed with or without the `sha256=` prefix.
- *
- * @returns {boolean}
+ * Verify the HMAC signature in constant time.
  */
 export function verifyHmac(secret, timestamp, rawBody, sigHeader) {
   const expected = 'sha256=' + hmacHex(secret, timestamp, rawBody)
   const given = sigHeader.startsWith('sha256=') ? sigHeader : `sha256=${sigHeader}`
-  const a = Buffer.from(expected)
-  const b = Buffer.from(given)
-  if (a.length !== b.length) return false
-  return timingSafeEqual(a, b)
+  return constTimeEqualStrings(expected, given)
 }
 
 /**
- * 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.
  */
 export function pqSign(secretKey, timestamp, rawBody) {
   const sig = mlDsaSign(secretKey, envelope(timestamp, rawBody))
@@ -60,10 +82,7 @@ export function pqSign(secretKey, timestamp, rawBody) {
 }
 
 /**
- * Verify a hex ML-DSA-65 signature header. Accepts the value with or
- * without the `ml-dsa-65=` prefix.
- *
- * @returns {boolean}
+ * Verify a hex ML-DSA-65 signature header.
  */
 export function verifyPq(publicKey, timestamp, rawBody, sigHeader) {
   const hex = sigHeader.startsWith('ml-dsa-65=')
@@ -74,17 +93,7 @@ export function verifyPq(publicKey, timestamp, rawBody, sigHeader) {
 
 /**
  * Sign a webhook delivery. Returns the full set of headers a sender should
- * attach to the HTTP request. The caller is responsible for sending the
- * `rawBody` byte-for-byte unchanged (no re-stringification on the receiver).
- *
- * @param {object} args
- * @param {string|Buffer} args.rawBody
- * @param {string|Buffer} args.hmacSecret
- * @param {Buffer|Uint8Array} args.pqSecretKey
- * @param {string} args.pqKid             — fingerprint of the matching public key
- * @param {string} [args.event]           — optional event name
- * @param {string} [args.deliveryId]      — optional idempotency / debugging ID
- * @returns {object} HTTP header map
+ * attach to the HTTP request.
  */
 export function signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, event, deliveryId }) {
   const ts = Math.floor(Date.now() / 1000).toString()
@@ -101,24 +110,13 @@ export function signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, event, d
 }
 
 /**
- * Verify a webhook delivery on the receiving side. Both signatures are
- * checked; the result tells you which (or both) passed. Also enforces a
- * timestamp window to prevent replays.
- *
- * @param {object} args
- * @param {object} args.headers           — case-insensitive lookups OK if normalised
- * @param {string|Buffer} args.rawBody    — the EXACT body byte-for-byte
- * @param {string|Buffer} [args.hmacSecret]
- * @param {Buffer|Uint8Array} [args.pqPublicKey]
- * @param {string}  [args.pinnedKid]      — required if pqPublicKey is given
- * @param {number}  [args.windowSeconds]  — default 300 (5 minutes)
- * @returns {{ hmacOk: boolean, pqOk: boolean, timestampOk: boolean, kidOk: boolean }}
+ * 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']
+  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']
 
   const tsNum = parseInt(ts, 10)
   const timestampOk = Number.isFinite(tsNum) &&

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.