@blamejs/pki 0.8.6 → 0.8.9

package/lib/path-validate.js

@@ -34,6 +34,7 @@ var webcrypto = require("./webcrypto");
 var pkix = require("./schema-pkix");
 var oid = require("./oid");
 var ct = require("./ct");
+var identity = require("./identity-match");
 var errors = require("./framework-error");
 var asn1 = require("./asn1-der");
 var schema = require("./schema-engine");
@@ -493,35 +494,17 @@ function hostConstraintMatch(constraint, host, reachIntoBase) {
   return false;
 }
 
-function _charTable(chars) { var t = []; for (var i = 0; i < chars.length; i++) t[_charCodeAt(chars, i)] = true; return t; }
 function _startsWithDigit(s) { if (s.length === 0) return false; var c = _charCodeAt(s, 0); return c >= 48 && c <= 57; }
 
-var _SCHEME_TABLE = _charTable("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+.-");
-function _uriAuthorityRange(uri) {
-  var n = uri.length;
-  if (n === 0) return null;
-  var c0 = _charCodeAt(uri, 0);
-  if (!((c0 >= 65 && c0 <= 90) || (c0 >= 97 && c0 <= 122))) return null;
-  var p = 1;
-  while (p < n && _SCHEME_TABLE[_charCodeAt(uri, p)]) p += 1;
-  if (_charCodeAt(uri, p) !== 58 || _charCodeAt(uri, p + 1) !== 47 || _charCodeAt(uri, p + 2) !== 47) return null;
-  p += 3;
-  var authStart = p;
-  while (p < n) { var d = _charCodeAt(uri, p); if (d === 47 || d === 63 || d === 35) break; p += 1; }
-  return [authStart, p];
-}
-function _portStripIndex(s) {
-  var i = s.length;
-  while (i > 0) { var c = _charCodeAt(s, i - 1); if (c >= 48 && c <= 57) i -= 1; else break; }
-  return (i < s.length && i > 0 && _charCodeAt(s, i - 1) === 58) ? i - 1 : s.length;
-}
+var isFqdnHost = guard.name.isFqdnHost;
+
+/** @internal `URL.hostname` keeps an IPv6 literal's brackets, and `net.isIP` reads the address
+ * without them. */
 function _stripBrackets(s) {
   var n = s.length;
   return (n >= 2 && _charCodeAt(s, 0) === 91 && _charCodeAt(s, n - 1) === 93) ? s.slice(1, n - 1) : s;
 }
 
