@blamejs/pki 0.3.15 → 0.3.17

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.3.17 — 2026-07-25
+
+Refresh two development-only tooling dependencies to clear newly-disclosed advisories.
+
+### Security
+
+- Refresh the development/fuzzing-only brace-expansion (5.0.7 -> 5.0.8, GHSA-mh99-v99m-4gvg) and tar (7.5.19 -> 7.5.22, GHSA-r292-9mhp-454m) tooling dependencies to versions clear of two newly-disclosed advisories. Both are used only by the development and fuzzing harnesses and are never part of the published package (the toolkit has zero runtime dependencies), so installed contents are unchanged.
+
+## v0.3.16 — 2026-07-24
+
+The EST enrollment client ships -- pki.est fetches CA certificates and enrolls certificates over the wire (RFC 7030), on a new shared node:https transport.
+
+### Added
+
+- pki.est.cacerts(baseUrl, opts?), pki.est.simpleenroll(baseUrl, csr, opts?), and pki.est.simplereenroll(baseUrl, csr, opts?) -- the thin RFC 7030 client verbs over pki.transport. cacerts returns the raw, unordered CA certificate set; simpleenroll submits a PKCS#10 CSR (a DER Buffer or PEM) and returns the issued certificate (chosen by public-key match) with its chain; simplereenroll additionally requires opts.oldCert and enforces the byte-identical Subject + SubjectAltName re-enroll check before the request. A 202 is surfaced as { retry, retryAfterSeconds } and never slept on. Trust is fail-closed: an https URL and an explicit opts.tls.anchors (or opts.tls.useSystemStore) are required, HTTP Basic credentials are answered only after the server is authenticated and are dropped on a cross-origin redirect, and a downgrade, redirect loop, oversized response, or unmatched issued certificate each fails closed with a typed est/* error.
+- pki.transport -- the shared, fail-closed node:https transport the enrollment clients drive. pki.transport.https(defaults) returns a transport(request) -> Promise<{ status, headers, body }>. It is the toolkit's only socket: rejectUnauthorized is always on with no disable path, an explicit trust anchor or a system-store opt-in is required, TLS is floored at 1.2, the response body is bounded while it streams (LIMITS.HTTP_MAX_RESPONSE_BYTES, tightenable downward), and connect/read is bounded by a timeout. It carries no HTTP or protocol semantics -- status, content-type, redirect, and authentication decisions live in the message layer -- so it is reused verbatim across enrollment protocols. errors.TransportError is its default fault type; a protocol client may parameterize it to surface domain codes.
+
 ## v0.3.15 — 2026-07-24
 
 PKCS#12 public-key integrity is produced and verified (RFC 7292 sec. 4).

package/README.md

@@ -216,7 +216,8 @@ is callable today; nothing below is a stub.
 | `pki.schema.pkcs12` | Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores — key bags via the PKCS#8 parser, shrouded keys (algorithm surfaced, ciphertext opaque), cert / CRL / secret bags raw and byte-exact, encrypted and enveloped safes structurally via CMS, `friendlyName` / `localKeyId` decoded, and the exact MAC byte range (`macedBytes`) plus RFC 9579 PBMAC1 recognition for external verification; BER accepted exactly where §4.1 requires it, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.cmp` | Parse DER / PEM RFC 9810 Certificate Management Protocol messages (PKIMessage) — the header (version, sender / recipient incl. the anonymous NULL-DN, nonces, transaction id, general info), the 27-arm body (certificate requests via the CRMF parser, an encrypted certificate's EnvelopedData via CMS, response / revocation / confirmation / error / support / polling arms structural, the rest raw), and the exact `headerBytes` / `bodyBytes` slices an external verifier reconstructs the protected part from; the CMP-before-OCSP dispatch order is enforced, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.csrattrs` | Parse DER EST CSR Attributes (`CsrAttrs`, RFC 8951 §3.5 / RFC 9908) — the `AttrOrOID` items a server sends to shape an enrollment: bare OIDs, attributes with raw values, and decoded views of the RFC 9908 meaningful types (extension requests, EC/RSA key-type conventions, the certification-request-info template). Unknown types tolerated (surfaced raw), fail-closed on structure and the RFC 9908 semantic MUSTs — `parse` |
