kxco-post-quantum 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.3.0 - unreleased
+
+Adds FIPS 204 / FIPS 205 context string support. Purely additive: the
+cryptographic surface for every existing call site is byte-for-byte unchanged,
+and all 39 pinned vectors still match.
+
+### Added
+- **Optional `context` on `mlDsa.sign` / `mlDsa.verify`** via a trailing options
+  object, `{ context }`. At most 255 bytes per FIPS 204 section 5.2; strings are
+  encoded as UTF-8. A signature made under a context does not verify without it
+  or under a different one. Closes a real incompleteness relative to FIPS 204:
+  the library previously could not verify a counterparty's signature that used a
+  context.
+- **The same option on `slhDsa.sign` / `slhDsa.verify`**, on the same terms.
+  Added alongside ML-DSA rather than after it, because one signature module
+  accepting an options object while its sibling silently ignored one would be a
+  footgun.
+- `MAX_CONTEXT_BYTES` (255) exported from both modules.
+- `test/context.test.js`, 26 tests, including cross-verification against
+  third-party ML-DSA-65 signatures produced by OpenSSL through Python
+  `cryptography`, covering five context shapes: short, single-byte, the 255-byte
+  maximum, binary, and multi-byte UTF-8.
+
+### Notes
+- **No behaviour change without the new argument.** Omitting `opts` takes the
+  identical code path as before. An empty context is collapsed to no context,
+  which is what FIPS 204 specifies and what was verified empirically.
+- **Misuse throws rather than returning `false`.** A context over 255 bytes, a
+  wrongly typed context, or a bare value passed where an options object belongs
+  raises `RangeError` / `TypeError`. These are caller bugs, not failed
+  verifications, and swallowing them would hide a signature that silently
+  carried no domain separation. No existing call site passes the argument, so
+  nothing can regress.
+- Works identically on `@noble/post-quantum` 0.6.1 and 0.7.0, verified on both,
+  so this release is independent of the 0.7.0 upgrade.
+
 ## 1.2.1 — 2026-07-22
 
 Metadata alignment. No code changes; cryptographic surface is byte-for-byte

package/README.md

@@ -48,6 +48,44 @@ const recovered = mlKem.decapsulate(ciphertext, kemKeys.secretKey)
 
 `masterSecret` is a `Buffer` or `Uint8Array` with at least 16 bytes of entropy (typically 32–64 bytes from an env var or KMS).
 
+### Context strings (FIPS 204 / FIPS 205)
+
+`sign` and `verify` take an optional context string, at most 255 bytes. A
+signature made under a context does not verify without it, or under a different
+one.
+
+```js
+const sig = mlDsa.sign(secretKey, 'hello', { context: 'kxco-nexus-v1' })
+
+mlDsa.verify(publicKey, 'hello', sig, { context: 'kxco-nexus-v1' })  // true
+mlDsa.verify(publicKey, 'hello', sig)                                // false
+mlDsa.verify(publicKey, 'hello', sig, { context: 'other-v1' })       // false
+```
+
+The parameter is optional and defaults to no context, so every existing call
+site is unaffected. An empty context is identical to omitting it. `slhDsa` takes
+the same option.
+
+**Context separates at the signature level; `keypairFromMaster(master, info)`
+separates at the key level.** They are complementary. Use a context when one key
+legitimately signs for several purposes and you need a signature from one
+purpose to be unusable in another. Use a distinct derived key when the purposes
+should not share a key at all.
+
+Strings are encoded as UTF-8, so the 255-byte limit is bytes and not
+characters. Over-length or wrongly typed input throws (`RangeError` /
+`TypeError`) rather than returning `false`, because that is a caller bug and not
+a failed verification:
+
+```js
+mlDsa.sign(secretKey, 'hello', 'kxco-nexus-v1')  // throws TypeError
+                                                 // (needs { context: ... })
+```
+
+That last case is worth guarding: without the throw it would silently sign with
+*no* context and produce a valid-looking signature carrying none of the intended
+separation.
+
 ---
 
 ## API
