@blamejs/core 0.8.42 → 0.8.49

package/lib/network-tls.js

@@ -5,6 +5,7 @@ var fs = require("node:fs");
 var path = require("node:path");
 var nodeCrypto = require("node:crypto");
 
+var blamejsCrypto = require("./crypto");
 var C = require("./constants");
 var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
@@ -13,6 +14,7 @@ var safeAsync = require("./safe-async");
 var { defineClass } = require("./framework-error");
 
 var TlsTrustError = defineClass("TlsTrustError", { alwaysPermanent: true });
+var NetworkTlsError = defineClass("NetworkTlsError", { alwaysPermanent: true });
 
 var observability = lazyRequire(function () { return require("./observability"); });
 var audit = lazyRequire(function () { return require("./audit"); });
@@ -26,7 +28,7 @@ var STATE = {
   cas:             [],
   systemTrust:     false,
   baselineFingerprints: null,
-  tlsKeyShares:    ["SecP384r1MLKEM1024", "X25519MLKEM768", "X25519"],
+  tlsKeyShares:    ["X25519MLKEM768", "SecP256r1MLKEM768", "SecP384r1MLKEM1024", "X25519"],
 };
 
 function _normalizePem(pem) {
@@ -435,10 +437,29 @@ function applyToContext(opts) {
 //   setKeyShares(["X25519MLKEM768", "X25519"])        → string[] (after)
 //   resetKeyShares()                                  → restores default
 
+// RFC 9794 (PQ TLS Hybrid Key Exchange) named-group ordering. The
+// preferred groups (the first the peer mutually supports wins) put the
+// IANA-registered hybrid named groups ahead of the classical fallback:
+//
+//   X25519MLKEM768       — codepoint 0x11EC, RFC 9794 default hybrid
+//   SecP256r1MLKEM768    — codepoint 0x11EB, RFC 9794 optional hybrid
+//                            (NIST-curve fallback for FIPS-mandated peers
+//                            that refuse X25519)
+//   SecP384r1MLKEM1024   — draft-kwiatkowski-tls-ecdhe-mlkem-02 codepoint
+//                            0x11ED; highest-PQC hybrid; only ML-KEM-1024
+//                            offering for FIPS-mandated peers wanting
+//                            CNSA-2.0-aligned key strength
+//   X25519               — classical fallback (modern non-PQC peers)
+//
+// Operators FIPS-mandated to a NIST curve set `setKeyShares([
+// "SecP256r1MLKEM768", "SecP384r1MLKEM1024" ])` and drop the X25519-
+// based groups. Operators on legacy peers without any PQC support set
+// `setKeyShares(["X25519"])` to opt out of the hybrid groups entirely.
 var DEFAULT_PQC_KEY_SHARES = Object.freeze([
-  "SecP384r1MLKEM1024",                                                          // highest-PQC hybrid (codepoint 0x11ED, draft-kwiatkowski-tls-ecdhe-mlkem-02)
-  "X25519MLKEM768",                                                              // mid-PQC hybrid (codepoint 0x11EC, IETF/Cloudflare/Chrome interop)
-  "X25519",                                                                      // classical fallback (modern non-PQC peers)
+  "X25519MLKEM768",
+  "SecP256r1MLKEM768",
+  "SecP384r1MLKEM1024",
+  "X25519",
 ]);
 
 function _validateKeyShare(name) {
@@ -474,6 +495,18 @@ function resetKeyShares() {
   return getKeyShares();
 }
 
+// preferredGroups — RFC 9794 alias surface for the named-group list.
+// `set(list)` overrides the default ordering; `get()` reads the active
+// list; `reset()` restores the framework default. The setKeyShares /
+// getKeyShares / resetKeyShares names are kept as the lower-level
+// alias under `b.network.tls.pqc.*`.
+var preferredGroups = Object.freeze({
+  set:    setKeyShares,
+  get:    getKeyShares,
+  reset:  resetKeyShares,
+  DEFAULT: DEFAULT_PQC_KEY_SHARES,
+});
+
 var pqc = Object.freeze({
   setKeyShares:           setKeyShares,
   getKeyShares:           getKeyShares,
@@ -485,6 +518,139 @@ function getCaPems() {
   return STATE.cas.map(function (e) { return e.pem; });
 }
 
+// b.network.tls.buildOptions(opts) — assemble a plain options object
+// suitable for tls.connect / new https.Agent(...) / https.request,
+// pre-populated with the framework's PQC group preference + TLSv1.3
+// floor. Operators that build their own outbound transport (custom
+// https.Agent, raw tls.connect for protocol clients other than HTTP)
+// route through this primitive so the same posture lands everywhere.
+//
+// Throws NetworkTlsError("network-tls/bad-tls-options") on invalid
+// shape (config-time entry point — operator catches typo at boot).
+//
+//   buildOptions({ ecdhCurve, groups, cert, key, ca, minVersion, sni })
+//     returns { minVersion, ecdhCurve, groups, cert, key, ca, servername }
+//
+// `ca` accepts a PEM string OR Buffer OR Array<string|Buffer>; arrays
+// are concatenated with `\n` so Node's TLS layer parses every block.
+function _normalizeCaInput(ca) {
+  if (ca === undefined || ca === null) return undefined;
+  if (Buffer.isBuffer(ca)) return ca.toString("utf8");
+  if (typeof ca === "string") return ca;
+  if (!Array.isArray(ca)) {
+    throw new NetworkTlsError("network-tls/bad-tls-options",
+      "buildOptions: ca must be a PEM string, Buffer, or array thereof");
+  }
+  var parts = [];
+  for (var i = 0; i < ca.length; i += 1) {
+    var entry = ca[i];
+    if (Buffer.isBuffer(entry)) parts.push(entry.toString("utf8"));
+    else if (typeof entry === "string") parts.push(entry);
+    else {
+      throw new NetworkTlsError("network-tls/bad-tls-options",
+        "buildOptions: ca[" + i + "] must be a PEM string or Buffer");
+    }
+  }
+  return parts.join("\n");
+}
+
+function buildOptions(opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Array.isArray(opts)) {
+    throw new NetworkTlsError("network-tls/bad-tls-options",
+      "buildOptions: opts must be a plain object");
+  }
+  validateOpts(opts,
+    ["ecdhCurve", "groups", "cert", "key", "ca", "minVersion", "sni"],
+    "network.tls.buildOptions");
+  var out = {};
+  // TLS-1.3 floor — matches the framework's locked posture in
+  // pqc-agent. Operators may pass minVersion: "TLSv1.3" explicitly;
+  // anything else fails closed.
+  var minV = opts.minVersion === undefined ? "TLSv1.3" : opts.minVersion;
+  if (minV !== "TLSv1.3") {
+    throw new NetworkTlsError("network-tls/bad-tls-options",
+      "buildOptions: minVersion must be 'TLSv1.3' (got " +
+      JSON.stringify(opts.minVersion) + ") — framework posture is " +
+      "TLS-1.3-only outbound; construct tls.connect opts directly to " +
+      "negotiate weaker protocol versions.");
+  }
+  out.minVersion = minV;
+
+  // PQC group preference. Caller may narrow (drop a group) but not
+  // widen — every requested group must appear in the framework
+  // preferred list. Both `groups` (RFC 9794 alias) and `ecdhCurve`
+  // (Node TLS option) are accepted; `groups` wins when both supplied.
+  var requested = null;
+  if (Array.isArray(opts.groups)) {
+    requested = opts.groups.slice();
+  } else if (typeof opts.groups === "string" && opts.groups.length > 0) {
+    requested = opts.groups.split(":");
+  } else if (typeof opts.ecdhCurve === "string" && opts.ecdhCurve.length > 0) {
+    requested = opts.ecdhCurve.split(":");
+  } else if (opts.groups !== undefined || opts.ecdhCurve !== undefined) {
+    throw new NetworkTlsError("network-tls/bad-tls-options",
+      "buildOptions: groups must be string or string[], ecdhCurve must be string");
+  }
+  var preferred = STATE.tlsKeyShares.length > 0
+    ? STATE.tlsKeyShares.slice()
+    : DEFAULT_PQC_KEY_SHARES.slice();
+  var resolved;
+  if (requested === null) {
+    resolved = preferred;
+  } else {
+    if (requested.length === 0) {
+      throw new NetworkTlsError("network-tls/bad-tls-options",
+        "buildOptions: groups/ecdhCurve must list at least one named group");
+    }
+    for (var rgi = 0; rgi < requested.length; rgi += 1) {
+      if (typeof requested[rgi] !== "string" || requested[rgi].length === 0) {
+        throw new NetworkTlsError("network-tls/bad-tls-options",
+          "buildOptions: groups[" + rgi + "] must be a non-empty string");
+      }
+      if (preferred.indexOf(requested[rgi]) === -1) {
+        throw new NetworkTlsError("network-tls/bad-tls-options",
+          "buildOptions: group '" + requested[rgi] + "' is not in the " +
+          "framework preferred list (" + preferred.join(":") + "); " +
+          "construct tls.connect opts directly to negotiate weaker groups.");
+      }
+    }
+    resolved = requested;
+  }
+  var resolvedStr = resolved.join(":");
+  out.ecdhCurve = resolvedStr;
+  out.groups    = resolvedStr;
+
+  // cert / key — pass-through with light shape check. Both are
+  // typically PEM strings or Buffers; arrays are valid for cert
+  // bundles per Node's tls API, so allow array<string|Buffer>.
+  if (opts.cert !== undefined) {
+    if (!(typeof opts.cert === "string" || Buffer.isBuffer(opts.cert) ||
+          Array.isArray(opts.cert))) {
+      throw new NetworkTlsError("network-tls/bad-tls-options",
+        "buildOptions: cert must be a string, Buffer, or array thereof");
+    }
+    out.cert = opts.cert;
+  }
+  if (opts.key !== undefined) {
+    if (!(typeof opts.key === "string" || Buffer.isBuffer(opts.key) ||
+          Array.isArray(opts.key))) {
+      throw new NetworkTlsError("network-tls/bad-tls-options",
+        "buildOptions: key must be a string, Buffer, or array thereof");
+    }
+    out.key = opts.key;
+  }
+  if (opts.ca !== undefined) out.ca = _normalizeCaInput(opts.ca);
+
+  // SNI override — Node spells this `servername`.
+  if (opts.sni !== undefined) {
+    validateOpts.requireNonEmptyString(opts.sni, "buildOptions: sni",
+      NetworkTlsError, "network-tls/bad-tls-options");
+    out.servername = opts.sni;
+  }
+  return out;
+}
+
 function _emitAuditAdd(metaList, opts) {
   if (opts.audit === false) return;
   var sink;
@@ -1686,6 +1852,186 @@ function verifyScts(certDer, opts) {
   };
 }
 
+// ---- RFC 9162 §2.1 Merkle tree primitives ----
+//
+// CT v2 (RFC 9162) inclusion + consistency proofs operate on a binary
+// Merkle tree with the following node hashes (RFC 9162 §2.1.1):
+//
+//   MTH(empty) = SHA-256("")                                  — empty tree
+//   MTH({d})   = SHA-256(0x00 || d)                           — leaf
+//   MTH(D)     = SHA-256(0x01 || MTH(D[0:k]) || MTH(D[k:n]))  — internal
+//
+// SHA-256 is the algorithm RFC 9162 mandates; the framework's PQC-first
+// posture does not apply here because the algorithm is wire-defined
+// by the CT log itself and changing it would break interop with every
+// public log. A future SHA3-flavoured CT (no draft as of writing) ships
+// alongside, not in place.
+//
+// LEAF_HASH_PREFIX  = 0x00
+// INNER_HASH_PREFIX = 0x01
+// k = largest power of 2 < n  (RFC 9162 §2.1.1)
+
+var CT_LEAF_HASH_PREFIX  = 0x00;
+var CT_INNER_HASH_PREFIX = 0x01;
+
+function _ctSha256(buf) {
+  return nodeCrypto.createHash("sha256").update(buf).digest();
+}
+function _ctLeafHash(leafBytes) {
+  return _ctSha256(Buffer.concat([Buffer.from([CT_LEAF_HASH_PREFIX]), leafBytes]));
+}
+function _ctInnerHash(left, right) {
+  return Buffer.concat([Buffer.from([CT_INNER_HASH_PREFIX]), left, right]);
+}
+function _ctInnerHashFinal(left, right) {
+  return _ctSha256(_ctInnerHash(left, right));
+}
+
+// _ctLargestPowerOf2LessThan — k from RFC 9162 §2.1.1: the largest
+// power of 2 that is strictly less than n. n must be > 1.
+function _ctLargestPowerOf2LessThan(n) {
+  if (n < 2) {
+    throw new TlsTrustError("tls/ct-bad-tree-size",
+      "ct: largest-power-of-2-less-than requires n >= 2 (got " + n + ")");
+  }
+  var k = 1;
+  while ((k << 1) < n) k = k << 1;
+  return k;
+}
+
+// _ctVerifyInclusion — RFC 9162 §2.1.3 algorithm. Walks the audit path
+// from the leaf hash up to the tree's expected root using the supplied
+// audit path siblings. The leafIndex (0-based) selects which side at
+// each level the leaf sits on; the audit path provides the sibling
+// hash for that level.
+//
+//   args:
+//     leafHash:    Buffer (32 bytes) — MTH({d}) of the leaf
+//     leafIndex:   integer 0 <= idx < treeSize
+//     treeSize:    integer >= 1
+//     auditPath:   Array of Buffer (each 32 bytes) — siblings bottom-up
+//
+//   returns: Buffer (32 bytes) — computed root hash to compare
+//   throws:  TlsTrustError on shape errors
+function _ctVerifyInclusionPath(leafHash, leafIndex, treeSize, auditPath) {
+  if (!Buffer.isBuffer(leafHash) || leafHash.length !== 32) {                    // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+    throw new TlsTrustError("tls/ct-bad-leaf-hash",
+      "ct.verifyInclusion: leafHash must be a 32-byte Buffer");
+  }
+  if (typeof leafIndex !== "number" || leafIndex < 0 || leafIndex >= treeSize ||
+      Math.floor(leafIndex) !== leafIndex) {
+    throw new TlsTrustError("tls/ct-bad-index",
+      "ct.verifyInclusion: leafIndex must be an integer 0..treeSize-1");
+  }
+  if (typeof treeSize !== "number" || treeSize < 1 || Math.floor(treeSize) !== treeSize) {
+    throw new TlsTrustError("tls/ct-bad-tree-size",
+      "ct.verifyInclusion: treeSize must be a positive integer");
+  }
+  if (!Array.isArray(auditPath)) {
+    throw new TlsTrustError("tls/ct-bad-audit-path",
+      "ct.verifyInclusion: auditPath must be an array of 32-byte Buffers");
+  }
+
+  // Per RFC 9162 §2.1.3 — climb the tree using the audit path. fn=leafIndex,
+  // sn=treeSize-1 (last index in the tree at this level). Pop one
+  // sibling from the audit path per level.
+  var fn = leafIndex;
+  var sn = treeSize - 1;
+  var r = leafHash;
+  var pathPos = 0;
+  while (sn > 0) {
+    if (pathPos >= auditPath.length) {
+      throw new TlsTrustError("tls/ct-audit-path-short",
+        "ct.verifyInclusion: audit path exhausted before tree root reached");
+    }
+    var sibling = auditPath[pathPos++];
+    if (!Buffer.isBuffer(sibling) || sibling.length !== 32) {                    // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+      throw new TlsTrustError("tls/ct-bad-audit-path",
+        "ct.verifyInclusion: audit path entry " + (pathPos - 1) + " is not a 32-byte Buffer");
+    }
+    if ((fn & 1) === 1 || fn === sn) {
+      r = _ctInnerHashFinal(sibling, r);
+      // Right-side leaf — climb until we hit a left-side ancestor.
+      while ((fn & 1) === 0 && fn !== 0) { fn >>>= 1; sn >>>= 1; }
+    } else {
+      r = _ctInnerHashFinal(r, sibling);
+    }
+    fn >>>= 1;
+    sn >>>= 1;
+  }
+  if (pathPos !== auditPath.length) {
+    throw new TlsTrustError("tls/ct-audit-path-long",
+      "ct.verifyInclusion: audit path has " + (auditPath.length - pathPos) +
+      " trailing entries beyond the root");
+  }
+  return r;
+}
+
+// _ctVerifyConsistency — RFC 9162 §2.1.4 consistency proof verification.
+// Given a first STH (size m) and a second STH (size n, n >= m), the
+// consistency proof shows the second tree contains the first tree as a
+// prefix. Returns the computed roots (oldRoot, newRoot) so the caller
+// can compare against the operator-supplied STHs.
+function _ctVerifyConsistencyPath(m, n, consistencyProof, firstHash) {
+  if (typeof m !== "number" || m < 1 || Math.floor(m) !== m) {
+    throw new TlsTrustError("tls/ct-bad-first-size",
+      "ct.verifyConsistency: m (first tree size) must be a positive integer");
+  }
+  if (typeof n !== "number" || n < m || Math.floor(n) !== n) {
+    throw new TlsTrustError("tls/ct-bad-second-size",
+      "ct.verifyConsistency: n (second tree size) must be an integer >= m");
+  }
+  if (!Buffer.isBuffer(firstHash) || firstHash.length !== 32) {                  // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+    throw new TlsTrustError("tls/ct-bad-first-hash",
+      "ct.verifyConsistency: firstHash must be a 32-byte Buffer");
+  }
+  if (!Array.isArray(consistencyProof)) {
+    throw new TlsTrustError("tls/ct-bad-consistency-proof",
+      "ct.verifyConsistency: consistencyProof must be an array of Buffers");
+  }
+  // RFC 9162 §2.1.4.2 — algorithm is the same as the inclusion-proof
+  // walk, with the leaf-index seeded at the first-tree size minus 1 and
+  // the special case for m being a complete subtree.
+  var path = consistencyProof.slice();
+  var node;
+  var fn = m - 1;
+  var sn = n - 1;
+  // Walk past the right-side bits — the consistency proof omits the
+  // path while the first tree is a complete subtree of the second.
+  while ((fn & 1) === 1) { fn >>>= 1; sn >>>= 1; }
+
+  if (fn === 0) {
+    // m was a complete subtree — its root is the firstHash itself.
+    node = firstHash;
+  } else {
+    if (path.length === 0) {
+      throw new TlsTrustError("tls/ct-consistency-empty",
+        "ct.verifyConsistency: consistency proof empty but first tree is not a complete subtree");
+    }
+    node = path.shift();
+  }
+  while (sn > 0) {
+    if (path.length === 0) {
+      throw new TlsTrustError("tls/ct-consistency-short",
+        "ct.verifyConsistency: consistency proof exhausted before second-tree root");
+    }
+    var sibling = path.shift();
+    if (!Buffer.isBuffer(sibling) || sibling.length !== 32) {                    // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+      throw new TlsTrustError("tls/ct-bad-consistency-entry",
+        "ct.verifyConsistency: consistency-proof entry is not a 32-byte Buffer");
+    }
+    if ((fn & 1) === 1 || fn === sn) {
+      node = _ctInnerHashFinal(sibling, node);
+      while ((fn & 1) === 0 && fn !== 0) { fn >>>= 1; sn >>>= 1; }
+    } else {
+      node = _ctInnerHashFinal(node, sibling);
+    }
+    fn >>>= 1;
+    sn >>>= 1;
+  }
+  return node;
+}
+
 function _findSctOid(rawDer) {
   // Cheap presence check — used by inspect() before ASN.1 walking.
   // OID 1.3.6.1.4.1.11129.2.4.2 = 06 0A 2B 06 01 04 01 D6 79 02 04 02.
@@ -1726,6 +2072,187 @@ var ct = Object.freeze({
   verifyScts: verifyScts,
   // Operator middleware predicate: refuse a peer cert lacking SCT
   // verification. Composes verifyScts under the hood.
+  // verifyInclusion — RFC 9162 §4.5/§5.1 inclusion-proof verifier.
+  // Composes with inspect() / parseScts() / verifyScts() for the
+  // signature side: an SCT proves a log promised to include the cert,
+  // and verifyInclusion proves that promise was kept (the leaf actually
+  // sits in the published tree).
+  //
+  //   opts: {
+  //     sct:              { logIdHex, timestamp, signedEntryDer? } — from parseScts
+  //     leafCertificate:  Buffer — leaf cert DER (the entry hashed at the leaf)
+  //     leafIndex:        integer — position in the tree (from RFC 9162 §6.7 get-proof-by-hash)
+  //     auditPath:        [Buffer] — the inclusion-proof siblings, bottom-up
+  //     sthFromLog:       { treeSize, rootHash[, sha256RootHash] }
+  //                       — operator fetched the signed tree head from the log
+  //                         (RFC 9162 §6.4 get-sth) and supplies treeSize +
+  //                         rootHash (32-byte Buffer or hex string)
+  //     consistency:      { firstSize, firstRoot, proof } — optional
+  //                       — when provided, also verifies that the supplied
+  //                         STH is consistent with an earlier STH the operator
+  //                         pinned (RFC 9162 §6.5 get-sth-consistency)
+  //   }
+  //
+  //   returns: { valid: bool, reason?: string, computedRoot?: hex,
+  //              consistency?: { ok, computedSecondRoot? } }
+  verifyInclusion: function (opts) {
+    if (!opts || typeof opts !== "object") {
+      return { valid: false, reason: "missing-opts" };
+    }
+    if (!opts.sct || typeof opts.sct !== "object") {
+      return { valid: false, reason: "missing-sct" };
+    }
+    if (!Buffer.isBuffer(opts.leafCertificate)) {
+      return { valid: false, reason: "missing-leaf-certificate" };
+    }
+    if (!opts.sthFromLog || typeof opts.sthFromLog !== "object") {
+      return { valid: false, reason: "missing-sth" };
+    }
+    if (typeof opts.leafIndex !== "number" || !isFinite(opts.leafIndex) ||
+        opts.leafIndex < 0 || Math.floor(opts.leafIndex) !== opts.leafIndex) {
+      return { valid: false, reason: "bad-leaf-index" };
+    }
+    if (!Array.isArray(opts.auditPath)) {
+      return { valid: false, reason: "bad-audit-path" };
+    }
+
+    // Build the leaf bytes per RFC 9162 §4.6 — TimestampedEntry.
+    // entry_type = x509_entry (0); signed_entry = strip-SCT-extension(cert).
+    // Operators may pass a pre-built signedEntryDer when the SCT was
+    // already extracted via parseScts() + the framework has the
+    // pre-issuance cert; otherwise we strip the SCT extension here.
+    var signedEntryDer = opts.sct.signedEntryDer;
+    if (!Buffer.isBuffer(signedEntryDer)) {
+      try { signedEntryDer = _stripSctExtensionFromCert(opts.leafCertificate); }
+      catch (e) {
+        return { valid: false, reason: "strip-failed",
+                 error: (e && e.message) || String(e) };
+      }
+    }
+
+    // RFC 9162 §4.6 MerkleTreeLeaf — version (1) + leaf_type (0) +
+    // timestamp (uint64) + entry_type (uint16) + signed_entry (variable-
+    // length cert DER with 24-bit length prefix) + extensions (variable-
+    // length, 16-bit length prefix, empty for x509_entry).
+    var ts = opts.sct.timestamp;
+    if (typeof ts !== "number" && typeof ts !== "bigint") {
+      return { valid: false, reason: "bad-sct-timestamp" };
+    }
+    var tsBuf = Buffer.alloc(8);                                                 // allow:raw-byte-literal — TLS uint64 width
+    var tsBig = typeof ts === "bigint" ? ts : BigInt(Math.floor(ts));
+    tsBuf.writeBigUInt64BE(tsBig);
+    var entryTypeBuf = Buffer.from([0x00, 0x00]);
+    var lenBuf = Buffer.alloc(3);                                                // allow:raw-byte-literal — TLS uint24 length prefix
+    lenBuf.writeUIntBE(signedEntryDer.length, 0, 3);
+    var extensionsBuf = Buffer.from([0x00, 0x00]);                               // allow:raw-byte-literal — empty extensions vector
+    var leafBytes = Buffer.concat([
+      Buffer.from([0x00]),                                                       // version v1
+      Buffer.from([0x00]),                                                       // leaf_type timestamped_entry
+      tsBuf,
+      entryTypeBuf,
+      lenBuf, signedEntryDer,
+      extensionsBuf,
+    ]);
+
+    var leafHash = _ctLeafHash(leafBytes);
+    var computedRoot;
+    try {
+      computedRoot = _ctVerifyInclusionPath(leafHash, opts.leafIndex,
+        opts.sthFromLog.treeSize, opts.auditPath);
+    } catch (e) {
+      return { valid: false, reason: "inclusion-walk-failed",
+               error: (e && e.message) || String(e) };
+    }
+
+    // sthFromLog.rootHash may be a Buffer or hex string.
+    var sthRoot = opts.sthFromLog.rootHash || opts.sthFromLog.sha256RootHash;
+    if (typeof sthRoot === "string") {
+      try { sthRoot = Buffer.from(sthRoot, "hex"); }
+      catch (_e) { return { valid: false, reason: "bad-sth-root-encoding" }; }
+    }
+    if (!Buffer.isBuffer(sthRoot) || sthRoot.length !== 32) {                    // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+      return { valid: false, reason: "bad-sth-root" };
+    }
+    if (!blamejsCrypto.timingSafeEqual(computedRoot, sthRoot)) {
+      return { valid: false, reason: "root-mismatch",
+               computedRoot: computedRoot.toString("hex") };
+    }
+
+    // Optional consistency proof — RFC 9162 §2.1.4.
+    var consistencyResult = null;
+    if (opts.consistency && typeof opts.consistency === "object") {
+      var firstRoot = opts.consistency.firstRoot;
+      if (typeof firstRoot === "string") {
+        try { firstRoot = Buffer.from(firstRoot, "hex"); }
+        catch (_e) {
+          return { valid: false, reason: "bad-consistency-first-root-encoding" };
+        }
+      }
+      try {
+        var computedSecond = _ctVerifyConsistencyPath(
+          opts.consistency.firstSize, opts.sthFromLog.treeSize,
+          opts.consistency.proof || [], firstRoot);
+        var ok = blamejsCrypto.timingSafeEqual(computedSecond, sthRoot);
+        consistencyResult = {
+          ok: ok,
+          computedSecondRoot: computedSecond.toString("hex"),
+        };
+        if (!ok) {
+          return { valid: false, reason: "consistency-mismatch",
+                   computedRoot: computedRoot.toString("hex"),
+                   consistency: consistencyResult };
+        }
+      } catch (e) {
+        return { valid: false, reason: "consistency-walk-failed",
+                 error: (e && e.message) || String(e) };
+      }
+    }
+
+    return {
+      valid:        true,
+      computedRoot: computedRoot.toString("hex"),
+      leafHash:     leafHash.toString("hex"),
+      consistency:  consistencyResult,
+    };
+  },
+  // verifyConsistency — standalone RFC 9162 §2.1.4 consistency-proof
+  // verifier. Operators pinning historical tree-head fingerprints call
+  // this whenever they fetch a fresh STH to confirm the log hasn't
+  // forked. Returns { valid, computedRoot } / { valid:false, reason }.
+  verifyConsistency: function (opts) {
+    if (!opts || typeof opts !== "object") {
+      return { valid: false, reason: "missing-opts" };
+    }
+    var firstRoot = opts.firstRoot;
+    if (typeof firstRoot === "string") {
+      try { firstRoot = Buffer.from(firstRoot, "hex"); }
+      catch (_e) { return { valid: false, reason: "bad-first-root-encoding" }; }
+    }
+    var secondRoot = opts.secondRoot;
+    if (typeof secondRoot === "string") {
+      try { secondRoot = Buffer.from(secondRoot, "hex"); }
+      catch (_e) { return { valid: false, reason: "bad-second-root-encoding" }; }
+    }
+    if (!Buffer.isBuffer(firstRoot) || firstRoot.length !== 32) {                // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+      return { valid: false, reason: "bad-first-root" };
+    }
+    if (!Buffer.isBuffer(secondRoot) || secondRoot.length !== 32) {              // allow:raw-byte-literal — RFC 9162 SHA-256 digest length
+      return { valid: false, reason: "bad-second-root" };
+    }
+    var computed;
+    try {
+      computed = _ctVerifyConsistencyPath(opts.firstSize, opts.secondSize,
+        opts.proof || [], firstRoot);
+    } catch (e) {
+      return { valid: false, reason: "consistency-walk-failed",
+               error: (e && e.message) || String(e) };
+    }
+    if (!blamejsCrypto.timingSafeEqual(computed, secondRoot)) {
+      return { valid: false, reason: "root-mismatch",
+               computedRoot: computed.toString("hex") };
+    }
+    return { valid: true, computedRoot: computed.toString("hex") };
+  },
   requireScts: function (opts) {
     opts = opts || {};
     return function (peerCert) {
@@ -1766,10 +2293,13 @@ module.exports = {
   captureBaselineFingerprints: captureBaselineFingerprints,
   detectBaselineDrift: detectBaselineDrift,
   applyToContext:      applyToContext,
+  buildOptions:        buildOptions,
   getCaPems:           getCaPems,
   ocsp:                ocsp,
   ct:                  ct,
   pqc:                 pqc,
+  preferredGroups:     preferredGroups,
   TlsTrustError:       TlsTrustError,
+  NetworkTlsError:     NetworkTlsError,
   _resetForTest:       _resetForTest,
 };