@blamejs/pki 0.8.30 → 0.8.48

package/lib/http-transport.js

@@ -72,6 +72,15 @@ var nodeDns = require("node:dns");
 var nodeUtil = require("node:util");
 var constants = require("./constants");
 var guard = require("./guard-all");
+var intrinsic = require("./guard-intrinsic");
+/** @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
+ *  step rejected proceed, and `peerChain`'s refusal to tunnel through a proxy is one of those. Taken at
+ *  load. */
+var _Promise = intrinsic.Promise;
+var _promiseResolve = intrinsic.uncurry(intrinsic.promiseResolve);
+var _promiseReject = intrinsic.uncurry(intrinsic.promiseReject);
 var frameworkError = require("./framework-error");
 
 var TransportError = frameworkError.TransportError;
@@ -124,6 +133,30 @@ function _tlsInfo(socket) {
   return { protocol: proto, cipher: cipher, peerCertificate: peer && peer.raw ? peer.raw : null, tlsUnique: tlsUnique, tlsExporter: tlsExporter };
 }
 
+/** @internal The chain the TLS session resolved, leaf first, walked through the detailed peer
+ * certificate's `issuerCertificate` links. The walk is bounded twice over: the top certificate
+ * issues itself, so the identity comparison ends it, and a cap ends any cycle a runtime could
+ * report instead.
+ * IT IS NOT THE SAME AS WHAT THE ENDPOINT TRANSMITTED, which this comment used to claim. Node
+ * completes `issuerCertificate` from the trust store in scope, so an endpoint that sends its leaf
+ * alone still yields a chain whose upper entries came from the configured anchors rather than off
+ * the wire. Node exposes no API for the transmitted list, so the distinction cannot be recovered
+ * here and is stated instead of guessed at: filtering the entries that match an anchor would drop
+ * a root an endpoint really did send. */
+function _peerChain(socket) {
+  if (!socket || typeof socket.getPeerCertificate !== "function") return [];
+  var out = [];
+  var seen = [];
+  var cur = socket.getPeerCertificate(true);
+  while (cur && Buffer.isBuffer(cur.raw) && out.length < constants.LIMITS.TLS_MAX_PEER_CHAIN) {
+    if (seen.indexOf(cur) !== -1) break;
+    seen.push(cur);
+    out.push(cur.raw);
+    cur = cur.issuerCertificate;
+  }
+  return out;
+}
+
 function _pemifyAnchor(a) {
   if (typeof a === "string") return a;
   if (Buffer.isBuffer(a)) {
@@ -557,8 +590,8 @@ function httpsTransport(defaults) {
     request = request || {};
     var prep;
     try { prep = _prepare(request); }
-    catch (e) { return Promise.reject(e); }
-    return new Promise(function (resolve, reject) {
+    catch (e) { return _promiseReject(_Promise, e); }
+    return new _Promise(function (resolve, reject) {
       var settled = false;
       var req = null;
       var creq = null;
@@ -625,7 +658,7 @@ function httpsTransport(defaults) {
               function _writeBoundBody() {
                 if (settled) return;
                 var info = _tlsInfo(socket);
-                Promise.resolve().then(function () { return prep.body(info); }).then(function (b) {
+                _promiseResolve(_Promise, undefined).then(function () { return prep.body(info); }).then(function (b) {
                   if (settled) return;
                   try {
                     if (guard.bytes.isByteSource(b)) b = guard.bytes.source(b, E, C("bad-input"), "the channel-binding body");
@@ -745,7 +778,126 @@ function httpsTransport(defaults) {
     });
   };
   _transportFn.blocksPrivateAddresses = true;
+
+  /** @internal peerChain negotiates TLS and hands back the channel without sending a request. It
+   * prepares the connection through the SAME `_prepare` the request path uses, so the anchors, the
+   * SNI, the version floor, the identity hook, the private-address block and the URL scheme gate are
+   * one policy with two entry points rather than two policies. `tls.connect` takes `host` where
+   * `https.request` takes `hostname`, and ignores the method, path and headers `_prepare` also
+   * builds. A proxy is refused rather than bypassed: tunnelling belongs to the request path, and
+   * connecting directly while a proxy is configured would reach an origin the caller asked not to
+   * reach directly. */
+  _transportFn.peerChain = function peerChain(request) {
+    request = request || {};
+    var prep;
+    try { prep = _prepare({
+      url: request.url,
+      method: "GET",
+      tls: request.tls,
+      timeout: request.timeout,
+      blockPrivateAddresses: request.blockPrivateAddresses,
+      allowPlaintextHttp: false,
+      proxy: request.proxy,
+    }); }
+    catch (e) { return _promiseReject(_Promise, e); }
+    if (prep.proxy) {
+      return _promiseReject(_Promise, E(C("bad-proxy"),
+        "peerChain opens a direct connection and does not tunnel; fetch through a proxy with the request verb"));
+    }
+    var o = prep.options;
+    var connectOpts = {
+      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;
+
+    return new _Promise(function (resolve, reject) {
+      var settled = false;
+      var socket;
+      var timer = null;
+      function done(fn, arg) {
+        if (settled) return;
+        settled = true;
+        if (timer !== null) { clearTimeout(timer); timer = null; }
+        try { if (socket) socket.destroy(); } catch (_de) { /* allow:swallow-unverified the socket is being abandoned either way */ }
+        fn(arg);
+      }
+      try { socket = nodeTls.connect(connectOpts); }
+      catch (e) {
+        reject(E(_classifyError(e, C), "the TLS connection failed: " + e.message, e));
+        return;
+      }
+      /** @internal The budget is an ABSOLUTE deadline, the same timer the request path above uses, and not
+       *  `socket.setTimeout`: that one bounds INACTIVITY, so what it measures is the gap between bytes
+       *  rather than the elapsed time a caller asked to be bounded by. A peer that keeps the socket busy
+       *  without completing the handshake is the case the two differ on. The socket inactivity timeout is
+       *  kept as well, since it ends a connection that goes silent sooner than the deadline would. */
+      timer = setTimeout(function () {
+        done(reject, E(C("timeout"), "the TLS handshake did not complete within " + prep.timeout + "ms"));
+      }, prep.timeout);
+      socket.setTimeout(prep.timeout, function () {
+        done(reject, E(C("timeout"), "the TLS handshake did not complete within " + prep.timeout + "ms"));
+      });
+      socket.once("secureConnect", function () {
+        var info = _tlsInfo(socket);
+        info.peerChain = _peerChain(socket);
+        done(resolve, info);
+      });
+      socket.once("error", function (e) {
+        var code = _classifyError(e, C);
+        done(reject, E(code || C("tls-failed"), "the TLS connection failed: " + e.message, e));
+      });
+    });
+  };
+
   return _transportFn;
 }
 
-module.exports = { https: httpsTransport, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT, snapshotProxy: snapshotProxy };
+/**
+ * @primitive  pki.transport.peerChain
+ * @signature  pki.transport.peerChain(request, defaults?) -> Promise<channel>
+ * @since      0.8.32
+ * @status     stable
+ * @spec       RFC 8446, RFC 6125
+ * @defends    server-impersonation (CWE-297), tls-downgrade (CWE-757), ssrf (CWE-918)
+ * @related    pki.transport.https, pki.path.validate
+ *
+ * Negotiate TLS with an endpoint and return the channel it established, without sending a
+ * request: `{ protocol, cipher, peerCertificate, peerChain, tlsUnique, tlsExporter }`.
+ * `peerChain` is the chain the session resolved as DER, leaf first, walked up from the peer
+ * certificate and stopping at the one that issues itself. It is not a record of what crossed the
+ * wire: the runtime completes the chain from the trust anchors in scope, so an endpoint that sends
+ * only its leaf still yields the entries above it, and those came from the configured anchors.
+ * Treat the list as the chain this session built, and read `peerCertificate` for the one
+ * certificate the endpoint certainly sent. Nothing reaches the application behind the endpoint,
+ * which is the difference from making a request for the same purpose.
+ *
+ * The connection is prepared by the same code `pki.transport.https` prepares a request with,
+ * so the trust anchors, the SNI, the version floor, the `checkServerIdentity` hook, the
+ * private-address block and the https-only rule are one policy rather than a second copy of
+ * 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`)
+ * rather than bypassed, since connecting directly would reach an origin the caller asked to
+ * reach through the proxy.
+ *
+ * **A chain this returns is not a validated one.** The handshake checked that it builds to a
+ * configured anchor and matches the name in the URL, and checked no revocation status and no
+ * policy. `pki.path.validate` is what validates a path.
+ *
+ * @example
+ *   var channel = await pki.transport.peerChain(
+ *     { url: "https://example.com/" }, { tls: { useSystemStore: true } });
+ *   channel.peerChain.length;                                  // the chain the session resolved
+ *   pki.schema.x509.parse(channel.peerChain[0]).subject.dn;    // the leaf's subject
+ *   channel.peerCertificate;                                   // the one certificate the endpoint sent
+ */
+function peerChain(request, defaults) { return httpsTransport(defaults || {}).peerChain(request); }
+
+module.exports = { https: httpsTransport, peerChain: peerChain, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT, snapshotProxy: snapshotProxy };

package/lib/identity-match.js

@@ -446,8 +446,8 @@ function _search(refs, entries, wildcardsAllowed) {
       pairs.tick();
       var got = _compare(refs[r], entries[e], wildcardsAllowed);
       if (got.disposition === "match") {
-        return { matched: true, matchedReference: refs[r].input, matchedEntry: _entryLabel(entries[e]),
-          ignored: ignored, reason: null };
+        return guard.verdict.of({ matched: true, matchedReference: refs[r].input, matchedEntry: _entryLabel(entries[e]),
+          ignored: ignored, reason: null });
       }
       if (got.disposition === "ignored") {
         var key = e + "|" + got.reason;
@@ -458,10 +458,10 @@ function _search(refs, entries, wildcardsAllowed) {
       }
     }
   }
-  return { matched: false, matchedReference: null, matchedEntry: null, ignored: ignored,
+  return guard.verdict.of({ matched: false, matchedReference: null, matchedEntry: null, ignored: ignored,
     reason: entries.length === 0
       ? "the certificate presents no subjectAltName entry, and RFC 9525 sec. 2 forbids reading an identity from the subject"
-      : "no presented identifier matched a reference identity" };
+      : "no presented identifier matched a reference identity" });
 }
 
 /**