kxco-post-quantum 1.3.0 → 1.4.0

package/src/slh-dsa.d.ts

@@ -1,72 +1,72 @@
-/// <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
-
-/** Maximum context length in bytes (FIPS 205, matching FIPS 204). */
-export const MAX_CONTEXT_BYTES: 255
-
-export interface SignatureOptions {
-  /**
-   * Optional context string, at most 255 bytes. Strings are encoded as UTF-8.
-   * A signature made under a context does not verify without it. An empty
-   * context is identical to omitting it.
-   */
-  context?: Buffer | Uint8Array | string
-}
-
-/**
- * Sign a message under an SLH-DSA-SHA2-192s secret key. Returns the signature
- * as a hex string (16224 bytes = 32448 hex characters).
- *
- * @throws {TypeError}  if `opts` is not an options object, or `context` is
- *                      neither a string nor a Uint8Array
- * @throws {RangeError} if `context` exceeds 255 bytes
- */
-export function sign(
-  secretKey: Buffer | Uint8Array,
-  message:   Buffer | Uint8Array | string,
-  opts?:     SignatureOptions,
-): string
-
-/**
- * Verify a hex-encoded SLH-DSA-SHA2-192s signature against a public key +
- * message.
- *
- * Returns `false` on any cryptographic failure (invalid hex, wrong length,
- * mismatch, or a missing/incorrect context). Throws only on caller misuse of
- * `opts`.
- *
- * @throws {TypeError}  if `opts` is not an options object, or `context` is
- *                      neither a string nor a Uint8Array
- * @throws {RangeError} if `context` exceeds 255 bytes
- */
-export function verify(
-  publicKey: Buffer | Uint8Array,
-  message:   Buffer | Uint8Array | string,
-  sigHex:    string,
-  opts?:     SignatureOptions,
-): 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
+/// <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
+
+/** Maximum context length in bytes (FIPS 205, matching FIPS 204). */
+export const MAX_CONTEXT_BYTES: 255
+
+export interface SignatureOptions {
+  /**
+   * Optional context string, at most 255 bytes. Strings are encoded as UTF-8.
+   * A signature made under a context does not verify without it. An empty
+   * context is identical to omitting it.
+   */
+  context?: Buffer | Uint8Array | string
+}
+
+/**
+ * Sign a message under an SLH-DSA-SHA2-192s secret key. Returns the signature
+ * as a hex string (16224 bytes = 32448 hex characters).
+ *
+ * @throws {TypeError}  if `opts` is not an options object, or `context` is
+ *                      neither a string nor a Uint8Array
+ * @throws {RangeError} if `context` exceeds 255 bytes
+ */
+export function sign(
+  secretKey: Buffer | Uint8Array,
+  message:   Buffer | Uint8Array | string,
+  opts?:     SignatureOptions,
+): string
+
+/**
+ * Verify a hex-encoded SLH-DSA-SHA2-192s signature against a public key +
+ * message.
+ *
+ * Returns `false` on any cryptographic failure (invalid hex, wrong length,
+ * mismatch, or a missing/incorrect context). Throws only on caller misuse of
+ * `opts`.
+ *
+ * @throws {TypeError}  if `opts` is not an options object, or `context` is
+ *                      neither a string nor a Uint8Array
+ * @throws {RangeError} if `context` exceeds 255 bytes
+ */
+export function verify(
+  publicKey: Buffer | Uint8Array,
+  message:   Buffer | Uint8Array | string,
+  sigHex:    string,
+  opts?:     SignatureOptions,
+): 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

@@ -1,106 +1,106 @@
-// 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'
-import { normalizeContext, MAX_CONTEXT_BYTES } from './_context.js'
-
-export { MAX_CONTEXT_BYTES }
-
-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.
- *
- * Accepts the same optional context string as ml-dsa.js (FIPS 205 allows it on
- * the same terms as FIPS 204, at most 255 bytes). Omit it and the behaviour is
- * exactly as before this parameter existed.
- *
- * @param {Buffer|Uint8Array} secretKey
- * @param {Buffer|Uint8Array|string} message
- * @param {{ context?: Uint8Array|Buffer|string }} [opts] at most 255 context bytes
- * @returns {string} hex-encoded signature (32448 chars)
- */
-export function sign(secretKey, message, opts) {
-  const context = normalizeContext(opts)
-  const sig = context === undefined
-    ? slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
-    : slh_dsa_sha2_192s.sign(toBytes(message), secretKey, { context })
-  return bytesToHex(sig)
-}
-
-/**
- * Verify a hex-encoded signature.
- *
- * Pass the same context the signer used. Returns false for any cryptographic
- * failure; throws only on caller misuse of `opts`.
- *
- * @param {Buffer|Uint8Array} publicKey
- * @param {Buffer|Uint8Array|string} message
- * @param {string} sigHex
- * @param {{ context?: Uint8Array|Buffer|string }} [opts]
- * @returns {boolean}
- */
-export function verify(publicKey, message, sigHex, opts) {
-  const context = normalizeContext(opts)
-  try {
-    return context === undefined
-      ? slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)
-      : slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
-  } catch {
-    return false
-  }
-}
-
-export { slh_dsa_sha2_192s }
+// 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'
+import { normalizeContext, MAX_CONTEXT_BYTES } from './_context.js'
+
+export { MAX_CONTEXT_BYTES }
+
+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.
+ *
+ * Accepts the same optional context string as ml-dsa.js (FIPS 205 allows it on
+ * the same terms as FIPS 204, at most 255 bytes). Omit it and the behaviour is
+ * exactly as before this parameter existed.
+ *
+ * @param {Buffer|Uint8Array} secretKey
+ * @param {Buffer|Uint8Array|string} message
+ * @param {{ context?: Uint8Array|Buffer|string }} [opts] at most 255 context bytes
+ * @returns {string} hex-encoded signature (32448 chars)
+ */
+export function sign(secretKey, message, opts) {
+  const context = normalizeContext(opts)
+  const sig = context === undefined
+    ? slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
+    : slh_dsa_sha2_192s.sign(toBytes(message), secretKey, { context })
+  return bytesToHex(sig)
+}
+
+/**
+ * Verify a hex-encoded signature.
+ *
+ * Pass the same context the signer used. Returns false for any cryptographic
+ * failure; throws only on caller misuse of `opts`.
+ *
+ * @param {Buffer|Uint8Array} publicKey
+ * @param {Buffer|Uint8Array|string} message
+ * @param {string} sigHex
+ * @param {{ context?: Uint8Array|Buffer|string }} [opts]
+ * @returns {boolean}
+ */
+export function verify(publicKey, message, sigHex, opts) {
+  const context = normalizeContext(opts)
+  try {
+    return context === undefined
+      ? slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+      : slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
+  } 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