@blamejs/pki 0.6.14 → 0.6.16

package/lib/http-transport.js

@@ -58,37 +58,22 @@ var DEFAULT_TIMEOUT = constants.TIME.seconds(30);
 var MAX_TIMEOUT = constants.TIME.seconds(600);
 var DEFAULT_MIN_VERSION = "TLSv1.2";
 
-// A config-time budget: cap() with the caller's typed factory + a >= 1 floor and an
-// upper bound (maxResponseBytes may only be tightened DOWNWARD from the default). A
-// NaN / negative / over-max value is a typed reject, never a silently-disabled bound.
 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
-// 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).
-// The JS regex \s code points representable in a latin1 string (0..255): TAB LF VT FF CR SP NBSP.
-// Built at load so the source stays pure ASCII. The armor scan runs over a latin1 prefix, where these
-// are the only \s characters that can appear, so this is exactly /^\s*/ for that input.
 var _LATIN1_WS = String.fromCharCode(0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20, 0xa0);
 
-// PEM armor at the START after optional whitespace, decided by character scan (no regex): skip the
-// leading \s run, then require "-----BEGIN ".
 function _looksLikePemArmor(s) {
   var i = 0;
   while (i < s.length && _LATIN1_WS.indexOf(s.charAt(i)) !== -1) i += 1;
   return s.slice(i, i + 11) === "-----BEGIN ";
 }
-// Base64 wrapped to <=64-column lines, each terminated by LF (matching /.{1,64}/g -> "$&\n", which
-// keeps a trailing LF on the final line).
 function _wrap64Lines(s) {
   var out = "";
   for (var i = 0; i < s.length; i += 64) out += s.slice(i, i + 64) + "\n";
   return out;
 }
-// The surrounding "[" "]" of an IPv6 literal removed, else the string unchanged (matching /^\[(.*)\]$/).
 function _stripIpv6Brackets(s) {
   return (s.length >= 2 && s.charAt(0) === "[" && s.charAt(s.length - 1) === "]") ? s.slice(1, s.length - 1) : s;
 }
@@ -96,9 +81,6 @@ function _stripIpv6Brackets(s) {
 function _pemifyAnchor(a) {
   if (typeof a === "string") return a;
   if (Buffer.isBuffer(a)) {
-    // Detect PEM by its armor at the START (after optional whitespace) only: a DER certificate begins
-    // with the SEQUENCE tag 0x30 and may itself contain the bytes "-----BEGIN" in a subject / extension
-    // value, so an anywhere-search would leave such a DER anchor unwrapped and unusable.
     if (_looksLikePemArmor(a.toString("latin1", 0, 64))) return a;
     var b64 = _wrap64Lines(a.toString("base64"));
     return "-----BEGIN CERTIFICATE-----\n" + b64 + "-----END CERTIFICATE-----\n";
@@ -110,10 +92,6 @@ function _pemifyAnchors(anchors) {
   return list;
 }
 
-// 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 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;
 function _systemCa() {
   if (_systemCaCache !== null) return _systemCaCache;
@@ -121,73 +99,54 @@ 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. Best-effort store load.
-      try { var c = nodeTls.getCACertificates(t); if (Array.isArray(c)) out = out.concat(c); } catch (_e) { /* unsupported type */ }
+      try { var c = nodeTls.getCACertificates(t); if (Array.isArray(c)) out = out.concat(c); } catch (_e) { }
     });
   }
   _systemCaCache = out;
   return out;
 }
 
-// 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).
 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.
     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
