@blamejs/core 0.8.39 → 0.8.41

package/lib/crypto.js

@@ -91,6 +91,19 @@ function hmacSha3(key, data) { return hmac(key, data, "sha3-512"); }
 // ---- KDF ----
 function kdf(input, outputLength) { return hash(input, "shake256", outputLength); }
 
+// _suiteFixedInfo — NIST SP 800-56C r2 §4.1 OtherInfo / RFC 9180
+// (HPKE) §5.1 suite_id binding. Returns the byte string that the KDF
+// MUST absorb alongside the shared-secret(s) so a key derived under
+// one suite is not silently usable under a different suite. Same
+// label is recovered on decrypt by re-reading the envelope-prefix
+// bytes (kemId / cipherId / kdfId).
+function _suiteFixedInfo(kemId, cipherId, kdfId) {
+  return Buffer.concat([
+    Buffer.from(C.ENVELOPE_FIXED_INFO_LABEL, "utf8"),
+    Buffer.from([0x00, kemId, cipherId, kdfId, 0x00]),
+  ]);
+}
+
 // ---- Random ----
 function generateBytes(byteLength) { return Buffer.from(random(byteLength)); }
 function generateToken(byteLength) { return random(byteLength || 32).toString("hex"); }
@@ -206,28 +219,38 @@ function encrypt(plaintext, publicKeys) {
     privateKey: nodeCrypto.createPrivateKey(ephEc.privateKey),
     publicKey:  nodeCrypto.createPublicKey(ecPubPem),
   });
-  var key = kdf(Buffer.concat([kem.sharedKey, ecSs]), C.BYTES.bytes(32));
+  var key = kdf(Buffer.concat([kem.sharedKey, ecSs,
+    _suiteFixedInfo(C.ACTIVE.KEM, C.ACTIVE.CIPHER, C.ACTIVE.KDF)]),
+    C.BYTES.bytes(32));
   var nonce = generateBytes(C.BYTES.bytes(24));
-  var ct = xchacha20poly1305(key, nonce).encrypt(Buffer.from(plaintext, "utf8"));
+  // Bind the 4-byte envelope header (MAGIC + kemId + cipherId + kdfId)
+  // as AAD so a tampered header (algorithm-substitution attack) fails
+  // the Poly1305 tag.
+  var headerAad = Buffer.from([C.ENVELOPE_MAGIC, C.ACTIVE.KEM, C.ACTIVE.CIPHER, C.ACTIVE.KDF]);
+  var ct = xchacha20poly1305(key, nonce, headerAad).encrypt(Buffer.from(plaintext, "utf8"));
 
   var kemCtLen = Buffer.alloc(2); kemCtLen.writeUInt16BE(kem.ciphertext.length);
   var ecEphDer = ephEc.publicKey;
   var ecEphLen = Buffer.alloc(2); ecEphLen.writeUInt16BE(ecEphDer.length);
 
   return Buffer.concat([
-    Buffer.from([C.ENVELOPE_MAGIC, C.ACTIVE.KEM, C.ACTIVE.CIPHER, C.ACTIVE.KDF]),
+    headerAad,
     kemCtLen, kem.ciphertext, ecEphLen, ecEphDer, nonce, Buffer.from(ct),
   ]).toString("base64");
 }
 
 function encryptMlkemOnly(plaintext, publicKeyPem) {
   var kem = nodeCrypto.encapsulate(nodeCrypto.createPublicKey(publicKeyPem));
-  var key = kdf(kem.sharedKey, C.BYTES.bytes(32));
+  var key = kdf(Buffer.concat([kem.sharedKey,
+    _suiteFixedInfo(C.KEM_IDS.ML_KEM_1024, C.ACTIVE.CIPHER, C.ACTIVE.KDF)]),
+    C.BYTES.bytes(32));
   var nonce = generateBytes(C.BYTES.bytes(24));
-  var ct = xchacha20poly1305(key, nonce).encrypt(Buffer.from(plaintext, "utf8"));
+  var headerAad = Buffer.from([C.ENVELOPE_MAGIC, C.KEM_IDS.ML_KEM_1024,
+    C.ACTIVE.CIPHER, C.ACTIVE.KDF]);
+  var ct = xchacha20poly1305(key, nonce, headerAad).encrypt(Buffer.from(plaintext, "utf8"));
   var kemCtLen = Buffer.alloc(2); kemCtLen.writeUInt16BE(kem.ciphertext.length);
   return Buffer.concat([
-    Buffer.from([C.ENVELOPE_MAGIC, C.KEM_IDS.ML_KEM_1024, C.ACTIVE.CIPHER, C.ACTIVE.KDF]),
+    headerAad,
     kemCtLen, kem.ciphertext, nonce, Buffer.from(ct),
   ]).toString("base64");
 }
