@blamejs/core 0.8.52 → 0.8.57

package/lib/network-tls.js

@@ -3,6 +3,7 @@
 var tls = require("node:tls");
 var fs = require("node:fs");
 var path = require("node:path");
+var net = require("node:net");
 var nodeCrypto = require("node:crypto");
 
 var blamejsCrypto = require("./crypto");
@@ -18,6 +19,7 @@ var NetworkTlsError = defineClass("NetworkTlsError", { alwaysPermanent: true });
 
 var observability = lazyRequire(function () { return require("./observability"); });
 var audit = lazyRequire(function () { return require("./audit"); });
+var networkDns = lazyRequire(function () { return require("./network-dns"); });
 var asn1 = require("./asn1-der");
 
 // STATE.tlsKeyShares is initialized to the default PQC group list at
@@ -2277,6 +2279,745 @@ var ct = Object.freeze({
   },
 });
 
+// ---- ECH (Encrypted Client Hello) — RFC 9460 SVCB ech= SvcParam +
+//      draft-ietf-tls-esni-22 §4 ECHConfigList -----------------------
+//
+// ECH is a TLS 1.3 extension that encrypts the Client Hello Inner
+// (SNI, ALPN, etc.) under a public key the server publishes via DNS
+// SVCB/HTTPS records. A passive observer sees only the public_name
+// SNI in the outer hello — the real virtual host stays confidential.
+//
+// Wire format reminder (uint16 lengths are big-endian throughout):
+//
+//   ECHConfigList = uint16 total_length || ECHConfig[]
+//   ECHConfig     = uint16 version || uint16 length || contents
+//   contents (v=0xfe0d) =
+//     HpkeKeyConfig key_config
+//     uint8         maximum_name_length
+//     opaque<1..255> public_name        (with uint8 length prefix)
+//     Extension     extensions<0..2^16-1>  (uint16 length prefix +
+//                                           list of (uint16 ext_type,
+//                                           opaque<0..2^16-1> ext_data))
+//   HpkeKeyConfig =
+//     uint8  config_id
+//     uint16 kem_id
+//     opaque public_key<1..2^16-1>      (uint16 length prefix)
+//     HpkeSymmetricCipherSuite cipher_suites<4..2^16-1>
+//                                       (uint16 length prefix; entries
+//                                        each (uint16 kdf_id, uint16
+//                                        aead_id) — 4 bytes apiece)
+
+var ECH_CONFIG_VERSION_DRAFT_22 = 0xfe0d;                                        // allow:raw-byte-literal — draft-ietf-tls-esni-22 ECH version codepoint
+
+function _echReadU8(buf, off) {
+  if (off + 1 > buf.length) {
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: truncated reading uint8 at offset " + off);
+  }
+  return buf[off];
+}
+function _echReadU16(buf, off) {
+  if (off + 2 > buf.length) {                                                    // allow:raw-byte-literal — uint16 width
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: truncated reading uint16 at offset " + off);
+  }
+  return buf.readUInt16BE(off);
+}
+function _echReadVarOpaqueU16(buf, off) {
+  var len = _echReadU16(buf, off);
+  off += 2;                                                                      // allow:raw-byte-literal — uint16 length-prefix width
+  if (off + len > buf.length) {
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: opaque vector overflows buffer (declared " + len +
+      " bytes at offset " + (off - 2) + ", " + (buf.length - off) + " available)");
+  }
+  return { value: buf.slice(off, off + len), nextOff: off + len };
+}
+function _echReadVarOpaqueU8(buf, off) {
+  var len = _echReadU8(buf, off);
+  off += 1;
+  if (off + len > buf.length) {
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: u8-prefixed opaque overflows buffer");
+  }
+  return { value: buf.slice(off, off + len), nextOff: off + len };
+}
+
+/**
+ * @primitive b.network.tls.parseEchConfigList
+ * @signature b.network.tls.parseEchConfigList(raw)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.tls.connectWithEch, b.network.dns.queryHttps
+ *
+ * Parse a draft-ietf-tls-esni-22 ECHConfigList byte string (the value
+ * of the `ech=` SvcParam in an SVCB or HTTPS DNS record per RFC 9460
+ * paragraph 7.4.2). Accepts a `Buffer` or a strict-base64 string. Returns
+ * `{ rawLength, configs: [{ version, length, keyConfig, ... }] }`.
+ *
+ * For each ECHConfig at the published draft-22 version (`0xfe0d`) the
+ * decoded `keyConfig` carries `configId`, `kemId`, `publicKey`
+ * (Buffer), and `cipherSuites` (each `{ kdfId, aeadId }`); the entry
+ * also exposes `maximumNameLength`, `publicName`, and `extensions`.
+ * Unknown future ECH versions surface their raw `body` Buffer so the
+ * caller can forward them to a Node build that supports them.
+ *
+ * Throws `NetworkTlsError("tls/ech-config-malformed")` on any framing
+ * violation (truncated length prefix, vector overflow, bad
+ * cipher_suites stride, etc.).
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rrs = await b.network.dns.queryHttps("example.com");
+ *   var rec = rrs.find(function (r) { return r.params && r.params.ech; });
+ *   var parsed = b.network.tls.parseEchConfigList(rec.params.ech);
+ *   // parsed.configs[0].keyConfig.kemId === 0x0020 (X25519)
+ */
+function parseEchConfigList(raw) {
+  if (typeof raw === "string") {
+    // Operators sometimes hold the SvcParam as a base64 string; accept
+    // both. Reject anything that doesn't round-trip cleanly through
+    // strict-base64 — Node's Buffer.from(b64, "base64") is lenient
+    // (silently ignores stray bytes), so we re-encode and compare.
+    var stripped = raw.replace(/\s+/g, "");
+    var decoded = Buffer.from(stripped, "base64");
+    if (decoded.length === 0 || decoded.toString("base64") !== stripped) {
+      throw new NetworkTlsError("tls/ech-config-malformed",
+        "parseEchConfigList: input string is not strict base64");
+    }
+    raw = decoded;
+  }
+  if (!Buffer.isBuffer(raw) || raw.length === 0) {
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "parseEchConfigList: input must be a non-empty Buffer or base64 string");
+  }
+  if (raw.length < 2) {                                                          // allow:raw-byte-literal — uint16 outer length prefix
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: too short for outer length prefix");
+  }
+  var totalLen = raw.readUInt16BE(0);
+  if (2 + totalLen !== raw.length) {                                             // allow:raw-byte-literal — uint16 prefix width
+    throw new NetworkTlsError("tls/ech-config-malformed",
+      "ECHConfigList: outer length " + totalLen + " does not match buffer " +
+      "tail length " + (raw.length - 2));
+  }
+  var off = 2;                                                                   // allow:raw-byte-literal — uint16 prefix width
+  var configs = [];
+  while (off < raw.length) {
+    if (off + 4 > raw.length) {                                                  // allow:raw-byte-literal — uint16 ver + uint16 len
+      throw new NetworkTlsError("tls/ech-config-malformed",
+        "ECHConfig: truncated header at offset " + off);
+    }
+    var version = raw.readUInt16BE(off);
+    var length  = raw.readUInt16BE(off + 2);
+    var bodyOff = off + 4;
+    var bodyEnd = bodyOff + length;
+    if (bodyEnd > raw.length) {
+      throw new NetworkTlsError("tls/ech-config-malformed",
+        "ECHConfig: declared length " + length + " overflows ECHConfigList");
+    }
+    var entry = { version: version, length: length };
+    if (version === ECH_CONFIG_VERSION_DRAFT_22) {
+      var p = bodyOff;
+      // HpkeKeyConfig
+      var configId = _echReadU8(raw, p); p += 1;
+      var kemId    = _echReadU16(raw, p); p += 2;                                // allow:raw-byte-literal — uint16 KEM id width
+      var pkOpaque = _echReadVarOpaqueU16(raw, p); p = pkOpaque.nextOff;
+      var suitesLen = _echReadU16(raw, p); p += 2;                               // allow:raw-byte-literal — uint16 length prefix width
+      if (p + suitesLen > bodyEnd) {
+        throw new NetworkTlsError("tls/ech-config-malformed",
+          "ECHConfig: cipher_suites vector overflows config body");
+      }
+      if (suitesLen % 4 !== 0 || suitesLen < 4) {                                // allow:raw-byte-literal — kdf+aead = 4 bytes per suite
+        throw new NetworkTlsError("tls/ech-config-malformed",
+          "ECHConfig: cipher_suites length must be a positive multiple of 4");
+      }
+      var suites = [];
+      for (var sp = p; sp < p + suitesLen; sp += 4) {                            // allow:raw-byte-literal — 4-byte cipher suite stride
+        suites.push({
+          kdfId:  raw.readUInt16BE(sp),
+          aeadId: raw.readUInt16BE(sp + 2),
+        });
+      }
+      p += suitesLen;
+      // remainder of contents
+      var maxNameLen = _echReadU8(raw, p); p += 1;
+      var publicName = _echReadVarOpaqueU8(raw, p); p = publicName.nextOff;
+      var extLen = _echReadU16(raw, p); p += 2;                                  // allow:raw-byte-literal — uint16 length prefix width
+      if (p + extLen !== bodyEnd) {
+        throw new NetworkTlsError("tls/ech-config-malformed",
+          "ECHConfig: extensions vector does not consume remaining body " +
+          "(extLen=" + extLen + ", remaining=" + (bodyEnd - p) + ")");
+      }
+      var extensions = [];
+      var extEnd = p + extLen;
+      while (p < extEnd) {
+        var extType = _echReadU16(raw, p); p += 2;                               // allow:raw-byte-literal — uint16 ext type
+        var extData = _echReadVarOpaqueU16(raw, p); p = extData.nextOff;
+        extensions.push({ type: extType, data: extData.value });
+      }
+      entry.keyConfig = {
+        configId:     configId,
+        kemId:        kemId,
+        publicKey:    pkOpaque.value,
+        cipherSuites: suites,
+      };
+      entry.maximumNameLength = maxNameLen;
+      entry.publicName        = publicName.value.toString("ascii");
+      entry.extensions        = extensions;
+    } else {
+      // Unknown future version — surface raw bytes so the caller can
+      // forward them to a Node build that does support that version.
+      entry.body = Buffer.from(raw.slice(bodyOff, bodyEnd));
+    }
+    configs.push(entry);
+    off = bodyEnd;
+  }
+  return { rawLength: raw.length, configs: configs };
+}
+
+// Feature-detect: probe whether tls.connect accepts the `ech` option.
+// Cached so repeated connect calls don't re-test on every connection.
+// Strategy: tls.connect throws synchronously on a port=0 socket attempt
+// when the option shape is rejected at the C++ layer with
+// ERR_INVALID_ARG_TYPE / ERR_TLS_INVALID_OPTION; if it makes it past
+// option-validation we destroy the half-built socket. We never actually
+// open a socket — the probe runs entirely in option-parsing.
+var _echFeatureProbe = null;
+function _isEchSupported() {
+  if (_echFeatureProbe !== null) return _echFeatureProbe;
+  // The cleanest probe is to read tls.connect.toString() — but Node
+  // hides option parsing in C++. Instead we attempt to construct the
+  // options object via tls.checkServerIdentity-adjacent surface: call
+  // tls.connect with a sentinel `ech: Buffer.alloc(0)` and an
+  // immediately-destroyed socket. Any non-throwing path = supported.
+  var supported = false;
+  try {
+    var probe = tls.connect({
+      host:    "127.0.0.1",
+      port:    1,
+      ech:     Buffer.alloc(0),
+      lookup:  function (_h, _o, cb) { cb(new Error("probe-abort")); },
+    });
+    supported = true;
+    try { probe.destroy(); } catch (_e) { /* probe socket */ }
+  } catch (e) {
+    var msg = (e && (e.code || e.message)) || "";
+    // ERR_INVALID_ARG_TYPE or ERR_TLS_* on `ech` = unsupported.
+    if (/ech/i.test(msg) || /unknown option/i.test(msg)) supported = false;
+    else supported = true;  // unrelated throw (e.g. lookup): option accepted
+  }
+  _echFeatureProbe = supported;
+  return supported;
+}
+
+/**
+ * @primitive b.network.tls.connectWithEch
+ * @signature b.network.tls.connectWithEch(opts)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.tls.parseEchConfigList, b.network.dns.queryHttps,
+ *            b.network.tls.checkServerIdentity9525
+ *
+ * Open a TLS-1.3 outbound connection with Encrypted Client Hello (ECH,
+ * draft-ietf-tls-esni-22) when the destination publishes an `ech=`
+ * SvcParam via SVCB/HTTPS records (RFC 9460 paragraph 2.4 / paragraph 9). The flow:
+ *
+ *   1. `b.network.dns.queryHttps(host)` to discover ECH config.
+ *   2. If any record carries `ech=`, the parsed ECHConfigList is
+ *      attached to `tls.connect({ ech })` so the outer ClientHello
+ *      uses the published `public_name` SNI and the inner ClientHello
+ *      (real SNI, ALPN, etc.) is HPKE-encrypted under the published
+ *      public key.
+ *   3. If no record carries `ech=`, or DNS fails, the function falls
+ *      back to a normal TLS connect (still TLSv1.3-floor + framework
+ *      PQC group preference). Operators get an `observability.event`
+ *      so the degradation is visible.
+ *   4. If the running Node build does not support the `ech` connect
+ *      option, the function emits a one-shot warn and connects
+ *      without ECH — never throws on missing Node-side support.
+ *
+ * Returns the connected `tls.TLSSocket` once `secureConnect` fires.
+ * `b.httpClient` will compose this in a follow-up release; this
+ * primitive is the operator escape hatch for raw outbound TLS over
+ * ECH (custom protocol clients, mTLS testing, ECH validation tools).
+ *
+ * @opts
+ *   {
+ *     host:        string,
+ *     port:        number,
+ *     alpn:        string[],
+ *     ipFamily:    4 | 6,
+ *     timeoutMs:   number,
+ *     servername:  string,
+ *     ca:          string|Buffer|Array,
+ *     checkServerIdentity: function,
+ *     echOverride: Buffer|string,
+ *     rejectUnauthorized: boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var sock = await b.network.tls.connectWithEch({
+ *     host: "ech-target.example.com",
+ *     alpn: ["h2", "http/1.1"],
+ *   });
+ *   sock.write("GET / HTTP/1.1\r\nHost: ech-target.example.com\r\n\r\n");
+ */
+function connectWithEch(opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Array.isArray(opts)) {
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: opts must be a plain object");
+  }
+  validateOpts(opts,
+    ["host", "port", "alpn", "ipFamily", "timeoutMs", "servername", "ca",
+     "checkServerIdentity", "echOverride", "rejectUnauthorized"],
+    "network.tls.connectWithEch");
+  validateOpts.requireNonEmptyString(opts.host, "connectWithEch: host",
+    NetworkTlsError, "tls/ech-bad-opts");
+  var port = opts.port === undefined ? 443 : opts.port;                          // allow:raw-byte-literal — HTTPS default port
+  if (typeof port !== "number" || !isFinite(port) ||
+      port <= 0 || port > 65535 || Math.floor(port) !== port) {                  // allow:raw-byte-literal — TCP port range
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: port must be an integer in 1..65535");
+  }
+  if (opts.alpn !== undefined && !Array.isArray(opts.alpn)) {
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: alpn must be an array of strings");
+  }
+  if (opts.ipFamily !== undefined && opts.ipFamily !== 4 && opts.ipFamily !== 6) {
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: ipFamily must be 4 | 6 | undefined");
+  }
+  var timeoutMs = opts.timeoutMs === undefined
+    ? C.TIME.seconds(30) : opts.timeoutMs;
+  if (typeof timeoutMs !== "number" || !isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: timeoutMs must be a non-negative finite number");
+  }
+  if (opts.echOverride !== undefined &&
+      !Buffer.isBuffer(opts.echOverride) &&
+      typeof opts.echOverride !== "string") {
+    throw new NetworkTlsError("tls/ech-bad-opts",
+      "connectWithEch: echOverride must be a Buffer or base64 string");
+  }
+
+  return new Promise(function (resolve, reject) {
+    function _doConnect(echConfigBuf, sourceLabel) {
+      var nodeSupportsEch = _isEchSupported();
+      var connectOpts = {
+        host:       opts.host,
+        port:       port,
+        servername: opts.servername || opts.host,
+        minVersion: "TLSv1.3",
+      };
+      if (Array.isArray(opts.alpn)) connectOpts.ALPNProtocols = opts.alpn.slice();
+      if (opts.ipFamily !== undefined) connectOpts.family = opts.ipFamily;
+      if (opts.ca !== undefined) connectOpts.ca = _normalizeCaInput(opts.ca);
+      if (typeof opts.checkServerIdentity === "function") {
+        connectOpts.checkServerIdentity = opts.checkServerIdentity;
+      }
+      if (opts.rejectUnauthorized === false) {
+        connectOpts.rejectUnauthorized = false;
+      }
+      var echAttached = false;
+      if (echConfigBuf && nodeSupportsEch) {
+        connectOpts.ech = echConfigBuf;
+        echAttached = true;
+      } else if (echConfigBuf && !nodeSupportsEch) {
+        // ECHConfig present but Node build can't honor it — degrade
+        // gracefully with a one-shot warn so operators know they're
+        // sending an outer-only ClientHello.
+        try {
+          observability().emit("network.tls.ech.unsupported", {
+            host: opts.host, source: sourceLabel,
+          });
+        } catch (_e) { /* drop-silent */ }
+        try {
+          audit().safeEmit({
+            action:  "network.tls.ech.unsupported",
+            outcome: "success",  // Node lacks `ech` opt — degraded to non-ECH
+            metadata: { host: opts.host, source: sourceLabel },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+
+      var sock;
+      try { sock = tls.connect(connectOpts); }
+      catch (e) {
+        reject(new NetworkTlsError("tls/ech-connect-failed",
+          "connectWithEch: tls.connect threw: " + ((e && e.message) || String(e))));
+        return;
+      }
+      var settled = false;
+      var to = null;
+      if (timeoutMs > 0) {
+        to = setTimeout(function () {
+          if (settled) return;
+          settled = true;
+          try { sock.destroy(); } catch (_e) { /* destroy best-effort */ }
+          reject(new NetworkTlsError("tls/ech-timeout",
+            "connectWithEch: handshake timed out after " + timeoutMs + "ms"));
+        }, timeoutMs);
+        if (typeof to.unref === "function") to.unref();
+      }
+      sock.once("secureConnect", function () {
+        if (settled) return;
+        settled = true;
+        if (to) clearTimeout(to);
+        try {
+          observability().emit("network.tls.ech.connected", {
+            host: opts.host, echAttached: echAttached, source: sourceLabel,
+          });
+        } catch (_e) { /* drop-silent */ }
+        resolve(sock);
+      });
+      sock.once("error", function (e) {
+        if (settled) return;
+        settled = true;
+        if (to) clearTimeout(to);
+        reject(e);
+      });
+    }
+
+    if (Buffer.isBuffer(opts.echOverride) || typeof opts.echOverride === "string") {
+      // Operator-provided ECHConfigList — skip the SVCB lookup, validate
+      // shape, then connect.
+      var override;
+      try {
+        var bufOverride = Buffer.isBuffer(opts.echOverride)
+          ? opts.echOverride
+          : Buffer.from(opts.echOverride, "base64");
+        parseEchConfigList(bufOverride);  // validate-only
+        override = bufOverride;
+      } catch (e) {
+        reject(e);
+        return;
+      }
+      _doConnect(override, "override");
+      return;
+    }
+
+    // Default: SVCB/HTTPS lookup. Per RFC 9460 §2.4 the prefix `_https.`
+    // is the SVCB owner-name for an HTTPS origin; modern Node honors a
+    // bare HTTPS QTYPE on the apex name though, which is what
+    // queryHttps does. We use queryHttps directly.
+    var dnsMod;
+    try { dnsMod = networkDns(); }
+    catch (e) {
+      reject(new NetworkTlsError("tls/ech-dns-unavailable",
+        "connectWithEch: network-dns module unavailable: " +
+        ((e && e.message) || String(e))));
+      return;
+    }
+    dnsMod.queryHttps(opts.host).then(function (records) {
+      var echBuf = null;
+      for (var i = 0; i < records.length; i += 1) {
+        var rec = records[i];
+        if (rec && rec.params && Buffer.isBuffer(rec.params.ech) &&
+            rec.params.ech.length > 0) {
+          echBuf = rec.params.ech;
+          break;
+        }
+      }
+      _doConnect(echBuf, echBuf ? "svcb" : "no-ech-record");
+    }).catch(function (e) {
+      // DNS failure is not fatal — fall back to non-ECH connect so the
+      // operator still gets a working TLS session. Emit obs so the
+      // operator sees the degradation.
+      try {
+        observability().emit("network.tls.ech.dns_failed", {
+          host: opts.host, error: (e && e.message) || String(e),
+        });
+      } catch (_e) { /* drop-silent */ }
+      _doConnect(null, "dns-failed");
+    });
+  });
+}
+
+// ---- RFC 9525 strict server identity verification ----------------
+//
+// RFC 9525 §6 — PKIX name validation:
+//   §6.1   The certificate's subjectAltName extension is the
+//          authoritative source of identifiers. CN-fallback is
+//          forbidden when SAN is present. RFC 9525 §6.4.4 explicitly
+//          deprecates CN matching outright; legacy CN-only certs
+//          (no SAN) are refused under strict mode.
+//   §6.4.3 Wildcard `*.example.com` matches `foo.example.com` (one
+//          left-most label) but NOT `foo.bar.example.com` (deeper
+//          subdomain) and NOT `example.com` (the wildcard owner
+//          itself). Wildcards in the middle (`foo.*.example.com`) or
+//          partial wildcards (`f*o.example.com`) are refused.
+//   §6.5   IP addresses match against iPAddress entries in SAN, never
+//          dNSName entries. Textual IP literals do not get DNS-style
+//          wildcard treatment.
+//
+// Operators pass `b.network.tls.checkServerIdentity9525` to
+// `tls.connect({ checkServerIdentity })` to swap Node's permissive
+// default for the strict policy.
+
+function _normalizeAsciiHost(host) {
+  // RFC 9525 §6.4 — comparisons are ASCII case-insensitive on the
+  // A-label form. We don't perform IDNA conversion (operators that
+  // need U-label hosts must pre-convert via punycode); raw non-ASCII
+  // input is refused so we never silently match across encodings.
+  if (typeof host !== "string" || host.length === 0) return null;
+  for (var i = 0; i < host.length; i += 1) {
+    var cc = host.charCodeAt(i);
+    if (cc > 0x7f) return null;                                                  // allow:raw-byte-literal — ASCII upper bound codepoint
+  }
+  // Strip a trailing dot (FQDN absolute form) for matching.
+  var h = host.toLowerCase();
+  if (h.length > 1 && h.charAt(h.length - 1) === ".") h = h.slice(0, -1);
+  return h;
+}
+
+function _matchDnsNamePattern(pattern, host) {
+  // Both inputs must be ASCII-normalized. `pattern` is from the SAN;
+  // `host` is the operator-supplied target host.
+  pattern = _normalizeAsciiHost(pattern);
+  if (!pattern || !host) return false;
+  if (pattern.indexOf("*") === -1) {
+    return pattern === host;
+  }
+  // Wildcards permitted only as the entire left-most label.
+  var pLabels = pattern.split(".");
+  var hLabels = host.split(".");
+  if (pLabels.length !== hLabels.length) return false;
+  if (pLabels.length < 3) return false;  // refuse `*.tld` — too broad
+  // Only the FIRST label may contain the wildcard, and it must be `*`
+  // exactly (no partial like `f*o`).
+  if (pLabels[0] !== "*") return false;
+  for (var li = 1; li < pLabels.length; li += 1) {
+    if (pLabels[li].indexOf("*") !== -1) return false;
+    if (pLabels[li] !== hLabels[li]) return false;
+  }
+  // Left-most host label must be non-empty (no `*` matching empty).
+  if (hLabels[0].length === 0) return false;
+  return true;
+}
+
+function _parseSanString(rawSubjectAltName) {
+  // Node exposes the SAN as a comma-separated string of typed entries:
+  //   "DNS:foo.example.com, DNS:*.example.com, IP Address:198.51.100.1,
+  //    IP Address:2001:db8::1"
+  // The RFC 9525 verifier only consumes DNS / IP entries.
+  var dns = [];
+  var ips = [];
+  if (typeof rawSubjectAltName !== "string" || rawSubjectAltName.length === 0) {
+    return { dns: dns, ips: ips };
+  }
+  var entries = rawSubjectAltName.split(",");
+  for (var i = 0; i < entries.length; i += 1) {
+    var raw = entries[i].trim();
+    var colon = raw.indexOf(":");
+    if (colon === -1) continue;
+    var kind = raw.slice(0, colon).trim();
+    var val  = raw.slice(colon + 1).trim();
+    if (kind === "DNS") {
+      dns.push(val);
+    } else if (kind === "IP Address" || kind === "IP") {
+      ips.push(val);
+    }
+    // Other GeneralName types (URI / email / dirName / OID-based) are
+    // outside RFC 9525's HTTPS scope.
+  }
+  return { dns: dns, ips: ips };
+}
+
+function _normalizeIpForCompare(ip) {
+  // Lower-case + strip embedded brackets so "[::1]" / "::1" / "::0001"
+  // all compare equal.
+  if (typeof ip !== "string") return null;
+  var s = ip.trim();
+  if (s.length >= 2 && s.charAt(0) === "[" && s.charAt(s.length - 1) === "]") {
+    s = s.slice(1, -1);
+  }
+  // For IPv6 the canonical form is what `net.isIP` accepts; we
+  // round-trip through Buffer comparison via net.isIPv4 / isIPv6.
+  if (net.isIPv4(s)) return { family: 4, text: s };
+  if (net.isIPv6(s)) {
+    // Canonicalize by expanding to bytes and re-emitting lower-case.
+    var parts = s.split("%");                                                    // strip zone id
+    var addr = parts[0];
+    // Expand "::" then re-collapse via toString won't work in pure JS;
+    // instead produce a 16-byte buffer for byte-equal comparison.
+    var bytes = _ipv6ToBytes(addr);
+    if (!bytes) return null;
+    return { family: 6, text: addr.toLowerCase(), bytes: bytes };
+  }
+  return null;
+}
+function _ipv6ToBytes(addr) {
+  // Minimal IPv6 → 16-byte parser. Splits on "::" once, parses each
+  // hextet as base-16 uint16. Returns null on malformed input.
+  if (typeof addr !== "string") return null;
+  var halves;
+  var doubleIdx = addr.indexOf("::");
+  if (doubleIdx === -1) {
+    halves = [addr.split(":"), []];
+  } else {
+    var leftStr  = addr.slice(0, doubleIdx);
+    var rightStr = addr.slice(doubleIdx + 2);
+    halves = [
+      leftStr.length  ? leftStr.split(":")  : [],
+      rightStr.length ? rightStr.split(":") : [],
+    ];
+  }
+  var left = halves[0], right = halves[1];
+  var fillCount = 8 - (left.length + right.length);                              // allow:raw-byte-literal — IPv6 has 8 hextets
+  if (fillCount < 0) return null;
+  var hextets = left.concat(new Array(fillCount).fill("0")).concat(right);
+  if (hextets.length !== 8) return null;                                         // allow:raw-byte-literal — IPv6 hextet count
+  var bytes = Buffer.alloc(16);                                                  // allow:raw-byte-literal — IPv6 = 16 bytes
+  for (var i = 0; i < 8; i += 1) {                                               // allow:raw-byte-literal — IPv6 hextet count
+    var h = hextets[i];
+    if (!safeBuffer.IPV6_HEXTET_RE.test(h)) return null;
+    var v = parseInt(h, 16);                                                     // allow:raw-byte-literal — hex radix
+    bytes[i * 2]     = (v >> 8) & 0xff;                                          // allow:raw-byte-literal — uint8 mask + uint16-half shift
+    bytes[i * 2 + 1] = v & 0xff;                                                 // allow:raw-byte-literal — uint8 mask
+  }
+  return bytes;
+}
+function _ipsEqual(sanIp, hostIp) {
+  var a = _normalizeIpForCompare(sanIp);
+  var b = _normalizeIpForCompare(hostIp);
+  if (!a || !b) return false;
+  if (a.family !== b.family) return false;
+  if (a.family === 4) return a.text === b.text;
+  // family === 6 — byte compare.
+  if (!a.bytes || !b.bytes) return false;
+  if (a.bytes.length !== b.bytes.length) return false;
+  for (var i = 0; i < a.bytes.length; i += 1) {
+    if (a.bytes[i] !== b.bytes[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * @primitive b.network.tls.checkServerIdentity9525
+ * @signature b.network.tls.checkServerIdentity9525(host, cert)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.tls.connectWithEch
+ *
+ * Drop-in replacement for Node's `tls.checkServerIdentity` that
+ * implements RFC 9525 paragraph 6 strictly. Operators pass it to
+ * `tls.connect({ checkServerIdentity })` (or to any framework primitive
+ * that exposes `pkixStrict: true`).
+ *
+ * Differences vs Node's default matcher:
+ *
+ *   - SAN-required when present is mandatory: a peer cert lacking
+ *     `subjectAltName` refuses with `tls/pkix-san-required` (RFC 9525
+ *     paragraph 6.4.4 forbids Common Name fallback).
+ *   - CN-only legacy certs surface a distinct
+ *     `tls/pkix-cn-fallback-refused` code so audit logs distinguish
+ *     "missing SAN" from "ancient CN-only cert still shipping".
+ *   - Wildcard matching is restricted to the entire leftmost label.
+ *     `*.example.com` matches `foo.example.com` but NOT
+ *     `foo.bar.example.com` and NOT `example.com`. Partial wildcards
+ *     like `f*o.example.com` and middle wildcards like
+ *     `foo.*.example.com` refuse.
+ *   - IP literals match `iPAddress` SAN entries only — never DNS
+ *     entries, never wildcards. IPv6 comparison is byte-equal after
+ *     canonicalization (zone-id stripped, `::` expanded).
+ *
+ * Returns `Error | undefined` — the `Error` shape Node expects; when
+ * undefined, the connection is permitted to proceed.
+ *
+ * @example
+ *   var tls  = require("node:tls");
+ *   var b    = require("@blamejs/core");
+ *   var sock = tls.connect({
+ *     host: "internal.example.com",
+ *     port: 443,
+ *     checkServerIdentity: b.network.tls.checkServerIdentity9525,
+ *   });
+ */
+function checkServerIdentity9525(host, cert) {
+  // Drop-in for tls.checkServerIdentity. Returns Error|undefined.
+  // Node calls this with the post-handshake `cert` shape: subject,
+  // subjectaltname, etc.
+  if (typeof host !== "string" || host.length === 0) {
+    return new NetworkTlsError("tls/pkix-hostname-mismatch",
+      "checkServerIdentity9525: host must be a non-empty string");
+  }
+  if (!cert || typeof cert !== "object") {
+    return new NetworkTlsError("tls/pkix-hostname-mismatch",
+      "checkServerIdentity9525: peer cert object missing");
+  }
+  var hostIsIp = net.isIP(host) > 0;
+  var hostNorm = hostIsIp ? host : _normalizeAsciiHost(host);
+  if (!hostIsIp && !hostNorm) {
+    return new NetworkTlsError("tls/pkix-hostname-mismatch",
+      "checkServerIdentity9525: host '" + host + "' is not a valid ASCII " +
+      "DNS name (pre-convert U-labels to A-labels with punycode)");
+  }
+  var rawSan = cert.subjectaltname;
+  if (typeof rawSan !== "string" || rawSan.length === 0) {
+    // RFC 9525 §6.4.4 forbids CN fallback. If there's no SAN we refuse,
+    // never inspect cert.subject.CN — a CN-only cert violates the
+    // modern PKIX baseline and the operator chose the strict checker.
+    return new NetworkTlsError("tls/pkix-san-required",
+      "checkServerIdentity9525: certificate has no subjectAltName " +
+      "extension (RFC 9525 §6.4.4 forbids Common Name fallback)");
+  }
+  var san = _parseSanString(rawSan);
+  if (hostIsIp) {
+    if (san.ips.length === 0) {
+      return new NetworkTlsError("tls/pkix-hostname-mismatch",
+        "checkServerIdentity9525: host '" + host + "' is an IP literal " +
+        "but the certificate's SAN contains no iPAddress entries");
+    }
+    for (var ii = 0; ii < san.ips.length; ii += 1) {
+      if (_ipsEqual(san.ips[ii], host)) return undefined;
+    }
+    return new NetworkTlsError("tls/pkix-hostname-mismatch",
+      "checkServerIdentity9525: host IP '" + host + "' does not match " +
+      "any iPAddress SAN (" + san.ips.join(", ") + ")");
+  }
+  // DNS host — must match a dNSName SAN entry.
+  if (san.dns.length === 0) {
+    return new NetworkTlsError("tls/pkix-hostname-mismatch",
+      "checkServerIdentity9525: certificate's SAN contains no dNSName " +
+      "entries (host '" + host + "' cannot match an iPAddress-only cert)");
+  }
+  for (var di = 0; di < san.dns.length; di += 1) {
+    if (_matchDnsNamePattern(san.dns[di], hostNorm)) return undefined;
+  }
+  return new NetworkTlsError("tls/pkix-hostname-mismatch",
+    "checkServerIdentity9525: host '" + host + "' does not match any " +
+    "dNSName SAN (" + san.dns.join(", ") + ")");
+}
+
+// Detect: did the caller pass a CN-only legacy cert? Surface a
+// distinct error code so operators can grep audit logs for the
+// fallback-refused shape vs a generic mismatch.
+function _refuseCnFallback(host, cert) {
+  if (cert && cert.subject && typeof cert.subject.CN === "string" &&
+      cert.subject.CN.length > 0 &&
+      (typeof cert.subjectaltname !== "string" || cert.subjectaltname.length === 0)) {
+    return new NetworkTlsError("tls/pkix-cn-fallback-refused",
+      "checkServerIdentity9525: peer cert is CN-only (CN='" +
+      cert.subject.CN + "'); RFC 9525 §6.4.4 refuses CN-fallback. " +
+      "Reissue the certificate with a subjectAltName extension covering " +
+      "host '" + host + "'.");
+  }
+  return null;
+}
+
+// Public combined verifier — applies both the SAN-required check and
+// the CN-fallback explicit refusal so operators get the more specific
+// of the two error codes when applicable. checkServerIdentity9525 is
+// the drop-in name; this internal helper is what `connect` wires in.
+function _checkServerIdentityStrict(host, cert) {
+  var cnRefusal = _refuseCnFallback(host, cert);
+  if (cnRefusal) return cnRefusal;
+  return checkServerIdentity9525(host, cert);
+}
+
 module.exports = {
   addCa:               addCa,
   addCaBundle:         addCaBundle,
@@ -2299,7 +3040,11 @@ module.exports = {
   ct:                  ct,
   pqc:                 pqc,
   preferredGroups:     preferredGroups,
+  parseEchConfigList:  parseEchConfigList,
+  connectWithEch:      connectWithEch,
+  checkServerIdentity9525: checkServerIdentity9525,
   TlsTrustError:       TlsTrustError,
   NetworkTlsError:     NetworkTlsError,
   _resetForTest:       _resetForTest,
+  _checkServerIdentityStrict: _checkServerIdentityStrict,
 };