kxco-post-quantum 1.2.1 → 1.4.0

package/src/index.js

@@ -1,17 +1,24 @@
-// @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 * as slhDsa from './slh-dsa.js'
-export * from './derive.js'
-export * from './kid.js'
-export * as webhook from './webhook.js'
+// @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 * as slhDsa from './slh-dsa.js'
+
+// Category 5 parameter sets, for callers who are given ML-DSA-87 or
+// ML-KEM-1024 as a requirement. The KXCO default stays Category 3
+// (mlDsa / mlKem). Supporting these sets is not a CNSA 2.0 compliance claim;
+// see the notes at the top of each module and CONFORMANCE.md.
+export * as mlDsa87   from './ml-dsa-87.js'
+export * as mlKem1024 from './ml-kem-1024.js'
+export * from './derive.js'
+export * from './kid.js'
+export * as webhook from './webhook.js'

package/src/kid.d.ts

@@ -1,21 +1,21 @@
-/// <reference types="node" />
-
-/**
- * Compute a 16-hex-character fingerprint of a public key:
- * the first 8 bytes of `SHA-256(public_key)`, hex-encoded.
- *
- * Stable for the lifetime of the keypair. Used to identify which
- * platform key signed an outbound delivery without including the
- * full 1952-byte public key in every request.
- *
- * @param publicKey — raw bytes or hex string
- */
-export function fingerprint(publicKey: Buffer | Uint8Array | string): string
-
-/**
- * Constant-time comparison of two kid strings.
- *
- * Use this instead of `===` when comparing kids that may be
- * influenced by untrusted input — eg. an `X-KXCO-PQ-Kid` header.
- */
-export function kidEquals(a: string, b: string): boolean
+/// <reference types="node" />
+
+/**
+ * Compute a 16-hex-character fingerprint of a public key:
+ * the first 8 bytes of `SHA-256(public_key)`, hex-encoded.
+ *
+ * Stable for the lifetime of the keypair. Used to identify which
+ * platform key signed an outbound delivery without including the
+ * full 1952-byte public key in every request.
+ *
+ * @param publicKey — raw bytes or hex string
+ */
+export function fingerprint(publicKey: Buffer | Uint8Array | string): string
+
+/**
+ * Constant-time comparison of two kid strings.
+ *
+ * Use this instead of `===` when comparing kids that may be
+ * influenced by untrusted input — eg. an `X-KXCO-PQ-Kid` header.
+ */
+export function kidEquals(a: string, b: string): boolean

package/src/kid.js

@@ -1,53 +1,53 @@
-// 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.
-//
-// Isomorphic: uses @noble/hashes/sha256 — runs identically in Node and
-// browsers.
-
-import { sha256 } from '@noble/hashes/sha2.js'
-
-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.
- *
- * @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 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.
- *
- * @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
-}
+// 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.
+//
+// Isomorphic: uses @noble/hashes/sha256 — runs identically in Node and
+// browsers.
+
+import { sha256 } from '@noble/hashes/sha2.js'
+
+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.
+ *
+ * @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 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.
+ *
+ * @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-87.d.ts

