@blamejs/pki 0.5.7 → 0.5.9

package/lib/path-validate.js

@@ -88,7 +88,7 @@ var OID = {
   caIssuers: oid.byName("caIssuers"),
 };
 
-// The set of extension OIDs the validator PROCESSES -- an unrecognized critical
+// The set of extension OIDs the validator processes. An unrecognized critical
 // extension outside this set fails the path (6.1.4(o), 6.1.5(e)).
 // extendedKeyUsage is recognized: the critical form is legal (4.2.1.12) and
 // appears in the wild (RFC 6960 4.2.2.2 delegated OCSP responders); its
@@ -102,7 +102,7 @@ var PROCESSED_EXTENSIONS = {};
 // validateCriticalExtensionStructure via the registered decoder. freshestCRL
 // stays OUT: sec. 4.2.1.15 requires it non-critical and the validator does not
 // consult it (no delta merge), so a critical instance fails unrecognized.
-// qcStatements is deliberately NOT processed: a critical QC statement (QcLimitValue reliance limit,
+// qcStatements is deliberately left unprocessed: a critical QC statement (QcLimitValue reliance limit,
 // QcType certificate purpose) asserts qualified-certificate semantics a relying party MUST enforce, and
 // this validator does not enforce them (nor expose a handler to). Marking it processed would let a caller
 // treat a certificate as valid outside its asserted critical QC constraints, so a critical qcStatements
@@ -113,7 +113,7 @@ var PROCESSED_EXTENSIONS = {};
  OID.extKeyUsage, OID.cRLDistributionPoints].
   forEach(function (o) { PROCESSED_EXTENSIONS[o] = true; });
 // Frozen after seeding: this exact object is both consulted by the critical-extension check here and
-// exported (for pki.lint to stay consistent). A caller must not be able to add an OID -- doing so
+// exported (for pki.lint to stay consistent). A caller must not be able to add an OID, because that
 // would make an attacker's critical, decoder-less extension pass as "processed" and skip both the
 // unrecognized-critical check and structural validation. Freezing makes any such write a no-op.
 Object.freeze(PROCESSED_EXTENSIONS);
@@ -130,11 +130,11 @@ var SIG_ALGS = {};
 // NULL must be present -- RSASSA-PKCS1-v1_5, RFC 4055 sec. 5) or "absent" (parameters
 // must be omitted -- ECDSA/EdDSA/ML-DSA, RFC 5758/8410). A cert deviating from
 // its algorithm's required shape is malformed and rejected before verify.
