@blamejs/pki 0.3.17 → 0.3.19

package/lib/acme.js

@@ -44,6 +44,10 @@ var constants = require("./constants");
 var rfc3339 = require("./rfc3339");
 var subtle = require("./webcrypto").webcrypto.subtle;
 var frameworkError = require("./framework-error");
+var httpTransport = require("./http-transport");
+var retryAfter = require("./http-retry-after");
+var guard = require("./guard-all");
+var pkgVersion = require("../package.json").version;
 
 var AcmeError = frameworkError.AcmeError;
 function E(code, message, cause) { return new AcmeError(code, message, cause); }
@@ -302,7 +306,7 @@ function _canonicalizeIpv6(value) {
 // illegal server transition the client fails closed on (acme/bad-transition).
 var TRANSITIONS = {
   challenge:     { pending: ["processing", "valid", "invalid"], processing: ["processing", "valid", "invalid"] },
-  authorization: { pending: ["valid", "invalid"], valid: ["expired", "deactivated", "revoked"] },
+  authorization: { pending: ["valid", "invalid", "deactivated"], valid: ["expired", "deactivated", "revoked"] },
   order:         { pending: ["ready", "invalid"], ready: ["processing", "valid", "invalid"], processing: ["valid", "invalid"] },
 };
 
@@ -1118,7 +1122,513 @@ function validateRenewalInfo(obj) {
   return obj;
 }
 
+// ---- the thin RFC 8555 client: a stateful session over the shared pki.transport ----
+
+var CLIENT_DEFAULT_TIMEOUT = constants.TIME.seconds(30);
+var CLIENT_MAX_TIMEOUT = constants.TIME.seconds(600);
+// The RFC 8555 sec. 6.1 REQUIRED User-Agent, sent on every request (caller-overridable per request).
+var CLIENT_USER_AGENT = "blamejs-pki/" + pkgVersion + " node/" + process.versions.node;
+// A hard cap on the single-use nonce pool so a server that attaches a Replay-Nonce to every response
+// (permitted, RFC 8555 sec. 6.5) -- including the unauthenticated, poll-scheduled renewalInfo GET --
+// cannot grow it without bound; the oldest (least fresh) nonce is evicted first (CWE-770).
+var CLIENT_MAX_NONCE_POOL = 32;
+
+// Parse + validate a URL BEFORE any request: not-parseable -> acme/bad-url, non-https -> acme/insecure-url
+// (RFC 8555 sec. 6.1 -- HTTPS is REQUIRED; the message-layer _isUrl accepts http, the client does not).
+// The validated string is returned VERBATIM (never url.href): the JWS protected `url` and the account
+// `kid` must be the exact server-provided value (RFC 8555 sec. 6.4/7.3), which URL normalization -- a
+// dropped :443, an added trailing slash -- would otherwise change, breaking the server's match.
+function _clientUrl(urlStr) {
+  var s = String(urlStr);
+  var url;
+  try { url = new URL(s); }
+  catch (e) { throw E("acme/bad-url", "the ACME URL did not parse: " + s, e); }
+  if (url.protocol !== "https:") throw E("acme/insecure-url", "ACME requires https (RFC 8555 sec. 6.1), got " + url.protocol + " for " + s);
+  // Reject a spelling the transport would REPAIR into a different path -- whitespace (WHATWG percent-
+  // encodes or trims it) or a backslash (rewritten to `/`). The transport re-parses the URL to the
+  // normalized path while the JWS `url` keeps the original, so the signed and requested URLs would differ.
+  if (/[\s\\]/.test(s)) throw E("acme/bad-url", "an ACME URL must not contain whitespace or a backslash: " + JSON.stringify(s));
+  // Reject any path the transport would NORMALIZE differently -- literal OR percent-encoded dot-segments
+  // (`/..`, `/%2e%2e/`), or an authority-only URL with NO path (`https://ca.example`, where the transport
+  // inserts a `/`) -- by comparing the raw path in `s` to the WHATWG-parsed pathname the transport sends as
+  // the request target; a mismatch means the signed JWS `url` would keep a path the request never used. The
+  // empty raw path is deliberately NOT coerced to `/`: that coercion would mask the authority-only case,
+  // whose verbatim `s` (no slash) differs from the `/` the transport requests. (The authority may still
+  // normalize -- a default :443 port, an uppercase host -- as that does not change the path; an encoded char
+  // like `%41` or a dot inside a segment name round-trips unchanged.)
+  var rawPath = s.replace(/^[a-z]+:\/\/[^/?#]*/i, "").split(/[?#]/)[0];
+  if (rawPath !== url.pathname) throw E("acme/bad-url", "an ACME URL path is not canonical (the transport would normalize it): " + JSON.stringify(s));
+  // Reject a fragment: the transport builds the request target from pathname+search only, so a `#frag`
+  // would sign a JWS `url` (sec. 6.4) that differs from the URL actually requested, failing at the CA.
+  if (url.hash) throw E("acme/bad-url", "an ACME URL must not contain a fragment: " + JSON.stringify(s));
+  // Return the value VERBATIM (the server's exact spelling for the sec. 6.4/7.3 JWS match) -- a conforming
+  // CA may emit a form WHATWG would normalize (a default :443 port, an uppercase host); the transport
+  // re-parses it for the connection, so such a URL is honored rather than rejected as non-canonical.
+  return s;
+}
+// Turn a server `Location` (which MAY be a relative URI-reference -- valid HTTP, common behind a proxy)
+// into the account/order URL: an absolute Location is used verbatim, a relative one is resolved against
+// the request URL, and the result is https-gated. A caller URL uses _clientUrl directly.
+function _resolveLocation(loc, base) {
+  // An ABSOLUTE Location is used VERBATIM (its exact spelling -- an uppercase host, an explicit :443 --
+  // for the sec. 6.4/7.3 JWS match, via _clientUrl). Only a RELATIVE reference is resolved against the
+  // request URL first (the resolved href is then https-gated).
+  var isAbsolute = true;
+  try { new URL(loc); }
+  catch (_e) { isAbsolute = false; }
+  if (isAbsolute) return _clientUrl(loc);
+  var abs;
+  try { abs = new URL(loc, base).href; }
+  catch (e) { throw E("acme/bad-url", "the Location header did not resolve to a valid URL: " + JSON.stringify(loc), e); }
+  return _clientUrl(abs);
+}
+// The default poll sleeper: SPLITS a delay above Node's 32-bit setTimeout ceiling into chained chunks, so
+// a large (but parser-bounded, up to a year) Retry-After is actually honored -- a single oversized
+// setTimeout is silently clamped to 1 ms (TimeoutOverflowWarning), which would rapidly re-poll instead.
+var SETTIMEOUT_MAX_MS = 2147483647;
+function _defaultSleep(ms) {
+  return new Promise(function (resolve) {
+    (function step(remaining) {
+      if (remaining <= SETTIMEOUT_MAX_MS) { setTimeout(resolve, remaining); return; }
+      setTimeout(function () { step(remaining - SETTIMEOUT_MAX_MS); }, SETTIMEOUT_MAX_MS);
+    })(ms);
+  });
+}
+function _clientTls(o) {
+  var t = o.tls || {};
+  return { anchors: t.anchors, useSystemStore: t.useSystemStore, cert: t.cert, key: t.key, minVersion: t.minVersion, servername: t.servername, checkServerIdentity: t.checkServerIdentity };
+}
+// Split a PEM certificate chain (RFC 8555 sec. 7.4.2 application/pem-certificate-chain) into its DER certs.
+function _splitPemChain(text) {
+  var out = [];
+  var re = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+  var m;
+  var lastEnd = 0;
+  while ((m = re.exec(text)) !== null) {
+    // application/pem-certificate-chain is ONLY PEM blocks separated by whitespace (RFC 8555 sec. 7.4.2) --
+    // no explanatory text before, between, or after; reject any non-whitespace outside a block.
+    if (text.slice(lastEnd, m.index).trim() !== "") throw E("acme/bad-certificate-chain", "the certificate chain contained non-whitespace text outside a PEM block (RFC 8555 sec. 7.4.2)");
+    var der;
+    // Decode the armor AND structurally parse it: valid PEM armor can wrap arbitrary base64, so without
+    // the strict X.509 parse the download could return non-certificate bytes as the issued certificate.
+    try { der = x509.pemDecode(m[0], "CERTIFICATE"); x509.parse(der); }
+    catch (e) { throw E("acme/bad-certificate-chain", "a downloaded certificate did not decode as a valid X.509 certificate (RFC 8555 sec. 7.4.2)", e); }
+    out.push(der);
+    lastEnd = re.lastIndex;
+  }
+  if (text.slice(lastEnd).trim() !== "") throw E("acme/bad-certificate-chain", "the certificate chain contained trailing non-whitespace text outside a PEM block (RFC 8555 sec. 7.4.2)");
+  if (!out.length) throw E("acme/bad-certificate-chain", "the certificate download carried no PEM certificate (RFC 8555 sec. 7.4.2)");
+  return out;
+}
+
+/**
+ * @primitive  pki.acme.client
+ * @signature  pki.acme.client(directoryUrl, opts) -> client
+ * @since      0.3.18
+ * @status     experimental
+ * @spec       RFC 8555, RFC 8737, RFC 8738, RFC 9773
+ * @related    pki.acme.newOrder, pki.transport.https
+ *
+ * A stateful RFC 8555 ACME client that drives the live directory flow over the shared `pki.transport`
+ * (inject `opts.transport`, else a fail-closed `pki.transport.https`). It composes the shipped message
+ * layer (the JWS builders + object validators + state machines) and owns only session state -- the
+ * fetched directory, the single-use nonce pool (a fresh anti-replay nonce per JWS, badNonce bounded-
+ * retried with the error's Replay-Nonce), and the account URL captured as the `kid`. `opts.accountKey`
+ * (a private CryptoKey) + `opts.accountJwk` (its public JWK) + `opts.alg` sign every request. Every
+ * request is https-only (`acme/insecure-url`); reads are POST-as-GET; a problem+json response is a
+ * typed `acme/server-problem`; a poll sleeps on a bounded Retry-After via an injectable sleeper and is
+ * capped by a poll count and a total-wait budget. Returns a client
+ * object: `directory`, `newAccount`, `newOrder`, `getOrder` / `getAuthorization` / `getChallenge`,
+ * `respondToChallenge`, `finalize`, `pollOrder` / `pollAuthorization`, `downloadCertificate`,
+ * `revokeCert`, `deactivateAccount` / `deactivateAuthorization`, `keyChange`, `renewalInfo`.
+ *
+ * @opts
+ *   - `accountKey` / `accountJwk` / `alg` -- REQUIRED: the account private key, its public JWK, and the JWS alg.
+ *   - `transport` -- injectable transport(request) -> {status, headers, body}; default pki.transport.https.
+ *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity } for the default transport.
+ *   - `timeout` / `maxResponseBytes` / `maxRedirects` -- transport budgets; `maxNonceRetries` -- badNonce retry cap (default 1).
+ *   - `maxPolls` / `maxTotalWait` / `sleep` -- poll-loop budgets + an injectable sleeper; `clock` -- an injectable receipt clock (default Date.now) for a Retry-After HTTP-date.
+ * @example
+ *   var acme = pki.acme.client("https://acme.example/directory", { accountKey, accountJwk, alg: "ES256", transport });
+ *   var acct = await acme.newAccount({ termsOfServiceAgreed: true });
+ *   var ord = await acme.newOrder({ identifiers: [{ type: "dns", value: "example.org" }] });
+ */
+function client(directoryUrl, opts) {
+  opts = opts || {};
+  if (!opts.accountKey) throw E("acme/bad-input", "client requires opts.accountKey (the account private key)");
+  if (!_isObject(opts.accountJwk)) throw E("acme/bad-input", "client requires opts.accountJwk (the account public JWK)");
+  if (!_isString(opts.alg)) throw E("acme/bad-input", "client requires opts.alg (the account-key JWS alg)");
+  jose.assertPublicJwk(opts.accountJwk);
+  var dirUrl = _clientUrl(directoryUrl);
+  var accountKey = opts.accountKey, accountJwk = opts.accountJwk, alg = opts.alg;
+
+  var transport = opts.transport;
+  if (!transport) {
+    var t0 = opts.tls || {};
+    var hasAnchors = t0.anchors !== undefined && t0.anchors !== null && !(Array.isArray(t0.anchors) && t0.anchors.length === 0);
+    if (!hasAnchors && t0.useSystemStore !== true) throw E("acme/no-trust-anchors", "no explicit trust anchor and tls.useSystemStore not set to true (RFC 8555 sec. 6.1)");
+    transport = httpTransport.https({ E: E, errPrefix: "acme" });
+  }
+  var budgets = {
+    tls: _clientTls(opts),
+    timeout: guard.limits.cap(opts.timeout, "timeout", CLIENT_DEFAULT_TIMEOUT, { E: E, code: "acme/bad-input", min: 1, max: CLIENT_MAX_TIMEOUT }),
+    maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "acme/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
+    maxRedirects: guard.limits.cap(opts.maxRedirects, "maxRedirects", 5, { E: E, code: "acme/bad-input", min: 0, max: 32 }),
+  };
+  var maxNonceRetries = guard.limits.cap(opts.maxNonceRetries, "maxNonceRetries", 1, { E: E, code: "acme/bad-input", min: 0, max: 8 });
+  var maxPolls = guard.limits.cap(opts.maxPolls, "maxPolls", 20, { E: E, code: "acme/bad-input", min: 1, max: 1000 });
+  var maxTotalWait = guard.limits.cap(opts.maxTotalWait, "maxTotalWait", retryAfter.MAX_RETRY_AFTER_SECONDS, { E: E, code: "acme/bad-input", min: 0, max: retryAfter.MAX_RETRY_AFTER_SECONDS });
+  var sleep = typeof opts.sleep === "function" ? opts.sleep : _defaultSleep;
+  // The receipt clock for a Retry-After HTTP-date: read FRESH per response (a fixed value would go stale
+  // across polls, and a missing one would collapse every HTTP-date to a 1s delay). Injectable for tests.
+  var clock = typeof opts.clock === "function" ? opts.clock : function () { return Date.now(); };
+
+  // session state
+  var dirCache = null;
+  var nonces = [];
+  var kid = null;
+  // The mTLS client credential is bound to the CONFIGURED directory origin: it is presented ONLY to that
+  // origin, never to a different one reached via a redirect or advertised by a (possibly compromised)
+  // directory. A CA that legitimately spans origins uses JWS auth, not a transport client certificate.
+  var trustedOrigin = new URL(dirUrl).origin;
+  function _tlsFor(url) {
+    var t = budgets.tls;
+    // Cross-origin, strip the ORIGIN-SPECIFIC identity: the client certificate/key (credential leak) AND
+    // the pinned `servername` / `checkServerIdentity` (they drive SNI + RFC 6125 verification for the
+    // trusted host, so applying them to another origin authenticates against the wrong identity).
+    if (new URL(url).origin !== trustedOrigin && (t.cert != null || t.key != null || t.servername != null || t.checkServerIdentity != null)) {
+      t = Object.assign({}, t);
+      delete t.cert; delete t.key; delete t.servername; delete t.checkServerIdentity;
+    }
+    return t;
+  }
+
+  function _bodyText(res) { return Buffer.isBuffer(res.body) ? res.body.toString("utf8") : String(res.body || ""); }
+  // The RAW bytes for jose.parseJson, so its FATAL UTF-8 validation runs on the wire body -- _bodyText's
+  // lossy utf8 decode (replacement chars) would let a malformed RFC 8259 response slip through. A string
+  // body (an injected test transport) carries no malformed UTF-8, so encoding it is lossless.
+  function _jsonInput(res) { return Buffer.isBuffer(res.body) ? res.body : Buffer.from(String(res.body == null ? "" : res.body), "utf8"); }
+  function _requireKid() { if (!kid) throw E("acme/no-account", "no account is set -- call newAccount before an authenticated request (RFC 8555 sec. 6.2)"); return kid; }
+  function _harvestNonce(v) {
+    if (typeof v !== "string" || v === "") return;
+    try { jose.base64url.decode(v); }
+    catch (_e) { return; }   // ignore an invalid Replay-Nonce (RFC 8555 sec. 6.5.1)
+    while (nonces.length >= CLIENT_MAX_NONCE_POOL) nonces.shift();   // evict the oldest, bound the pool (CWE-770)
+    nonces.push(v);
+  }
+  function _isProblem(res) { return /application\/problem\+json/i.test(String(res.headers["content-type"] || "")); }
+  function _serverProblem(res) {
+    var prob = null;
+    try { prob = jose.parseJson(_jsonInput(res)); if (_isObject(prob)) validateProblem(prob); }
+    catch (_e) { /* allow:swallow-unverified an unparseable / schema-invalid problem doc; the typed acme/server-problem is surfaced from the HTTP status regardless */ }
+    var type = (prob && prob.type) || "", detail = (prob && prob.detail) || "";
+    var err = E("acme/server-problem", "the ACME server returned a problem (HTTP " + res.status + ")" + (type ? " " + type : "") + (detail ? ": " + detail : ""));
+    err.problem = prob; err.httpStatus = res.status;
+    return err;
+  }
+  function _json(res) {
+    try { return jose.parseJson(_jsonInput(res)); }
+    catch (e) { throw E("acme/bad-response", "the response body was not valid JSON: " + ((e && e.message) || String(e)), e); }
+  }
+
+  // One request over the transport; lowercases headers, caps the body, harvests a Replay-Nonce off every
+  // FINAL response (validated base64url, RFC 8555 sec. 6.5.1). A redirect on a SAFE method (GET/HEAD --
+  // the unauthenticated directory / newNonce / renewalInfo reads) is followed to its https Location, up to
+  // the maxRedirects budget; an authenticated POST is bound to its JWS `url` (sec. 6.4), so its redirect
+  // is surfaced unchanged for the verb to reject. Every request carries the sec. 6.1 REQUIRED User-Agent.
+  function _send(method, url, headers, body) { return _sendFollowing(method, url, headers, body, 0); }
+  function _sendFollowing(method, url, headers, body, redirects) {
+    var reqHeaders = Object.assign({ "user-agent": CLIENT_USER_AGENT }, headers || {});
+    // _tlsFor binds the mTLS credential to the trusted origin, so EVERY request (this one, a redirect
+    // target, or a directory-advertised URL on another host) presents the client certificate only there.
+    return transport({ method: method, url: url, headers: reqHeaders, body: body, tls: _tlsFor(url), timeout: budgets.timeout, maxResponseBytes: budgets.maxResponseBytes }).then(function (res) {
+      res = res || {};
+      var h = {};
+      Object.keys(res.headers || {}).forEach(function (k) { h[k.toLowerCase()] = res.headers[k]; });
+      // Measure an injected string body as UTF-8 -- the exact bytes _jsonInput re-encodes it to before the
+      // decoder sees it -- so a non-ASCII body (e.g. multi-byte emoji, ~half the byte count under latin1)
+      // cannot slip past the cap and reach the JSON parser.
+      var blen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "utf8");
+      if (blen > budgets.maxResponseBytes) throw E("acme/response-too-large", "the response body (" + blen + " bytes) exceeds the " + budgets.maxResponseBytes + "-byte cap");
+      if ((method === "GET" || method === "HEAD") && res.status >= 300 && res.status < 400) {
+        if (redirects >= budgets.maxRedirects) throw E("acme/too-many-redirects", "the redirect budget of " + budgets.maxRedirects + " was exceeded");
+        if (!_isString(h["location"])) throw E("acme/bad-redirect", "a " + res.status + " redirect carried no Location header (RFC 7231 sec. 6.4)");
+        // A Location may be relative (common behind a reverse proxy) -- resolve it against the request URL
+        // before the https gate, so `/v2/directory` follows rather than failing the URL parse.
+        var next;
+        try { next = new URL(h["location"], url).href; }
+        catch (e) { throw E("acme/bad-redirect", "the redirect Location did not resolve to a valid URL", e); }
+        return _sendFollowing(method, _clientUrl(next), headers, body, redirects + 1);
+      }
+      _harvestNonce(h["replay-nonce"]);
+      return { status: res.status, headers: h, body: res.body == null ? "" : res.body };
+    });
+  }
+
+  function _getDirectory() {
+    if (dirCache) return Promise.resolve(dirCache);
+    return _send("GET", dirUrl, { accept: "application/json" }, null).then(function (res) {
+      if (res.status !== 200) throw E("acme/bad-directory", "the ACME directory request returned HTTP " + res.status);
+      var obj = _json(res);
+      validate("directory", obj);
+      dirCache = obj;
+      return obj;
+    });
+  }
+  function _resource(name) {
+    return _getDirectory().then(function (dir) {
+      if (!_isString(dir[name])) throw E("acme/resource-unavailable", "the directory does not advertise the '" + name + "' resource (RFC 8555 sec. 7.1.1)");
+      return _clientUrl(dir[name]);   // the client is the sole https gate -- a directory advertising an http resource fails closed (RFC 8555 sec. 6.1)
+    });
+  }
+  // Take the FRESHEST pooled nonce (LIFO): every response's Replay-Nonce is appended, so on a badNonce
+  // the error response's fresh nonce is the last harvested and is the one the retry consumes (RFC 8555
+  // sec. 6.5) -- never a staler pooled nonce (e.g. one an unauthenticated read left behind).
+  function _takeNonce() {
+    if (nonces.length) return Promise.resolve(nonces.pop());
+    var before = nonces.length;
+    return _resource("newNonce").then(function (nn) { return _send("HEAD", nn, {}, null); }).then(function (res) {
+      // newNonce must succeed (RFC 8555 sec. 7.2: 200/204). An ERROR response (a 4xx/5xx rate limit) also
+      // carries a Replay-Nonce, but using it would silently proceed past the server's error -- discard the
+      // harvested nonce and surface the problem instead.
+      if (res.status !== 200 && res.status !== 204) { nonces.length = before; throw _serverProblem(res); }
+      if (!nonces.length) throw E("acme/no-nonce", "the server did not provide a usable Replay-Nonce (RFC 8555 sec. 7.2)");
+      return nonces.pop();
+    });
+  }
+
+  // POST a JWS built by makeJws(nonce) as application/jose+json, and on a badNonce error retry (bounded)
+  // with the error response's fresh nonce (RFC 8555 sec. 6.5 -- _takeNonce's LIFO pool surfaces it).
+  // `accept` is the media type the request advertises (default application/json). This is the single
+  // home of the badNonce retry, so every signed POST -- account-key or certificate-key -- inherits it.
+  function _postJws(url, makeJws, accept, okStatuses) {
+    var ok = okStatuses || [200];
+    var attempt = 0;
+    function once() {
+      return _takeNonce().then(makeJws).then(function (jws) {
+        return _send("POST", url, { "content-type": "application/jose+json", "accept": accept || "application/json" }, JSON.stringify(jws));
+      }).then(function (res) {
+        // An application/problem+json body is an ERROR regardless of the HTTP status -- a CA / proxy
+        // returning a problem with an erroneous 2xx must NOT be accepted as success (RFC 7807 / RFC 8555).
+        if (res.status >= 300 || _isProblem(res)) {
+          if (_isProblem(res)) {
+            var prob = null;
+            try { prob = jose.parseJson(_jsonInput(res)); }
+            catch (_e) { /* allow:swallow-unverified a non-JSON problem body is not a badNonce; prob stays null, falling through to the typed acme/server-problem throw */ }
+            if (prob && typeof prob.type === "string" && /:badNonce$/.test(prob.type) && attempt < maxNonceRetries) { attempt++; return once(); }
+          }
+          throw _serverProblem(res);
+        }
+        // Enforce the PER-OPERATION success status (RFC 8555): only newAccount/newOrder may return 201
+        // (created); every other verb requires 200, so a verb never acts on an incomplete result -- e.g.
+        // keyChange rotating the session key or revokeCert reporting success on a 201/202.
+        if (ok.indexOf(res.status) === -1) throw E("acme/unexpected-status", "an ACME POST returned an unexpected status " + res.status + " (expected " + ok.join("/") + ", RFC 8555)");
+        return res;
+      });
+    }
+    return once();
+  }
+  // Build an account-key JWS (kid or jwk mode) with a fresh nonce and POST it through the retrying _postJws.
+  function _post(url, builder, extra, mode, accept, okStatuses) {
+    return _postJws(url, function (nonce) {
+      // The client-owned JWS session fields (signing key, alg, single-use nonce, protected url) are applied
+      // AFTER the caller's payload options, so a payload carrying key/alg/nonce/url cannot override them and
+      // desynchronize the protected header from the actual request (or reuse a nonce).
+      var base = Object.assign({}, extra || {}, { key: accountKey, alg: alg, nonce: nonce, url: url });
+      if (mode === "jwk") base.jwk = accountJwk; else base.kid = _requireKid();
+      return builder(base);
+    }, accept, okStatuses);
+  }
+  function _postAsGet(url) { return _post(url, postAsGet, null, "kid"); }
+
+  // ---- verbs (internal _-prefixed to avoid shadowing the module builders) ----
+  function _directory() { return _getDirectory(); }
+
+  function _newAccount(payloadOpts) {
+    return _resource("newAccount").then(function (url) {
+      // newAccount is 201 (created) for a new account or 200 for an existing one (RFC 8555 sec. 7.3).
+      return _post(url, newAccount, payloadOpts || {}, "jwk", undefined, [200, 201]).then(function (res) {
+        var loc = res.headers["location"];
+        if (!_isString(loc)) throw E("acme/no-account-url", "newAccount did not return an account URL in a Location header (RFC 8555 sec. 7.3)");
+        // Validate the account object BEFORE committing the kid, so a malformed account (no status,
+        // an unknown status) fails closed rather than enabling authenticated operations under a bad kid.
+        var account = validate("account", _json(res));
+        kid = _resolveLocation(loc, url);
+        return { account: account, url: kid };
+      });
+    });
+  }
+  function _newOrder(payloadOpts) {
+    return _resource("newOrder").then(function (url) {
+      // newOrder returns 201 Created ONLY (RFC 8555 sec. 7.4) -- a 200 is a non-conforming server / proxy.
+      return _post(url, newOrder, payloadOpts || {}, "kid", undefined, [201]).then(function (res) {
+        var loc = res.headers["location"];
+        if (!_isString(loc)) throw E("acme/no-order-url", "newOrder did not return an order URL in a Location header (RFC 8555 sec. 7.4)");
+        return { order: validate("order", _json(res)), url: _resolveLocation(loc, url) };
+      });
+    });
+  }
+  function _getOrder(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("order", _json(res)); }); }
+  function _getAuthorization(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("authorization", _json(res)); }); }
+  function _getChallenge(url) { return _postAsGet(_clientUrl(url)).then(function (res) { return validate("challenge", _json(res)); }); }
+  function _respondToChallenge(url) { return _post(_clientUrl(url), challengeResponse, null, "kid").then(function (res) { return validate("challenge", _json(res)); }); }
+
+  function _finalize(order, o) {
+    o = o || {};
+    if (!_isObject(order) || !_isString(order.finalize)) throw E("acme/bad-input", "finalize requires the order object with its finalize URL");
+    if (!Array.isArray(order.identifiers)) throw E("acme/bad-input", "finalize requires the order's identifiers to enforce the RFC 8555 sec. 7.4 CSR-set match");
+    // The sec. 7.4 CSR-vs-order check is ALWAYS bound to the order's OWN authoritative identifiers (the
+    // client holds the validated order) -- never a caller-supplied set, which could otherwise loosen the
+    // check so a CSR matching the replacement passes locally only to be rejected by the CA.
+    return _post(_clientUrl(order.finalize), finalize, { csr: o.csr, identifiers: order.identifiers, accountJwk: accountJwk }, "kid").then(function (res) { return validate("order", _json(res)); });
+  }
+
+  // Poll a resource by POST-as-GET until it reaches a terminal state, honoring Retry-After (surfaced +
+  // slept via the injectable sleep), bounded by maxPolls + maxTotalWait; each observed pair runs
+  // assertTransition. A terminal `invalid` surfaces the object (the caller inspects .status).
+  function _poll(kind, url, budget) {
+    budget = budget || {};
+    // A per-call poll override is validated through the SAME bounds as the constructor budget, so an
+    // Infinity / NaN / over-ceiling value cannot turn a non-terminal resource into an unbounded loop.
+    // Surface a bad override (or url) as a REJECTION, not a sync throw, so this async verb is uniform.
+    var capPolls, capWait;
+    try {
+      capPolls = budget.maxPolls != null ? guard.limits.cap(budget.maxPolls, "maxPolls", maxPolls, { E: E, code: "acme/bad-input", min: 1, max: 1000 }) : maxPolls;
+      capWait = budget.maxTotalWait != null ? guard.limits.cap(budget.maxTotalWait, "maxTotalWait", maxTotalWait, { E: E, code: "acme/bad-input", min: 0, max: retryAfter.MAX_RETRY_AFTER_SECONDS }) : maxTotalWait;
+      url = _clientUrl(url);
+    } catch (e) { return Promise.reject(e); }
+    // An order poll terminates on every STABLE state (RFC 8555 sec. 7.1.6): `ready` (all authorizations
+    // met -- the signal to finalize) and `valid` / `invalid`, not just valid/invalid -- otherwise a poll
+    // run before finalize spins on the stable `ready` until the budget is exhausted.
+    var terminal = kind === "order" ? { ready: true, valid: true, invalid: true } : { valid: true, invalid: true, deactivated: true, expired: true, revoked: true };
+    var last = null, count = 0, waited = 0;
+    function step() {
+      count++;
+      return _postAsGet(url).then(function (res) {
+        var obj = validate(kind, _json(res));
+        if (last && last !== obj.status) assertTransition(kind, last, obj.status);
+        last = obj.status;
+        if (terminal[obj.status]) return obj;
+        if (count >= capPolls) throw E("acme/poll-exhausted", "the " + kind + " did not reach a terminal state within " + capPolls + " polls (RFC 8555 sec. 7.5.1)");
+        var ra = res.headers["retry-after"];
+        var delaySec = 1;
+        if (typeof ra === "string" && ra.trim() !== "") { delaySec = retryAfter.parse(ra, { now: clock(), E: E, code: "acme/bad-retry-after" }).retryAfterSeconds; if (delaySec == null) delaySec = 1; }
+        waited += delaySec;
+        if (waited > capWait) throw E("acme/poll-exhausted", "the " + kind + " poll exceeded the total wait budget of " + capWait + " seconds");
+        if (typeof budget.onRetryAfter === "function") budget.onRetryAfter(delaySec);
+        return Promise.resolve(sleep(delaySec * constants.TIME.seconds(1))).then(step);
+      });
+    }
+    return step();
+  }
+  function _pollOrder(url, budget) { return _poll("order", url, budget); }
+  function _pollAuthorization(url, budget) { return _poll("authorization", url, budget); }
+
+  function _downloadCertificate(url) {
+    return _post(_clientUrl(url), postAsGet, null, "kid", "application/pem-certificate-chain").then(function (res) {
+      if (res.status !== 200) throw _serverProblem(res);
+      // The certificate representation is bound to application/pem-certificate-chain (RFC 8555 sec. 7.4.2):
+      // a 200 with a wrong media type (a proxy error, a misrouted response) fails closed even if its body
+      // happens to contain parseable PEM. Match the media-type TOKEN exactly (before any ;-parameters), so
+      // a lookalike like application/pem-certificate-chain-evil does not slip through a substring test.
+      var ctToken = String(res.headers["content-type"] || "").split(";")[0].trim().toLowerCase();
+      if (ctToken !== "application/pem-certificate-chain") throw E("acme/bad-certificate-chain", "the certificate download returned an unexpected media type " + JSON.stringify(ctToken) + " (expected application/pem-certificate-chain, RFC 8555 sec. 7.4.2)");
+      var chain = _splitPemChain(_bodyText(res));
+      return { certificate: chain[0], chain: chain.slice(1), certificates: chain, alternates: [] };
+    });
+  }
+
+  function _revokeCert(o) {
+    o = o || {};
+    // Surface bad input as a REJECTION (not a sync throw) so this async verb is uniform for a .catch caller.
+    if (!Buffer.isBuffer(o.certificate)) return Promise.reject(E("acme/bad-input", "revokeCert requires a DER certificate Buffer (opts.certificate)"));
+    // Certificate-key mode (RFC 8555 sec. 7.6) needs the COMPLETE triple certKey + certJwk + certAlg: an
+    // incomplete set must NOT fall through to the account-key path (wrong credential), and certAlg must be
+    // explicit -- inheriting the account alg would sign a different-family certificate key under the wrong
+    // JWS algorithm (an ES256 account revoking with an RSA certificate key), which JOSE then rejects.
+    var certKeyMode = o.certKey != null || _isObject(o.certJwk) || o.certAlg != null;
+    if (certKeyMode && !(o.certKey != null && _isObject(o.certJwk) && _isString(o.certAlg))) return Promise.reject(E("acme/bad-input", "revokeCert certificate-key mode requires certKey, certJwk, AND certAlg together, or none (RFC 8555 sec. 7.6)"));
+    var extra = { certificate: o.certificate };
+    if (o.reason !== undefined) extra.reason = o.reason;
+    return _resource("revokeCert").then(function (url) {
+      if (certKeyMode) {
+        // sign with the certificate key (jwk mode) rather than the account (RFC 8555 sec. 7.6), through
+        // the same _postJws so it inherits the badNonce bounded retry the kid path has.
+        return _postJws(url, function (nonce) {
+          return revokeCert(Object.assign({}, extra, { key: o.certKey, alg: o.certAlg, nonce: nonce, url: url, jwk: o.certJwk }));
+        }).then(function () { return true; });
+      }
+      return _post(url, revokeCert, extra, "kid").then(function () { return true; });
+    });
+  }
+
+  function _deactivateAccount() { return _post(_requireKid(), deactivate, null, "kid").then(function (res) { return validate("account", _json(res)); }); }
+  function _deactivateAuthorization(url) { return _post(_clientUrl(url), deactivate, null, "kid").then(function (res) { return validate("authorization", _json(res)); }); }
+
+  function _keyChange(o) {
+    o = o || {};
+    if (!o.newKey || !_isObject(o.newJwk) || !_isString(o.newAlg)) throw E("acme/bad-input", "keyChange requires newKey, newJwk, and newAlg");
+    var account = _requireKid();
+    return _resource("keyChange").then(function (url) {
+      return _post(url, keyChange, { account: account, oldKey: accountJwk, newKey: o.newKey, newJwk: o.newJwk, newAlg: o.newAlg }, "kid").then(function (res) {
+        // RFC 8555 sec. 7.3.5: a 200 means the server has COMMITTED the rollover (the status is gated to 200
+        // by _post; a problem+json is already rejected). Rotate the session key FIRST so the client stays in
+        // sync -- a bodyless or malformed account body must NOT leave the client on the old key while the
+        // server holds the new one. The account object is optional + informational: parse it best-effort.
+        accountKey = o.newKey; accountJwk = o.newJwk; alg = o.newAlg;
+        var acct = null;
+        if (_bodyText(res).trim() !== "") {
+          try { acct = validate("account", _json(res)); }
+          catch (_e) { acct = null; }
+        }
+        return { account: acct, url: account };
+      });
+    });
+  }
+
+  // ARI RenewalInfo (RFC 9773 sec. 4.1) -- the SOLE UNAUTHENTICATED GET (no JWS, no nonce).
+  function _renewalInfo(certDer) {
+    if (!Buffer.isBuffer(certDer)) throw E("acme/bad-input", "renewalInfo requires a DER certificate Buffer");
+    var certId = ariCertId(certDer);
+    return _resource("renewalInfo").then(function (base) {
+      // Append the certID to the PATH, before any query string (RFC 9773): a directory renewalInfo URL may
+      // carry a query, so string concatenation would push the certID into the query rather than the path.
+      var u = new URL(base);
+      u.pathname = u.pathname.replace(/\/+$/, "") + "/" + certId;
+      var url = _clientUrl(u.href);
+      return _send("GET", url, { accept: "application/json" }, null).then(function (res) {
+        if (res.status !== 200) throw _serverProblem(res);
+        var obj = validateRenewalInfo(_json(res));
+        var ra = res.headers["retry-after"];
+        var retryAfterSeconds = null;
+        if (typeof ra === "string" && ra.trim() !== "") retryAfterSeconds = retryAfter.parse(ra, { now: clock(), E: E, code: "acme/bad-retry-after" }).retryAfterSeconds;
+        return { renewalInfo: obj, retryAfterSeconds: retryAfterSeconds };
+      });
+    });
+  }
+
+  return {
+    directory: _directory,
+    newAccount: _newAccount,
+    newOrder: _newOrder,
+    getOrder: _getOrder,
+    getAuthorization: _getAuthorization,
+    getChallenge: _getChallenge,
+    respondToChallenge: _respondToChallenge,
+    finalize: _finalize,
+    pollOrder: _pollOrder,
+    pollAuthorization: _pollAuthorization,
+    downloadCertificate: _downloadCertificate,
+    revokeCert: _revokeCert,
+    deactivateAccount: _deactivateAccount,
+    deactivateAuthorization: _deactivateAuthorization,
+    keyChange: _keyChange,
+    renewalInfo: _renewalInfo,
+  };
+}
+
 module.exports = {
+  client: client,
   validate: validate,
   validateProblem: validateProblem,
   validateRenewalInfo: validateRenewalInfo,