kxco-post-quantum 1.1.11 → 1.2.0

package/src/derive.d.ts

@@ -1,20 +1,20 @@
-/// <reference types="node" />
-
-/**
- * Derive a deterministic seed from a master secret + an info string,
- * using HKDF-SHA-512 with an empty salt.
- *
- * Same `master + info + length` always produces the same seed.
- *
- * @param master — high-entropy input keying material (≥16 bytes)
- * @param info   — domain separation tag (eg. 'kxco-platform-ml-dsa-65-v1')
- * @param length — output seed length in bytes (32 for ML-DSA, 64 for ML-KEM)
- *
- * @throws {Error} if `master` is shorter than 16 bytes
- * @throws {Error} if `info` is empty or not a string
- */
-export function deriveSeed(
-  master: Buffer | Uint8Array,
-  info:   string,
-  length: number,
-): Buffer
+/// <reference types="node" />
+
+/**
+ * Derive a deterministic seed from a master secret + an info string,
+ * using HKDF-SHA-512 with an empty salt.
+ *
+ * Same `master + info + length` always produces the same seed.
+ *
+ * @param master — high-entropy input keying material (≥16 bytes)
+ * @param info   — domain separation tag (eg. 'kxco-platform-ml-dsa-65-v1')
+ * @param length — output seed length in bytes (32 for ML-DSA, 64 for ML-KEM)
+ *
+ * @throws {Error} if `master` is shorter than 16 bytes
+ * @throws {Error} if `info` is empty or not a string
+ */
+export function deriveSeed(
+  master: Buffer | Uint8Array,
+  info:   string,
+  length: number,
+): Buffer

package/src/derive.js

@@ -1,47 +1,47 @@
-// Deterministic key derivation via HKDF-SHA-512.
-//
-// Same seed + same info = same keypair, every time. This is how the KXCO
-// platform reproduces its signing identity across replicas without storing
-// the private key in a database: the master key is the env var, the rest is
-// pure derivation.
-//
-// 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'
-
-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|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) {
-  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')
-  }
-  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
-}
+// Deterministic key derivation via HKDF-SHA-512.
+//
+// Same seed + same info = same keypair, every time. This is how the KXCO
+// platform reproduces its signing identity across replicas without storing
+// the private key in a database: the master key is the env var, the rest is
+// pure derivation.
+//
+// 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'
+
+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|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) {
+  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')
+  }
+  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/index.d.ts

@@ -1,7 +1,8 @@
-/// <reference types="node" />
-
-export * as mlDsa  from './ml-dsa.js'
-export * as mlKem  from './ml-kem.js'
-export * from './derive.js'
-export * from './kid.js'
-export * as webhook from './webhook.js'
+/// <reference types="node" />
+
+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'

package/src/index.js

@@ -11,6 +11,7 @@
 
 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'

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.d.ts

@@ -1,45 +1,45 @@
-/// <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').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
+
+/**
+ * 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

package/src/ml-dsa.js

@@ -1,78 +1,78 @@
-// ML-DSA-65 helpers (NIST FIPS 204, Dilithium3).
-//
-// Module-lattice signatures. Security Category 3 (≈ AES-192). Public key 1952
-// bytes, signature 3309 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_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.
- *
- * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
- */
-export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
-  const seed = deriveSeed(master, info, 32)
-  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
-  const k = ml_dsa65.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 (6618 chars)
- */
-export function sign(secretKey, message) {
-  const sig = ml_dsa65.sign(secretKey, toBytes(message))
-  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 ml_dsa65.verify(publicKey, toBytes(message), hexToBytes(sigHex))
-  } catch {
-    return false
-  }
-}
-
-export { ml_dsa65 }
+// ML-DSA-65 helpers (NIST FIPS 204, Dilithium3).
+//
+// Module-lattice signatures. Security Category 3 (≈ AES-192). Public key 1952
+// bytes, signature 3309 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_dsa65 } from '@noble/post-quantum/ml-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
+}
+
+/**
+ * Generate an ML-DSA-65 keypair from a master + domain-separation info.
+ *
+ * @returns {{ publicKey: Buffer|Uint8Array, secretKey: Buffer|Uint8Array }}
+ */
+export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
+  const seed = deriveSeed(master, info, 32)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_dsa65.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 (6618 chars)
+ */
+export function sign(secretKey, message) {
+  const sig = ml_dsa65.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 ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+  } catch {
+    return false
+  }
+}
+
+export { ml_dsa65 }

