kxco-post-quantum 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knightsbridge Group — KXCO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# @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)
+
+---
+
+## What this is
+
+A higher-level package that wraps [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) — the audited, dependency-free TypeScript reference implementation of NIST's August 2024 post-quantum standards — with the integration patterns we run in production:
+
+- **Deterministic key derivation** from a master secret via HKDF-SHA-512 with domain separation
+- **Hybrid HMAC + ML-DSA-65 webhook signing** with non-repudiation
+- **Kid fingerprints** for fast key identification in delivery headers
+- **Replay protection** through enforced timestamp windows
+- **Constant-time comparisons** where it matters
+
+This package does NOT reimplement the NIST primitives. Cryptographic operations defer to `@noble/post-quantum`.
+
+## What it isn't
+
+- Not a TLS library — use OpenSSL 3.5+ or BoringSSL for `X25519MLKEM768` at the edge
+- Not a key management service — use AWS KMS, HashiCorp Vault, or an HSM for production secret storage
+- Not FIPS 140-3 certified — the underlying algorithms are FIPS-standardised; the *module* is not validated
+
+## Install
+
+```bash
+npm install @kxco/post-quantum
+```
+
+Requires Node.js 18+. ESM-only.
+
+## Quick start
+
+### Sign a webhook
+
+```js
+import { webhook, mlDsa, fingerprint, deriveSeed } from '@kxco/post-quantum'
+
+// Derive a stable platform identity from your master secret
+const KXCO_KEY_MASTER = Buffer.from(process.env.KXCO_KEY_MASTER, 'hex')
+const { publicKey, secretKey } = mlDsa.keypairFromMaster(KXCO_KEY_MASTER, 'platform-v1')
+const pqKid = fingerprint(publicKey)
+
+// On every outbound webhook
+const rawBody = JSON.stringify(payload)
+const headers = webhook.signDelivery({
+  rawBody,
+  hmacSecret:  endpointSecret,
+  pqSecretKey: secretKey,
+  pqKid,
+  event:       'payment.settled',
+  deliveryId:  jobId,
+})
+
+await fetch(url, { method: 'POST', headers, body: rawBody })
+```
+
+### Verify a webhook (receiver side)
+
+```js
+import { webhook } from '@kxco/post-quantum'
+
+// Pin these from /.well-known/kxco-pq-pubkey on first integration
+const PINNED_KID    = '4a7c9e2f1b3d5680'
+const PINNED_PUBKEY = Buffer.from('...3904 hex chars...', 'hex')
+const HMAC_SECRET   = process.env.KXCO_WEBHOOK_SECRET
+
+const result = webhook.verifyDelivery({
+  headers:      req.headers,
+  rawBody:      req.rawBody,      // the body bytes EXACTLY as received
+  hmacSecret:   HMAC_SECRET,
+  pqPublicKey:  PINNED_PUBKEY,
+  pinnedKid:    PINNED_KID,
+})
+
+if (!result.hmacOk && !result.pqOk) {
+  return res.status(401).end()
+}
+```
+
+### Encapsulate to a recipient
+
+```js
+import { mlKem } from '@kxco/post-quantum'
+
+// Sender side — encapsulate to the recipient's public key
+const { ciphertext, sharedSecret } = mlKem.encapsulate(recipientPubKey)
+// Use sharedSecret as an AES-256-GCM key; transmit ciphertext to the recipient
+
+// Recipient side — recover the same shared secret
+const recovered = mlKem.decapsulate(ciphertext, mySecretKey)
+```
+
+### Deterministic keypair from a master secret
+
+```js
+import { mlDsa, mlKem, deriveSeed } from '@kxco/post-quantum'
+
+const master = Buffer.from(process.env.KXCO_KEY_MASTER, 'hex')
+
+// Two domain-separated keypairs from the same master
+const signing    = mlDsa.keypairFromMaster(master, 'platform-signing-v1')
+const encryption = mlKem.keypairFromMaster(master, 'platform-encryption-v1')
+
+// You can also derive raw seeds for other purposes
+const customSeed = deriveSeed(master, 'audit-trail-anchor-v1', 32)
+```
+
+## The signed envelope
+
+Both signatures cover **the exact same envelope**: `timestamp + "." + raw_body`.
+
+```
+4a7c9e2f1b3d5680.{"event":"payment.settled","amount":1000}
+^^^ Unix seconds  ^^^ raw body, byte-for-byte
+```
+
+This means receivers can verify either signature independently. Verifying both is defence-in-depth: HMAC blocks tampering by anyone without the shared secret, while ML-DSA-65 binds the message to the platform identity even if the HMAC secret leaks.
+
+## Why hybrid (HMAC + PQ) instead of PQ-only?
+
+| Concern | HMAC-SHA-256 | ML-DSA-65 |
+|---|---|---|
+| Symmetric / asymmetric | Symmetric | Asymmetric |
+| Post-quantum secure | ✓ | ✓ |
+| Verify offline with shared secret | ✓ | — |
+| Non-repudiation | ✗ — anyone with the secret can forge | ✓ — only the holder of the private key can sign |
+| Library required to verify | none | a FIPS-204 library |
+| Signature size | 32 bytes | 3309 bytes |
+
+You get the cheap-and-easy verification path AND cryptographic identity binding. Receivers can adopt one signature first and the other later, or both from day one.
+
+## API
+
+### `mlDsa` — ML-DSA-65 (NIST FIPS 204, Dilithium3)
+
+- `keypairFromMaster(master, info?)` → `{ publicKey, secretKey }`
+- `sign(secretKey, message)` → hex string
+- `verify(publicKey, message, sigHex)` → boolean
+- `ml_dsa65` — the raw `@noble/post-quantum` primitive, re-exported
+
+### `mlKem` — ML-KEM-768 (NIST FIPS 203, Kyber768)
+
+- `keypairFromMaster(master, info?)` → `{ publicKey, secretKey }`
+- `encapsulate(publicKey)` → `{ ciphertext, sharedSecret }`
+- `decapsulate(ciphertext, secretKey)` → `Buffer`
+- `ml_kem768` — the raw `@noble/post-quantum` primitive, re-exported
+
+### `deriveSeed(master, info, length)` → `Buffer`
+
+HKDF-SHA-512 derivation. Empty salt is fine when `master` has high entropy. Domain-separate via `info`.
+
+### `fingerprint(publicKey)` → 16-hex `kid`
+
+First 16 hex characters of SHA-256 of the public key. Stable for the lifetime of the key.
+
+### `kidEquals(a, b)` → boolean
+
+Constant-time string compare. Use this when comparing user-supplied kids.
+
+### `webhook` — hybrid signing utilities
+
+- `envelope(timestamp, rawBody)` → `Buffer`
+- `hmacHex(secret, timestamp, rawBody)` → hex string
+- `verifyHmac(secret, timestamp, rawBody, sigHeader)` → boolean
+- `pqSign(secretKey, timestamp, rawBody)` → `ml-dsa-65=<hex>` header value
+- `verifyPq(publicKey, timestamp, rawBody, sigHeader)` → boolean
+- `signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, ... })` → header map
+- `verifyDelivery({ headers, rawBody, hmacSecret?, pqPublicKey?, pinnedKid?, windowSeconds? })` → `{ hmacOk, pqOk, timestampOk, kidOk }`
+
+## Security notes
+
+- **Keep your master secret in environment variables or a KMS / HSM.** Never commit it.
+- **Use domain separation.** Two purposes = two distinct `info` strings.
+- **Pin the kid.** Don't trust the public key on every request — fetch and pin it once.
+- **Receive raw bodies byte-for-byte.** Re-stringifying JSON before verifying changes the signature input.
+- **Enforce timestamp windows.** Defaults to 5 minutes. Set lower for higher-security paths.
+- **Constant-time compare strings.** Use `kidEquals` and `verifyHmac`, not `===`.
+
+## References
+
+- [NIST FIPS 204 — Module-Lattice-Based Digital Signature Standard](https://csrc.nist.gov/pubs/fips/204/final)
+- [NIST FIPS 203 — Module-Lattice-Based Key-Encapsulation Mechanism Standard](https://csrc.nist.gov/pubs/fips/203/final)
+- [NSA CNSA 2.0](https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF)
+- [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) — the underlying audited implementation
+- [RFC 9106 — Argon2](https://datatracker.ietf.org/doc/html/rfc9106)
+
+## About KXCO
+
+KXCO by Knightsbridge is the unification layer for global trade — settlement, issuance, compliance, custody, trading. Quantum-resistant by design. Visit [kxco.ai](https://kxco.ai).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Reporting
+
+Email `security@kxco.ai` with details. Do not open public issues for security reports.
+
+We acknowledge within 48 hours. Critical findings are triaged within 5 business days.
+
+## Scope
+
+This package wraps `@noble/post-quantum`. Vulnerabilities in the underlying NIST primitives or `@noble/post-quantum` should be reported to that project upstream. This package's scope is the integration patterns: derivation, envelope construction, kid generation, hybrid signing, verification.
+
+## Cryptographic posture
+
+- **Algorithms:** NIST FIPS 203 (ML-KEM-768), NIST FIPS 204 (ML-DSA-65). Both Security Category 3.
+- **FIPS module validation:** not held. Algorithms are FIPS-standardised; the module is not CMVP-certified.
+- **Side channels:** the underlying `@noble/post-quantum` aims for constant-time execution. This package adds constant-time string compares for kid and HMAC headers. Higher-assurance deployments should run cryptographic operations inside a FIPS 140-3 HSM.
+- **Randomness:** all operations use Node's `crypto` module CSPRNG.
+
+## Known limitations
+
+- Public-edge TLS is hybrid X25519MLKEM768, not pure-PQ. This is correct posture for 2026; pure-PQ TLS will be appropriate once the IETF finalises the relevant drafts.
+- Replay window default is 5 minutes. Reduce for tighter security.
+- Master secret rotation is the caller's responsibility — this library does not manage rotation.
+
+## Audit status
+
+- Underlying primitives (`@noble/post-quantum`) — audited by Cure53 (2024).
+- This wrapper — internal review only at present. External audit planned.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "kxco-post-quantum",
+  "version": "0.1.0",
+  "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",
+    "pqc",
+    "ml-dsa",
+    "ml-kem",
+    "dilithium",
+    "kyber",
+    "nist",
+    "fips-203",
+    "fips-204",
+    "webhook-signing",
+    "quantum-resistant",
+    "armature"
+  ],
+  "license": "MIT",
+  "author": "KXCO by Knightsbridge <hello@kxco.ai>",
+  "homepage": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kxco/post-quantum.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kxco/post-quantum/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "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"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "^0.2.1"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
+}

package/src/derive.js

@@ -0,0 +1,33 @@
+// Deterministic key derivation via HKDF-SHA-512.
+//
+// Same seed + same info = same keypair, every time. This is how the KXCO
+// platform reproduces its signing identity across replicas without storing
+// the private key in a database: the master key is the env var, the rest is
+// pure derivation.
+//
+// Domain separation through `info` is critical — using the same master key
+// for different purposes (signing vs encryption) MUST use distinct info
+// strings or you create a cross-protocol attack surface.
+
+import { hkdfSync } from 'node:crypto'
+
+/**
+ * Derive a deterministic seed from a master secret + an info string.
+ *
+ * @param {Buffer|Uint8Array} master   — high-entropy input keying material
+ * @param {string}             info    — domain separation tag (eg. 'kxco-platform-ml-dsa-65-v1')
+ * @param {number}             length  — output seed length in bytes (32 for ML-DSA, 64 for ML-KEM)
+ * @returns {Buffer}
+ */
+export function deriveSeed(master, info, length) {
+  if (!master || master.length < 16) {
+    throw new Error('deriveSeed: master keying material must be at least 16 bytes')
+  }
+  if (!info || typeof info !== 'string') {
+    throw new Error('deriveSeed: info string is required for domain separation')
+  }
+  // Empty salt with HKDF-SHA-512 is fine when master has high entropy.
+  return Buffer.from(
+    hkdfSync('sha512', master, Buffer.alloc(32), Buffer.from(info, 'utf8'), length)
+  )
+}

package/src/index.js

@@ -0,0 +1,16 @@
+// @kxco/post-quantum
+//
+// Production-tested post-quantum cryptography patterns: deterministic key
+// derivation, hybrid HMAC + ML-DSA webhook signing, kid fingerprinting.
+// Built on @noble/post-quantum. Used in production at KXCO across
+// KnightsVault, KXCO Bank, KnightsBot, The Exchequer, and Armature L1.
+//
+// This package does NOT reimplement the NIST primitives. It wraps the
+// audited @noble/post-quantum reference implementation with the integration
+// patterns we have proven in production.
+
+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.js

@@ -0,0 +1,38 @@
+// Public-key fingerprints (kid = "key identifier").
+//
+// Receivers pin a 16-hex fingerprint of the platform's public key, then
+// compare against an X-KXCO-PQ-Kid header on every webhook. Fast rejection of
+// stale or unknown keys without re-fetching the full 1952-byte public key on
+// every request.
+
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute a stable, 16-hex-character fingerprint of a public key.
+ *
+ * @param {Buffer|Uint8Array|string} publicKey  — raw bytes or hex string
+ * @returns {string} 16 hex chars (8 bytes of SHA-256)
+ */
+export function fingerprint(publicKey) {
+  const buf = typeof publicKey === 'string'
+    ? Buffer.from(publicKey, 'hex')
+    : Buffer.from(publicKey)
+  return createHash('sha256').update(buf).digest('hex').slice(0, 16)
+}
+
+/**
+ * Constant-time comparison of two kid strings. Use this instead of `===`
+ * when comparing kids from user input.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function kidEquals(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || 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
+}

package/src/ml-dsa.js

@@ -0,0 +1,58 @@
+// ML-DSA-65 helpers (NIST FIPS 204, Dilithium3).
+//
+// 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.
+
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa'
+import { deriveSeed } from './derive.js'
+
+/**
+ * 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 }}
+ */
+export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
+  const seed = deriveSeed(master, info, 32)
+  const k = ml_dsa65.keygen(seed)
+  return {
+    publicKey: Buffer.from(k.publicKey),
+    secretKey: Buffer.from(k.secretKey),
+  }
+}
+
+/**
+ * Sign a message. Returns the signature as a hex string.
+ *
+ * @param {Buffer|Uint8Array} secretKey
+ * @param {Buffer|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')
+}
+
+/**
+ * Verify a hex-encoded signature.
+ *
+ * @param {Buffer|Uint8Array} publicKey
+ * @param {Buffer|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'))
+  } catch {
+    return false
+  }
+}
+
+// Re-export the raw noble primitive for callers who want the lower-level API.
+export { ml_dsa65 }

package/src/ml-kem.js

@@ -0,0 +1,59 @@
+// ML-KEM-768 helpers (NIST FIPS 203, Kyber768).
+//
+// Module-lattice key encapsulation. Security Category 3 (≈ AES-192). Public
+// 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.
+
+import { ml_kem768 } from '@noble/post-quantum/ml-kem'
+import { deriveSeed } from './derive.js'
+
+/**
+ * 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 }}
+ */
+export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
+  const seed = deriveSeed(master, info, 64)
+  const k = ml_kem768.keygen(seed)
+  return {
+    publicKey: Buffer.from(k.publicKey),
+    secretKey: Buffer.from(k.secretKey),
+  }
+}
+
+/**
+ * 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
+ */
+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)
+  return {
+    ciphertext:   ct,
+    cipherText:   ct,
+    sharedSecret: Buffer.from(r.sharedSecret),
+  }
+}
+
+/**
+ * Decapsulate: recover the shared secret from a ciphertext using the secret key.
+ *
+ * @param {Buffer|Uint8Array} ciphertext
+ * @param {Buffer|Uint8Array} secretKey
+ * @returns {Buffer} shared secret (32 bytes)
+ */
+export function decapsulate(ciphertext, secretKey) {
+  return Buffer.from(ml_kem768.decapsulate(ciphertext, secretKey))
+}
+
+export { ml_kem768 }