@@ -235,6 +258,10 @@ function encryptMlkemOnly(plaintext, publicKeyPem) {
 // ---- Envelope decrypt (dispatches on envelope IDs, supports both KEM IDs) ----
 function decrypt(ciphertext, privateKeys) {
   var packed = Buffer.from(ciphertext, "base64");
+  if (packed[0] === 0xE1) {                                                       // allow:raw-byte-literal — legacy envelope magic
+    throw new Error("Invalid envelope: legacy 0xE1 format predates the FixedInfo " +
+      "KDF binding (NIST SP 800-56C r2 §4.1) — re-seal data under the current envelope");
+  }
   if (packed[0] !== C.ENVELOPE_MAGIC) {
     throw new Error("Invalid envelope: unsupported format");
   }
@@ -269,9 +296,11 @@ function decryptEnvelope(packed, privateKeys) {
       privateKey: nodeCrypto.createPrivateKey(ecPrivPem),
       publicKey:  nodeCrypto.createPublicKey({ key: ecEphDer, type: "spki", format: "der" }),
     });
-    symmetricKey = kdf(Buffer.concat([mlkemSs, ecSs]), C.BYTES.bytes(32));
+    symmetricKey = kdf(Buffer.concat([mlkemSs, ecSs,
+      _suiteFixedInfo(kemId, cipherId, kdfId)]), C.BYTES.bytes(32));
   } else if (kemId === C.KEM_IDS.ML_KEM_1024) {
-    symmetricKey = kdf(mlkemSs, C.BYTES.bytes(32));
+    symmetricKey = kdf(Buffer.concat([mlkemSs,
+      _suiteFixedInfo(kemId, cipherId, kdfId)]), C.BYTES.bytes(32));
   } else if (kemId === C.KEM_IDS.ML_KEM_768_X25519) {
     // ML-KEM-768 + X25519 hybrid envelope. The mlkemPriv must be an
     // ML-KEM-768 key (not 1024); operators are responsible for passing
@@ -286,14 +315,19 @@ function decryptEnvelope(packed, privateKeys) {
       privateKey: nodeCrypto.createPrivateKey(x25519PrivPem),
       publicKey:  nodeCrypto.createPublicKey({ key: x25519EphDer, type: "spki", format: "der" }),
     });
-    symmetricKey = kdf(Buffer.concat([mlkemSs, x25519Ss]), C.BYTES.bytes(32));
+    symmetricKey = kdf(Buffer.concat([mlkemSs, x25519Ss,
+      _suiteFixedInfo(kemId, cipherId, kdfId)]), C.BYTES.bytes(32));
   } else {
     throw new Error("Invalid envelope: unsupported KEM ID " + kemId);
   }
 
   var nonce = packed.subarray(pos, pos + C.BYTES.bytes(24)); pos += C.BYTES.bytes(24);
