@blamejs/pki 0.3.15 → 0.3.18

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,8 @@ 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 retryAfter = require("./http-retry-after");
 
 var EstError = frameworkError.EstError;
 function E(code, message, cause) { return new EstError(code, message, cause); }
@@ -65,50 +77,6 @@ var OID_TEMPLATE = oid.byName("certificationRequestInfoTemplate");
 
 var OPERATIONS = ["cacerts", "simpleenroll", "simplereenroll", "fullcmc", "serverkeygen", "csrattrs"];
 
-// The largest Retry-After delay this classifier will surface as a number: a
-// generous one-year ceiling that keeps the value a safe integer and rejects an
-// overflowing / nonsensical delay-seconds fail-closed rather than returning it.
-var MAX_RETRY_AFTER_SECONDS = constants.TIME.days(365) / constants.TIME.seconds(1);
-
-// The three HTTP-date forms (RFC 7231 sec. 7.1.1.1): IMF-fixdate (the required
-// form), and the obsolete rfc850-date / asctime-date a recipient must still
-// accept. Gating Date.parse on this grammar keeps its permissiveness (an ISO
-// string like "2026-07-10") from passing as a valid Retry-After header.
-var _MONTHS = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
-var _MONTH = "(?:" + _MONTHS.join("|") + ")";
-var HTTP_DATE_FORMS = [
-  new RegExp("^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \\d{2} " + _MONTH + " \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$"),
-  new RegExp("^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), \\d{2}-" + _MONTH + "-\\d{2} \\d{2}:\\d{2}:\\d{2} GMT$"),
-  new RegExp("^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) " + _MONTH + " [ \\d]\\d \\d{2}:\\d{2}:\\d{2} \\d{4}$"),
-];
-
-// Parse an HTTP-date to epoch ms, or NaN when its grammar, calendar, or time is
-// invalid. Built from the extracted fields via Date.UTC (never Date.parse): every
-// HTTP-date is UTC -- the asctime form carries no GMT token, so delegating would
-// parse it in LOCAL time -- and the round-trip check rejects an impossible date /
-// time (Date.UTC normalizes Feb 31 -> Mar 2 just as Date.parse would).
-function _httpDateMs(s) {
-  if (!HTTP_DATE_FORMS.some(function (re) { return re.test(s); })) return NaN;
-  var day, monName, year;
-  var asc = /^\w{3} (\w{3}) ([ \d]\d) /.exec(s);                           // asctime: month then day
-  if (asc) { monName = asc[1]; day = parseInt(asc[2], 10); year = parseInt(/(\d{4})$/.exec(s)[1], 10); }
-  else {
-    var dmy = /(\d{2})[ -](\w{3})[ -](\d{2,4})/.exec(s);                   // IMF / rfc850: day month year
-    if (!dmy) return NaN;
-    day = parseInt(dmy[1], 10); monName = dmy[2]; year = parseInt(dmy[3], 10);
-    if (year < 100) year += (year < 70 ? 2000 : 1900);                    // rfc850 two-digit year
-  }
-  var t = /(\d{2}):(\d{2}):(\d{2})/.exec(s);
-  var mon = _MONTHS.indexOf(monName);
-  if (!t || mon < 0) return NaN;
-  var hh = parseInt(t[1], 10), mi = parseInt(t[2], 10), ss = parseInt(t[3], 10);
-  var when = Date.UTC(year, mon, day, hh, mi, ss);
-  var d = new Date(when);
-  if (d.getUTCDate() !== day || d.getUTCMonth() !== mon || d.getUTCFullYear() !== year ||
-      d.getUTCHours() !== hh || d.getUTCMinutes() !== mi || d.getUTCSeconds() !== ss) return NaN;
-  return when;
-}
-
 // ---- the RFC 8951 sec. 3/3.1 transfer codec (CTE-header-blind) -----------
 
 /**
@@ -498,31 +466,13 @@ 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
-    // as an absolute retryAfterDate (epoch ms) -- and, when the caller passes its
-    // receipt time as opts.now (epoch ms), also as a bounded retryAfterSeconds.
-    // Neither form -> fail closed rather than a retry verdict with no delay.
-    var out202 = { status: "retry", retryAfter: raStr, retryAfterSeconds: null, retryAfterDate: null };
-    if (/^\d+$/.test(raStr)) {
-      var n = parseInt(raStr, 10);
-      if (!Number.isSafeInteger(n) || n > MAX_RETRY_AFTER_SECONDS) throw E("est/bad-retry-after", "the 202 Retry-After delay is out of the supported range (0.." + MAX_RETRY_AFTER_SECONDS + " seconds)");
-      out202.retryAfterSeconds = n;
-    } else {
-      var when = _httpDateMs(raStr);
-      if (isNaN(when)) throw E("est/bad-retry-after", "a 202 Retry-After must be delay-seconds or a valid HTTP-date (RFC 7231 sec. 7.1.1.1/7.1.3), got " + JSON.stringify(raStr));
-      out202.retryAfterDate = when;
-      if (typeof opts.now === "number" && isFinite(opts.now)) {
-        var d = Math.max(0, Math.round((when - opts.now) / constants.TIME.seconds(1)));
-        // The same one-year ceiling the delay-seconds form enforces (a date far in
-        // the future would otherwise surface a huge numeric delay).
-        if (d > MAX_RETRY_AFTER_SECONDS) throw E("est/bad-retry-after", "the 202 Retry-After date is beyond the supported horizon (" + MAX_RETRY_AFTER_SECONDS + " seconds)");
-        out202.retryAfterSeconds = d;
-      }
-    }
-    return out202;
+    // Retry-After is delay-seconds OR an HTTP-date (RFC 7231 sec. 7.1.3), surfaced (never slept on)
+    // as a bounded retryAfterSeconds and/or an absolute retryAfterDate via the shared parser; neither
+    // form -> fail closed rather than a retry verdict with no delay.
+    var parsed = retryAfter.parse(raStr, { now: opts.now, E: E, code: "est/bad-retry-after" });
+    return { status: "retry", retryAfter: raStr, retryAfterSeconds: parsed.retryAfterSeconds, retryAfterDate: parsed.retryAfterDate };
   }
   if (status === 204 || status === 404) {
     if (op === "csrattrs") return { status: "none-available" };
@@ -708,7 +658,309 @@ 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 || {};
+      // Measure an injected string body as UTF-8 -- the byte width the body is decoded/transfer-decoded at,
+      // and what the real socket transport counts -- so a non-ASCII body (multi-byte chars are ~half the
+      // count under latin1) cannot undercount past the DoS cap and reach body handling.
+      var blen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "utf8");
+      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);
+  // Measure the body as UTF-8 for parity with the transport cap above (this check only distinguishes empty
+  // from non-empty, where the encoding is immaterial, but the shape is kept uniform so no site undercounts).
+  var bodyLen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "utf8");
+  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-retry-after.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- the shared HTTP Retry-After parser (RFC 7231 sec. 7.1.3): a delay-seconds count OR an
+// HTTP-date (sec. 7.1.1.1). The enrollment protocol clients (pki.est now, pki.acme next) all surface a
+// server's Retry-After as a bounded delay -- never sleeping on it in a single-step call -- so the
+// delay-seconds | HTTP-date grammar and the one-year ceiling live in ONE place both compose, error-
+// factory-parameterized so each domain keeps its own typed verdict. A malformed / overflowing value
+// fails closed (the caller's E(code, ...)); the value is never returned unparsed.
+
+var constants = require("./constants");
+
+// The largest delay this parser surfaces as a number: a generous one-year ceiling that keeps the
+// value a safe integer and rejects an overflowing / nonsensical delay-seconds or far-future date.
+var MAX_RETRY_AFTER_SECONDS = constants.TIME.days(365) / constants.TIME.seconds(1);
+
+// The three HTTP-date forms (RFC 7231 sec. 7.1.1.1): IMF-fixdate (the required form), and the obsolete
+// rfc850-date / asctime-date a recipient must still accept. Gating Date.parse on this grammar keeps its
+// permissiveness (an ISO string like "2026-07-10") from passing as a valid Retry-After header.
+var MONTHS = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+var MONTH = "(?:" + MONTHS.join("|") + ")";
+var HTTP_DATE_FORMS = [
+  new RegExp("^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \\d{2} " + MONTH + " \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$"),
+  new RegExp("^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), \\d{2}-" + MONTH + "-\\d{2} \\d{2}:\\d{2}:\\d{2} GMT$"),
+  new RegExp("^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) " + MONTH + " [ \\d]\\d \\d{2}:\\d{2}:\\d{2} \\d{4}$"),
+];
+
+// Expand an obsolete RFC 850 two-digit year: HTTP interprets it RELATIVE TO the receipt year -- the full
+// year with these two digits within [refYear-50, refYear+49] (moved to the past only when it would
+// otherwise be more than 50 years ahead). A fixed cutoff would misdate a year near the century boundary.
+// With no receipt time, fall back to the RFC 6265 fixed rule (< 70 -> 2000s, else 1900s).
+function _rfc850Year(yy, refMs) {
+  if (typeof refMs !== "number" || !isFinite(refMs)) return yy + (yy < 70 ? 2000 : 1900);
+  var refYear = new Date(refMs).getUTCFullYear();
+  var full = Math.floor(refYear / 100) * 100 + yy;
+  // Move to the PREVIOUS century ONLY when the same-century year would be more than 50 years ahead; never
+  // advance a past year to the future (an old two-digit year stays in the past).
+  if (full - refYear > 50) full -= 100;
+  return full;
+}
+
+// Parse an HTTP-date to epoch ms, or NaN when its grammar, calendar, or time is invalid. Built from the
+// extracted fields via Date.UTC (never Date.parse): every HTTP-date is UTC -- the asctime form carries
+// no GMT token, so delegating would parse it in LOCAL time -- and the round-trip check rejects an
+// impossible date / time (Date.UTC normalizes Feb 31 -> Mar 2 just as Date.parse would).
+function httpDateMs(s, refMs) {
+  if (!HTTP_DATE_FORMS.some(function (re) { return re.test(s); })) return NaN;
+  var day, monName, year;
+  var asc = /^\w{3} (\w{3}) ([ \d]\d) /.exec(s);                           // asctime: month then day
+  if (asc) { monName = asc[1]; day = parseInt(asc[2], 10); year = parseInt(/(\d{4})$/.exec(s)[1], 10); }
+  else {
+    var dmy = /(\d{2})[ -](\w{3})[ -](\d{2,4})/.exec(s);                   // IMF / rfc850: day month year
+    if (!dmy) return NaN;
+    day = parseInt(dmy[1], 10); monName = dmy[2]; year = parseInt(dmy[3], 10);
+    if (year < 100) year = _rfc850Year(year, refMs);                       // rfc850 two-digit year
+  }
+  var t = /(\d{2}):(\d{2}):(\d{2})/.exec(s);
+  var mon = MONTHS.indexOf(monName);
+  if (!t || mon < 0) return NaN;
+  var hh = parseInt(t[1], 10), mi = parseInt(t[2], 10), ss = parseInt(t[3], 10);
+  var when = Date.UTC(year, mon, day, hh, mi, ss);
+  var d = new Date(when);
+  if (d.getUTCDate() !== day || d.getUTCMonth() !== mon || d.getUTCFullYear() !== year ||
+      d.getUTCHours() !== hh || d.getUTCMinutes() !== mi || d.getUTCSeconds() !== ss) return NaN;
+  return when;
+}
+
+// parse(value, opts) -> { retryAfterSeconds, retryAfterDate }. A PRESENT Retry-After value (the caller
+// gates absence with its own code) is a delay-seconds integer -> retryAfterSeconds, or an HTTP-date ->
+// retryAfterDate (epoch ms) plus, when opts.now (epoch ms) is given, a bounded retryAfterSeconds. Either
+// form beyond the one-year ceiling, or a value that is neither, fails closed via opts.E(opts.code, ...).
+// Never slept on here -- the value is SURFACED for the caller to decide.
+function parse(value, opts) {
+  opts = opts || {};
+  var raStr = String(value).trim();
+  var out = { retryAfterSeconds: null, retryAfterDate: null };
+  if (/^\d+$/.test(raStr)) {
+    var n = parseInt(raStr, 10);
+    if (!Number.isSafeInteger(n) || n > MAX_RETRY_AFTER_SECONDS) throw _fail(opts, "the Retry-After delay is out of the supported range (0.." + MAX_RETRY_AFTER_SECONDS + " seconds)");
+    out.retryAfterSeconds = n;
+    return out;
+  }
+  var when = httpDateMs(raStr, opts.now);
+  if (isNaN(when)) throw _fail(opts, "a Retry-After must be delay-seconds or a valid HTTP-date (RFC 7231 sec. 7.1.1.1/7.1.3), got " + JSON.stringify(raStr));
+  out.retryAfterDate = when;
+  if (typeof opts.now === "number" && isFinite(opts.now)) {
+    // Round the remaining whole-second delay UP (a sub-second date must not retry before the requested
+    // time), clamping a past date to 0.
+    var d = Math.max(0, Math.ceil((when - opts.now) / constants.TIME.seconds(1)));
+    if (d > MAX_RETRY_AFTER_SECONDS) throw _fail(opts, "the Retry-After date is beyond the supported horizon (" + MAX_RETRY_AFTER_SECONDS + " seconds)");
+    out.retryAfterSeconds = d;
+  }
+  return out;
+}
+
+function _fail(opts, message) {
+  return typeof opts.E === "function" ? opts.E(opts.code, message) : new TypeError(message);
+}
+
+module.exports = { MAX_RETRY_AFTER_SECONDS: MAX_RETRY_AFTER_SECONDS, httpDateMs: httpDateMs, parse: parse };