@blamejs/pki 0.6.14 → 0.6.15

package/lib/ocsp.js

@@ -25,14 +25,14 @@
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
-var pkiBuild = require("./pki-build");   // reqDenseArray: reject a sparse/nullish caller array as a typed ocsp/bad-input
+var pkiBuild = require("./pki-build");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var ocspSchema = require("./schema-ocsp");
 var pathValidate = require("./path-validate");
 var signScheme = require("./sign-scheme");
 var ocspVerify = require("./ocsp-verify");
-var ocspRequestVerify = require("./ocsp-request-verify");   // path-validate (required above) injects its signature engine into this seam at load
+var ocspRequestVerify = require("./ocsp-request-verify");
 var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var guard = require("./guard-all");
@@ -43,15 +43,9 @@ var OcspError = frameworkError.OcspError;
 var b = asn1.build;
 function O(name) { return oid.byName(name); }
 function _err(code, message, cause) { return new OcspError(code, message, cause); }
-// The domain error factory the shared sign-scheme resolver/signer throws through (kind ->
-// ocsp/<kind>), so its faults keep the ocsp/* codes.
 function _signE(kind, message, cause) { return new OcspError("ocsp/" + kind, message, cause); }
 
-// CertID / responder-ID hash algorithm name -> WebCrypto digest name. SHA-1 is the RFC 5019 interop
-// default for the CertID identity hash (not a signature; collision resistance is irrelevant to the
-// lookup, so SHAttered does not bar it, the same deliberate split path-validate makes).
 var HASH_WC = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
-// A CRLReason name -> its enumerated value (RFC 5280 sec. 5.3.1), reverse of pki.C.NAMES.CRL_REASON.
 var REASON_CODE = {};
 Object.keys(constants.NAMES.CRL_REASON).forEach(function (k) { REASON_CODE[constants.NAMES.CRL_REASON[k]] = parseInt(k, 10); });
 var OID_OCSP_NONCE = O("ocspNonce");