-| `pki.est` | RFC 7030 / 8951 / 9908 Enrollment over Secure Transport — the transport-agnostic client codecs (the RFC 8951 base64 transfer codec, blind to Content-Transfer-Encoding; the `multipart/mixed` splitter), the certs-only + serverkeygen response validators layered over CMS, the enroll-attribute builders (channel-binding challengePassword, out-of-band key identifiers, SMIMECapabilities, the template-priority enroll plan), and the HTTP response classifier (202 Retry-After surfaced, never slept on; 204/404 on csrattrs a "none available" verdict). No socket, fail-closed — `transferDecode`/`transferEncode`, `parseCertsOnly`, `findIssuedCert`, `parseServerKeygenResponse`, `classifyResponse`, `paths`, and the builders |
+| `pki.est` | RFC 7030 / 8951 / 9908 Enrollment over Secure Transport — the thin client verbs `cacerts` / `simpleenroll` / `simplereenroll` drive the RFC 7030 flow over `pki.transport` (inject your own, or the fail-closed default): https-only, an explicit trust anchor required, same-origin redirects followed but a downgrade / loop refused, a 202 Retry-After surfaced (never slept), HTTP Basic answered only after the server is authenticated, and the issued certificate chosen by public-key match. Under them, the transport-agnostic codecs they compose — the RFC 8951 base64 transfer codec (blind to Content-Transfer-Encoding), the `multipart/mixed` splitter, the certs-only + serverkeygen response validators over CMS, the enroll-attribute builders, and the HTTP response classifier — `cacerts`, `simpleenroll`, `simplereenroll`, `transferDecode`/`transferEncode`, `parseCertsOnly`, `findIssuedCert`, `classifyResponse`, `paths`, and the builders |
+| `pki.transport` | The shared, fail-closed `node:https` transport the enrollment clients drive — `pki.transport.https(defaults)` returns a `transport(request) → { status, headers, body }`. The toolkit's sole socket choke point: an explicit trust anchor (or an opt-in to the system store) is required, `rejectUnauthorized` is always on, TLS is floored at 1.2, the response body is capped while it streams, and a stalled socket times out. Reused verbatim by the EST client today (ACME / CMP next) — `https` |
 | `pki.jose` | RFC 7515 Flattened JWS + RFC 7638 JWK thumbprints — `sign` / `verify` run a Flattened JWS against declarative profiles (ACME outer, EAB inner, keyChange inner) that carry the required/forbidden header rules as data; `base64url` is the strict RFC 4648 §5 codec (padding, non-alphabet, and non-canonical trailing bits rejected); `parseJson` is a bounded reader that refuses duplicate members at any depth; `thumbprint` is the RFC 7638 / 8037 / 9964 canonical digest. The algorithm registry binds each `alg` to its key type (ES/RS/PS/EdDSA/ML-DSA), so `alg:none`, an RS256→HS256 key confusion, and an all-zero ECDSA signature have no code path; `assertPublicJwk` refuses a JWK carrying private material so an exported private key is never published — `sign`, `verify`, `base64url`, `parseJson`, `thumbprint`, `assertPublicJwk` |
 | `pki.acme` | RFC 8555 / 8737 / 8738 / 9773 ACME message layer over `pki.jose` — resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, request builders (newAccount + EAB, newOrder + `replaces`, finalize with CSR identifier-set match and account-key-reuse rejection, challenge responses, deactivation, revokeCert in both key modes, the keyChange nested JWS, POST-as-GET), the http-01 / dns-01 / tls-alpn-01 challenge computations, the dns/ip identifier validators, and the ARI certID (serial sign-padding preserved). A message layer, not an HTTP client — transport-injectable, fail-closed — `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |

package/index.js

@@ -53,6 +53,7 @@ var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
 var sigstore  = require("./lib/sigstore");
 var est        = require("./lib/est");
+var transport  = require("./lib/http-transport");
 var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
 var trust      = require("./lib/trust");
@@ -143,11 +144,17 @@ module.exports = {
   // keyless Fulcio signature over a DSSE-wrapped in-toto SLSA attestation with a
   // Rekor inclusion proof -- offline, zero-dep, against caller-pinned trust.
   sigstore:  sigstore,
-  // `est` is RFC 7030 / 8951 / 9908 Enrollment over Secure Transport -- the
-  // transport-agnostic client codecs (base64 transfer, multipart splitter),
-  // certs-only + serverkeygen validators over CMS, the enroll-attribute builders,
-  // and the HTTP response classifier. No socket; fail-closed.
+  // `est` is RFC 7030 / 8951 / 9908 Enrollment over Secure Transport -- the thin
+  // client verbs (pki.est.cacerts / simpleenroll / simplereenroll) over pki.transport,
+  // plus the transport-agnostic codecs they compose (base64 transfer, multipart
+  // splitter, certs-only + serverkeygen validators over CMS, the enroll-attribute
+  // builders, the HTTP response classifier). est opens no socket; fail-closed.
   est:       est,
+  // `transport` is the shared fail-closed node:https transport the enrollment clients
+  // drive -- pki.transport.https(defaults) returns a transport(request) -> {status,
+  // headers, body}. The toolkit's sole socket choke point: explicit trust anchors,
+  // rejectUnauthorized always on, a TLS floor, a streaming response cap, and a timeout.
+  transport: transport,
   // `jose` is the RFC 7515 Flattened JWS + RFC 7638 JWK-thumbprint layer: a strict
   // base64url codec, a bounded duplicate-key-rejecting JSON reader, profiled
   // sign/verify (ACME-outer / EAB-inner / keyChange-inner), and an alg registry

package/lib/constants.js

@@ -153,6 +153,14 @@ var LIMITS = {
   PEM_MAX_BYTES: BYTES.mib(16),
   DER_MAX_INTEGER_BYTES: BYTES.kib(16),
   OID_MAX_SUBIDENTIFIER_BYTES: 32,
+  // Network transport response ceiling (pki.transport / the EST client). A remote
+  // server's HTTP response body is bounded WHILE it streams -- the accumulator
+  // aborts the socket the instant the running total crosses this cap, before the
+  // body reaches a decoder, so a malicious length field cannot drive unbounded
+  // allocation (RFC 7030 sec. 6). Sized above a base64-inflated DER_MAX_BYTES
+  // document plus multipart/header overhead (16 MiB * 4/3 ~= 21.3 MiB); 24 MiB
+  // clears it. An operator may only tighten it DOWNWARD via opts.maxResponseBytes.
+  HTTP_MAX_RESPONSE_BYTES: BYTES.mib(24),
   // Deterministic-CBOR codec ceilings (RFC 8949), the DER neighbours' siblings:
   // a whole-document cap refused before the walk, a nesting cap, and a per-value
   // bignum ceiling the document cap can't provide. Unlike DER_MAX_INTEGER_BYTES,

package/lib/est.js

@@ -9,10 +9,19 @@
  * @slug       est
  *
  * @intro
- *   Enrollment over Secure Transport (RFC 7030, updated by RFC 8951 and
- *   RFC 9908) -- the transport-agnostic codecs, validators, and request builders
- *   an EST client composes over the shipped CMS / CSR / PKCS#8 / X.509 parsers.
- *   No socket is opened here: `transferDecode` / `transferEncode` are the RFC 8951
+ *   Enrollment over Secure Transport (RFC 7030, updated by RFC 8951 and RFC 9908).
+ *   The network verbs -- `cacerts`, `simpleenroll`, `simplereenroll` -- run the thin
+ *   RFC 7030 client: they compose the codecs below over the shared `pki.transport`
+ *   (a caller MAY inject `opts.transport`; the default is a fail-closed
+ *   `pki.transport.https`). This module opens no socket itself -- the sole socket
+ *   choke point is `pki.transport` -- so the verbs stay a thin, fail-closed shell:
+ *   https-only (`est/insecure-url`), an explicit trust anchor required
+ *   (`est/no-trust-anchors`), same-origin redirects followed but a downgrade / loop
+ *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic answered only
+ *   after the transport authenticated the server, and the issued certificate chosen
+ *   by public-key match. Under them sit the transport-agnostic codecs, validators, and
+ *   request builders over the shipped CMS / CSR / PKCS#8 / X.509 parsers:
+ *   `transferDecode` / `transferEncode` are the RFC 8951
  *   sec. 3 base64 transfer codec (RFC 4648, and DELIBERATELY blind to any
  *   Content-Transfer-Encoding header -- errata 5904/5107); `splitMultipartMixed`
  *   is the /serverkeygen `multipart/mixed` splitter; `parseCertsOnly` validates a
@@ -36,9 +45,10 @@
  *   module). DER-only where DER, fail-closed everywhere.
  *
  * @card
- *   EST (RFC 7030 / 8951 / 9908) client codecs -- base64 transfer, multipart
- *   splitter, certs-only + serverkeygen validators over CMS, the enroll-attribute
- *   builders, and the HTTP response classifier. Transport-agnostic, fail-closed.
+ *   EST (RFC 7030 / 8951 / 9908) client -- the cacerts / simpleenroll / simplereenroll
+ *   verbs over the shared pki.transport, plus the codecs they compose: base64 transfer,
+ *   multipart splitter, certs-only + serverkeygen validators over CMS, the
+ *   enroll-attribute builders, and the HTTP response classifier. Fail-closed.
  */
 
 var asn1 = require("./asn1-der");
@@ -51,6 +61,7 @@ var pkcs8 = require("./schema-pkcs8");
 var csr = require("./schema-csr");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
+var httpTransport = require("./http-transport");
 
 var EstError = frameworkError.EstError;
 function E(code, message, cause) { return new EstError(code, message, cause); }
@@ -498,7 +509,7 @@ function classifyResponse(status, headers, body, opts) {
   }
   if (status === 202) {
     var ra = h["retry-after"];
-    if (ra === undefined || ra === null || String(ra).trim() === "") throw E("est/missing-retry-after", "an HTTP 202 EST response must include Retry-After (RFC 8951 sec. 3.3)");
+    if (ra === undefined || ra === null || String(ra).trim() === "") throw E("est/missing-retry-after", "an HTTP 202 EST response must include Retry-After (RFC 7030 sec. 4.2.3)");
     var raStr = String(ra).trim();
     // Retry-After is delay-seconds OR an HTTP-date (RFC 7231 sec. 7.1.3). A
     // delay-seconds becomes retryAfterSeconds directly; an HTTP-date is surfaced
@@ -708,7 +719,304 @@ function reenrollGuard(oldCertDer, newCsrDer) {
   return { subjectDn: oldSubjectDn, subjectAltName: oldSan };
 }
 
+// ---- the thin RFC 7030 client: network verbs over the shared pki.transport ----
+
+var DEFAULT_TIMEOUT = constants.TIME.seconds(30);
+var MAX_TIMEOUT = constants.TIME.seconds(600);
+
+// The DER of a caller-supplied CSR: a DER Buffer as-is, or a PEM "CERTIFICATE REQUEST"
+// decoded. Any other input is a config-time est/bad-input.
+function _csrDer(input) {
+  if (Buffer.isBuffer(input)) return input;
+  if (typeof input === "string") return csr.pemDecode(input);
+  throw E("est/bad-input", "a CSR must be a DER Buffer or a PEM CERTIFICATE REQUEST string");
+}
+
+// Parse + validate the request URL BEFORE any transport is called: a URL that will not
+// parse is est/bad-url, a non-https URL is est/insecure-url (RFC 7030 sec. 3.3). Runs
+// even when a transport is injected, so an insecure URL never reaches the wire.
+function _parseUrl(urlStr) {
+  var url;
+  try { url = new URL(String(urlStr)); }
+  catch (e) { throw E("est/bad-url", "the EST server URL did not parse: " + String(urlStr), e); }
+  if (url.protocol !== "https:") throw E("est/insecure-url", "EST requires https (RFC 7030 sec. 3.3), got " + url.protocol + " for " + urlStr);
+  return url;
+}
+
+// Map opts.tls (operator-facing) to the transport request.tls shape (anchors -> ca).
+// rejectUnauthorized is NOT here -- the transport forces it on unconditionally.
+function _tlsForRequest(opts) {
+  var t = opts.tls || {};
+  return { anchors: t.anchors, useSystemStore: t.useSystemStore, cert: t.cert, key: t.key, minVersion: t.minVersion, servername: t.servername, checkServerIdentity: t.checkServerIdentity };
+}
+
+// Resolve a redirect target: reject a scheme downgrade (est/insecure-redirect) or a
+// cross-origin redirect on a non-GET/HEAD method without opt-in
+// (est/cross-origin-redirect); a Location that will not parse is est/bad-url. Same-origin
+// (and cross-origin GET/HEAD) are followed -- the transport re-runs every TLS check on the
+// new connection (RFC 7030 sec. 3.2.1).
+function _redirectTarget(current, location, method, opts) {
+  if (location == null || String(location).trim() === "") throw E("est/http-error", "a redirect response carried no Location header");
+  var resolved;
+  try { resolved = new URL(String(location), current.href); }
+  catch (e) { throw E("est/bad-url", "a redirect Location did not parse: " + location, e); }
+  if (resolved.protocol !== "https:") throw E("est/insecure-redirect", "a redirect to a non-https URL is refused (RFC 7030 sec. 3.2.1): " + resolved.protocol);
+  var safeMethod = method === "GET" || method === "HEAD";
+  if (resolved.origin !== current.origin && !safeMethod && !opts.allowCrossOriginRedirect) {
+    throw E("est/cross-origin-redirect", "a cross-origin redirect on a " + method + " needs opts.allowCrossOriginRedirect (RFC 7030 sec. 3.2.1)");
+  }
+  return resolved;
+}
+
+// Does WWW-Authenticate advertise a Basic challenge? The quoted-string contents are blanked first
+// (a quoted auth-param may contain a comma + "Basic", e.g. `Digest realm="x, Basic required"`, which
+// must NOT be read as a Basic challenge), then Basic is matched as an auth-scheme TOKEN (at the start
+// or after a comma-separated challenge, followed by whitespace / a comma / end) -- never a substring,
+// so `Digest realm="basic"` / `Bearer error="basic required"` are not taken as Basic either.
+function _hasBasicChallenge(www) {
+  var s = String(www || "").replace(/"(?:[^"\\]|\\.)*"/g, "\"\"");
+  return /(?:^|,)\s*Basic(?=[\s,]|$)/i.test(s);
+}
+
+// The redirect-follow + HTTP-auth-retry loop. Returns the terminal transport response
+// ({status, headers, body}) -- a 2xx, a 202, or a non-401 4xx/5xx. A 3xx is followed
+// (bounded by maxRedirects); a 401 is answered ONCE with Basic credentials, and ONLY when
+// the caller supplied them and the challenge is Basic (RFC 7030 sec. 3.2.3) -- the server
+// was authenticated by the transport's rejectUnauthorized TLS before any credential is
+// transmitted (no credential ever precedes server authorization).
+function _drive(method, url, body, headers, opts, transport, budgets) {
+  var redirects = 0;
+  var authTried = false;
+  var initialOrigin = url.origin;   // the origin the caller intended to authenticate to
+  var tls = budgets.tls;            // narrowed (mTLS client identity stripped) on a cross-origin hop
+  function step() {
+    return transport({ method: method, url: url.href, headers: headers, body: body, tls: tls, timeout: budgets.timeout, maxResponseBytes: budgets.maxResponseBytes }).then(function (res) {
+      res = res || {};
+      var blen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "latin1");
+      if (blen > budgets.maxResponseBytes) throw E("est/response-too-large", "the response body (" + blen + " bytes) exceeds the " + budgets.maxResponseBytes + "-byte cap (RFC 7030 sec. 6)");
+      // The transport contract returns lowercased headers, but the injectable seam only promises
+      // { status, headers, body }; normalize here so a redirect Location / WWW-Authenticate from an
+      // injected transport using ordinary HTTP casing is read correctly (never missed as absent).
+      var h = {};
+      Object.keys(res.headers || {}).forEach(function (k) { h[k.toLowerCase()] = res.headers[k]; });
+      var status = res.status;
+      if (status >= 300 && status < 400) {
+        if (redirects >= budgets.maxRedirects) throw E("est/too-many-redirects", "the redirect chain exceeded maxRedirects=" + budgets.maxRedirects + " (RFC 7030 sec. 3.2.1)");
+        // 303 See Other directs a non-GET/HEAD request to retrieve the target with GET and no body
+        // (RFC 7231 sec. 6.4.4); drop the request body + its entity content-type before following, so
+        // the CSR is not re-POSTed to the redirect target as a duplicate enrollment.
+        if (status === 303 && method !== "GET" && method !== "HEAD") {
+          method = "GET";
+          body = null;
+          if (headers["content-type"]) { headers = Object.assign({}, headers); delete headers["content-type"]; }
+        }
+        var prevOrigin = url.origin;
+        url = _redirectTarget(url, h.location, method, opts);
+        // Credentials MUST NOT cross an origin boundary. A redirect to a different web origin (even a
+        // permitted cross-origin GET) drops BOTH the HTTP Basic Authorization header AND the mTLS
+        // client identity (cert/key), so a prior 401's password and the caller's certificate + proof
+        // of private-key possession are never presented to a different server.
+        if (url.origin !== prevOrigin) {
+          if (headers.authorization) { headers = Object.assign({}, headers); delete headers.authorization; }
+          if (tls && (tls.cert || tls.key)) { tls = Object.assign({}, tls); delete tls.cert; delete tls.key; }
+        }
+        redirects += 1;
+        return step();
+      }
+      if (status === 401) {
+        if (authTried) throw E("est/auth-required", "the server rejected the credentialed request (RFC 7030 sec. 3.2.3)");
+        // Answer a challenge ONLY on the origin the caller targeted: a 401 arriving after a
+        // cross-origin redirect is a different server, and the client MUST NOT send its credentials
+        // there (RFC 7030 sec. 3.6 -- credentials go only to an authorized server the caller chose).
+        if (url.origin !== initialOrigin) throw E("est/auth-required", "refusing to send HTTP credentials to a redirected origin (RFC 7030 sec. 3.6)");
+        var www = String(h["www-authenticate"] || "");
+        if (!_hasBasicChallenge(www)) throw E("est/auth-required", "the server requires an unsupported HTTP authentication scheme (only Basic is supported): " + www);
+        if (opts.username === undefined && opts.password === undefined) throw E("est/auth-required", "the server requires HTTP authentication but no credentials were supplied (RFC 7030 sec. 3.2.3)");
+        headers = Object.assign({}, headers, { authorization: "Basic " + Buffer.from((opts.username || "") + ":" + (opts.password || ""), "utf8").toString("base64") });
+        authTried = true;
+        return step();
+      }
+      return res;
+    });
+  }
+  return step();
+}
+
+// The shared client entry: build the op URL, validate it + the trust config + the budgets
+// (ALL before any transport call so a config fault proves the transport was never reached),
+// then drive the request through the redirect/auth loop.
+function _client(op, method, baseUrl, body, headers, opts) {
+  // paths() concatenates onto the base string, so a query / fragment on the base URL would capture
+  // the operation path (sending the request -- possibly an enrollment CSR -- to the wrong resource).
+  var base;
+  try { base = new URL(String(baseUrl)); }
+  catch (e) { throw E("est/bad-url", "the EST base URL did not parse: " + String(baseUrl), e); }
+  if (base.search || base.hash) throw E("est/bad-url", "the EST base URL must not carry a query or fragment component (RFC 7030 sec. 3.2.2)");
+  var url = _parseUrl(paths(baseUrl, { label: opts.label })[op]);
+  var transport = opts.transport;
+  if (!transport) {
+    var t = opts.tls || {};
+    var hasAnchors = t.anchors !== undefined && t.anchors !== null && !(Array.isArray(t.anchors) && t.anchors.length === 0);
+    if (!hasAnchors && t.useSystemStore !== true) throw E("est/no-trust-anchors", "no explicit trust anchor and tls.useSystemStore not set to true -- refusing an unpinned server (RFC 7030 sec. 3.6)");
+    transport = httpTransport.https({ E: E, errPrefix: "est" });
+  }
+  var budgets = {
+    tls: _tlsForRequest(opts),
+    timeout: guard.limits.cap(opts.timeout, "timeout", DEFAULT_TIMEOUT, { E: E, code: "est/bad-input", min: 1, max: MAX_TIMEOUT }),
+    maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "est/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
+    maxRedirects: guard.limits.cap(opts.maxRedirects, "maxRedirects", 5, { E: E, code: "est/bad-input", min: 0, max: 32 }),
+  };
+  return _drive(method, url, body, Object.assign({}, headers), opts, transport, budgets);
+}
+
+// Turn a terminal response into the verb result: classifyResponse gates status +
+// content-type (202 -> a surfaced retry, never slept; 4xx/5xx -> est/http-error), then an
+// empty 200 is rejected and the certs-only body is decoded + validated. For an enroll, the
+// issued certificate is the public-key match (findIssuedCert), never a positional guess;
+// the remaining certificates are the chain.
+function _certsResult(op, res, opts, csrSpki) {
+  var verdict = classifyResponse(res.status, res.headers, res.body, { op: op, now: opts.now });
+  if (verdict.status === "retry") {
+    // 202 Retry-After is an ENROLLMENT response (RFC 7030 sec. 4.2.3); a successful /cacerts is 200
+    // only (sec. 4.1.3), so a 202 there is a nonconforming server -> fail closed rather than "retry".
+    if (op === "cacerts") throw E("est/http-error", "a /cacerts response must be HTTP 200, not 202 (RFC 7030 sec. 4.1.3)");
+    return { retry: true, retryAfterSeconds: verdict.retryAfterSeconds, retryAfterDate: verdict.retryAfterDate };
+  }
+  // Only the RFC-defined success statuses are accepted: a non-standard 2xx (201, 206, ...) that the
+  // classifier reports as "unexpected" must NOT have its body decoded and accepted as certificates.
+  if (verdict.status !== "ok") throw E("est/http-error", "an EST " + op + " response must be HTTP 200 or 202 (RFC 7030 sec. 4.1.3 / 4.2.3), got " + res.status);
+  var bodyLen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "latin1");
+  if (bodyLen === 0) throw E("est/empty-body", "a 200 " + op + " response carried an empty body (RFC 7030 sec. 4.1.3 / 4.2.3)");
+  var parsed = parseCertsOnly(transferDecode(res.body));
+  if (op === "cacerts") return { certificates: parsed.certificates, crls: parsed.crls };
+  var issued = findIssuedCert(parsed.certificates, csrSpki);
+  if (!issued) throw E("est/issued-cert-not-found", "no returned certificate matched the submitted CSR public key (RFC 5272 sec. 4.1)");
+  // The chain is every OTHER response certificate (by reference, so a byte-identical duplicate is
+  // NOT silently collapsed into the issued cert). Exactly one certificate may match the submitted
+  // public key -- a second match (a renewed cert sharing the key, or a duplicate entry) makes the
+  // issued certificate ambiguous, since the certs-only set has no issuance ordering (RFC 5272 sec. 4.1).
+  var chain = parsed.certificates.filter(function (c) { return c !== issued; });
+  if (findIssuedCert(chain, csrSpki)) throw E("est/ambiguous-issued-cert", "the enroll response carried more than one certificate matching the submitted CSR public key; the issued certificate is ambiguous (RFC 5272 sec. 4.1)");
+  if (opts.strict && chain.length > 0) throw E("est/unexpected-certs", "strict: the enroll response carried " + parsed.certificates.length + " certificates, expected exactly the issued one");
+  return { certificate: issued, chain: chain, certificates: parsed.certificates };
+}
+
+function _enroll(op, baseUrl, csrInput, opts) {
+  var csrDer = _csrDer(csrInput);
+  var spki = csr.parse(csrDer).subjectPublicKeyInfo;
+  var body = transferEncode(csrDer);
+  return _client(op, "POST", baseUrl, body, { accept: "application/pkcs7-mime", "content-type": "application/pkcs10" }, opts)
+    .then(function (res) { return _certsResult(op, res, opts, spki); });
+}
+
+/**
+ * @primitive  pki.est.cacerts
+ * @signature  pki.est.cacerts(baseUrl, opts?) -> Promise<{ certificates, crls } | { retry, retryAfterSeconds }>
+ * @since      0.3.16
+ * @status     experimental
+ * @spec       RFC 7030, RFC 8951
+ * @related    pki.est.simpleenroll, pki.transport.https
+ *
+ * Fetch a CA's certificates over the wire: GET `<baseUrl>/.well-known/est/cacerts` through
+ * the shared `pki.transport` (inject `opts.transport`, else a fail-closed
+ * `pki.transport.https`). Returns the raw, unordered certs-only set
+ * (`{ certificates, crls }`), or `{ retry: true, retryAfterSeconds }` on a 202 (surfaced,
+ * never slept). https-only (`est/insecure-url`); an explicit `opts.tls.anchors` (or an
+ * `opts.tls.useSystemStore` opt-in) is required (`est/no-trust-anchors`); the returned CA
+ * certificate is NOT auto-trusted -- the caller path-validates it and supplies the accepted
+ * anchor on the next call.
+ *
+ * @opts
+ *   - `transport` -- an injected transport(request) -> {status, headers, body}; default pki.transport.https.
+ *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }.
+ *   - `label` -- an OPTIONAL CA label path segment; `timeout` / `maxResponseBytes` / `maxRedirects` -- budgets.
+ *   - `now` -- receipt time (epoch ms) to render a 202 Retry-After HTTP-date as seconds.
+ * @example
+ *   // a live CA uses the default pki.transport.https; here an injected transport returns a canned bag
+ *   var r = await pki.est.cacerts("https://ca.example",
+ *     { transport: function () { return Promise.resolve({ status: 200, headers: { "content-type": "application/pkcs7-mime" }, body: caCertsDer.toString("base64") }); } });
+ *   r.certificates;   // -> [Buffer, ...] raw, unordered
+ */
+function cacerts(baseUrl, opts) {
+  opts = opts || {};
+  return Promise.resolve().then(function () {
+    return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts);
+  }).then(function (res) { return _certsResult("cacerts", res, opts, null); });
+}
+
+/**
+ * @primitive  pki.est.simpleenroll
+ * @signature  pki.est.simpleenroll(baseUrl, csr, opts?) -> Promise<{ certificate, chain, certificates } | { retry, retryAfterSeconds }>
+ * @since      0.3.16
+ * @status     experimental
+ * @spec       RFC 7030, RFC 5272
+ * @related    pki.csr.sign, pki.est.simplereenroll, pki.est.cacerts
+ *
+ * Enroll for a certificate: POST a PKCS#10 `csr` (a DER Buffer or a PEM CERTIFICATE REQUEST,
+ * e.g. from `pki.csr.sign`) to `<baseUrl>/.well-known/est/simpleenroll` as
+ * `application/pkcs10`, over the shared `pki.transport`. Returns the issued certificate
+ * chosen by public-key match against the submitted CSR (`certificate`), the remaining
+ * certificates (`chain`), and the raw set (`certificates`); or `{ retry: true,
+ * retryAfterSeconds }` on a 202. No returned certificate matching the CSR key fails closed
+ * (`est/issued-cert-not-found`); `opts.strict` requires exactly the issued certificate. A
+ * 401 is answered once with HTTP Basic ONLY when `opts.username`/`password` are supplied and
+ * the transport already authenticated the server.
+ *
+ * @opts
+ *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now` -- as pki.est.cacerts.
+ *   - `strict` -- reject an enroll response that carries more than the single issued certificate.
+ *   - `username` / `password` -- HTTP Basic credentials, answered only after server authorization (empty username allowed).
+ *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on this POST.
+ * @example
+ *   var req = await pki.csr.sign({ subject: "device.example", subjectPublicKey: signerSpki }, { key: signerKeyPkcs8 });
+ *   // a 202 means the CA queued the request -- the verb surfaces the delay, never sleeps
+ *   var r = await pki.est.simpleenroll("https://ca.example", req,
+ *     { transport: function () { return Promise.resolve({ status: 202, headers: { "retry-after": "60" }, body: "" }); } });
+ *   r.retry && r.retryAfterSeconds;   // 60
+ */
+function simpleenroll(baseUrl, csrInput, opts) {
+  opts = opts || {};
+  return Promise.resolve().then(function () { return _enroll("simpleenroll", baseUrl, csrInput, opts); });
+}
+
+/**
+ * @primitive  pki.est.simplereenroll
+ * @signature  pki.est.simplereenroll(baseUrl, csr, opts?) -> Promise<{ certificate, chain, certificates } | { retry, retryAfterSeconds }>
+ * @since      0.3.16
+ * @status     experimental
+ * @spec       RFC 7030
+ * @related    pki.est.simpleenroll, pki.est.reenrollGuard
+ *
+ * Renew / rekey a certificate: identical to `pki.est.simpleenroll` but POSTs to
+ * `/.well-known/est/simplereenroll` and REQUIRES `opts.oldCert` (the certificate being
+ * renewed). Before anything crosses the wire, `reenrollGuard` enforces that the CSR's
+ * Subject and SubjectAltName (names and criticality) are byte-identical to `opts.oldCert`
+ * (RFC 7030 sec. 4.2.2) -- a mismatch fails closed (`est/reenroll-subject-mismatch` /
+ * `est/reenroll-san-mismatch`) and the transport is never called. A missing `opts.oldCert`
+ * is `est/bad-input`.
+ *
+ * @opts
+ *   - `oldCert` -- REQUIRED, the DER certificate being renewed (the re-enroll identity check).
+ *   - every option of pki.est.simpleenroll (transport, tls, label, budgets, strict, credentials).
+ * @example
+ *   // reenrollGuard enforces the RFC 7030 sec. 4.2.2 identity check before anything is sent
+ *   var r = await pki.est.simplereenroll("https://ca.example", renewCsr,
+ *     { oldCert: signerCertDer, transport: function () { return Promise.resolve({ status: 202, headers: { "retry-after": "60" }, body: "" }); } });
+ *   r.retry;   // true
+ */
+function simplereenroll(baseUrl, csrInput, opts) {
+  opts = opts || {};
+  return Promise.resolve().then(function () {
+    if (!opts.oldCert) throw E("est/bad-input", "simplereenroll requires opts.oldCert (the certificate being renewed, RFC 7030 sec. 4.2.2)");
+    reenrollGuard(opts.oldCert, _csrDer(csrInput));   // est/reenroll-* on mismatch, BEFORE the POST
+    return _enroll("simplereenroll", baseUrl, csrInput, opts);
+  });
+}
+
 module.exports = {
+  cacerts: cacerts,
+  simpleenroll: simpleenroll,
+  simplereenroll: simplereenroll,
   transferDecode: transferDecode,
   transferEncode: transferEncode,
   splitMultipartMixed: splitMultipartMixed,

package/lib/framework-error.js

@@ -264,6 +264,15 @@ var CsrattrsError = defineClass("CsrattrsError", { withCause: true });
 // `.cause`.
 var EstError = defineClass("EstError", { withCause: true });
 
+// TransportError -- a fault from the shared node:https transport (pki.transport):
+// a non-https / unparseable request URL, a missing trust anchor, a TLS handshake /
+// server-authentication failure, a negotiated protocol below the floor, a response
+// over the size cap, or a connect / read timeout. A protocol client (est / acme /
+// cmp) may parameterize the transport with its OWN error factory + code prefix so
+// the same choke point surfaces domain codes; this is the default identity when the
+// transport is used directly. Carries the underlying socket / TLS fault as `.cause`.
+var TransportError = defineClass("TransportError", { withCause: true });
+
 // JoseError -- a JOSE (RFC 7515 JWS / RFC 7518 JWA / RFC 7638 thumbprint)
 // fault: a non-canonical base64url field, a duplicate JSON member, a
 // bounds violation, a header that fails its profile (alg/nonce/url/jwk-kid),
@@ -361,6 +370,7 @@ module.exports = {
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,
   EstError:         EstError,
+  TransportError:   TransportError,
   JoseError:        JoseError,
   AcmeError:        AcmeError,
   TrustError:       TrustError,

package/lib/http-transport.js

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.transport
+ * @nav        Protocols
+ * @title      Transport
+ * @order      195
+ * @slug       transport
+ *
+ * @intro
+ *   The shared, fail-closed `node:https` transport the enrollment protocol clients
+ *   drive -- `pki.est` now, `pki.acme` and `pki.cmp` next. This is the ONLY module in
+ *   the toolkit that opens a socket; every protocol layer stays transport-agnostic and
+ *   composes it (or an injected substitute) through one contract:
+ *   `transport(request) -> Promise<{ status, headers, body }>`. The response triple is
+ *   exactly what a message layer's classifier consumes, so no protocol semantics leak
+ *   into the socket layer -- the transport owns socket lifecycle, the TLS trust policy,
+ *   the streaming size cap, and the timeout budget; the caller owns HTTP status,
+ *   content-type, redirect, and authentication decisions.
+ *
+ *   `pki.transport.https(defaults?)` binds TLS + budget defaults and returns a
+ *   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
+ *   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
+ *   factory + code prefix, so the same choke point surfaces domain-specific codes.
+ *
+ * @card
+ *   The shared fail-closed node:https transport (est / acme / cmp): explicit trust
+ *   anchors, rejectUnauthorized always on, a TLS floor, a streaming response-size cap,
+ *   and a timeout -- behind one `transport(request) -> {status, headers, body}` seam.
+ */
+
+var nodeHttps = require("node:https");
+var nodeNet = require("node:net");
+var nodeTls = require("node:tls");
+var constants = require("./constants");
+var guard = require("./guard-all");
+var frameworkError = require("./framework-error");
+
+var TransportError = frameworkError.TransportError;
+function defaultE(code, message, cause) { return new TransportError(code, message, cause); }
+
+var DEFAULT_TIMEOUT = constants.TIME.seconds(30);
+var MAX_TIMEOUT = constants.TIME.seconds(600);
+var DEFAULT_MIN_VERSION = "TLSv1.2";
+
+// A config-time budget: cap() with the caller's typed factory + a >= 1 floor and an
+// upper bound (maxResponseBytes may only be tightened DOWNWARD from the default). A
+// NaN / negative / over-max value is a typed reject, never a silently-disabled bound.
+function _budget(value, key, dflt, max, E, code) {
+  return guard.limits.cap(value, key, dflt, { E: E, code: code, min: 1, max: max, label: key });
+}
+
+// Node's `ca` option expects PEM; a raw DER certificate Buffer -- the toolkit's native trust-anchor
+// form (e.g. what pki.est.cacerts / parseCertsOnly return) -- is silently ignored there, so the
+// connection would fail server authentication despite a valid anchor. Wrap a DER anchor as PEM
+// (a Buffer already carrying PEM text, or a PEM string, passes through unchanged).
+function _pemifyAnchor(a) {
+  if (typeof a === "string") return a;
+  if (Buffer.isBuffer(a)) {
+    // Detect PEM by its armor at the START (after optional whitespace) only: a DER certificate begins
+    // with the SEQUENCE tag 0x30 and may itself contain the bytes "-----BEGIN" in a subject / extension
+    // value, so an anywhere-search would leave such a DER anchor unwrapped and unusable.
+    if (/^\s*-----BEGIN /.test(a.toString("latin1", 0, 64))) return a;
+    var b64 = a.toString("base64").replace(/.{1,64}/g, "$&\n");
+    return "-----BEGIN CERTIFICATE-----\n" + b64 + "-----END CERTIFICATE-----\n";
+  }
+  return a;
+}
+function _pemifyAnchors(anchors) {
+  var list = Array.isArray(anchors) ? anchors.map(_pemifyAnchor) : [_pemifyAnchor(anchors)];
+  return list;
+}
+
+// The OS system certificate store plus node's bundled roots (cached; the read is not free), for a
+// tls.useSystemStore opt-in. Node's default (no `ca`) is ONLY the bundled Mozilla set, so a server
+// chaining to an OS-installed enterprise CA would fail without this. On a node too old for
+// tls.getCACertificates the cache stays empty and the caller falls back to node's default store.
+var _systemCaCache = null;
+function _systemCa() {
+  if (_systemCaCache !== null) return _systemCaCache;
+  var out = [];
+  if (typeof nodeTls.getCACertificates === "function") {
+    ["system", "bundled"].forEach(function (t) {
+      // allow:swallow-unverified a store TYPE unsupported on this node is skipped; the other type
+      // (and, if both fail, node's default-store fallback) still applies -- a best-effort store load.
+      try { var c = nodeTls.getCACertificates(t); if (Array.isArray(c)) out = out.concat(c); } catch (_e) { /* unsupported type */ }
+    });
+  }
+  _systemCaCache = out;
+  return out;
+}
+
+// Classify a node request/TLS error into the transport's fail-closed verdict: a
+// protocol-version mismatch is the TLS floor; a certificate / identity / handshake
+// failure is a server-authentication failure; anything else is a generic transport
+// error. Every arm threads the raw fault as `.cause`, so the diagnostic survives.
+function _classifyError(e, C) {
+  var s = String((e && e.code) || "") + " " + String((e && e.message) || "");
+  if (/PROTOCOL_VERSION|UNSUPPORTED_PROTOCOL|VERSION_TOO_LOW|WRONG_VERSION|NO_PROTOCOLS_AVAILABLE|INAPPROPRIATE_FALLBACK/i.test(s)) return C("tls-floor");
+  if (/CERT|SELF.?SIGNED|VERIFY|ALTNAME|HOSTNAME|DEPTH_ZERO|LOCAL_ISSUER|HANDSHAKE|\bSSL\b|\bTLS\b/i.test(s)) return C("server-auth-failed");
+  return C("transport-error");
+}
+
+/**
+ * @primitive  pki.transport.https
+ * @signature  pki.transport.https(defaults?) -> transport
+ * @since      0.3.16
+ * @status     experimental
+ * @spec       RFC 7030, RFC 8996
+ * @defends    tls-downgrade (CWE-757), server-impersonation (CWE-297), response-flooding (CWE-770)
+ * @related    pki.est.cacerts, pki.est.simpleenroll
+ *
+ * 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;
+ * `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.
+ * 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
+ * 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.
+ * 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 ONLY opt-in to node's bundled CA store (default false).
+ *   - `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.
+ * @example
+ *   var t = pki.transport.https({ tls: { anchors: [caPem] } });
+ *   var res = await t({ method: "GET", url: "https://ca.example/.well-known/est/cacerts" });
+ *   res.status;   // 200
+ */
+function httpsTransport(defaults) {
+  defaults = defaults || {};
+  var E = typeof defaults.E === "function" ? defaults.E : defaultE;
+  var prefix = defaults.errPrefix || "transport";
+  function C(name) { return prefix + "/" + name; }
+  var tlsDefaults = defaults.tls || {};
+
+  // Synchronous config validation + node-options build. Throws the typed verdict on any
+  // fault (a non-https URL, no trust anchor, a bad budget, a sub-floor minVersion) so the
+  // async executor below never has to `return reject(...)`. rejectUnauthorized is forced on.
+  function _prepare(request) {
+    var url;
+    try { url = new URL(String(request.url)); }
+    catch (e) { throw E(C("bad-url"), "the request URL did not parse: " + String(request.url), e); }
+    if (url.protocol !== "https:") throw E(C("insecure-url"), "transport requires https (RFC 7030 sec. 3.3), got " + url.protocol);
+
+    var reqTls = request.tls || {};
+    var anchors = reqTls.anchors !== undefined ? reqTls.anchors : tlsDefaults.anchors;
+    // System-store trust requires a STRICT boolean true; a non-boolean (a "false" / "true" string from
+    // JSON/env, a truthy object) is treated as absent, so a malformed config fails closed rather than
+    // silently trusting node's bundled roots.
+    var useSystem = (reqTls.useSystemStore !== undefined ? reqTls.useSystemStore : tlsDefaults.useSystemStore) === true;
+    var hasAnchors = anchors !== undefined && anchors !== null && !(Array.isArray(anchors) && anchors.length === 0);
+    if (!hasAnchors && !useSystem) throw E(C("no-trust-anchors"), "no explicit trust anchor and useSystemStore not set -- refusing an unpinned server (RFC 7030 sec. 3.6)");
+
+    var timeout = _budget(request.timeout !== undefined ? request.timeout : defaults.timeout, "timeout", DEFAULT_TIMEOUT, MAX_TIMEOUT, E, C("bad-input"));
+    var maxBytes = _budget(request.maxResponseBytes !== undefined ? request.maxResponseBytes : defaults.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, E, C("bad-input"));
+
+    var minVersion = reqTls.minVersion || tlsDefaults.minVersion || DEFAULT_MIN_VERSION;
+    if (minVersion !== "TLSv1.2" && minVersion !== "TLSv1.3") throw E(C("bad-input"), "tls.minVersion must be 'TLSv1.2' or 'TLSv1.3' (never below the floor), got " + minVersion);
+
+    var body = request.body;
+    if (Buffer.isBuffer(body)) body = guard.bytes.view(body, E, C("bad-input"), "the request body");
+
+    // URL.hostname keeps the square brackets on an IPv6 literal ([2001:db8::1]); node's `hostname`
+    // option and its IP-detection expect the bare address, so strip the brackets once here.
+    var host = url.hostname.replace(/^\[(.*)\]$/, "$1");
+    var options = {
+      method: request.method || "GET",
+      hostname: host,
+      port: url.port || 443,
+      path: url.pathname + url.search,
+      headers: request.headers || {},
+      minVersion: minVersion,
+      rejectUnauthorized: true,   // ALWAYS on -- there is no code path that disables server verification
+      // Opt out of connection pooling: node's keep-alive agent keys the socket pool on host + TLS
+      // options but NOT on checkServerIdentity, so a reused socket would skip a per-request identity /
+      // pinning callback. A fresh connection per request guarantees the identity check always runs.
+      agent: false,
+    };
+    // Every TLS field falls back to the factory defaults (as anchors / minVersion already do), so a
+    // reusable transport built with pki.transport.https({ tls: { cert, key, servername } }) applies
+    // them to a request that carries no per-request tls (mTLS enrollment, a configured SNI).
+    var cert = reqTls.cert !== undefined ? reqTls.cert : tlsDefaults.cert;
+    var key = reqTls.key !== undefined ? reqTls.key : tlsDefaults.key;
+    var callerCsi = typeof reqTls.checkServerIdentity === "function" ? reqTls.checkServerIdentity
+      : (typeof tlsDefaults.checkServerIdentity === "function" ? tlsDefaults.checkServerIdentity : null);
+    // SNI (and RFC 6125 identity) uses a hostname; node forbids a servername that is an IP
+    // literal, so it is omitted for an IP host (node then matches the IP against the cert's
+    // IP SANs). A caller connecting by hostname gets SNI + name verification by default.
+    var sni = reqTls.servername || tlsDefaults.servername || host;
+    if (sni && !nodeNet.isIP(sni)) options.servername = sni;
+    // Build node's `ca`: the explicit anchors (DER wrapped as PEM) and, when useSystemStore is opted
+    // in, the OS system store + bundled roots. Node's `ca` REPLACES the default set, so both sources
+    // are merged here. Left unset only when no anchors and (on an older node) the system store is
+    // empty -- then node's default bundled store applies (the documented fallback).
+    var caList = [];
+    if (hasAnchors) caList = caList.concat(_pemifyAnchors(anchors));
+    if (useSystem) caList = caList.concat(_systemCa());
+    if (caList.length) options.ca = caList;
+    if (cert) options.cert = cert;
+    if (key) options.key = key;
+    // A caller checkServerIdentity may only TIGHTEN, never REPLACE, name verification: node uses a
+    // supplied callback in place of its default RFC 6125 check, so a hook that returns undefined
+    // (pinning/metrics only) would silently disable hostname verification. Run node's default first
+    // and reject on its verdict; the caller's hook adds checks only after the default has passed.
+    if (callerCsi) {
+      options.checkServerIdentity = function (host, cert2) {
+        var baseErr = nodeTls.checkServerIdentity(host, cert2);
+        if (baseErr) return baseErr;
+        return callerCsi(host, cert2);
+      };
+    }
+
+    return { options: options, timeout: timeout, maxBytes: maxBytes, body: body };
+  }
+
+  return function transport(request) {
+    request = request || {};
+    var prep;
+    try { prep = _prepare(request); }
+    catch (e) { return Promise.reject(e); }
+    return new Promise(function (resolve, reject) {
+      var settled = false;
+      var req;
+      var timer = null;
+      function clearTimer() { if (timer) { clearTimeout(timer); timer = null; } }
+      function fail(code, msg, cause) {
+        if (settled) return;
+        settled = true;
+        clearTimer();
+        // allow:swallow-unverified req.destroy() is idempotent and does not throw in practice; a
+        // raw throw from this best-effort abort would mask the real fail-closed verdict below.
+        try { if (req) req.destroy(); } catch (_e) { /* best-effort abort */ }
+        reject(E(code, msg, cause));
+      }
+      // An independent wall-clock deadline bounds DNS resolution and connection setup as well as
+      // socket inactivity: node's request/socket timeout does not run during a DNS lookup, so a
+      // stalled resolver would otherwise leave this promise pending forever despite a finite timeout.
+      timer = setTimeout(function () { fail(C("timeout"), "the request timed out after " + prep.timeout + "ms"); }, prep.timeout);
+      try {
+        req = nodeHttps.request(prep.options, function (res) {
+          // Capture the TLS session facts while the socket is live -- getProtocol() /
+          // getPeerCertificate() return null once the socket detaches at stream end.
+          var proto = res.socket && res.socket.getProtocol ? res.socket.getProtocol() : null;
+          var peer = res.socket && res.socket.getPeerCertificate ? res.socket.getPeerCertificate() : null;
+          // Pre-check a declared content-length so an oversized body is refused before it streams.
+          var declared = parseInt((res.headers || {})["content-length"], 10);
+          if (Number.isFinite(declared) && declared > prep.maxBytes) { fail(C("response-too-large"), "the declared content-length " + declared + " exceeds the " + prep.maxBytes + "-byte cap (RFC 7030 sec. 6)"); return; }
+          // Accumulate into a single doubling buffer rather than an array of chunks: a body sent as
+          // many tiny chunks (one-byte TLS records) would otherwise retain millions of Buffer objects
+          // under the byte cap and exhaust the heap. One live buffer bounds the metadata as well as the
+          // bytes; only the written prefix [0, len) is ever surfaced (the unwritten tail is never read).
+          var buf = Buffer.allocUnsafe(0);
+          var len = 0;
+          var total = 0;
+          res.on("data", function (chunk) {
+            total += chunk.length;
+            if (total > prep.maxBytes) { fail(C("response-too-large"), "the response exceeded the " + prep.maxBytes + "-byte cap (RFC 7030 sec. 6)"); return; }
+            if (len + chunk.length > buf.length) {
+              var want = Math.min(prep.maxBytes, Math.max(buf.length ? buf.length * 2 : 8192, len + chunk.length));
+              var grown = Buffer.allocUnsafe(want);
+              buf.copy(grown, 0, 0, len);
+              buf = grown;
+            }
+            chunk.copy(buf, len);
+            len += chunk.length;
+          });
+          res.on("end", function () {
+            if (settled) return;
+            settled = true;
+            clearTimer();
+            var lower = {};
+            Object.keys(res.headers || {}).forEach(function (k) { lower[k.toLowerCase()] = res.headers[k]; });
+            resolve({
+              status: res.statusCode,
+              headers: lower,
+              body: Buffer.from(buf.subarray(0, len)),
+              tls: { protocol: proto, peerCertificate: peer && peer.raw ? peer.raw : null },
+            });
+          });
+          res.on("error", function (e) { fail(C("transport-error"), "the response stream failed", e); });
+        });
+        req.on("error", function (e) { fail(_classifyError(e, C), "the request failed: " + ((e && e.message) || String(e)), e); });
+        // Write a provided body for ANY method (POST / PUT / PATCH / ...), not only POST, so a body
+        // is never silently dropped on a body-bearing request through this generic transport seam.
+        if (prep.body != null && prep.body !== "") req.write(prep.body);
+        req.end();
+      } catch (e) { fail(C("transport-error"), "the request could not be initiated: " + ((e && e.message) || String(e)), e); }
+    });
+  };
+}
+
+module.exports = { https: httpsTransport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:535d6fbb-3650-4575-9c45-a256806e58cf",
+  "serialNumber": "urn:uuid:d422e0bf-7707-4f70-8e04-0d467ade9599",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-24T11:36:26.019Z",
+    "timestamp": "2026-07-25T04:02:51.828Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.15",
+      "bom-ref": "@blamejs/pki@0.3.17",
       "type": "application",
       "name": "pki",
-      "version": "0.3.15",
+      "version": "0.3.17",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.3.15",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.15",
+      "ref": "@blamejs/pki@0.3.17",
       "dependsOn": []
     }
   ]