@blamejs/pki 0.9.5 → 0.9.7

package/lib/http-transport.js

@@ -51,8 +51,9 @@
  *   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
- *   code path that disables server-certificate verification. The response body is
+ *   opt-in to the platform certificate store. `rejectUnauthorized` is always on: there is no
+ *   code path that disables server-certificate verification. `tls.distrustedKeys` refuses a
+ *   server whose verified chain carries a listed key. 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
  *   client MAY parameterize the transport with its own `(code, message, cause)` error
@@ -87,6 +88,17 @@ var nodeUtil = require("node:util");
 var constants = require("./constants");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
+/** @internal The certificate reader, and the two operations the distrust walk proves a link with,
+ *  taken at load. A replaced `verify` would answer whether each link of a server chain is signed by
+ *  the certificate above it. */
+var _X509Certificate = require("node:crypto").X509Certificate;
+var _x509Verify = intrinsic.uncurry(_X509Certificate.prototype.verify);
+var _x509PublicKey = intrinsic.uncurry(intrinsic.getOwnPropertyDescriptor(_X509Certificate.prototype, "publicKey").get);
+var _x509Ca = intrinsic.uncurry(intrinsic.getOwnPropertyDescriptor(_X509Certificate.prototype, "ca").get);
+var _x509CheckIssued = intrinsic.uncurry(_X509Certificate.prototype.checkIssued);
+var _x509ValidFrom = intrinsic.uncurry(intrinsic.getOwnPropertyDescriptor(_X509Certificate.prototype, "validFromDate").get);
+var _x509ValidTo = intrinsic.uncurry(intrinsic.getOwnPropertyDescriptor(_X509Certificate.prototype, "validToDate").get);
+var _Date = intrinsic.Date;
 /** @internal `resolve` and `reject` build their promise from the RECEIVER, so reading the global
  *  binding at the call hands the construction to whatever that binding holds. A refusal returned as a
  *  rejected promise is a verdict: a replacement whose `reject` resolves lets a request the preparation
@@ -245,10 +257,16 @@ function _peerChain(socket) {
   return out;
 }
 
+/** @internal Whether an anchor buffer is PEM text rather than DER. A DER certificate is a SEQUENCE,
+ *  so its first byte is 0x30; a buffer that starts with anything else is PEM text, which may carry a
+ *  comment ahead of its armor. */
+function _isPemBuffer(a) {
+  return _looksLikePemArmor(_bufToString(a, "latin1", 0, 64)) || (a.length > 0 && a[0] !== 0x30);
+}
 function _pemifyAnchor(a) {
   if (typeof a === "string") return a;
   if (_isBuffer(a)) {
-    if (_looksLikePemArmor(_bufToString(a, "latin1", 0, 64))) return a;
+    if (_isPemBuffer(a)) return a;
     var b64 = _wrap64Lines(_bufToString(a, "base64"));
     return "-----BEGIN CERTIFICATE-----\n" + b64 + "-----END CERTIFICATE-----\n";
   }
@@ -264,20 +282,292 @@ function _pemifyAnchors(anchors) {
  *  trust a `useSystemStore` connection is accepted under. */
 var _getCACertificates = typeof nodeTls.getCACertificates === "function" ? nodeTls.getCACertificates : null;
 
+/** @internal The platform store alone: the certificates the operating system trusts. Node's
+ *  compiled-in Mozilla set is a separate store that changes only when Node is upgraded, so a root a
+ *  distribution has removed would stay trusted if it were added here. A store that cannot be read
+ *  answers an empty list, and the request paths refuse an empty list rather than leave `ca` unset,
+ *  which would hand the connection Node's default store instead. */
 var _systemCaCache = null;
 function _systemCa() {
   if (_systemCaCache !== null) return _systemCaCache;
   var out = [];
   if (_getCACertificates !== null) {
-    _arrForEach(["system", "bundled"], function (t) {
-      // allow:swallow-unverified a store TYPE unsupported on this node is skipped; the other type
-      try { var c = intrinsic.apply(_getCACertificates, nodeTls, [t]); if (_isArray(c)) out = _concatList(out, c); } catch (_e) { }
-    });
+    // allow:swallow-unverified an unreadable platform store answers empty, and an empty list is refused by every caller
+    try { var c = intrinsic.apply(_getCACertificates, nodeTls, ["system"]); if (_isArray(c)) out = _concatList(out, c); } catch (_e) { }
+  }
+  _systemCaCache = _withoutCompromised(out);
+  return _systemCaCache;
+}
+
+/** @internal `pems` without the entries holding a certificate whose key is compromised
+ *  (`guard.distrust.compromised`), so the TLS layer cannot verify a session through one. An entry
+ *  this reader cannot decode is kept: `_anchorKeySet` reports no certificate for it. */
+function _withoutCompromised(pems) {
+  var out = [];
+  for (var i = 0; i < pems.length; i++) {
+    var entries = _anchorKeySet([pems[i]]).entries;
+    var listed = false;
+    for (var j = 0; j < entries.length && !listed; j++) listed = guard.distrust.compromised(entries[j].spki) !== null;
+    if (!listed) _arrPush(out, pems[i]);
   }
-  _systemCaCache = out;
   return out;
 }
 
+/** @internal Throws `E(code, ...)` when a caller's anchor carries a compromised key. `pems` is the
+ *  list `_pemifyAnchors` returns, and an entry may hold several certificates. */
+function _refuseCompromisedAnchors(pems, E, code, label) {
+  var keys = _anchorKeySet(pems).entries;
+  for (var i = 0; i < keys.length; i++) {
+    var why = guard.distrust.compromised(keys[i].spki);
+    if (why !== null) throw E(code, label + " holds a certificate with a compromised key: " + why);
+  }
+}
+
+/** @internal The first compromised key on node's walk of the peer chain, as `{ digest, compromised }`;
+ *  `{ unchecked: reason }` when the walk is longer than `LIMITS.PATH_MAX_CERTS` certificates, so part
+ *  of it would go unread; or null. The walk is read as node builds it and no link is proven: the check
+ *  refuses on a hit and does not refuse a walk whose links it cannot prove. This runs
+ *  inside node's `checkServerIdentity` call, which node makes without a `try`, so nothing here may
+ *  throw. */
+function _compromisedOnWalk(cert) {
+  var cur = cert;
+  for (var n = 0; cur && _isBuffer(cur.raw); n++) {
+    if (n >= constants.LIMITS.PATH_MAX_CERTS) {
+      return { unchecked: "the chain is longer than the " + constants.LIMITS.PATH_MAX_CERTS + " certificates the check reads" };
+    }
+    var spki;
+    try { spki = _peerSpki(cur.raw); }
+    catch (_e) {
+      // allow:swallow-unverified a certificate whose key neither reader returns is not a hit here; a non-empty tls.distrustedKeys refuses it as unproven
+      spki = null;
+    }
+    var why = spki === null ? null : guard.distrust.compromised(spki);
+    if (why !== null) return { digest: guard.distrust.digest(spki), compromised: why };
+    if (cur.issuerCertificate === cur) return null;
+    cur = cur.issuerCertificate;
+  }
+  return null;
+}
+
+/** @internal The DER SubjectPublicKeyInfo of a certificate the TLS layer verified. The toolkit's
+ *  parser is reached through an inline require because of a circular load (schema-x509 ->
+ *  schema-pkix -> ct -> this module). A certificate the strict parser refuses was still accepted by
+ *  the TLS stack, so its key is taken from node's own reading rather than left unchecked. */
+function _peerSpki(raw) {
+  var x509 = require("./schema-x509");   // allow:inline-require -- circular load: schema-x509 -> schema-pkix -> ct -> this module
+  try { return x509.parse(raw).subjectPublicKeyInfo.bytes; }
+  catch (_e) {
+    // allow:swallow-unverified the parser's refusal is answered from node's reading of the same certificate
+    return guard.crypto.exportKey(_x509PublicKey(new _X509Certificate(raw)), { type: "spki", format: "der" });
+  }
+}
+
+/** @internal Whether `child` carries a signature that verifies under `parent`'s key. A certificate
+ *  node cannot read, or whose signature algorithm it cannot verify, answers false. */
+function _signedBy(child, parent) {
+  try { return _x509Verify(new _X509Certificate(child), _x509PublicKey(new _X509Certificate(parent))) === true; }
+  catch (_e) {
+    // allow:swallow-unverified a link node cannot verify is reported as unproven, and the caller refuses it
+    return false;
+  }
+}
+
+/** @internal Whether `raw` is inside its validity window now and, for a certificate that issues
+ *  another on the walk, is a CA certificate. A certificate node cannot read answers false. */
+function _usableLink(raw, mustBeCa, now) {
+  try {
+    var c = new _X509Certificate(raw);
+    if (mustBeCa && _x509Ca(c) !== true) return false;
+    return guard.time.instantOf(_x509ValidFrom(c)) <= now && now <= guard.time.instantOf(_x509ValidTo(c));
+  } catch (_e) {
+    // allow:swallow-unverified a certificate node cannot read is reported as unproven, and the caller refuses it
+    return false;
+  }
+}
+
+/** @internal The trust anchors a connection is opened under, as `{ keys, entries }`: `keys` is a set
+ *  keyed by `guard.distrust.keyDigest`, and `entries` holds each anchor certificate node reads, with
+ *  its key, for the branches through the trust store `_storeBranchListed` follows. `caList` holds PEM
+ *  text, which may carry several certificates, and DER buffers. The codec is reached through an
+ *  inline require for the circular load named at `_peerSpki`. */
+function _anchorKeySet(caList) {
+  var pkix = require("./schema-pkix");   // allow:inline-require -- circular load: schema-pkix -> ct -> this module
+  var set = _objectCreate(null);
+  var entries = [];
+  for (var i = 0; i < caList.length; i++) {
+    var a = caList[i];
+    var ders = [];
+    if (_isBuffer(a) && !_isPemBuffer(a)) ders = [a];
+    else {
+      var rows;
+      try { rows = pkix.pemDecodeBundle(typeof a === "string" ? a : _bufToString(a, "latin1"), {}, Error); }
+      catch (_e) {
+        // allow:swallow-unverified an anchor this reader cannot decode adds no key, so a chain ending there is refused
+        rows = [];
+      }
+      for (var r = 0; r < rows.length; r++) if (rows[r].label === "CERTIFICATE") _arrPush(ders, rows[r].der);
+    }
+    for (var d = 0; d < ders.length; d++) {
+      try {
+        var spki = _peerSpki(ders[d]);
+        set[guard.distrust.keyDigest(spki)] = true;
+        _arrPush(entries, { x509: new _X509Certificate(ders[d]), spki: spki });
+      } catch (_e2) {
+        // allow:swallow-unverified an anchor whose key cannot be read adds no key, so a chain ending there is refused
+        void 0;
+      }
+    }
+  }
+  return { keys: set, entries: entries };
+}
+var _systemAnchorKeys = null;
+function _systemAnchorKeySet() {
+  if (_systemAnchorKeys === null) _systemAnchorKeys = _anchorKeySet(_systemCa());
+  return _systemAnchorKeys;
+}
+/** @internal The anchors for one hop: the caller's, and the platform store's when the hop uses it.
+ *  Computed only when the hop has a distrust list to apply. */
+function _hopAnchorKeys(distrust, anchorPems, useSystem) {
+  if (distrust === null || distrust.length === 0) return null;
+  var own = _anchorKeySet(anchorPems);
+  if (!useSystem) return own;
+  var sys = _systemAnchorKeySet();
+  var names = _objectKeys(sys.keys);
+  for (var i = 0; i < names.length; i++) own.keys[names[i]] = true;
+  return { keys: own.keys, entries: _concatList(own.entries, sys.entries) };
+}
+
+/** @internal The digest of a listed key on a branch through the trust store above `childX509`, or
+ *  null. OpenSSL looks in the trust store for an issuer before it looks at what the server sent, so
+ *  when the store holds a certificate that issues one on node's walk (an intermediate, or a
+ *  cross-certificate), the session may have been verified up that branch instead. Every such branch
+ *  is followed upward through the store, and a listed key anywhere on one refuses the session.
+ *  `visited` bounds the search to one visit per anchor certificate. */
+function _storeBranchListed(childX509, anchors, list, visited) {
+  for (var i = 0; i < anchors.entries.length; i++) {
+    var e = anchors.entries[i];
+    if (_arrIndexOf(visited, e) !== -1) continue;
+    var issues;
+    try { issues = _x509CheckIssued(childX509, e.x509) === true && _x509Verify(childX509, _x509PublicKey(e.x509)) === true; }
+    catch (_e) {
+      // allow:swallow-unverified a store certificate node cannot compare is not an issuer on any branch
+      issues = false;
+    }
+    if (!issues) continue;
+    _arrPush(visited, e);
+    if (guard.distrust.has(list, e.spki)) return e.spki;
+    var above = _storeBranchListed(e.x509, anchors, list, visited);
+    if (above !== null) return above;
+  }
+  return null;
+}
+
+/** @internal The first distrusted key on the chain the session verified, as `{ digest }`; null
+ *  when none is listed; or `{ unproven: reason }` when the walk cannot stand for the verified chain.
+ *
+ *  The walk follows the detailed peer certificate's `issuerCertificate` links, which node builds by
+ *  name and key identifier from the certificates the server sent and then from the trust store,
+ *  without checking a signature, a validity period or whether the top is trusted. OpenSSL may have
+ *  verified the session through different certificates with the same names, so the walk is held to
+ *  what makes it a path in its own right: each link is signed by the certificate above it, each
+ *  certificate below the top is inside its validity window, each one that issues another is a CA,
+ *  and the top is self-issued with the key of a configured trust anchor (`anchors.keys`). OpenSSL
+ *  looks in the trust store for an issuer first, so where the store holds a certificate that issues
+ *  one on the walk, the session may have been verified up the store's branch rather than the walk;
+ *  every such branch is followed (`_storeBranchListed`) and a listed key on one refuses the session.
+ *  Node gives no way to read the chain OpenSSL verified, so the check covers every chain the session
+ *  could have been verified through, and may refuse a session whose verified chain was clean. The
+ *  walk reads up to `LIMITS.PATH_MAX_CERTS` certificates. */
+function _distrustedInChain(cert, list, anchors) {
+  var now = guard.time.instantOf(new _Date());
+  var seen = [];
+  var visitedStore = [];
+  var cur = cert;
+  for (;;) {
+    if (seen.length >= constants.LIMITS.PATH_MAX_CERTS) {
+      return { unproven: "the chain is longer than the " + constants.LIMITS.PATH_MAX_CERTS + " certificates the check reads" };
+    }
+    var spki;
+    try { spki = _peerSpki(cur.raw); }
+    catch (_pe) {
+      // allow:swallow-unverified a certificate whose key neither reader returns cannot be checked, so the walk is unproven
+      return { unproven: "the key of a certificate on the chain could not be read" };
+    }
+    if (guard.distrust.has(list, spki)) return _keyHit(spki);
+    var storeHit;
+    try { storeHit = _storeBranchListed(new _X509Certificate(cur.raw), anchors, list, visitedStore); }
+    catch (_se) {
+      // allow:swallow-unverified a certificate node cannot read leaves the store branches unchecked, so the walk is unproven
+      return { unproven: "a certificate on the chain could not be compared with the trust store" };
+    }
+    if (storeHit !== null) return _keyHit(storeHit);
+    var up = cur.issuerCertificate;
+    if (up === cur) {
+      return anchors.keys[guard.distrust.keyDigest(spki)] === true ? null
+        : { unproven: "the chain ends at a self-issued certificate whose key is not a configured trust anchor's" };
+    }
+    if (!_usableLink(cur.raw, seen.length > 0, now)) {
+      return { unproven: "a certificate on the chain is outside its validity period or issues without being a CA" };
+    }
+    _arrPush(seen, cur);
+    if (_arrIndexOf(seen, up) !== -1) return { unproven: "the chain loops back on a certificate it already passed" };
+    if (!up || !_isBuffer(up.raw) || !_signedBy(cur.raw, up.raw)) {
+      return { unproven: "a link of the chain is not signed by the certificate node places above it" };
+    }
+    cur = up;
+  }
+}
+
+/** @internal A refused key as `{ digest, compromised }`, where `compromised` is the reason
+ *  `guard.distrust.compromised` gives, or null for a key refused only by the caller's list. */
+function _keyHit(spki) {
+  return { digest: guard.distrust.digest(spki), compromised: guard.distrust.compromised(spki) };
+}
+
+function _distrustError(hit, hop) {
+  var e;
+  if (hit.compromised || hit.unchecked) {
+    e = new Error(hit.compromised
+      ? "the " + hop + " certificate chain carries a compromised key (SubjectPublicKeyInfo SHA-256 " + hit.digest + "): " + hit.compromised
+      : "the " + hop + " certificate chain could not be checked for a compromised key: " + hit.unchecked);
+    return guard.verdict.set(e, "pkiCompromisedKey", hop);
+  }
+  e = new Error(hit.digest !== undefined
+    ? "the " + hop + " certificate chain carries a key listed in tls.distrustedKeys (SubjectPublicKeyInfo SHA-256 " + hit.digest + ")"
+    : "the " + hop + " certificate chain could not be checked against tls.distrustedKeys: " + hit.unproven);
+  return guard.verdict.set(e, "pkiDistrustedKey", hop);
+}
+
+/** @internal An identity check that also refuses a chain carrying a compromised or distrusted key.
+ *  With no list, the chain node walks is checked for a compromised key (`_compromisedOnWalk`); with a
+ *  list, the walk is held to the proof `_distrustedInChain` describes, and a key on the list or a
+ *  compromised key anywhere on it refuses the session. The chain is read before the identity check
+ *  runs, because a caller's hook receives the same certificate object and can change it. The identity
+ *  verdict is returned first, so a name mismatch is still reported as one. Node calls this without a
+ *  `try`, so a hook that throws is returned as the refusal, and the refusal is built before the hook
+ *  runs. Anything else in the body that throws, such as a read a changed prototype answers, returns a
+ *  refusal built from string concatenation alone. */
+function _withDistrust(check, list, hop, anchorKeys) {
+  var strict = list !== null && list.length > 0;
+  return function (host, cert) {
+    try {
+      var hit = strict ? _distrustedInChain(cert, list, anchorKeys) : _compromisedOnWalk(cert);
+      var refusal = hit === null ? undefined : _distrustError(hit, hop);
+      var err;
+      try { err = check(host, cert); }
+      catch (e) {
+        var thrown = new Error("the " + hop + " identity check (tls.checkServerIdentity) threw: " + guard.text.describeThrown(e));
+        return guard.verdict.set(thrown, "cause", e);
+      }
+      if (err) return err;
+      return refusal;
+    } catch (_e) {
+      // allow:swallow-unverified the throw is returned as a refusal of the session, which is the verdict a failed check has to give
+      return new Error("the " + hop + " certificate chain could not be checked");
+    }
+  };
+}
+
 function _isBlockedIp(ip) {
   /** @internal The argument has to BE a string, and what cannot be classified is blocked. `isIP`
    * converts its argument, so a value whose conversion answers a loopback literal to the family
@@ -334,8 +624,7 @@ function _isBlockedIp(ip) {
 
 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;
+  return guard.verdict.set(e, "pkiBlockedAddress", true);
 }
 function _makeGuardedLookup(lookupFn) {
   return function guardedLookup(hostname, options, callback) {
@@ -389,6 +678,10 @@ function _hasWordBounded(l, word) {
 function _isLowerWordChar(c) { return (c >= 97 && c <= 122) || (c >= 48 && c <= 57) || c === 95; }
 function _classifyError(e, C) {
   if (e && e.pkiBlockedAddress) return C("blocked-address");
+  if (e && e.pkiCompromisedKey === "proxy") return C("proxy-key-compromised");
+  if (e && e.pkiCompromisedKey === "server") return C("server-key-compromised");
+  if (e && e.pkiDistrustedKey === "proxy") return C("proxy-key-distrusted");
+  if (e && e.pkiDistrustedKey === "server") return C("server-key-distrusted");
   var s = _stringOf((e && e.code) || "") + " " + _stringOf((e && e.message) || "");
   var l = _toLowerCase(s);
   if (_strIndexOf(l, "protocol_version") !== -1 || _strIndexOf(l, "unsupported_protocol") !== -1 || _strIndexOf(l, "version_too_low") !== -1 ||
@@ -403,7 +696,11 @@ function _keySet(names) { var m = _objectCreate(null); for (var i = 0; i < names
 var PROXY_KEYS = _keySet(["url", "auth", "tls"]);
 var PROXY_AUTH_KEYS = _keySet(["scheme", "username", "password", "allowMD5", "allowLegacyQop"]);
 var PROXY_DIGEST_KNOBS = ["allowMD5", "allowLegacyQop"];
-var PROXY_TLS_KEYS = _keySet(["anchors", "useSystemStore", "servername", "minVersion"]);
+var PROXY_TLS_KEYS = _keySet(["anchors", "useSystemStore", "servername", "minVersion", "distrustedKeys"]);
+/** @internal The names a `tls` policy bag may carry. A name outside them is refused rather than
+ *  ignored: a misspelled `distrustedKeys` or `anchors` would otherwise leave the connection under a
+ *  policy the caller did not state. */
+var TLS_KEYS = _keySet(["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity", "distrustedKeys"]);
 
 function _copyAnchor(a) { return (a !== null && typeof a === "object" && nodeUtil.types.isProxy(a)) ? a : (_isBuffer(a) ? _bufferFrom(a) : a); }
 function _noopProxyErr(code, message) { var e = new Error(message); e.code = code; e.isPkiError = true; return e; }
@@ -461,6 +758,12 @@ function snapshotProxy(p) {
         out.tls.anchors = copied;
       } else if (typeof a === "string") out.tls.anchors = a;
       else if (a !== null && typeof a === "object" && !nodeUtil.types.isProxy(a) && _isBuffer(a)) out.tls.anchors = _bufferFrom(a);
+      /** @internal The distrust list is copied for the reason the anchors are: the snapshot is taken
+       *  so a caller's later edit cannot change the policy, and a shared array would carry the edit. */
+      var dk = p.tls.distrustedKeys;
+      if (dk !== undefined && dk !== null) {
+        out.tls.distrustedKeys = guard.distrust.keys(dk, _noopProxyErr, "transport/bad-proxy", "opts.proxy.tls.distrustedKeys");
+      }
     }
     return out;
   } catch (_e) {
@@ -472,7 +775,7 @@ function snapshotProxy(p) {
 /** @internal `originHost`, `statedPort` and `scheme` are the values the request path already read off
  *  the parsed origin; they are passed in rather than read again here, so the authority this builds for
  *  the CONNECT target is the same authority the socket options were built from. */
-function _validateProxy(request, defaults, E, C, originHost, originStatedPort, originScheme) {
+function _validateProxy(request, defaults, E, C, originHost, originStatedPort, originScheme, originDistrust) {
   var rawProxy = request.proxy;
   var proxy = rawProxy !== undefined ? rawProxy : defaults.proxy;
   if (proxy === undefined || proxy === null) return null;
@@ -542,9 +845,23 @@ function _validateProxy(request, defaults, E, C, originHost, originStatedPort, o
      * consult `Symbol.isConcatSpreadable` on each argument, so capturing the method leaves the
      * SPREADING replaceable and an inherited hook replaced a validated anchor with another one in
      * the CONNECT options. `concatList` copies own indexes and appends own indexes. */
-    if (pHasAnchors) pCa = _concatList(pCa, _pemifyAnchors(pAnchors));
+    if (pHasAnchors) {
+      var pPems = _pemifyAnchors(pAnchors);
+      _refuseCompromisedAnchors(pPems, E, C("bad-proxy"), "opts.proxy.tls.anchors");
+      pCa = _concatList(pCa, pPems);
+    }
     if (pUseSystem) pCa = _concatList(pCa, _systemCa());
-    proxyTls = { ca: pCa.length ? pCa : undefined, minVersion: pMinVersion, servername: pServername };
+    if (pCa.length === 0) {
+      throw E(C("no-trust-anchors"), "proxy.tls.useSystemStore is set and the platform certificate store returned no certificates, " +
+        "so the proxy cannot be authenticated; set proxy.tls.anchors");
+    }
+    /** @internal A key the caller distrusts is refused on this hop too, whether it was listed for
+     * the proxy or for the origin. */
+    var pDistrust = guard.distrust.union(
+      guard.distrust.keys(ptls ? ptls.distrustedKeys : undefined, E, C("bad-proxy"), "opts.proxy.tls.distrustedKeys"),
+      originDistrust);
+    proxyTls = { ca: pCa, minVersion: pMinVersion, servername: pServername, distrust: pDistrust,
+      anchorKeys: _hopAnchorKeys(pDistrust, pHasAnchors ? _pemifyAnchors(pAnchors) : [], pUseSystem) };
   }
 
   var originAuthHost = _isIP(originHost) === 6 ? "[" + originHost + "]" : originHost;
@@ -587,6 +904,8 @@ function _digestProxyCredential(headers, pinfo, C, E) {
   }, E);
 }
 function _proxyErrorClass(e, C) {
+  if (e && e.pkiCompromisedKey === "proxy") return C("proxy-key-compromised");
+  if (e && e.pkiDistrustedKey === "proxy") return C("proxy-key-distrusted");
   var code = _stringOf((e && e.code) || "");
   if (_strIndexOf(code, "ERR_TLS") === 0 || _strIndexOf(code, "ERR_SSL") === 0 || _strIndexOf(code, "SSL") !== -1 ||
       _strIndexOf(code, "CERT") !== -1 || _strIndexOf(code, "SELF_SIGNED") !== -1 || _strIndexOf(code, "VERIFY") !== -1 ||
@@ -605,28 +924,47 @@ function _proxyErrorClass(e, C) {
  *
  * Build a fail-closed `node:https` transport: `transport(request) -> Promise<{ status,
  * headers, body }>`. `defaults` binds a `tls` policy (`anchors` -> the node `ca`;
- * `useSystemStore` to opt into the bundled roots; `cert`/`key` for mutual TLS;
+ * `useSystemStore` to opt into the platform certificate store; `distrustedKeys` to refuse
+ * listed keys; `cert`/`key` for mutual TLS;
  * `minVersion` 'TLSv1.2' (default) or 'TLSv1.3'; `servername`; a `checkServerIdentity`
  * that may only tighten) plus `timeout` and `maxResponseBytes` budgets. Each `request`
- * ({ method, url, headers, body, tls, timeout, maxResponseBytes }) may override them.
+ * ({ method, url, headers, body, tls, timeout, maxResponseBytes }) may override them,
+ * except `distrustedKeys`: the request's list is added to the default's.
  * A non-https URL (`transport/insecure-url`), a request with neither an explicit
- * anchor nor `useSystemStore` (`transport/no-trust-anchors`), a body over the streaming
+ * anchor nor `useSystemStore`, or with `useSystemStore` and an empty platform store
+ * (`transport/no-trust-anchors`), a body over the streaming
  * cap (`transport/response-too-large`), a stalled socket (`transport/timeout`), a below
- * -floor negotiation (`transport/tls-floor`), or a failed server authentication
- * (`transport/server-auth-failed`) all fail closed; `rejectUnauthorized` is always on.
+ * -floor negotiation (`transport/tls-floor`), a failed server authentication
+ * (`transport/server-auth-failed`), a chain carrying a key whose private key is public
+ * (`transport/server-key-compromised`), or a verified chain carrying a distrusted key
+ * (`transport/server-key-distrusted`) all fail closed; `rejectUnauthorized` is always on.
+ * The compromised-key check runs on every connection and hop with no option to turn it off: a
+ * certificate on the chain node reports whose key is on `pki.trust.knownCompromisedKeys()`, or is an
+ * elliptic curve key whose private key is an integer below 256, refuses the server
+ * (`transport/proxy-key-compromised` for a proxy). That chain is the one node builds from the
+ * certificates the server sent and the trust store, and a link of it is not proven; set
+ * `tls.distrustedKeys` for the proven walk described below, which applies the same compromised keys.
+ * A chain longer than `C.LIMITS.PATH_MAX_CERTS` is refused with the same code, and the chain is read
+ * before a `tls.checkServerIdentity` hook runs. A hook that throws refuses the server with
+ * `transport/server-auth-failed`.
+ * A `tls.anchors` or `proxy.tls.anchors` certificate whose key is compromised is refused with
+ * `transport/bad-input` or `transport/bad-proxy` before any connection, and under `useSystemStore`
+ * such a certificate in the platform store is left out of the certificates the connection trusts.
  * A protocol client passes its own error factory (`defaults.E`) + `defaults.errPrefix`
  * to surface domain codes (`est/...`). The transport owns no HTTP/redirect/auth
  * semantics; those live in the message layer that consumes the response triple.
  *
  * @opts
  *   - `tls.anchors` -- Explicit trust anchor(s): a DER/PEM Buffer, an array, or PEM string(s) (node `ca`).
- *   - `tls.useSystemStore` -- boolean; the one opt-in to node's bundled CA store (default false).
+ *   - `tls.useSystemStore` -- boolean; the one opt-in to the platform certificate store, `tls.getCACertificates("system")` (default false). Node's compiled-in roots are not included; pass them as `tls.anchors` to use them. An empty platform store is refused with `transport/no-trust-anchors` unless `tls.anchors` is also set.
+ *   - `tls.distrustedKeys` -- SHA-256 digests of SubjectPublicKeyInfo values (64 hex characters or 32 bytes each, see `pki.trust.spkiDigest`). A server whose verified chain carries a listed key, at any position including the root, is refused with `transport/server-key-distrusted`. The chain node reports is checked as a path of its own: each link is signed by the certificate above it, each certificate below the top is inside its validity period and each one that issues another is a CA, and the top is self-issued with the key of a configured anchor. Where a configured anchor certificate (an intermediate or a cross-certificate, as a platform store can hold) issues a certificate on that chain, the branch up through the anchors is checked too, since OpenSSL may have verified the session that way. A chain that fails any of these, or is longer than `C.LIMITS.PATH_MAX_CERTS`, is refused with the same code while a list is set, so a session can be refused when the chain OpenSSL verified was clean but another chain it could have used is not. A request's list is added to the transport default's, which is read when the transport is built.
+ *   - A `tls` bag naming anything other than the options above is refused with `transport/bad-input`, the transport default's when the transport is built and a request's before a socket opens.
  *   - `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.
  *   - `timeout` -- ms (default C.TIME.seconds(30)); `maxResponseBytes` -- default LIMITS.HTTP_MAX_RESPONSE_BYTES, tightenable downward only.
  *   - `blockPrivateAddresses` -- boolean; when true, an IP-literal host OR a hostname resolving to a private / loopback / link-local address is refused (`transport/blocked-address`), and a resolved address is pinned for the connection. For fetching an untrusted-certificate URL (AIA caIssuers); default false. It cannot be combined with `proxy`: a forward proxy resolves the origin itself, so the transport cannot enforce the block on it, and the combination is refused (`transport/bad-proxy`).
- *   - `proxy` -- reach the https origin through a forward HTTP proxy: `{ url: "http://proxy:3128" | "https://proxy:3128", auth?: { scheme: "basic" | "digest", username, password, allowMD5?, allowLegacyQop? }, tls?: { anchors, useSystemStore, servername, minVersion } }`. A CONNECT tunnel is opened to the proxy and the origin's TLS is negotiated inside it under the identical origin trust policy, so the proxy cannot read the origin's encrypted session or substitute the origin certificate. `auth` requires an `https://` proxy: the credentials ride the authenticated TLS-to-proxy channel (verified against `proxy.tls`, which is required for an https proxy), so a plaintext `http://` proxy carrying `auth` is refused (`transport/proxy-auth-requires-tls`) rather than exposing them to the proxy hop. An `http://` proxy is tunnel-only. Basic (RFC 7617) sends its credential on the first CONNECT. Digest (RFC 7616) answers the proxy's `Proxy-Authenticate` challenge on a `407`, hashing the method `CONNECT` over the authority-form target, and answers exactly once: a proxy that repeats its challenge has rejected the credential. The Digest policy is the one the origin verbs use, so MD5 and a challenge carrying no `qop` are refused unless `allowMD5` / `allowLegacyQop` says otherwise (`transport/proxy-digest-weak-algorithm`, `transport/proxy-digest-unsupported-algorithm`, `transport/proxy-digest-no-qop`, `transport/proxy-digest-bad-challenge`). A `407` is `transport/proxy-auth-failed` (credentials rejected) or `transport/proxy-auth-required` (none supplied, or none of the offered schemes is the configured one); a proxy certificate that does not verify is `transport/proxy-tls-failed`; a non-2xx CONNECT is `transport/proxy-connect-failed`; a malformed option is `transport/bad-proxy`. Off by default (a direct connection).
+ *   - `proxy` -- reach the https origin through a forward HTTP proxy: `{ url: "http://proxy:3128" | "https://proxy:3128", auth?: { scheme: "basic" | "digest", username, password, allowMD5?, allowLegacyQop? }, tls?: { anchors, useSystemStore, servername, minVersion, distrustedKeys } }`. A CONNECT tunnel is opened to the proxy and the origin's TLS is negotiated inside it under the identical origin trust policy, so the proxy cannot read the origin's encrypted session or substitute the origin certificate. `auth` requires an `https://` proxy: the credentials ride the authenticated TLS-to-proxy channel (verified against `proxy.tls`, which is required for an https proxy), so a plaintext `http://` proxy carrying `auth` is refused (`transport/proxy-auth-requires-tls`) rather than exposing them to the proxy hop. An `http://` proxy is tunnel-only. Basic (RFC 7617) sends its credential on the first CONNECT. Digest (RFC 7616) answers the proxy's `Proxy-Authenticate` challenge on a `407`, hashing the method `CONNECT` over the authority-form target, and answers exactly once: a proxy that repeats its challenge has rejected the credential. The Digest policy is the one the origin verbs use, so MD5 and a challenge carrying no `qop` are refused unless `allowMD5` / `allowLegacyQop` says otherwise (`transport/proxy-digest-weak-algorithm`, `transport/proxy-digest-unsupported-algorithm`, `transport/proxy-digest-no-qop`, `transport/proxy-digest-bad-challenge`). A `407` is `transport/proxy-auth-failed` (credentials rejected) or `transport/proxy-auth-required` (none supplied, or none of the offered schemes is the configured one); a proxy certificate that does not verify is `transport/proxy-tls-failed`; a proxy chain carrying a key listed in `proxy.tls.distrustedKeys` or the origin's `tls.distrustedKeys` is `transport/proxy-key-distrusted`; a non-2xx CONNECT is `transport/proxy-connect-failed`; a malformed option is `transport/bad-proxy`. Off by default (a direct connection).
  * @example
  *   var t = pki.transport.https({ tls: { anchors: [caPem] } });
  *   var res = await t({ method: "GET", url: "https://ca.example/.well-known/est/cacerts" });
@@ -645,6 +983,12 @@ function httpsTransport(defaults) {
    *  the settings read from this record is the opt-in that turns away an unpinned server. */
   var rawDefaultTls = defaults.tls;
   var tlsDefaults = rawDefaultTls != null ? rawDefaultTls : intrinsic.create(null);
+  if (rawDefaultTls != null) {
+    guard.identifier.assertKnownKeys(tlsDefaults, TLS_KEYS, E, C("bad-input"), "the transport default tls has an unknown option ");
+  }
+  /** @internal The default distrust list is read and copied once, here, so editing the caller's
+   *  array after the transport is built changes nothing. */
+  var defaultDistrust = guard.distrust.keys(tlsDefaults.distrustedKeys, E, C("bad-input"), "the transport default tls.distrustedKeys");
 
   function _prepare(request) {
     var url;
@@ -674,6 +1018,7 @@ function httpsTransport(defaults) {
      *  public verb instead of this module's typed refusal. */
     var rawReqTls = request.tls;
     var reqTls = rawReqTls != null ? rawReqTls : intrinsic.create(null);
+    if (rawReqTls != null) guard.identifier.assertKnownKeys(reqTls, TLS_KEYS, E, C("bad-input"), "tls has an unknown option ");
     var rawAnchors = reqTls.anchors;
     var anchors = rawAnchors !== undefined ? rawAnchors : tlsDefaults.anchors;
     var rawUseSystem = reqTls.useSystemStore;
@@ -686,6 +1031,20 @@ function httpsTransport(defaults) {
     if (scheme === "https:" && !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)");
     }
+    /** @internal The platform store is read here so an empty one is refused before any socket
+     * opens. A connection given an empty `ca` list falls back to Node's default store, which is
+     * Node's compiled-in set plus NODE_EXTRA_CA_CERTS, and that is not the store the caller asked
+     * for. */
+    var systemCa = useSystem ? _systemCa() : [];
+    if (scheme === "https:" && !hasAnchors && systemCa.length === 0) {
+      throw E(C("no-trust-anchors"), "useSystemStore is set and the platform certificate store returned no certificates, " +
+        "so the server cannot be authenticated; set tls.anchors, or install the host's CA bundle");
+    }
+    /** @internal The transport's list and the request's are combined, so a request cannot drop a
+     * key the transport was built to refuse by naming a shorter list. */
+    var rawDistrust = reqTls.distrustedKeys;
+    var distrust = guard.distrust.union(defaultDistrust,
+      guard.distrust.keys(rawDistrust, E, C("bad-input"), "tls.distrustedKeys"));
 
     var rawTimeout = request.timeout;
     var timeout = _budget(rawTimeout !== undefined ? rawTimeout : defaults.timeout, "timeout", DEFAULT_TIMEOUT, MAX_TIMEOUT, E, C("bad-input"));
@@ -711,10 +1070,14 @@ function httpsTransport(defaults) {
     var host = _stripIpv6Brackets(_urlHostname(url));
     var plaintext = scheme === "http:";
     var statedPort = _urlPort(url);
+    /** @internal `defaultPort` is what node compares the port with when it writes the Host header.
+     * With no agent there is no default to compare with, so node appends the port every time and a
+     * URL with no port is sent as `Host: name:80`. Some servers answer that with an error. */
     var options = {
       method: request.method || "GET",
       hostname: host,
       port: statedPort || (plaintext ? 80 : 443),
+      defaultPort: plaintext ? 80 : 443,
       path: _urlPathname(url) + _urlSearch(url),
       headers: reqHeaders,
       minVersion: minVersion,
@@ -746,17 +1109,22 @@ function httpsTransport(defaults) {
     if (typeof sni !== "string") throw E(C("bad-input"), "tls.servername must be a string, got " + guard.text.showValue(sni));
     if (sni && !_isIP(sni)) options.servername = sni;
     var caList = [];
-    if (hasAnchors) caList = _concatList(caList, _pemifyAnchors(anchors));
-    if (useSystem) caList = _concatList(caList, _systemCa());
+    if (hasAnchors) {
+      var anchorPems = _pemifyAnchors(anchors);
+      _refuseCompromisedAnchors(anchorPems, E, C("bad-input"), "tls.anchors");
+      caList = _concatList(caList, anchorPems);
+    }
+    if (useSystem) caList = _concatList(caList, systemCa);
     if (caList.length) options.ca = caList;
     if (cert) options.cert = cert;
     if (key) options.key = key;
+    var anchorKeys = _hopAnchorKeys(distrust, hasAnchors ? _pemifyAnchors(anchors) : [], useSystem);
     if (callerCsi) {
-      options.checkServerIdentity = function (host, cert2) {
+      options.checkServerIdentity = _withDistrust(function (host, cert2) {
         var baseErr = _checkServerIdentity(host, cert2);
         if (baseErr) return baseErr;
         return callerCsi(host, cert2);
-      };
+      }, distrust, "server", anchorKeys);
     } else {
       /** @internal With no caller hook, the option is set to the CAPTURE rather than left out. Left
        * out, node's own TLS stack looks the function up on its module export when the handshake
@@ -764,15 +1132,15 @@ function httpsTransport(defaults) {
        * another host is accepted. Measured: with this absent, a request asking for a name the
        * server's certificate does not carry was admitted. The function is node's own default, taken
        * at load, so the verdict is the one it would have reached anyway. */
-      options.checkServerIdentity = _checkServerIdentity;
+      options.checkServerIdentity = _withDistrust(_checkServerIdentity, distrust, "server", anchorKeys);
     }
     var proxyInfo;
-    try { proxyInfo = _validateProxy(request, defaults, E, C, host, statedPort, scheme); }
+    try { proxyInfo = _validateProxy(request, defaults, E, C, host, statedPort, scheme, distrust); }
     catch (e) {
       var typedProxyError = false;
       try {
         var ec = (e instanceof Error) && !nodeUtil.types.isProxy(e) ? e.code : undefined;
-        typedProxyError = ec === C("bad-proxy") || ec === C("proxy-auth-requires-tls");
+        typedProxyError = ec === C("bad-proxy") || ec === C("proxy-auth-requires-tls") || ec === C("no-trust-anchors");
       } catch (_ie) { /* allow:swallow-unverified reading .code on a hostile error object can throw; treat any such failure as untyped */ }
       if (typedProxyError) throw e;
       throw E(C("bad-proxy"), "opts.proxy could not be validated", e);
@@ -785,7 +1153,7 @@ function httpsTransport(defaults) {
       options.lookup = _guardedLookup;
     }
 
-    return { options: options, timeout: timeout, maxBytes: maxBytes, body: body, proxy: proxyInfo, blockPrivate: blockPrivate, callerCsi: callerCsi, plaintext: plaintext };
+    return { options: options, timeout: timeout, maxBytes: maxBytes, body: body, proxy: proxyInfo, blockPrivate: blockPrivate, callerCsi: callerCsi, plaintext: plaintext, distrust: distrust, anchorKeys: anchorKeys };
   }
 
   var _transportFn = function transport(request) {
@@ -833,7 +1201,7 @@ function httpsTransport(defaults) {
            * options are the ones node computed for this hop, forwarded unchanged, so every TLS
            * setting the request carries still applies; only the function that opens the socket is
            * this module's. The tunnel path already supplies its own and keeps it. */
-          if (options.createConnection === undefined) {
+          if (options.createConnection == null) {
             options.createConnection = prep.plaintext
               ? function (opts) { return intrinsic.apply(_netConnect, nodeNet, [opts]); }
               : function (opts) { return intrinsic.apply(_tlsConnect, nodeTls, [opts]); };
@@ -949,7 +1317,8 @@ function httpsTransport(defaults) {
             connectOpts.minVersion = pinfo.proxyTls.minVersion;
             var pIdentity = pinfo.proxyTls.servername || pinfo.host;
             connectOpts.servername = (pIdentity && !_isIP(pIdentity)) ? pIdentity : "";
-            connectOpts.checkServerIdentity = function (host, cert) { return _checkServerIdentity(pIdentity, cert); };
+            connectOpts.checkServerIdentity = _withDistrust(function (host, cert) { return _checkServerIdentity(pIdentity, cert); },
+              pinfo.proxyTls.distrust, "proxy", pinfo.proxyTls.anchorKeys);
             connectOpts.createConnection = function (opts) { return intrinsic.apply(_tlsConnect, nodeTls, [opts]); };
             cr = intrinsic.apply(_httpsRequest, nodeHttps, [connectOpts]);
           } else {
@@ -997,11 +1366,11 @@ function httpsTransport(defaults) {
                 ca: prep.options.ca,
                 minVersion: prep.options.minVersion,
                 rejectUnauthorized: true,
-                checkServerIdentity: function (host, cert) {
+                checkServerIdentity: _withDistrust(function (host, cert) {
                   var baseErr = _checkServerIdentity(idHost, cert);
                   if (baseErr) return baseErr;
                   return prep.callerCsi ? prep.callerCsi(idHost, cert) : undefined;
-                },
+                }, prep.distrust, "server", prep.anchorKeys),
                 cert: prep.options.cert,
                 key: prep.options.key,
               }]);
@@ -1060,12 +1429,12 @@ function httpsTransport(defaults) {
       host: o.hostname, port: o.port, minVersion: o.minVersion,
       rejectUnauthorized: o.rejectUnauthorized,
     };
-    if (o.servername !== undefined) connectOpts.servername = o.servername;
-    if (o.ca !== undefined) connectOpts.ca = o.ca;
-    if (o.cert !== undefined) connectOpts.cert = o.cert;
-    if (o.key !== undefined) connectOpts.key = o.key;
-    if (o.checkServerIdentity !== undefined) connectOpts.checkServerIdentity = o.checkServerIdentity;
-    if (o.lookup !== undefined) connectOpts.lookup = o.lookup;
+    if (o.servername != null) connectOpts.servername = o.servername;
+    if (o.ca != null) connectOpts.ca = o.ca;
+    if (o.cert != null) connectOpts.cert = o.cert;
+    if (o.key != null) connectOpts.key = o.key;
+    if (o.checkServerIdentity != null) connectOpts.checkServerIdentity = o.checkServerIdentity;
+    if (o.lookup != null) connectOpts.lookup = o.lookup;
 
     return new _Promise(function (resolve, reject) {
       var settled = false;
@@ -1134,7 +1503,8 @@ function httpsTransport(defaults) {
  * one. A request with neither an explicit anchor nor `useSystemStore` is refused
  * (`transport/no-trust-anchors`) before any socket is opened, and an endpoint whose chain does
  * not build to the configured anchors, or whose name does not match the URL, is refused
- * (`transport/server-auth-failed`). A configured proxy is refused (`transport/bad-proxy`)
+ * (`transport/server-auth-failed`). A chain carrying a key listed in `tls.distrustedKeys` is
+ * refused (`transport/server-key-distrusted`). A configured proxy is refused (`transport/bad-proxy`)
  * rather than bypassed, since connecting directly would reach an origin the caller asked to
  * reach through the proxy.
  *
@@ -1151,4 +1521,5 @@ function httpsTransport(defaults) {
  */
 function peerChain(request, defaults) { return httpsTransport(defaults || intrinsic.create(null)).peerChain(request); }
 
-module.exports = { https: httpsTransport, peerChain: peerChain, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT, snapshotProxy: snapshotProxy };
+module.exports = { https: httpsTransport, peerChain: peerChain, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT, snapshotProxy: snapshotProxy,
+  TLS_KEYS: intrinsic.freeze(TLS_KEYS) };