package/src/webhook.js

@@ -0,0 +1,137 @@
+// Hybrid HMAC + ML-DSA-65 webhook signing — the production pattern used by
+// KXCO Bank, KnightsVault, and every product on the KXCO platform.
+//
+// Why hybrid?
+//   - HMAC-SHA-256 is symmetric and post-quantum secure as a MAC. Receivers
+//     who share the secret can verify offline with no library dependencies.
+//   - ML-DSA-65 adds NON-REPUDIATION: a receiver who only verifies the PQ
+//     signature can prove the message came from the holder of the platform
+//     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.
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { sign as mlDsaSign, verify as mlDsaVerify } from './ml-dsa.js'
+
+/**
+ * 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])
+}
+
+/**
+ * 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')
+}
+
+/**
+ * Verify the HMAC signature in constant time. The signature header may be
+ * passed with or without the `sha256=` prefix.
+ *
+ * @returns {boolean}
+ */
+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)
+}
+
+/**
+ * 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, timestamp, rawBody) {
+  const sig = mlDsaSign(secretKey, envelope(timestamp, rawBody))
+  return `ml-dsa-65=${sig}`
+}
+
+/**
+ * Verify a hex ML-DSA-65 signature header. Accepts the value with or
+ * without the `ml-dsa-65=` prefix.
+ *
+ * @returns {boolean}
+ */
+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)
+}
+
+/**
+ * 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
+ */
+export function signDelivery({ rawBody, hmacSecret, pqSecretKey, pqKid, event, deliveryId }) {
+  const ts = Math.floor(Date.now() / 1000).toString()
+  const headers = {
+    'Content-Type':        'application/json',
+    'X-KXCO-Timestamp':    ts,
+    'X-KXCO-Signature':    'sha256=' + hmacHex(hmacSecret, ts, rawBody),
+    'X-KXCO-PQ-Signature': pqSign(pqSecretKey, ts, rawBody),
+    'X-KXCO-PQ-Kid':       pqKid,
+  }
+  if (event)      headers['X-KXCO-Event']    = event
+  if (deliveryId) headers['X-KXCO-Delivery'] = deliveryId
+  return headers
+}
+
+/**
+ * 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 }}
+ */
+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 tsNum = parseInt(ts, 10)
+  const timestampOk = Number.isFinite(tsNum) &&
+    Math.abs(Date.now() / 1000 - tsNum) <= windowSeconds
+
+  const hmacOk = (hmacSecret && sigHmac && timestampOk)
+    ? verifyHmac(hmacSecret, ts, rawBody, sigHmac)
+    : false
+
+  const kidOk = pinnedKid ? kid === pinnedKid : true
+  const pqOk = (pqPublicKey && sigPq && timestampOk && kidOk)
+    ? verifyPq(pqPublicKey, ts, rawBody, sigPq)
+    : false
+
+  return { hmacOk, pqOk, timestampOk, kidOk }
+}