@blamejs/pki 0.6.14 → 0.6.15

package/lib/http-digest.js

@@ -1,36 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @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 (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 or nonce is rejected and not defaulted, and an unsupported or
-// weak algorithm, or a no-qop challenge, fails closed instead of downgrading.
+// @internal
 
 var crypto = require("crypto");
 var constants = require("./constants");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides whether an auth-param repeats --
-// answering false lets the second copy of a nonce overwrite the first.
 var _hasOwn = intrinsic.hasOwn;
 var _charCodeAt = intrinsic.uncurry(String.prototype.charCodeAt);
 var _strSlice = intrinsic.uncurry(String.prototype.slice);
 var _fromCharCode = intrinsic.fromCharCode;
-var pkix = require("./schema-pkix");   // the shared JS-\s code-point predicate (pkix.isJsWhitespace)
+var pkix = require("./schema-pkix");
 
-// 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.
-//
-// Null prototype, because the gate on an unknown algorithm is `if (!ALGS[name])`. With an ordinary
-// object literal that question is asked of the prototype chain too, so an algorithm named for any
-// member of Object.prototype answers with a truthy value the table never carried: the
-// unsupported-algorithm refusal is skipped and the descriptor's own fields read as undefined.
 var ALGS = intrinsic.assign(intrinsic.create(null), {
   "SHA-512-256": { hash: "sha512-256", rank: 3, sess: false }, "SHA-512-256-SESS": { hash: "sha512-256", rank: 3, sess: true },
   "SHA-256": { hash: "sha256", rank: 2, sess: false }, "SHA-256-SESS": { hash: "sha256", rank: 2, sess: true },
@@ -41,18 +22,14 @@ var DEFAULT_CODES = {
   noQop: "digest/no-qop", badChallenge: "digest/bad-challenge",
 };
 
-// H = lowercase-hex digest; the octet string is fed as latin1 so a UTF-8-encoded credential (charset=UTF-8)
-// is hashed over its exact bytes. KD(secret, data) = H(secret ":" data).
 function H(hash, s) { return crypto.createHash(hash).update(s, "latin1").digest("hex"); }
 function KD(hash, secret, data) { return H(hash, secret + ":" + data); }
-// Quote a value: wrap in double quotes, backslash-escaping any " or \ (matching /(["\\])/g -> "\\$1").
 function _qstr(v) {
   var s = String(v), out = "";
   for (var i = 0; i < s.length; i++) { var c = _charCodeAt(s, i); if (c === 34 || c === 92) out += "\\"; out += _fromCharCode(c); }
   return "\"" + out + "\"";
 }
 
-// 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++) {
@@ -66,7 +43,6 @@ function _commaSplitOutsideQuotes(s) {
   out.push(buf);
   return out;
 }
-// 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++) {
@@ -78,15 +54,11 @@ function _firstEqOutsideQuotes(s) {
   }
   return -1;
 }
-// Unquote a well-formed quoted-string (only ever called after _closedQuote): drop the surrounding
-// quotes and each escaping backslash (matching s.slice(1,-1).replace(/\\(.)/g, "$1")).
 function _unq(s) {
-  var out = "", last = 1, n = s.length;                       // skip the opening quote at 0
+  var out = "", last = 1, n = s.length;
   for (var i = 1; i < n - 1; i++) { if (_charCodeAt(s, i) === 92) { out += _strSlice(s, last, i); last = i + 1; i += 1; } }
-  return out + _strSlice(s, last, n - 1);                     // trailing content, excluding the closing quote
+  return out + _strSlice(s, last, n - 1);
 }
-// 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;
   var esc = false;
@@ -98,41 +70,31 @@ function _closedQuote(s) {
   }
   return false;
 }
-// A control octet (RFC 7230 sec. 3.2.6 quoted-string / qdtext forbids CTL except HTAB). Scanned with charCodeAt
-// 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 = _charCodeAt(s, i); if ((c < 0x20 && c !== 0x09) || c === 0x7f) return true; }
   return false;
 }
 
