kxco-post-quantum 1.3.0 → 1.4.1

package/src/webhook.d.ts

@@ -1,119 +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
+/// <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

@@ -1,135 +1,135 @@
-// 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}`.
-//
-// 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 { 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.
- */
-export function envelope(timestamp, rawBody) {
-  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.
- */
-export function hmacHex(secret, timestamp, rawBody) {
-  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.
- */
-export function verifyHmac(secret, timestamp, rawBody, sigHeader) {
-  const expected = 'sha256=' + hmacHex(secret, timestamp, rawBody)
-  const given = sigHeader.startsWith('sha256=') ? sigHeader : `sha256=${sigHeader}`
-  return constTimeEqualStrings(expected, given)
-}
-
-/**
- * Produce the X-KXCO-PQ-Signature header value.
- */
-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.
- */
-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.
- */
-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.
- */
-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 }
-}
+// 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}`.
+//
+// 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 { 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.
+ */
+export function envelope(timestamp, rawBody) {
+  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.
+ */
+export function hmacHex(secret, timestamp, rawBody) {
+  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.
+ */
+export function verifyHmac(secret, timestamp, rawBody, sigHeader) {
+  const expected = 'sha256=' + hmacHex(secret, timestamp, rawBody)
+  const given = sigHeader.startsWith('sha256=') ? sigHeader : `sha256=${sigHeader}`
+  return constTimeEqualStrings(expected, given)
+}
+
+/**
+ * Produce the X-KXCO-PQ-Signature header value.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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 }
+}