-// `sameKeyOid` marks the one-shot families whose PUBLIC-KEY algorithm OID is the
-// SAME as the signature algorithm OID -- EdDSA, ML-DSA, SLH-DSA. For these, Node's
-// WebCrypto imports an SPKI of ANOTHER type under the requested name and verifies
-// with the real key (it does NOT reject a mismatched SPKI the way it does for
-// RSA/ECDSA), so the issuer-key <-> signature-algorithm consistency (RFC 9814 sec. 4)
+// `sameKeyOid` marks the one-shot families whose public-key algorithm OID equals
+// the signature algorithm OID: EdDSA, ML-DSA, SLH-DSA. For these, Node's
+// WebCrypto imports an SPKI of another type under the requested name and verifies
+// with the real key (unlike RSA/ECDSA, where a mismatched SPKI is refused at
+// import), so the issuer-key <-> signature-algorithm consistency (RFC 9814 sec. 4)
 // must be checked structurally: the SPKI OID must equal the signature OID.
 function _sig(name, verify, imp, params, ecdsa, sameKeyOid) {
   var entry = { verify: verify, imp: imp, params: params };
@@ -223,9 +223,9 @@ function resolveRsaPss(paramsBytes) {
   // RSASSA-PSS-params ::= SEQUENCE { hashAlgorithm [0] DEFAULT sha1,
   //   maskGenAlgorithm [1] DEFAULT mgf1SHA1, saltLength [2] INTEGER DEFAULT 20,
   //   trailerField [3] DEFAULT 1 }. WebCrypto verifies with MGF1 keyed to the
-  //   SAME hash as the signature and trailerField 0xBC (1); any declared value
-  //   that deviates cannot be honored, so it is REJECTED rather than verified
-  //   under WebCrypto's defaults (a signatureAlgorithm bypass otherwise).
+  //   same hash as the signature and trailerField 0xBC (1). A declared value
+  //   that deviates cannot be honored, so it is rejected; verifying it under
+  //   WebCrypto's defaults would be a signatureAlgorithm bypass.
   // RFC 4055 DEFAULTs are SHA-1 (hashAlgorithm and mgf1SHA1). Because SHA-1 is
   // rejected, an absent hashAlgorithm or maskGenAlgorithm would resolve to SHA-1
   // and must be REJECTED -- a supported PSS AlgorithmIdentifier must state both
@@ -244,8 +244,8 @@ function resolveRsaPss(paramsBytes) {
     if (f.tagNumber > 3 || f.tagNumber <= pssLastTag) throw E("path/unsupported-algorithm", "RSASSA-PSS-params has an unexpected, duplicate, or out-of-order field [" + f.tagNumber + "]");
     pssLastTag = f.tagNumber;
     // Every RSASSA-PSS-params field is an EXPLICIT [n] wrapper (constructed)
-    // around EXACTLY ONE value (an AlgorithmIdentifier or an INTEGER); a
-    // primitive/childless or multi-child context field is malformed -- reading
+    // around exactly one value (an AlgorithmIdentifier or an INTEGER); a
+    // primitive/childless or multi-child context field is malformed: reading
     // f.children[0] and ignoring the rest would accept non-DER parameters.
     if (!f.children || f.children.length !== 1) throw E("path/unsupported-algorithm", "malformed RSASSA-PSS parameter field [" + f.tagNumber + "] (an EXPLICIT wrapper carries exactly one value)");
     if (f.tagNumber === 0) {
@@ -305,7 +305,7 @@ function resolveDescriptor(sigAlg) {
 // RFC 9814 sec. 4 issuer-key <-> signature-algorithm consistency (algorithm-confusion
 // defense). For the one-shot families whose public key shares the signature OID
 // (EdDSA, ML-DSA, SLH-DSA), Node's WebCrypto imports an SPKI of a DIFFERENT type
-// under the requested name and verifies with the real key -- so an Ed25519-signed
+// under the requested name and verifies with the real key, so an Ed25519-signed
 // certificate labelled SLH-DSA would otherwise validate. Enforce structurally:
 // the issuer SPKI's algorithm OID MUST equal the signature algorithm OID. (For
 // RSA/ECDSA -- different key vs signature OIDs -- WebCrypto's import already rejects
@@ -331,9 +331,9 @@ function assertKeyMatchesSigAlg(spkiBytes, sigOid, d) {
 // compositeKeyUsageCheck (below) enforces the sec. 5.2 signature-only keyUsage restriction.
 
 // draft-ietf-lamps-pq-composite-sigs sec. 5.2: a certificate whose SubjectPublicKeyInfo
-// carries a composite ML-DSA OID, IF it has a keyUsage extension, MUST assert at least
-// one signature bit (digitalSignature / nonRepudiation / keyCertSign / cRLSign) and MUST
-// NOT assert any encryption or key-establishment bit -- a composite ML-DSA key is a
+// carries a composite ML-DSA OID, if it has a keyUsage extension, MUST assert at least
+// one signature bit (digitalSignature / nonRepudiation / keyCertSign / cRLSign) and
+// MUST NOT assert any encryption or key-establishment bit. A composite ML-DSA key is a
 // signature-only key (ML-DSA cannot encrypt or agree, so a "dual usage" key is forbidden
 // even when the traditional component could encrypt). The caller invokes this only for a
 // composite-keyed certificate; an absent keyUsage places no restriction (RFC 5280 4.2.1.3).
@@ -359,9 +359,9 @@ function compositeKeyUsageCheck(cert) {
 var ML_KEM_OIDS = {};
 ["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) { ML_KEM_OIDS[oid.byName(n)] = true; });
 
-// RFC 9935 sec. 5: a certificate whose SubjectPublicKeyInfo carries an id-ml-kem-* OID, IF it
-// has a keyUsage extension, MUST assert keyEncipherment as the ONLY key usage set -- an ML-KEM
-// key is a key-establishment-only key (it cannot sign or agree, so no other bit is legitimate,
+// RFC 9935 sec. 5: a certificate whose SubjectPublicKeyInfo carries an id-ml-kem-* OID, if it
+// has a keyUsage extension, MUST assert keyEncipherment as the only key usage set, since an
+// ML-KEM key is a key-establishment-only key (it cannot sign or agree, so no other bit is legitimate,
 // and an unnamed/reserved bit set alongside keyEncipherment is equally forbidden). The caller
 // invokes this only for an ML-KEM-keyed certificate; an absent keyUsage places no restriction
 // (RFC 5280 sec. 4.2.1.3). This also makes an ML-KEM "CA" (keyCertSign) an explicit reject.
@@ -380,12 +380,13 @@ function kemKeyUsageCheck(cert) {
   return { ok: true };
 }
 
-// Import a descriptor's verification key, validating an EdDSA point FIRST: node/OpenSSL import a
-// low-order (e.g. identity or all-zeroes) Ed25519/Ed448 SPKI without complaint and such a key
-// verifies a forged signature. This is the ONE seam both the certificate path and the revocation
-// (CRL / OCSP-response) path import through, so neither can skip the point gate -- a low-order
-// issuer / responder key fails the caller closed (a rejected promise the caller maps to a bad
-// verdict), never verifying a forged chain or a forged revocation.
+// Import a descriptor's verification key, validating an EdDSA point before the import runs:
+// node/OpenSSL import a low-order (e.g. identity or all-zeroes) Ed25519/Ed448 SPKI without
+// complaint and such a key verifies a forged signature. Both the certificate path and the
+// revocation (CRL / OCSP-response) path import through this single seam, so neither can skip
+// the point gate; a low-order issuer / responder key fails the caller closed (a rejected
+// promise the caller maps to a bad verdict), never verifying a forged chain or a forged
+// revocation.
 function _importVerifyKey(spkiBytes, d) {
   try {
     if (d.eddsa) edwardsPoint.validateSpki(spkiBytes, d.eddsa, PathError, "path/bad-signature");
@@ -474,7 +475,7 @@ function requireCriticalExt(ext, name, checks) {
 // Split an addr-spec into [localPart, host] at its single "@". Returns null when
 // there is no "@" (a bare host/domain constraint), or "ambiguous" when there are
 // multiple "@": a conformant certificate rfc822Name is a simple addr-spec with
-// EXACTLY ONE "@" (RFC 5280 sec. 4.2.1.6 deprecates the quoted local part, and an
+// exactly one "@" (RFC 5280 sec. 4.2.1.6 deprecates the quoted local part, and an
 // addr-spec domain never contains "@"), so a multi-"@" mailbox like
 // "a@b"@example.com cannot be split reliably and must fail closed.
 function splitMailbox(addr) {
@@ -511,8 +512,8 @@ function emailMatch(constraint, mailbox) {
 }
 
 // Strip a single trailing dot (the absolute-FQDN root label) so "evil.com."
-// and "evil.com" compare equal -- otherwise a trailing-dot SAN would escape a
-// dNSName constraint.
+// and "evil.com" compare equal. Without that, a trailing-dot SAN would escape
+// a dNSName constraint.
 function stripTrailingDot(s) { return s.charAt(s.length - 1) === "." ? s.slice(0, -1) : s; }
 
 // Host-suffix match with the RFC 5280 sec. 4.2.1.10 leading-period rule shared by
@@ -527,7 +528,7 @@ function hostConstraintMatch(constraint, host) {
 // Is `host` a fully qualified domain name (as a URI host constraint requires,
 // RFC 5280 sec. 4.2.1.10)? A dotless single label (localhost), an IPv4/IPv6 literal,
 // or a value carrying non-hostname characters (a scheme "://", a path "/", a
-// port ":") is NOT a FQDN and cannot be matched against a domain-suffix
+// port ":") is not a FQDN and cannot be matched against a domain-suffix
 // constraint. Only [A-Za-z0-9.-] with at least one dot qualifies.
 function isFqdnHost(host) {
   var h = stripTrailingDot(host);
@@ -538,12 +539,12 @@ function isFqdnHost(host) {
 }
 
 // A URI constraint applies to the host part: a leading "." matches subdomains
-// only; a bare host matches that host EXACTLY (not subdomains, per sec. 4.2.1.10).
-// BOTH sides must be a fully qualified domain name: a URI SAN with no host / an
-// IP literal, OR a malformed constraint that is not an FQDN (e.g. a full URI
-// "http://blocked.example" rather than "blocked.example"), cannot be evaluated
-// and returns "unsupported" so the caller fails closed rather than letting the
-// name silently escape a critical constraint by never matching.
+// only; a bare host matches that host exactly (not subdomains, per sec. 4.2.1.10).
+// Both sides must be a fully qualified domain name. A URI SAN with no host / an
+// IP literal, or a malformed constraint that is not an FQDN (e.g. a full URI
+// "http://blocked.example" where the required form is "blocked.example"), cannot
+// be evaluated, so it returns "unsupported" and the caller fails closed; reporting
+// it as a plain non-match would let the name silently escape a critical constraint.
 function uriMatch(constraint, uri) {
   var host = uriHost(uri);
   if (host === null) return "unsupported";
@@ -560,10 +561,10 @@ function uriHost(uri) {
   if (!m) return null;
   var authority = m[1];
   // authority = [ userinfo "@" ] host [ ":" port ]. RFC 3986 userinfo does not
-  // contain a raw "@", so a conformant authority has AT MOST ONE "@". Multiple
-  // "@" is ambiguous -- the host cannot be determined reliably -- so fail CLOSED
-  // (null -> uriMatch returns "unsupported" -> the caller rejects the path)
-  // rather than guess a host that could slip a URI name constraint.
+  // contain a raw "@", so a conformant authority has at most one "@". With more
+  // than one the host cannot be determined reliably, so this fails closed
+  // (null -> uriMatch returns "unsupported" -> the caller rejects the path);
+  // guessing a host could slip a URI name constraint.
   var firstAt = authority.indexOf("@");
   if (firstAt !== authority.lastIndexOf("@")) return null;
   if (firstAt !== -1) authority = authority.slice(firstAt + 1);
@@ -583,9 +584,9 @@ function ipMatch(constraint, addr) {
 
 // Does GeneralName-like {tagNumber, value} match a constraint base of the same
 // form? Returns true/false for a supported form, null when the forms differ
-// (not comparable), or the string "unsupported" when the forms are the SAME
-// but this validator does not implement that form's comparison -- the caller
-// must then fail closed rather than treat it as "no match".
+// (not comparable), or the string "unsupported" when the forms match but this
+// validator does not implement that form's comparison. The caller must then fail
+// closed: an unenforceable constraint cannot be read as "no match".
 function nameMatchesConstraint(gnTag, gnValue, base) {
   if (base.tagNumber !== gnTag) return null;         // different form -> not comparable
   switch (gnTag) {
@@ -616,8 +617,8 @@ function certNameForms(cert) {
   var san = decodeExt(cert, OID.subjectAltName);
   var hasRfc822San = false;
   if (san) {
-    // Preserve EVERY SAN entry, including a form whose value the validator does
-    // not decode (x400Address [3] / ediPartyName [5]) -- dropping it would let a
+    // Preserve every SAN entry, including a form whose value the validator does
+    // not decode (x400Address [3] / ediPartyName [5]); dropping one would let a
     // critical constraint of that same unsupported form pass unenforced. The
     // constraint check fails such a form closed (name-constraint-unsupported).
     san.value.names.forEach(function (nm) {
@@ -629,10 +630,10 @@ function certNameForms(cert) {
     });
   }
   // RFC 5280 sec. 4.2.1.10: the legacy emailAddress in the subject DN is checked as
-  // an rfc822Name UNLESS the SAN already carries the email identity as an
-  // rfc822Name entry. A SAN of a DIFFERENT form (e.g. dNSName only) does NOT
-  // cover the email, so the subject-DN email must still be constrained -- else an
-  // excluded/non-permitted mailbox would slip an rfc822Name constraint.
+  // an rfc822Name unless the SAN already carries the email identity as an
+  // rfc822Name entry. A SAN of a different form (e.g. dNSName only) does not
+  // cover the email, so the subject-DN email must still be constrained. Otherwise
+  // an excluded/non-permitted mailbox would slip an rfc822Name constraint.
   if (!hasRfc822San) {
     cert.subject.rdns.forEach(function (rdn) {
       rdn.forEach(function (atv) {
@@ -645,17 +646,17 @@ function certNameForms(cert) {
 }
 
 // Check a cert's own names against the accumulated constraints. `excluded` is
-// a UNION (any match rejects). `permitted` is the INTERSECTION of every
+// a union (any match rejects). `permitted` is the intersection of every
 // absorbing cert's permittedSubtrees (6.1.4(g)): the permitted set is tracked
-// as one GENERATION per absorbing cert, and a name of form F must match a
-// subtree of form F in EVERY generation that constrains form F. A flat pool
-// would compute the UNION -- letting a subordinate CA BROADEN what its parent
+// as one generation per absorbing cert, and a name of form F must match a
+// subtree of form F in every generation that constrains form F. A flat pool
+// would compute the union, letting a subordinate CA broaden what its parent
 // permitted (a name-constraint bypass).
 function checkNameConstraints(state, cert) {
   var forms = certNameForms(cert);
   // Excluded: any match -> reject. A constraint of the same form the validator
   // cannot compare ("unsupported") means a critical exclusion it cannot
-  // enforce -> fail closed rather than treat it as "no match".
+  // enforce, so it fails closed on the same footing as a match.
   for (var e = 0; e < state.excludedSubtrees.length; e++) {
     var ex = state.excludedSubtrees[e];
     for (var i = 0; i < forms.length; i++) {
@@ -703,7 +704,7 @@ function absorbNameConstraints(state, decoded) {
 function rootNode() {
   return { depth: 0, validPolicy: OID.anyPolicy, qualifierSet: [], expectedPolicySet: [OID.anyPolicy], children: [], parent: null };
 }
-// A deep copy of the valid-policy tree WITHOUT the internal `parent` back-pointer,
+// A deep copy of the valid-policy tree that omits the internal `parent` back-pointer,
 // so the structured verdict returned to callers is acyclic (JSON.stringify-safe).
 // The `parent` link is an implementation detail of the 6.1.3 processing, not part
 // of the RFC 5280 valid_policy_tree a consumer inspects.
@@ -778,7 +779,7 @@ function initialize(certs, params, seeds) {
     policyNodeCount: 1,
     maxPolicyNodes: params.maxPolicyNodes !== undefined ? params.maxPolicyNodes : constants.LIMITS.PATH_MAX_POLICY_NODES,
     // Each absorbing cert's permittedSubtrees is one generation; a name must be
-    // admitted by EVERY generation (intersection). An initial seed is generation 0.
+    // admitted by every generation (intersection). An initial seed is generation 0.
     permittedGenerations: seeds.permitted.length ? [seeds.permitted] : [],
     excludedSubtrees: seeds.excluded,
     explicitPolicy: params.initialExplicitPolicy ? 0 : n + 1,
@@ -796,8 +797,8 @@ function initialize(certs, params, seeds) {
 
 // self-issued = subject DN equals issuer DN. dnEqual throws on a NUL/control
 // DN (CVE-2009-2408); a malformed-DN cert is never "self-issued" (and is failed
-// by the name-chaining check), so swallow the throw rather than reject the
-// whole validate() promise from these unwrapped call sites.
+// by the name-chaining check), so the throw is swallowed here, keeping it from
+// rejecting the whole validate() promise at these unwrapped call sites.
 function selfIssued(cert) {
   try { return dnEqual(cert.subject.rdns, cert.issuer.rdns); }
   catch (_e) { return false; }
@@ -812,8 +813,8 @@ function processPolicies(state, cert, i, checks) {
     var policies = cp.value;
     var depth = i - 1;
     // anyPolicy processing is active only while inhibit_anyPolicy > 0, or for a
-    // self-issued non-final cert -- this gates ONLY the (d)(2) expansion of a
-    // cert-asserted anyPolicy. 4.2.1.14 inhibition is implemented entirely by
+    // self-issued non-final cert. What the gate covers is the (d)(2) expansion of
+    // a cert-asserted anyPolicy and nothing more. 4.2.1.14 inhibition rests entirely on
     // that gate: a depth-(i-1) anyPolicy node created while processing was
     // active remains matchable in (d)(1)(ii).
     var anyPolicyActive = state.inhibitAnyPolicy > 0 || (i < state._n && selfIssued(cert));
@@ -829,7 +830,7 @@ function processPolicies(state, cert, i, checks) {
         }
       });
       if (!matched) {
-        // 6.1.3(d)(1)(ii): no expected-policy match -- create the node from a
+        // 6.1.3(d)(1)(ii): with no expected-policy match, create the node from a
         // depth-(i-1) anyPolicy node. The RFC runs this step UNCONDITIONALLY
         // (no inhibit clause); gating it would false-reject a path whose
         // specific policy chains through a legitimately created anyPolicy node.
@@ -901,8 +902,8 @@ function updateWorkingKey(state, cert) {
     state.workingPublicKeyParameters = null;
   }
   // When this cert's SPKI omits its algorithm parameters but the working set
-  // carries inherited ones, store a reconstructed SPKI so the next signature
-  // verify can import a complete key rather than failing on the bare bytes.
+  // carries inherited ones, store a reconstructed SPKI: the next signature verify
+  // needs a complete key and would fail on the bare bytes.
   if (isNullOrAbsentParams(keyAlg.parameters) && state.workingPublicKeyParameters) {
     state.workingPublicKey = spliceSpkiParameters(cert.subjectPublicKeyInfo, keyAlg.oid, state.workingPublicKeyParameters);
   } else {
@@ -915,7 +916,7 @@ function updateWorkingKey(state, cert) {
 // carrying an extendedKeyUsage must assert every one (or anyExtendedKeyUsage).
 // Applied to the TARGET cert (its own purposes) AND to every intermediate CA
 // (EKU chaining: an EKU on a CA constrains the purposes below it), so marking
-// extKeyUsage a PROCESSED critical extension is sound -- the semantic gate runs
+// extKeyUsage a processed critical extension is sound. The semantic gate runs
 // wherever the extension appears, never only on the leaf. A cert with no EKU is
 // unconstrained. Returns true if the cert FAILS the required-purpose check.
 function ekuPurposeFails(cert, requiredEku, checks) {
@@ -954,7 +955,7 @@ function prepareNext(state, cert, i, checks) {
   state.workingIssuerName = cert.subject;
   updateWorkingKey(state, cert);
 
-  // (g) name constraints absorb (AFTER this cert's own names were checked).
+  // (g) name constraints absorb, once this cert's own names have been checked.
   var nc;
   try { nc = decodeExt(cert, OID.nameConstraints); }
   catch (e) { checks.push({ name: "nameConstraints", ok: false, code: pathCode(e, "path/bad-name-constraints") }); return { fatal: true, error: e }; }
@@ -986,7 +987,7 @@ function prepareNext(state, cert, i, checks) {
   if (iapCritErr) return { fatal: true, error: iapCritErr };
   if (iap && iap.value < state.inhibitAnyPolicy) state.inhibitAnyPolicy = iap.value;
 
-  // (k) basicConstraints cA gate -- the single authoritative CA check.
+  // (k) basicConstraints cA gate, the single authoritative CA check.
   var bc;
   try { bc = decodeExt(cert, OID.basicConstraints); }
   catch (e) { checks.push({ name: "basicConstraints", ok: false, code: "path/bad-basic-constraints" }); return { fatal: true, error: e }; }
@@ -995,7 +996,7 @@ function prepareNext(state, cert, i, checks) {
     return { fatal: true, error: E("path/not-a-ca", "intermediate certificate is not a CA (basicConstraints cA is not TRUE, RFC 5280 6.1.4(k))") };
   }
   // 4.2.1.9: a CA certificate used to validate certificate signatures MUST mark
-  // basicConstraints critical. A non-critical cA:TRUE is non-conforming -- a
+  // basicConstraints critical. A non-critical cA:TRUE is non-conforming. A
   // relying party that skips non-critical extensions would not see the CA bit.
   var bcCritErr = requireCriticalExt(bc, "basicConstraints", checks);
   if (bcCritErr) return { fatal: true, error: bcCritErr };
@@ -1022,9 +1023,9 @@ function applyPolicyMappings(state, mappings, i) {
   if (state.policyMapping > 0) {
     // 6.1.4(b)(1): for each depth-i node whose valid_policy is an ID-P that
     // the extension maps, REPLACE its expected_policy_set with the SET of
-    // subjectDomainPolicy values mapped from that ID-P (not append -- retaining
-    // the pre-mapping policy would let a later cert satisfy the chain by
-    // asserting the mapped-away policy).
+    // subjectDomainPolicy values mapped from that ID-P. Appending would retain
+    // the pre-mapping policy, letting a later cert satisfy the chain by
+    // asserting the mapped-away policy.
     var mappedFrom = {};   // issuerDomainPolicy -> [subjectDomainPolicy, ...]
     mappings.forEach(function (m) { (mappedFrom[m.issuerDomainPolicy] = mappedFrom[m.issuerDomainPolicy] || []).push(m.subjectDomainPolicy); });
     var depthI = leavesAt(state.validPolicyTree, depth);
@@ -1034,7 +1035,7 @@ function applyPolicyMappings(state, mappings, i) {
       if (idpNodes.length) {
         idpNodes.forEach(function (nd) { nd.expectedPolicySet = mappedFrom[idp].slice(); });
       } else {
-        // 6.1.4(b)(1): no depth-i ID-P node, but a depth-i anyPolicy node -- GENERATE
+        // 6.1.4(b)(1): with no depth-i ID-P node but a depth-i anyPolicy node, generate
         // the missing ID-P node under the anyPolicy node's parent with the mapped
         // expected set (else an anyPolicy-only CA loses the mapping).
         anyNodes.forEach(function (anyNode) {
@@ -1045,7 +1046,7 @@ function applyPolicyMappings(state, mappings, i) {
   } else {
     // 6.1.4(b)(2), policy_mapping == 0: delete every depth-i node whose
     // valid_policy is a mapped ID-P, then prune. A prior mapping in the same
-    // extension may have already emptied the tree -- stop if it is gone.
+    // extension may have already emptied the tree, so stop if it is gone.
     var mappedSet = {};
     mappings.forEach(function (m) { mappedSet[m.issuerDomainPolicy] = true; });
     // Coverage residual -- unreachable today: applyPolicyMappings is invoked once per
@@ -1067,14 +1068,14 @@ function applyPolicyMappings(state, mappings, i) {
   }
 }
 
-// policyMappings is semantically processed ONLY in the prepare-for-next step
+// policyMappings is semantically processed only in the prepare-for-next step
 // (sec. 6.1.4(a),(b)), which does not run for the target certificate. It is also
-// SHOULD-be-non-critical (sec. 4.2.1.5), so a CRITICAL policyMappings on the target
-// is both anomalous and unprocessed -- it must fail closed (sec. 6.1.5(f)) rather
-// than let, e.g., a mapping to/from anyPolicy slip past the sec. 6.1.4(a) rejection
+// SHOULD-be-non-critical (sec. 4.2.1.5), so a critical policyMappings on the target
+// is both anomalous and unprocessed, and must fail closed (sec. 6.1.5(f)); accepting
+// it would let, e.g., a mapping to/from anyPolicy slip past the sec. 6.1.4(a) rejection
 // the intermediate path applies. (nameConstraints / inhibitAnyPolicy are also
 // prepare-next-only but are MUST-be-critical CA extensions, so a critical one on
-// a terminal CA cert is conforming and is NOT treated as unprocessed here.)
+// a terminal CA cert is conforming and is not treated as unprocessed here.)
 var TARGET_UNPROCESSED_IF_CRITICAL = {};
 TARGET_UNPROCESSED_IF_CRITICAL[OID.policyMappings] = true;
 Object.freeze(TARGET_UNPROCESSED_IF_CRITICAL);
@@ -1121,13 +1122,13 @@ function validateCriticalExtensionStructure(cert) {
  * `userInitialPolicySet`, and `initialPermittedSubtrees` /
  * `initialExcludedSubtrees` -- arrays of `{ tag, base }` where `tag` is the
  * GeneralName tag number and `base` that form's constraint value), an
- * optional `requiredEku` (key purposes -- registered OID names or dotted OID
- * strings -- the target's extendedKeyUsage must assert; an absent extension
- * is unrestricted, RFC 5280 4.2.1.12), and an optional `revocationChecker`.
- * The value-carrying options (`time`, `maxPathCerts`, `maxPolicyNodes`, the
- * subtree seeds, `userInitialPolicySet`, `requiredEku`) are validated at the
- * entry point -- a mis-shaped value throws `path/bad-input` rather than
- * silently not applying. Returns `{ valid, revocationChecked, anchorConstraints,
+ * optional `requiredEku` (key purposes the target's extendedKeyUsage must
+ * assert, given as registered OID names or dotted OID strings; an absent
+ * extension is unrestricted, RFC 5280 4.2.1.12), and an optional
+ * `revocationChecker`. The value-carrying options (`time`, `maxPathCerts`,
+ * `maxPolicyNodes`, the subtree seeds, `userInitialPolicySet`, `requiredEku`)
+ * are validated at the entry point. A mis-shaped value throws `path/bad-input`,
+ * so it cannot silently go unapplied. Returns `{ valid, revocationChecked, anchorConstraints,
  * path, results, workingPublicKey, workingPublicKeyAlgorithm,
  * workingPublicKeyParameters, validPolicyTree }` where `results[i].checks`
  * carries a per-check reason code (`path/*`) for every step. Pure and
@@ -1142,19 +1143,18 @@ 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" -- which a stored verdict is re-read to settle. A checker
- * that THROWS is a fault in the checker rather than a status it reported, so it
- * fails the path as `path/revocation-checker-error` carrying the fault whatever
- * `softFail` says -- `softFail` opts into an undetermined ANSWER, and the
- * built-in checkers report one as `{ status: "unknown" }` rather than throwing.
+ * and you waived it", a distinction a stored verdict is re-read to settle. 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
+ * checkers report one as `{ status: "unknown" }` and do not throw.
  *
  * `anchorConstraints` reports what the anchor's own trust metadata decided:
  * the `checkedPurpose` it was judged under, and whether the `distrustAfter`
  * date and the `purposes` delegator map each applied. That metadata is keyed BY
  * key purpose, so an anchor carrying it while `opts.checkPurpose` is absent is a
- * configuration fault (`path/bad-input`) rather than a constraint that silently
- * does nothing -- a root distrusted years ago must not quietly validate a
- * current leaf.
+ * configuration fault (`path/bad-input`). A silently inert constraint would let
+ * a root distrusted years ago quietly validate a current leaf.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -1838,7 +1838,7 @@ function selectDelta(candidates) {
  * reasons, so a CA that partitions by reason code is served. A DELTA CRL is
  * merged onto a complete CRL it may be combined with (sec. 5.2.4 / 6.3.3(c)):
  * the delta is searched first, the complete CRL only if the delta left the
- * status unrevoked, and `removeFromCRL` then releases the certificate -- so a
+ * status unrevoked, and `removeFromCRL` then releases the certificate. A
  * base+delta pair reports a real verdict where the base alone could not. A
  * delta that merges with nothing is still consulted for revocation and still
  * blocks "good": merging may turn undetermined into good or revoked, never a
@@ -2288,9 +2288,9 @@ cmsVerify.setEngine({ build: build, validate: validate, toAnchor: toAnchor,
  * Build an OCSP-backed `RevocationChecker` for `pki.path.validate`'s
  * `revocationChecker` option from a set of pre-fetched OCSP responses (DER/PEM
  * or already-parsed). For each certificate it locates a SingleResponse whose
- * CertID binds this cert's serial to its issuer -- recomputing `issuerNameHash`
- * and `issuerKeyHash` under the CertID's own hashAlgorithm (SHA-1 or SHA-2), so
- * a response using either matches -- confirms the responder is authorized (the
+ * CertID binds this cert's serial to its issuer (recomputing `issuerNameHash`
+ * and `issuerKeyHash` under the CertID's own hashAlgorithm, SHA-1 or SHA-2, so
+ * a response using either matches), confirms the responder is authorized (the
  * issuing CA directly, or a valid CA-issued delegate bearing both id-kp-OCSPSigning
  * and id-pkix-ocsp-nocheck), verifies the response signature over
  * `tbsResponseDataBytes`, checks currency
@@ -2368,10 +2368,10 @@ function ocspChecker(responses) {
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
  * Verify a single OCSP response for one certificate
- * against its already-parsed issuer certificate at `time` -- 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 the EXACT SAME gates the path validator's `ocspChecker`
+ * 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`
  * 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
@@ -2818,20 +2818,21 @@ async function _fetchAiaIssuers(current, aia) {
  *
  * Candidate issuers are matched by RFC 5280 7.1 name chaining, prioritized by the RFC 4158 3.5
  * heuristics (a subjectKeyIdentifier/authorityKeyIdentifier match, an anchor-adjacent issuer,
- * CA + keyCertSign, validity at the check time -- all hints, never filters), and searched
- * depth-first with backtracking: the first ordered path that `pki.path.validate` accepts wins. A
- * name or key-identifier match is only an ordering hint; every accept flows through `validate`,
- * so `build` never weakens or duplicates a 6.1 check. The search over the untrusted pool is
- * bounded -- a depth cap on chain length, a total-work cap on candidate expansions, and a
- * visited-set keyed on the (subject, subjectAltName, public key) tuple -- so a cross-certificate
- * cycle or Bridge-CA fan-out terminates deterministically rather than growing without bound.
+ * CA + keyCertSign, validity at the check time; each orders the search without excluding a
+ * candidate), and searched depth-first with backtracking: the first ordered path that
+ * `pki.path.validate` accepts wins. A name or key-identifier match is only an ordering hint;
+ * every accept flows through `validate`, so `build` never weakens or duplicates a 6.1 check. The
+ * search over the untrusted pool is bounded: a depth cap on chain length, a total-work cap on
+ * candidate expansions, and a visited-set keyed on the (subject, subjectAltName, public key)
+ * tuple. A cross-certificate cycle or Bridge-CA fan-out therefore terminates deterministically;
+ * the search cannot grow without bound.
  *
  * `leaf` is a DER `Buffer`, a PEM string, or an already-parsed `pki.schema.x509` object. Returns
  * `{ valid, path, trustAnchor, result, candidatesConsidered }`, where `path` is the ordered array
  * `validate` consumes (anchor-proximal first, leaf last, the anchor excluded). Fail-closed: bad
  * options throw `path/bad-input`; no chain to any anchor throws `path/no-path`; chains that
  * assemble but none validate return `{ valid:false }` with the best failing `validate` result;
- * the search bound throws `path/build-limit`. By default `build` is OFFLINE (zero network) -- supply
+ * the search bound throws `path/build-limit`. By default `build` is OFFLINE (zero network), so supply
  * intermediates in `opts.candidates`. Set `opts.fetchAia: true` to opt in to fetching a MISSING intermediate
  * from a certificate's Authority Information Access `caIssuers` URL (RFC 5280 sec. 4.2.2.1) over
  * `pki.transport`: the fetch triggers only on a pool miss, every fetched certificate is UNTRUSTED pool material
@@ -2840,7 +2841,7 @@ async function _fetchAiaIssuers(current, aia) {
  * buildable path), a per-cert URL cap, a build-wide URL dedupe, a response size + certificate-count cap, and no
  * redirect following; every fetch fault is a silent skip. `aiaFetches` reports how many network GETs the build
  * performed (`0` when `fetchAia` is off). NOTE: with `opts.validate:false` (pure-builder mode) a fetched cert is
- * returned unvalidated, identical to a static candidate -- the "flows through validate" guarantee needs validation on.
+ * returned unvalidated, identical to a static candidate; the "flows through validate" guarantee needs validation on.
  *
  * @opts  candidates             The untrusted candidate CA pool (array of DER/PEM/parsed certs; alias `intermediates`).
  * @opts  trustAnchors           The trust store (non-empty array of `{ name, publicKey, algorithm }` tuples or self-signed root certificates).
@@ -2848,10 +2849,10 @@ async function _fetchAiaIssuers(current, aia) {
  * @opts  maxDepth               Chain-length depth cap (default `C.LIMITS.PATH_BUILD_MAX_DEPTH`).
  * @opts  maxCandidatesConsidered  Total-work cap on candidate expansions (default `C.LIMITS.PATH_BUILD_MAX_CANDIDATES`).
  * @opts  validate               `false` returns the ordered path without validating (pure-builder mode; default `true`).
- * @opts  fetchAia               `true` opts in to AIA caIssuers network fetching of a missing intermediate (default `false` -- fully offline). Off unless set; when set, a fetch runs only on a pool miss for a non-anchor-adjacent cert, and (with validation on) every fetched cert still flows through `validate`.
- * @opts  transport              The injectable transport seam (`fn(request) -> Promise<{ status, headers, body }>`); tests drive the fetch offline. With none, the default `pki.transport.https` is used, which fails closed unless `opts.tls` carries trust. SSRF: for a caIssuers URL with a DNS hostname, a custom transport is used ONLY if it declares `fn.blocksPrivateAddresses = true` -- vouching it refuses (and pins) a resolved private / loopback / link-local / special-use address, as the default transport does. Without that marker a DNS-name AIA URL is fail-closed (skipped) and only an IP-literal URL (validated up front) is fetched; set the marker on your transport when it filters resolved addresses.
- * @opts  tls                    The TLS trust for the AIA HTTPS host (`{ anchors, useSystemStore, ... }`) -- DISTINCT from `opts.trustAnchors` (the PKI trust store the path validates against). The default transport refuses an unpinned server.
- * @opts  maxAiaFetches          Total AIA network GET budget across the whole build (default `C.LIMITS.PATH_AIA_MAX_FETCHES`); on reaching it the builder stops fetching (a silent cap), never a throw -- a fetch bound never denies a path the pool could build.
+ * @opts  fetchAia               `true` opts in to AIA caIssuers network fetching of a missing intermediate (default `false`, fully offline). Off unless set; when set, a fetch runs only on a pool miss for a non-anchor-adjacent cert, and (with validation on) every fetched cert still flows through `validate`.
+ * @opts  transport              The injectable transport seam (`fn(request) -> Promise<{ status, headers, body }>`); tests drive the fetch offline. With none, the default `pki.transport.https` is used, which fails closed unless `opts.tls` carries trust. SSRF: for a caIssuers URL with a DNS hostname, a custom transport is used only if it declares `fn.blocksPrivateAddresses = true`, which vouches that it refuses (and pins) a resolved private / loopback / link-local / special-use address, as the default transport does. Without that marker a DNS-name AIA URL is fail-closed (skipped) and only an IP-literal URL (validated up front) is fetched; set the marker on your transport when it filters resolved addresses.
+ * @opts  tls                    The TLS trust for the AIA HTTPS host (`{ anchors, useSystemStore, ... }`). This is distinct from `opts.trustAnchors`, the PKI trust store the path validates against. The default transport refuses an unpinned server.
+ * @opts  maxAiaFetches          Total AIA network GET budget across the whole build (default `C.LIMITS.PATH_AIA_MAX_FETCHES`); on reaching it the builder stops fetching (a silent cap) and does not throw, so a fetch bound cannot deny a path the pool could build.
  * @opts  maxAiaPerCert          Cap on caIssuers URLs tried per certificate (default `C.LIMITS.PATH_AIA_MAX_PER_CERT`).
  * @opts  aiaTimeout             Per-fetch timeout in ms, forwarded to the transport.
  * @opts  maxResponseBytes       Per-fetch response size cap, forwarded to the transport (tightenable downward only).