@@ -0,0 +1,81 @@
+/// <reference types="node" />
+
+export interface MlDsa87Keypair {
+  /** 2592-byte public key */
+  publicKey: Buffer
+  /** 4896-byte secret key */
+  secretKey: Buffer
+}
+
+/**
+ * Generate an ML-DSA-87 (NIST FIPS 204) keypair deterministically
+ * from a master + domain-separation info string.
+ *
+ * Same inputs always produce the same keypair — no state, no DB row.
+ *
+ * Security Category 5. The default `info` differs from the ML-DSA-65 module's,
+ * so one master yields unrelated keys for the two parameter sets.
+ *
+ * CNSA 2.0 names ML-DSA-87. Support for the parameter set is not a CNSA 2.0
+ * compliance claim; see the note at the top of `ml-dsa-87.js`.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlDsa87Keypair
+
+/** Maximum context length in bytes (FIPS 204 section 5.2). */
+export const MAX_CONTEXT_BYTES: 255
+
+export interface SignatureOptions {
+  /**
+   * Optional FIPS 204 section 5.2 context string, at most 255 bytes.
+   * Strings are encoded as UTF-8.
+   *
+   * Gives domain separation at the signature level: a signature made under a
+   * context does not verify without it, or under a different one. An empty
+   * context is identical to omitting it.
+   */
+  context?: Buffer | Uint8Array | string
+}
+
+/**
+ * Sign a message under an ML-DSA-87 secret key. Returns the signature
+ * as a hex string (4627 bytes = 9254 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 ML-DSA-87 signature against a public key + message.
+ *
+ * Returns `false` on any cryptographic failure, including a signature or key
+ * from a different parameter set.
+ *
+ * Throws only on caller misuse of `opts`, which is a programming error rather
+ * than a failed verification and is not swallowed.
+ *
+ * @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` ML-DSA-87 primitive, re-exported for callers
+ * who want the lower-level API. The wrapper functions above are
+ * recommended for production use.
+ */
+export const ml_dsa87: typeof import('@noble/post-quantum/ml-dsa.js').ml_dsa87

package/src/ml-dsa-87.js

