kxco-post-quantum 1.7.2 → 1.7.5

package/src/_native.node.js

@@ -28,11 +28,73 @@
 
 import crypto from 'node:crypto'
 
-// FIPS 204 section 5.2 context strings are not reachable through Node's sign and
-// verify, which take no context argument. A call that uses one falls back to the
-// JavaScript backend rather than being signed without it: a signature made
-// without the caller's context verifies against nothing and would look like a
+// Which implementation this process must use, chosen by the operator.
+//
+// Until now the only control was requireNativeBackend(), which asserts OpenSSL
+// is present. That was enough while only one implementation was going to carry
+// a certificate. Both are now being taken to validation, so a deployment under
+// a validated-module control has to be able to pin EITHER, and the one it must
+// pin is whichever its certificate names.
+//
+// Set from the environment rather than from application code, for the same
+// reason the assertion is: the team under the control is usually not the team
+// calling this library.
+//
+//   KXCO_PQ_BACKEND=javascript   never use OpenSSL, even where it is present
+//   KXCO_PQ_BACKEND=openssl      prefer OpenSSL, which is the default anyway;
+//                                pair with requireBackend to make it binding
+//
+// A value that is neither throws at import. A misspelled pin that silently did
+// nothing would leave the operator believing a control was in force when it
+// was not, which is the exact failure this exists to remove.
+//
+// Nothing here changes what a signature looks like. The two implementations
+// produce identical wire bytes, proved for every parameter set in both
+// directions by the interoperability matrix. What it changes is which one
+// computed them, and backend() always reports that truthfully, including when
+// the answer is the result of this pin.
+const PIN = (() => {
+  try {
+    const v = globalThis.process?.env?.KXCO_PQ_BACKEND
+    if (v === undefined || v === null || v === '') return null
+    const k = String(v).trim().toLowerCase()
+    if (k !== 'openssl' && k !== 'javascript') {
+      throw new Error(
+        `KXCO_PQ_BACKEND must be 'openssl' or 'javascript', got '${v}'`,
+      )
+    }
+    return k
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith('KXCO_PQ_BACKEND')) throw err
+    return null
+  }
+})()
+
+/** The operator's pin, or null. Reported by backend() so evidence records it. */
+export const pinned = PIN
+
+// FIPS 204 section 5.2 and FIPS 205 context strings. Node's sign and verify
+// took no context argument when this module was written, so a call that used
+// one fell back to the JavaScript backend: signing without the caller's context
+// produces a signature that verifies against nothing, which would look like a
 // cross-implementation disagreement rather than a missing feature.
+//
+// Newer Node builds do take one, and honour it. That is worth having rather
+// than assuming either way, because the fallback quietly moved every
+// context-using call onto the implementation the operator did not ask for, and
+// requireNativeBackend() cannot see it happen: it asserts the backend is
+// present, not that a particular call reached it.
+//
+// So the capability is probed rather than inferred from a version number, and
+// the probe is the real thing: sign under one context, then require that the
+// same context verifies and a different one does not. A build that accepted
+// the argument and ignored it would pass the first check and fail the second,
+// and ignoring it is the dangerous outcome, not rejecting it.
+//
+// Verified before this was enabled: with a context string, OpenSSL and
+// @noble/post-quantum accept each other's signatures in both directions, and
+// both reject a wrong context, across ML-DSA-44/65/87 and the three SLH-DSA
+// sets this build exposes.
 
 const DER_SEQUENCE = 0x30
 const DER_OCTET_STRING = 0x04
