kxco-post-quantum 1.1.11 → 1.2.0

package/src/ml-kem.js

@@ -1,61 +1,61 @@
-// 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.
-//
-// 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.
- *
- * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
- */
-export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
-  const seed = deriveSeed(master, info, 64)
-  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
-  const k = ml_kem768.keygen(seedU8)
-  return {
-    publicKey: wrap(k.publicKey),
-    secretKey: wrap(k.secretKey),
-  }
-}
-
-/**
- * Encapsulate a shared secret to the recipient's public key.
- *
- * @param {Buffer|Uint8Array} publicKey
- * @returns {{ ciphertext: Buffer|Uint8Array, cipherText: Buffer|Uint8Array, sharedSecret: Buffer|Uint8Array }}
- */
-export function encapsulate(publicKey) {
-  const r = ml_kem768.encapsulate(publicKey)
-  const ct = wrap(r.cipherText ?? r.ciphertext)
-  return {
-    ciphertext:   ct,
-    cipherText:   ct,
-    sharedSecret: wrap(r.sharedSecret),
-  }
-}
-
-/**
- * Decapsulate: recover the shared secret from a ciphertext using the secret key.
- *
- * @param {Buffer|Uint8Array} ciphertext
- * @param {Buffer|Uint8Array} secretKey
- * @returns {Buffer|Uint8Array} shared secret (32 bytes)
- */
-export function decapsulate(ciphertext, secretKey) {
-  return wrap(ml_kem768.decapsulate(ciphertext, secretKey))
-}
-
-export { ml_kem768 }
+// 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.
+//
+// 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.js'
+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.
+ *
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
+ */
+export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
+  const seed = deriveSeed(master, info, 64)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_kem768.keygen(seedU8)
+  return {
+    publicKey: wrap(k.publicKey),
+    secretKey: wrap(k.secretKey),
+  }
+}
+
+/**
+ * Encapsulate a shared secret to the recipient's public key.
+ *
+ * @param {Buffer|Uint8Array} publicKey
+ * @returns {{ ciphertext: Buffer|Uint8Array, cipherText: Buffer|Uint8Array, sharedSecret: Buffer|Uint8Array }}
+ */
+export function encapsulate(publicKey) {
+  const r = ml_kem768.encapsulate(publicKey)
+  const ct = wrap(r.cipherText ?? r.ciphertext)
+  return {
+    ciphertext:   ct,
+    cipherText:   ct,
+    sharedSecret: wrap(r.sharedSecret),
+  }
+}
+
+/**
+ * Decapsulate: recover the shared secret from a ciphertext using the secret key.
+ *
+ * @param {Buffer|Uint8Array} ciphertext
+ * @param {Buffer|Uint8Array} secretKey
+ * @returns {Buffer|Uint8Array} shared secret (32 bytes)
+ */
+export function decapsulate(ciphertext, secretKey) {
+  return wrap(ml_kem768.decapsulate(ciphertext, secretKey))
+}
+
+export { ml_kem768 }

package/src/slh-dsa.d.ts

@@ -0,0 +1,46 @@
+/// <reference types="node" />
+
+export interface SlhDsaKeypair {
+  /** 48-byte public key */
+  publicKey: Buffer
+  /** 96-byte secret key */
+  secretKey: Buffer
+}
+
+/**
+ * Generate an SLH-DSA-SHA2-192s (NIST FIPS 205) keypair deterministically
+ * from a master + domain-separation info string.
+ *
+ * Same inputs always produce the same keypair — no state, no DB row.
+ * Security Category 3, matching ML-DSA-65.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): SlhDsaKeypair
+
+/**
+ * Sign a message under an SLH-DSA-SHA2-192s secret key. Returns the signature
+ * as a hex string (16224 bytes = 32448 hex characters).
+ */
+export function sign(
+  secretKey: Buffer | Uint8Array,
+  message:   Buffer | string,
+): string
+
+/**
+ * Verify a hex-encoded SLH-DSA-SHA2-192s 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` SLH-DSA-SHA2-192s primitive, re-exported for
+ * callers who want the lower-level API. The wrapper functions above are
+ * recommended for production use.
+ */
+export const slh_dsa_sha2_192s: typeof import('@noble/post-quantum/slh-dsa.js').slh_dsa_sha2_192s

package/src/slh-dsa.js

@@ -0,0 +1,88 @@
+// SLH-DSA-SHA2-192s helpers (NIST FIPS 205, SPHINCS+).
+//
+// Stateless hash-based signatures. Security Category 3 (≈ AES-192), matching
+// ML-DSA-65's security level. Public key 48 bytes, secret key 96 bytes,
+// signature 16224 bytes. Security rests only on the SHA-2 hash function — no
+// lattice or number-theoretic assumptions — which makes it the conservative
+// hedge alongside ML-DSA-65.
+//
+// Tradeoff: signatures are ~5x larger than ML-DSA-65 (16224 vs 3309 bytes) and
+// signing is slower. Use ML-DSA-65 as the default; reach for SLH-DSA when you
+// want a signature whose security does not depend on lattice hardness.
+//
+// Isomorphic: works in Node and modern browsers. Returns Buffer on Node
+// (consistent with ml-dsa.js), Uint8Array in browsers.
+
+import { slh_dsa_sha2_192s } from '@noble/post-quantum/slh-dsa.js'
+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
+}
+
+// Seed length for SLH-DSA-SHA2-192s keygen (FIPS 205: SK.seed || SK.prf || PK.seed).
+const SEED_BYTES = slh_dsa_sha2_192s.lengths.seed
+
+/**
+ * Generate an SLH-DSA-SHA2-192s keypair from a master + domain-separation info.
+ *
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
+ */
+export function keypairFromMaster(master, info = 'slh-dsa-sha2-192s-v1') {
+  const seed = deriveSeed(master, info, SEED_BYTES)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = slh_dsa_sha2_192s.keygen(seedU8)
+  return {
+    publicKey: wrap(k.publicKey),
+    secretKey: wrap(k.secretKey),
+  }
+}
+
+/**
+ * Sign a message. Returns the signature as a hex string.
+ *
+ * @param {Buffer|Uint8Array} secretKey
+ * @param {Buffer|Uint8Array|string} message
+ * @returns {string} hex-encoded signature (32448 chars)
+ */
+export function sign(secretKey, message) {
+  const sig = slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
+  return bytesToHex(sig)
+}
+
+/**
+ * Verify a hex-encoded signature.
+ *
+ * @param {Buffer|Uint8Array} publicKey
+ * @param {Buffer|Uint8Array|string} message
+ * @param {string} sigHex
+ * @returns {boolean}
+ */
+export function verify(publicKey, message, sigHex) {
+  try {
+    return slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+  } catch {
+    return false
+  }
+}
+
+export { slh_dsa_sha2_192s }

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