kxco-post-quantum 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-05-21
+
+Same API. Same byte-for-byte outputs (all 29 pinned vectors still match).
+The package now runs in **browsers** as well as Node.
+
+### Added
+- Isomorphic runtime — every module works identically in modern browsers
+  (Chromium, Firefox, Safari) and Node, served from CDNs like esm.sh
+  with zero polyfill burden
+- `test/browser-smoke.test.js` runs the public API with `globalThis.Buffer`
+  removed, asserts plain `Uint8Array` outputs and a clean hybrid-signing
+  round trip — proves browser compatibility in CI
+
+### Changed
+- HKDF-SHA-512 now sourced from `@noble/hashes/hkdf` (was `node:crypto`)
+- HMAC-SHA-256 now sourced from `@noble/hashes/hmac` (was `node:crypto`)
+- SHA-256 for kid fingerprints now sourced from `@noble/hashes/sha256`
+  (was `node:crypto`)
+- Constant-time comparisons are portable byte loops (replaces
+  `node:crypto.timingSafeEqual`) — identical security property,
+  runs in browsers
+- Functions return `Buffer` on Node (when `globalThis.Buffer` is defined)
+  and plain `Uint8Array` in browsers. **Backwards compatible** for Node
+  callers; `Buffer extends Uint8Array` so any code accepting `Uint8Array`
+  already works.
+- `engines.node` bumped to `>=20.19` to match the underlying
+  `@noble/hashes@2` requirement (Node 18 is past EOL)
+
+### Dependencies
+- Added `@noble/hashes ^2.2.0` (peer of `@noble/post-quantum`)
+- `@noble/post-quantum ^0.2.1` unchanged
+
+### Verification
+- 9 node tests pass
+- 6 browser-smoke tests pass
+- 29 pinned vectors still match — no cryptographic surface changes,
+  bit-for-bit identical to 1.0.3 in Node
+
 ## [1.0.3] — 2026-05-21
 
 First release ships with SLSA Level 2 provenance attestation tied to a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.0.3",
+  "version": "1.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",
@@ -33,27 +33,27 @@
   "types": "./src/index.d.ts",
   "exports": {
     ".": {
-      "types":  "./src/index.d.ts",
+      "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
     "./ml-dsa": {
-      "types":  "./src/ml-dsa.d.ts",
+      "types": "./src/ml-dsa.d.ts",
       "import": "./src/ml-dsa.js"
     },
     "./ml-kem": {
-      "types":  "./src/ml-kem.d.ts",
+      "types": "./src/ml-kem.d.ts",
       "import": "./src/ml-kem.js"
     },
     "./derive": {
-      "types":  "./src/derive.d.ts",
+      "types": "./src/derive.d.ts",
       "import": "./src/derive.js"
     },
     "./webhook": {
-      "types":  "./src/webhook.d.ts",
+      "types": "./src/webhook.d.ts",
       "import": "./src/webhook.js"
     },
     "./kid": {
-      "types":  "./src/kid.d.ts",
+      "types": "./src/kid.d.ts",
       "import": "./src/kid.js"
     }
   },
@@ -65,15 +65,17 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19"
   },
   "dependencies": {
+    "@noble/hashes": "^2.2.0",
     "@noble/post-quantum": "^0.2.1"
   },
   "scripts": {
-    "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"
+    "test": "node --test test/basic.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
+    "test:vectors": "node test/run-vectors.js",
+    "generate:vectors": "node test/generate-vectors.js > test/vectors.json",
+    "bench": "node bench/bench.js"
   },
   "publishConfig": {
     "provenance": true,

package/src/derive.js

@@ -8,26 +8,40 @@
 // 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.
+//
+// Isomorphic: uses @noble/hashes/hkdf which runs identically in Node 18+ and
+// modern browsers. Returns Buffer when running on Node (for backwards
+// compatibility with existing callers), Uint8Array in browsers.
+
+import { hkdf } from '@noble/hashes/hkdf.js'
+import { sha512 } from '@noble/hashes/sha2.js'
 
-import { hkdfSync } from 'node:crypto'
+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')
+}
 
 /**
  * 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}
+ * @param {Buffer|Uint8Array|string} master   — high-entropy keying material (>= 16 bytes)
+ * @param {string}                    info    — domain separation tag
+ * @param {number}                    length  — output seed length in bytes
+ * @returns {Buffer|Uint8Array}
  */
 export function deriveSeed(master, info, length) {
-  if (!master || master.length < 16) {
+  const ikm = toBytes(master)
+  if (!ikm || ikm.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)
-  )
+  const salt = new Uint8Array(32) // 32 zero bytes — fine with high-entropy IKM
+  const out = hkdf(sha512, ikm, salt, enc.encode(info), length)
+  return HAS_BUFFER ? Buffer.from(out) : out
 }

package/src/kid.js

@@ -4,25 +4,40 @@
 // 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.
+//
+// Isomorphic: uses @noble/hashes/sha256 — runs identically in Node and
+// browsers.
+
+import { sha256 } from '@noble/hashes/sha2.js'
 
-import { createHash } from 'node:crypto'
+function hexToBytes(hex) {
+  if (hex.length % 2) throw new Error('odd hex length')
+  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
+}
 
 /**
- * Compute a stable, 16-hex-character fingerprint of a public key.
+ * Compute a stable 16-hex-character fingerprint of a public key.
  *
- * @param {Buffer|Uint8Array|string} publicKey  — raw bytes or hex string
+ * @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)
+  const bytes = typeof publicKey === 'string'
+    ? hexToBytes(publicKey)
+    : (publicKey instanceof Uint8Array ? publicKey : new Uint8Array(publicKey))
+  return bytesToHex(sha256(bytes)).slice(0, 16)
 }
 
 /**
- * Constant-time comparison of two kid strings. Use this instead of `===`
- * when comparing kids from user input.
+ * Constant-time comparison of two kid strings.
  *
  * @param {string} a
  * @param {string} b

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.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.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) &&