kxco-post-quantum 1.1.12 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.2.0 — 2026-07-22
+
+Adds SLH-DSA (FIPS 205) and modernises the underlying primitive engine to
+`@noble/post-quantum@0.6.1`. **No breaking changes for consumers** — the
+public API and all previously pinned outputs are byte-for-byte identical.
+
+### Added
+- **`slhDsa` — SLH-DSA-SHA2-192s (NIST FIPS 205)**, exported both from the
+  package root and the `kxco-post-quantum/slh-dsa` subpath. Hash-based,
+  stateless signatures at Security Category 3 (matching ML-DSA-65), whose
+  security rests only on SHA-2 — the conservative hedge alongside the
+  lattice-based ML-DSA-65. Deterministic `keypairFromMaster(master, info?)`
+  via the same HKDF-SHA-512 derivation, plus `sign` / `verify`. Public key
+  48 bytes, secret key 96 bytes, signature 16224 bytes.
+- Test vectors extended to pin SLH-DSA keypairs and round-trip (39 checks,
+  up from 29).
+
+### Changed
+- **`@noble/post-quantum` bumped `^0.2.1` → `^0.6.1`** — the FIPS 203/204/205
+  final reference implementation. The engine's public API changed argument
+  order for signature `sign`/`verify` and requires `.js` in subpath imports;
+  both are absorbed inside this package's wrappers, so no downstream package
+  or caller is affected.
+- Description and keywords updated to reflect SLH-DSA / FIPS 205 coverage.
+
+### Verification
+- 11 node tests pass, 7 browser-smoke tests pass, 39 pinned vectors pass.
+- **Compatibility gate:** every ML-DSA-65, ML-KEM-768, HKDF, fingerprint and
+  webhook vector pinned under `@noble/post-quantum@0.2.1` still matches
+  bit-for-bit under `0.6.1`. Deterministic keys derived from existing KXCO
+  master secrets — including Armature L1 identities — are unchanged.
+
 ## 1.1.6 — 2026-05-24
 
 Maintenance release. No breaking changes.

package/README.md

