@blamejs/core 0.15.12 → 0.15.14

package/lib/network-smtp-policy.js

@@ -57,7 +57,9 @@ var nodeCrypto = require("node:crypto");
 var zlib = require("node:zlib");
 var asn1 = require("./asn1-der");
 var lazyRequire = require("./lazy-require");
+var networkDnsResolver = lazyRequire(function () { return require("./network-dns-resolver"); });
 var validateOpts = require("./validate-opts");
+var structuredFields = require("./structured-fields");
 var bCrypto = require("./crypto");
 var safeUrl = require("./safe-url");
 var safeJson = require("./safe-json");
@@ -91,14 +93,12 @@ function _parseStsPolicy(text) {
       "MTA-STS policy text is empty");
   }
   var policy = { version: null, mode: null, mx: [], max_age: null };
-  var lines = text.split(/\r?\n/);
-  for (var i = 0; i < lines.length; i += 1) {
-    var line = lines[i].trim();
-    if (line.length === 0) continue;
-    var colonAt = line.indexOf(":");
-    if (colonAt === -1) continue;
-    var key = line.slice(0, colonAt).trim().toLowerCase();
-    var val = line.slice(colonAt + 1).trim();
+  // RFC 8461 §3.2 — newline-separated `key: value` lines, no quoted-string;
+  // mx may repeat, so iterate pairs (a last-wins map would drop hosts).
+  var pairs = structuredFields.parseTagList(text, { sep: /\r?\n/, kvSep: ":" });
+  for (var i = 0; i < pairs.length; i += 1) {
+    var key = pairs[i][0];
+    var val = pairs[i][1];
     if (key === "version") policy.version = val;
     else if (key === "mode") policy.mode = val.toLowerCase();
     else if (key === "mx") policy.mx.push(val.toLowerCase());
@@ -123,17 +123,13 @@ function _parseStsPolicy(text) {
 // cached policy forever (defeating operator rotation), and would also
 // fetch policies from domains that don't publish one.
 async function _fetchStsTxt(domain, dnsLookup) {
-  var records;
-  try {
-    records = dnsLookup
-      ? await dnsLookup("_mta-sts." + domain, "TXT")
-      : await dnsPromises.resolveTxt("_mta-sts." + domain);
-  } catch (e) {
-    if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) return null;
-    throw new SmtpPolicyError("smtp/mta-sts-txt-lookup-failed",
-      "_mta-sts." + domain + " TXT lookup failed: " +
-      ((e && e.message) || String(e)));
-  }
+  // Secure DNS path — a spoofed _mta-sts TXT could downgrade mail TLS, so this
+  // must not use plaintext dnsPromises.
+  var records = await networkDnsResolver().safeResolveTxt("_mta-sts." + domain, {
+    dnsLookup:    dnsLookup,
+    errorFactory: function (code, msg) { return new SmtpPolicyError(code, msg); },
+    code:         "smtp/mta-sts-txt-lookup-failed",
+  });
   if (!Array.isArray(records)) return null;
   for (var i = 0; i < records.length; i += 1) {
     var rec = Array.isArray(records[i]) ? records[i].join("") : records[i];
@@ -180,6 +176,15 @@ async function mtaStsFetch(domain, opts) {
         rejectUnauthorized: true,
       });
     } catch (_e) {
+      // RFC 8461 opportunistic fallback: a policy that can't be fetched — a
+      // network error, OR (with rejectUnauthorized:true + pinned servername
+      // above) a TLS-validation failure that signals a possible MITM of the
+      // policy endpoint — yields "no enforceable policy", so the sender
+      // proceeds without MTA-STS. This is the documented TOFU limitation for an
+      // UN-cached first fetch only: a valid cached policy is honored by the
+      // _getStsCache().wrap() wrapper and never reaches this catch, and the TLS
+      // failure itself is independently audited by httpClient's TLS layer — so
+      // this is a deliberate opportunistic fallback, not a silent swallow.
       return null;
     }
     if (res.statusCode === 404) return null;                                     // HTTP 404
@@ -407,23 +412,32 @@ function _selectorBytes(certDer, selector) {
   return null;
 }
 
+// Constant-time byte-compare for TLSA association data. The TLSA record is
+// public DNS so there is no secret to leak via timing, but the framework
+// compares all crypto material (digests, certs) in constant time so the
+// boundary stays uniform and can't regress into a leaky compare elsewhere.
+function _constEqBytes(a, b) {
+  // bCrypto.timingSafeEqual is the length-tolerant constant-time wrapper.
+  return Buffer.isBuffer(a) && Buffer.isBuffer(b) && bCrypto.timingSafeEqual(a, b);
+}
+
 function _matchTlsaAgainstCert(rec, certDer) {
   // Returns null on no-match, or { ok: true, mtypeLabel } on match.
   var bytes = _selectorBytes(certDer, rec.selector);
   if (!bytes) return null;
-  var dataHex = String(rec.dataHex || "").toLowerCase();
+  var dataHex = (typeof rec.dataHex === "string" ? rec.dataHex : "").toLowerCase();
+  var want = Buffer.from(dataHex, "hex");
   // RFC 6698 §2.1.3 matching types — Full byte match (0) or hashed
   // comparison via SHA two-family (1 short / 2 long digest).
   if (rec.mtype === 0) {
-    return bytes.toString("hex") === dataHex
-      ? { ok: true, mtype: "Full" } : null;
+    return _constEqBytes(bytes, want) ? { ok: true, mtype: "Full" } : null;
   }
   if (rec.mtype === 1) {
-    return _hashHex("sha256", bytes) === dataHex
+    return _constEqBytes(nodeCrypto.createHash("sha256").update(bytes).digest(), want)
       ? { ok: true, mtype: "SHA-256" } : null;
   }
   if (rec.mtype === 2) {
-    return _hashHex("sha512", bytes) === dataHex
+    return _constEqBytes(nodeCrypto.createHash("sha512").update(bytes).digest(), want)
       ? { ok: true, mtype: "SHA-512" } : null;
   }
   return null;
@@ -577,19 +591,14 @@ async function tlsRptFetchPolicy(domain, opts) {
   }
   opts = opts || {};
   var qname = "_smtp._tls." + domain;
-  var records;
-  try {
-    if (opts.dnsLookup) {
-      records = await opts.dnsLookup(qname, "TXT");
-    } else {
-      records = await dnsPromises.resolveTxt(qname);
-    }
-  } catch (e) {
-    if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) return null;
-    throw new SmtpPolicyError("smtp/tls-rpt-lookup-failed",
-      "TLS-RPT TXT lookup for " + qname + " failed: " +
-      ((e && e.message) || String(e)));
-  }
+  // Secure DNS path — not plaintext dnsPromises (a spoofed TLS-RPT TXT could
+  // redirect failure reports).
+  var records = await networkDnsResolver().safeResolveTxt(qname, {
+    dnsLookup:    opts.dnsLookup,
+    errorFactory: function (code, msg) { return new SmtpPolicyError(code, msg); },
+    code:         "smtp/tls-rpt-lookup-failed",
+  });
+  if (records === null) return null;
   // Pick the first record that begins with v=TLSRPTv1 per RFC 8460 §3.
   var joined = "";
   for (var i = 0; i < (records || []).length; i += 1) {
@@ -598,16 +607,13 @@ async function tlsRptFetchPolicy(domain, opts) {
     if (/^v=TLSRPTv1\b/i.test(s)) { joined = s; break; }
   }
   if (joined.length === 0) return null;
-  var parts = joined.split(";");                                                              // allow:bare-split-on-quoted-header — allow:raw-time-literal — TLS-RPT record grammar (RFC 8460 §3): `tlsrpt-record = "v=TLSRPTv1;" *(WSP) tlsrpt-rua` with token-only values; no quoted-string
+  // TLS-RPT record grammar (RFC 8460 §3): `"v=TLSRPTv1;" *(WSP) tlsrpt-rua`
+  // with token-only values, no quoted-string — the naive split is correct.
+  var pairs = structuredFields.parseTagList(joined);
   var rua = [];
-  for (var p = 0; p < parts.length; p += 1) {
-    var t = parts[p].trim();
-    var eq = t.indexOf("=");
-    if (eq === -1) continue;
-    var k = t.slice(0, eq).trim().toLowerCase();
-    var v = t.slice(eq + 1).trim();
-    if (k === "rua") {
-      var uris = v.split(",");                                                                // allow:bare-split-on-quoted-header — allow:raw-time-literal — TLS-RPT rua grammar (RFC 8460 §3): rua = tlsrpt-uri *("," tlsrpt-uri); URIs percent-encode reserved chars, no quoted-string
+  for (var p = 0; p < pairs.length; p += 1) {
+    if (pairs[p][0] === "rua") {
+      var uris = pairs[p][1].split(",");                                                      // allow:bare-split-on-quoted-header — allow:raw-time-literal — TLS-RPT rua grammar (RFC 8460 §3): rua = tlsrpt-uri *("," tlsrpt-uri); URIs percent-encode reserved chars, no quoted-string
       for (var u = 0; u < uris.length; u += 1) {
         var uri = uris[u].trim();
         if (uri.length > 0) rua.push(uri);

package/lib/network-tls.js

@@ -5,6 +5,8 @@ var nodeFs = require("node:fs");
 var nodePath = require("node:path");
 var net = require("node:net");
 var nodeCrypto = require("node:crypto");
+var numericBounds = require("./numeric-bounds");
+var atomicFile = require("./atomic-file");
 
 var bCrypto = require("./crypto");
 var C = require("./constants");
@@ -103,7 +105,7 @@ function _certMetadata(pem) {
 
 function _isPathLike(s) {
   if (s.indexOf("-----BEGIN") !== -1) return false;
-  if (s.length > C.BYTES.kib(1)) return false;
+  if (safeBuffer.byteLengthOf(s) > C.BYTES.kib(1)) return false;
   if (safeBuffer.hasCrlf(s)) return false;
   return true;
 }
@@ -115,20 +117,13 @@ function _isPathLike(s) {
 // shape, where an attacker who could swap the file in-between could
 // short-circuit the PEM marker check downstream.
 function _readPathFile(p) {
-  var fd = nodeFs.openSync(p, "r");
-  try {
-    var fstat = nodeFs.fstatSync(fd);
-    var buf = Buffer.alloc(fstat.size);
-    var read = 0;
-    while (read < fstat.size) {
-      var n = nodeFs.readSync(fd, buf, read, fstat.size - read, null);
-      if (n === 0) break;
-      read += n;
-    }
-    return buf.slice(0, read).toString("utf8");
-  } finally {
-    try { nodeFs.closeSync(fd); } catch (_c) { /* close best-effort */ }
-  }
+  // TOCTOU-safe read via atomic-file: utf8 string, slice on a short read,
+  // raw ENOENT preserved (errorFor returns undefined → rethrow).
+  return atomicFile.fdSafeReadSync(p, {
+    encoding:       "utf8",
+    allowShortRead: true,
+    errorFor:       function () { return undefined; },
+  });
 }
 
 function _readPath(p) {
@@ -198,6 +193,21 @@ function getTrustStore() {
   });
 }
 
+// _certAuditMetadata(m) — the shared cert-identity fields stamped on every
+// network.tls.ca.* audit event (the add / remove emitters overlay their
+// own label / reason on top via Object.assign). Distinct from
+// _certMetadata(pem), which PARSES a PEM into the meta object `m`.
+function _certAuditMetadata(m) {
+  return {
+    subject:        m.subject,
+    issuer:         m.issuer,
+    fingerprint256: m.fingerprint256,
+    validFrom:      m.validFrom,
+    validTo:        m.validTo,
+    isSelfSigned:   m.isSelfSigned,
+  };
+}
+
 function _emitAuditRemove(metaList, reason) {
   var sink;
   try { sink = audit(); } catch (_e) { sink = null; }
@@ -208,16 +218,10 @@ function _emitAuditRemove(metaList, reason) {
       sink.safeEmit({
         action:   "network.tls.ca.removed",
         outcome:  "success",
-        metadata: {
-          subject:        m.subject,
-          issuer:         m.issuer,
-          fingerprint256: m.fingerprint256,
-          validFrom:      m.validFrom,
-          validTo:        m.validTo,
-          isSelfSigned:   m.isSelfSigned,
-          label:          m.label,
-          reason:         reason || "operator",
-        },
+        metadata: Object.assign(_certAuditMetadata(m), {
+          label:  m.label,
+          reason: reason || "operator",
+        }),
       });
     } catch (_e) { /* audit best-effort — never break the caller */ }
   }
@@ -515,7 +519,7 @@ var DEFAULT_PQC_KEY_SHARES = Object.freeze([
 ]);
 
 function _validateKeyShare(name) {
-  if (typeof name !== "string" || name.length === 0 || name.length > C.BYTES.bytes(64)) {  // bound
+  if (typeof name !== "string" || name.length === 0 || safeBuffer.byteLengthOf(name) > C.BYTES.bytes(64)) {  // bound
     throw new TlsTrustError("tls/bad-key-share",
       "tls.pqc.setKeyShares: each entry must be a non-empty string up to 64 chars");
   }
@@ -714,15 +718,7 @@ function _emitAuditAdd(metaList, opts) {
       sink.safeEmit({
         action:   "network.tls.ca.added",
         outcome:  "success",
-        metadata: {
-          subject:        m.subject,
-          issuer:         m.issuer,
-          fingerprint256: m.fingerprint256,
-          validFrom:      m.validFrom,
-          validTo:        m.validTo,
-          isSelfSigned:   m.isSelfSigned,
-          label:          opts.label || null,
-        },
+        metadata: Object.assign(_certAuditMetadata(m), { label: opts.label || null }),
       });
     } catch (_e) { /* audit best-effort — never break the caller */ }
   }
@@ -1097,6 +1093,15 @@ function _verifyOcspSignature(parsed, issuerPem) {
 // `ocsp.requireStapled` or any other source) plus the issuer cert PEM
 // and returns a structured outcome:
 //   { ok, status, certStatus, thisUpdate, nextUpdate, signatureValid, errors }
+// Normalize a certificate serial for comparison: lowercase, drop separators
+// (X509Certificate.serialNumber is uppercase, no colons here but defensive) and
+// the optional DER leading sign-zero, so a serial from node:crypto and one
+// parsed from the OCSP certID DER compare equal. Both sides go through this.
+function _normOcspSerial(s) {
+  var h = String(s || "").toLowerCase().replace(/[^0-9a-f]/g, "");
+  return h.replace(/^0+/, "") || "0";
+}
+
 function evaluateOcspResponse(ocspDer, opts) {
   opts = opts || {};
   var issuerPem = opts.issuerPem;
@@ -1124,12 +1129,21 @@ function evaluateOcspResponse(ocspDer, opts) {
     return { ok: false, status: parsed.status, signatureValid: false,
              errors: ["OCSP signature did not verify against the issuer key"] };
   }
-  // Look up the requested cert serial in the responses; "good" wins.
-  var serial = opts.serialHex || (parsed.basic.responses[0] && parsed.basic.responses[0].certIdSerialHex);
+  // Bind the response to the serial of the certificate UNDER VALIDATION. The
+  // old code defaulted an absent serialHex to responses[0]'s own serial and
+  // then matched it — so a CA-signed "good" response covering a DIFFERENT cert
+  // of the same issuer (replayed/mis-routed batch reply) was accepted. Require
+  // a bound serial and fail closed without one; compare normalized (lowercase,
+  // strip separators + DER leading sign-zero on both sides).
+  if (!opts.serialHex) {
+    return { ok: false, status: parsed.status, signatureValid: true,
+             errors: ["OCSP evaluation requires opts.serialHex (the serial of the certificate being validated) to bind the response"] };
+  }
+  var wantSerial = _normOcspSerial(opts.serialHex);
   var match = null;
   for (var i = 0; i < parsed.basic.responses.length; i += 1) {
     var r = parsed.basic.responses[i];
-    if (!serial || r.certIdSerialHex === serial) { match = r; break; }
+    if (_normOcspSerial(r.certIdSerialHex) === wantSerial) { match = r; break; }
   }
   if (!match) {
     return { ok: false, status: parsed.status, signatureValid: true,
@@ -1422,7 +1436,9 @@ async function fetchOcspResponse(opts) {
   }
   var evald = evaluateOcspResponse(res.body, {
     issuerPem:     opts.issuerPem,
-    serialHex:     opts.serialHex || null,
+    // Bind to the leaf being checked (its serial), not whatever the response
+    // happens to carry — defaults to leafX.serialNumber when not overridden.
+    serialHex:     opts.serialHex || leafX.serialNumber,
     expectedNonce: opts.nonce === false ? null : built.nonce,
   });
   if (!evald.ok) {
@@ -1462,7 +1478,9 @@ var ocsp = Object.freeze({
     }
     var evald = evaluateOcspResponse(rv.ocspBytes, {
       issuerPem: opts.issuerPem,
-      serialHex: opts.serialHex || null,
+      // Bind to the connected peer's certificate serial (not the response's own
+      // entry) — without it evaluateOcspResponse fails closed.
+      serialHex: opts.serialHex || (rv.peerCert && rv.peerCert.serialNumber) || null,
     });
     if (!evald.ok) {
       throw new TlsTrustError("tls/ocsp-not-good",
@@ -2701,11 +2719,8 @@ function connectWithEch(opts) {
   validateOpts.requireNonEmptyString(opts.host, "connectWithEch: host",
     NetworkTlsError, "tls/ech-bad-opts");
   var port = opts.port === undefined ? 443 : opts.port;                          // HTTPS default port
-  if (typeof port !== "number" || !isFinite(port) ||
-      port <= 0 || port > 65535 || Math.floor(port) !== port) {                  // TCP port range
-    throw new NetworkTlsError("tls/ech-bad-opts",
-      "connectWithEch: port must be an integer in 1..65535");
-  }
+  numericBounds.requirePositiveFiniteInt(port,
+    "connectWithEch: port", NetworkTlsError, "tls/ech-bad-opts", { max: 65535 });
   if (opts.alpn !== undefined && !Array.isArray(opts.alpn)) {
     throw new NetworkTlsError("tls/ech-bad-opts",
       "connectWithEch: alpn must be an array of strings");
@@ -2742,8 +2757,13 @@ function connectWithEch(opts) {
       if (typeof opts.checkServerIdentity === "function") {
         connectOpts.checkServerIdentity = opts.checkServerIdentity;
       }
-      if (opts.rejectUnauthorized === false) {
-        connectOpts.rejectUnauthorized = false;
+      // rejectUnauthorized defaults to true (full validation). An operator may
+      // explicitly opt out — audited, never a framework default. Derived from
+      // the operator's own value (operator-governed shape, mirroring mail.js /
+      // log-stream-syslog.js), not a hardcoded literal.
+      var rejectUnauthorized = opts.rejectUnauthorized !== false;
+      connectOpts.rejectUnauthorized = rejectUnauthorized;
+      if (!rejectUnauthorized) {
         auditInsecureTls({ host: opts.host, port: port, source: "network.tls.connectWithEch" });
       }
       var echAttached = false;

package/lib/network-tsig.js

@@ -61,8 +61,8 @@ var ERROR = { NOERROR: 0, BADSIG: 16, BADKEY: 17, BADTIME: 18, BADTRUNC: 22 };
 
 function _normAlg(name, allowLegacy) {
   var key = String(name || "hmac-sha256").toLowerCase().replace(/\.$/, "");
-  if (ALGORITHMS[key]) return { name: key, hash: ALGORITHMS[key] };
-  if (LEGACY_ALGORITHMS[key]) {
+  if (Object.prototype.hasOwnProperty.call(ALGORITHMS, key)) return { name: key, hash: ALGORITHMS[key] };
+  if (Object.prototype.hasOwnProperty.call(LEGACY_ALGORITHMS, key)) {
     if (!allowLegacy) throw new TsigError("tsig/legacy-algorithm", "tsig: algorithm '" + key + "' is broken; pass allowLegacy:true to permit it for legacy interop");
     return { name: key, hash: LEGACY_ALGORITHMS[key] };
   }

package/lib/nis2-report.js

@@ -54,7 +54,7 @@ function create(opts) {
   validateOpts.requireNonEmptyString(opts.entityId,
     "nis2.report.create: opts.entityId is required (NIS2 registration ID)",
     Nis2ReportError, "nis2-report/bad-entity-id");
-  if (!VALID_ENTITY_TYPES[opts.entityType]) {
+  if (!Object.prototype.hasOwnProperty.call(VALID_ENTITY_TYPES, opts.entityType)) {
     throw new Nis2ReportError("nis2-report/bad-entity-type",
       "nis2.report.create: opts.entityType must be 'essential' or 'important' (NIS2 Article 3 classification)");
   }
@@ -66,7 +66,6 @@ function create(opts) {
   var sectorAnnex = opts.sectorAnnex;
   var csirtEndpoint = opts.csirtEndpoint || null;
   var httpClient = opts.httpClient || null;
-  var auditOn = opts.audit !== false;
 
   var ir = incidentReport().create({
     audit:    opts.audit,
@@ -79,16 +78,7 @@ function create(opts) {
     },
   });
 
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({
-        action:   "nis2.report." + action,
-        outcome:  outcome,
-        metadata: metadata || {},
-      });
-    } catch (_e) { /* drop-silent */ }
-  }
+  var _emitAudit = audit().namespaced("nis2.report", opts.audit);
 
   async function _submitToCsirt(payload) {
     if (!csirtEndpoint || !httpClient) {

package/lib/nist-crosswalk.js

@@ -199,7 +199,7 @@ var CATALOGS = {
  *   // → ["b.permissions", "b.middleware.requireAuth", ...]
  */
 function controls(catalog) {
-  if (typeof catalog !== "string" || !CATALOGS[catalog]) {
+  if (typeof catalog !== "string" || !Object.prototype.hasOwnProperty.call(CATALOGS, catalog)) {
     throw new NistCrosswalkError("nist-crosswalk/unknown-catalog",
       "controls: unknown catalog '" + catalog + "'. Known: " +
       Object.keys(CATALOGS).join(", "));

package/lib/nonce-store.js

@@ -13,6 +13,16 @@
  *     inserting second would race on concurrent requests carrying
  *     the same nonce.
  *
+ *   await store.release(nonce) → boolean
+ *     Un-claims a single nonce so a later checkAndInsert of the same value
+ *     succeeds again — the rollback half of reserve -> commit -> rollback.
+ *     A handler that claims an event id the moment a signature verifies (to
+ *     win the race against a concurrent duplicate) MUST release it when
+ *     downstream processing fails, otherwise the provider's at-least-once
+ *     redelivery is reported as a replay and the event is dropped. Returns
+ *     whether a live claim existed. Pair with checkAndInsert; without it an
+ *     eager claim inverts the at-least-once contract on any failure.
+ *
  *   await store.purgeExpired() → number
  *     Removes entries past their expireAt. Called periodically by the
  *     middleware that uses the store. Returns the count purged.
@@ -32,8 +42,11 @@
  *     table _blamejs_api_encrypt_nonces. The PRIMARY KEY race is what
  *     makes the check + insert atomic across nodes.
  *
- *   { checkAndInsert, purgeExpired, close } — operator-supplied
- *     custom backend (Redis SETNX, Memcached add, etc.). Use this
+ *   { checkAndInsert, release?, purgeExpired?, close? } — operator-supplied
+ *     custom backend (Redis SETNX, Memcached add, etc.). release() is
+ *     optional but required to use reserve -> rollback; a backend omitting
+ *     it throws NONCE_BACKEND_NO_RELEASE the first time release() is called
+ *     (a loud gap, never a silent dropped rollback). Use this
  *     for cross-process accuracy without a per-request SQL hop.
  *
  * Sweep cadence: memory backend sweeps every opts.sweepIntervalMs
@@ -132,6 +145,21 @@ function _memoryBackend(opts) {
     return Promise.resolve(true);
   }
 
+  // Un-claim a nonce so a future checkAndInsert of the same value succeeds
+  // again — the rollback half of reserve -> commit -> rollback. A handler
+  // that claims an event id the moment a signature verifies (to win the race
+  // against a concurrent duplicate) MUST release it when downstream processing
+  // fails, otherwise the provider's at-least-once redelivery is reported as a
+  // replay and the event is dropped. Returns whether a live claim existed.
+  function release(nonce) {
+    if (typeof nonce !== "string" || nonce.length === 0) {
+      return Promise.reject(_err("INVALID_NONCE", "nonce must be a non-empty string"));
+    }
+    var existed = seen.get(nonce) !== undefined;
+    if (existed) seen.delete(nonce);
+    return Promise.resolve(existed);
+  }
+
   function purgeExpired() {
     return Promise.resolve(_purgeExpiredSync());
   }
@@ -144,6 +172,7 @@ function _memoryBackend(opts) {
   return {
     name:            "memory",
     checkAndInsert:  checkAndInsert,
+    release:         release,
     purgeExpired:    purgeExpired,
     close:           close,
     // Test hooks — underlying entry count + count of capacity fail-closed
@@ -178,6 +207,19 @@ function _clusterBackend(_opts) {
     return (result && result.rowCount > 0);
   }
 
+  async function release(nonce) {
+    if (typeof nonce !== "string" || nonce.length === 0) {
+      throw _err("INVALID_NONCE", "nonce must be a non-empty string");
+    }
+    // Un-claim a single nonce (the reserve -> rollback half). The middleware
+    // hashes the raw nonce before it reaches here, so we delete by hash.
+    var built = sql.delete(frameworkSchema.tableName(NONCE_TABLE), _nonceSqlOpts())
+      .where("nonceHash", "=", nonce)
+      .toSql();
+    var result = await clusterStorage.execute(built.sql, built.params);
+    return (result && result.rowCount > 0);
+  }
+
   async function purgeExpired() {
     var built = sql.delete(frameworkSchema.tableName(NONCE_TABLE), _nonceSqlOpts())
       .where("expireAt", "<=", Date.now())
@@ -191,6 +233,7 @@ function _clusterBackend(_opts) {
   return {
     name:           "cluster",
     checkAndInsert: checkAndInsert,
+    release:        release,
     purgeExpired:   purgeExpired,
     close:          close,
   };
@@ -208,6 +251,15 @@ function create(opts) {
     return Object.assign({
       name:         "custom",
       purgeExpired: function () { return Promise.resolve(0); },
+      // A custom backend that omits release() cannot participate in
+      // reserve -> rollback. Fail LOUDLY (not a silent no-op) so the gap
+      // surfaces the first time a handler tries to un-claim, rather than
+      // silently dropping the rollback and inverting the at-least-once contract.
+      release:      function () {
+        return Promise.reject(_err("BACKEND_NO_RELEASE",
+          "this custom nonce backend does not implement release(nonce); " +
+          "the reserve -> commit -> rollback pattern requires it"));
+      },
       close:        function () {},
     }, backend);
   }
@@ -215,11 +267,37 @@ function create(opts) {
   if (!backend || backend === "memory") return _memoryBackend(opts);
   throw _err("UNKNOWN_BACKEND",
     "nonce-store: unknown backend '" + backend +
-    "' (must be 'memory', 'cluster', or { checkAndInsert, purgeExpired, close })");
+    "' (must be 'memory', 'cluster', or { checkAndInsert, release?, purgeExpired?, close? })");
+}
+
+// enforceReplay(store, jti, expireAtMs, opts) — single-use enforcement
+// against a replay store: `await store.checkAndInsert(jti, expireAtMs)`,
+// raising opts.errorClass(opts.storeFailedCode, …) if the store itself
+// fails (a store outage must NOT be mistaken for a clean token) and
+// opts.errorClass(opts.replayCode, "<opts.tokenLabel> jti='<jti>' has
+// been seen before — replay refused") if the jti was already seen. The
+// fail-closed anti-replay control flow every JWT / DPoP verifier repeated
+// identically — centralised here so the contract lives in one place.
+// Verifiers with a divergent message or store contract (e.g. an atomic
+// back-channel-logout-token store) keep their own inline check.
+async function enforceReplay(store, jti, expireAtMs, opts) {
+  opts = opts || {};
+  var inserted;
+  try {
+    inserted = await store.checkAndInsert(jti, expireAtMs);
+  } catch (e) {
+    throw new opts.errorClass(opts.storeFailedCode,
+      "replayStore.checkAndInsert threw: " + ((e && e.message) || String(e)));
+  }
+  if (inserted === false) {
+    throw new opts.errorClass(opts.replayCode,
+      opts.tokenLabel + " jti='" + jti + "' has been seen before — replay refused");
+  }
 }
 
 module.exports = {
   create:           create,
+  enforceReplay:    enforceReplay,
   NonceStoreError:  NonceStoreError,
   _memoryBackend:   _memoryBackend,
   _clusterBackend:  _clusterBackend,

package/lib/ntp-check.js

@@ -45,6 +45,8 @@
  *   Boot-time clock-drift verification against an external NTP / NTS-KE reference.
  */
 var dgram = require("node:dgram");
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
@@ -200,6 +202,14 @@ function querySingle(server, opts) {
     //   LI=0 (no warning), VN=4, Mode=3 (client). Other bytes zero.
     var req = Buffer.alloc(NTP_PACKET_BYTES);
     req[0] = 0x23;
+    // RFC 5905 §8 client-cookie: put a random 64-bit nonce in the request's
+    // Transmit Timestamp (bytes 40-47). A conformant server copies it verbatim
+    // into the reply's Originate Timestamp (bytes 24-31). Verifying that echo
+    // rejects an off-path spoofed reply — without it ANY 48-byte UDP datagram
+    // reaching our ephemeral port becomes the authoritative time, letting a
+    // spoofer force a fatal-drift refuse-to-boot under BLAMEJS_NTP_STRICT.
+    var originCookie = nodeCrypto.randomBytes(8);
+    originCookie.copy(req, 40);
     var sendTimeMs = Date.now();
 
     socket.on("error", function (e) {
@@ -213,6 +223,24 @@ function querySingle(server, opts) {
       if (!Buffer.isBuffer(msg) || msg.length < NTP_PACKET_BYTES) {
         return done({ code: "ntp/bad-reply", message: "reply too short (" + (msg && msg.length) + " bytes)" });
       }
+      // Origin-cookie echo (RFC 5905 §8): the reply's Originate Timestamp
+      // (bytes 24-31) MUST equal the nonce we sent. An off-path spoofer can't
+      // know it, so this is the primary reply-authenticity check.
+      if (!bCrypto.timingSafeEqual(msg.subarray(24, 32), originCookie)) {
+        return done({ code: "ntp/origin-mismatch",
+          message: server + ": reply Originate Timestamp does not echo the request nonce (spoofed/stale reply)" });
+      }
+      // Reject a non-server mode, an unsynchronized/kiss-o'-death stratum
+      // (0 or >= 16), or LI=3 (alarm — clock not synchronized): such a peer
+      // cannot supply a trustworthy time and must not drive drift.
+      var mode = msg[0] & 0x07;
+      var li = (msg[0] >> 6) & 0x03;
+      var stratum = msg[1];
+      if (mode !== 4 || li === 3 || stratum === 0 || stratum >= 16) {
+        return done({ code: "ntp/unsynchronized",
+          message: server + ": reply mode=" + mode + " stratum=" + stratum + " LI=" + li +
+            " is not a synchronized server response" });
+      }
       // Bytes 40-47 = Transmit Timestamp (NTP epoch seconds.fraction)
       var ntpSeconds  = msg.readUInt32BE(40);                                    // NTP packet offset
       var ntpFraction = msg.readUInt32BE(44);                                    // NTP packet offset