@@ -129,7 +167,7 @@ Install this package directly when you need ML-DSA or ML-KEM without the rest of
 
 Cryptographic operations delegate entirely to [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) and [`@noble/hashes`](https://github.com/paulmillr/noble-hashes) — this package does not reimplement any NIST primitive. `@noble/hashes` falls under Cure53's 2023 audit of the `@noble` ecosystem (`ciphers`, `curves`, `hashes`); `@noble/post-quantum` was **not** in that audit's scope and has been self-audited by its maintainer. See [AUDIT.md](./AUDIT.md) for the full posture.
 
-To report a vulnerability: [open a private security advisory](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/security/advisories/new) or email **security@kxco.ai**.
+To report a vulnerability: [open a private security advisory](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/security/advisories/new) or email **john@knightsbridgelaw.com**. Acknowledgement within 2 business days, triage decision within 5. Full policy, including safe harbour for good-faith research: <https://kxco.ai/security>.
 
 ## License
 

package/SECURITY.md

@@ -1,9 +1,22 @@
 # Security Policy
 
 ## Reporting a vulnerability
-Email **security@kxco.ai**. Do not open public issues for security reports.
-PGP key available on request. We respond within 48 hours and credit reporters
-in `CHANGELOG.md` unless they request otherwise.
+Email **john@knightsbridgelaw.com**. Do not open public issues for security reports.
+PGP key available on request. We credit reporters in `CHANGELOG.md` unless they
+request otherwise.
+
+Acknowledgement within **2 business days**. Triage decision within **5 business days**.
+
+Full policy: <https://kxco.ai/security>
+
+## Safe harbour
+If you make a good-faith effort to comply with this policy, we will treat your
+research as authorised, and we will not pursue or support legal action against
+you. Good faith means: do not access, modify, exfiltrate, or destroy data that
+is not yours; use test accounts where possible; do not degrade service for
+others; and stop and report as soon as you have established that a
+vulnerability exists. This cannot bind third parties, and it does not cover
+extortion, data sale, or public disclosure ahead of the window below.
 
 ## Scope
 In scope:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.2.1",
+  "version": "1.3.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",
@@ -23,7 +23,6 @@
     "deterministic-keys",
     "fingerprint",
     "replay-protection",
-    "constant-time",
     "hybrid-signing",
     "non-repudiation"
   ],
@@ -41,10 +40,10 @@
   "funding": "https://kxco.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/JackKXCO/kxco-post-quantum.git"
+    "url": "https://github.com/KnightsbridgeAIQ/kxco-post-quantum.git"
   },
   "bugs": {
-    "url": "https://github.com/JackKXCO/kxco-post-quantum/issues"
+    "url": "https://github.com/KnightsbridgeAIQ/kxco-post-quantum/issues"
   },
   "type": "module",
   "sideEffects": false,
