@blamejs/core 0.7.38 → 0.7.40

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.40** (2026-05-05) — RFC 8617 ARC chain-validity hardening: duplicate-instance refusal, gap detection, hop ceiling, per-hop `cv=` rule enforcement. Closes a class of chain-injection holes the prior `arcVerify` would silently accept. **Duplicate instance** — two `ARC-Seal` (or AMS / AAR) headers at the same `i=N` now fail with `reason: "duplicate-instance"` instead of silently letting the second header overwrite the first signer's record (the latter is a known forwarder-injection attack). **Non-contiguous chain** — gap detection (`i=1, i=3` with no `i=2`) now correctly fails with `reason: "incomplete-or-non-contiguous"`. The prior `.some()` check skipped sparse-array empty slots and let the gap through. **Hop ceiling** — RFC 8617 §5.1.2 caps the chain at 50 sets; verifier now refuses with `reason: "too-many-hops"`. **Per-hop `cv=` rules** — i=1 MUST be `cv=none` (no upstream chain to validate); i≥2 MUST be `cv=pass` or `cv=fail` (cv=none invalid past hop 1); a downstream `cv=pass` after an upstream `cv=fail` is invalid (a hop can't claim chain-pass when an earlier hop saw it fail). Each violation surfaces with a structured `reason` field. **Result shape gains** `perHopCv: [string|null,...]` (one entry per hop) and `reason: string` when `chainStatus === "fail"` so operators can distinguish "signature failed" from "chain rules violated" without parsing free-text errors. Smoke 8642 → 8648 / wiki e2e 178 / Linux container smoke 8648 / Linux container wiki e2e 178 / eslint clean / api-snapshot baseline refreshed.
+
+- **0.7.39** (2026-05-05) — RFC 8954 OCSP nonce extension default-on, plus persistent-log reliability fix in the smoke runner. **`b.network.tls.ocsp.buildRequest(opts)`** (NEW) — constructs a DER-encoded OCSPRequest for a single (`leafCertDer`, `issuerCertDer`) pair. The RFC 8954 nonce extension is **on by default** (security-defaults-on rule); operators talking to responders that ignore nonces opt out via `nonce: false`. Default nonce length is 16 bytes (RFC 8954 §2.1 floor 1, ceiling 32 — `nonceLen` overrides). CertID hashes are SHA-1 per RFC 6960 §4.1.1 (the universally-supported algorithm; SHA-256 in OCSP requests is §4.3 optional and many responders reject). Returns `{ requestDer, nonce }`. Operators send `requestDer` to the OCSP responder URL via `b.httpClient` (Content-Type: `application/ocsp-request`) and pass the returned `nonce` Buffer to `evaluate(responseDer, { issuerPem, expectedNonce })` — defends against replay attacks where an attacker captures a "good" OCSP response and replays it after the cert is revoked. **DER writer surface added to `lib/asn1-der.js`** — `writeNode` / `writeSequence` / `writeOctetString` / `writeInteger` / `writeNull` / `writeOid` / `writeContextExplicit` (minimal, ~80 lines, X.690 short + long-form length encoding). **`evaluate(der, opts)` accepts `expectedNonce`** — when supplied, the response's nonce extension MUST match (else `tls/ocsp-nonce-mismatch`). Result shape gains a `nonce` field: `"matched"` / `"present-not-checked"` / `"n/a"`. **Smoke-runner persistent log reliability fix** — the `.test-output/smoke.log` tee was using `fs.createWriteStream` (async); when the runner threw on a test failure the buffer didn't flush before `process.exit`, so the failure detail never reached the log. Replaced with synchronous `fs.writeSync` against an open fd — every byte hits disk before exit. Surface change for diagnosing future failures: the log now ALWAYS captures the failure stack instead of truncating mid-run. Smoke 8635 → 8642 / wiki e2e 178 / Linux container smoke 8642 / Linux container wiki e2e 178 / eslint clean / api-snapshot baseline refreshed.
+
 - **0.7.38** (2026-05-05) — RFC 6698 + RFC 7672 DANE certificate-chain verification, plus smoke-runner LPT scheduling and a wiki failure-detail bugfix. **`b.network.smtp.dane.verifyChain(certChain, tlsaRecords, opts?)`** (NEW) — walks the peer cert chain (leaf-first DER buffers — typically `sock.getPeerCertificate(true).raw`) and confirms at least one TLSA record matches per the record's usage / selector / mtype. SMTP outbound (RFC 7672) only honors `DANE-TA` (2) and `DANE-EE` (3); `PKIX-TA` (0) and `PKIX-EE` (1) require a full PKIX path validator + CA-bundle and are refused unless the operator opts in via `allowPkixModes`. Selector `Cert` (0) compares the full DER; selector `SPKI` (1) compares the SubjectPublicKeyInfo bytes (extracted via the framework ASN.1 walker). Matching types: `Full`, sha-two-family at the short-digest length, sha-two-family at the long-digest length. Returns `{ ok, matches: [{ tlsaIndex, certIndex, usage, mtype }], errors }`. **ASN.1 walker** — `lib/asn1-der.js` `readNode` now surfaces a `.raw` field on each node (header + value bytes from the source buffer) so SPKI extraction can return the exact wire bytes for byte-identical TLSA matching. **Smoke-runner LPT scheduling** — `test/smoke.js` parallel mode now uses Longest-Processing-Time-first scheduling with a continuous worker queue. Per-test durations persist under `.test-output/smoke-timings.json` keyed by `process.platform` (so host win32/darwin and Linux container don't pollute each other's medians) with a 5-run history per test. Replaces the prior batched `Promise.all(slice(i, i + PARALLEL))` scheduling that left workers idle when one batch contained the long-tail test. **Wiki failure-detail bugfix** — `examples/wiki/test/e2e.js` was printing the per-example failure list AFTER the assert that throws on failure → operators only saw "1 of 178 failed" without WHICH example. Reordered so failure detail prints first. Smoke 8627 → 8635 / wiki e2e 178 / Linux container smoke 8635 / Linux container wiki e2e 178 / eslint clean / api-snapshot baseline refreshed.
 
 - **0.7.37** (2026-05-05) — RFC 8460 TLS-RPT submission transport: `b.network.smtp.tlsRpt.fetchPolicy` + `submit`. The previous `recordShape` only generated the JSON; operators had to wire submission themselves. **`b.network.smtp.tlsRpt.fetchPolicy(domain, opts)`** (NEW) — reads the RFC 8460 §3 `_smtp._tls.<domain>` TXT record and returns `{ version, rua: [string,...] }` where `rua` is the comma-separated list of report URIs (`https://` and `mailto:`) the recipient publishes. Returns `null` when no record is published. `opts.dnsLookup` is operator-supplied so the call composes with `b.network.dns` (DoH / DoT) without a hard dep; falls back to `node:dns/promises.resolveTxt`. **`b.network.smtp.tlsRpt.submit(report, opts)`** (NEW) — submits a TLS-RPT report to the published rua endpoints. `https://` URIs receive an HTTPS `POST` with `Content-Type: application/tlsrpt+gzip` and a gzip-compressed JSON body per RFC 8460 §6.2. `mailto:` URIs return a prepared `{ to, subject, contentType, encoding, body }` object so operators hand it to `b.mail` with their configured relay (the framework doesn't bake an SMTP relay in — operators wire transport per their environment). Per-endpoint result records carry `{ uri, kind, ok, status, error }` so a failure on one rua doesn't cascade. Routes through `b.httpClient` so SSRF + DNS-pin + retry policy come for free. Smoke 8619 → 8627 / wiki e2e 178 / Linux container smoke 8627 / Linux container wiki e2e 178 / eslint clean / api-snapshot baseline refreshed.

package/lib/asn1-der.js

@@ -250,6 +250,81 @@ function unwrapExplicit(node, expectedTag) {
   return readNode(node.value, 0);
 }
 
+// ---- DER writers (minimal — just the shapes the framework needs) ----
+//
+// Encoders for the small ASN.1 set the framework currently constructs:
+// SEQUENCE / OCTET STRING / OID / INTEGER / NULL / context-specific
+// [N] EXPLICIT. Fewer than 100 lines because we only emit the DER that
+// crosses the wire (OCSP requests today; future TLSA encoding tomorrow).
+// All length fields use the standard X.690 short / long-form encoding.
+
+function _encodeLength(n) {
+  if (n < 128) return Buffer.from([n]);                                          // allow:raw-byte-literal — X.690 short-form length boundary
+  // Long-form: first byte is 0x80 | numLengthOctets, then the length
+  // big-endian.
+  var bytes = [];
+  while (n > 0) {
+    bytes.unshift(n & 0xff);                                                     // allow:raw-byte-literal — base-256 length encoding mask
+    n = n >>> 8;                                                                 // allow:raw-byte-literal — base-256 length encoding shift
+  }
+  return Buffer.concat([Buffer.from([0x80 | bytes.length]), Buffer.from(bytes)]);
+}
+
+function writeNode(tagByte, value) {
+  return Buffer.concat([Buffer.from([tagByte]), _encodeLength(value.length), value]);
+}
+
+function writeSequence(children) {
+  // children: Array<Buffer> of already-encoded child nodes.
+  return writeNode(TAG.SEQUENCE | 0x20, Buffer.concat(children));                // allow:raw-byte-literal — DER constructed bit
+}
+
+function writeOctetString(value) {
+  return writeNode(TAG.OCTET_STRING, value);
+}
+
+function writeNull() {
+  return writeNode(TAG.NULL, Buffer.alloc(0));
+}
+
+function writeInteger(buf) {
+  // INTEGER values are big-endian. If high bit of leading byte is set
+  // and the value is positive (cert serials always are here), prepend
+  // 0x00 to disambiguate from a negative two's complement.
+  if (buf.length === 0) return writeNode(TAG.INTEGER, Buffer.from([0]));
+  if (buf[0] & 0x80) {                                                           // allow:raw-byte-literal — sign-bit disambiguation
+    return writeNode(TAG.INTEGER, Buffer.concat([Buffer.from([0]), buf]));
+  }
+  return writeNode(TAG.INTEGER, buf);
+}
+
+function writeOid(dotted) {
+  // Encode dotted-decimal OID per X.690 §8.19.
+  var parts = String(dotted).split(".").map(function (s) { return parseInt(s, 10); });
+  if (parts.length < 2) {
+    throw new Asn1Error("asn1/oid-too-short", "OID needs at least 2 arcs");
+  }
+  var bytes = [parts[0] * 40 + parts[1]];                                        // allow:raw-byte-literal — OID first-arc encoding
+  for (var i = 2; i < parts.length; i += 1) {
+    var arc = parts[i];
+    if (arc === 0) { bytes.push(0); continue; }
+    var stack = [];
+    while (arc > 0) {
+      stack.unshift(arc & 0x7f);                                                 // allow:raw-byte-literal — base-128 mask
+      arc = arc >>> 7;                                                           // allow:raw-byte-literal — base-128 shift
+    }
+    for (var j = 0; j < stack.length - 1; j += 1) stack[j] |= 0x80;              // allow:raw-byte-literal — continuation bit
+    for (var k = 0; k < stack.length; k += 1) bytes.push(stack[k]);
+  }
+  return writeNode(TAG.OID, Buffer.from(bytes));
+}
+
+function writeContextExplicit(tagNumber, child) {
+  // [N] EXPLICIT — context-specific class (0xA0 | tag) + constructed.
+  var tagByte = 0xa0 | (tagNumber & 0x1f);                                       // allow:raw-byte-literal — context-specific constructed mask
+  return writeNode(tagByte, child);
+}
+
 // Find a child node of a SEQUENCE / SET by predicate. Returns null if
 // no child matches.
 function findChild(children, predicate) {
@@ -260,15 +335,22 @@ function findChild(children, predicate) {
 }
 
 module.exports = {
-  TAG_CLASS:       TAG_CLASS,
-  TAG:             TAG,
-  readNode:        readNode,
-  readSequence:    readSequence,
-  readOid:         readOid,
-  readOctetString: readOctetString,
-  readUnsignedInt: readUnsignedInt,
-  readBitString:   readBitString,
-  unwrapExplicit:  unwrapExplicit,
-  findChild:       findChild,
-  Asn1Error:       Asn1Error,
+  TAG_CLASS:           TAG_CLASS,
+  TAG:                 TAG,
+  readNode:            readNode,
+  readSequence:        readSequence,
+  readOid:             readOid,
+  readOctetString:     readOctetString,
+  readUnsignedInt:     readUnsignedInt,
+  readBitString:       readBitString,
+  unwrapExplicit:      unwrapExplicit,
+  findChild:           findChild,
+  writeNode:           writeNode,
+  writeSequence:       writeSequence,
+  writeOctetString:    writeOctetString,
+  writeInteger:        writeInteger,
+  writeNull:           writeNull,
+  writeOid:            writeOid,
+  writeContextExplicit: writeContextExplicit,
+  Asn1Error:           Asn1Error,
 };

package/lib/mail-auth.js

@@ -376,6 +376,10 @@ function _parseHeaderLines(headerSection) {
   return unfolded;
 }
 
+// RFC 8617 §5.1.2 caps the chain at 50 sets to bound verifier work and
+// limit how far an attacker can push junk headers.
+var ARC_MAX_HOPS = 50;                                                           // allow:raw-byte-literal — RFC 8617 §5.1.2 chain ceiling
+
 async function arcVerify(rfc822, opts) {
   if (typeof rfc822 !== "string" || rfc822.length === 0) {
     throw new MailAuthError("mail-auth/arc-bad-input",
@@ -384,8 +388,16 @@ async function arcVerify(rfc822, opts) {
   opts = opts || {};
   var headers = _parseHeaderLines(_splitHeaders(rfc822));
   var hops = [];
-
-  // 1. Index ARC headers by instance number.
+  var seenSlot = {};                                                             // {`<instance>:<name>`: true} — duplicate detection
+
+  // 1. Index ARC headers by instance number. Refuse duplicates: a single
+  //    hop has exactly one ARC-Seal / ARC-Message-Signature /
+  //    ARC-Authentication-Results. A second copy at the same instance is
+  //    a malformed chain (per RFC 8617 §5.1 implicit, and a known
+  //    injection vector — a forwarder that re-signs with a duplicate
+  //    instance would silently overwrite the original signer).
+  var duplicate = false;
+  var maxInstanceSeen = 0;
   for (var i = 0; i < headers.length; i += 1) {
     var line = headers[i];
     var colonAt = line.indexOf(":");
@@ -396,7 +408,11 @@ async function arcVerify(rfc822, opts) {
         name !== "arc-authentication-results") continue;
     var iMatch = value.match(/(?:^|[;,\s])i=(\d+)/);                             // allow:regex-no-length-cap — header bounded by RFC 5322 998
     var inst = iMatch ? parseInt(iMatch[1], 10) : null;
-    if (inst === null) continue;
+    if (inst === null || !isFinite(inst) || inst < 1) continue;
+    if (inst > maxInstanceSeen) maxInstanceSeen = inst;
+    var slotKey = inst + ":" + name;
+    if (seenSlot[slotKey]) { duplicate = true; continue; }
+    seenSlot[slotKey] = true;
     if (!hops[inst - 1]) hops[inst - 1] = { instance: inst };
     hops[inst - 1][name] = value;
   }
@@ -405,14 +421,48 @@ async function arcVerify(rfc822, opts) {
     return { chainStatus: "none", hopCount: 0, hops: [] };
   }
 
-  // 2. Structural check — every hop must carry all three headers.
-  var structuralFail = hops.some(function (h) {
-    return !h || !h["arc-seal"] || !h["arc-message-signature"] ||
-           !h["arc-authentication-results"];
-  });
+  if (duplicate) {
+    return {
+      chainStatus: "fail",
+      reason:      "duplicate-instance",
+      hopCount:    hops.filter(Boolean).length,
+      hops: hops.filter(Boolean).map(function (h) {
+        return { instance: h.instance,
+                 hasSeal: !!h["arc-seal"],
+                 hasMessageSignature: !!h["arc-message-signature"],
+                 hasAuthenticationResults: !!h["arc-authentication-results"],
+                 amsResult: "skipped", asResult: "skipped" };
+      }),
+    };
+  }
+
+  if (maxInstanceSeen > ARC_MAX_HOPS) {
+    return {
+      chainStatus: "fail",
+      reason:      "too-many-hops",
+      hopCount:    maxInstanceSeen,
+      hops:        [],
+    };
+  }
+
+  // 2. Structural check — every hop must carry all three headers AND
+  //    the chain must start at i=1 with no gaps. RFC 8617 §5.1 requires
+  //    instances to form a contiguous 1..N sequence. Indexed loop (not
+  //    .some) because sparse arrays skip empty slots in callbacks —
+  //    a non-contiguous chain ([hop1, , hop3]) would silently pass.
+  var structuralFail = false;
+  for (var sci = 0; sci < hops.length; sci += 1) {
+    var sch = hops[sci];
+    if (!sch || !sch["arc-seal"] || !sch["arc-message-signature"] ||
+        !sch["arc-authentication-results"]) {
+      structuralFail = true;
+      break;
+    }
+  }
   if (structuralFail) {
     return {
       chainStatus: "fail",
+      reason:      "incomplete-or-non-contiguous",
       hopCount:    hops.filter(Boolean).length,
       hops: hops.filter(Boolean).map(function (h) {
         return { instance: h.instance,
@@ -454,23 +504,73 @@ async function arcVerify(rfc822, opts) {
     if (amsResult.result !== "pass" || asResult.result !== "pass") anyFail = true;
   }
 
-  // 4. Chain Validation per §5.2: the most recent AS's cv= must
-  //    reflect the validity of every prior hop.
-  var lastAs = hops[hops.length - 1]["arc-seal"];
-  var cvMatch = lastAs.match(/(?:^|[;,\s])cv=(none|pass|fail)/);
-  var cv = cvMatch ? cvMatch[1] : null;
+  // 4. Chain Validation per RFC 8617 §5.2.
+  //
+  //    Per-hop cv= self-attestation rules:
+  //      i=1   — cv=none REQUIRED (no upstream chain to validate)
+  //      i>=2  — cv=pass or cv=fail; cv=none is invalid at i>=2
+  //
+  //    Once any hop's AS reports cv=fail, the chain is permanently
+  //    broken — downstream cv=pass claims after an upstream cv=fail
+  //    are malformed (a hop can't claim the chain validates when it
+  //    knows an earlier hop saw it fail).
+  var perHopCv = [];
+  var hopRuleViolation = null;
+  var sawFail = false;
+  for (var hi = 0; hi < hops.length; hi += 1) {
+    var as = hops[hi]["arc-seal"];
+    var hopCvMatch = as.match(/(?:^|[;,\s])cv=(none|pass|fail)/);
+    var hopCv = hopCvMatch ? hopCvMatch[1] : null;
+    perHopCv.push(hopCv);
+    if (hopCv === null) {
+      hopRuleViolation = "missing-cv-at-i=" + (hi + 1);
+      break;
+    }
+    if (hi === 0 && hopCv !== "none") {
+      hopRuleViolation = "i=1-cv-must-be-none-got-" + hopCv;
+      break;
+    }
+    if (hi >= 1 && hopCv === "none") {
+      hopRuleViolation = "i=" + (hi + 1) + "-cv=none-invalid-after-hop-1";
+      break;
+    }
+    if (hopCv === "fail") sawFail = true;
+    if (hopCv === "pass" && sawFail) {
+      hopRuleViolation = "i=" + (hi + 1) + "-cv=pass-after-upstream-fail";
+      break;
+    }
+  }
 
-  var chainStatus = anyFail ? "fail" :
-                    (hops.length === 1 && cv === "none") ? "pass" :
-                    (hops.length > 1 && cv === "pass")   ? "pass" :
-                    "fail";
+  var lastCv = perHopCv[perHopCv.length - 1];
+  var chainStatus;
+  var reasonOut = null;
+  if (hopRuleViolation) {
+    chainStatus = "fail";
+    reasonOut = hopRuleViolation;
+  } else if (anyFail) {
+    chainStatus = "fail";
+    reasonOut = "signature-verification-failed";
+  } else if (lastCv === "fail") {
+    chainStatus = "fail";
+    reasonOut = "last-as-cv=fail";
+  } else if (hops.length === 1 && lastCv === "none") {
+    chainStatus = "pass";
+  } else if (hops.length > 1 && lastCv === "pass") {
+    chainStatus = "pass";
+  } else {
+    chainStatus = "fail";
+    reasonOut = "unexpected-cv-state";
+  }
 
-  return {
+  var out = {
     chainStatus: chainStatus,
     hopCount:    hops.length,
-    cv:          cv,
+    cv:          lastCv,
+    perHopCv:    perHopCv,
     hops:        perHop,
   };
+  if (reasonOut) out.reason = reasonOut;
+  return out;
 }
 
 // Verify a single AMS or AS within the chain by reconstructing the

package/lib/network-tls.js

@@ -412,6 +412,9 @@ function _connectAndCheckOcsp(opts, requireStapled) {
 // validation (operators relying on those wire their own parser).
 
 var OID_BASIC_OCSP_RESPONSE = "1.3.6.1.5.5.7.48.1.1";
+// OCSP nonce extension — id-pkix-ocsp-nonce.
+var OID_OCSP_NONCE          = "1.3.6.1.5.5.7.48.1.2";
+var OID_SHA1                = "1.3.14.3.2.26";                                   // allow:raw-byte-literal — SHA-1 algorithm OID arc
 var OID_RSA_SHA256          = "1.2.840.113549.1.1.11";
 var OID_RSA_SHA384          = "1.2.840.113549.1.1.12";
 var OID_RSA_SHA512          = "1.2.840.113549.1.1.13";
@@ -533,17 +536,53 @@ function parseOcspResponse(der) {
   // ResponderID is itself a CHOICE (byName [1] / byKey [2]), then a
   // GeneralizedTime, then the responses SEQUENCE-OF.
   var responsesNode = null;
+  var responseExtensionsNode = null;
   for (var rdi = rdChildren.length - 1; rdi >= 0; rdi -= 1) {
     var ch = rdChildren[rdi];
     if (ch.tag === asn1.TAG.SEQUENCE && ch.tagClass === asn1.TAG_CLASS.UNIVERSAL) {
       responsesNode = ch;
       break;
     }
+    if (ch.tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC && ch.tag === 1) {       // [1] EXPLICIT responseExtensions
+      responseExtensionsNode = asn1.readNode(ch.value, 0);
+    }
   }
   if (!responsesNode) {
     throw new TlsTrustError("tls/ocsp-bad-shape",
       "ResponseData missing responses SEQUENCE OF");
   }
+  // Walk responseExtensions for the OCSP nonce (RFC 8954 / RFC 6960
+  // §4.4.1). Returns the raw nonce bytes when present, or null.
+  var responseNonce = null;
+  if (responseExtensionsNode && responseExtensionsNode.tag === asn1.TAG.SEQUENCE) {
+    var extKids = asn1.readSequence(responseExtensionsNode.value);
+    for (var ei = 0; ei < extKids.length; ei += 1) {
+      var ext = extKids[ei];
+      if (ext.tag !== asn1.TAG.SEQUENCE) continue;
+      var extChildren = asn1.readSequence(ext.value);
+      if (extChildren.length === 0) continue;
+      var extOid;
+      try { extOid = asn1.readOid(extChildren[0]); }
+      catch (_e3) { continue; }
+      if (extOid !== OID_OCSP_NONCE) continue;
+      var extnValue = asn1.readOctetString(extChildren[extChildren.length - 1]);
+      // RFC 8954 §2.1 — the nonce extension value is the raw bytes
+      // wrapped in an OCTET STRING (the value here). RFC 6960 §4.4.1
+      // historically wrapped the nonce in another OCTET STRING; tolerate
+      // both shapes.
+      try {
+        var inner = asn1.readNode(extnValue);
+        if (inner.tag === asn1.TAG.OCTET_STRING) {
+          responseNonce = inner.value;
+        } else {
+          responseNonce = extnValue;
+        }
+      } catch (_e4) {
+        responseNonce = extnValue;
+      }
+      break;
+    }
+  }
   var singleResponses = asn1.readSequence(responsesNode.value);
   var responses = [];
   for (var sri = 0; sri < singleResponses.length; sri += 1) {
@@ -586,6 +625,7 @@ function parseOcspResponse(der) {
       signatureAlgorithmOid: sigAlgOid,
       signature:             signatureBytes,
       responses:             responses,
+      nonce:                 responseNonce,
     },
   };
 }
@@ -669,6 +709,28 @@ function evaluateOcspResponse(ocspDer, opts) {
     return { ok: false, status: parsed.status, signatureValid: true,
              errors: ["OCSP response has no entry for the requested cert serial"] };
   }
+  // Optional nonce echo verification (RFC 8954 / RFC 6960 §4.4.1).
+  // When opts.expectedNonce is supplied, the response MUST carry an
+  // OCSP nonce extension equal to the expected bytes — defends against
+  // replay of a stale "good" response captured before revocation.
+  var nonceCheck = "n/a";
+  if (opts.expectedNonce !== undefined && opts.expectedNonce !== null) {
+    if (!Buffer.isBuffer(opts.expectedNonce)) {
+      return { ok: false, status: parsed.status, signatureValid: true,
+               errors: ["evaluateOcspResponse: opts.expectedNonce must be a Buffer when supplied"] };
+    }
+    if (!parsed.basic.nonce) {
+      return { ok: false, status: parsed.status, signatureValid: true,
+               errors: ["OCSP response missing nonce extension (expected for replay defense)"] };
+    }
+    if (!parsed.basic.nonce.equals(opts.expectedNonce)) {
+      return { ok: false, status: parsed.status, signatureValid: true,
+               errors: ["OCSP nonce mismatch — possible replay or wrong responder"] };
+    }
+    nonceCheck = "matched";
+  } else if (parsed.basic.nonce) {
+    nonceCheck = "present-not-checked";
+  }
   return {
     ok:             match.certStatus === "good",
     status:         parsed.status,
@@ -676,11 +738,146 @@ function evaluateOcspResponse(ocspDer, opts) {
     thisUpdate:     match.thisUpdate,
     nextUpdate:     match.nextUpdate,
     signatureValid: true,
+    nonce:          nonceCheck,
     errors:         match.certStatus === "good" ? [] :
                     ["certStatus=" + match.certStatus],
   };
 }
 
+// ---- OCSPRequest builder (RFC 6960 §4.1 + RFC 8954 nonce ext) ----
+//
+// Constructs a DER-encoded OCSPRequest for a single (leafCertDer,
+// issuerCertDer) pair, optionally with an RFC 8954 nonce extension.
+// Operators send the returned `requestDer` to the OCSP responder URL
+// (e.g. via b.httpClient with `Content-Type: application/ocsp-request`)
+// and pass `nonce` to `ocsp.evaluate(responseDer, { expectedNonce })`
+// to defend against replay attacks.
+//
+// Nonce DEFAULT ON — defense in depth. RFC 6960 §4.4.1 marks nonce
+// optional and some public responders (notably Let's Encrypt's) ignore
+// it; operators explicitly targeting those responders opt out via
+// `opts.nonce: false`. The framework default is RFC 8954 with 16 random
+// bytes (RFC 8954 §2.1 floor; ceiling 32).
+
+function _extractIssuerNameDerAndKeyBitString(certDer) {
+  // From the leaf cert's tbsCertificate, pull the issuer Name (DER) +
+  // the issuer's SubjectPublicKey BIT STRING content. For OCSP CertID,
+  // RFC 6960 §4.1.1 specifies hash(issuerName) and hash(issuerKey).
+  // This helper operates on the ISSUER cert (not the leaf): the issuer's
+  // Name and SubjectPublicKey are what get hashed.
+  var top = asn1.readNode(certDer);
+  if (top.tag !== asn1.TAG.SEQUENCE) {
+    throw new TlsTrustError("tls/ocsp-bad-issuer-cert", "issuer cert is not a SEQUENCE");
+  }
+  var children = asn1.readSequence(top.value);
+  if (children.length === 0) {
+    throw new TlsTrustError("tls/ocsp-bad-issuer-cert", "issuer cert has no children");
+  }
+  var tbs = children[0];
+  if (tbs.tag !== asn1.TAG.SEQUENCE) {
+    throw new TlsTrustError("tls/ocsp-bad-issuer-cert", "tbsCertificate is not a SEQUENCE");
+  }
+  var tbsKids = asn1.readSequence(tbs.value);
+  // Skip optional [0] EXPLICIT version, then serialNumber, signature,
+  // then issuer (the cert's own subject in a self-signed CA, or its
+  // issuer field for a sub-CA — we just want THIS cert's subject).
+  var idx = 0;
+  if (tbsKids.length > 0 &&
+      tbsKids[0].tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC &&
+      tbsKids[0].tag === 0) {                                                    // allow:raw-byte-literal — X.509 [0] EXPLICIT version tag
+    idx = 1;
+  }
+  // After version: serialNumber, signature, issuer, validity, subject, SPKI.
+  var subjectIdx = idx + 4;                                                      // allow:raw-byte-literal — X.509 TBSCertificate field count
+  var spkiIdx = idx + 5;                                                         // allow:raw-byte-literal — X.509 TBSCertificate field count
+  if (spkiIdx >= tbsKids.length) {
+    throw new TlsTrustError("tls/ocsp-bad-issuer-cert", "issuer cert lacks SPKI field");
+  }
+  var subject = tbsKids[subjectIdx];
+  var spki = tbsKids[spkiIdx];
+  // Within SPKI: SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
+  var spkiKids = asn1.readSequence(spki.value);
+  if (spkiKids.length < 2) {                                                     // allow:raw-byte-literal — minimum SPKI fields
+    throw new TlsTrustError("tls/ocsp-bad-issuer-cert", "SPKI missing subjectPublicKey BIT STRING");
+  }
+  var keyBytes = asn1.readBitString(spkiKids[1]);
+  return {
+    issuerNameDer: subject.raw,                                                  // the DER of the Name SEQUENCE (header + value)
+    issuerKey:     keyBytes,
+  };
+}
+
+function _extractLeafSerial(leafCertDer) {
+  var top = asn1.readNode(leafCertDer);
+  if (top.tag !== asn1.TAG.SEQUENCE) {
+    throw new TlsTrustError("tls/ocsp-bad-leaf-cert", "leaf cert is not a SEQUENCE");
+  }
+  var children = asn1.readSequence(top.value);
+  var tbs = children[0];
+  var tbsKids = asn1.readSequence(tbs.value);
+  var idx = 0;
+  if (tbsKids.length > 0 &&
+      tbsKids[0].tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC &&
+      tbsKids[0].tag === 0) {                                                    // allow:raw-byte-literal — X.509 [0] EXPLICIT version tag
+    idx = 1;
+  }
+  // serialNumber is the next field after the optional version.
+  return tbsKids[idx].value;
+}
+
+function buildOcspRequest(opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(opts.leafCertDer)) {
+    throw new TlsTrustError("tls/ocsp-bad-input",
+      "buildRequest: opts.leafCertDer must be a Buffer (peer cert raw DER)");
+  }
+  if (!Buffer.isBuffer(opts.issuerCertDer)) {
+    throw new TlsTrustError("tls/ocsp-bad-input",
+      "buildRequest: opts.issuerCertDer must be a Buffer (issuer cert raw DER)");
+  }
+  var iss = _extractIssuerNameDerAndKeyBitString(opts.issuerCertDer);
+  var serial = _extractLeafSerial(opts.leafCertDer);
+  // CertID hashes — SHA-1 per RFC 6960 §4.1.1 (the only universally
+  // supported algorithm; SHA-256 in OCSP requests is RFC 6960 §4.3
+  // optional and many responders reject).
+  var nameHash = nodeCrypto.createHash("sha1").update(iss.issuerNameDer).digest();
+  var keyHash  = nodeCrypto.createHash("sha1").update(iss.issuerKey).digest();
+  // hashAlgorithm AlgorithmIdentifier ::= SEQUENCE { algorithm OID, NULL }
+  var algId = asn1.writeSequence([asn1.writeOid(OID_SHA1), asn1.writeNull()]);
+  var certId = asn1.writeSequence([
+    algId,
+    asn1.writeOctetString(nameHash),
+    asn1.writeOctetString(keyHash),
+    asn1.writeInteger(serial),
+  ]);
+  var requestNode = asn1.writeSequence([certId]);
+  var requestList = asn1.writeSequence([requestNode]);
+  var nonceBytes = null;
+  var tbsChildren = [requestList];
+  // Default ON per the framework security-defaults-on rule. Operators
+  // talking to a responder that ignores nonces opt out via nonce: false.
+  var includeNonce = opts.nonce !== false;
+  if (includeNonce) {
+    var nonceLen = typeof opts.nonceLen === "number" ? opts.nonceLen : 16;       // allow:raw-byte-literal — RFC 8954 §2.1 nonce length floor
+    if (nonceLen < 1 || nonceLen > 32) {                                         // allow:raw-byte-literal — RFC 8954 §2.1 nonce length ceiling
+      throw new TlsTrustError("tls/ocsp-bad-nonce-len",
+        "nonce length out of RFC 8954 range (1..32)");
+    }
+    nonceBytes = nodeCrypto.randomBytes(nonceLen);
+    // Extension ::= SEQUENCE { extnID OID, critical BOOL DEFAULT FALSE, extnValue OCTET STRING }
+    // For nonce, extnValue is OCTET STRING wrapping the raw nonce bytes (RFC 8954 §2.1 — outer OCTET STRING only).
+    var nonceExt = asn1.writeSequence([
+      asn1.writeOid(OID_OCSP_NONCE),
+      asn1.writeOctetString(nonceBytes),
+    ]);
+    var extensions = asn1.writeSequence([nonceExt]);
+    tbsChildren.push(asn1.writeContextExplicit(2, extensions));                  // [2] EXPLICIT requestExtensions
+  }
+  var tbs = asn1.writeSequence(tbsChildren);
+  var requestDer = asn1.writeSequence([tbs]);
+  return { requestDer: requestDer, nonce: nonceBytes };
+}
+
 var ocsp = Object.freeze({
   // Connect with OCSP requested. Returns { authorized, ocspBytes,
   // peerCert }. requireStapled: true makes empty / not-stapled responses
@@ -721,6 +918,13 @@ var ocsp = Object.freeze({
   },
   parseResponse:        parseOcspResponse,
   evaluate:             evaluateOcspResponse,
+  // buildRequest — construct a DER-encoded OCSPRequest for a single
+  // (leafCertDer, issuerCertDer) pair. RFC 8954 nonce extension is ON
+  // by default (16 random bytes; opts.nonceLen overrides within RFC
+  // 8954's 1..32 range; opts.nonce: false opts out for responders that
+  // ignore nonces). Returns { requestDer, nonce }; pass `nonce` to
+  // evaluate({ expectedNonce }).
+  buildRequest:         buildOcspRequest,
   // inspectMustStaple — read the RFC 7633 TLS Feature extension on a
   // peer cert. Returns { mustStaple, features }. mustStaple === true
   // when status_request (5) is in the feature list; the cert is then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.38",
+  "version": "0.7.40",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:3adb7877-ed69-4d8b-8275-eccb0ef99166",
+  "serialNumber": "urn:uuid:bd5fd6e1-f474-44da-9714-adb6fbf43b34",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-05T19:15:46.191Z",
+    "timestamp": "2026-05-05T19:17:14.991Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.38",
+      "bom-ref": "@blamejs/core@0.7.40",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.38",
+      "version": "0.7.40",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.38",
+      "purl": "pkg:npm/%40blamejs/core@0.7.40",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.38",
+      "ref": "@blamejs/core@0.7.40",
       "dependsOn": []
     }
   ]