package/src/ml-kem.d.ts

@@ -1,49 +1,49 @@
-/// <reference types="node" />
-
-export interface MlKemKeypair {
-  /** 1184-byte public key */
-  publicKey: Buffer
-  /** 2400-byte secret key */
-  secretKey: Buffer
-}
-
-export interface MlKemEncapsulation {
-  /** 1088-byte KEM ciphertext to transmit to the recipient */
-  ciphertext: Buffer
-  /** Alias for `ciphertext` (mirrors @noble/post-quantum's camelCase) */
-  cipherText: Buffer
-  /** 32-byte shared secret to use as a symmetric AEAD key */
-  sharedSecret: Buffer
-}
-
-/**
- * Generate an ML-KEM-768 (NIST FIPS 203) keypair deterministically
- * from a master + domain-separation info string.
- */
-export function keypairFromMaster(
-  master: Buffer | Uint8Array,
-  info?:  string,
-): MlKemKeypair
-
-/**
- * Encapsulate a shared secret to the recipient's ML-KEM-768 public key.
- *
- * The recipient calls `decapsulate(ciphertext, secretKey)` to recover
- * the same shared secret. Use the shared secret as a symmetric AEAD
- * key (eg. AES-256-GCM).
- */
-export function encapsulate(publicKey: Buffer | Uint8Array): MlKemEncapsulation
-
-/**
- * Decapsulate: recover the shared secret from a KEM ciphertext
- * using the recipient's secret key.
- */
-export function decapsulate(
-  ciphertext: Buffer | Uint8Array,
-  secretKey:  Buffer | Uint8Array,
-): Buffer
-
-/**
- * Raw `@noble/post-quantum` ML-KEM-768 primitive, re-exported.
- */
-export const ml_kem768: typeof import('@noble/post-quantum/ml-kem').ml_kem768
+/// <reference types="node" />
+
+export interface MlKemKeypair {
+  /** 1184-byte public key */
+  publicKey: Buffer
+  /** 2400-byte secret key */
+  secretKey: Buffer
+}
+
+export interface MlKemEncapsulation {
+  /** 1088-byte KEM ciphertext to transmit to the recipient */
+  ciphertext: Buffer
+  /** Alias for `ciphertext` (mirrors @noble/post-quantum's camelCase) */
+  cipherText: Buffer
+  /** 32-byte shared secret to use as a symmetric AEAD key */
+  sharedSecret: Buffer
+}
+
+/**
+ * Generate an ML-KEM-768 (NIST FIPS 203) keypair deterministically
+ * from a master + domain-separation info string.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlKemKeypair
+
+/**
+ * Encapsulate a shared secret to the recipient's ML-KEM-768 public key.
+ *
+ * The recipient calls `decapsulate(ciphertext, secretKey)` to recover
+ * the same shared secret. Use the shared secret as a symmetric AEAD
+ * key (eg. AES-256-GCM).
+ */
+export function encapsulate(publicKey: Buffer | Uint8Array): MlKemEncapsulation
+
+/**
+ * Decapsulate: recover the shared secret from a KEM ciphertext
+ * using the recipient's secret key.
+ */
+export function decapsulate(
+  ciphertext: Buffer | Uint8Array,
+  secretKey:  Buffer | Uint8Array,
+): Buffer
+
+/**
+ * Raw `@noble/post-quantum` ML-KEM-768 primitive, re-exported.
+ */
+export const ml_kem768: typeof import('@noble/post-quantum/ml-kem.js').ml_kem768