kxco-post-quantum 1.3.0 → 1.4.1

package/src/ml-dsa.d.ts

@@ -1,78 +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
-
-/** 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
+/// <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

package/src/ml-dsa.js

@@ -1,102 +1,102 @@
-// 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'
-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-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.
- *
- * An optional FIPS 204 section 5.2 context string gives domain separation: a
- * signature made under a context does not verify without it. 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 (6618 chars)
- */
-export function sign(secretKey, message, opts) {
-  const context = normalizeContext(opts)
-  const sig = context === undefined
-    ? ml_dsa65.sign(toBytes(message), secretKey)
-    : ml_dsa65.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. 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_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
-      : ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
-  } 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'
+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-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.
+ *
+ * An optional FIPS 204 section 5.2 context string gives domain separation: a
+ * signature made under a context does not verify without it. 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 (6618 chars)
+ */
+export function sign(secretKey, message, opts) {
+  const context = normalizeContext(opts)
+  const sig = context === undefined
+    ? ml_dsa65.sign(toBytes(message), secretKey)
+    : ml_dsa65.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. 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_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+      : ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
+  } catch {
+    return false
+  }
+}
+
+export { ml_dsa65 }

package/src/ml-kem-1024.d.ts

@@ -0,0 +1,59 @@
+/// <reference types="node" />
+
+export interface MlKem1024Keypair {
+  /** 1568-byte public key */
+  publicKey: Buffer
+  /** 3168-byte secret key */
+  secretKey: Buffer
+}
+
+export interface MlKem1024Encapsulation {
+  /** 1568-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; run it through a KDF before use as a key */
+  sharedSecret: Buffer
+}
+
+/**
+ * Generate an ML-KEM-1024 (NIST FIPS 203) keypair deterministically
+ * from a master + domain-separation info string.
+ *
+ * Security Category 5. The default `info` differs from the ML-KEM-768 module's,
+ * so one master yields unrelated keys for the two parameter sets.
+ *
+ * CNSA 2.0 names ML-KEM-1024. Support for the parameter set is not a CNSA 2.0
+ * compliance claim; see the note at the top of `ml-kem-1024.js`.
+ */
+export function keypairFromMaster(
+  master: Buffer | Uint8Array,
+  info?:  string,
+): MlKem1024Keypair
+
+/**
+ * Encapsulate a shared secret to the recipient's ML-KEM-1024 public key.
+ *
+ * The recipient calls `decapsulate(ciphertext, secretKey)` to recover
+ * the same shared secret. Derive the symmetric key from it with a KDF rather
+ * than using it directly.
+ */
+export function encapsulate(publicKey: Buffer | Uint8Array): MlKem1024Encapsulation
+
+/**
+ * Decapsulate: recover the shared secret from a KEM ciphertext
+ * using the recipient's secret key.
+ *
+ * A corrupted ciphertext returns an unrelated 32-byte secret rather than
+ * throwing (FIPS 203 implicit rejection), so a successful return is not
+ * evidence the ciphertext was authentic.
+ */
+export function decapsulate(
+  ciphertext: Buffer | Uint8Array,
+  secretKey:  Buffer | Uint8Array,
+): Buffer
+
+/**
+ * Raw `@noble/post-quantum` ML-KEM-1024 primitive, re-exported.
+ */
+export const ml_kem1024: typeof import('@noble/post-quantum/ml-kem.js').ml_kem1024

package/src/ml-kem-1024.js

@@ -0,0 +1,90 @@
+// ML-KEM-1024 helpers (NIST FIPS 203, Kyber1024).
+//
+// Module-lattice key encapsulation. Security Category 5 (≈ AES-256). Public
+// key 1568 bytes, ciphertext 1568 bytes, shared secret 32 bytes. Resistant to
+// attacks by quantum computers.
+//
+// Same API as ./ml-kem.js, one security category higher. Use this where a
+// counterparty specifies Category 5 or names ML-KEM-1024. ML-KEM-768 remains
+// the default for the KXCO stack.
+//
+// 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-KEM-1024 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 accurate sentence is "supports ML-KEM-1024".
+// See CONFORMANCE.md.
+//
+// The shared secret is 32 bytes at both parameter sets, so moving up does not
+// change key-derivation code downstream. Public keys and ciphertexts do grow:
+// 1568 bytes each, against 1184 and 1088 at ML-KEM-768.
+//
+// As with ML-KEM-768: do not use the returned shared secret as a key directly.
+// Run it through a KDF with a context label. That is what deriveSeed is for.
+// ---------------------------------------------------------------------------
+
+import { ml_kem1024 } 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-1024 keypair from a master + domain-separation info.
+ *
+ * The default info differs from the ML-KEM-768 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-kem-1024-v1') {
+  const seed = deriveSeed(master, info, 64)
+  const seedU8 = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
+  const k = ml_kem1024.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_kem1024.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.
+ *
+ * A corrupted ciphertext yields an unrelated 32-byte secret rather than an
+ * error, which is FIPS 203 implicit rejection and is deliberate. Never treat a
+ * successful return as proof the ciphertext was authentic.
+ *
+ * @param {Buffer|Uint8Array} ciphertext
+ * @param {Buffer|Uint8Array} secretKey
+ * @returns {Buffer|Uint8Array} shared secret (32 bytes)
+ */
+export function decapsulate(ciphertext, secretKey) {
+  return wrap(ml_kem1024.decapsulate(ciphertext, secretKey))
+}
+
+export { ml_kem1024 }

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.js').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