@blamejs/pki 0.5.6 → 0.5.8

package/lib/guard-time.js

@@ -10,19 +10,19 @@
 //
 // Defends the NaN-Date fail-open class (CWE-20 improper input validation feeding
 // a silent security-gate bypass). An Invalid Date is still `instanceof Date`, and
-// EVERY relational comparison against its NaN getTime() (NaN < x, NaN >= x) is
-// false -- so a validity / not-before / not-after / currency window built on an
-// unvalidated Date silently ACCEPTS when it should reject. The class recurred at
+// every relational comparison against its NaN getTime() (NaN < x, NaN >= x) is
+// false, so a validity / not-before / not-after / currency window built on an
+// unvalidated Date silently accepts when it should reject. The class recurred at
 // three independent boundaries (TSP genTime, OCSP producedAt/thisUpdate, CT
 // temporal-interval) before it was centralized here; the sibling
 // nan-date-comparison-unguarded codebase-patterns detector flags any lib function
-// that re-inlines a `.getTime()` comparison WITHOUT first rejecting a NaN, so a
-// new boundary is routed to this guard rather than re-growing the bug.
+// that re-inlines a `.getTime()` comparison without first rejecting a NaN, so a
+// new boundary is routed to this guard instead of re-growing the bug.
 //
-// Tier split: `value instanceof Date` with a NaN time is malformed CALLER input
-// (a config-time / entry-point Date -- an operator-supplied distrustAfter, a
-// caller `opts.time`), so assertValid throws the caller's typed error rather than
-// returning a silent default. within() is the fail-closed window primitive: it
+// Tier split: `value instanceof Date` with a NaN time is malformed caller input
+// (a config-time or entry-point Date, such as an operator-supplied distrustAfter
+// or a caller `opts.time`), so assertValid throws the caller's typed error instead
+// of returning a silent default. within() is the fail-closed window primitive: it
 // THROWS on a malformed operand but RETURNS a boolean for in/out-of-window, so the
 // OCSP / CRL currency callers that treat out-of-window as a `continue` skip keep
 // their control flow while a NaN operand can never slip through as a false.
@@ -30,7 +30,7 @@
 // assertValid(value, E, code, label) -> the same Date, once proven valid.
 //   value : a Date (or an alleged one) from a caller boundary.
 //   E     : the (code, message[, cause]) typed-error FACTORY in scope at the call
-//           site (ns.E / the module-local _err) -- NEVER a defineClass class, which
+//           site (ns.E / the module-local _err), never a defineClass class, which
 //           would crash `class cannot be invoked without new` on the error path.
 //   code  : the frozen domain/reason code this boundary rejects malformed time under.
 //   label : field phrase for the message.

package/lib/hpke.js

@@ -14,7 +14,7 @@
  *   Appendix A known-answer vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered
  *   but Appendix A ships no test vector for them, so they are omitted (a request
  *   fails closed) until an authoritative KAT is available. Pure composition over
- *   node:crypto -- no ASN.1, no schema engine. Post-quantum KEMs (ML-KEM, X-Wing)
+ *   node:crypto: no ASN.1, no schema engine. Post-quantum KEMs (ML-KEM, X-Wing)
  *   are a data-row extension the registry is shaped to admit once their
  *   specifications stabilize.
  *   The RFC 9180 sec. 7 registry code points live in pki.hpke.suites