-var isFqdnHost = guard.name.isFqdnHost;
-
 function uriMatch(constraint, uri) {
   var host = uriHost(uri);
   if (host === null) return "unsupported";
@@ -532,15 +515,14 @@ function uriMatch(constraint, uri) {
   return h === c;
 }
 
+/** @internal The host a `uniformResourceIdentifier` constraint compares against. A URI written
+ * without an authority has no host, and RFC 5280 sec. 4.2.1.10 constrains a host, so the caller
+ * reads that as `unsupported` rather than as a name. The brackets an IPv6 literal arrives in are
+ * kept, so the value stays the one the certificate carries and `isFqdnHost` refuses it. */
 function uriHost(uri) {
-  var r = _uriAuthorityRange(uri);
-  if (r === null) return null;
-  var authority = uri.slice(r[0], r[1]);
-  var firstAt = authority.indexOf("@");
-  if (firstAt !== authority.lastIndexOf("@")) return null;
-  if (firstAt !== -1) authority = authority.slice(firstAt + 1);
-  var host = authority.slice(0, _portStripIndex(authority));
-  return host === "" ? null : host;
+  var p = guard.name.uriParts(uri);
+  if (p === null || !p.hasAuthority || p.host === null) return null;
+  return p.bracketed ? "[" + p.host + "]" : p.host;
 }
 
 function ipMatch(constraint, addr) {
@@ -995,6 +977,25 @@ function validateCriticalExtensionStructure(cert) {
   return null;
 }
 
+/** @internal A checker decides on more than a status: which source answered, which locations it
+ * skipped, and for a revocation the CRLReason and the time the entry named. Those reach the caller
+ * on the check row, because the status alone cannot tell a waiver what it waived or a revocation
+ * why. The verdict is a caller-supplied object where `opts.revocationChecker` is, so each field is
+ * read once into a local and the value is copied rather than the object. `reasonCode` is the name
+ * `crlChecker` gives the CRLReason integer and `revocationReason` the name `ocspChecker` gives it;
+ * both are read so the row does not depend on which checker answered. */
+function _revocationRow(row, rv) {
+  if (rv == null) return row;
+  var reason = rv.reason;
+  if (typeof reason === "string" && reason.length > 0) row.reason = reason;
+  var code = rv.revocationReason;
+  if (typeof code !== "number") code = rv.reasonCode;
+  if (intrinsic.numberIsFinite(code)) row.revocationReason = code;
+  var at = rv.revocationTime;
+  if (guard.time.isDate(at)) row.revocationTime = new intrinsic.Date(guard.time.instantOf(at));
+  return row;
+}
+
 /**
  * @primitive  pki.path.validate
  * @signature  pki.path.validate(path, opts) -> Promise<result>
@@ -1060,7 +1061,10 @@ function validateCriticalExtensionStructure(cert) {
  * one could not be answered at all and the path fails for it. The
  * per-certificate `revocation` check carries the `status` it was decided on and
  * marks a waiver, so "checked, good" is distinguishable from "could not check,
- * and you waived it", a distinction a stored verdict is re-read to settle. A
+ * and you waived it", a distinction a stored verdict is re-read to settle. It
+ * also carries what the checker decided on: `reason` (the source that answered,
+ * the locations it skipped, the faults it noted), and for a revocation
+ * `revocationReason` (the CRLReason integer) and `revocationTime`. A
  * throw from a checker is a fault in the checker: no status was reported, so the
  * path fails as `path/revocation-checker-error` carrying the fault whatever
  * `softFail` says. `softFail` opts into an undetermined answer; the built-in
@@ -1105,7 +1109,7 @@ function validateCriticalExtensionStructure(cert) {
  *   res.valid;  // boolean; res.results[0].checks carries the per-check codes
  */
 var _VALIDATE_OPTS = intrinsic.assign(intrinsic.create(null), {
-  checkPurpose: 1, ctLogList: 1, ctPolicy: 1, historicalMode: 1, initialAnyPolicyInhibit: 1,
+  checkPurpose: 1, ctLogList: 1, ctPolicy: 1, historicalMode: 1, identity: 1, initialAnyPolicyInhibit: 1,
   initialExcludedSubtrees: 1, initialExplicitPolicy: 1, initialPermittedSubtrees: 1,
   initialPolicyMappingInhibit: 1, maxPathCerts: 1, maxPolicyNodes: 1, minRsaModulusBits: 1, requireRevocation: 1,
   requiredEku: 1, revocationChecker: 1, softFail: 1, time: 1, trustAnchors: 1,
@@ -1139,9 +1143,22 @@ async function ctGateCheck(leaf, certs, anchor, ctLogList, ctPolicy, n, at) {
 }
 
 async function validate(path, opts) {
-  opts = guard.identifier.optionsObject(opts, E, "path/bad-input", "validate: opts");
-  guard.identifier.assertKnownKeys(opts, _VALIDATE_OPTS, E, "path/bad-input",
+  var checked = guard.identifier.optionsObject(opts, E, "path/bad-input", "validate: opts");
+  guard.identifier.assertKnownKeys(checked, _VALIDATE_OPTS, E, "path/bad-input",
     "pki.path.validate has an unknown option (the anchor option is `trustAnchors`, a single anchor or an array). The unknown option was: ");
+  /** @internal One validation, named by an object nothing outside this module can reach. A
+   * revocation checker that budgets fetches is called once per certificate and again per anchor
+   * attempt, so without a name for the run it cannot tell "the next certificate on this path" from
+   * "a new validation", and the totals it documents become per-certificate totals. The checker
+   * holds its state against this object; the object is unreachable once the validation returns, so
+   * a checker stays reusable and nothing accumulates between runs. The anchor recursion carries the
+   * same one, and a caller has no way to supply one, so two validations never share a budget. */
+  return _validate(path, checked, intrinsic.freeze(intrinsic.create(null)));
+}
+
+/** @internal The options are the ones the door above checked, and each anchor attempt is handed a
+ * copy this module built, so the door runs once per call rather than once per anchor. */
+async function _validate(path, opts, run) {
   if (opts.ctPolicy != null && opts.ctLogList == null) throw E("path/bad-input", "validate: opts.ctPolicy requires opts.ctLogList (the trusted CT log-list to verify the certificate's SCTs against)");
   if (opts.ctLogList != null) {
     if (typeof opts.ctLogList !== "object" || opts.ctLogList.byLogId == null) throw E("path/bad-input", "validate: opts.ctLogList must be a pki.ct.parseLogList result");
@@ -1150,6 +1167,15 @@ async function validate(path, opts) {
     if (ctp.minScts != null && (typeof ctp.minScts !== "number" || !intrinsic.isInteger(ctp.minScts) || ctp.minScts < 1)) throw E("path/bad-input", "validate: opts.ctPolicy.minScts must be a positive integer");
     if (ctp.minOperators != null && (typeof ctp.minOperators !== "number" || !intrinsic.isInteger(ctp.minOperators) || ctp.minOperators < 1)) throw E("path/bad-input", "validate: opts.ctPolicy.minOperators must be a positive integer");
   }
+  /** @internal RFC 9525 sec. 6.1.1 has the client build its reference identities before it asks,
+   * and everything between this call and the comparison is awaited, so the list is read and copied
+   * here. A caller that reuses its options object, or whose object is reachable from elsewhere,
+   * then cannot change the question after asking it. */
+  var identityRefs = null;
+  if (opts.identity != null) {
+    try { identityRefs = identity.snapshotReferences(opts.identity); }
+    catch (e) { throw E("path/bad-input", "validate: opts.identity is not a reference identity this toolkit reads", e); }
+  }
   if (!intrinsic.isArray(path)) throw E("path/bad-input", "validate: path must be an array of certificates");
   var maxCerts = guard.limits.cap(opts.maxPathCerts, "validate: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
   if (path.length > maxCerts) throw E("path/bad-input", "validate: the certification path has " + path.length + " certificates, exceeding the maxPathCerts limit (" + maxCerts + ")");
@@ -1193,17 +1219,21 @@ async function validate(path, opts) {
       o.trustAnchors = a;
       if (permRawOnce != null) o.initialPermittedSubtrees = callerPermitted;
       if (exclRawOnce != null) o.initialExcludedSubtrees = callerExcluded;
+      /** @internal The snapshot taken in this call's prologue, so every anchor attempt asks the
+       * question the caller asked. Copying `opts.identity` across would have each attempt read
+       * the caller's own list again, after the awaits the earlier attempts spent. */
+      if (identityRefs !== null) o.identity = identityRefs;
       return o;
     };
     var lastMatched = null, anyMatched = false;
     for (var ai = 0; ai < tuples.length; ai++) {
       if (!dnEqual(tuples[ai].name.rdns, certs[0].issuer.rdns)) continue;
       anyMatched = true;
-      var oneRes = await validate(path, singleOpts(tuples[ai]));
+      var oneRes = await _validate(path, singleOpts(tuples[ai]), run);
       if (oneRes && oneRes.valid) return oneRes;
       lastMatched = oneRes;
     }
-    return anyMatched ? lastMatched : validate(path, singleOpts(tuples[0]));
+    return anyMatched ? lastMatched : _validate(path, singleOpts(tuples[0]), run);
   }
   var anchor = toAnchor(anchorList[0], "validate");
   guard.time.assertValid(opts.time, E, "path/bad-input", "validate: opts.time (the always-on validity-window check date)");
@@ -1228,6 +1258,7 @@ async function validate(path, opts) {
   var requireRevocation = opts.requireRevocation === true;
   var failed = false;
   var revocationRan = false, revocationWaived = false, revocationUndetermined = false;
+  var prefixAuthentic = true;
   var anchorDistrustApplied = false, anchorPurposeApplied = false;
   if (!checkPurpose && _hasPurposeScopedMetadata(anchor)) {
     throw E("path/bad-input", "validate: the trust anchor carries purpose-scoped metadata (distrustAfter / purposes), which is keyed by key purpose -- supply opts.checkPurpose to say which purpose this validation is for, or the constraint cannot be applied");
@@ -1258,6 +1289,11 @@ async function validate(path, opts) {
     }
     guard.list.append(checks, { name: "signature", ok: sigRes.ok, code: sigRes.ok ? undefined : (sigRes.code || "path/bad-signature") });
     if (!sigRes.ok) failed = true;
+    /** @internal What authenticates a certificate is the chain above it, not its own signature:
+     * a forged issuer fails its own check and its key still becomes the working key, so everything
+     * below verifies against a key nothing vouched for. Once a signature on the path has failed,
+     * no certificate under it is authenticated however its own check reads. */
+    if (!sigRes.ok) prefixAuthentic = false;
 
     if (compositeSig.COMPOSITE_ALGS[cert.subjectPublicKeyInfo.algorithm.oid]) {
       var cku = compositeKeyUsageCheck(cert);
@@ -1298,24 +1334,38 @@ async function validate(path, opts) {
       if (!ncRes.ok) failed = true;
     }
 
-    if (revocationChecker) {
+    /** @internal RFC 5019 sec. 3.2 has the status asked for after the chain signatures are
+     * validated, and a certificate no chain has authenticated is a claim: the serial and issuer a
+     * responder would answer about are ones nothing has bound to a key. A checker may open a
+     * socket, so asking anyway lets an unauthenticated certificate choose a destination and spend
+     * the fetch budget. The row says the status was not asked for, which is an undetermined
+     * outcome and not a checked one. */
+    if (revocationChecker && !prefixAuthentic) {
+      guard.list.append(checks, { name: "revocation", ok: false, status: "unknown",
+        code: "path/revocation-undetermined",
+        reason: sigRes.ok
+          ? "a signature above this certificate on the path did not verify, so no revocation status was asked for"
+          : "the certificate's own signature did not verify, so no revocation status was asked for" });
+      revocationUndetermined = true;
+      revocationRan = true;
+    } else if (revocationChecker) {
       var issuerCert = idx > 0 ? certs[idx - 1] : null;
       var rv, rvError = null;
-      try { rv = await revocationChecker.check(cert, { workingIssuerName: state.workingIssuerName, workingPublicKey: state.workingPublicKey, workingPublicKeyAlgorithm: state.workingPublicKeyAlgorithm, issuerCert: issuerCert }, { time: opts.time, historicalMode: opts.historicalMode === true }); }
+      try { rv = await revocationChecker.check(cert, { workingIssuerName: state.workingIssuerName, workingPublicKey: state.workingPublicKey, workingPublicKeyAlgorithm: state.workingPublicKeyAlgorithm, issuerCert: issuerCert }, { time: opts.time, historicalMode: opts.historicalMode === true, run: run }); }
       catch (e) { rv = { status: "error" }; rvError = e; }
       var rvStatus = (rv && typeof rv.status === "string") ? rv.status : "unknown";
-      if (rv && rv.status === "good") { guard.list.append(checks,{ name: "revocation", ok: true, status: "good" }); }
-      else if (rv && rv.status === "revoked") { guard.list.append(checks,{ name: "revocation", ok: false, status: "revoked", code: "path/revoked" }); failed = true; }
+      if (rv && rv.status === "good") { guard.list.append(checks, _revocationRow({ name: "revocation", ok: true, status: "good" }, rv)); }
+      else if (rv && rv.status === "revoked") { guard.list.append(checks, _revocationRow({ name: "revocation", ok: false, status: "revoked", code: "path/revoked" }, rv)); failed = true; }
       else if (rvError) {
         guard.list.append(checks,{ name: "revocation", ok: false, status: "error", code: "path/revocation-checker-error", error: rvError });
         revocationUndetermined = true;
         failed = true;
       }
       else if (softFail) {
-        guard.list.append(checks,{ name: "revocation", ok: true, status: rvStatus, waived: true });
+        guard.list.append(checks, _revocationRow({ name: "revocation", ok: true, status: rvStatus, waived: true }, rv));
         revocationWaived = true;
       } else {
-        guard.list.append(checks,{ name: "revocation", ok: false, status: rvStatus, code: "path/revocation-undetermined" });
+        guard.list.append(checks, _revocationRow({ name: "revocation", ok: false, status: rvStatus, code: "path/revocation-undetermined" }, rv));
         revocationUndetermined = true;
         failed = true;
       }
@@ -1404,8 +1454,26 @@ async function validate(path, opts) {
     if (!ctCheck.ok) failed = true;
   }
 
+  /** @internal RFC 9525 sec. 1.2 has identity matching run in addition to the sec. 6.1 checks
+   * rather than in place of any of them, and sec. 1.2 again has it read the leaf alone. So this
+   * runs after the per-certificate loop, against `certs[n-1]`, and its row joins that certificate's
+   * checks beside the sec. 6.1 rows rather than replacing them. */
+  var identityChecked = false;
+  if (identityRefs !== null) {
+    var idVerdict = identity.match(certs[n - 1], identityRefs);
+    var idRow = guard.verdict.of(idVerdict.matched
+      ? { name: "identity", ok: true }
+      : { name: "identity", ok: false, code: "path/identity-mismatch" });
+    var idTarget = null;
+    for (var ir = 0; ir < state.results.length; ir++) { if (state.results[ir].index === n - 1) { idTarget = state.results[ir]; break; } }
+    if (idTarget) guard.list.append(idTarget.checks, idRow);
+    if (!idVerdict.matched) failed = true;
+    identityChecked = idVerdict.matched ? idVerdict.matchedReference : false;
+  }
+
   return guard.verdict.of({
     valid: !failed,
+    identityChecked: identityChecked,
     revocationChecked: !revocationRan ? false
       : revocationUndetermined ? "undetermined"
         : revocationWaived ? "waived" : "determined",
@@ -1621,7 +1689,8 @@ function selectDelta(candidates) {
  * `unknown`, which the validator fails closed unless `softFail` is set.
  *
  * A `revoked` verdict carries `reasonCode` (the CRLReason integer, 0 for
- * `unspecified`) and a `reason` naming it.
+ * `unspecified`), a `reason` naming it, and `revocationTime` from the entry's
+ * revocationDate.
  *
  * @opts
  *   useDeltas  boolean  merge delta CRLs onto their base (RFC 5280 sec. 6.3.1(b)).
@@ -1665,7 +1734,7 @@ function crlChecker(crls, opts) {
         if (iku && iku.value.cRLSign !== true) signerAuthorized = false;
       }
 
-      var certStatus = null;
+      var certStatus = null, certTime = null;
       var reasonsMask = 0;
       var releasedByUnmergedDelta = false;
       var sawUnmergedDelta = false;
@@ -1743,7 +1812,8 @@ function crlChecker(crls, opts) {
           if (historical && guard.time.isDate(entry.revocationDate) &&
             guard.time.instantOf(entry.revocationDate) > guard.time.instantOf(time)) continue;
           var rc = crlEntryReason(entry);
-          return rc === null ? 0 : rc;
+          return { code: rc === null ? 0 : rc,
+            at: guard.time.isDate(entry.revocationDate) ? entry.revocationDate : null };
         }
         return null;
       }
@@ -1779,9 +1849,9 @@ function crlChecker(crls, opts) {
         } else {
           status = scanCrl(rec.crl);
         }
-        if (status === 8) status = null;
+        if (status !== null && status.code === 8) status = null;
 
-        if (status !== null && certStatus === null) certStatus = status;
+        if (status !== null && certStatus === null) { certStatus = status.code; certTime = status.at; }
         else if (status === null) reasonsMask |= gate.interim;
       }
 
@@ -1793,14 +1863,15 @@ function crlChecker(crls, opts) {
         sawUnmergedDelta = true;
         var dStatus = scanCrl(dRec.crl);
         if (dStatus === null) continue;
-        if (dStatus === 8) { releasedByUnmergedDelta = true; continue; }
-        if (certStatus === null) certStatus = dStatus;
+        if (dStatus.code === 8) { releasedByUnmergedDelta = true; continue; }
+        if (certStatus === null) { certStatus = dStatus.code; certTime = dStatus.at; }
       }
 
       if (releasedByUnmergedDelta) return guard.verdict.of({ status: "unknown", reason: "a delta CRL released this serial from hold; without merging its base CRL the revocation status is undetermined" });
       if (certStatus !== null) {
         var reasonName = constants.NAMES.CRL_REASON[String(certStatus)] || "unspecified";
-        return guard.verdict.of({ status: "revoked", reasonCode: certStatus, reason: "serial listed in a CRL (" + reasonName + ")" });
+        return guard.verdict.of({ status: "revoked", reasonCode: certStatus, reason: "serial listed in a CRL (" + reasonName + ")" },
+          certTime === null ? null : { revocationTime: certTime });
       }
       if (sawUnmergedDelta) return guard.verdict.of({ status: "unknown", reason: "a delta CRL cannot be combined with any complete CRL held here, so the revocation picture is incomplete" });
       if ((reasonsMask & ALL_REASONS) === ALL_REASONS) return guard.verdict.of({ status: "good" });
@@ -1816,6 +1887,7 @@ function crlChecker(crls, opts) {
 }
 
 var OID_REASON_CODE = oid.byName("reasonCode");
+var OID_OCSP_NONCE = oid.byName("ocspNonce");
 function crlEntryReason(entry) {
   var exts = entry.crlEntryExtensions || [];
   for (var i = 0; i < exts.length; i++) {
@@ -1939,17 +2011,16 @@ function ocspChecker(responses) {
 
 /**
  * @primitive  pki.path.verifyOcspResponse
- * @signature  pki.path.verifyOcspResponse(response, cert, issuerCert, time, opts?) -> Promise<{ valid, status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, revocationTime?, reason }>
+ * @signature  pki.path.verifyOcspResponse(response, cert, issuerCert, time, opts?) -> Promise<{ valid, status, responderAuthorized, signatureValid, matched, nonceMatched, thisUpdate, nextUpdate, revocationReason?, revocationTime?, reason }>
  * @since       0.2.22
  * @status      stable
- * @spec        RFC 6960
+ * @spec        RFC 6960, RFC 9654
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
  * Verify a single OCSP response for one certificate
  * against its already-parsed issuer certificate at `time`. This is the lower-level
  * primitive `pki.ocsp.verify` composes after parsing its inputs (most callers want
- * that ergonomic entry, which also handles DER/PEM decoding and request-nonce
- * matching). It runs exactly the gates the path validator's `ocspChecker`
+ * that ergonomic entry, which also handles DER/PEM decoding). It runs exactly the gates the path validator's `ocspChecker`
  * does: it locates the SingleResponse whose CertID binds this cert's serial to
  * its issuer (recomputing `issuerNameHash`/`issuerKeyHash` under the CertID's
  * own hashAlgorithm), confirms the responder is authorized (the issuing CA
@@ -1967,6 +2038,13 @@ function ocspChecker(responses) {
  * `time` either way. `time` must be a valid `Date`. A malformed response's parse
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
+ * `opts.requestNonce` is the nonce bytes the request carried. Given one, the response must echo it
+ * (RFC 9654 sec. 2.1, RFC 6960 sec. 4.4.1), compared in constant time, and `nonceMatched` reports
+ * the outcome: `true`, `false`, or `null` when no nonce was sent. An unechoed nonce takes a `good`
+ * to `unknown`, because a response that does not carry it answers an earlier question; a `revoked`
+ * keeps its status and carries `nonceMatched: false`, a stale revocation being no safer to accept.
+ * This is where the rule is applied, so every caller reaching this gate gets it.
+ *
  * The response is its DER bytes, a PEM string, or an unmodified
  * `pki.schema.ocsp.parseResponse` result. A REBUILT parsed response is refused. A
  * signature check has three parts (the signature, the algorithm that verifies it,
@@ -1995,14 +2073,23 @@ function ocspChecker(responses) {
  *   var v = await pki.path.verifyOcspResponse(der, cert, issuerCert, new Date());
  *   v.status;   // "good" | "revoked" | "unknown"
  */
+var _VERIFY_OCSP_OPTS = intrinsic.assign(intrinsic.create(null), { historicalMode: 1, requestNonce: 1 });
+
 async function verifyOcspResponse(response, cert, issuerCert, time, opts) {
-  var parsedResponse, subject, issuer;
+  var parsedResponse, subject, issuer, checkedOpts;
   try {
+    /** @internal The options go through the same door every other verb's do. Without it a
+     * misspelled `requestNonce` leaves the nonce unasked and the response is accepted against
+     * bytes nobody compared, and an accessor supplies one value to the check and another to the
+     * comparison. This verb is the acceptance gate, so both end at a response reported good. */
+    checkedOpts = guard.identifier.optionsObject(opts, E, "path/bad-input", "verifyOcspResponse: opts");
+    guard.identifier.assertKnownKeys(checkedOpts, _VERIFY_OCSP_OPTS, E, "path/bad-input",
+      "pki.path.verifyOcspResponse has an unknown option (the request nonce to bind against is `requestNonce`). The unknown option was: ");
     parsedResponse = _ocspFromBytes(response);
     subject = coerceCert(cert, "the certificate");
     issuer = coerceCert(issuerCert, "the issuer certificate");
   } catch (e) { return Promise.reject(e); }
-  var v = await _verifyOcspParsed(parsedResponse, subject, issuer, time, opts);
+  var v = await _verifyOcspParsed(parsedResponse, subject, issuer, time, checkedOpts);
   var out = guard.verdict.of(v);
   return guard.verdict.of(out, { valid: out.status === "good" });
 }
@@ -2023,7 +2110,21 @@ function _verifyOcspParsed(parsedResponse, cert, issuerCert, time, opts) {
   if (!guard.time.isDate(time) || isNaN(guard.time.instantOf(time))) {
     return Promise.reject(E("path/bad-input", "verifyOcspResponse: time must be a valid Date (the currency + responder-validity check date)"));
   }
-  function unbound(reason) { return guard.verdict.of({ status: "unknown", responderAuthorized: false, signatureValid: false, matched: false, thisUpdate: null, nextUpdate: null, reason: reason }); }
+  /** @internal Snapshotted in the synchronous prologue: the bytes compared are the bytes the caller
+   * passed, not what its BufferSource holds once the verify has awaited. A value that is not bytes
+   * at all is not a refusal, because a caller that asked for a nonce and supplied something that
+   * cannot be one has still asked: `wantNonce` stays set with nothing to compare, so the response
+   * cannot echo it and the verdict fails closed rather than passing the check by skipping it. */
+  var wantNonce = opts.requestNonce != null;
+  var nonce = (wantNonce && guard.bytes.isByteSource(opts.requestNonce))
+    ? guard.bytes.snapshotSource(opts.requestNonce, PathError, "path/bad-input", "opts.requestNonce")
+    : null;
+  /** @internal A verdict decided before the response is read is still a verdict, and the field
+   * that says what became of the nonce is on every one of them: absent is not the same answer as
+   * "no nonce was sent", which is what `null` says. */
+  function unbound(reason) {
+    return _withNonceRule(guard.verdict.of({ status: "unknown", responderAuthorized: false, signatureValid: false, matched: false, thisUpdate: null, nextUpdate: null, reason: reason }), parsedResponse, wantNonce, nonce);
+  }
   var boundName;
   try { boundName = dnEqual(cert.issuer.rdns, issuerCert.subject.rdns); }
   catch (e) { return Promise.reject(e); }
@@ -2040,13 +2141,39 @@ function _verifyOcspParsed(parsedResponse, cert, issuerCert, time, opts) {
     try { issuerKeyBits = ocspVerify.ocspKeyValue(issuerCert.subjectPublicKeyInfo.bytes); }
     catch (_e) { return unbound("the issuer public key could not be read to recompute the OCSP CertID"); }
     return ocspCore.evaluateResponse(parsedResponse, cert, issuerCtx, issuerKeyBits, issuerNameCandidates, time, opts.historicalMode === true).then(function (v) {
-      if (v.revoked) return guard.verdict.of({ status: "revoked", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, revocationReason: v.revoked.revocationReason, revocationTime: v.revoked.revocationTime, reason: v.revoked.reason });
-      if (v.sawGood) return guard.verdict.of({ status: "good", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: "good" });
-      return guard.verdict.of({ status: "unknown", responderAuthorized: v.responderAuthorized === true, signatureValid: v.signatureValid === true, matched: v.matched === true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: v.reason });
+      if (v.revoked) return _withNonceRule(guard.verdict.of({ status: "revoked", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, revocationReason: v.revoked.revocationReason, revocationTime: v.revoked.revocationTime, reason: v.revoked.reason }), parsedResponse, wantNonce, nonce);
+      if (v.sawGood) return _withNonceRule(guard.verdict.of({ status: "good", responderAuthorized: true, signatureValid: true, matched: true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: "good" }), parsedResponse, wantNonce, nonce);
+      return _withNonceRule(guard.verdict.of({ status: "unknown", responderAuthorized: v.responderAuthorized === true, signatureValid: v.signatureValid === true, matched: v.matched === true, thisUpdate: v.thisUpdate, nextUpdate: v.nextUpdate, reason: v.reason }), parsedResponse, wantNonce, nonce);
     });
   });
 }
 
+/** @internal RFC 9654 sec. 2.1 with RFC 6960 sec. 4.4.1: a client that sent a nonce is asking this
+ * responder this question now, and a response that does not echo it answers some earlier question.
+ * The rule lives here because this is the acceptance gate every OCSP consumer reaches, and a copy
+ * above it would leave a consumer that does not go through that copy with no check at all.
+ *
+ * An unechoed nonce takes a `good` to undetermined and leaves a `revoked` standing: a response
+ * saying the certificate is revoked is not made safe by being stale, so the verdict keeps its
+ * status and reports `nonceMatched: false` beside it. The comparison is constant-time. */
+function _withNonceRule(verdict, parsedResponse, wantNonce, requestNonce) {
+  if (!wantNonce) return guard.verdict.of(verdict, { nonceMatched: null });
+  var respNonce = _responseNonce(parsedResponse);
+  var matched = requestNonce !== null && respNonce != null &&
+    guard.crypto.constantTimeEqual(respNonce, requestNonce);
+  var out = guard.verdict.of(verdict, { nonceMatched: matched });
+  if (matched || out.status !== "good") return out;
+  return guard.verdict.of(out, { status: "unknown",
+    reason: "the OCSP response nonce does not echo the request nonce (RFC 9654 sec. 2.1)" });
+}
+
+function _responseNonce(parsedResponse) {
+  var br = parsedResponse && parsedResponse.basicResponse;
+  var exts = (br && br.responseExtensions) || [];
+  for (var i = 0; i < exts.length; i++) if (exts[i].oid === OID_OCSP_NONCE) return exts[i].nonce || null;
+  return null;
+}
+
 
 function softDecode(cert, extOid) {
   try { return decodeExt(cert, extOid); }
@@ -2857,7 +2984,12 @@ async function build(leaf, opts) {
     var aiaTransport = checkedTransport || httpTransport.https({ E: E, errPrefix: "path" });
     aiaCtx = {
       transport: aiaTransport,
-      transportGuardsAddresses: aiaTransport.blocksPrivateAddresses === true,
+      /** @internal Read off the slot, not the chain: `Function.prototype` carries whatever has
+       * been written to it for every function in the process, so a transport that declares
+       * nothing would otherwise be read as promising it filters the address it resolved, and a
+       * hostname taken from a certificate would be opened on that promise.
+       * @guard-via guard.identifier.declaresOwn */
+      transportGuardsAddresses: guard.identifier.declaresOwn(aiaTransport, "blocksPrivateAddresses"),
       tls: opts.tls || {},
       timeout: opts.aiaTimeout,
       maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "build: opts.maxResponseBytes", constants.LIMITS.PATH_AIA_MAX_RESPONSE_BYTES, { E: E, code: "path/bad-input", min: 1, max: constants.LIMITS.PATH_AIA_MAX_RESPONSE_BYTES }),
@@ -3027,11 +3159,17 @@ async function build(leaf, opts) {
   throw E("path/no-path", "build: no certification path from the leaf to any configured trust anchor could be assembled");
 }
 
+/** @internal The fetching checker composes the two gates below, so it loads after this module
+ * rather than beside it. The require sits in the call so the cycle resolves at first use, which is
+ * the documented reason an inline require is permitted. */
+function fetchingChecker(opts) { return require("./revocation-fetch").fetchingChecker(opts); }
+
 module.exports = {
   validate: validate,
   build: build,
   anchorFromCert: anchorFromCert,
   crlChecker: crlChecker,
+  fetchingChecker: fetchingChecker,
   ocspChecker: ocspChecker,
   verifyOcspResponse: verifyOcspResponse,
   PROCESSED_EXTENSIONS: PROCESSED_EXTENSIONS,