+  // Re-derive the 4-byte envelope-header AAD from the bytes we just
+  // dispatched on. A tampered header (algorithm-substitution attack)
+  // surfaces here as a Poly1305 tag verification failure.
+  var headerAad = packed.subarray(0, 4);                                          // allow:raw-byte-literal — envelope-header byte slice
   return Buffer.from(
-    xchacha20poly1305(symmetricKey, nonce).decrypt(packed.subarray(pos))
+    xchacha20poly1305(symmetricKey, nonce, headerAad).decrypt(packed.subarray(pos))
   ).toString("utf8");
 }
 
@@ -375,17 +409,20 @@ function encryptMlkem768X25519(plaintext, recipient) {
     privateKey: nodeCrypto.createPrivateKey(ephX25519.privateKey),
     publicKey:  nodeCrypto.createPublicKey(recipient.x25519PublicKey),
   });
-  var key = kdf(Buffer.concat([kem.sharedKey, x25519Ss]), C.BYTES.bytes(32));
+  var key = kdf(Buffer.concat([kem.sharedKey, x25519Ss,
+    _suiteFixedInfo(C.KEM_IDS.ML_KEM_768_X25519, C.ACTIVE.CIPHER, C.ACTIVE.KDF)]),
+    C.BYTES.bytes(32));
   var nonce = generateBytes(C.BYTES.bytes(24));
-  var ct = xchacha20poly1305(key, nonce).encrypt(Buffer.from(plaintext, "utf8"));
+  var headerAad = Buffer.from([C.ENVELOPE_MAGIC, C.KEM_IDS.ML_KEM_768_X25519,
+    C.ACTIVE.CIPHER, C.ACTIVE.KDF]);
+  var ct = xchacha20poly1305(key, nonce, headerAad).encrypt(Buffer.from(plaintext, "utf8"));
 
   var kemCtLen = Buffer.alloc(2); kemCtLen.writeUInt16BE(kem.ciphertext.length);
   var x25519EphDer = ephX25519.publicKey;
   var x25519EphLen = Buffer.alloc(2); x25519EphLen.writeUInt16BE(x25519EphDer.length);
 
   return Buffer.concat([
-    Buffer.from([C.ENVELOPE_MAGIC, C.KEM_IDS.ML_KEM_768_X25519,
-                 C.ACTIVE.CIPHER, C.ACTIVE.KDF]),
+    headerAad,
     kemCtLen, kem.ciphertext, x25519EphLen, x25519EphDer, nonce, Buffer.from(ct),
   ]).toString("base64");
 }