-// Split a WWW-Authenticate header into [{ scheme, paramText }]. A comma-separated segment whose pre-'='
-// text is "token WS token" (a scheme name before the first auth-param key), or a bare token with no '=',
-// STARTS a new challenge; a "key=value" segment is a param continuation of the current challenge.
-// The leading token when `pre` is "token WS more" (/^(\S+)\s+(\S[\s\S]*)$/) -- a scheme name before the
-// first auth-param -- else null. \s is the shared JS-\s predicate (RFC 7230 OWS is a subset).
 function _matchTokenRest(pre) {
   var n = pre.length, p = 0;
-  while (p < n && !pkix.isJsWhitespace(_charCodeAt(pre, p))) p += 1;              // ^(\S+)
+  while (p < n && !pkix.isJsWhitespace(_charCodeAt(pre, p))) p += 1;
   if (p === 0) return null;
   var tokEnd = p;
-  if (p >= n || !pkix.isJsWhitespace(_charCodeAt(pre, p))) return null;          // \s+
+  if (p >= n || !pkix.isJsWhitespace(_charCodeAt(pre, p))) return null;
   while (p < n && pkix.isJsWhitespace(_charCodeAt(pre, p))) p += 1;
-  if (p >= n || pkix.isJsWhitespace(_charCodeAt(pre, p))) return null;           // (\S[\s\S]*)$ -- at least one non-\s
+  if (p >= n || pkix.isJsWhitespace(_charCodeAt(pre, p))) return null;
   return _strSlice(pre, 0, tokEnd);
 }
