@blamejs/pki 0.5.7 → 0.5.8

package/lib/cmp-verify.js

@@ -11,12 +11,12 @@
 // dependency set (the path-validate signature engine + full path building) that pki.cmp.build never
 // pulls, and re-exports the cmp-build producing surface so the whole pki.cmp namespace is wired here.
 //
-// The load-bearing rule: the protection is recomputed over the EXACT ProtectedPart bytes the builder
-// signed -- SEQUENCE { header, body } reconstructed from the parser-surfaced RAW headerBytes / bodyBytes
-// (schema-cmp), NEVER a re-serialization of the decoded structs. A re-encoder that normalized a malleable
+// The load-bearing rule: the protection is recomputed over the exact ProtectedPart bytes the builder
+// signed, a SEQUENCE { header, body } reconstructed from the parser-surfaced raw headerBytes / bodyBytes
+// (schema-cmp), never a re-serialization of the decoded structs. A re-encoder that normalized a malleable
 // interior field would run the recompute over different bytes than a strict signer covered: both a false
-// reject for a canonical peer AND a bypass. The signature path routes through the ONE path-validate engine
-// (with the EdDSA low-order-point gate) injected via setEngine -- never build's self-check, which skips it.
+// reject for a canonical peer and a bypass. The signature path routes through the single path-validate engine
+// (with the EdDSA low-order-point gate) injected via setEngine, never build's self-check, which skips it.
 // RFC 9810 sec. 5.1.3, algorithms RFC 9481 / RFC 9579, out-of-path signer profile RFC 9483.
 
 var asn1 = require("./asn1-der");