@@ -0,0 +1,127 @@
+// ML-DSA-87 helpers (NIST FIPS 204, Dilithium5).
+//
+// Module-lattice signatures. Security Category 5 (≈ AES-256). Public key 2592
+// bytes, secret key 4896 bytes, signature 4627 bytes. Resistant to attacks by
+// quantum computers.
+//
+// Same API as ./ml-dsa.js, one security category higher. Use this where a
+// counterparty specifies Category 5 or names ML-DSA-87. ML-DSA-65 remains the
+// default for the KXCO stack; see the note on parameter choice below.
+//
+// Isomorphic: works in Node and modern browsers. Returns Buffer on Node
+// (backwards compatible), Uint8Array in browsers.
+//
+// ---------------------------------------------------------------------------
+// Parameter choice, and what this module does NOT establish
+//
+// CNSA 2.0 names ML-DSA-87 for National Security Systems. Exporting this module
+// makes that parameter set available to callers. It does not make any deployed
+// system CNSA 2.0 compliant, and it must not be cited as a compliance badge.
+// Compliance is a property of a deployment, not of an available function: the
+// KXCO estate signs with ML-DSA-65 at Category 3, including Armature L1 from
+// block 0 and every issued KXCO ID, none of which this module changes.
+//
+// The accurate sentence is "supports ML-DSA-87". See CONFORMANCE.md.
+//
+// Cost of moving up: a signature is 4627 bytes against 3309 for ML-DSA-65, and
+// a public key is 2592 against 1952. Once both sets are in use, anything
+// downstream with a fixed-width signature field will meet both sizes.
+// ---------------------------------------------------------------------------
+
+import { ml_dsa87 } from '@noble/post-quantum/ml-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
+}
+
+/**
+ * Generate an ML-DSA-87 keypair from a master + domain-separation info.
+ *
+ * The default info differs from the ML-DSA-65 default, so the same master
+ * yields unrelated keys for the two parameter sets rather than colliding.
+ *
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
+ */
+export function keypairFromMaster(master, info = 'ml-dsa-87-v1') {
+  const seed = deriveSeed(master, info, 32)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_dsa87.keygen(seedU8)
+  return {
+    publicKey: wrap(k.publicKey),
+    secretKey: wrap(k.secretKey),
+  }
+}
+
+/**
+ * Sign a message. Returns the signature as a hex string.
+ *
+ * An optional FIPS 204 section 5.2 context string gives domain separation: a
+ * signature made under a context does not verify without it.
+ *
+ * @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 (9254 chars)
+ */
+export function sign(secretKey, message, opts) {
+  const context = normalizeContext(opts)
+  const sig = context === undefined
+    ? ml_dsa87.sign(toBytes(message), secretKey)
+    : ml_dsa87.sign(toBytes(message), secretKey, { context })
+  return bytesToHex(sig)
+}
+
+/**
+ * Verify a hex-encoded signature.
+ *
+ * Pass the same context the signer used. A signature made under a context
+ * returns false here if the context is omitted or differs, which is the point
+ * of it.
+ *
+ * Returns false for any cryptographic failure, including a signature produced
+ * under a different parameter set. Throws only on caller misuse of `opts`
+ * (wrong type, or a context over 255 bytes), because that is a bug rather than
+ * a failed verification and should not be silently swallowed.
+ *
+ * @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) {
+  // Outside the try: misuse must surface, not be swallowed as "invalid".
+  const context = normalizeContext(opts)
+  try {
+    return context === undefined
+      ? ml_dsa87.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+      : ml_dsa87.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
+  } catch {
+    return false
+  }
+}
+
+export { ml_dsa87 }

package/src/ml-dsa.d.ts

@@ -1,45 +1,78 @@
-/// <reference types="node" />
-
-export interface MlDsaKeypair {
-  /** 1952-byte public key */
-  publicKey: Buffer
-  /** 4032-byte secret key */
-  secretKey: Buffer
-}
-
-/**
- * Generate an ML-DSA-65 (NIST FIPS 204) keypair deterministically
- * from a master + domain-separation info string.
- *
- * Same inputs always produce the same keypair — no state, no DB row.
- */
-export function keypairFromMaster(
-  master: Buffer | Uint8Array,
-  info?:  string,
-): MlDsaKeypair
-
-/**
- * Sign a message under an ML-DSA-65 secret key. Returns the signature
- * as a hex string (3309 bytes = 6618 hex characters).
- */
-export function sign(
-  secretKey: Buffer | Uint8Array,
-  message:   Buffer | string,
-): string
-
-/**
- * Verify a hex-encoded ML-DSA-65 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` ML-DSA-65 primitive, re-exported for callers
- * who want the lower-level API. The wrapper functions above are
- * recommended for production use.
- */
-export const ml_dsa65: typeof import('@noble/post-quantum/ml-dsa.js').ml_dsa65
+/// <reference types="node" />
+
+export interface MlDsaKeypair {
+  /** 1952-byte public key */
+  publicKey: Buffer
+  /** 4032-byte secret key */
+  secretKey: Buffer
+}
+
+/**
+ * Generate an ML-DSA-65 (NIST FIPS 204) keypair deterministically
+ * from a master + domain-separation info string.
+ *
+ * Same inputs always produce the same keypair — no state, no DB row.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlDsaKeypair
+
+/** Maximum context length in bytes (FIPS 204 section 5.2). */
+export const MAX_CONTEXT_BYTES: 255
+
+export interface SignatureOptions {
+  /**
+   * Optional FIPS 204 section 5.2 context string, at most 255 bytes.
+   * Strings are encoded as UTF-8.
+   *
+   * Gives domain separation at the signature level: a signature made under a
+   * context does not verify without it, or under a different one. An empty
+   * context is identical to omitting it.
+   *
+   * Complements `keypairFromMaster(master, info)`, which separates domains at
+   * the key level.
+   */
+  context?: Buffer | Uint8Array | string
+}
+
+/**
+ * Sign a message under an ML-DSA-65 secret key. Returns the signature
+ * as a hex string (3309 bytes = 6618 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 ML-DSA-65 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`, which is a programming error rather
+ * than a failed verification and is not swallowed.
+ *
+ * @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` ML-DSA-65 primitive, re-exported for callers
+ * who want the lower-level API. The wrapper functions above are
+ * recommended for production use.
+ */
+export const ml_dsa65: typeof import('@noble/post-quantum/ml-dsa.js').ml_dsa65