package/lib/honeytoken.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * b.honeytoken — canary credential framework. Generates decoy values
+ * (fake api-key shapes, fake admin URLs, fake DB row references) that
+ * are NEVER handed to a real client; their presence in a request,
+ * log, or DB lookup means an attacker found something they shouldn't
+ * have. The framework registers each token at issuance and refuses
+ * silently in production but always emits a `honeytoken.tripped`
+ * audit row on any positive lookup.
+ *
+ *   var honey = b.honeytoken.create({ audit: b.audit });
+ *
+ *   var token = honey.issue({
+ *     kind:     "apiKey",
+ *     metadata: { plantedAt: "GET /admin/keys/404", linkedTo: "u_42" },
+ *   });
+ *   // → { value: "bk_canary_8f3a7b2e0c…", id: "ht_<hex>" }
+ *
+ *   if (honey.lookup(req.headers["x-api-key"])) {
+ *     // attacker is using the canary; tripped event already audited
+ *     return res.status(403).end();
+ *   }
+ *
+ * Canary value shapes (`kind`):
+ *   - "apiKey"   → `bk_canary_<32 hex>` (matches b.apiKey shape)
+ *   - "session"  → `bks_canary_<48 hex>` (matches b.session shape)
+ *   - "url"      → `/admin/canary-<32 hex>` (planted as a clickable link)
+ *   - "rowId"    → `ht_canary_<32 hex>` (planted as a fake foreign key)
+ *
+ * Audit shape:
+ *   - `honeytoken.issued` — outcome=success; metadata: { id, kind }
+ *   - `honeytoken.tripped` — outcome=failure; metadata: { id, kind,
+ *     metadata, observedAt, observedActor }
+ */
+
+var crypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var HoneytokenError = defineClass("HoneytokenError", { alwaysPermanent: true });
+
+var KINDS = Object.freeze({
+  apiKey:  function () { return "bk_canary_"  + crypto.generateToken(16); },     // allow:raw-byte-literal — 16-byte (128-bit) canary entropy
+  session: function () { return "bks_canary_" + crypto.generateToken(24); },     // allow:raw-byte-literal — 24-byte (192-bit) canary entropy
+  url:     function () { return "/admin/canary-" + crypto.generateToken(16); },  // allow:raw-byte-literal — 16-byte canary entropy
+  rowId:   function () { return "ht_canary_"  + crypto.generateToken(16); },     // allow:raw-byte-literal — 16-byte canary entropy
+});
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["audit"], "honeytoken.create");
+
+  var registry = new Map();   // value → { id, kind, metadata, issuedAt }
+
+  function issue(spec) {
+    spec = spec || {};
+    validateOpts(spec, ["kind", "metadata"], "honeytoken.issue");
+    var kind = spec.kind;
+    if (typeof KINDS[kind] !== "function") {
+      throw new HoneytokenError(
+        "honeytoken/unknown-kind",
+        "honeytoken.issue: unknown kind '" + kind + "' " +
+        "(supported: " + Object.keys(KINDS).join(", ") + ")");
+    }
+    var value = KINDS[kind]();
+    var id = "ht_" + crypto.generateToken(8);                                    // allow:raw-byte-literal — 8-byte registry id
+    var record = Object.freeze({
+      id:        id,
+      kind:      kind,
+      metadata:  spec.metadata || null,
+      issuedAt:  Date.now(),
+    });
+    registry.set(value, record);
+    try {
+      audit().safeEmit({
+        action: "honeytoken.issued",
+        outcome: "success",
+        metadata: { id: id, kind: kind },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    return { id: id, value: value };
+  }
+
+  function lookup(value, observedActor) {
+    if (typeof value !== "string" || value.length === 0) return null;
+    var record = registry.get(value);
+    if (!record) return null;
+    try {
+      audit().safeEmit({
+        action: "honeytoken.tripped",
+        outcome: "failure",
+        metadata: {
+          id:             record.id,
+          kind:           record.kind,
+          metadata:       record.metadata,
+          observedAt:     Date.now(),
+          observedActor:  observedActor || null,
+        },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    return record;
+  }
+
+  function revoke(id) {
+    var found = false;
+    registry.forEach(function (record, value) {
+      if (record.id === id) {
+        registry.delete(value);
+        found = true;
+      }
+    });
+    return found;
+  }
+
+  function size() { return registry.size; }
+
+  return {
+    issue:   issue,
+    lookup:  lookup,
+    revoke:  revoke,
+    size:    size,
+  };
+}
+
+module.exports = {
+  create:           create,
+  KINDS:            Object.freeze(Object.keys(KINDS)),
+  HoneytokenError:  HoneytokenError,
+};

package/lib/mail-auth.js

@@ -565,7 +565,11 @@ async function arcVerify(rfc822, opts) {
     var value = line.slice(colonAt + 1).trim();
     if (name !== "arc-seal" && name !== "arc-message-signature" &&
         name !== "arc-authentication-results") continue;
-    var iMatch = value.match(/(?:^|[;,\s])i=(\d+)/);                             // allow:regex-no-length-cap — header bounded by RFC 5322 998
+    // ARC hop instance per RFC 8617 §4.2.1 — bounded to 3 digits; the
+    // spec doesn't define a hard ceiling but operational use never
+    // exceeds 50 hops, and a 999-hop limit prevents pathological
+    // header values from chewing the verifier.
+    var iMatch = value.match(/(?:^|[;,\s])i=(\d{1,3})\b/);
     var inst = iMatch ? parseInt(iMatch[1], 10) : null;
     if (inst === null || !isFinite(inst) || inst < 1) continue;
     if (inst > maxInstanceSeen) maxInstanceSeen = inst;
@@ -1126,9 +1130,17 @@ function authResultsEmit(opts) {
     var propKeys = Object.keys(props);
     for (var pk = 0; pk < propKeys.length; pk += 1) {
       var k = propKeys[pk];
-      if (typeof r[k] === "string" && r[k].length > 0 && !/[\r\n\0;]/.test(r[k])) {
-        clause += " " + props[k] + "=" + r[k];
-      }
+      var rv = r[k];
+      if (typeof rv !== "string" || rv.length === 0) continue;
+      // pvalue ABNF per RFC 8601 §2.3:
+      //   pvalue = [CFWS] ((value / dot-atom-text) [CFWS]) /
+      //            (local-part "@" domain) [CFWS]
+      // For framework emit we require the printable-ASCII subset of
+      // dot-atom-text + local-part-at-domain shapes; CRLF / NUL /
+      // semicolon / SP / HTAB / quoting metacharacters are refused
+      // (operator-supplied value is structured, not free-form).
+      if (!/^[A-Za-z0-9._@\-:[\]]+$/.test(rv)) continue;                            // allow:regex-no-length-cap — bounded by header line cap
+      clause += " " + props[k] + "=" + rv;
     }
     clauses.push(clause);
   }

package/lib/middleware/csp-report.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * b.middleware.cspReport — Reporting-API endpoint for CSP / COEP /
+ * COOP / Permissions-Policy violations.
+ *
+ * The framework's default CSP appends `report-to default;` (see
+ * lib/middleware/security-headers.js); operators wire the matching
+ * `Reporting-Endpoints: default="https://app.example.com/csp-report"`
+ * header — and mount this middleware at the configured path. Browsers
+ * POST batches of violations as `application/reports+json`.
+ *
+ *   var cspReport = b.middleware.cspReport.create({
+ *     audit:     b.audit,
+ *     onReport:  function (report) { metrics.count("csp.violation", 1, { directive: report.body.effectiveDirective }); },
+ *     maxBytes:  C.BYTES.kib(64),
+ *   });
+ *   router.post("/csp-report", cspReport);
+ *
+ * Audit shape: `csp.violation` (failure) per report; metadata carries
+ * the report.body fields (blockedURL, documentURL, effectiveDirective,
+ * sample, statusCode). Sample is truncated to 200 chars.
+ *
+ * Validation:
+ *   - Refuses non-POST methods with 405
+ *   - Refuses bodies > maxBytes (default 64 KiB) with 413
+ *   - Refuses non-JSON bodies with 400
+ *   - Accepts `application/reports+json` AND legacy `application/csp-report`
+ */
+
+var C = require("../constants");
+var lazyRequire = require("../lazy-require");
+var safeBuffer = require("../safe-buffer");
+var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var DEFAULT_MAX_BYTES = C.BYTES.kib(64);
+var SAMPLE_TRUNCATE = 200;
+
+function _truncate(value) {
+  if (typeof value !== "string") return value;
+  if (value.length <= SAMPLE_TRUNCATE) return value;
+  return value.slice(0, SAMPLE_TRUNCATE) + "…";
+}
+
+function _normalizeOne(reportLike) {
+  // Reporting API shape: { type, age, url, user_agent, body: {...} }
+  // Legacy CSP shape:    { "csp-report": { ... } }
+  if (!reportLike || typeof reportLike !== "object") return null;
+  if (reportLike["csp-report"] && typeof reportLike["csp-report"] === "object") {
+    var legacy = reportLike["csp-report"];
+    return {
+      type: "csp-violation",
+      url:  legacy["document-uri"] || null,
+      body: {
+        documentURL:        legacy["document-uri"] || null,
+        blockedURL:         legacy["blocked-uri"] || null,
+        effectiveDirective: legacy["effective-directive"] || legacy["violated-directive"] || null,
+        statusCode:         legacy["status-code"] || null,
+        sample:             _truncate(legacy["script-sample"] || ""),
+        sourceFile:         legacy["source-file"] || null,
+        lineNumber:         legacy["line-number"] || null,
+      },
+    };
+  }
+  if (reportLike.type && reportLike.body && typeof reportLike.body === "object") {
+    return {
+      type: reportLike.type,
+      url:  reportLike.url || null,
+      body: {
+        documentURL:        reportLike.body.documentURL || null,
+        blockedURL:         reportLike.body.blockedURL || null,
+        effectiveDirective: reportLike.body.effectiveDirective || null,
+        statusCode:         reportLike.body.statusCode || null,
+        sample:             _truncate(reportLike.body.sample || ""),
+        sourceFile:         reportLike.body.sourceFile || null,
+        lineNumber:         reportLike.body.lineNumber || null,
+      },
+    };
+  }
+  return null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["audit", "onReport", "maxBytes"], "middleware.cspReport");
+  var maxBytes = (typeof opts.maxBytes === "number" && isFinite(opts.maxBytes) && opts.maxBytes > 0)
+    ? opts.maxBytes : DEFAULT_MAX_BYTES;
+  var onReport = (typeof opts.onReport === "function") ? opts.onReport : null;
+
+  return async function cspReport(req, res, _next) {
+    if (req.method !== "POST") {
+      res.writeHead(405, { "Allow": "POST" });                                     // allow:raw-byte-literal — HTTP 405 status
+      res.end();
+      return;
+    }
+    var body;
+    try {
+      body = await safeBuffer.boundedChunkCollector(req, { maxBytes: maxBytes });
+    } catch (_e) {
+      res.writeHead(413);                                                         // allow:raw-byte-literal — HTTP 413 status
+      res.end();
+      return;
+    }
+    var parsed;
+    try { parsed = safeJson.parse(body.toString("utf8")); }
+    catch (_e) {
+      res.writeHead(400);                                                         // allow:raw-byte-literal — HTTP 400 status
+      res.end();
+      return;
+    }
+    var reports = Array.isArray(parsed) ? parsed : [parsed];
+    for (var i = 0; i < reports.length; i++) {
+      var normalized = _normalizeOne(reports[i]);
+      if (!normalized) continue;
+      try {
+        audit().safeEmit({
+          action:  "csp.violation",
+          outcome: "failure",
+          metadata: Object.assign({ type: normalized.type, url: normalized.url }, normalized.body),
+        });
+      } catch (_e) { /* audit best-effort */ }
+      if (onReport) {
+        try { onReport(normalized); } catch (_e) { /* hook best-effort */ }
+      }
+    }
+    res.writeHead(204);                                                           // allow:raw-byte-literal — HTTP 204 status
+    res.end();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/index.js

@@ -32,6 +32,7 @@ var cookies = require("./cookies");
 var cors = require("./cors");
 var dailyByteQuota = require("./daily-byte-quota");
 var cspNonce = require("./csp-nonce");
+var cspReport = require("./csp-report");
 var csrfProtect = require("./csrf-protect");
 var dbRoleFor = require("./db-role-for");
 var dpop = require("./dpop");
@@ -88,6 +89,7 @@ module.exports = {
   compression:      compression.create,
   cookies:          cookies.create,
   cspNonce:         cspNonce.create,
+  cspReport:        cspReport.create,
   securityTxt:      securityTxt.create,
   sse:              sse.create,
   requestLog:       requestLog.create,

package/lib/network-smtp-policy.js

@@ -164,13 +164,20 @@ async function mtaStsFetch(domain, opts) {
   return await _getStsCache().wrap(cacheKey, async function () {
     var url = "https://mta-sts." + lcDomain + "/.well-known/mta-sts.txt";
     safeUrl.parse(url, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS });
+    // RFC 8461 §3.3 — the HTTPS cert MUST validate against
+    // mta-sts.<domain> with the standard public-CA chain. We pass
+    // checkServerIdentity:default + rejectUnauthorized:true (the
+    // framework default) and pin servername to the expected host
+    // so a permissive httpClient default can't be flipped on.
     var res;
     try {
       res = await httpClient().request({
-        method:    "GET",
-        url:       url,
-        maxBytes:  MAX_POLICY_BYTES,
-        timeoutMs: C.TIME.seconds(10),
+        method:             "GET",
+        url:                url,
+        maxBytes:           MAX_POLICY_BYTES,
+        timeoutMs:          C.TIME.seconds(10),
+        servername:         "mta-sts." + lcDomain,
+        rejectUnauthorized: true,
       });
     } catch (_e) {
       return null;

package/lib/network-tls.js

@@ -329,6 +329,67 @@ function captureBaselineFingerprints() {
   STATE.baselineFingerprints = STATE.cas.map(function (e) { return e.meta.fingerprint256; });
 }
 
+// pinsetDriftMonitor — periodic check that emits audit + observability
+// events when the trust-store fingerprint set drifts from the captured
+// baseline. Different intent from expiryMonitor: this fires when a
+// CA is added or removed (by operator config-flip OR by a tampered
+// MANIFEST / vendor refresh), not when an existing one approaches
+// validity expiry.
+//
+//   b.network.tls.captureBaselineFingerprints();   // at boot
+//   var mon = b.network.tls.pinsetDriftMonitor({
+//     intervalMs:  C.TIME.minutes(15),
+//     onDrift:     function (drift) { /* operator hook */ },
+//   });
+//
+// Audit emissions:
+//   network.tls.pinset.drift_check  — every check, ok / warn
+//   network.tls.pinset.drifted      — when added.length || removed.length
+function pinsetDriftMonitor(opts) {
+  opts = opts || {};
+  var intervalMs = opts.intervalMs;
+  var auditOn    = opts.audit !== false;
+  if (typeof intervalMs !== "number" || !isFinite(intervalMs) || intervalMs <= 0) {
+    throw new TlsTrustError("tls/bad-interval",
+      "tls.pinsetDriftMonitor: intervalMs must be a positive finite number");
+  }
+  function _tick() {
+    var drift;
+    try { drift = detectBaselineDrift(); }
+    catch (_e) { return; }
+    if (drift === null) return;   // baseline not captured; nothing to compare
+    if (auditOn) {
+      try {
+        audit().safeEmit({
+          action:  "network.tls.pinset.drift_check",
+          outcome: drift.drifted ? "warn" : "ok",
+          metadata: { added: drift.added.length, removed: drift.removed.length },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    if (drift.drifted) {
+      try { observability().safeEvent("network.tls.pinset.drifted", 1, {}); }
+      catch (_e) { /* drop-silent */ }
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "network.tls.pinset.drifted",
+            outcome: "failure",
+            metadata: { added: drift.added, removed: drift.removed },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      if (typeof opts.onDrift === "function") {
+        try { opts.onDrift(drift); } catch (_e) { /* operator hook */ }
+      }
+    }
+  }
+  var handle = safeAsync.repeating(_tick, intervalMs, { name: "tls-pinset-drift-monitor" });
+  return {
+    stop: function () { if (handle) { handle.stop(); handle = null; } },
+  };
+}
+
 function detectBaselineDrift() {
   if (!STATE.baselineFingerprints) return null;
   var current = STATE.cas.map(function (e) { return e.meta.fingerprint256; });
@@ -1589,6 +1650,21 @@ function verifyScts(certDer, opts) {
         error: (e && e.message) || String(e) });
       continue;
     }
+    // RFC 6962 §2.1.4 — log-key SignatureAndHashAlgorithm pair must
+    // match the SCT's signatureAlgorithm. signatureAlgo enum 1=RSA,
+    // 3=ECDSA. Cross-check against the actual log-key type so a
+    // malformed log-keys map can't silently accept SCTs signed
+    // under one algorithm against a key registered under another.
+    var keyType = keyObj.asymmetricKeyType;
+    var sctSigAlgo = sct.signatureAlgo;
+    var algoOk = (sctSigAlgo === 1 && keyType === "rsa") ||                       // allow:raw-byte-literal — TLS 1.2 SignatureAlgorithm rsa
+                 (sctSigAlgo === 3 && (keyType === "ec" || keyType === "ecdsa")); // allow:raw-byte-literal — TLS 1.2 SignatureAlgorithm ecdsa
+    if (!algoOk) {
+      perSctResults.push({ logIdHex: sct.logIdHex, verified: false,
+        reason: "log-key-algo-mismatch",
+        sctSignatureAlgo: sctSigAlgo, logKeyType: keyType });
+      continue;
+    }
     var verified;
     try { verified = nodeCrypto.verify(nodeAlgo, signedEntry, keyObj, sct.signature); }
     catch (e) {
@@ -1683,6 +1759,7 @@ module.exports = {
   purgeExpired:        purgeExpired,
   expiringSoon:        expiringSoon,
   expiryMonitor:       expiryMonitor,
+  pinsetDriftMonitor:  pinsetDriftMonitor,
   useSystemTrust:      useSystemTrust,
   isSystemTrustEnabled: isSystemTrustEnabled,
   getTrustStore:       getTrustStore,

package/lib/pqc-software.js

@@ -57,6 +57,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var bCrypto = require("./crypto");
 var PqcError = defineClass("PqcError", { alwaysPermanent: true });
 
 var _vendoredOnce = null;
@@ -192,4 +193,45 @@ Object.defineProperty(pqc, "DEFAULT_HASH_SIG", {
   get: function () { return _accessor("slh_dsa_shake_256f"); },
 });
 
+// runKnownAnswerTest — round-trip the vendored ML-KEM-1024 against
+// itself with a self-generated keypair. This is NOT the FIPS 203
+// Appendix A KAT vector (those are 800 KB of test data the framework
+// chooses not to vendor); it's a self-consistency check that the
+// vendored bundle's keygen / encapsulate / decapsulate survives a
+// full cycle and produces a 32-byte shared secret. The fallback
+// path becomes load-bearing if Node strips the WebCrypto ML-KEM
+// extension; this gate fails fast at boot rather than mid-request.
+//
+//   var result = b.pqcSoftware.runKnownAnswerTest();
+//   if (!result.ok) throw new Error("PQC KAT failed: " + result.reason);
+function runKnownAnswerTest() {
+  if (!isAvailable()) {
+    return { ok: false, reason: "vendored @noble/post-quantum bundle not loadable" };
+  }
+  try {
+    var kem = _accessor("ml_kem1024");
+    var kp = kem.keygen();
+    var enc = kem.encapsulate(kp.publicKey);
+    var ssAlice = enc.sharedSecret;
+    var ssBob = kem.decapsulate(enc.cipherText, kp.secretKey);
+    if (!ssAlice || !ssBob) {
+      return { ok: false, reason: "keygen/encapsulate/decapsulate returned falsy" };
+    }
+    if (ssAlice.length !== 32 || ssBob.length !== 32) {                            // allow:raw-byte-literal — FIPS 203 §1 K_size = 32 bytes
+      return { ok: false, reason: "shared-secret length mismatch (expected 32 bytes)" };
+    }
+    // Constant-time compare via the framework wrapper. The KAT runs
+    // at boot only, but using the timing-safe path keeps the wider
+    // pattern-detector signal clean.
+    if (!bCrypto.timingSafeEqual(Buffer.from(ssAlice), Buffer.from(ssBob))) {
+      return { ok: false, reason: "shared-secret bytes diverge" };
+    }
+    return { ok: true, sharedSecretLength: ssAlice.length };
+  } catch (e) {
+    return { ok: false, reason: "exception: " + (e && e.message) };
+  }
+}
+
+pqc.runKnownAnswerTest = runKnownAnswerTest;
+
 module.exports = pqc;