kxco-post-quantum 1.3.0 → 1.4.1

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.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 }
+// 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

@@ -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 }