@@ -91,11 +90,11 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@noble/hashes": "^2.2.0",
-    "@noble/post-quantum": "^0.6.1"
+    "@noble/hashes": "2.3.0",
+    "@noble/post-quantum": "0.7.0"
   },
   "scripts": {
-    "test": "node --test test/basic.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
+    "test": "node --test test/basic.test.js && node --test test/context.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
     "test:vectors": "node test/run-vectors.js",
     "generate:vectors": "node test/generate-vectors.js > test/vectors.json",
     "bench": "node bench/bench.js"

package/src/_context.js

@@ -0,0 +1,69 @@
+// Internal: FIPS 204 / FIPS 205 signature context strings.
+//
+// Not part of the public exports map. Shared by ml-dsa.js and slh-dsa.js
+// because a validator for security-relevant input should exist once, even
+// though the small byte/hex helpers in those modules are duplicated.
+//
+// FIPS 204 section 5.2 (and FIPS 205 equivalently) allow an optional context
+// string of at most 255 bytes, mixed into the message representative. It gives
+// domain separation: a signature made under one context does not verify under
+// another, or under no context at all.
+//
+// KXCO derives keys per domain via deriveSeed(master, info), which separates at
+// the KEY level. Context separates at the SIGNATURE level, so one key can sign
+// for several domains without a signature being replayable across them. The two
+// are complementary, not alternatives.
+
+const enc = new TextEncoder()
+
+/** FIPS 204 section 5.2: |ctx| <= 255. */
+export const MAX_CONTEXT_BYTES = 255
+
+/**
+ * Normalise the options bag into a context byte string, or undefined.
+ *
+ * Returns undefined for "no context", which makes the caller take the exact
+ * code path it took before this parameter existed. An empty context is
+ * cryptographically identical to no context, so it also returns undefined
+ * rather than passing a zero-length array down.
+ *
+ * THROWS on caller misuse (wrong type, over-length). This is deliberate and it
+ * differs from verify()'s usual fail-closed behaviour: a malformed context is a
+ * programming error, not a bad signature, and silently returning false would
+ * hide the bug behind an outcome that looks like a normal verification failure.
+ * No existing call site passes this argument, so nothing can regress.
+ *
+ * @param {{ context?: Uint8Array|Buffer|string }} [opts]
+ * @returns {Uint8Array|undefined}
+ */
+export function normalizeContext(opts) {
+  if (opts === undefined || opts === null) return undefined
+
+  if (typeof opts !== 'object' || Array.isArray(opts) || opts instanceof Uint8Array) {
+    throw new TypeError(
+      'expected an options object such as { context }, not a bare value',
+    )
+  }
+
+  const { context } = opts
+  if (context === undefined || context === null) return undefined
+
+  let bytes
+  if (context instanceof Uint8Array) {
+    bytes = context
+  } else if (typeof context === 'string') {
+    bytes = enc.encode(context)
+  } else {
+    throw new TypeError('context must be a Uint8Array or a string')
+  }
+
+  if (bytes.length > MAX_CONTEXT_BYTES) {
+    throw new RangeError(
+      `context must be at most ${MAX_CONTEXT_BYTES} bytes (FIPS 204 section 5.2), got ${bytes.length}`,
+    )
+  }
+
+  // Empty context is identical to no context under FIPS 204, so collapse it
+  // and keep the legacy call path byte-for-byte.
+  return bytes.length === 0 ? undefined : bytes
+}

package/src/ml-dsa.d.ts

@@ -18,23 +18,56 @@ export function keypairFromMaster(
   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 | string,
+  message:   Buffer | Uint8Array | string,
+  opts?:     SignatureOptions,
 ): string
 
 /**
  * Verify a hex-encoded ML-DSA-65 signature against a public key + message.
- * Returns `false` on any error (invalid hex, wrong length, mismatch).
+ *
+ * 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 | string,
+  message:   Buffer | Uint8Array | string,
   sigHex:    string,
+  opts?:     SignatureOptions,
 ): boolean
 
 /**

package/src/ml-dsa.js

@@ -8,6 +8,9 @@
 
 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()
@@ -50,26 +53,47 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
 /**
  * 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) {
-  const sig = ml_dsa65.sign(toBytes(message), secretKey)
+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) {
+export function verify(publicKey, message, sigHex, opts) {
+  // Outside the try: misuse must surface, not be swallowed as "invalid".
+  const context = normalizeContext(opts)
   try {
-    return ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+    return context === undefined
+      ? ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+      : ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey, { context })
   } catch {
     return false
   }

package/src/slh-dsa.d.ts

@@ -19,23 +19,49 @@ export function keypairFromMaster(
   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 | string,
+  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 error (invalid hex, wrong length, mismatch).
+ * 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 | string,
+  message:   Buffer | Uint8Array | string,
   sigHex:    string,
+  opts?:     SignatureOptions,
 ): boolean
 
 /**

package/src/slh-dsa.js

@@ -15,6 +15,9 @@
 
 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()
@@ -60,26 +63,41 @@ export function keypairFromMaster(master, info = 'slh-dsa-sha2-192s-v1') {
 /**
  * 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) {
-  const sig = slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
+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) {
+export function verify(publicKey, message, sigHex, opts) {
+  const context = normalizeContext(opts)
   try {
-    return slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)
+    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
   }