-      (a === 169 && b === 254) ||                                           // 169.254/16 link-local (cloud metadata)
-      (a === 172 && b >= 16 && b <= 31) ||                                  // 172.16/12
-      (a === 192 && b === 168) ||                                           // 192.168/16
-      (a === 192 && b === 0 && (c === 0 || c === 2)) ||                      // 192.0.0/24 IETF protocol + 192.0.2/24 TEST-NET-1
-      (a === 192 && b === 88 && c === 99) ||                                 // 192.88.99/24 6to4 relay anycast (deprecated)
-      (a === 198 && (b === 18 || b === 19)) ||                              // 198.18/15 benchmarking
-      (a === 198 && b === 51 && c === 100) ||                               // 198.51.100/24 TEST-NET-2
-      (a === 203 && b === 0 && c === 113);                                   // 203.0.113/24 TEST-NET-3
+    return a === 0 || a === 10 || a === 127 || a >= 224 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 192 && b === 0 && (c === 0 || c === 2)) ||
+      (a === 192 && b === 88 && c === 99) ||
+      (a === 198 && (b === 18 || b === 19)) ||
+      (a === 198 && b === 51 && c === 100) ||
+      (a === 203 && b === 0 && c === 113);
   }
   if (fam === 6) {
     var l = ip.toLowerCase();
-    if (l.indexOf("::ffff:") === 0) return true;                            // IPv4-mapped -- may embed a private v4; block all (fail-closed)
+    if (l.indexOf("::ffff:") === 0) return true;
     var parts = l.split(":");
-    var h = parseInt(parts[0], 16);                                         // first hextet ("" for a leading "::" -> NaN -> not in 2000::/3 -> blocked)
-    if (!(h >= 0x2000 && h <= 0x3fff)) return true;                         // outside global unicast 2000::/3: loopback/ULA/link-local/site-local/multicast(ff00::/8)/unspecified/unallocated
-    // Within 2000::/3, carve out the non-globally-routable special-purpose sub-ranges (IANA IPv6 Special-Purpose
-    // Address Registry) an attacker could route to an internal service: a first-hextet allow of the whole block
-    // would admit them. The second hextet is 0 when "::" compresses it (parts[1] empty).
+    var h = parseInt(parts[0], 16);
+    if (!(h >= 0x2000 && h <= 0x3fff)) return true;
     var h2 = parts[1] ? parseInt(parts[1], 16) : 0;
-    if (h === 0x2002) return true;                                          // 2002::/16 6to4 (embeds an IPv4 that may be private)
-    if (h === 0x2001 && h2 < 0x0200) return true;                           // 2001::/23 IETF protocol assignments (Teredo / benchmarking / ORCHID / AMT / ...)
-    if (h === 0x2001 && h2 === 0x0db8) return true;                         // 2001:db8::/32 documentation (RFC 3849)
-    if (h === 0x3fff && h2 < 0x1000) return true;                           // 3fff::/20 documentation (RFC 9637)
+    if (h === 0x2002) return true;
+    if (h === 0x2001 && h2 < 0x0200) return true;
+    if (h === 0x2001 && h2 === 0x0db8) return true;
+    if (h === 0x3fff && h2 < 0x1000) return true;
     return false;
   }
   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, 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.
 function _makeGuardedLookup(lookupFn) {
   return function guardedLookup(hostname, options, callback) {
     lookupFn(hostname, options || {}, function (err, address, family) {
       if (err) return callback(err);
-      if (Array.isArray(address)) {   // options.all -> [{ address, family }, ...]; reject if ANY resolved address is blocked
+      if (Array.isArray(address)) {
         for (var i = 0; i < address.length; i++) if (_isBlockedIp(address[i].address)) return callback(_blockedAddrErr(hostname, address[i].address));
         return callback(null, address);
       }
@@ -198,12 +157,6 @@ function _makeGuardedLookup(lookupFn) {
 }
 var _guardedLookup = _makeGuardedLookup(nodeDns.lookup);
 
-// Classify a node request/TLS error into the transport's fail-closed verdict: a
-// blocked-address lookup rejection; a protocol-version mismatch is the TLS floor; a
-// certificate / identity / handshake failure is a server-authentication failure;
-// anything else is a generic transport error. Every arm threads the raw fault as
-// `.cause`, so the diagnostic survives.
-// SELF.?SIGNED : "self", an optional single non-line-terminator character, then "signed" (in a lowercased string).
 function _hasSelfSigned(l) {
   for (var i = 0; i + 4 <= l.length; i++) {
     if (l.charCodeAt(i) === 0x73 && l.charCodeAt(i + 1) === 0x65 && l.charCodeAt(i + 2) === 0x6c && l.charCodeAt(i + 3) === 0x66) {
@@ -214,7 +167,6 @@ function _hasSelfSigned(l) {
   }
   return false;
 }
-// \bWORD\b : `word` (lowercase) bounded on both sides by a non-word character ([a-z0-9_]) or a string edge.
 function _hasWordBounded(l, word) {
   var at = l.indexOf(word);
   while (at !== -1) {
@@ -231,10 +183,8 @@ function _classifyError(e, C) {
   if (e && e.pkiBlockedAddress) return C("blocked-address");
   var s = String((e && e.code) || "") + " " + String((e && e.message) || "");
   var l = s.toLowerCase();
-  // /PROTOCOL_VERSION|UNSUPPORTED_PROTOCOL|VERSION_TOO_LOW|WRONG_VERSION|NO_PROTOCOLS_AVAILABLE|INAPPROPRIATE_FALLBACK/i
   if (l.indexOf("protocol_version") !== -1 || l.indexOf("unsupported_protocol") !== -1 || l.indexOf("version_too_low") !== -1 ||
       l.indexOf("wrong_version") !== -1 || l.indexOf("no_protocols_available") !== -1 || l.indexOf("inappropriate_fallback") !== -1) return C("tls-floor");
-  // /CERT|SELF.?SIGNED|VERIFY|ALTNAME|HOSTNAME|DEPTH_ZERO|LOCAL_ISSUER|HANDSHAKE|\bSSL\b|\bTLS\b/i
   if (l.indexOf("cert") !== -1 || l.indexOf("verify") !== -1 || l.indexOf("altname") !== -1 || l.indexOf("hostname") !== -1 ||
       l.indexOf("depth_zero") !== -1 || l.indexOf("local_issuer") !== -1 || l.indexOf("handshake") !== -1 ||
       _hasSelfSigned(l) || _hasWordBounded(l, "ssl") || _hasWordBounded(l, "tls")) return C("server-auth-failed");
@@ -285,9 +235,6 @@ function httpsTransport(defaults) {
   function C(name) { return prefix + "/" + name; }
   var tlsDefaults = defaults.tls || {};
 
-  // Synchronous config validation + node-options build. Throws the typed verdict on any
-  // fault (a non-https URL, no trust anchor, a bad budget, a sub-floor minVersion) so the
-  // async executor below never has to `return reject(...)`. rejectUnauthorized is forced on.
   function _prepare(request) {
     var url;
     try { url = new URL(String(request.url)); }
@@ -296,9 +243,6 @@ function httpsTransport(defaults) {
 
     var reqTls = request.tls || {};
     var anchors = reqTls.anchors !== undefined ? reqTls.anchors : tlsDefaults.anchors;
-    // System-store trust requires a STRICT boolean true; a non-boolean (a "false" / "true" string from
-    // JSON/env, a truthy object) is treated as absent, so a malformed config fails closed rather than
-    // silently trusting node's bundled roots.
     var useSystem = (reqTls.useSystemStore !== undefined ? reqTls.useSystemStore : tlsDefaults.useSystemStore) === true;
     var hasAnchors = anchors !== undefined && anchors !== null && !(Array.isArray(anchors) && anchors.length === 0);
     if (!hasAnchors && !useSystem) throw E(C("no-trust-anchors"), "no explicit trust anchor and useSystemStore not set -- refusing an unpinned server (RFC 7030 sec. 3.6)");
@@ -312,21 +256,12 @@ function httpsTransport(defaults) {
     var body = request.body;
     if (guard.bytes.isByteSource(body)) body = guard.bytes.source(body, E, C("bad-input"), "the request body");
 
-    // Frame a body-bearing request with a fixed Content-Length computed from the EXACT body, so it is sent
-    // length-delimited rather than Transfer-Encoding: chunked (node's default when a body is written with no
-    // Content-Length -- which strict enrollment / CMP appliances reject). A caller-supplied content-length
-    // (any case) is dropped: the transport owns request framing and never trusts a possibly-mismatched value.
     var reqHeaders = Object.assign({}, request.headers || {});
     if (body != null && body !== "") {
-      // Drop BOTH caller-supplied framing headers before installing the fixed length: node rejects a request
-      // carrying Content-Length AND Transfer-Encoding together (HPE_INVALID_CONTENT_LENGTH), and the transport
-      // owns framing -- it never honors a caller's chunked directive or a mismatched length.
       Object.keys(reqHeaders).forEach(function (k) { var lk = k.toLowerCase(); if (lk === "content-length" || lk === "transfer-encoding") delete reqHeaders[k]; });
       reqHeaders["Content-Length"] = Buffer.byteLength(body);
     }
 
-    // URL.hostname keeps the square brackets on an IPv6 literal ([2001:db8::1]); node's `hostname`
-    // option and its IP-detection expect the bare address, so strip the brackets once here.
     var host = _stripIpv6Brackets(url.hostname);
     var options = {
       method: request.method || "GET",
@@ -335,42 +270,21 @@ function httpsTransport(defaults) {
       path: url.pathname + url.search,
       headers: reqHeaders,
       minVersion: minVersion,
-      rejectUnauthorized: true,   // ALWAYS on -- there is no code path that disables server verification
-      // Opt out of connection pooling: node's keep-alive agent keys the socket pool on host + TLS
-      // options but NOT on checkServerIdentity, so a reused socket would skip a per-request identity /
-      // pinning callback. A fresh connection per request guarantees the identity check always runs.
+      rejectUnauthorized: true,
       agent: false,
     };
-    // Every TLS field falls back to the factory defaults (as anchors / minVersion already do), so a
-    // reusable transport built with pki.transport.https({ tls: { cert, key, servername } }) applies
-    // them to a request that carries no per-request tls (mTLS enrollment, a configured SNI).
     var cert = reqTls.cert !== undefined ? reqTls.cert : tlsDefaults.cert;
     var key = reqTls.key !== undefined ? reqTls.key : tlsDefaults.key;
     var callerCsi = typeof reqTls.checkServerIdentity === "function" ? reqTls.checkServerIdentity
       : (typeof tlsDefaults.checkServerIdentity === "function" ? tlsDefaults.checkServerIdentity : null);
-    // SNI (and RFC 6125 identity) uses a hostname; node forbids a servername that is an IP
-    // literal, so it is omitted for an IP host (node then matches the IP against the cert's
-    // IP SANs). A caller connecting by hostname gets SNI + name verification by default.
-    // The per-request servername falls back to the factory default only when it is ABSENT
-    // (as cert/key do); an explicit value, INCLUDING null, overrides the default, so a caller
-    // that sets servername to null on a cross-origin hop suppresses a configured default SNI
-    // rather than falsy-coalescing back to it.
     var sni = (reqTls.servername !== undefined ? reqTls.servername : tlsDefaults.servername) || host;
     if (sni && !nodeNet.isIP(sni)) options.servername = sni;
-    // Build node's `ca`: the explicit anchors (DER wrapped as PEM) and, when useSystemStore is opted
-    // in, the OS system store + bundled roots. Node's `ca` REPLACES the default set, so both sources
-    // are merged here. Left unset only when no anchors and (on an older node) the system store is
-    // empty -- then node's default bundled store applies (the documented fallback).
     var caList = [];
     if (hasAnchors) caList = caList.concat(_pemifyAnchors(anchors));
     if (useSystem) caList = caList.concat(_systemCa());
     if (caList.length) options.ca = caList;
     if (cert) options.cert = cert;
     if (key) options.key = key;
-    // A caller checkServerIdentity may only TIGHTEN, never REPLACE, name verification: node uses a
-    // supplied callback in place of its default RFC 6125 check, so a hook that returns undefined
-    // (pinning/metrics only) would silently disable hostname verification. Run node's default first
-    // and reject on its verdict; the caller's hook adds checks only after the default has passed.
     if (callerCsi) {
       options.checkServerIdentity = function (host, cert2) {
         var baseErr = nodeTls.checkServerIdentity(host, cert2);
@@ -378,15 +292,8 @@ function httpsTransport(defaults) {
         return callerCsi(host, cert2);
       };
     }
-    // SSRF at resolution time: when a request opts in (the AIA fetch of an untrusted-cert URL), install a
-    // lookup that refuses -- and pins -- a private / loopback / link-local resolved address, so a hostname
-    // pointing at an internal service is blocked even though the literal-address check saw only a DNS name.
-    // A STRICT boolean true (a truthy string/object is treated as absent) keeps a malformed config fail-open-free.
     var blockPrivate = (request.blockPrivateAddresses !== undefined ? request.blockPrivateAddresses : defaults.blockPrivateAddresses) === true;
     if (blockPrivate) {
-      // Node does NOT invoke a custom `lookup` for an IP-LITERAL host (there is nothing to resolve), so the
-      // resolver alone would let a literal private / loopback / link-local destination through. Reject a blocked
-      // literal here, before installing the resolver -- so the option blocks a literal AND a resolved hostname.
       if (_isBlockedIp(host)) throw E(C("blocked-address"), "refusing to connect to the private / loopback / link-local address literal " + host);
       options.lookup = _guardedLookup;
     }
@@ -409,29 +316,17 @@ function httpsTransport(defaults) {
         settled = true;
         clearTimer();
         // allow:swallow-unverified req.destroy() is idempotent and does not throw in practice; a
-        // raw throw from this best-effort abort would mask the real fail-closed verdict below.
-        try { if (req) req.destroy(); } catch (_e) { /* best-effort abort */ }
+        try { if (req) req.destroy(); } catch (_e) { }
         reject(E(code, msg, cause));
       }
-      // An independent wall-clock deadline bounds DNS resolution and connection setup as well as
-      // socket inactivity: node's request/socket timeout does not run during a DNS lookup, so a
-      // stalled resolver would otherwise leave this promise pending forever despite a finite timeout.
       timer = setTimeout(function () { fail(C("timeout"), "the request timed out after " + prep.timeout + "ms"); }, prep.timeout);
       try {
         req = nodeHttps.request(prep.options, function (res) {
-          // Capture the TLS session facts while the socket is live -- getProtocol() / getCipher() /
-          // getPeerCertificate() return null once the socket detaches at stream end. The negotiated cipher lets a
-          // caller refuse a NULL / anonymous / EXPORT suite before it trusts confidentiality (RFC 7030 sec. 4.4).
           var proto = res.socket && res.socket.getProtocol ? res.socket.getProtocol() : null;
           var cipher = res.socket && res.socket.getCipher ? res.socket.getCipher() : null;
           var peer = res.socket && res.socket.getPeerCertificate ? res.socket.getPeerCertificate() : null;
-          // Pre-check a declared content-length so an oversized body is refused before it streams.
           var declared = parseInt((res.headers || {})["content-length"], 10);
           if (Number.isFinite(declared) && declared > prep.maxBytes) { fail(C("response-too-large"), "the declared content-length " + declared + " exceeds the " + prep.maxBytes + "-byte cap (RFC 7030 sec. 6)"); return; }
-          // Accumulate into a single doubling buffer rather than an array of chunks: a body sent as
-          // many tiny chunks (one-byte TLS records) would otherwise retain millions of Buffer objects
-          // under the byte cap and exhaust the heap. One live buffer bounds the metadata as well as the
-          // bytes; only the written prefix [0, len) is ever surfaced (the unwritten tail is never read).
           var buf = Buffer.allocUnsafe(0);
           var len = 0;
           var total = 0;
@@ -463,16 +358,11 @@ function httpsTransport(defaults) {
           res.on("error", function (e) { fail(C("transport-error"), "the response stream failed", e); });
         });
         req.on("error", function (e) { fail(_classifyError(e, C), "the request failed: " + ((e && e.message) || String(e)), e); });
-        // Write a provided body for ANY method (POST / PUT / PATCH / ...), not only POST, so a body
-        // is never silently dropped on a body-bearing request through this generic transport seam.
         if (prep.body != null && prep.body !== "") req.write(prep.body);
         req.end();
       } catch (e) { fail(C("transport-error"), "the request could not be initiated: " + ((e && e.message) || String(e)), e); }
     });
   };
-  // Advertise that this transport HONORS the blockPrivateAddresses request flag (it filters and pins a resolved
-  // address). A consumer of an UNTRUSTED URL (pki.path.build's AIA fetch) checks this marker before relying on the
-  // flag for SSRF protection -- an injected transport that does not set it is treated as unguarded (fail-closed).
   _transportFn.blocksPrivateAddresses = true;
   return _transportFn;
 }