@@ -44,14 +44,15 @@ function xor(a, b) { var o = Buffer.alloc(a.length); for (var i = 0; i < a.lengt
 var HPKE_V1 = Buffer.from("HPKE-v1", "ascii");
 function L(s) { return Buffer.from(s, "ascii"); }
 
-// ---- registries (RFC 9180 sec. 7, Tables 2/3/5 -- data, not switch) ----------
+// ---- registries: the RFC 9180 sec. 7 data tables (Tables 2/3/5) --------------
 
 // KDF: id -> { hash (node name), Nh }.
 // HKDF-SHA384 (0x0002) and DHKEM(P-384) (0x0011) are registered by RFC 9180 sec.
 // 7 but Appendix A / the cited [TestVectors] file ship no known-answer vector for
-// them, so they are omitted here until an authoritative KAT exists -- a request
-// for either fails closed as hpke/unknown-suite rather than running crypto no
-// test vector proves. They admit as a one-row addition the moment a KAT lands.
+// them, so they are omitted here until an authoritative KAT exists. A request for
+// either fails closed as hpke/unknown-suite, because no test vector proves the
+// crypto it would otherwise run. They admit as a one-row addition the moment a
+// KAT lands.
 var KDFS = {
   0x0001: { hash: "sha256", Nh: 32 },
   0x0003: { hash: "sha512", Nh: 64 },
@@ -112,7 +113,7 @@ function _expand(hash, Nh, prk, info, len) {
   return exact;
 }
 function _labeledExtract(kdf, suiteId, salt, label, ikm) {
-  // The concatenation copies the input keying material -- a DH secret or a PSK -- into a fresh
+  // The concatenation copies the input keying material (a DH secret or a PSK) into a fresh
   // buffer, so that copy is cleared once extract has consumed it. The caller still owns .
   var labeled = concat([HPKE_V1, suiteId, L(label), ikm]);
   try { return _extract(kdf.hash, kdf.Nh, salt, labeled); }
@@ -174,7 +175,7 @@ function _importPrivate(kem, rawSk, rawPk) {
 // The single KEM Diffie-Hellman choke point. node:crypto throws a raw
 // ERR_OSSL_FAILED_DURING_DERIVATION when the peer point is low-order / invalid
 // (an all-zero X25519 shared secret, a point not on the curve). RFC 9180 sec.
-// 4.1: Decap raises an error on DH failure -- surface it as a typed hpke/bad-key
+// 4.1: Decap raises an error on DH failure. Surface it as a typed hpke/bad-key
 // so no raw OpenSSL error escapes any encap / decap path.
 function _dh(privateKey, publicKey) {
   try {
@@ -211,9 +212,9 @@ function _ephemeral(kem, eph) {
 // The raw DH output is the KEM's shared secret before extraction: it is this module's allocation
 // and is cleared once _extractAndExpand has consumed it, on every DHKEM arm. In the authenticated
 // arms  builds a THIRD copy holding both DH results, so the concatenation is cleared as
-// well -- clearing only the pieces would leave the joined buffer readable.
+// well, since clearing only the pieces would leave the joined buffer readable.
 function _wipeDh(dh) { guard.secret.zeroize(dh, HpkeError, "hpke/bad-input", "the KEM shared secret"); }
-// EVERY agreement happens inside the protected region. In the authenticated modes the second
+// Every agreement happens inside the protected region. In the authenticated modes the second
 // agreement can throw on an attacker-supplied low-order sender key, and a first secret computed
 // outside the region would be left behind on exactly that failure path.
 function _encap(kem, pkR, pkRm, eph) {
@@ -361,7 +362,7 @@ function _recipPublic(suite, pk) {
   if (Buffer.isBuffer(pk)) return { key: _importPublic(suite.kem, pk), pkm: pk };
   if (pk && pk.pkm) return { key: _importPublic(suite.kem, pk.pkm), pkm: pk.pkm };
   // A node KeyObject: derive its wire form. A null/undefined/invalid value must
-  // fail closed here rather than let node's export throw a raw error upward.
+  // fail closed here, so no raw error from node's export escapes upward.
   try {
     return { key: pk, pkm: _exportPublic(suite.kem, pk) };
   } catch (e) {
@@ -373,8 +374,8 @@ function _recipPrivate(suite, sk) {
   if (sk && sk.skm) return { key: _importPrivate(suite.kem, sk.skm, sk.pkm), pkm: sk.pkm };
   // A raw scalar alone cannot be imported (an EC private key needs its public
   // point for the JWK), so the serialized private form is { skm, pkm }; reject a
-  // bare buffer, and fail any other bad key closed rather than let node's
-  // createPublicKey throw a raw error out of the setup path.
+  // bare buffer, and fail any other bad key closed; a raw createPublicKey error
+  // must not escape the setup path.
   if (Buffer.isBuffer(sk)) throw _err("hpke/bad-key", "a serialized private key must be provided as { skm, pkm } (raw scalar + public point), not a bare buffer");
   try {
     var pkm = _exportPublic(suite.kem, nodeCrypto.createPublicKey(sk));
@@ -389,9 +390,9 @@ function _recipPrivate(suite, sk) {
 // psk / auth / auth-psk. An unknown mode must fail closed, never key-schedule
 // with an out-of-registry mode byte.
 // The sender and the recipient read the same option object from OPPOSITE ends, so each direction
-// gets its own table rather than sharing their union. A union recognises every name at both ends and
-// so accepts the one that cannot do anything there: `senderPublicKey` handed to setupS, or
-// `senderKey` handed to setupR, is silently ignored -- which is the exact silence these tables exist
+// gets its own table. A shared union recognises every name at both ends and so accepts the one that
+// cannot do anything there: `senderPublicKey` handed to setupS, or
+// `senderKey` handed to setupR, is silently ignored, which is the exact silence these tables exist
 // to remove, in a wider form. An option that means nothing where it was passed is a misunderstanding
 // worth reporting, and usually a misdirected auth-mode setup.
 //
@@ -491,8 +492,8 @@ function _setupS(ids, pkR, opts) {
  * @related pki.hpke.setupS, pki.hpke.open
  *
  * Establish the recipient HPKE context from the sender's encapsulated key `enc`
- * and the recipient KEM private key (a node KeyObject or `{ skm, pkm }` -- the
- * raw private scalar plus its public point),
+ * and the recipient KEM private key (a node KeyObject, or `{ skm, pkm }` holding
+ * the raw private scalar plus its public point),
  * recovering the same shared secret and key schedule. The returned `context`
  * `.open(aad, ct)` decrypts and `.export(ctx, L)` derives secrets. `opts` mirrors
  * `setupS` (mode / info / psk / pskId), with `opts.senderPublicKey` for the auth

package/lib/http-digest.js

@@ -2,20 +2,20 @@
 // Copyright (c) blamejs contributors
 "use strict";
 //
-// @internal -- NOT on pki.*. HTTP Digest access authentication (RFC 7616): parse an UNTRUSTED
+// @internal -- not on pki.*. HTTP Digest access authentication (RFC 7616): parse an untrusted
 // WWW-Authenticate challenge (fail-closed, quoted-string-honoring) and compute the Authorization
 // response header (byte-exact A1/A2/KD). Prefix-agnostic: every thrown code comes from the caller's
-// E(code, msg) FACTORY (never a defineClass class -- feedback_guard_error_factory_not_class) and its
+// E(code, msg) factory, never a defineClass class (which would crash on the error path), plus its
 // policy.codes map, so pki.est composes it now and pki.acme / pki.cmp can reuse it as config, not a fork.
 //
-// The challenge is attacker-shaped: a comma inside a quoted value is NOT a delimiter (the _hasBasicChallenge
-// substring-scan bug class), a missing realm / nonce is REJECTED not defaulted, and an unsupported / weak
-// algorithm or a no-qop challenge fails closed rather than downgrading (feedback_guards_fail_closed_not_guess).
+// The challenge is attacker-shaped: a comma inside a quoted value is not a delimiter (the _hasBasicChallenge
+// substring-scan bug class), a missing realm or nonce is rejected and not defaulted, and an unsupported or
+// weak algorithm, or a no-qop challenge, fails closed instead of downgrading.
 
 var crypto = require("crypto");
 var constants = require("./constants");
 
-// Algorithm registry (a data row, not a switch -- Hard rule #2): rank orders the RFC 7616 sec. 3.7
+// Algorithm registry, a data row and not a switch: rank orders the RFC 7616 sec. 3.7
 // "most secure the client can use" selection (SHA-512-256 > SHA-256 > MD5); an unknown algorithm ranks 0.
 var ALGS = {
   "SHA-512-256": { hash: "sha512-256", rank: 3, sess: false }, "SHA-512-256-SESS": { hash: "sha512-256", rank: 3, sess: true },
@@ -33,7 +33,7 @@ function H(hash, s) { return crypto.createHash(hash).update(s, "latin1").digest(
 function KD(hash, secret, data) { return H(hash, secret + ":" + data); }
 function _qstr(v) { return "\"" + String(v).replace(/(["\\])/g, "\\$1") + "\""; }
 
-// Split a header at commas that are OUTSIDE a quoted-string (a quoted comma is a literal, not a delimiter).
+// Split a header at commas outside a quoted-string (a quoted comma is a literal, not a delimiter).
 function _commaSplitOutsideQuotes(s) {
   var out = [], buf = "", inQ = false, esc = false;
   for (var i = 0; i < s.length; i++) {
@@ -47,7 +47,7 @@ function _commaSplitOutsideQuotes(s) {
   out.push(buf);
   return out;
 }
-// Index of the first '=' OUTSIDE a quoted-string, or -1.
+// Index of the first '=' outside a quoted-string, or -1.
 function _firstEqOutsideQuotes(s) {
   var inQ = false, esc = false;
   for (var i = 0; i < s.length; i++) {
@@ -60,7 +60,7 @@ function _firstEqOutsideQuotes(s) {
   return -1;
 }
 function _unq(s) { return s.slice(1, -1).replace(/\\(.)/g, "$1"); }   // only ever called on a well-formed quoted-string (see _closedQuote)
-// A well-formed quoted-string: opens with ", closes with an UNESCAPED " that is the LAST character (nothing trails
+// A well-formed quoted-string: opens with ", closes with an unescaped " as the last character (nothing trails
 // it). An unterminated / trailing-garbage quoted-string is malformed (RFC 7230 sec. 3.2.6) and rejected.
 function _closedQuote(s) {
   if (s.length < 2 || s.charAt(0) !== "\"") return false;
@@ -74,7 +74,7 @@ function _closedQuote(s) {
   return false;
 }
 // A control octet (RFC 7230 sec. 3.2.6 quoted-string / qdtext forbids CTL except HTAB). Scanned with charCodeAt
-// rather than a control-char regex literal (which eslint no-control-regex correctly refuses).
+// instead of a control-char regex literal (which eslint no-control-regex correctly refuses).
 function _hasCtl(s) {
   for (var i = 0; i < s.length; i++) { var c = s.charCodeAt(i); if ((c < 0x20 && c !== 0x09) || c === 0x7f) return true; }
   return false;
@@ -119,7 +119,7 @@ function _parseParams(paramText, E, code) {
   }
   return map;
 }
-// Structural validation of ONE Digest challenge's params (RFC 7616 sec. 3.3). Throws on any violation.
+// Structural validation of one Digest challenge's params (RFC 7616 sec. 3.3). Throws on any violation.
 function _validateDigest(paramText, E, code) {
   var p = _parseParams(paramText, E, code);
   if (!p.realm || !p.realm.quoted || p.realm.value === "") throw E(code, "a Digest challenge requires a non-empty quoted realm (RFC 7616 sec. 3.3)");
@@ -129,38 +129,38 @@ function _validateDigest(paramText, E, code) {
   if (p.qop) {
     if (!p.qop.quoted) throw E(code, "the Digest qop must be a quoted list (RFC 7616 sec. 3.3)");
     qop = p.qop.value.split(",").map(function (x) { return x.replace(/^\s+|\s+$/g, "").toLowerCase(); }).filter(Boolean);
-    // A qop directive that is PRESENT but lists no value (qop="" / qop=", ,") is malformed -- it is NOT the
-    // absent-qop (RFC 2069) case. Reject it rather than silently collapsing to a no-qop response the server
-    // cannot accept (RFC 7616 sec. 3.3). Only an OMITTED qop directive selects the legacy no-qop path.
+    // A qop directive that is present but lists no value (qop="" / qop=", ,") is malformed, and is not the
+    // absent-qop (RFC 2069) case. Reject it instead of silently collapsing to a no-qop response the server
+    // cannot accept (RFC 7616 sec. 3.3). Only an omitted qop directive selects the legacy no-qop path.
     if (qop.length === 0) throw E(code, "a present Digest qop directive must list at least one value (RFC 7616 sec. 3.3)");
   }
-  // domain (RFC 7616 sec. 3.3): a QUOTED, space-separated list of URIs defining the protection space. An
-  // UNQUOTED domain is malformed and rejected (fail closed like realm / nonce / qop) rather than silently
-  // widened -- widening a mis-encoded scope to "the whole server" would send credentials MORE broadly than the
-  // server intended. Surfaced as an array of the listed URIs, or null when omitted / quoted-empty -- which per
+  // domain (RFC 7616 sec. 3.3): a quoted, space-separated list of URIs defining the protection space. An
+  // unquoted domain is malformed and rejected (fail closed like realm / nonce / qop) instead of silently
+  // widened: widening a mis-encoded scope to "the whole server" would send credentials more broadly than the
+  // server intended. Surfaced as an array of the listed URIs, or null when omitted or quoted-empty, which per
   // the RFC means "all URIs on the responding server" (the answer may be reused for any same-origin URI, sec. 3.5).
   if (p.domain && !p.domain.quoted) throw E(code, "the Digest domain must be a quoted-string (RFC 7616 sec. 3.3)");
   var domain = (p.domain && p.domain.value.replace(/^\s+|\s+$/g, "") !== "")
     ? p.domain.value.replace(/^\s+|\s+$/g, "").split(/\s+/) : null;
-  // charset (RFC 7616 sec. 3.3): the ONLY permitted value is the UNQUOTED token "UTF-8". A quoted charset, or any
-  // other value, is malformed -- answering it would hash the credentials in the wrong encoding -- so it is
+  // charset (RFC 7616 sec. 3.3): the one permitted value is the unquoted token "UTF-8". A quoted charset, or any
+  // other value, is malformed, since answering it would hash the credentials in the wrong encoding, so it is
   // rejected (and thus skipped during multi-offer selection in favour of a conforming offer).
   if (p.charset && (p.charset.quoted || String(p.charset.value).toUpperCase() !== "UTF-8")) throw E(code, "the Digest charset must be the unquoted token UTF-8 (RFC 7616 sec. 3.3)");
   // stale (RFC 7616 sec. 3.3) is the unquoted token "true" or "false". A quoted or otherwise invalid value
-  // (stale=maybe) is malformed and rejected (thus skipped in selection) rather than parsed as a false flag that
+  // (stale=maybe) is malformed and rejected (thus skipped in selection), never parsed as a false flag that
   // could shadow a conforming offer.
   if (p.stale) {
     var sv = String(p.stale.value).toLowerCase();
     if (p.stale.quoted || (sv !== "true" && sv !== "false")) throw E(code, "the Digest stale directive must be the unquoted token true or false (RFC 7616 sec. 3.3)");
   }
   // userhash (RFC 7616 sec. 3.3) is likewise the unquoted token "true" or "false". A quoted or otherwise invalid
-  // value is malformed and rejected (skipped in selection) rather than silently changing how the username is sent.
+  // value is malformed and rejected (skipped in selection), never silently changing how the username is sent.
   if (p.userhash) {
     var uhv = String(p.userhash.value).toLowerCase();
     if (p.userhash.quoted || (uhv !== "true" && uhv !== "false")) throw E(code, "the Digest userhash directive must be the unquoted token true or false (RFC 7616 sec. 3.3)");
   }
-  // opaque (RFC 7616 sec. 3.3) is a quoted-string echoed back verbatim. An UNQUOTED opaque is malformed and
-  // rejected (skipped in selection) rather than accepted, where it could shadow a conforming offer.
+  // opaque (RFC 7616 sec. 3.3) is a quoted-string echoed back verbatim. An unquoted opaque is malformed and
+  // rejected (skipped in selection), never accepted, where it could shadow a conforming offer.
   if (p.opaque && !p.opaque.quoted) throw E(code, "the Digest opaque directive must be a quoted-string (RFC 7616 sec. 3.3)");
   return {
     scheme: "Digest", realm: p.realm.value, nonce: p.nonce.value, qop: qop, domain: domain,
@@ -177,9 +177,9 @@ function _validateDigest(paramText, E, code) {
 // Selection is policy-aware: a challenge answer() would refuse under the active policy (an unsupported /
 // MD5-when-disallowed algorithm, or a qop this client cannot satisfy) is ranked BELOW every usable one, so a
 // higher-algorithm-rank but unusable offer (e.g. a SHA-512-256 no-qop challenge under the default policy)
-// never shadows a lower-ranked usable one (e.g. SHA-256 with qop="auth") -- RFC 7616 sec. 3.3. When NO
+// never shadows a lower-ranked usable one (e.g. SHA-256 with qop="auth"), per RFC 7616 sec. 3.3. When no
 // challenge is usable the highest-algorithm-rank one is still returned, so answer() reports the specific
-// policy reason (which opt to set) rather than a generic "no challenge".
+// policy reason (which opt to set) in place of a generic "no challenge".
 function parseChallenge(www, E, code, policy) {
   var pol = policy || {};
   var codes = pol.codes || DEFAULT_CODES;
@@ -210,9 +210,9 @@ function parseChallenge(www, E, code, policy) {
     // so it must not shadow a weaker offer that does apply. Only checked when the caller supplies the request
     // context; otherwise every offer is treated as applicable.
     var applicable = pol.requestTarget === undefined ? true : inProtectionSpace(parsed, pol.requestOrigin, pol.requestTarget);
-    // A RETRYABLE offer (only meaningful in the rejection context) is stale=true, carries a FRESH nonce, AND is
-    // for the SAME realm whose credential was just rejected -- the conditions under which the caller re-answers.
-    // A stale offer for a DIFFERENT realm is a new protection space (not a retry), and a stale offer repeating
+    // A retryable offer (only meaningful in the rejection context) is stale=true, carries a fresh nonce, and is
+    // for the same realm whose credential was just rejected: the conditions under which the caller re-answers.
+    // A stale offer for a different realm is a new protection space (not a retry), and a stale offer repeating
     // the prior nonce cannot re-answer, so neither must out-rank a weaker genuinely retryable offer (RFC 7616 sec. 3.3).
     var retryable = preferStale && !!parsed.stale && parsed.nonce !== pol.priorNonce && parsed.realm === pol.priorRealm;
     // Usability dominates; then an offer that APPLIES to this request; then (in a rejection) a retryable offer;
@@ -296,7 +296,7 @@ function answer(challenge, params, E) {
   var realm = challenge.realm, nonce = challenge.nonce;
   // Normalize UTF-8 credentials to NFC before hashing (RFC 7616 sec. 4): a server hashes the normalized form,
   // so a canonically-decomposed username / password (e + combining accent vs the precomposed char) must be
-  // composed first or HA1 disagrees. The SAME normalized username feeds A1, userhash, and username*.
+  // composed first or HA1 disagrees. That one normalized username feeds A1, userhash, and username*.
   var isUtf8 = String(challenge.charset || "").toUpperCase() === "UTF-8";
   var pUser = params.username == null ? "" : String(params.username);
   var pPass = params.password == null ? "" : String(params.password);
@@ -317,8 +317,8 @@ function answer(challenge, params, E) {
   var response = useQop
     ? KD(alg.hash, HA1, nonce + ":" + nc + ":" + cnonce + ":" + useQop + ":" + HA2)
     : KD(alg.hash, HA1, nonce + ":" + HA2);
-  // The username field (RFC 7616 sec. 3.4). userhash=true sends H(username:realm) for privacy (sec. 3.4.4) --
-  // an ASCII hex value; A1 above still used the REAL username. Otherwise a charset=UTF-8 username containing
+  // The username field (RFC 7616 sec. 3.4). userhash=true sends H(username:realm) for privacy (sec. 3.4.4),
+  // an ASCII hex value; A1 above still used the actual username. Otherwise a charset=UTF-8 username containing
   // non-ASCII characters MUST be carried in the extended `username*` form (RFC 5987 / RFC 8187 percent-encoded
   // UTF-8), because a server reads the legacy quoted `username` as ISO-8859-1 and could not resolve the account;
   // `username` and `username*` MUST NOT both appear. An ASCII (or userhash) username uses the legacy quoted form.
@@ -341,9 +341,9 @@ function answer(challenge, params, E) {
 }
 
 // Parse one domain URI entry (RFC 7616 sec. 3.3) into { origin, full }: an abs_path ("/a", "/a?x=1") is
-// relative to the responding server -> origin null (any same-origin request); an ABSOLUTE URI carries its own
-// authority -> origin "scheme://authority" (lowercased, default port normalized) and matches ONLY a request to
-// that SAME origin, since an entry to a different host names a protection space on a different server. `full` is
+// relative to the responding server -> origin null (any same-origin request); an absolute URI carries its own
+// authority -> origin "scheme://authority" (lowercased, default port normalized) and matches only a request to
+// that same origin, since an entry to a different host names a protection space on a different server. `full` is
 // the pathname + query the request URI is prefix-compared against. A relative / unparseable absolute entry -> null.
 function _domainEntry(d) {
   d = String(d == null ? "" : d);

package/lib/http-retry-after.js

@@ -4,8 +4,8 @@
 //
 // @internal -- the shared HTTP Retry-After parser (RFC 7231 sec. 7.1.3): a delay-seconds count OR an
 // HTTP-date (sec. 7.1.1.1). The enrollment protocol clients (pki.est now, pki.acme next) all surface a
-// server's Retry-After as a bounded delay -- never sleeping on it in a single-step call -- so the
-// delay-seconds | HTTP-date grammar and the one-year ceiling live in ONE place both compose, error-
+// server's Retry-After as a bounded delay, never sleeping on it in a single-step call, so the
+// delay-seconds | HTTP-date grammar and the one-year ceiling live in one place both compose, error-
 // factory-parameterized so each domain keeps its own typed verdict. A malformed / overflowing value
 // fails closed (the caller's E(code, ...)); the value is never returned unparsed.
 
@@ -26,7 +26,7 @@ var HTTP_DATE_FORMS = [
   new RegExp("^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) " + MONTH + " [ \\d]\\d \\d{2}:\\d{2}:\\d{2} \\d{4}$"),
 ];
 
-// Expand an obsolete RFC 850 two-digit year: HTTP interprets it RELATIVE TO the receipt year -- the full
+// Expand an obsolete RFC 850 two-digit year: HTTP interprets it relative to the receipt year, as the full
 // year with these two digits within [refYear-50, refYear+49] (moved to the past only when it would
 // otherwise be more than 50 years ahead). A fixed cutoff would misdate a year near the century boundary.
 // With no receipt time, fall back to the RFC 6265 fixed rule (< 70 -> 2000s, else 1900s).
@@ -34,15 +34,15 @@ function _rfc850Year(yy, refMs) {
   if (typeof refMs !== "number" || !isFinite(refMs)) return yy + (yy < 70 ? 2000 : 1900);
   var refYear = new Date(refMs).getUTCFullYear();
   var full = Math.floor(refYear / 100) * 100 + yy;
-  // Move to the PREVIOUS century ONLY when the same-century year would be more than 50 years ahead; never
+  // Move to the previous century only when the same-century year would be more than 50 years ahead; never
   // advance a past year to the future (an old two-digit year stays in the past).
   if (full - refYear > 50) full -= 100;
   return full;
 }
 
 // Parse an HTTP-date to epoch ms, or NaN when its grammar, calendar, or time is invalid. Built from the
-// extracted fields via Date.UTC (never Date.parse): every HTTP-date is UTC -- the asctime form carries
-// no GMT token, so delegating would parse it in LOCAL time -- and the round-trip check rejects an
+// extracted fields via Date.UTC (never Date.parse): every HTTP-date is UTC, the asctime form carries
+// no GMT token so delegating would parse it in local time, and the round-trip check rejects an
 // impossible date / time (Date.UTC normalizes Feb 31 -> Mar 2 just as Date.parse would).
 function httpDateMs(s, refMs) {
   if (!HTTP_DATE_FORMS.some(function (re) { return re.test(s); })) return NaN;
@@ -71,20 +71,20 @@ function httpDateMs(s, refMs) {
 // retryAfterDate (epoch ms) plus, when opts.now (epoch ms) is given, a bounded retryAfterSeconds. Either
 // form beyond the one-year ceiling, or a value that is neither, fails closed via opts.E(opts.code, ...).
 // opts.cap (seconds) clamps a value above the cap to the cap instead of rejecting it; opts.lenient surfaces
-// an otherwise-rejected value as a null retryAfterSeconds -- both for a caller (e.g. an ARI poll cadence)
-// for whom the value is advisory and must not discard the response. Never slept on here -- the value is
-// SURFACED for the caller to decide.
+// an otherwise-rejected value as a null retryAfterSeconds. Both exist for a caller (e.g. an ARI poll
+// cadence) for whom the value is advisory and must not discard the response. Nothing sleeps here; the
+// value is surfaced for the caller to decide.
 function parse(value, opts) {
   opts = opts || {};
   var raStr = String(value).trim();
   var out = { retryAfterSeconds: null, retryAfterDate: null };
   if (/^\d+$/.test(raStr)) {
     var n = parseInt(raStr, 10);
-    // opts.cap (seconds): a caller that will clamp anyway (e.g. an ARI poll cadence) wants a delay ABOVE its
-    // ceiling reduced to the ceiling, not rejected -- so a valid-but-huge value never discards the response.
+    // opts.cap (seconds): a caller that will clamp anyway (e.g. an ARI poll cadence) wants a delay above its
+    // ceiling reduced to the ceiling, not rejected, so a valid-but-huge value never discards the response.
     if (typeof opts.cap === "number" && n > opts.cap) { out.retryAfterSeconds = opts.cap; return out; }
-    // opts.lenient: a caller for whom the value is purely advisory wants an UNPARSEABLE one surfaced as
-    // null (retryAfterSeconds stays null) rather than a hard reject that would discard the whole response.
+    // opts.lenient: a caller for whom the value is purely advisory wants an unparseable one surfaced as
+    // null (retryAfterSeconds stays null) instead of a hard reject that would discard the whole response.
     if (!Number.isSafeInteger(n) || n > MAX_RETRY_AFTER_SECONDS) { if (opts.lenient) return out; throw _fail(opts, "the Retry-After delay is out of the supported range (0.." + MAX_RETRY_AFTER_SECONDS + " seconds)"); }
     out.retryAfterSeconds = n;
     return out;

package/lib/http-transport.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   The shared, fail-closed `node:https` transport the enrollment protocol clients
- *   drive -- `pki.est` now, `pki.acme` and `pki.cmp` next. This is the ONLY module in
+ *   drive: `pki.est` now, `pki.acme` and `pki.cmp` next. This is the only module in
  *   the toolkit that opens a socket; every protocol layer stays transport-agnostic and
  *   composes it (or an injected substitute) through one contract:
  *   `transport(request) -> Promise<{ status, headers, body, tls }>`. The first three are
@@ -21,7 +21,7 @@
  *   channel -- `{ protocol, cipher, peerCertificate }` -- which is the one fact a caller
  *   cannot recover from the response bytes. An INJECTED substitute should return it too:
  *   `pki.est.serverkeygen` asserts the negotiated cipher can protect the private key it
- *   is about to accept, and a transport that reports no cipher is trusted rather than
+ *   is about to accept, and a transport that reports no cipher is trusted instead of
  *   refused (so a loopback test channel works), which means omitting the field silently
  *   skips that assertion.
  *
@@ -29,7 +29,7 @@
  *   transport. Trust is EXPLICIT and fail-closed: a request is refused unless it
  *   carries an https URL and either a `tls.anchors` set (an Explicit trust-anchor
  *   database, mapped to the node `ca` option) or an explicit `tls.useSystemStore`
- *   opt-in to node's bundled roots. `rejectUnauthorized` is ALWAYS on -- there is no
+ *   opt-in to node's bundled roots. `rejectUnauthorized` is always on: there is no
  *   code path that disables server-certificate verification. The response body is
  *   bounded WHILE it streams: the accumulator aborts the socket the instant the running
  *   total crosses `maxResponseBytes`, before a byte reaches a decoder. A protocol
@@ -64,8 +64,8 @@ function _budget(value, key, dflt, max, E, code) {
   return guard.limits.cap(value, key, dflt, { E: E, code: code, min: 1, max: max, label: key });
 }
 
-// Node's `ca` option expects PEM; a raw DER certificate Buffer -- the toolkit's native trust-anchor
-// form (e.g. what pki.est.cacerts / parseCertsOnly return) -- is silently ignored there, so the
+// Node's `ca` option expects PEM. A raw DER certificate Buffer, the toolkit's native trust-anchor
+// form (e.g. what pki.est.cacerts / parseCertsOnly return), is silently ignored there, so the
 // connection would fail server authentication despite a valid anchor. Wrap a DER anchor as PEM
 // (a Buffer already carrying PEM text, or a PEM string, passes through unchanged).
 function _pemifyAnchor(a) {
@@ -86,7 +86,7 @@ function _pemifyAnchors(anchors) {
 }
 
 // The OS system certificate store plus node's bundled roots (cached; the read is not free), for a
-// tls.useSystemStore opt-in. Node's default (no `ca`) is ONLY the bundled Mozilla set, so a server
+// tls.useSystemStore opt-in. Node's default (no `ca`) is just the bundled Mozilla set, so a server
 // chaining to an OS-installed enterprise CA would fail without this. On a node too old for
 // tls.getCACertificates the cache stays empty and the caller falls back to node's default store.
 var _systemCaCache = null;
@@ -96,7 +96,7 @@ function _systemCa() {
   if (typeof nodeTls.getCACertificates === "function") {
     ["system", "bundled"].forEach(function (t) {
       // allow:swallow-unverified a store TYPE unsupported on this node is skipped; the other type
-      // (and, if both fail, node's default-store fallback) still applies -- a best-effort store load.
+      // (and, if both fail, node's default-store fallback) still applies. Best-effort store load.
       try { var c = nodeTls.getCACertificates(t); if (Array.isArray(c)) out = out.concat(c); } catch (_e) { /* unsupported type */ }
     });
   }
@@ -107,14 +107,14 @@ function _systemCa() {
 // Classify a bare IP string (no brackets) as a private / loopback / link-local / reserved destination an
 // untrusted URL must not reach: RFC 1918 + loopback + this-network + multicast/reserved + 169.254 (cloud
 // metadata) + CGNAT for IPv4, and loopback / unspecified / IPv4-mapped / ULA (fc00::/7) + link-local (fe80::/10)
-// for IPv6. This is the SAME range set the AIA literal pre-check applies (pki.path.build reuses it), enforced
-// here at DNS-RESOLUTION time so a hostname pointing AT an internal address is caught too. A malformed IP fails
-// CLOSED (net.isIP === 0 -> not a v4/v6 arm -> the caller treats a non-IP as un-judgeable, never as public).
+// for IPv6. This is the same range set the AIA literal pre-check applies (pki.path.build reuses it), enforced
+// here at DNS-resolution time so a hostname pointing at an internal address is caught too. A malformed IP fails
+// closed (net.isIP === 0 -> not a v4/v6 arm -> the caller treats a non-IP as un-judgeable, never as public).
 function _isBlockedIp(ip) {
   var fam = nodeNet.isIP(ip);
   if (fam === 4) {
-    // net.isIP === 4 guarantees exactly four octets 0..255. Block the COMPLETE IANA special-purpose /
-    // non-global set (RFC 6890) so an untrusted destination can reach ONLY globally-routable public space.
+    // net.isIP === 4 guarantees exactly four octets 0..255. Block the complete IANA special-purpose /
+    // non-global set (RFC 6890) so an untrusted destination can reach only globally-routable public space.
     var o = ip.split("."), a = +o[0], b = +o[1], c = +o[2];
     return a === 0 || a === 10 || a === 127 || a >= 224 ||                 // this-network / RFC1918 10/8 / loopback / multicast 224/4 + reserved 240/4 + broadcast
       (a === 100 && b >= 64 && b <= 127) ||                                 // 100.64/10 CGNAT
@@ -146,17 +146,18 @@ function _isBlockedIp(ip) {
   return false;
 }
 
-// A DNS-rebinding-safe SSRF filter, installed as node's `lookup` ONLY when a request opts into
-// blockPrivateAddresses (the AIA fetch of an untrusted-cert URL). node connects to EXACTLY the address this
-// returns -- no second resolution -- so checking the resolved address here PINS it, closing the resolve/connect
-// TOCTOU. Any private / loopback / link-local result fails the lookup, which surfaces as transport/blocked-address.
+// A DNS-rebinding-safe SSRF filter, installed as node's `lookup` only when a request opts into
+// blockPrivateAddresses (the AIA fetch of an untrusted-cert URL). node connects to exactly the address this
+// returns, with no second resolution, so checking the resolved address here pins it and closes the
+// resolve/connect TOCTOU. Any private, loopback or link-local result fails the lookup, which surfaces as
+// transport/blocked-address.
 function _blockedAddrErr(hostname, address) {
   var e = new Error("refusing to connect to " + hostname + " -> " + address + " (private / loopback / link-local address blocked)");
   e.pkiBlockedAddress = true;
   return e;
 }
-// Built over an injectable resolver (defaults to nodeDns.lookup) so every branch -- a resolve error, the
-// options.all array shape, a blocked result, a permitted result -- is unit-testable without a live DNS.
+// Built over an injectable resolver (defaults to nodeDns.lookup) so every branch (a resolve error, the
+// options.all array shape, a blocked result, a permitted result) is unit-testable without a live DNS.
 function _makeGuardedLookup(lookupFn) {
   return function guardedLookup(hostname, options, callback) {
     lookupFn(hostname, options || {}, function (err, address, family) {
@@ -211,7 +212,7 @@ function _classifyError(e, C) {
  *
  * @opts
  *   - `tls.anchors` -- Explicit trust anchor(s): a DER/PEM Buffer, an array, or PEM string(s) (node `ca`).
- *   - `tls.useSystemStore` -- boolean; the ONLY opt-in to node's bundled CA store (default false).
+ *   - `tls.useSystemStore` -- boolean; the one opt-in to node's bundled CA store (default false).
  *   - `tls.cert` / `tls.key` -- client certificate + key for mutual-TLS re-enrollment.
  *   - `tls.minVersion` -- 'TLSv1.2' (default) or 'TLSv1.3'; never below the floor.
  *   - `tls.servername` / `tls.checkServerIdentity` -- SNI + RFC 6125 identity; may tighten, never disable.