@@ -61,10 +55,6 @@ var OID_EXTENDED_REVOKE = O("ocspExtendedRevoke");
 function _digest(wcHash, buf) { return subtle.digest(wcHash, buf).then(function (h) { return Buffer.from(h); }); }
 function _certOf(arg, what) {
   var label = what || "a certificate";
-  // Re-derived from the bytes its parser read, like every other certificate door. A CertID is an
-  // IDENTITY -- the issuer's name and key hashed, plus the serial -- so a certificate that names one
-  // identity while carrying another's signed bytes would have this verb ask about, or answer for,
-  // a certificate nobody issued.
   return guard.parsed.acceptDerived(arg, "certificate", function (bytes) {
     var der = bytes;
     if (typeof bytes === "string") {
@@ -73,10 +63,6 @@ function _certOf(arg, what) {
     try { return x509.parse(der); } catch (e) { throw _err("ocsp/bad-input", label + " is not a well-formed X.509 certificate", e); }
   }, _err, "ocsp/bad-input", label);
 }
-// The response, always parsed from the bytes the caller handed over. See verify's own comment for
-// why an object cannot be accepted here: the three parts of a signature check would come from three
-// independently-chosen properties. The claim is detected on any of the parsed-response fields, so a
-// caller who passes one is told what happened, never given a byte-parse fault about its type.
 var _RESPONSE_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
 function _responseFromBytes(response) {
   return guard.parsed.fromTrustedSource(response, "ocspResponse", _RESPONSE_CLAIM, function (bytes) {
@@ -90,17 +76,13 @@ function _toDer(input, what) {
   if (typeof input === "string") { try { return ocspSchema.pemDecode(input); } catch (e) { throw _err("ocsp/bad-input", (what || "input") + " PEM could not be decoded", e); } }
   throw _err("ocsp/bad-input", (what || "input") + " must be a DER Buffer, Uint8Array, or PEM string");
 }
-// The subjectPublicKey BIT STRING value an issuerKeyHash / byKey KeyHash hashes over.
 function _keyValue(spkiDer) { return ocspVerify.ocspKeyValue(spkiDer); }
-// A non-critical id-pkix-ocsp-nonce Extension carrying the raw nonce (RFC 9654): the extnValue
-// OCTET STRING wraps the Nonce ::= OCTET STRING.
 function _nonceExt(nonceBytes) { return b.sequence([b.oid(OID_OCSP_NONCE), b.octetString(b.octetString(nonceBytes))]); }
 function _assertNonce(nonceBytes) {
   if (!Buffer.isBuffer(nonceBytes) || nonceBytes.length < 1 || nonceBytes.length > 128) {
     throw _err("ocsp/bad-input", "a nonce must be a Buffer of 1..128 octets (RFC 9654 sec. 2.1)");
   }
 }
-// The CertID SEQUENCE for target `cert` under `issuer`, hashing under `hashName` (RFC 6960 sec. 4.1.1).
 function _buildCertID(cert, issuer, hashName) {
   var wc = HASH_WC[hashName];
   if (!wc) throw _err("ocsp/bad-input", "unsupported CertID hashAlgorithm " + JSON.stringify(hashName) + " (sha1 / sha256 / sha384 / sha512)");
@@ -108,8 +90,6 @@ function _buildCertID(cert, issuer, hashName) {
     _digest(wc, issuer.subject.bytes),
     _digest(wc, _keyValue(issuer.subjectPublicKeyInfo.bytes)),
   ]).then(function (hashes) {
-    // SHA-1 carries NULL parameters (RFC 3279); a SHA-2 digest AlgorithmIdentifier omits them
-    // (RFC 5754 sec. 2). The CertID matcher keys on the OID and ignores parameters either way.
     var hashAlgId = hashName === "sha1" ? b.sequence([b.oid(O(hashName)), b.nullValue()]) : b.sequence([b.oid(O(hashName))]);
     return b.sequence([
       hashAlgId,
@@ -154,19 +134,11 @@ function _buildCertID(cert, issuer, hashName) {
  *   var der = await pki.ocsp.buildRequest({ cert: leafDer, issuer: caDer }, { nonce: true });
  */
 function buildRequest(query, opts) {
-  // Both arguments copied at entry and released when the call settles -- see the note on the same
-  // call in x509-sign. The request is assembled across several promise turns (each CertID is a
-  // hash), and opts carries byte fields -- the nonce and requestorName -- that reach the encoding.
   return guard.bytes.fixedCall(OcspError, "ocsp/bad-input", [
     [query, "the OCSP request query"], [opts, "pki.ocsp.buildRequest options"],
   ], _buildRequest);
 }
 
-// Every option pki.ocsp.buildRequest reads. `nonce` earns the named refusal: it is the
-// anti-replay binding, and a misspelling ships a request with no nonce at all, which the
-// responder answers happily and the caller cannot later bind to.
-// Taken from this verb's own @opts block, which is the published contract; a grep of the
-// function body misses `pem`, read by the shared emitter rather than here.
 var _BUILD_REQUEST_OPTS = {
   hashAlgorithm: 1, nonce: 1, pem: 1, profile: 1, requestorName: 1, signer: 1
 };
@@ -178,8 +150,6 @@ function _buildRequest(query, opts) {
   var lightweight = opts.profile === "lightweight";
   var hashName = opts.hashAlgorithm || "sha1";
   if (lightweight && hashName !== "sha1") throw _err("ocsp/bad-input", "the lightweight profile requires a SHA-1 CertID (RFC 5019 sec. 2.1.1)");
-  // A batch array is density-checked before the map below (which would otherwise skip a hole and reach
-  // Promise.all/b.sequence with an undefined); a single {cert,issuer} wraps to a dense one-element array.
   var queries = Array.isArray(query) ? pkiBuild.reqDenseArray(query, "queries", _err, "ocsp/bad-input") : [query];
   if (!queries.length) throw _err("ocsp/bad-input", "buildRequest needs at least one { cert, issuer } query");
   if (lightweight && queries.length !== 1) throw _err("ocsp/bad-input", "the lightweight profile permits exactly one Request (RFC 5019 sec. 2.1.1)");
@@ -200,14 +170,13 @@ function _buildRequest(query, opts) {
   })).then(function (requests) {
     var tbsChildren = [];
     if (opts.requestorName) {
-      // requestorName [1] EXPLICIT GeneralName; a Name is carried as directoryName [4].
       var nameDer = _nameDer(opts.requestorName);
       tbsChildren.push(b.explicit(1, b.contextConstructed(4, nameDer)));
     }
     tbsChildren.push(b.sequence(requests));
     var reqExts = [];
     if (opts.nonce) {
-      var nonceBytes = opts.nonce === true ? nodeCrypto.randomBytes(32) : opts.nonce;   // >= 32 octets, CSPRNG (RFC 9654 sec. 2.1)
+      var nonceBytes = opts.nonce === true ? nodeCrypto.randomBytes(32) : opts.nonce;
       _assertNonce(nonceBytes);
       reqExts.push(_nonceExt(nonceBytes));
     }
@@ -226,13 +195,9 @@ function _buildRequest(query, opts) {
 function _emitReq(der, opts) { return opts.pem ? ocspSchema.pemEncode(der, "OCSP REQUEST") : der; }
 function _nameDer(name) {
   if (guard.bytes.isByteSource(name)) return guard.bytes.snapshotSource(name, OcspError, "ocsp/bad-input", "requestorName");
-  if (name && name.bytes) return name.bytes;   // a parsed Name
+  if (name && name.bytes) return name.bytes;
   throw _err("ocsp/bad-input", "requestorName must be a DER Name BufferSource or a parsed Name");
 }
-// The RAW DER of a certificate that will be embedded verbatim (the responder cert in a
-// BasicOCSPResponse, the signer cert in a signed OCSPRequest). It must be supplied as bytes:
-// a parsed certificate does not retain its full DER encoding, and re-encoding it would risk
-// byte drift from the signed original, so a parsed cert is rejected rather than reconstructed.
 function _normCertDer(cert, what) {
   if (guard.bytes.isByteSource(cert)) return guard.bytes.snapshotSource(cert, OcspError, "ocsp/bad-input", what || "a certificate");
   if (typeof cert === "string") { try { return x509.pemDecode(cert); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " PEM could not be decoded", e); } }
@@ -279,19 +244,12 @@ function _normCertDer(cert, what) {
  *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
  *     { cert: responderCertDer, key: responderPkcs8 });
  */
-// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
-// synchronous because they read the responder's mutable cert and key.
 function sign(responseData, responder, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
-  // on the same call in x509-sign.
   return guard.bytes.fixedCall(OcspError, "ocsp/bad-input", [
     [responseData, "the OCSP responseData"], [responder, "the responder"], [opts, "pki.ocsp.sign options"],
   ], _sign);
 }
 
-// Every option pki.ocsp.sign reads. `nonce` here is the request nonce this response echoes back.
-// A misspelling emits a response that answers nobody's request, and the client that sent a nonce
-// then reads it as unbound.
 var _SIGN_OPTS = { embedCert: 1, extendedRevoke: 1, nonce: 1, pem: 1 };
 
 function _sign(responseData, responder, opts) {
@@ -302,27 +260,8 @@ function _sign(responseData, responder, opts) {
   if (!responder || responder.cert == null || responder.key == null) throw _err("ocsp/bad-input", "a responder must be { cert, key }");
   var respCertDer = _normCertDer(responder.cert, "the responder certificate");
   var respCert = _certOf(respCertDer, "the responder certificate");
-  // Read with the certificate, not after the awaits below. The ResponderID and the
-  // embedded certificate are both fixed from `respCert` here; the signature is made
-  // several promise turns later, so a `responder` whose key was replaced in between
-  // would produce a response naming one responder and signed by another key.
-  //
-  // Capturing the REFERENCE only closes half of that: it stops `responder.key = other`,
-  // but PKCS#8 arrives as caller-owned BYTES and a composite key as a caller-owned
-  // { mldsa, trad } object, either of which can be rewritten in place across the same
-  // gap with the same result -- a response carrying this responder's ID and certificate
-  // over a signature made by a different key, which no relying party can verify. So the
-  // material itself is snapshotted here, not just the binding to it. A CryptoKey is
-  // opaque and a PEM string is immutable, so both are already safe by reference.
   var ownedKeyBytes = [];
   var responderKey = _snapshotSignerKey(responder.key, ownedKeyBytes);
-  // The copy is cleared on the failing path as well as the succeeding one -- a wrong or
-  // malformed key is the case an attacker can force, so a success-only wipe would keep the
-  // secret exactly when it matters. The wipe covers the WHOLE window the copy exists, not
-  // just the signing call: the copy is taken before the response list, the responder ID, the
-  // SingleResponses, the dates, the nonce and the signature scheme are validated, and every
-  // one of those can fail. Attaching cleanup to signing alone leaves the secret in the heap
-  // on each of those earlier exits, which are the easiest ones for a caller to reach.
   function _wipeOwnedKey() {
     if (ownedKeyBytes.length) guard.secret.zeroizeAll(ownedKeyBytes, OcspError, "ocsp/bad-input", "the responder key copy");
     ownedKeyBytes.length = 0;
@@ -335,9 +274,6 @@ function _sign(responseData, responder, opts) {
     function (e) { _wipeOwnedKey(); throw e; });
 }
 
-// Everything from the key snapshot onward, so a single cleanup in the caller covers every
-// exit -- sync throw and async rejection alike -- rather than each fallible step needing to
-// remember. `responderKey` is the private copy; it is never the caller's object.
 function _signResponse(responseData, responder, respCert, respCertDer, responderKey, opts) {
   var responses = responseData.responses != null ? pkiBuild.reqDenseArray(responseData.responses, "responses", _err, "ocsp/bad-input") : [];
   if (!responses.length) throw _err("ocsp/bad-input", "a response MUST include at least one SingleResponse (RFC 6960 sec. 4.2.1)");
@@ -361,39 +297,18 @@ function _signResponse(responseData, responder, respCert, respCertDer, responder
     });
   });
 }
-// A date value -> Date, or null when absent (the caller defaults). An unparseable value is a
-// config-time error, not a silently-emitted Invalid Date: a NaN date would encode as a malformed
-// GeneralizedTime in a SIGNED response, and compare false against every currency bound on verify.
 function _asDate(d) {
   if (d == null) return null;
   var dt = guard.time.isDate(d) ? d : new Date(d);
   if (isNaN(guard.time.instantOf(dt))) throw _err("ocsp/bad-input", "an invalid date value " + JSON.stringify(d));
   return dt;
 }
-// A private copy of whatever signer-key material the caller owns, taken at the entry
-// point because signing happens several promise turns later (see `sign`). Bytes are
-// copied; a composite { mldsa, trad } is rebuilt with each component copied, since
-// rewriting a component is the same attack one level down. Anything else -- a CryptoKey,
-// a PEM string -- is not caller-mutable in a way that changes the key, so it rides as-is
-// rather than being coerced into a shape this function does not understand.
-// `owned` collects every buffer THIS function allocated, so the caller can clear them once
-// signing is done. A copy of a private key is a second copy of a secret, which is precisely
-// what this project's secret-lifetime discipline exists to avoid -- so the copy that closes
-// the aliasing window is wiped rather than left to the garbage collector. Only our own
-// allocations are listed: the caller's key is never written to.
 function _snapshotSignerKey(key, owned) {
   if (Buffer.isBuffer(key) || key instanceof Uint8Array) {   // allow:byte-source-narrow -- responder private key on the key-ownership contract (Buffer / Uint8Array / PEM / CryptoKey); widening keys is a separate root decision
     var copy = guard.bytes.snapshot(key, OcspError, "ocsp/bad-input", "the responder key");
     owned.push(copy);
     return copy;
   }
-  // The test is "is this a composite DESCRIPTOR", not "does it currently hold bytes". A
-  // composite whose components are both PEM strings carries nothing mutable inside it, but
-  // the OBJECT is still the caller's: reassigning `key.mldsa` after the call reaches the
-  // deferred signing operation just as rewriting a buffer would, and yields a response whose
-  // responder ID and embedded certificate describe one responder over a signature made by
-  // another key. So the container is always rebuilt, and each component is snapshotted by
-  // its own type -- bytes copied, an immutable PEM string passed through.
   if (key && typeof key === "object" && (key.mldsa != null || key.trad != null)) {
     return Object.assign({}, key, { mldsa: _snapshotSignerKey(key.mldsa, owned), trad: _snapshotSignerKey(key.trad, owned) });
   }
@@ -401,16 +316,13 @@ function _snapshotSignerKey(key, owned) {
 }
 
 function _responderID(rid, respCert) {
-  if (rid == null || rid === "byName") return Promise.resolve(b.explicit(1, b.raw(respCert.subject.bytes)));   // byName [1] EXPLICIT Name
+  if (rid == null || rid === "byName") return Promise.resolve(b.explicit(1, b.raw(respCert.subject.bytes)));
   if (rid === "byKey") return _digest("SHA-1", _keyValue(respCert.subjectPublicKeyInfo.bytes)).then(function (kh) { return b.explicit(2, b.octetString(kh)); });
   throw _err("ocsp/bad-input", "responderID must be \"byName\" or \"byKey\"");
 }
 function _buildSingleResponse(r, opts) {
   r = r || {};
   var certIdP;
-  // A pre-encoded CertID is spliced in RAW, so its type is checked rather than coerced:
-  // Buffer.from(20) would allocate twenty zero octets and emit a structurally broken
-  // CertID inside a response this responder then SIGNS.
   if (r.certID != null) certIdP = Promise.resolve(b.raw(guard.bytes.view(r.certID, OcspError, "ocsp/bad-input", "a response entry's certID")));
   else if (r.cert != null && r.issuer != null) certIdP = _buildCertID(_certOf(r.cert, "a response certificate"), _certOf(r.issuer, "a response issuer"), r.hashAlgorithm || "sha1");
   else return Promise.reject(_err("ocsp/bad-input", "each response entry needs { certID } or { cert, issuer }"));
@@ -424,16 +336,16 @@ function _buildSingleResponse(r, opts) {
 }
 function _defaultNextUpdate() { return new Date(Date.now() + constants.TIME.days(7)); }
 function _certStatusNode(status, opts) {
-  if (status == null || status === "good") return b.contextPrimitive(0, Buffer.alloc(0));   // good [0] IMPLICIT NULL
-  if (status === "unknown") return b.contextPrimitive(2, Buffer.alloc(0));                   // unknown [2] IMPLICIT NULL
+  if (status == null || status === "good") return b.contextPrimitive(0, Buffer.alloc(0));
+  if (status === "unknown") return b.contextPrimitive(2, Buffer.alloc(0));
   if (typeof status === "object" && status.revoked != null) {
-    var ri = [b.generalizedTime(_asDate(status.revoked))];   // revoked != null is guaranteed above
+    var ri = [b.generalizedTime(_asDate(status.revoked))];
     if (status.revocationReason != null) {
       var code = typeof status.revocationReason === "number" ? status.revocationReason : REASON_CODE[status.revocationReason];
       if (code == null) throw _err("ocsp/bad-input", "unknown revocationReason " + JSON.stringify(status.revocationReason));
-      ri.push(b.explicit(0, b.enumerated(BigInt(code))));   // revocationReason [0] EXPLICIT CRLReason
+      ri.push(b.explicit(0, b.enumerated(BigInt(code))));
     }
-    return b.contextConstructed(1, Buffer.concat(ri));       // revoked [1] IMPLICIT RevokedInfo
+    return b.contextConstructed(1, Buffer.concat(ri));
   }
   throw _err("ocsp/bad-input", "a response status must be \"good\", \"unknown\", or { revoked: <Date>, revocationReason? }");
 }
@@ -508,14 +420,9 @@ function buildErrorResponse(status) {
  *   var res = await pki.ocsp.verify(responseDer, { cert: leafDer, issuer: caDer });
  *   res.status;   // "good" | "revoked" | "unknown"
  */
-// Every option pki.ocsp.verify reads. `requestNonce` is the one worth refusing by name: it is
-// what binds the response to this request. A misspelling leaves nonceMatched null on a call
-// that did ask, and null is the value meaning "the client never asked".
 var _VERIFY_OPTS = { cert: 1, historicalMode: 1, issuer: 1, requestNonce: 1, time: 1 };
 
 function verify(response, opts) {
-  // This verb reports faults by rejecting, not throwing, so both entry guards run inside the
-  // same try and surface as a rejection like every other fault on this path.
   try {
     opts = guard.identifier.optionsObject(opts, _err, "ocsp/bad-input", "pki.ocsp.verify options");
     guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "ocsp/bad-input",
@@ -524,49 +431,18 @@ function verify(response, opts) {
   if (opts.cert == null || opts.issuer == null) return Promise.reject(_err("ocsp/bad-input", "verify requires opts.cert and opts.issuer"));
   var parsed, cert, issuerCert, time;
   try {
-    // The response is parsed from BYTES, always. A claimed-parsed response carries the signature,
-    // the algorithm that verifies it and the byte range it covers as three independent properties,
-    // so an object could pair one structure's tbsResponseDataBytes with another's signature -- and a
-    // signature the issuing CA made over a certificate it issued would verify as a ResponseData
-    // signature, returning status "good" for a certificate the responder never spoke about.
-    // Parsing here binds all three to one byte string. pki.schema.ocsp.parseResponse remains the
-    // parse-only route for a caller who wants the structure without a verdict.
     parsed = _responseFromBytes(response);
     cert = _certOf(opts.cert, "the target certificate");
     issuerCert = _certOf(opts.issuer, "the issuer certificate");
-    // The time drives the currency + responder-cert validity windows; an invalid Date fails closed
-    // via _asDate (a NaN compares false against every bound, silently disabling both), never defaults.
     time = opts.time == null ? new Date() : _asDate(opts.time);
   } catch (e) { return Promise.reject(e); }
-  // The object parsed HERE goes to the verdict verb, not the caller's argument again. It carries the
-  // parser's record, so the verdict verb re-derives from the same recorded bytes -- one snapshot,
-  // read by both. Passing the caller's argument a second time would take a SECOND snapshot of it,
-  // and a shared-memory view can differ between the two: the nonce compared below would belong to
-  // one response and the signature verified to another, which is the split this whole mechanism
-  // exists to close.
   return pathValidate.verifyOcspResponse(parsed, cert, issuerCert, time, { historicalMode: opts.historicalMode === true }).then(function (verdict) {
-    // A client that sent no nonce still gets the field, as null. Leaving it absent would make
-    // "not requested" indistinguishable from "the field is not there yet" for a consumer reading
-    // res.nonceMatched, and the three-state contract is the whole point: true bound, false not
-    // bound, null never asked. The verdict is copied rather than mutated, since it is the lower
-    // primitive's object and this layer does not own it.
     if (opts.requestNonce == null) return Object.assign({}, verdict, { nonceMatched: null });
-    // A client that sent a nonce binds it (RFC 9654 / RFC 5019 sec. 4): a missing or mismatched
-    // response nonce fails the verdict closed, even if the status/signature were otherwise good.
     var respNonce = _responseNonce(parsed);
     var reqNonce = guard.bytes.isByteSource(opts.requestNonce)
       ? guard.bytes.snapshotSource(opts.requestNonce, OcspError, "ocsp/bad-input", "opts.requestNonce") : null;
     var matched = respNonce != null && reqNonce != null && guard.crypto.constantTimeEqual(respNonce, reqNonce);
     var out = Object.assign({}, verdict, { nonceMatched: matched });
-    // The downgrade applies to `good` ONLY. `unknown` is the closed direction for a
-    // response claiming the certificate is fine, because an unmatched nonce means
-    // this is not an answer to this request and the "fine" may be stale. It is NOT
-    // the closed direction for `revoked`: revocation does not expire the way
-    // non-revocation does, so discarding a signed, current, authorized revoked
-    // verdict because it was replayed would hand a soft-fail caller the certificate
-    // the responder just refused -- turning the anti-replay defense into the thing
-    // that accepts a revoked certificate. `nonceMatched: false` still reports that
-    // this response was not bound to this request.
     if (!matched && verdict.status === "good") {
       return Object.assign(out, { status: "unknown", reason: "the OCSP response nonce does not echo the request nonce (RFC 9654)" });
     }
@@ -581,19 +457,13 @@ function _responseNonce(parsed) {
 }
 
 var _VERIFY_REQUEST_OPTS = { certs: 1 };
-// Parsed from BYTES so the signature, the algorithm that verifies it and the tbsRequest it covers
-// are bound to one byte string, the same discipline pki.ocsp.verify follows for a response. A
-// BufferSource is SNAPSHOT first: parseRequest surfaces tbsRequest / signature / embedded certs as
-// views into it, and the signature check awaits, so without a copy a caller could mutate the buffer
-// mid-verification and be judged on bytes other than the parser read. A PEM string decodes to a
-// fresh buffer already; parseRequest owns that decode and a non-bytes input is its typed refusal.
 function _requestFromBytes(request) {
   if (guard.bytes.isByteSource(request)) request = guard.bytes.snapshotSource(request, OcspError, "ocsp/bad-input", "the OCSP request");
   return ocspSchema.parseRequest(request);
 }
 function _reqVerdict(parsed, extra) {
   return {
-    valid: extra.signed === true && extra.signatureValid === true,   // canonical alias: the request was signed AND the signature verified
+    valid: extra.signed === true && extra.signatureValid === true,
     signed: extra.signed, signatureValid: extra.signatureValid,
     signerCert: extra.signerCert != null ? extra.signerCert : null,
     signerCerts: extra.signerCerts != null ? extra.signerCerts : [],
@@ -604,33 +474,13 @@ function _reqVerdict(parsed, extra) {
     reason: extra.reason != null ? extra.reason : null,
   };
 }
-// Collect EVERY candidate certificate whose key verified the request signature. RFC 6960 sec. 4.1.1
-// certs is an unordered SEQUENCE OF Certificate, and several may share the signing key (an expired
-// certificate carried beside its renewal), so all matches are surfaced rather than one
-// position-dependent pick: the responder builds a trusted path to one of them to select a usable
-// one, and no valid match is hidden behind an unusable one that happened to appear first. `strict` separates the
-// responder's own opts.certs (a malformed entry is its config error, a typed throw) from the
-// request's untrusted embedded certs (a malformed one is skipped, never fatal).
 async function _findRequestSigners(candidates, strict, parsed, sig, sigBits) {
   var parsedList = [];
   for (var i = 0; i < candidates.length; i++) {
     try { parsedList.push({ der: candidates[i], cert: x509.parse(candidates[i]) }); }
     catch (e) { if (strict) throw _err("ocsp/bad-signer-cert", "an opts.certs entry does not parse as an X.509 certificate", e); }
   }
-  // The certs surfaced for path building are the PARSEABLE ones: a malformed embedded entry (skipped
-  // above rather than fatal) is excluded so it is never handed to pki.path.build as a candidate.
   var parseable = parsedList.map(function (p) { return p.der; });
-  // signerCerts is every candidate whose key VERIFIES the request signature, identified by the
-  // verification itself rather than by comparing encoded key bytes. A request carries one signature
-  // under one key, but that key can appear across several certificates in the unordered certs field
-  // (an expired certificate beside its renewal), and the one key can be encoded differently between
-  // them -- rsaEncryption with NULL versus absent parameters, an EC point compressed versus
-  // uncompressed -- so a byte comparison would drop a genuine match, while a coincidental byte match
-  // under a different algorithm would be a false one. Verifying each candidate answers both exactly,
-  // through the algorithm-confusion gate (RFC 9814 sec. 4) in the shared engine. The work is bounded:
-  // the parser already caps the certificate count at OCSP_MAX_CERTS, and the engine returns false
-  // (never throws) for a candidate whose key does not match the signature, so a non-signer is skipped
-  // rather than aborting the verdict.
   var matches = [];
   for (var j = 0; j < parsedList.length; j++) {
     if (await ocspRequestVerify.verifyRequestSignature(sig.signatureAlgorithm, sigBits, parsedList[j].cert.subjectPublicKeyInfo.bytes, parsed.tbsRequestBytes)) {
@@ -639,11 +489,6 @@ async function _findRequestSigners(candidates, strict, parsed, sig, sigBits) {
   }
   return { matches: matches, parseable: parseable };
 }
-// The verdict from `_findRequestSigners`: signerCerts is every match (so the caller's trust decision
-// does not depend on ordering), signerCert / signerSubject the first for the common single-signer
-// case. `certs` is every PARSEABLE certificate the request carried (or opts.certs supplied), so the
-// responder has the intermediates it needs to chain a signer to an anchor -- those do not sign the
-// request, so they never appear in signerCerts. No match is signatureValid:false with the reason.
 function _signerVerdict(parsed, found, failReason) {
   if (!found.matches.length) return _reqVerdict(parsed, { signed: true, signatureValid: false, certs: found.parseable, reason: failReason });
   return _reqVerdict(parsed, {
@@ -714,10 +559,7 @@ async function verifyRequest(request, opts) {
     return _reqVerdict(parsed, { signed: false, signatureValid: false,
       reason: "the OCSP request is unsigned (RFC 6960 sec. 4.1.1 makes optionalSignature OPTIONAL); no requestor is authenticated" });
   }
-  // sig.signature is the raw signature the parser already refused unless octet-aligned; the seam
-  // re-checks alignment, so it is handed the BIT STRING shape the seam verifies.
   var sigBits = { unusedBits: 0, bytes: sig.signature };
-  // Prefer the certificates the request carries; fall back to opts.certs only when it carries none.
   if (sig.certs.length) {
     return _signerVerdict(parsed, await _findRequestSigners(sig.certs, false, parsed, sig, sigBits),
       "the OCSP request signature does not verify over tbsRequest under any certificate the request carries (RFC 6960 sec. 4.1.1)");