@@ -40,7 +40,7 @@ function _err(code, message, cause) { return new CmpError(code, message, cause);
 var NS = pkix.makeNS("cmp", CmpError, oid);
 var PBMAC1_PARAMS = pkix.pbmac1Params(NS);
 // The shared RFC 5280 sec. 4.2.1 extension-value decoders (the acme / inspect home): the signer keyUsage gate
-// reads through the ONE structurally-strict decoder (X.690 sec. 11.2.2 minimal NamedBitList) rather than a
+// reads through the single structurally-strict decoder (X.690 sec. 11.2.2 minimal NamedBitList), not a
 // hand-rolled bit test, so a malformed KeyUsage fails the gate independently of the path validator also rejecting it.
 var _certExtDecoders = pkix.certExtensionDecoders(NS).byOid;
 
@@ -50,9 +50,9 @@ var KNOWN_VERIFY_OPTS = {
 };
 
 // PBMAC1 PBKDF2-PRF / messageAuthScheme name -> WebCrypto hash. Only SHA-256/384/512 are supported
-// (RFC 9481 sec. 7 mandates SHA-256; RFC 9579 sec. 7 bars a <= 160-bit digest, so hmacWithSHA1 -- and an
-// omitted-PRF that resolves to it -- is unsupported, never MAC-verified under a weak digest).
-// Keyed by the IMMUTABLE dotted OID, never the display name: pki.oid.register() can rename hmacWithSHA256/384/512,
+// (RFC 9481 sec. 7 mandates SHA-256; RFC 9579 sec. 7 bars a <= 160-bit digest, so hmacWithSHA1, and an
+// omitted-PRF that resolves to it, is unsupported and never MAC-verified under a weak digest).
+// Keyed by the immutable dotted OID, never the display name: pki.oid.register() can rename hmacWithSHA256/384/512,
 // so a name-keyed lookup would reject a valid PBMAC1 message under a renamed registry (the immutable-OID-dispatch rule).
 var PRF_HASH = {};
 PRF_HASH[oid.byName("hmacWithSHA256")] = "SHA-256";
@@ -69,8 +69,8 @@ var PBMAC1_KEYLEN_MAX = 1024;
 // PBKDF2 PRF output length (octets) -- the size of one derived block; keyLength beyond it costs extra HMAC rounds.
 var PRF_HLEN = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
 
-// The legacy / KEM MAC protection OIDs (RFC 9810 sec. 5.1.3.1/.2/.4) the v1 verifier recognizes and refuses
-// -- build emits only PBMAC1, so the verifier rejects a legacy/KEM MAC OID rather than accept a construction
+// The legacy / KEM MAC protection OIDs (RFC 9810 sec. 5.1.3.1/.2/.4) the v1 verifier recognizes and refuses.
+// Build emits only PBMAC1, so the verifier rejects a legacy/KEM MAC OID and never accepts a construction
 // it does not verify (a silent accept of an unverified algorithm would be fail-open).
 var UNSUPPORTED_MAC_OIDS = {};
 ["passwordBasedMac", "dhBasedMac", "kemBasedMac"].forEach(function (n) {
@@ -133,7 +133,7 @@ function _coerce(message) {
 }
 
 // Rebuild the PKIMessage DER from a parsed object's raw slices: SEQUENCE { header, body, protection [0]
-// EXPLICIT BIT STRING OPTIONAL, extraCerts [1] EXPLICIT SEQUENCE OPTIONAL } -- the exact inverse of the
+// EXPLICIT BIT STRING OPTIONAL, extraCerts [1] EXPLICIT SEQUENCE OPTIONAL }, the exact inverse of the
 // parser's surfaced fields (cmp-build.js assembles the identical shape). Re-parsing this authenticates every
 // field against the raw bytes, discarding any mutated decoded field the caller may have carried.
 function _reassemble(m) {
@@ -166,7 +166,7 @@ function _certSki(parsed) {
 function _subjectDn(parsed) { return parsed.subject.dn || null; }
 
 // The decoded GeneralName nodes of a parsed certificate's subjectAltName (empty if none / malformed).
-// x509.parse surfaces `value` as the unwrapped extnValue content -- for SAN that is the SEQUENCE OF GeneralName.
+// x509.parse surfaces `value` as the unwrapped extnValue content; for SAN that is the SEQUENCE OF GeneralName.
 function _sanGeneralNames(parsed) {
   var sanOid = oid.byName("subjectAltName");
   var exts = parsed.extensions;
@@ -189,7 +189,7 @@ function _sanGeneralNames(parsed) {
 // it equals the POPULATED subject DN (a [4] directoryName under the RFC 5280 sec. 7.1 canonical comparison) OR
 // a subjectAltName GeneralName entry -- checked regardless of whether the subject is empty, so a certificate
 // that carries both a subject and a SAN can be identified by either, and an empty subject (RFC 5280 sec.
-// 4.1.2.6 requires a critical SAN) is bound to its SAN identity rather than accepted with an anonymous sender.
+// 4.1.2.6 requires a critical SAN) is bound to its SAN identity, never accepted with an anonymous sender.
 function _senderBoundToCert(sender, parsed) {
   if (!sender || !sender.bytes) return false;
   var subjectRdns = parsed.subject.rdns;
@@ -203,7 +203,7 @@ function _senderBoundToCert(sender, parsed) {
 }
 
 // GeneralName equality (RFC 5280 sec. 7) for the sender <-> SAN binding, applying the per-type comparison
-// rules rather than a universal byte compare: a dNSName [2] case-insensitively (sec. 4.2.1.6 / 7.2), an
+// rules in place of a universal byte compare: a dNSName [2] case-insensitively (sec. 4.2.1.6 / 7.2), an
 // rfc822Name [1] with a case-insensitive domain (sec. 7.5), a uniformResourceIdentifier [6] with a
 // case-insensitive scheme + host (sec. 4.2.1.6 / RFC 3986 sec. 6.2.2.1), a directoryName [4] under the sec.
 // 7.1 canonical DN comparison, and every other type by exact DER (fail-closed). `sender` is the parsed [n]
@@ -213,9 +213,9 @@ function _generalNameMatches(sender, sanNode) {
   if (sanNode.tagClass === "context") {
     if (sanNode.tagNumber === 2 && sanNode.content) {   // dNSName IA5String
       var dnsSan = sanNode.content.toString("latin1"), dnsSender = String(sender.value);
-      // Case-fold ONLY a well-formed dNSName (RFC 5280 sec. 4.2.1.6 / RFC 1034, via the shared validator): a
+      // Case-fold only a well-formed dNSName (RFC 5280 sec. 4.2.1.6 / RFC 1034, via the shared validator): a
       // malformed name (an empty label like "victim..com", a leading/trailing dot, bad LDH) is compared
-      // byte-exact rather than folded, so it cannot bind a byte-distinct identity.
+      // byte-exact and never folded, so it cannot bind a byte-distinct identity.
       if (pkix.dnsNameProblem(dnsSan) !== null || pkix.dnsNameProblem(dnsSender) !== null) return dnsSan === dnsSender;
       return dnsSender.toLowerCase() === dnsSan.toLowerCase();
     }
@@ -256,10 +256,10 @@ function _mailboxSplit(s) {
     sep = s.indexOf("@");   // an unquoted (Dot-string) local-part cannot contain a raw "@" -> exactly one total
     if (sep < 0 || sep !== s.lastIndexOf("@")) return -1;
   }
-  // The Domain that follows the separator must be a well-formed FQDN (RFC 1034, via the shared validator) -- an
+  // The Domain that follows the separator must be a well-formed FQDN (RFC 1034, via the shared validator): an
   // empty / empty-label / extra-"@" domain is malformed. An unquoted Local-part must be a Dot-string: non-empty,
   // no leading/trailing dot, no empty atom ("a..b"). A quoted Local-part is already balanced above. A malformed
-  // mailbox returns -1 so _rfc822Equal compares it byte-exact rather than case-folding a malformed domain.
+  // mailbox returns -1 so _rfc822Equal compares it byte-exact and never case-folds a malformed domain.
   var local = s.slice(0, sep), domain = s.slice(sep + 1);
   if (pkix.dnsNameProblem(domain) !== null) return -1;
   // An unquoted (Dot-string) Local-part is atext atoms joined by single dots (RFC 5321 sec. 4.1.2): every
@@ -275,7 +275,21 @@ function _mailboxSplit(s) {
 function _rfc822Equal(a, b) {
   var ai = _mailboxSplit(a), bi = _mailboxSplit(b);
   if (ai < 0 || bi < 0) return a === b;
-  return a.slice(0, ai) === b.slice(0, bi) && a.slice(ai + 1).toLowerCase() === b.slice(bi + 1).toLowerCase();
+  return a.slice(0, ai) === b.slice(0, bi) && _lowerAsciiDomain(a.slice(ai + 1)) === _lowerAsciiDomain(b.slice(bi + 1));
+}
+
+// sec. 7.5 authorizes a case-insensitive ASCII comparison of the host-part, and nothing
+// wider. String.toLowerCase() is Unicode-aware and folds well beyond A-Z: U+212A KELVIN
+// SIGN lowercases to "k", so a host carrying it would compare EQUAL to the ASCII spelling
+// and two distinct domains would read as one identity. Fold only A-Z and leave every other
+// octet alone, so a non-ASCII host can differ from an ASCII one but never collide with it.
+function _lowerAsciiDomain(h) {
+  var out = "";
+  for (var i = 0; i < h.length; i++) {
+    var c = h.charCodeAt(i);
+    out += (c >= 0x41 && c <= 0x5a) ? String.fromCharCode(c + 32) : h.charAt(i);
+  }
+  return out;
 }
 
 // RFC 5280 sec. 4.2.1.6 / RFC 3986 sec. 6.2.2.1 URI comparison: the scheme and the authority host are
@@ -284,15 +298,15 @@ function _rfc822Equal(a, b) {
 // -- never normalize an input we cannot confidently parse into a false identity match).
 function _normalizeUri(u) {
   // RFC 3986 syntax: every character must be a URI character and every "%" must introduce a valid pct-encoding
-  // (%HH). A URI with an out-of-charset byte or a malformed percent-escape ("%zz") in ANY component (path,
-  // query, fragment, userinfo) is not normalized -- return null so it is compared byte-exact.
+  // (%HH). A URI with an out-of-charset byte or a malformed percent-escape ("%zz") in any component (path,
+  // query, fragment, userinfo) is not normalized; return null so it is compared byte-exact.
   if (!/^[A-Za-z0-9._~:/?#@!$&'()*+,;=%[\]-]*$/.test(u) || /%(?![0-9A-Fa-f]{2})/.test(u)) return null;
   var m = /^([a-zA-Z][a-zA-Z0-9+.-]*):(.*)$/.exec(u);   // scheme ":" rest (RFC 3986 sec. 3.1)
   if (!m) return null;
   var scheme = m[1].toLowerCase();
   var rest = m[2];
   // A URI SAN identity is host-based (RFC 5280 sec. 4.2.1.6): an authority-free URI (no "//", e.g. a URN) has
-  // no host to anchor the comparison, so compare it byte-exact rather than case-fold its scheme -- the shared
+  // no host to anchor the comparison, so compare it byte-exact and never case-fold its scheme; the shared
   // GeneralName parser only enforces printable IA5, not a present authority.
   if (rest.slice(0, 2) !== "//") return null;
   var body = rest.slice(2);
@@ -306,7 +320,7 @@ function _normalizeUri(u) {
   var userinfo = at < 0 ? "" : authority.slice(0, at + 1);
   var hostport = at < 0 ? authority : authority.slice(at + 1);
   // Split the host from an optional ":port": an IPv6 literal "[...]" carries the port after the "]", otherwise
-  // the port follows the FIRST ":". Case-fold ONLY the host (RFC 3986 sec. 6.2.2.1); the port stays byte-exact
+  // the port follows the first ":". Case-fold only the host (RFC 3986 sec. 6.2.2.1); the port stays byte-exact
   // so a malformed non-numeric port (":ADMIN" vs ":admin") is never folded into a false identity match.
   var host, port;
   if (hostport.charAt(0) === "[") {
@@ -317,13 +331,13 @@ function _normalizeUri(u) {
     var ci = hostport.indexOf(":");
     host = ci < 0 ? hostport : hostport.slice(0, ci); port = ci < 0 ? "" : hostport.slice(ci);
   }
-  // The port must be numeric (RFC 3986 sec. 3.2.3 port = *DIGIT). A non-numeric port is a MALFORMED authority:
-  // return null so the caller compares the raw values exactly, rather than case-fold the host of an input the
+  // The port must be numeric (RFC 3986 sec. 3.2.3 port = *DIGIT). A non-numeric port is a malformed authority:
+  // return null so the caller compares the raw values exactly and never case-folds the host of an input the
   // normalizer cannot confidently parse (which would bind two byte-distinct malformed authorities).
   if (port !== "" && !/^:[0-9]*$/.test(port)) return null;
   // The authority host must be a well-formed FQDN or IP literal (RFC 5280 sec. 4.2.1.6 requires a URI SAN
   // authority to carry an FQDN/IP host): an empty, malformed ("Victim..COM"), or bad IPv6-literal host is
-  // compared byte-exact rather than case-folded, since the GeneralName parser only enforces printable IA5.
+  // compared byte-exact and never case-folded, since the GeneralName parser only enforces printable IA5.
   var hostOk = host.charAt(0) === "["
     ? (host.charAt(host.length - 1) === "]" && ipUtils.expandIpv6Hex(host.slice(1, -1)) !== null)
     : (pkix.dnsNameProblem(host) === null);
@@ -337,8 +351,8 @@ function _uriEqual(a, b) {
 }
 
 // M11/M14: resolve the signature-protection signer certificate. An explicit opts.signerCert wins (with the
-// senderKID SKI binding when present); else `extra` (the ALREADY dedup+validity+count-bounded extraCerts) by
-// senderKID, else RFC 9483 sec. 3.3 -- extraCerts[0] IS the protection certificate. `extra` is bounded BEFORE
+// senderKID SKI binding when present); else `extra` (the already dedup+validity+count-bounded extraCerts) by
+// senderKID, else RFC 9483 sec. 3.3, where extraCerts[0] is the protection certificate. `extra` is bounded before
 // this search so an unsigned flood cannot force unbounded X.509 parsing. Returns { der, spki, subject, parsed }
 // or null (never verify against an unauthenticated key).
 function _resolveSignerCert(m, opts, extra) {
@@ -359,8 +373,8 @@ function _resolveSignerCert(m, opts, extra) {
     // would change verdict.signer.cert/.spki). Parse it SEPARATELY: a corrupt / mistyped certificate is a
     // deployment error that THROWS cmp/bad-input, never a routine signer-cert-not-found verdict indistinguishable
     // from a message that simply omitted its signer (the nullable path is reserved for message candidates).
-    // The caller EXPLICITLY selected this certificate, so the senderKID (a hint for narrowing a candidate search)
-    // is NOT applied here -- the protection signature verification against this cert's key is the real gate; a
+    // The caller explicitly selected this certificate, so the senderKID (a hint for narrowing a candidate search)
+    // is not applied here: the protection signature verification against this cert's key is the real gate; a
     // valid message from a signer certificate that omits an SKI still resolves to its exact opts.signerCert.
     var scDer = Buffer.from(_certDer(opts.signerCert, "opts.signerCert"));
     var scParsed;
@@ -402,9 +416,9 @@ function _keyUsageAllowsSigning(parsed) {
   for (var i = 0; i < exts.length; i++) {
     if (exts[i].oid !== kuOid) continue;
     var ku;
-    // Decode through the shared keyUsage decoder -- it enforces the RFC 5280 sec. 4.2.1.3 BIT STRING form + the
+    // Decode through the shared keyUsage decoder: it enforces the RFC 5280 sec. 4.2.1.3 BIT STRING form + the
     // X.690 sec. 11.2.2 minimal NamedBitList rule (rejecting a non-minimal 03 02 00 80). A malformed KeyUsage
-    // fails this gate rather than a hand-rolled bit test authorizing it and leaning on path validation to reject it.
+    // fails this gate, so no hand-rolled bit test authorizes it and leans on path validation to reject it.
     try { ku = _certExtDecoders[kuOid](exts[i].value); }
     catch (_e) { return false; }
     return ku.digitalSignature === true;
@@ -430,7 +444,7 @@ async function _verifyMac(m, protectedPart, protectionAlg, protection, opts) {
   if (!prfHash) return _fail(m, "mac", protectionAlg, "cmp/unsupported-algorithm", "unsupported PBMAC1 PBKDF2 PRF " + JSON.stringify(kdf.prfName) + " (SHA-256/384/512 only; RFC 9481 sec. 7, RFC 9579 sec. 7)");
   if (!macHash) return _fail(m, "mac", protectionAlg, "cmp/unsupported-algorithm", "unsupported PBMAC1 messageAuthScheme " + JSON.stringify(params.schemeName) + " (SHA-256/384/512 only)");
 
-  // M18: bound the attacker-controlled work factors BEFORE deriving (CWE-834/400). A config-tier throw.
+  // M18: bound the attacker-controlled work factors before deriving (CWE-834/400). A config-tier throw.
   _capWork(kdf.iterationCount, kdf.salt, kdf.keyLength, prfHash, opts);
 
   // M19: recompute the MAC over the reconstructed ProtectedPart and compare in constant time.
@@ -465,16 +479,16 @@ function _capWork(iterationCount, salt, keyLength, prfHash, opts) {
   if (iterationCount * blocks > cap) throw _err("cmp/bad-input", "the PBMAC1 combined work (iterationCount " + iterationCount + " x " + blocks + " derived blocks) exceeds the cap " + cap);
 }
 
-// M9-M14 + M20-M22: verify signature protection, then (with a trust store) FULL out-of-path cert validation.
+// M9-M14 + M20-M22: verify signature protection, then (with a trust store) full out-of-path cert validation.
 async function _verifySignature(m, protectedPart, protectionAlg, protection, opts) {
-  // Bound the UNSIGNED extraCerts ONCE (dedup + drop non-certificates + cap + scan cap) before either the
+  // Bound the unsigned extraCerts once (dedup + drop non-certificates + cap + scan cap) before either the
   // senderKID signer search or path building, so a hostile peer padding extraCerts cannot force unbounded
   // X.509 parsing or a candidate-pool overflow.
   var extra = _boundExtraCerts(m.extraCerts);
   var signer = _resolveSignerCert(m, opts, extra);
   if (!signer) return _fail(m, "signature", protectionAlg, "cmp/signer-cert-not-found", "no signer certificate resolved (opts.signerCert, senderKID, or extraCerts)");
 
-  // M2/M9: verify over the reconstructed ProtectedPart through the ONE path-validate engine (the EdDSA
+  // M2/M9: verify over the reconstructed ProtectedPart through the single path-validate engine (the EdDSA
   // low-order-point gate + the sig-OID<->key-OID algorithm-confusion gate apply); fail-closed to false.
   var ok = await _engine.verifyWithSpki(protectionAlg, protection.bytes, signer.spki, protectedPart);
   if (ok !== true) return _fail(m, "signature", protectionAlg, "cmp/protection-failed", "the protection signature does not verify over the ProtectedPart under the declared protectionAlg", signer);
@@ -487,18 +501,18 @@ async function _verifySignature(m, protectedPart, protectionAlg, protection, opt
     return _fail(m, "signature", protectionAlg, "cmp/sender-mismatch", "the header sender field does not match the signer certificate subject, or (for an empty subject) a subjectAltName entry (RFC 9483 sec. 3.1, RFC 5280 sec. 7.1)", signer);
   }
 
-  // A failed opt-in echo check is a REJECTION verdict (valid:false), consistent with the MAC path -- a caller
+  // A failed opt-in echo check is a rejection verdict (valid:false), consistent with the MAC path: a caller
   // that requested a transactionID / recipNonce binding must not see valid:true when it does not hold.
   var hc = _headerChecks(m, opts);
   if (hc) return _fail(m, "signature", protectionAlg, hc.code, hc.reason, signer);
 
   // M5/M12: with no trust store the verdict is crypto-only (trusted:false) and the signer is surfaced for
-  // the caller to anchor. With a trust store the signer cert gets the FULL RFC 5280 sec. 6.1 path gates.
+  // the caller to anchor. With a trust store the signer cert gets the full RFC 5280 sec. 6.1 path gates.
   if (opts.trustAnchors == null) return _ok(m, "signature", protectionAlg, false, signer);
   var trust = await _chainSigner(signer, m, opts, extra);
-  // Surface the ACTUAL validated chain (signer + the intermediates path.build used) on a trusted verdict, so a
-  // caller can cache exactly the certificates that established trust rather than the UNSIGNED extraCerts a peer
-  // can pad -- an appended-but-unused certificate never enters this chain.
+  // Surface the chain that actually validated (signer + the intermediates path.build used) on a trusted verdict,
+  // so a caller can cache exactly the certificates that established trust, not the unsigned extraCerts a peer
+  // can pad: an appended-but-unused certificate never enters this chain.
   if (trust.chain) signer.chain = trust.chain;
   return _verdict(m, "signature", protectionAlg, true, trust.trusted, trust.trusted ? null : "cmp/untrusted-signer", trust.reason, signer);
 }
@@ -526,26 +540,26 @@ async function _chainSigner(signer, m, opts, extra) {
   if (!_keyUsageAllowsSigning(signer.parsed)) {
     return { trusted: false, reason: "the signer certificate keyUsage does not assert digitalSignature (RFC 9483 sec. 3.2)" };
   }
-  // Validate the signer path at a TRUSTED current time by default -- NOT the message's self-asserted
+  // Validate the signer path at a trusted current time by default, never the message's self-asserted
   // messageTime, which the sender controls: a holder of a now-expired but once-valid signer certificate
   // could otherwise backdate messageTime into the certificate's validity window and be reported trusted.
-  // A caller doing historical verification opts into a specific instant via opts.time; a falsy but PRESENT
-  // opts.time (0 / false / "") is NOT silently replaced -- it reaches path.build and is rejected as bad-input.
+  // A caller doing historical verification opts into a specific instant via opts.time; a falsy but present
+  // opts.time (0 / false / "") is never silently replaced: it reaches path.build and is rejected as bad-input.
   var time = opts.time != null ? opts.time : new Date();
   var anchors = _certList(opts.trustAnchors);
   // `extra` is the already dedup + validity + count-bounded extraCerts (unsigned pool material), so a flood
   // of duplicate / junk / non-certificate entries cannot exhaust the candidate-search budget or raise a
-  // path/bad-input from a malformed pool certificate. Add it only up to the path-builder pool ceiling AFTER
+  // path/bad-input from a malformed pool certificate. Add it only up to the path-builder pool ceiling, after
   // the caller's intermediates, so unsigned extraCerts can never push a valid caller configuration over the
   // ceiling (if the caller's intermediates alone exceed it, that is a genuine config error path.build reports).
   var pool = _certList(opts.intermediates);
   var room = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES - pool.length;
   if (room > 0) {
     // Drop the signer leaf (already passed to build as the path TARGET) and any extraCert duplicating a caller
-    // intermediate BEFORE truncating to the remaining slots, so a tight ceiling spends those slots on genuinely
-    // useful embedded issuers rather than a redundant copy of the signer or a duplicate the pool already holds.
+    // intermediate before truncating to the remaining slots, so a tight ceiling spends those slots on genuinely
+    // useful embedded issuers, not on a redundant copy of the signer or a duplicate the pool already holds.
     // The identity is the canonical tbs+signature key so a Buffer extraCert dedups against a caller intermediate
-    // supplied either as raw bytes OR as an already-parsed certificate object (path.build accepts both).
+    // supplied either as raw bytes or as an already-parsed certificate object (path.build accepts both).
     var seen = Object.create(null);
     var sk = _certKey(signer.parsed); if (sk) seen[sk] = 1;
     pool.forEach(function (c) { var k = _certKey(c); if (k) seen[k] = 1; });
@@ -560,9 +574,9 @@ async function _chainSigner(signer, m, opts, extra) {
     // res.path is the ordered certificates path.build assembled (signer + the intermediates it used), as PARSED
     // objects whose byte fields are subarrays of the (possibly multi-MB) response allocation. Map each back to its
     // source DER (the signer, or a DER pool entry) and return an INDEPENDENT copy, so a caller caching the chain
-    // holds standalone buffers -- never slices pinning the whole response. Only certs on the trusted path enter it,
+    // holds standalone buffers, never slices pinning the whole response. Only certs on the trusted path enter it,
     // so unsigned extraCerts padding is excluded. (A path cert sourced from an already-parsed intermediate carries
-    // no DER to copy and is omitted; for a Buffer/DER pool -- the cmp.session case -- the chain is complete.)
+    // no DER to copy and is omitted; for a Buffer/DER pool, the cmp.session case, the chain is complete.)
     var byKey = Object.create(null);
     var skey = _certKey(signer.parsed); if (skey) byKey[skey] = signer.der;
     pool.forEach(function (c) { if (Buffer.isBuffer(c) || c instanceof Uint8Array) { var k = _certKey(c); if (k && !byKey[k]) byKey[k] = c; } });
@@ -570,7 +584,7 @@ async function _chainSigner(signer, m, opts, extra) {
     return { trusted: true, reason: null, chain: chain };
   } catch (e) {
     // A config-tier fault from path.build (an invalid opts.time, an empty / malformed trustAnchors or
-    // intermediate) is a DEPLOYMENT error, not an untrusted signer -- rethrow it as cmp/bad-input so it is
+    // intermediate) is a deployment error, not an untrusted signer, so rethrow it as cmp/bad-input and it is
     // not masked as a routine trust failure (the API contract: a bad required opt throws). A genuine
     // no-assemblable-path / validation failure collapses to an untrusted-signer verdict.
     if (e && e.code === "path/bad-input") {
@@ -643,7 +657,7 @@ async function _verify(message, opts) {
     return _fail(m, null, protectionAlg, "cmp/no-protection", "the PKIMessage carries no protection (RFC 9810 sec. 5.1.3); an unprotected message is never verified");
   }
 
-  // M2: reconstruct the ProtectedPart from the RAW surfaced slices -- byte-identical to what build signed,
+  // M2: reconstruct the ProtectedPart from the raw surfaced slices, byte-identical to what build signed,
   // never a re-serialization of the decoded header/body structs.
   var protectedPart = b.sequence([b.raw(m.headerBytes), b.raw(m.bodyBytes)]);
 
@@ -678,7 +692,7 @@ async function _verify(message, opts) {
  * @related    pki.cmp.build, pki.schema.cmp.parse
  * @defends    cmp-unverified-protection (CWE-347), cmp-mac-timing (CWE-208)
  *
- * Verify the protection on an incoming RFC 9810 CMP `PKIMessage` -- the verify-inverse of
+ * Verify the protection on an incoming RFC 9810 CMP `PKIMessage`, the verify-inverse of
  * `pki.cmp.build`. `message` is a raw DER `Buffer`, a PEM `CMP` string, or an already-parsed
  * `pki.schema.cmp.parse` result (the protection is always recomputed from the parser-surfaced raw
  * `headerBytes` / `bodyBytes`, so a mutated display field on a parsed object cannot desync the crypto).
@@ -693,7 +707,7 @@ async function _verify(message, opts) {
  * protection is cryptographically intact under the declared algorithm; `trusted` is whether a MAC secret
  * matched or a signature signer certificate chained to a supplied trust anchor. On a trusted signature
  * verdict `signer.chain` is the validated certificate path as independent DER buffers (the signer plus the
- * intermediates that chained it to the anchor) -- the certificates actually used, never the unsigned
+ * intermediates that chained it to the anchor): the certificates actually used, never the unsigned
  * `extraCerts` a peer can pad, and never a slice pinning the response allocation. A
  * well-formed but unverifiable message is a `{ valid: false }` verdict carrying a `cmp/*` code, not a throw;
  * only malformed input (a non-PKIMessage, a bad required opt, a flavor/credential mismatch) throws a typed `CmpError`.
@@ -706,11 +720,11 @@ async function _verify(message, opts) {
  *     (RFC 5280 sec. 6.1 plus the `keyUsage.digitalSignature` gate) to report `trusted`; absent -> the
  *     verdict is crypto-only (`trusted: false`) and the signer certificate is surfaced for the caller to
  *     anchor. The signature verify never routes through build's self-check (which skips the EdDSA
- *     low-order-point gate) -- it uses the same engine `pki.crl.verify` / `pki.ocsp.verify` do.
+ *     low-order-point gate); it uses the same engine `pki.crl.verify` / `pki.ocsp.verify` do.
  *   - `intermediates` (Buffer|Buffer[]|PEM) -- extra untrusted pool certificates for path building
  *     (`extraCerts` are added automatically, as untrusted pool material).
  *   - `time` (Date) -- the validity instant for path validation. Defaults to the current time (the message's
- *     self-asserted `messageTime` is NOT trusted for this); pass an explicit instant for historical verification.
+ *     self-asserted `messageTime` is not trusted for this); pass an explicit instant for historical verification.
  *   - `transactionID` (Buffer) -- opt-in: require `header.transactionID` to equal it (response-echo defense).
  *   - `expectRecipNonce` (Buffer) -- opt-in: require `header.recipNonce` to echo the sent sender nonce.
  *   - `revocationChecker` -- forwarded to `pki.path.validate` when chaining the signer certificate.

package/lib/cms-compress.js

@@ -12,7 +12,7 @@
 // absent-or-NULL params (RFC 3274 sec. 2), and BOUNDED-inflates the eContent. There is NO crypto
 // here -- CompressedData provides no integrity / confidentiality / authentication (RFC 8551 sec.
 // 2.4.5); it is purely a size transform. The one load-bearing defense is the decompression-bomb
-// cap: inflate stops at C.LIMITS.COMPRESS_MAX_BYTES BEFORE the output is materialized (a
+// cap: inflate stops at C.LIMITS.COMPRESS_MAX_BYTES before the output is materialized (a
 // resource-exhaustion defense, CWE-409), and every zlib fault collapses to a uniform typed error.
 
 var zlib = require("zlib");
@@ -70,7 +70,7 @@ async function decompress(input, opts) {
   if (parsed.contentTypeName !== "compressedData") throw _err("cms/unsupported-content-type", "input is not a CMS CompressedData (got " + parsed.contentTypeName + ")");
   var alg = parsed.compressionAlgorithm;
   if (alg.oid !== OID_ZLIB) throw _err("cms/unsupported-algorithm", "unsupported compressionAlgorithm " + (alg.name || alg.oid) + " (only id-alg-zlibCompress, RFC 3274 sec. 2)");
-  // RFC 3274 sec. 2: the parameters SHOULD be omitted but MAY be NULL -- reject any other encoding.
+  // RFC 3274 sec. 2: the parameters SHOULD be omitted but MAY be NULL. Reject any other encoding.
   if (alg.parameters != null && Buffer.compare(alg.parameters, NULL_PARAMS_DER) !== 0) throw _err("cms/bad-algorithm-parameters", "id-alg-zlibCompress parameters must be absent or NULL (RFC 3274 sec. 2)");
   var eci = parsed.encapContentInfo;
   if (eci.eContent == null) throw _err("cms/no-encapsulated-content", "the CompressedData carries no encapsulated content (a detached CompressedData cannot be decompressed)");
@@ -92,12 +92,12 @@ function _toDer(input) {
 }
 
 // Inflate the RFC 1950 ZLIB stream through the shared bounded-decompression guard, which applies
-// the output cap at the decompressor (so a bomb is refused mid-stream rather than after it is
-// allocated) and requires the whole octet string to be exactly one compressed frame (so trailing
-// bytes cannot give one content a second encoding). This module keeps its own verdict codes: a cap
-// breach is cms/decompress-too-large, every other fault the uniform cms/decompress-failed.
+// the output cap at the decompressor (so a bomb is refused mid-stream, before it is allocated) and
+// requires the whole octet string to be exactly one compressed frame (so trailing bytes cannot give
+// one content a second encoding). This module keeps its own verdict codes: a cap breach is
+// cms/decompress-too-large, every other fault the uniform cms/decompress-failed.
 //
-// `_err` is a FACTORY, and the guard calls it as one -- handing it CmsError instead would throw
+// `_err` is a factory and the guard calls it as one. Handing it CmsError instead would throw
 // "class cannot be invoked without new" on the rejection path, turning a refusal into a crash.
 function _inflateBounded(stream, cap) {
   var view = guard.bytes.view(stream, CmsError, "cms/decompress-failed", "the compressed content");