-// The index past a leading "OWS token OWS" (/^\s*\S+\s+/), or 0 when the string does not begin that way.
-// The caller slices from this index (the slice that replaces the removed .replace).
 function _stripTokenIndex(seg) {
   var n = seg.length, p = 0;
-  while (p < n && pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;              // ^\s*
+  while (p < n && pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;
   var ts = p;
-  while (p < n && !pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;             // \S+
+  while (p < n && !pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;
   if (p === ts) return 0;
   var ws = p;
-  while (p < n && pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;              // \s+ (required)
+  while (p < n && pkix.isJsWhitespace(_charCodeAt(seg, p))) p += 1;
   return p === ws ? 0 : p;
 }
-// String.prototype.split(/\s+/): the pieces between \s runs (a leading/trailing run yields a "" element).
 function _splitWhitespace(s) {
   var out = [], i = 0, n = s.length, ps = 0;
   while (i < n) {
@@ -155,13 +117,12 @@ function _splitChallenges(s) {
     var eq = _firstEqOutsideQuotes(seg);
     var pre = (eq < 0 ? seg : _strSlice(seg, 0, eq)).trim();
     var scheme = _matchTokenRest(pre);
-    if (eq < 0) { cur = { scheme: seg, paramText: "" }; out.push(cur); }        // a bare scheme token (e.g. "Basic")
-    else if (scheme !== null) { cur = { scheme: scheme, paramText: _strSlice(seg, _stripTokenIndex(seg)) }; out.push(cur); }   // "scheme firstKey=..."
-    else if (cur) { cur.paramText = cur.paramText ? cur.paramText + "," + seg : seg; }                   // "key=value" continuation
+    if (eq < 0) { cur = { scheme: seg, paramText: "" }; out.push(cur); }
+    else if (scheme !== null) { cur = { scheme: scheme, paramText: _strSlice(seg, _stripTokenIndex(seg)) }; out.push(cur); }
+    else if (cur) { cur.paramText = cur.paramText ? cur.paramText + "," + seg : seg; }
   }
   return out;
 }
-// Parse a challenge's params into { key(lower): { value, quoted } }; a repeated key is malformed (fail closed).
 function _parseParams(paramText, E, code) {
   var segs = _commaSplitOutsideQuotes(paramText), map = Object.create(null);
   for (var i = 0; i < segs.length; i++) {
@@ -175,14 +136,11 @@ function _parseParams(paramText, E, code) {
     if (quoted && !_closedQuote(rawVal)) throw E(code, "an unterminated or trailing-garbage Digest quoted-string (RFC 7230 sec. 3.2.6)");
     if (_hasOwn(map, key)) throw E(code, "repeated Digest auth-param " + JSON.stringify(key));
     var value = quoted ? _unq(rawVal) : rawVal;
-    // Reject a control octet in any value (CR / LF / NUL / ...): it is a MUST-reject per RFC 7230 qdtext AND a
-    // header-injection sink -- an unescaped CR/LF reflected into the outgoing Authorization would split the header.
     if (_hasCtl(value)) throw E(code, "a Digest auth-param value contains a control character (RFC 7230 sec. 3.2.6)");
     map[key] = { value: value, quoted: quoted };
   }
   return map;
 }
-// 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)");
@@ -192,38 +150,20 @@ 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.trim().toLowerCase(); }).filter(Boolean);
-    // 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) 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.trim() !== "")
     ? _splitWhitespace(p.domain.value.trim()) : null;
-  // 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 favor 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), 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), 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), 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,
@@ -235,21 +175,9 @@ function _validateDigest(paramText, E, code) {
   };
 }
 
-// parseChallenge(www, E, code, policy?) -> the most-secure USABLE structurally-valid Digest challenge,
-//   OR null (no Digest challenge present),  OR throw E(code) (a Digest challenge present but none valid).
-// 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"), 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) in place of a generic "no challenge".
 function parseChallenge(www, E, code, policy) {
   var pol = policy || {};
   var codes = pol.codes || DEFAULT_CODES;
-  // preferStale marks a CREDENTIAL-REJECTION context (a 401 answering a credentialed request in the same space):
-  // there, a stale=true offer is RETRYABLE with a fresh nonce while a stale=false offer is a terminal rejection,
-  // so a retryable offer must outrank a stronger non-retryable one (RFC 7616 sec. 3.3). In the initial context
-  // it is not set and stale plays no part.
   var preferStale = !!pol.preferStale;
   var raw = String(www == null ? "" : www);
   if (raw.length > constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES) throw E(code, "the WWW-Authenticate header exceeds the " + constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES + "-byte cap");
@@ -259,8 +187,6 @@ function parseChallenge(www, E, code, policy) {
     if (challenges[i].scheme.toLowerCase() !== "digest") continue;
     sawDigest = true;
     var parsed;
-    // A MALFORMED offer is skipped, not fatal: parseChallenge's contract is to throw only when NO valid Digest
-    // offer exists (RFC 7616 sec. 3.3), so a bad offer alongside a good one still authenticates on the good one.
     try { parsed = _validateDigest(challenges[i].paramText, E, code); }
     catch (_e) {
       continue;
@@ -268,18 +194,8 @@ function parseChallenge(www, E, code, policy) {
     var alg = ALGS[parsed.algorithm];
     var rank = alg ? alg.rank : 0;
     var usable = _rejection(parsed, pol, codes) === null;
-    // APPLICABLE: the offer's own protection space covers the CURRENT request target (RFC 7616 sec. 3.5). An
-    // offer whose `domain` excludes this request cannot authenticate it (the caller would omit the credential),
-    // 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
-    // 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;
-    // then the stronger algorithm.
     if (best === null ||
         (usable && !bestUsable) ||
         (usable === bestUsable && applicable && !bestApplicable) ||
@@ -293,22 +209,17 @@ function parseChallenge(www, E, code, policy) {
   return null;
 }
 
-// Credential octets for the given charset (RFC 7616 sec. 4): UTF-8 -> the exact UTF-8 bytes; else the
-// string as-is (ASCII / latin1). H() hashes over latin1, so a UTF-8 credential is fed as its octet string.
 function _octets(s, charset) {
   var v = s == null ? "" : String(s);
   return (charset && String(charset).toUpperCase() === "UTF-8") ? Buffer.from(v, "utf8").toString("latin1") : v;
 }
 
-// Does the string carry any non-ASCII code unit (> U+007F)? Such a UTF-8 username is sent via `username*`.
 function _hasNonAscii(s) {
   s = String(s == null ? "" : s);
   for (var i = 0; i < s.length; i++) { if (_charCodeAt(s, i) > 0x7F) return true; }
   return false;
 }
 
-// RFC 5987 / RFC 8187 percent-encoding of a string's UTF-8 octets: attr-char (ALPHA / DIGIT / "!#$&+-.^_`|~")
-// is kept literal, every other octet is %XX (upper-hex). Used for the Digest `username*` extended value.
 function _pctEncodeUtf8(s) {
   var bytes = Buffer.from(String(s == null ? "" : s), "utf8");
   var out = "";
@@ -325,11 +236,6 @@ function _pctEncodeUtf8(s) {
   return out;
 }
 
-// The policy gates a parsed challenge must clear to be answerable (RFC 7616 sec. 3.4): a supported
-// algorithm, MD5 only when allowed, and a qop this client can satisfy (auth / auth-int, or no-qop only when
-// allowLegacyQop). Returns a { code, msg } rejection or null. This is the SINGLE definition both answer()
-// and parseChallenge() consult, so challenge SELECTION can never rank a challenge as usable that answer()
-// would then refuse (or vice-versa) -- the two cannot drift.
 function _rejection(challenge, pol, codes) {
   var alg = ALGS[challenge.algorithm];
   if (!alg) return { code: codes.unsupportedAlgorithm, msg: "unsupported Digest algorithm " + challenge.algorithm + " (supported: SHA-512-256, SHA-256, MD5)" };
@@ -342,7 +248,6 @@ function _rejection(challenge, pol, codes) {
   return null;
 }
 
-// answer(challenge, { method, uri, username, password, body, policy, rng }, E) -> the Authorization header value.
 function answer(challenge, params, E) {
   var pol = params.policy || {};
   var codes = pol.codes || DEFAULT_CODES;
@@ -351,15 +256,7 @@ function answer(challenge, params, E) {
   var alg = ALGS[challenge.algorithm];
   var useQop = challenge.qop.indexOf("auth") !== -1 ? "auth" : (challenge.qop.indexOf("auth-int") !== -1 ? "auth-int" : null);
   var cnonce = String((params.rng || function () { return crypto.randomBytes(18).toString("base64"); })());
-  // The realm is used with its incoming header OCTETS unchanged (RFC 7616 sec. 4). The realm arrives from the
-  // wire, so a transport that exposes header bytes as Latin-1 (the Node default) already presents the server's
-  // UTF-8 octets one-per-char; re-encoding them as UTF-8 (as user / pass, which come from the caller as Unicode
-  // strings, correctly do) would DOUBLE-encode and make the digest disagree with the server. H() hashes over
-  // Latin-1, so the raw realm string contributes exactly the octets the server used.
   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. 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);
@@ -372,19 +269,11 @@ function answer(challenge, params, E) {
     ? params.method + ":" + params.uri + ":" + H(alg.hash, params.body == null ? "" : params.body)
     : params.method + ":" + params.uri;
   var HA2 = H(alg.hash, A2);
-  // The nonce-count: a (nonce, nc) pair MUST NOT be reused (RFC 7616 sec. 3.4), so a request that REUSES a nonce
-  // (a same-origin redirect, an auth-int retry) increments nc; a fresh nonce restarts at 1. The caller supplies
-  // the count for this nonce (default 1); formatted as 8 lowercase hex.
   var ncNum = (typeof params.nc === "number" && params.nc >= 1) ? Math.floor(params.nc) : 1;
   var nc = _strSlice("0000000" + ncNum.toString(16), -8);
   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 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.
   var parts;
   if (!challenge.userhash && isUtf8 && _hasNonAscii(pUser)) {
     parts = ["username*=UTF-8''" + _pctEncodeUtf8(pUser)];
@@ -394,8 +283,6 @@ function answer(challenge, params, E) {
   }
   parts.push("realm=" + _qstr(realm), "nonce=" + _qstr(nonce), "uri=" + _qstr(params.uri), "algorithm=" + challenge.algorithm);
   if (useQop) { parts.push("qop=" + useQop); parts.push("nc=" + nc); }
-  // The cnonce directive is emitted whenever the server needs it to recompute the response: under a qop, and
-  // also under a -sess algorithm whose A1 folds in the cnonce even with no qop (RFC 7616 sec. 3.4.2 / 3.9.1).
   if (useQop || alg.sess) { parts.push("cnonce=" + _qstr(cnonce)); }
   parts.push("response=" + _qstr(response));
   if (challenge.opaque != null) parts.push("opaque=" + _qstr(challenge.opaque));
@@ -403,28 +290,13 @@ function answer(challenge, params, E) {
   return "Digest " + parts.join(", ");
 }
 
-// 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
-// the pathname + query the request URI is prefix-compared against. A relative / unparseable absolute entry -> null.
 function _domainEntry(d) {
   d = String(d == null ? "" : d);
   if (d.charAt(0) === "/") return { origin: null, full: d };
-  // An absolute entry is parsed through the URL constructor so its origin is NORMALIZED the same way the
-  // request's URL.origin is -- an explicit default port (https :443 / http :80) is dropped, so a domain naming
-  // "https://h:443/x" still matches a request whose origin normalizes to "https://h". A relative / unparseable
-  // entry throws and never matches (fail closed).
   try { var u = new URL(d); return { origin: u.origin.toLowerCase(), full: (u.pathname || "/") + (u.search || "") }; }
   catch (_e) { return null; }
 }
 
-// inProtectionSpace(challenge, requestOrigin, requestPathAndSearch) -> is the request within the challenge's
-// protection space? An absent / empty domain means "all URIs on the responding server" (RFC 7616 sec. 3.3), so
-// any same-origin request matches; otherwise membership is by LITERAL URI PREFIX (RFC 7616 sec. 3.5 / RFC 2617
-// sec. 1.2): the request's pathname + query must have a listed domain URI as a prefix, and for an absolute entry
-// the same origin. The query is part of the prefix, so /enroll?tenant=a does not cover /enroll?tenant=b while a
-// query-less /enroll covers its whole subtree (including /enroll?...). Used to scope where a cached answer is reused.
 function inProtectionSpace(challenge, requestOrigin, requestPathAndSearch) {
   var domain = challenge && challenge.domain;
   if (!domain || !domain.length) return true;
@@ -433,7 +305,7 @@ function inProtectionSpace(challenge, requestOrigin, requestPathAndSearch) {
   for (var i = 0; i < domain.length; i++) {
     var e = _domainEntry(domain[i]);
     if (e === null) continue;
-    if (e.origin !== null && e.origin !== origin) continue;   // an absolute entry to a DIFFERENT origin is a different protection space
+    if (e.origin !== null && e.origin !== origin) continue;
     if (full.indexOf(e.full) === 0) return true;
   }
   return false;

package/lib/http-retry-after.js

@@ -1,66 +1,41 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @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-
-// 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.
+// @internal
 
 var constants = require("./constants");
 
-// The largest delay this parser surfaces as a number: a generous one-year ceiling that keeps the
-// value a safe integer and rejects an overflowing / nonsensical delay-seconds or far-future date.
 var MAX_RETRY_AFTER_SECONDS = constants.TIME.days(365) / constants.TIME.seconds(1);
 
-// The three HTTP-date forms (RFC 7231 sec. 7.1.1.1): IMF-fixdate (the required form), and the obsolete
-// rfc850-date / asctime-date a recipient must still accept. Gating Date.parse on this grammar keeps its
-// permissiveness (an ISO string like "2026-07-10") from passing as a valid Retry-After header.
 var MONTHS = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
 var DOW_SHORT = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
 var DOW_LONG = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
 
-// The grammar is scanned character by character (no regex): each form is a fixed layout of a
-// day-of-week name, delimiters, an all-digit field, a three-letter month name, and an HH:MM:SS time.
 function _isDigit(ch) { return ch >= "0" && ch <= "9"; }
-// The two-digit / four-digit integer at `i`, or -1 when those positions are not all digits.
 function _digits2(s, i) { return _isDigit(s.charAt(i)) && _isDigit(s.charAt(i + 1)) ? (s.charCodeAt(i) - 48) * 10 + (s.charCodeAt(i + 1) - 48) : -1; }
 function _digits4(s, i) { for (var k = 0; k < 4; k++) if (!_isDigit(s.charAt(i + k))) return -1; return parseInt(s.slice(i, i + 4), 10); }
-// The length of a name from `list` matching `s` at `i` (the day-of-week alternation), or -1.
 function _matchName(s, i, list) { for (var j = 0; j < list.length; j++) { if (s.slice(i, i + list[j].length) === list[j]) return list[j].length; } return -1; }
-// The three-letter month at `i` when it is a real month name, else null.
 function _monthAt(s, i) { return _matchName(s, i, MONTHS) === -1 ? null : s.slice(i, i + 3); }
-// An "HH:MM:SS" time at `i` -> { hh, mi, ss, next } (next = i + 8), or null.
 function _timeAt(s, i) {
   var hh = _digits2(s, i); if (hh < 0 || s.charAt(i + 2) !== ":") return null;
   var mi = _digits2(s, i + 3); if (mi < 0 || s.charAt(i + 5) !== ":") return null;
   var ss = _digits2(s, i + 6); if (ss < 0) return null;
   return { hh: hh, mi: mi, ss: ss, next: i + 8 };
 }
-// A non-empty run of ASCII digits (matching /^\d+$/, the delay-seconds form).
 function _isAllDigits(s) {
   if (s.length === 0) return false;
   for (var i = 0; i < s.length; i++) if (!_isDigit(s.charAt(i))) return false;
   return true;
 }
 
-// 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).
 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
-  // advance a past year to the future (an old two-digit year stays in the past).
   if (full - refYear > 50) full -= 100;
   return full;
 }
 
-// IMF-fixdate (the required form): "Sun, 06 Nov 1994 08:49:37 GMT".
 function _scanImf(s) {
   var p = _matchName(s, 0, DOW_SHORT);
   if (p === -1 || s.slice(p, p + 2) !== ", ") return null; p += 2;
@@ -70,8 +45,6 @@ function _scanImf(s) {
   var t = _timeAt(s, p); if (!t || s.slice(t.next, t.next + 4) !== " GMT" || t.next + 4 !== s.length) return null;
   return { day: dd, monName: mo, year: yy, hh: t.hh, mi: t.mi, ss: t.ss };
 }
-// rfc850-date (obsolete, still accepted): "Sunday, 06-Nov-94 08:49:37 GMT" -- a two-digit year expanded
-// relative to the receipt year.
 function _scanRfc850(s, refMs) {
   var p = _matchName(s, 0, DOW_LONG);
   if (p === -1 || s.slice(p, p + 2) !== ", ") return null; p += 2;
@@ -81,7 +54,6 @@ function _scanRfc850(s, refMs) {
   var t = _timeAt(s, p); if (!t || s.slice(t.next, t.next + 4) !== " GMT" || t.next + 4 !== s.length) return null;
   return { day: dd, monName: mo, year: _rfc850Year(yy, refMs), hh: t.hh, mi: t.mi, ss: t.ss };
 }
-// asctime-date (obsolete, still accepted): "Sun Nov  6 08:49:37 1994" -- a space-padded one/two-digit day.
 function _scanAsctime(s) {
   var p = _matchName(s, 0, DOW_SHORT);
   if (p === -1 || s.charAt(p) !== " ") return null; p += 1;
@@ -94,10 +66,6 @@ function _scanAsctime(s) {
   return { day: dd, monName: mo, year: yy, hh: t.hh, mi: t.mi, ss: t.ss };
 }
 
-// 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
-// impossible date / time (Date.UTC normalizes Feb 31 -> Mar 2 just as Date.parse would).
 function httpDateMs(s, refMs) {
   var f = _scanImf(s) || _scanRfc850(s, refMs) || _scanAsctime(s);
   if (!f) return NaN;
@@ -110,25 +78,13 @@ function httpDateMs(s, refMs) {
   return when;
 }
 
-// parse(value, opts) -> { retryAfterSeconds, retryAfterDate }. A PRESENT Retry-After value (the caller
-// gates absence with its own code) is a delay-seconds integer -> retryAfterSeconds, or an HTTP-date ->
-// 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 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 (_isAllDigits(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.
     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) 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;
@@ -137,8 +93,6 @@ function parse(value, opts) {
   if (isNaN(when)) { if (opts.lenient) return out; throw _fail(opts, "a Retry-After must be delay-seconds or a valid HTTP-date (RFC 7231 sec. 7.1.1.1/7.1.3), got " + JSON.stringify(raStr)); }
   out.retryAfterDate = when;
   if (typeof opts.now === "number" && isFinite(opts.now)) {
-    // Round the remaining whole-second delay UP (a sub-second date must not retry before the requested
-    // time), clamping a past date to 0.
     var d = Math.max(0, Math.ceil((when - opts.now) / constants.TIME.seconds(1)));
     if (typeof opts.cap === "number" && d > opts.cap) { out.retryAfterSeconds = opts.cap; return out; }
     if (d > MAX_RETRY_AFTER_SECONDS) { if (opts.lenient) return out; throw _fail(opts, "the Retry-After date is beyond the supported horizon (" + MAX_RETRY_AFTER_SECONDS + " seconds)"); }