@@ -6,7 +6,7 @@ Post-quantum cryptography primitives for the KXCO stack.
 [![CI](https://github.com/JackKXCO/kxco-post-quantum/actions/workflows/ci.yml/badge.svg)](https://github.com/JackKXCO/kxco-post-quantum/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-ML-DSA-65 (FIPS 204) signatures and ML-KEM-768 (FIPS 203) key encapsulation, with key fingerprinting utilities. Wraps [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) — the Cure53-audited NIST reference implementation. All other `kxco-pq-*` packages depend on this one.
+ML-DSA-65 (FIPS 204) and SLH-DSA-SHA2-192s (FIPS 205) signatures, ML-KEM-768 (FIPS 203) key encapsulation, and key fingerprinting utilities. Wraps [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) — the NIST reference implementation. All other `kxco-pq-*` packages depend on this one.
 
 ---
 
@@ -23,13 +23,18 @@ Requires Node.js 20.19+. ESM-only.
 ## Quick start
 
 ```js
-import { mlDsa, mlKem, fingerprint, kidEquals } from 'kxco-post-quantum'
+import { mlDsa, mlKem, slhDsa, fingerprint, kidEquals } from 'kxco-post-quantum'
 
 // ML-DSA-65 — sign and verify
 const { publicKey, secretKey } = mlDsa.keypairFromMaster(masterSecret, 'signing-v1')
 const sig = mlDsa.sign(secretKey, 'hello')
 const ok  = mlDsa.verify(publicKey, 'hello', sig)  // true
 
+// SLH-DSA-SHA2-192s — hash-based signatures (same API shape as mlDsa)
+const slh = slhDsa.keypairFromMaster(masterSecret, 'signing-v1')
+const slhSig = slhDsa.sign(slh.secretKey, 'hello')
+const slhOk  = slhDsa.verify(slh.publicKey, 'hello', slhSig)  // true
+
 // Key fingerprint
 const kid = fingerprint(publicKey)  // e.g. '4a7c9e2f1b3d5680'
 kidEquals(kid, kid)                 // true (constant-time)
@@ -58,6 +63,19 @@ const recovered = mlKem.decapsulate(ciphertext, kemKeys.secretKey)
 
 `publicKey` is 1952 bytes. `secretKey` is 4032 bytes. `message` accepts `Buffer`, `Uint8Array`, or `string`.
 
+### `slhDsa` — SLH-DSA-SHA2-192s (NIST FIPS 205)
+
+Hash-based, stateless signatures. Security Category 3 (matching ML-DSA-65), but security rests only on the SHA-2 hash function — no lattice or number-theoretic assumptions. Use this as a conservative hedge alongside `mlDsa`. Tradeoff: signatures are ~5× larger (16224 vs 3309 bytes) and signing is slower.
+
+| Export | Signature | Description |
+|---|---|---|
+| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'slh-dsa-sha2-192s-v1'`. |
+| `sign` | `(secretKey, message) → string` | Signs a message. Returns a hex-encoded signature (32448 chars). |
+| `verify` | `(publicKey, message, sigHex) → boolean` | Verifies a hex-encoded signature. Returns `false` on any failure. |
+| `slh_dsa_sha2_192s` | raw primitive | The underlying `@noble/post-quantum` primitive, re-exported. |
+
+`publicKey` is 48 bytes. `secretKey` is 96 bytes. `message` accepts `Buffer`, `Uint8Array`, or `string`.
+
 ### `mlKem` — ML-KEM-768 (NIST FIPS 203)
 
 | Export | Signature | Description |
@@ -81,12 +99,15 @@ Constant-time comparison of two kid strings. Use this when comparing user-suppli
 
 HKDF-SHA-512 derivation. `master` must be at least 16 bytes. `info` is a required domain-separation string. Returns `length` bytes.
 
+### `webhook` — hybrid HMAC + ML-DSA-65 delivery signing
+
+Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `verifyHmac`, `pqSign`, `verifyPq`, `signDelivery`, `verifyDelivery`. HMAC-SHA-256 gives symmetric verification with no library dependency; ML-DSA-65 adds non-repudiation over the same `${timestamp}.${body}` envelope. The full identity/credential surface lives in `kxco-pq-sdk`.
+
 ---
 
 ## What this does NOT do
 
-- No identity credentials or verifiable claims
-- No webhook signing or HMAC utilities (those are in `kxco-pq-sdk`)
+- No identity credentials or verifiable claims (those are in `kxco-pq-sdk`)
 - No relay, transport, or network layer
 - No key storage or KMS integration
 - No FIPS 140-3 module validation (the algorithms are FIPS-standardised; the module is not validated)

package/SECURITY.md

@@ -14,11 +14,12 @@ In scope:
 - Kid fingerprint collision behaviour
 
 Out of scope (report upstream to https://github.com/paulmillr/noble-post-quantum):
-- Bugs in the underlying ML-DSA-65, ML-KEM-768, or HKDF primitives
+- Bugs in the underlying ML-DSA-65, ML-KEM-768, SLH-DSA-SHA2-192s, or HKDF primitives
 
 ## Algorithms used
 - ML-DSA-65 — NIST FIPS 204 (lattice signatures)
 - ML-KEM-768 — NIST FIPS 203 (key encapsulation)
+- SLH-DSA-SHA2-192s — NIST FIPS 205 (hash-based signatures)
 - HMAC-SHA-256
 - HKDF-SHA-512 (RFC 5869)
 

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.1.12",
-  "description": "ML-DSA-65 and ML-KEM-768 primitives with key fingerprinting. The base layer for all kxco-pq-* packages.",
+  "version": "1.2.0",
+  "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s primitives with key fingerprinting. The base layer for all kxco-pq-* packages.",
   "keywords": [
     "post-quantum",
     "pqc",
     "ml-dsa",
     "ml-kem",
+    "slh-dsa",
+    "sphincs",
     "dilithium",
     "kyber",
     "nist",
     "fips-203",
     "fips-204",
+    "fips-205",
     "webhook-signing",
     "quantum-resistant",
     "armature",
@@ -60,6 +63,10 @@
       "types": "./src/ml-kem.d.ts",
       "import": "./src/ml-kem.js"
     },
+    "./slh-dsa": {
+      "types": "./src/slh-dsa.d.ts",
+      "import": "./src/slh-dsa.js"
+    },
     "./derive": {
       "types": "./src/derive.d.ts",
       "import": "./src/derive.js"
@@ -85,7 +92,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "@noble/post-quantum": "^0.2.1"
+    "@noble/post-quantum": "^0.6.1"
   },
   "scripts": {
     "test": "node --test test/basic.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",

package/src/index.d.ts

@@ -2,6 +2,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/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/ml-dsa.d.ts

@@ -42,4 +42,4 @@ export function verify(
  * 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
+export const ml_dsa65: typeof import('@noble/post-quantum/ml-dsa.js').ml_dsa65

package/src/ml-dsa.js

@@ -6,7 +6,7 @@
 // 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 { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js'
 import { deriveSeed } from './derive.js'
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'
@@ -55,7 +55,7 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
  * @returns {string} hex-encoded signature (6618 chars)
  */
 export function sign(secretKey, message) {
-  const sig = ml_dsa65.sign(secretKey, toBytes(message))
+  const sig = ml_dsa65.sign(toBytes(message), secretKey)
   return bytesToHex(sig)
 }
 
@@ -69,7 +69,7 @@ export function sign(secretKey, message) {
  */
 export function verify(publicKey, message, sigHex) {
   try {
-    return ml_dsa65.verify(publicKey, toBytes(message), hexToBytes(sigHex))
+    return ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
   } catch {
     return false
   }

package/src/ml-kem.d.ts

@@ -46,4 +46,4 @@ export function decapsulate(
 /**
  * Raw `@noble/post-quantum` ML-KEM-768 primitive, re-exported.
  */
-export const ml_kem768: typeof import('@noble/post-quantum/ml-kem').ml_kem768
+export const ml_kem768: typeof import('@noble/post-quantum/ml-kem.js').ml_kem768

package/src/ml-kem.js

@@ -7,7 +7,7 @@
 // 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 { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
 import { deriveSeed } from './derive.js'
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'

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 }