@@ -109,6 +171,34 @@ function probe() {
 
 const SUPPORTED = probe()
 
+// Whether this runtime's sign and verify honour a context string. Probed once,
+// on first use rather than at import, because most callers never pass one and
+// the probe costs a keygen.
+//
+// `null` means not yet probed. Any throw is read as "no", so a build that
+// rejects the argument outright falls back exactly as before.
+let contextHonoured = null
+function probeContext() {
+  if (contextHonoured !== null) return contextHonoured
+  contextHonoured = false
+  try {
+    // ML-DSA-44 is the cheapest set to key and sign. If the build has no
+    // ML-DSA at all there is nothing to probe with and the answer stays no.
+    const spec = SUPPORTED.get('ML-DSA-44')
+    if (!spec) return contextHonoured
+    const { privateKey, publicKey } = crypto.generateKeyPairSync(spec.nodeName)
+    const message = Buffer.from('kxco-pq context probe')
+    const a = Buffer.from('a'), b = Buffer.from('b')
+    const sig = crypto.sign(null, message, { key: privateKey, context: a })
+    contextHonoured =
+      crypto.verify(null, message, { key: publicKey, context: a }, sig) === true &&
+      crypto.verify(null, message, { key: publicKey, context: b }, sig) === false
+  } catch {
+    contextHonoured = false
+  }
+  return contextHonoured
+}
+
 function privateKeyObject(spec, secretKey, publicKey) {
   if (spec.privateForm === 'jwk') {
     // FIPS 205 lays the private key out as SK.seed || SK.prf || PK.seed ||
@@ -142,7 +232,7 @@ function publicKeyObject(spec, publicKey) {
   })
 }
 
-export const native = SUPPORTED.size === 0 ? null : {
+export const native = (PIN === 'javascript' || SUPPORTED.size === 0) ? null : {
   /** Parameter sets this build can do. Anything else falls through to JS.
    *
    * The Buffer check is not defensive padding. This package's browser-mode
@@ -161,22 +251,33 @@ export const native = SUPPORTED.size === 0 ? null : {
     return [...SUPPORTED.keys()].sort()
   },
 
+  /** Whether a signature carrying a context string can stay on this backend. */
+  supportsContext() {
+    return probeContext()
+  },
+
   openssl: process.versions.openssl,
 
-  sign(alg, secretKey, message, publicKey) {
+  sign(alg, secretKey, message, publicKey, context) {
     const spec = SUPPORTED.get(alg)
     if (!spec) return null
-    return crypto.sign(null, Buffer.from(message), privateKeyObject(spec, secretKey, publicKey))
+    const key = privateKeyObject(spec, secretKey, publicKey)
+    return crypto.sign(
+      null,
+      Buffer.from(message),
+      context === undefined ? key : { key, context: Buffer.from(context) },
+    )
   },
 
-  verify(alg, publicKey, message, signature) {
+  verify(alg, publicKey, message, signature, context) {
     const spec = SUPPORTED.get(alg)
     if (!spec) return null
     try {
+      const key = publicKeyObject(spec, publicKey)
       return crypto.verify(
         null,
         Buffer.from(message),
-        publicKeyObject(spec, publicKey),
+        context === undefined ? key : { key, context: Buffer.from(context) },
         Buffer.from(signature)
       )
     } catch {

package/src/_native.stub.js

@@ -11,3 +11,7 @@
 // working unmodified in a browser.
 
 export const native = null
+
+// Same shape as the Node module so backend() can import it unconditionally.
+// There is no OpenSSL to pin away from here, so there is never a pin.
+export const pinned = null

package/src/backend.d.ts

@@ -7,6 +7,8 @@ export interface BackendReport {
   parameterSets?: string[]
   /** Why the native backend is unavailable, on the JavaScript backend only. */
   reason?: string
+  /** The operator's KXCO_PQ_BACKEND pin, when one is set. */
+  pinned?: 'openssl' | 'javascript'
 }
 
 /** Describe the backend doing the maths in this process. Reports; never switches. */
@@ -32,3 +34,26 @@ export function isNative(alg: string): boolean
  * @throws Error with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
  */
 export function requireNativeBackend(algorithms?: string[]): BackendReport
+
+/**
+ * Refuse to run unless the cryptography is executing in a named implementation.
+ *
+ * The general form of requireNativeBackend. Both implementations are being
+ * taken to algorithm validation, so a deployment under a control that names a
+ * certificate must be able to pin the one its certificate covers, and for some
+ * that is the JavaScript one.
+ *
+ * Asserting 'javascript' where OpenSSL is present fails unless the operator
+ * also set `KXCO_PQ_BACKEND=javascript`. This function reports; the
+ * environment decides. Keeping those apart is what stops application code
+ * quietly changing which implementation a customer's evidence is about.
+ *
+ * @param kind Which implementation must be running.
+ * @param algorithms Parameter sets that must run in it. Only meaningful for
+ *   'openssl'; the JavaScript backend covers every set.
+ * @throws Error with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
+ */
+export function requireBackend(
+  kind: 'openssl' | 'javascript',
+  algorithms?: string[],
+): BackendReport

package/src/backend.js

@@ -16,7 +16,7 @@
 // wrong one, which is a different thing, and the thing a deployment under a
 // validated-module control actually needs.
 
-import { native } from '#native'
+import { native, pinned } from '#native'
 
 // An operator control. A deployment under a validated-module requirement is
 // usually not the same team as the one calling this library, so the
@@ -46,13 +46,20 @@ export function backend() {
     return {
       kind: 'javascript',
       library: '@noble/post-quantum',
-      reason: 'the runtime does not provide the FIPS 203/204/205 primitives',
+      // Two different facts wear the same result, and an evidence bundle that
+      // conflated them would be wrong. Absent means the runtime cannot do it.
+      // Pinned means it can and the operator said not to.
+      reason: pinned === 'javascript'
+        ? 'KXCO_PQ_BACKEND=javascript pins this process to the JavaScript backend'
+        : 'the runtime does not provide the FIPS 203/204/205 primitives',
+      ...(pinned ? { pinned } : {}),
     }
   }
   return {
     kind: 'openssl',
     library: 'node:crypto',
     openssl: native.openssl,
+    ...(pinned ? { pinned } : {}),
     // Only the sets OpenSSL can express. Anything absent here still works, on
     // the JavaScript backend, which is why this is a list rather than a flag.
     parameterSets: native.algorithms(),
@@ -93,20 +100,48 @@ export function isNative(alg) {
  * @throws {Error} with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
  */
 export function requireNativeBackend(algorithms) {
+  return requireBackend('openssl', algorithms)
+}
+
+/**
+ * Refuse to run unless the cryptography is executing in a named implementation.
+ *
+ * The general form of requireNativeBackend, and the reason it exists is that
+ * both implementations are being taken to algorithm validation. A deployment
+ * under a control that names a certificate has to be able to pin the one its
+ * certificate covers, and for some of them that is the JavaScript one.
+ *
+ * Asserting 'javascript' on a runtime that has OpenSSL will fail unless the
+ * operator also set KXCO_PQ_BACKEND=javascript, and that is deliberate. This
+ * function reports; the environment decides. Keeping the two apart is what
+ * stops application code quietly changing which implementation a customer's
+ * evidence is about.
+ *
+ * @param {'openssl'|'javascript'} kind
+ * @param {string[]} [algorithms] — parameter sets that must run in it. Only
+ *   meaningful for 'openssl'; the JavaScript backend covers every set.
+ * @throws {Error} with `code: 'ERR_KXCO_PQ_BACKEND'` when the requirement fails.
+ */
+export function requireBackend(kind, algorithms) {
+  if (kind !== 'openssl' && kind !== 'javascript') {
+    throw backendError(`backend must be 'openssl' or 'javascript', got '${kind}'`, { required: kind })
+  }
   const b = backend()
-  if (b.kind !== 'openssl') {
+  if (b.kind !== kind) {
     throw backendError(
-      `the native backend is required and is not present: ${b.reason}`,
-      { required: 'openssl', actual: b.kind, reason: b.reason },
+      `the ${kind} backend is required and is not the one running: ${b.reason ?? `this process is on ${b.kind}`}`,
+      { required: kind, actual: b.kind, reason: b.reason, pinned: b.pinned },
     )
   }
-  const missing = (algorithms ?? []).filter((a) => !isNative(a))
-  if (missing.length) {
-    throw backendError(
-      `the native backend is required for ${missing.join(', ')}, ` +
-        `and this OpenSSL does not provide ${missing.length > 1 ? 'them' : 'it'}`,
-      { required: 'openssl', actual: b.kind, missing, available: b.parameterSets },
-    )
+  if (kind === 'openssl') {
+    const missing = (algorithms ?? []).filter((a) => !isNative(a))
+    if (missing.length) {
+      throw backendError(
+        `the native backend is required for ${missing.join(', ')}, ` +
+          `and this OpenSSL does not provide ${missing.length > 1 ? 'them' : 'it'}`,
+        { required: 'openssl', actual: b.kind, missing, available: b.parameterSets },
+      )
+    }
   }
   return b
 }

package/src/index.js

@@ -37,4 +37,4 @@ export * as jws  from './jws.js'
 
 // Reports which backend is doing the maths in this process, for evidence
 // bundles and support. It reports; it never switches.
-export { backend, isNative, requireNativeBackend } from './backend.js'
+export { backend, isNative, requireNativeBackend, requireBackend } from './backend.js'

package/src/ml-dsa-87.js

@@ -64,8 +64,13 @@ function wrap(bytes) {
 // changes. The two backends are checked against each other for this parameter
 // set in both directions by the interoperability matrix.
 const NATIVE_ALG = 'ML-DSA-87'
+// A context string stays on the native backend only where the runtime honours
+// it; see the probe in _native.node.js. Where it does not, this falls back to
+// the JavaScript backend exactly as it always did.
 const usesNative = (context) =>
-  context === undefined && native !== null && native.supports(NATIVE_ALG)
+  native !== null &&
+  native.supports(NATIVE_ALG) &&
+  (context === undefined || native.supportsContext())
 
 /**
  * Generate an ML-DSA-87 keypair from a master + domain-separation info.
@@ -104,7 +109,7 @@ export function keypairFromMaster(master, info = 'ml-dsa-87-v1') {
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
   if (usesNative(context)) {
-    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message), undefined, context))
   }
   const sig = context === undefined
     ? ml_dsa87.sign(toBytes(message), secretKey)
@@ -135,7 +140,7 @@ export function verify(publicKey, message, sigHex, opts) {
   const context = normalizeContext(opts)
   try {
     if (usesNative(context)) {
-      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex), context)
     }
     return context === undefined
       ? ml_dsa87.verify(hexToBytes(sigHex), toBytes(message), publicKey)

package/src/ml-dsa.js

@@ -20,12 +20,18 @@ export { MAX_CONTEXT_BYTES }
 // set in both directions by the interoperability matrix, so this is a swap
 // between two implementations known to agree, not an assumption that they do.
 //
-// A context string forces the JavaScript path: Node's sign and verify take no
-// context argument, and signing without the caller's context would produce a
-// signature that verifies against nothing.
+// A context string used to force the JavaScript path unconditionally, because
+// Node's sign and verify took no context argument. Newer builds take one and
+// honour it, so the capability is probed and the call stays native where it
+// holds. The fallback is unchanged everywhere else.
 const NATIVE_ALG = 'ML-DSA-65'
+// A context string stays on the native backend only where the runtime honours
+// it; see the probe in _native.node.js. Where it does not, this falls back to
+// the JavaScript backend exactly as it always did.
 const usesNative = (context) =>
-  context === undefined && native !== null && native.supports(NATIVE_ALG)
+  native !== null &&
+  native.supports(NATIVE_ALG) &&
+  (context === undefined || native.supportsContext())
 
 const HAS_BUFFER = typeof Buffer !== 'undefined'
 const enc = new TextEncoder()
@@ -85,7 +91,7 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
   if (usesNative(context)) {
-    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message), undefined, context))
   }
   const sig = context === undefined
     ? ml_dsa65.sign(toBytes(message), secretKey)
@@ -115,7 +121,7 @@ export function verify(publicKey, message, sigHex, opts) {
   const context = normalizeContext(opts)
   try {
     if (usesNative(context)) {
-      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex), context)
     }
     return context === undefined
       ? ml_dsa65.verify(hexToBytes(sigHex), toBytes(message), publicKey)

package/src/slh-dsa.js

@@ -52,8 +52,13 @@ const SEED_BYTES = slh_dsa_sha2_192s.lengths.seed
 // changes. The two backends are checked against each other for this parameter
 // set in both directions by the interoperability matrix.
 const NATIVE_ALG = 'SLH-DSA-SHA2-192s'
+// A context string stays on the native backend only where the runtime honours
+// it; see the probe in _native.node.js. Where it does not, this falls back to
+// the JavaScript backend exactly as it always did.
 const usesNative = (context) =>
-  context === undefined && native !== null && native.supports(NATIVE_ALG)
+  native !== null &&
+  native.supports(NATIVE_ALG) &&
+  (context === undefined || native.supportsContext())
 
 /**
  * Generate an SLH-DSA-SHA2-192s keypair from a master + domain-separation info.
@@ -85,7 +90,7 @@ export function keypairFromMaster(master, info = 'slh-dsa-sha2-192s-v1') {
 export function sign(secretKey, message, opts) {
   const context = normalizeContext(opts)
   if (usesNative(context)) {
-    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message)))
+    return bytesToHex(native.sign(NATIVE_ALG, secretKey, toBytes(message), undefined, context))
   }
   const sig = context === undefined
     ? slh_dsa_sha2_192s.sign(toBytes(message), secretKey)
@@ -109,7 +114,7 @@ export function verify(publicKey, message, sigHex, opts) {
   const context = normalizeContext(opts)
   try {
     if (usesNative(context)) {
-      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex))
+      return native.verify(NATIVE_ALG, publicKey, toBytes(message), hexToBytes(sigHex), context)
     }
     return context === undefined
       ? slh_dsa_sha2_192s.verify(hexToBytes(sigHex), toBytes(message), publicKey)