@blamejs/pki 0.3.28 → 0.3.29

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.29 — 2026-08-02
+
+The pki.acme client rounds out its RFC 8555 / RFC 9773 surface -- pre-authorize an identifier with client.newAuthz, choose among alternate issuance chains in client.downloadCertificate, and schedule renewal from the CA's ARI window with client.renewalWindow.
+
+### Added
+
+- client.newAuthz(identifier) pre-authorizes a single identifier ahead of placing an order (RFC 8555 sec. 7.4.1): it POSTs the identifier to the directory's newAuthz resource (kid-signed) and returns { authorization, url } for the created authorization -- normally pending, or an already-valid one when the CA has out-of-band authorization for the identifier. A wildcard identifier is refused before any request (pre-authorization of a wildcard is not defined), an unadvertised newAuthz resource fails closed, a 201 without a Location fails closed, and the returned authorization is validated to name exactly the identifier requested and to be a non-wildcard authorization the flow can proceed with -- one that names a different identifier, is marked as a broader wildcard grant, or is in a terminal failed state is rejected rather than acted on.
+- client.downloadCertificate(url, opts?) gains selectChain + maxAlternates to choose among the alternate issuance chains a CA offers (RFC 8555 sec. 7.4.2, RFC 8288 Link). Without a selector it returns the primary chain and now also alternates -- the resolved URLs of every Link rel="alternate" the certificate response advertised. With selectChain, it evaluates the primary chain first, then each alternate in header order, and resolves to the first chain the predicate accepts (selectChain receives { certificate, chain, certificates }); none accepted fails closed. The alternate Link header is untrusted: it is parsed strictly against RFC 8288 (rel matched as a whole token, case-insensitively; a malformed header or a non-https target fails closed), the extra signed fetches are bounded by maxAlternates (default 8, over-budget fails closed), duplicate resolved URLs are de-duplicated, and an alternate whose end-entity certificate differs from the primary's is rejected rather than substituted. Each alternate is fetched by the same POST-as-GET path, inheriting the media-type, size, and strict-chain-parse gates.
+- client.renewalWindow(certDer, opts?) turns the CA's ARI renewal window into a scheduling decision (RFC 9773 sec. 4.2 / 4.3). It composes the unauthenticated renewalInfo GET, selects a uniform-random instant within the CA's suggested window -- bounded by the certificate's own expiry, so the chosen time is never after notAfter -- (an injectable random and clock make the decision deterministic and let a caller ask 'renew as of time T?') so many clients do not renew at the same edge, and returns { suggestedWindow, selectedTime, renewNow, retryAfterSeconds, explanationURL } -- renewNow is set when the selected instant is already in the past. It refuses before any request for a certificate already past its notAfter (nothing to renew) or one the caller marks with replaced: true (already superseded), and retryAfterSeconds always carries a poll delay: the CA's Retry-After clamped to [60s, 24h], or a sensible default when the CA omits it. Pass a prior result back as opts.previous to REUSE its selectedTime while the CA's window is unchanged (RFC 9773 sec. 4.2), so a client that refreshes ARI on each poll keeps one stable renewal instant instead of re-randomizing it. The helper returns the decision as data; it never sleeps or schedules on a background timer.
+
+### Changed
+
+- client.renewalInfo(certDer) now refuses an already-expired certificate before issuing the unauthenticated RenewalInfo GET (RFC 9773 sec. 4.3: a client MUST NOT check a certificate's RenewalInfo after it has expired), throwing acme/certificate-expired -- the same pre-fetch expiry gate renewalWindow applies.
+- pki.acme.client now rejects a server-provided URL whose host is an IPv4-address form (hex, octal, decimal, or shorthand) that the WHATWG URL parser would coerce to a different, often loopback or internal, address -- the account-signed JWS url (RFC 8555 sec. 6.4) must name the exact authority the request connects to, so such a URL can no longer steer an authenticated request to an unintended host (SSRF hardening).
+
 ## v0.3.28 — 2026-08-01
 
 pki.est gains its remaining RFC 7030 network verbs -- request a server-generated key pair with pki.est.serverkeygen, fetch the CA's CSR-attributes policy with pki.est.csrattrs, and authenticate with HTTP Digest as an alternative to HTTP Basic.

package/README.md

@@ -219,7 +219,7 @@ is callable today; nothing below is a stub.
 | `pki.est` | RFC 7030 / 8951 / 9908 / 7616 Enrollment over Secure Transport — the thin client verbs `cacerts` / `simpleenroll` / `simplereenroll` / `serverkeygen` / `csrattrs` 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 or Digest (RFC 7616; SHA-256 / SHA-512-256, MD5 and no-qop refused by default) answered only after the server is authenticated, and the issued certificate chosen by public-key match. `serverkeygen` requests a server-generated key (cleartext or an opaque CMS EnvelopedData, encryption bound to the CSR's key-identifier attribute, over a confidentiality-bearing cipher); `csrattrs` fetches the CA's RFC 9908 attributes policy. 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`, `serverkeygen`, `csrattrs`, `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, ACME, and CMP clients — `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 — `client(directoryUrl, opts)` is a stateful client that drives a live CA directory over `pki.transport` (inject your own, or the fail-closed default): `newAccount` / `newOrder` / `getOrder` / `getAuthorization` / `getChallenge` / `respondToChallenge` / `finalize` / `pollOrder` / `pollAuthorization` / `downloadCertificate` walk the issuance flow, and `revokeCert` (account-key or certificate-key signed), `keyChange` (account key rotation), `deactivateAccount` / `deactivateAuthorization`, and `renewalInfo` (ARI) round out the lifecycle — https-only for every URL, an explicit trust anchor required, a fresh single-use nonce per request with a bounded badNonce retry, POST-as-GET reads, bounded polling that sleeps on a Retry-After via an injectable sleeper (capped by a poll count and a total-wait budget), and every response body size-capped. Over the message layer it composes: 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), fail-closed — `client`, `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
+| `pki.acme` | RFC 8555 / 8737 / 8738 / 9773 ACME — `client(directoryUrl, opts)` is a stateful client that drives a live CA directory over `pki.transport` (inject your own, or the fail-closed default): `newAccount` / `newOrder` / `newAuthz` / `getOrder` / `getAuthorization` / `getChallenge` / `respondToChallenge` / `finalize` / `pollOrder` / `pollAuthorization` / `downloadCertificate` walk the issuance flow — `newAuthz` pre-authorizes a single identifier (§7.4.1) and `downloadCertificate` picks among alternate issuance chains (`Link rel="alternate"`, §7.4.2, via a `selectChain` predicate bounded by `maxAlternates`) — and `revokeCert` (account-key or certificate-key signed), `keyChange` (account key rotation), `deactivateAccount` / `deactivateAuthorization`, `renewalInfo` (ARI), and `renewalWindow` (the RFC 9773 §4.2/4.3 renewal decision) round out the lifecycle — https-only for every URL, an explicit trust anchor required, a fresh single-use nonce per request with a bounded badNonce retry, POST-as-GET reads, bounded polling that sleeps on a Retry-After via an injectable sleeper (capped by a poll count and a total-wait budget), and every response body size-capped. Over the message layer it composes: 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), fail-closed — `client`, `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` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. `build(leaf, opts)` is the discovering complement (RFC 4158): from a leaf, an untrusted pool of candidate CA certificates, and a trust store, it finds the ordered leaf→anchor path `validate` accepts — name chaining plus the RFC 4158 §3.5 sort hints (AKI/SKI match, anchor-adjacent issuer, CA + keyCertSign, validity), a depth-first search with backtracking so the first path `validate` accepts wins, and a bounded search (chain-length cap, candidate-expansion cap, identity-tuple visited-set) so a cross-certificate cycle or Bridge-CA fan-out terminates deterministically; every accept flows through `validate` and its verdict is cross-checked against `openssl verify`. **Opt-in AIA `caIssuers` fetching** (`opts.fetchAia: true`) discovers a *missing* intermediate from a certificate's Authority Information Access URL (RFC 5280 §4.2.2.1) over `pki.transport`, triggered only on a pool miss — SSRF/amplification-bounded (https-only, a total fetch budget that silently caps fetching rather than throwing, a per-cert URL cap, a build-wide URL dedupe, a response-size + certificate-count cap, no redirect following; every fault a silent skip), with the TLS trust (`opts.tls`) kept distinct from the PKI `trustAnchors` and every fetched certificate remaining untrusted pool material that still flows through `validate` (never a trust anchor). Off by default — the default build is byte-identical offline. Pure and re-entrant, fail-closed — `validate`, `build`, `crlChecker`, `ocspChecker` |

package/lib/acme.js

@@ -42,7 +42,8 @@ var csr = require("./schema-csr");
 var pkix = require("./schema-pkix");
 var constants = require("./constants");
 var rfc3339 = require("./rfc3339");
-var subtle = require("./webcrypto").webcrypto.subtle;
+var webcrypto = require("./webcrypto").webcrypto;
+var subtle = webcrypto.subtle;
 var frameworkError = require("./framework-error");
 var httpTransport = require("./http-transport");
 var retryAfter = require("./http-retry-after");
@@ -60,6 +61,18 @@ function _isString(v) { return typeof v === "string"; }
 // downstream expiry / renewal-window comparison never runs on an impossible instant (month 13, a :60
 // leap second, a rolled-over value). pki.ct's log-list window parse composes the same primitive.
 function _isRfc3339(v) { return rfc3339.isValid(v); }
+// A uniform random draw in [0, 1) from the platform CSPRNG (48 bits of entropy). Used ONLY to spread the
+// ARI renewal instant across the CA's suggested window (RFC 9773 sec. 4.2) so many clients do not stampede
+// the same edge -- a load-distribution measure, not a secret. Injectable via renewalWindow opts.random.
+var _RANDOM_DENOM = Math.pow(2, 48);   // 6 bytes -> a uniform fraction in [0, 1)
+function _defaultRandom() { return Buffer.from(webcrypto.getRandomValues(new Uint8Array(6))).readUIntBE(0, 6) / _RANDOM_DENOM; }
+// RFC 9773 sec. 4.3.2: the ARI Retry-After bounds the re-poll cadence -- clamp it to [60s, 24h] so a
+// hostile (or absent) value can neither hammer the CA nor defer the next check indefinitely. When the CA
+// omits Retry-After (permitted), the decision helper still owes the caller a poll interval, so it returns a
+// reasonable default in-range (sec. 4.3.2 "the client SHOULD use a reasonable default") rather than null.
+var RENEWAL_RETRY_MIN_SECONDS = 60;
+var RENEWAL_RETRY_MAX_SECONDS = constants.TIME.days(1) / constants.TIME.seconds(1);
+var RENEWAL_RETRY_DEFAULT_SECONDS = constants.TIME.hours(6) / constants.TIME.seconds(1);
 // A URL string: an absolute http(s) URI with a real host (RFC 3986). ACME URLs are
 // server-provided endpoints downstream transport will trust, so they are PARSED
 // (not prefix-matched) -- a malformed value like "https://[" or a hostless
@@ -138,7 +151,10 @@ var SPECS = {
     { name: "identifier", type: "identifier", required: true },
     { name: "status", type: "string", required: true, enum: STATUS.authorization },
     { name: "expires", type: "rfc3339", requiredWhen: function (o) { return o.status === "valid"; } },
-    { name: "challenges", type: "array", required: true, minItems: 1, elemType: "challenge" },
+    // challenges is required (the key is present) but MAY be empty for an already-"valid" authorization the CA
+    // granted out of band (RFC 8555 sec. 7.1.4 / 7.4.1 -- no challenge was validated); a pending/other authz still
+    // needs at least the one challenge the client fulfills.
+    { name: "challenges", type: "array", required: true, minItems: function (o) { return o.status === "valid" ? 0 : 1; }, elemType: "challenge" },
     { name: "wildcard", type: "boolean" },
   ],
   challenge: [
@@ -155,7 +171,7 @@ var SPECS = {
   ],
 };
 
-function _checkType(kind, field, value) {
+function _checkType(kind, field, value, obj) {
   switch (field.type) {
     case "string": if (!_isString(value)) return "must be a string"; break;
     case "url": if (!_isUrl(value)) return "must be a URL string"; break;
@@ -166,7 +182,8 @@ function _checkType(kind, field, value) {
     case "identifier": _validateIdentifier(value); break;
     case "array":
       if (!Array.isArray(value)) return "must be an array";
-      if (field.minItems && value.length < field.minItems) return "must have at least " + field.minItems + " element(s)";
+      var minItems = typeof field.minItems === "function" ? field.minItems(obj) : field.minItems;   // conditional (sec. 7.1.4)
+      if (minItems && value.length < minItems) return "must have at least " + minItems + " element(s)";
       for (var i = 0; i < value.length; i++) {
         if (field.elemType === "url" && !_isUrl(value[i])) return "element " + i + " must be a URL string";
         if (field.elemType === "contact" && !_isUriString(value[i])) return "element " + i + " must be a URI string";
@@ -202,7 +219,7 @@ function _validate(kind, obj) {
     if (field.enum && field.enum.indexOf(obj[field.name]) === -1) {
       throw E("acme/bad-status", "the " + kind + " " + field.name + " " + JSON.stringify(obj[field.name]) + " is not a recognized value");
     }
-    var err = _checkType(kind, field, obj[field.name]);
+    var err = _checkType(kind, field, obj[field.name], obj);
     if (err) throw E("acme/bad-" + _codeSlug(kind), "the " + kind + " field " + JSON.stringify(field.name) + " " + err);
   }
   return obj;
@@ -216,15 +233,19 @@ function _validate(kind, obj) {
 // round-trip. `_validateIdentifier` rejects a value beginning `*.` (that is only
 // legal in an order identifier, checked separately).
 function _validateIdentifier(id) {
-  if (!_isObject(id) || !_isString(id.type) || !_isString(id.value)) throw E("acme/bad-identifier", "an identifier must be { type, value } strings");
-  if (id.type === "dns") {
-    if (id.value.indexOf("*.") === 0) throw E("acme/bad-identifier", "a wildcard *. value is not permitted in an authorization identifier (RFC 8555 sec. 7.1.4)");
-    _assertDnsName(id.value);
-  } else if (id.type === "ip") {
-    _assertIpAddress(id.value);
+  if (!_isObject(id)) throw E("acme/bad-identifier", "an identifier must be { type, value } strings");
+  var type = id.type, value = id.value;   // read each field ONCE (a getter-backed / inherited prop is captured here)
+  if (!_isString(type) || !_isString(value)) throw E("acme/bad-identifier", "an identifier must be { type, value } strings");
+  if (type === "dns") {
+    if (value.indexOf("*.") === 0) throw E("acme/bad-identifier", "a wildcard *. value is not permitted in an authorization identifier (RFC 8555 sec. 7.1.4)");
+    _assertDnsName(value);
+  } else if (type === "ip") {
+    _assertIpAddress(value);
   }
-  // An unrecognized identifier type is surfaced raw (a server may add types).
-  return id;
+  // Return a CANONICAL { type, value } built from the single read above -- an unrecognized type is surfaced raw
+  // (a server may add types). Callers serialize THIS, not the caller's object, so an inherited/getter-backed field
+  // is not dropped by JSON.stringify and an enumerable extra property is not sent to the CA.
+  return { type: type, value: value };
 }
 
 // A DNS name (each label lowercase letters/digits/hyphen, not leading/trailing
@@ -758,9 +779,11 @@ async function externalAccountBinding(o) {
 // only (sec. 7.1.3). An `ip` identifier has no wildcard form. Everything else is
 // the shared _validateIdentifier syntax on the base name.
 function _validateOrderIdentifier(id) {
-  if (!_isObject(id) || !_isString(id.type) || !_isString(id.value)) throw E("acme/bad-identifier", "an order identifier must be { type, value } strings");
-  if (id.type === "dns") {
-    var v = id.value;
+  if (!_isObject(id)) throw E("acme/bad-identifier", "an order identifier must be { type, value } strings");
+  var type = id.type, value = id.value;   // read each field ONCE (a getter-backed / inherited prop is captured here)
+  if (!_isString(type) || !_isString(value)) throw E("acme/bad-identifier", "an order identifier must be { type, value } strings");
+  if (type === "dns") {
+    var v = value;
     if (v.indexOf("*.") === 0) {
       v = v.slice(2);
       if (v.indexOf("*") !== -1) throw E("acme/bad-identifier", "a wildcard order identifier permits exactly one leading *. label (RFC 8555 sec. 7.1.3)");
@@ -768,11 +791,13 @@ function _validateOrderIdentifier(id) {
       throw E("acme/bad-identifier", "a wildcard must be a single leading *. label (RFC 8555 sec. 7.1.3)");
     }
     _assertDnsName(v);
-  } else if (id.type === "ip") {
-    if (id.value.indexOf("*") !== -1) throw E("acme/bad-identifier", "an ip identifier has no wildcard form (RFC 8738)");
-    _assertIpAddress(id.value);
+  } else if (type === "ip") {
+    if (value.indexOf("*") !== -1) throw E("acme/bad-identifier", "an ip identifier has no wildcard form (RFC 8738)");
+    _assertIpAddress(value);
   }
-  return id;
+  // Canonical { type, value } from the single read (the ORIGINAL value, wildcard `*.` included) -- see
+  // _validateIdentifier: callers serialize THIS, so the wire payload cannot diverge from what was validated.
+  return { type: type, value: value };
 }
 
 /**
@@ -794,14 +819,39 @@ function _validateOrderIdentifier(id) {
  */
 function newOrder(o) {
   if (!_isObject(o) || !Array.isArray(o.identifiers) || o.identifiers.length === 0) throw E("acme/bad-order", "newOrder requires a non-empty identifiers array (RFC 8555 sec. 7.4)");
-  o.identifiers.forEach(_validateOrderIdentifier);
-  var payload = { identifiers: o.identifiers };
+  // Serialize the CANONICAL { type, value } each validator returns, never the caller's objects (which may carry
+  // getter-backed / inherited fields JSON.stringify would drop, or extra enumerable fields it would send).
+  var payload = { identifiers: o.identifiers.map(_validateOrderIdentifier) };
   if (o.notBefore !== undefined) { if (!_isRfc3339(o.notBefore)) throw E("acme/bad-order", "notBefore must be an RFC 3339 date-time"); payload.notBefore = o.notBefore; }
   if (o.notAfter !== undefined) { if (!_isRfc3339(o.notAfter)) throw E("acme/bad-order", "notAfter must be an RFC 3339 date-time"); payload.notAfter = o.notAfter; }
   if (o.replaces !== undefined) { if (!_isString(o.replaces)) throw E("acme/bad-order", "replaces must be an ARI certID string (RFC 9773 sec. 5)"); payload.replaces = o.replaces; }
   return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
 }
 
+/**
+ * @primitive  pki.acme.newAuthz
+ * @signature  pki.acme.newAuthz(opts) -> flattened JWS
+ * @since      0.3.29
+ * @status     experimental
+ * @spec       RFC 8555, RFC 8555 sec. 7.4.1
+ * @related    pki.acme.newOrder, pki.acme.client
+ *
+ * Build a kid-signed pre-authorization request (RFC 8555 sec. 7.4.1): a Flattened JWS over EXACTLY
+ * `{ identifier: { type, value } }` -- a SINGLE identifier object, not an array. The identifier is validated as
+ * an AUTHORIZATION identifier, which REJECTS a wildcard `*.` value (pre-authorization cannot authorize a
+ * wildcard name); a bad type / value is `acme/bad-identifier`. `opts` = `{ key, alg, nonce, url, kid, identifier }`.
+ * The `client.newAuthz(identifier)` verb composes this, POSTs it to the directory `newAuthz` resource, and
+ * returns the validated authorization bound to the requested identifier.
+ *
+ * @example
+ *   await pki.acme.newAuthz({ key, alg: "ES256", nonce, url, kid, identifier: { type: "dns", value: "example.org" } });
+ */
+function newAuthz(o) {
+  if (!_isObject(o) || !_isObject(o.identifier)) throw E("acme/bad-identifier", "newAuthz requires a single identifier object (RFC 8555 sec. 7.4.1)");
+  // Serialize the canonical { type, value } the validator returns, never the caller's object (see _validateIdentifier).
+  return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, { identifier: _validateIdentifier(o.identifier) });
+}
+
 // The account key's SubjectPublicKeyInfo DER, imported from its public JWK, so a
 // finalize CSR carrying that same key is caught (sec. 11.1). The DER is canonical
 // (node emits canonical SPKI), matched byte-for-byte against the CSR's strict-DER SPKI.
@@ -1144,10 +1194,35 @@ function _clientUrl(urlStr) {
   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);
+  // An ACME URL never carries userinfo. The transport connects to the host and does NOT put userinfo in the
+  // request target, so a signed JWS `url` with userinfo would not match the URL the request is directed to
+  // (RFC 8555 sec. 6.4); refuse it rather than sign a credential-bearing URL that steers nothing. Test the RAW
+  // authority for a literal "@", not url.username/password: an EMPTY userinfo ("https://@host", "https://:@host")
+  // leaves both empty while the verbatim URL still carries the "@" the transport drops.
+  if (((/^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/?#]*)/.exec(s) || [])[1] || "").indexOf("@") !== -1) throw E("acme/bad-url", "an ACME URL must not contain userinfo: " + JSON.stringify(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));
+  // The path/query round-trip checks below cover only pathname+search; apply the shared structural authority
+  // guard too, so a repaired AUTHORITY (a bracket in userinfo -- "a[b@host" -> "a%5Bb@host", a double "@") is
+  // rejected on THIS direct path (a directory / Location / caller URL) exactly as the Link-alternate path
+  // already rejects it. Otherwise the verbatim URL would be signed (sec. 6.4) while the transport connects to a
+  // different authority. (An uppercase host / explicit :443 is NOT a repair here -- it is normalized, not
+  // rewritten to a different authority -- and is deliberately honored below, so it is not flagged.)
+  if (_uriStructurallyInvalid(s)) throw E("acme/bad-url", "an ACME URL authority is not canonical (the transport would repair it): " + JSON.stringify(s));
+  // Reject a HOST the transport would rewrite to a DIFFERENT authority. WHATWG's special-scheme parser coerces an
+  // IPv4-address form -- hex ("0x7f.1"), octal ("0177.0.0.1"), decimal ("2130706433"), shorthand ("127.1") -- into
+  // a dotted-quad ("127.0.0.1"), so the JWS `url` would be signed over the raw host while the transport connects to
+  // a different (often loopback / internal, an SSRF-adjacent) address. Compare the raw host (ASCII-lowercased, the
+  // only tolerated normalization) to the parsed hostname: uppercase-host and a default :443 still match, an IPv4
+  // coercion or a non-canonical IPv6 literal does not. (path/query/fragment are checked separately below.)
+  var _auth = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/?#]*)/.exec(s);
+  if (_auth) {
+    var _hp = _auth[1].slice(_auth[1].lastIndexOf("@") + 1);   // strip any userinfo (does not route the request)
+    var _rawHost = _hp.charAt(0) === "[" ? _hp.slice(0, _hp.indexOf("]") + 1) : _hp.split(":")[0];   // strip the port
+    if (_rawHost.toLowerCase() !== url.hostname) throw E("acme/bad-url", "an ACME URL host is not canonical (the transport would rewrite it): " + 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
@@ -1158,9 +1233,19 @@ function _clientUrl(urlStr) {
   // 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));
+  // The query round-trips too (the transport sends pathname+search): an EMPTY query ("...?") -- which WHATWG
+  // drops (url.search === "") while the verbatim URL keeps the "?" -- or any query the parser would rewrite
+  // signs a JWS `url` differing from the request target. A non-empty canonical query (`?a=b`) round-trips and
+  // is honored. (The fragment is rejected below, so the first raw "?" is the query delimiter.)
+  var qi = s.indexOf("?");
+  var rawQuery = qi === -1 ? "" : s.slice(qi).split("#")[0];
+  if (rawQuery !== url.search) throw E("acme/bad-url", "an ACME URL query 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));
+  // would sign a JWS `url` (sec. 6.4) that differs from the URL actually requested, failing at the CA. Test
+  // the RAW `#` delimiter, not `url.hash`: an EMPTY fragment ("...alt#") leaves url.hash === "" (falsy) while
+  // the verbatim URL still carries the `#`. A literal `#` is always the fragment delimiter (a `#` in a path is
+  // %23), so its mere presence is the fragment.
+  if (s.indexOf("#") !== -1) 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.
@@ -1177,10 +1262,23 @@ function _resolveLocation(loc, base) {
   try { new URL(loc); }
   catch (_e) { isAbsolute = false; }
   if (isAbsolute) return _clientUrl(loc);
-  var abs;
-  try { abs = new URL(loc, base).href; }
+  var u;
+  try { u = new URL(loc, base); }
   catch (e) { throw E("acme/bad-url", "the Location header did not resolve to a valid URL: " + JSON.stringify(loc), e); }
-  return _clientUrl(abs);
+  // A relative reference whose QUERY WHATWG re-encoded on resolution (an RFC 3986 reserved char the special-scheme
+  // query set percent-encodes -- an apostrophe -> %27) is non-canonical: the signed+requested URL would differ from
+  // the raw advertised query (RFC 8555 sec. 6.4). _clientUrl makes this check for an absolute URL, which a relative
+  // reference would otherwise bypass.
+  if (_queryRepaired(loc, u)) throw E("acme/bad-url", "a relative Link/Location query is not canonical (resolution re-encoded it): " + JSON.stringify(loc));
+  return _clientUrl(u.href);
+}
+// Did resolving `rawRef` re-encode its query (a reserved char like "'" -> %27)? RFC 3986 sec. 6.2.2.2 does NOT make
+// a reserved char equivalent to its percent-escape, so a raw query that differs from the resolved search is a
+// non-canonical reference -- used to reject a repaired target AND to skip a repaired anchor whose context match
+// would otherwise be SPOOFED (a "?x='" anchor byte-matching a base carrying "?x=%27").
+function _queryRepaired(rawRef, resolvedUrl) {
+  var qi = rawRef.indexOf("?");
+  return qi !== -1 && rawRef.slice(qi).split("#")[0] !== resolvedUrl.search;
 }
 // The default poll sleeper is the shared bounded sleeper (lib/sleep.js): it chunks a delay above Node's
 // 32-bit setTimeout ceiling so a large (parser-bounded, up to a year) Retry-After is honored rather than
@@ -1213,6 +1311,355 @@ function _splitPemChain(text) {
   return out;
 }
 
+// The default and hard ceilings on the alternate-chain fetch (RFC 8555 sec. 7.4.2). A Link header is an
+// UNTRUSTED server field: cap its length before the walk, and cap how many extra signed POSTs it can drive
+// (CWE-770 fetch amplification), the same posture as maxRedirects.
+var LINK_HEADER_MAX_BYTES = constants.BYTES.kib(8);
+var DEFAULT_MAX_ALTERNATES = 8;
+// An RFC 7230 token (a Link parameter name, or an unquoted parameter value): 1*tchar, no whitespace/specials.
+var LINK_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+// Trim only HTTP OWS -- SP (0x20) and HTAB (0x09) -- NOT arbitrary Unicode whitespace. String.prototype.trim
+// would strip an NBSP (obs-text) and other Unicode spaces, letting them masquerade as field whitespace.
+function _trimOWS(s) { return s.replace(/^[ \t]+/, "").replace(/[ \t]+$/, ""); }
+// Is `t` a valid RFC 8288 sec. 3.3 relation-type -- a reg-rel-type (a letter then LDH, compared case-
+// insensitively) OR an ext-rel-type (an absolute URI: a scheme then ':', AND a canonical RFC 3986 reference so
+// a scheme prefix alone is not enough, e.g. "http:%ZZ" is rejected for its malformed pct-escape)? "@" is neither.
+function _validRelType(t) {
+  if (/^[A-Za-z][A-Za-z0-9.-]*$/.test(t)) return true;   // reg-rel-type
+  // ext-rel-type: a full absolute URI. A relation type is an identifier, never resolved, so a percent-encoded dot
+  // (%2e) is a legal char (not a dot-segment); other than that its structure must be a valid absolute URI.
+  if (LINK_URI_BADCHAR.test(t)) return false;
+  return _validAbsoluteUri(t);
+}
+// Is `t` a valid RFC 3986 ABSOLUTE URI (a relation-type identifier, never connected to)? A scheme, valid pct-
+// escapes, and a structurally valid authority/path. The characters are already validated (LINK_URI_BADCHAR above);
+// _uriStructurallyInvalid enforces the rest by RFC 3986 GRAMMAR -- brackets only in an authority IP-literal whose
+// content is a valid IPv6/IPvFuture, a non-empty authority, at most one "@", at most one "#", a numeric port. NO
+// URL.canParse on the whole URI: its special-scheme quirks wrongly reject valid identifiers (an IPv4 coercion of a
+// numeric reg-name "1.2.3.4.5", a 16-bit port cap, IPvFuture, an empty reg-name "foo://user@/"); WHATWG is used
+// only inside _badIpLiteral to validate an IPv6 literal, the one place it is correct.
+function _validAbsoluteUri(t) {
+  return /^[A-Za-z][A-Za-z0-9+.-]*:/.test(t) && !LINK_URI_BADPCT.test(t) && !_uriStructurallyInvalid(t);
+}
+// A URI carries at most ONE "#" (the fragment delimiter); a fragment cannot itself contain "#" (RFC 3986 sec.
+// 3.5), so a second literal "#" is invalid, which WHATWG ACCEPTS by folding the rest into the fragment. A pct-
+// encoded "%23" is a literal char, not counted.
+function _multiFragment(uri) { return uri.split("#").length > 2; }
+// The authority (after "//", optionally after a scheme, up to the next "/?#") carries at most one "@" (userinfo
+// "@" host); a second literal "@" is invalid RFC 3986, which WHATWG ACCEPTS while rewriting the first "@".
+function _authorityMultiAt(uri) {
+  var m = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/([^/?#]*)/.exec(uri);
+  return !!m && m[1].split("@").length > 2;
+}
+// A URI whose scheme REQUIRES an authority (or a scheme-relative reference, which inherits one -- always https
+// here) must have a NON-EMPTY authority. A "//" immediately followed by "/", "?", "#", or end is an empty
+// authority WHATWG silently REPAIRS by promoting the next path segment to the host ("///cert/alt" -> host "cert";
+// "////acme.example/p" -> host "acme.example"; "http:///relations" -> host "relations"). A scheme that legitimately
+// allows an empty authority (file:///path, or any non-authority scheme) is NOT flagged.
+function _hasEmptyAuthority(uri) {
+  var m = /^([A-Za-z][A-Za-z0-9+.-]*:)?\/\/([^/?#]*)/.exec(uri);
+  if (!m) return false;
+  var scheme = m[1] ? m[1].slice(0, -1).toLowerCase() : "";   // "" == scheme-relative (inherits the https base)
+  if (scheme !== "" && scheme !== "http" && scheme !== "https" && scheme !== "ws" && scheme !== "wss" && scheme !== "ftp") return false;
+  // The HOST itself (the authority with any userinfo and port stripped) must be non-empty -- not only the char
+  // right after "//": "https://user@/x" and "https://:443/x" have an empty host after the userinfo / before the
+  // port, which WHATWG rejects (or repairs) for a special scheme.
+  var host = m[2].slice(m[2].lastIndexOf("@") + 1);
+  if (host.charAt(0) !== "[") { var ci = host.indexOf(":"); if (ci !== -1) host = host.slice(0, ci); }
+  return host === "";
+}
+// Are any brackets in `uri` confined to a single authority IP-literal (`scheme://[...]`, scheme optional for a
+// network-path reference, RFC 3986 sec. 4.2)? RFC 3986 permits `[`/`]` ONLY there; anywhere else -- a path
+// ("/cert/[alt]") or an opaque scheme part ("urn:[") -- they are invalid, yet WHATWG's lenient parse accepts them.
+function _bracketsOnlyInAuthority(uri) {
+  if (uri.indexOf("[") === -1 && uri.indexOf("]") === -1) return true;
+  // Optional userinfo may precede the IP-literal host (RFC 3986: authority = [ userinfo "@" ] host [ ":" port ]).
+  // A raw "[" / "]" is NOT permitted in userinfo (RFC 3986 sec. 3.2.1/3.2.2 -- the IP-literal host is the ONLY place
+  // square brackets are allowed), so the userinfo class excludes them; otherwise "a[b@[::1]" (which WHATWG repairs
+  // to "a%5Bb@[::1]") would anchor on the real host and slip.
+  var m = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/(?:[^/?#@[\]]*@)?\[[^[\]]*\]/.exec(uri);
+  if (!m) return false;
+  var rest = uri.slice(m[0].length);
+  if (rest.indexOf("[") !== -1 || rest.indexOf("]") !== -1) return false;   // no bracket past the authority
+  // After the IP-literal HOST "]", the rest of the authority (up to the next "/?#") may be ONLY an optional numeric
+  // ":port". Anything else -- an "@" ("[::1]:80@host" / "[::1]@host", where "[::1]" is a bracketed userinfo, invalid
+  // RFC 3986), a non-numeric port, or trailing host text -- means the literal sits in an invalid position, which
+  // WHATWG would re-parse to a DIFFERENT host.
+  var afterHost = rest.split(/[/?#]/)[0];
+  return afterHost === "" || /^:[0-9]*$/.test(afterHost);
+}
+// A relative-PATH reference (no scheme, no "//" authority) whose FIRST path segment contains a ":" is a
+// path-noscheme violation (RFC 3986 sec. 3.3 / 4.2: the first segment "cannot contain a colon (':') character",
+// as it would be mistaken for a scheme). ":foo" or "1x:y" is such a case, which WHATWG resolves against the base
+// (same-origin) rather than rejecting. A real scheme ("foo:bar") is handled by the scheme/https gates, not here.
+function _relFirstSegHasColon(uri) {
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(uri) || uri.indexOf("//") === 0) return false;
+  return uri.split(/[/?#]/)[0].indexOf(":") !== -1;
+}
+// The authority port (":" after the host, before the next "/?#") must be *DIGIT (RFC 3986 sec. 3.2.3). A
+// non-numeric port ("host:bad") is malformed -- the character + structural checks otherwise miss it, and WHATWG
+// rejects it only on connect (so a fetched target would be skipped rather than failing closed). An empty port
+// (":") and a missing port are fine.
+function _badPort(uri) {
+  var m = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/(?:[^/?#@]*@)?(?:\[[^\]]*\]|[^/?#:]*)(:[^/?#]*)?/.exec(uri);
+  return !!(m && m[1] && !/^:[0-9]*$/.test(m[1]));
+}
+// An IP-literal host "[...]" must CONTAIN a valid IPv6 address or IPvFuture (RFC 3986 sec. 3.2.2) -- "[not-ip]",
+// "[]", "[garbage]" are malformed, which the bracket-placement check alone accepts (it only confirms the brackets
+// are in the authority) and WHATWG rejects only on connect (so a fetched target would be skipped rather than
+// failing closed). IPvFuture is checked by grammar; an IPv6 by WHATWG (which parses it correctly). `URL.canParse`
+// never throws, so no swallow.
+function _badIpLiteral(uri) {
+  var m = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/(?:[^/?#@]*@)?\[([^\]]*)\]/.exec(uri);
+  if (!m) return false;
+  if (/^[vV][0-9A-Fa-f]+\.[A-Za-z0-9._~!$&'()*+,;=:-]+$/.test(m[1])) return false;   // valid IPvFuture
+  return !URL.canParse("http://[" + m[1] + "]/");
+}
+// The RFC 3986 STRUCTURAL rules a URI-reference must satisfy that WHATWG would otherwise silently REPAIR (accept
+// while rewriting) or reject only on connect: brackets only in an authority IP-literal, a non-empty authority, at
+// most one "@" in the authority, at most one "#", a numeric port, no colon in a relative-path first segment.
+// SHARED by the fetched-target/anchor check (_linkUriInvalid) AND the ext-rel-type check (_validAbsoluteUri) so the
+// two can NEVER diverge -- a new structural rule added here binds both at once.
+function _uriStructurallyInvalid(uri) {
+  return !_bracketsOnlyInAuthority(uri) || _hasEmptyAuthority(uri) || _authorityMultiAt(uri) || _multiFragment(uri) || _relFirstSegHasColon(uri) || _badPort(uri) || _badIpLiteral(uri);
+}
+// RFC 3986 sec. 6.2.2 syntax-based normalization for an alternate DEDUP key (the verbatim URL is still what is
+// fetched + signed, sec. 6.4). The WHATWG-normalized href already lowercases scheme+host, drops a default port,
+// and removes dot-segments; on top of that, DECODE a percent-escape of an unreserved char (sec. 6.2.2.2 --
+// "%61" == "a") and UPPERCASE the hex of any other escape (sec. 6.2.2.1), so equivalent spellings collapse to one
+// signed fetch (CWE-770). fromCharCode keeps the source pure-ASCII while matching a runtime byte.
+function _dedupKey(href) {
+  return href.replace(/%[0-9A-Fa-f]{2}/g, function (m) {
+    var c = String.fromCharCode(parseInt(m.slice(1), 16));
+    return /[A-Za-z0-9._~-]/.test(c) ? c : "%" + m.slice(1).toUpperCase();
+  });
+}
+// The INTERIOR of a well-formed RFC 7230 quoted-string (between the DQUOTEs): a sequence of qdtext (any char
+// but `"`/`\`) and quoted-pair (`\` + a char). Rejects an unescaped interior quote (a""b) or a dangling `\`,
+// which first/last-char-is-a-quote alone would miss. Disjoint alternation -> linear, no ReDoS.
+var LINK_QUOTED_INTERIOR = /^(?:[^"\\]|\\.)*$/;
+// A character NOT permitted raw in an RFC 3986 URI-Reference (unreserved / reserved / pct-encode marker). A
+// Link target containing one -- a space, brace, backslash, control char -- is one WHATWG URL parsing would
+// silently repair (trim / percent-encode) on resolution, masking a malformed or off-path value; reject it.
+var LINK_URI_BADCHAR = /[^A-Za-z0-9._~:/?#[\]@!$&'()*+,;=%-]/;
+// A `%` that does NOT introduce a valid RFC 3986 pct-encoded triplet (%HEXDIG HEXDIG): the char allowlist
+// permits `%` for percent-encoding, but `%ZZ` / a trailing `%` is malformed and URL parsing would repair it.
+var LINK_URI_BADPCT = /%(?![0-9A-Fa-f]{2})/;
+// A path SEGMENT that decodes to "." or ".." via a percent-encoded dot (`%2e`): URL resolution decodes `%2e`
+// to `.` for dot-segment removal, so an encoded `..` silently becomes a path traversal that changes the
+// resolved target. Reject only such an encoded dot-SEGMENT -- an encoded dot elsewhere (a filename `0%2ex` ->
+// `0.x`) is a valid target, and a LITERAL `.`/`..` segment resolves transparently. Path only (before ?/#).
+function _hasEncodedDotSegment(uri) {
+  var segs = uri.split(/[?#]/)[0].split("/");
+  for (var _si = 0; _si < segs.length; _si++) {
+    if (!/%2e/i.test(segs[_si])) continue;
+    var dec = segs[_si].replace(/%2e/ig, ".");
+    if (dec === "." || dec === "..") return true;
+  }
+  return false;
+}
+// Is a Link URI-Reference (a target OR an anchor) NOT a canonical RFC 3986 reference -- i.e. one URL parsing
+// would repair (a disallowed char, a malformed pct-escape, an encoded dot-segment) on resolution?
+function _linkUriInvalid(uri) {
+  // A bracket in a resolved target/anchor is valid only in an authority IP-literal (a same-origin IPv6/IPvFuture
+  // cert URL is legal); in a path it is invalid and WHATWG would repair it by percent-encoding.
+  return LINK_URI_BADCHAR.test(uri) || LINK_URI_BADPCT.test(uri) || _hasEncodedDotSegment(uri) || _uriStructurallyInvalid(uri);
+}
+// A control octet forbidden in an HTTP field-value (RFC 9110): any C0 control except HTAB, plus DEL. Checked
+// by code point (not a control-char regex) to keep the source pure ASCII and clear of eslint no-control-regex.
+function _hasCtlOctet(s) {
+  for (var _ci = 0; _ci < s.length; _ci++) { var _cc = s.charCodeAt(_ci); if (_cc === 0x7F || (_cc < 0x20 && _cc !== 0x09)) return true; }
+  return false;
+}
+
+// Split an RFC 8288 Link field into its comma-separated link-values, respecting <...> and "..." context so
+// a comma inside a URI or a quoted parameter value is not a separator. An unterminated quote fails closed.
+function _splitLinkValues(s) {
+  var out = [], start = 0, inAngle = false, inQuote = false;
+  for (var i = 0; i < s.length; i++) {
+    var ch = s.charAt(i);
+    if (inQuote) { if (ch === "\\") { i++; continue; } if (ch === "\"") inQuote = false; continue; }
+    if (ch === "\"") { inQuote = true; continue; }
+    if (ch === "<") inAngle = true;
+    else if (ch === ">") inAngle = false;
+    else if (ch === "," && !inAngle) { out.push(s.slice(start, i)); start = i + 1; }
+  }
+  if (inQuote || inAngle) throw E("acme/bad-link", "the Link header has an unterminated quote or angle bracket (RFC 8288)");
+  out.push(s.slice(start));
+  return out;
+}
+// Split a link-value's parameter tail (everything after `<URI>`) into `;`-separated name=value params,
+// quote-aware; a quoted value is unescaped. Returns [{ name (lower-cased), value }].
+function _splitLinkParams(rest) {
+  var parts = [], start = 0, inQuote = false;
+  for (var i = 0; i < rest.length; i++) {
+    var ch = rest.charAt(i);
+    if (inQuote) { if (ch === "\\") { i++; continue; } if (ch === "\"") inQuote = false; continue; }
+    if (ch === "\"") inQuote = true;
+    else if (ch === ";") { parts.push(rest.slice(start, i)); start = i + 1; }
+  }
+  parts.push(rest.slice(start));
+  var out = [];
+  for (var j = 0; j < parts.length; j++) {
+    var p = _trimOWS(parts[j]);
+    // `rest` starts with the first `;`, so parts[0] is an expected empty slot before the first parameter. Any
+    // OTHER empty part is a `;` with no parameter after it (`;;` or a trailing `;`) -- malformed (RFC 8288).
+    if (p === "") { if (j === 0) continue; throw E("acme/bad-link", "an empty Link parameter (a ';' with no parameter) is malformed (RFC 8288): " + JSON.stringify(rest)); }
+    var eq = p.indexOf("=");
+    var name = (eq === -1 ? p : _trimOWS(p.slice(0, eq))).toLowerCase();
+    // A parameter NAME is a token (RFC 8288 / RFC 7230): reject whitespace / specials rather than accept a
+    // malformed "bad name=x" as a silently-ignored parameter that masks the value grammar below.
+    if (!LINK_TOKEN.test(name)) throw E("acme/bad-link", "a Link parameter name must be a token (RFC 8288 / RFC 7230): " + JSON.stringify(p));
+    // A valueless token parameter is VALID: RFC 8288 link-param = token BWS [ "=" BWS ( token / quoted-string ) ]
+    // -- the value is OPTIONAL. Keep it as an empty-valued extension param (it is never `rel`, so it is ignored).
+    // (An EMPTY part -- a `;` with no token at all, e.g. `;;` -- was already rejected above.)
+    if (eq === -1) { out.push({ name: name, value: "", hasValue: false }); continue; }
+    var v = _trimOWS(p.slice(eq + 1));
+    if (v.length >= 2 && v.charAt(0) === "\"" && v.charAt(v.length - 1) === "\"") {
+      var inner = v.slice(1, -1);   // a quoted-string may hold a space-separated list (RFC 8288)
+      if (!LINK_QUOTED_INTERIOR.test(inner)) throw E("acme/bad-link", "a quoted Link parameter value is malformed (an unescaped quote or dangling backslash, RFC 7230): " + JSON.stringify(p));
+      v = inner.replace(/\\(.)/g, "$1");
+    } else if (!LINK_TOKEN.test(v)) {
+      // An UNQUOTED value is a single NON-EMPTY RFC 7230 token -- no whitespace/specials, and an empty value
+      // (`foo=`) is not a token (an empty value must be quoted, `foo=""`). Reject a malformed one rather than
+      // split-and-match it as if it were a quoted relation list.
+      throw E("acme/bad-link", "an unquoted Link parameter value must be a non-empty token (RFC 8288 / RFC 7230): " + JSON.stringify(p));
+    }
+    out.push({ name: name, value: v, hasValue: true });
+  }
+  return out;
+}
+// Does an RFC 8288 rel value (a space-separated relation-type list) contain "alternate" as a WHOLE token,
+// case-insensitively (RFC 8288 sec. 3.3)? Never a substring -- "alternateX" / "xalternate" do not match.
+function _relHasAlternate(rel) {
+  // The rel value is a SPACE-separated relation-type list (RFC 8288 sec. 3.3) -- split on SP only, NOT a tab
+  // or other whitespace, so "alternate<TAB>index" is a single (non-matching) relation-type, not a false match.
+  var toks = String(rel).split(" ");
+  for (var i = 0; i < toks.length; i++) { if (toks[i].toLowerCase() === "alternate") return true; }
+  return false;
+}
+// Parse one link-value `"<" URI-Reference ">" *( ";" link-param )` -> { uri, rel } (rel "" if absent);
+// a blank segment (a trailing comma) -> null (skip); anything not starting with <...> -> acme/bad-link.
+function _parseLinkValue(raw) {
+  var s = _trimOWS(raw);
+  if (s === "") return null;
+  var gt = s.indexOf(">");
+  if (s.charAt(0) !== "<" || gt === -1) throw E("acme/bad-link", "a Link value must be <URI-Reference> with parameters (RFC 8288): " + JSON.stringify(raw));
+  // After the "<URI>" the remainder is *( OWS ";" OWS link-param ) -- so, past any leading whitespace, it is
+  // empty or begins with ';'. Any other trailing text (a param not introduced by ';', e.g. "<uri>rel=...") is
+  // malformed and MUST NOT be leniently read as a parameter.
+  var rest = s.slice(gt + 1).replace(/^[ \t]+/, "");
+  if (rest !== "" && rest.charAt(0) !== ";") throw E("acme/bad-link", "a Link value's parameters must be introduced by ';' (RFC 8288): " + JSON.stringify(raw));
+  var uri = s.slice(1, gt);
+  // A URI-Reference carries only RFC 3986 characters; WHATWG URL parsing would silently REPAIR anything else
+  // (trim whitespace, percent-encode a brace/control char, rewrite a backslash) when the target is later
+  // resolved -- masking a malformed / off-path value. Reject it up front, the same canonicality posture the
+  // client applies to every server-provided URL (a relative target skips _clientUrl's raw-vs-parsed check).
+  if (_linkUriInvalid(uri)) throw E("acme/bad-link", "a Link URI-Reference contains a character, percent-escape, or encoded dot-segment not permitted by RFC 3986: " + JSON.stringify(raw));
+  var params = _splitLinkParams(rest), rel = "", relSeen = false, anchor = null, anchorSeen = false;
+  for (var i = 0; i < params.length; i++) {
+    // The FIRST occurrence of rel wins; later ones are ignored (RFC 8288 sec. 3.3, a singleton) -- take the first
+    // even when its value is empty, so `rel="";rel=alternate` keeps the empty first value (the caller then fails
+    // closed on the empty rel, rather than falling through to the later alternate).
+    if (params[i].name === "rel" && !relSeen) { rel = params[i].value; relSeen = true; }
+    else if (params[i].name === "anchor") {
+      // anchor is NOT in the RFC 8288 sec. 3.3 singleton set (rel/media/title/title*/type), so it has no "ignore
+      // after the first" rule. A DUPLICATE anchor is ambiguous, and anchor is security-relevant (it overrides the
+      // link CONTEXT), so it fails closed rather than silently taking one. A VALUELESS anchor (no `=`) is malformed;
+      // an explicit value -- even an empty quoted one (`anchor=""`, resolving to the context) -- is valid.
+      if (anchorSeen) throw E("acme/bad-link", "a Link value must not carry more than one anchor parameter (RFC 8288 sec. 3.2, ambiguous context): " + JSON.stringify(raw));
+      anchorSeen = true;
+      if (!params[i].hasValue) throw E("acme/bad-link", "a Link anchor parameter requires a URI value (RFC 8288 sec. 3.2): " + JSON.stringify(raw));
+      anchor = params[i].value;
+    }
+  }
+  return { uri: uri, rel: rel, anchor: anchor, relSeen: relSeen };
+}
+// Parse an RFC 8288 Link response header for rel="alternate" certificate-chain targets (RFC 8555 sec.
+// 7.4.2): read the (case-insensitive, node-lower-cased) `link` field -- a combined string OR an array --
+// bound its length, split into link-values, keep the alternate-rel ones, resolve each against the download
+// URL, https-gate, and dedupe by resolved URL. An UNTRUSTED header: every malformed shape or non-https /
+// unresolvable target fails closed as acme/bad-link. Scoped to the alternate relation the download consumes.
+function _parseLinkAlternates(headers, base) {
+  var raw = null;
+  for (var k in headers) { if (Object.prototype.hasOwnProperty.call(headers, k) && k.toLowerCase() === "link") { raw = headers[k]; break; } }
+  if (raw == null) return [];
+  var baseUrl = new URL(base), baseOrigin = baseUrl.origin, baseHref = baseUrl.href;   // the download URL
+  var fields = Array.isArray(raw) ? raw : [raw], out = [], seen = Object.create(null), totalBytes = 0;
+  // Seed the dedup set with the PRIMARY download URL: a CA that advertises the certificate URL itself as a
+  // rel="alternate" (it is not an alternate of itself, RFC 8555 sec. 7.4.2) must not cause a redundant re-fetch.
+  seen[_dedupKey(baseHref)] = true;
+  for (var fi = 0; fi < fields.length; fi++) {
+    var field = String(fields[fi]);
+    // Cap the AGGREGATE across every Link field (CWE-770): an injected transport / duplicate-Link array can
+    // hand back many fields, each under a per-field size, that together are unbounded -- bound the sum so the
+    // parse work (and the collected alternate set) cannot amplify regardless of the header's shape. Charge a
+    // per-field overhead so a flood of EMPTY fields (each 0 bytes) still counts toward the cap.
+    totalBytes += field.length + 1;
+    if (totalBytes > LINK_HEADER_MAX_BYTES) throw E("acme/bad-link", "the Link header(s) exceed the " + LINK_HEADER_MAX_BYTES + "-byte aggregate cap (RFC 8288, CWE-770)");
+    if (_hasCtlOctet(field)) throw E("acme/bad-link", "a Link header must not contain control octets (RFC 9110 field-value)");
+    var values = _splitLinkValues(field);
+    for (var vi = 0; vi < values.length; vi++) {
+      var lv = _parseLinkValue(values[vi]);
+      if (lv === null) continue;
+      // A rel that is PRESENT but empty (`rel=""`) is a zero-length relation-type list, which is malformed (RFC
+      // 8288 sec. 3.3 requires >=1 type). Fail closed rather than silently skip it -- otherwise a malformed value
+      // could shadow a later valid one. (A link-value with NO rel at all is simply not one of ours -> skipped.)
+      if (lv.relSeen && lv.rel === "") throw E("acme/bad-link", "a Link rel parameter must name at least one relation-type (RFC 8288 sec. 3.3)");
+      // The rel value is a space-separated relation-type list with 1*SP separators (RFC 8288 sec. 3.3): multiple
+      // spaces BETWEEN types are allowed, but a LEADING or TRAILING space is malformed (so "alternate " is not
+      // split-and-matched as containing "alternate", while "alternate  index" is a valid two-type list).
+      if (lv.rel !== "" && (lv.rel.charAt(0) === " " || lv.rel.charAt(lv.rel.length - 1) === " ")) throw E("acme/bad-link", "a Link rel value has a leading or trailing space (RFC 8288 sec. 3.3): " + JSON.stringify(lv.rel));
+      // EVERY relation-type in the list must be well-formed (RFC 8288 sec. 3.3): a bad token (e.g. "@") makes the
+      // list malformed, even if another token is "alternate". (Empty tokens are internal 1*SP -- skip them.)
+      var relToks = lv.rel === "" ? [] : lv.rel.split(" ");
+      for (var ri = 0; ri < relToks.length; ri++) { if (relToks[ri] !== "" && !_validRelType(relToks[ri])) throw E("acme/bad-link", "a Link rel value contains a token that is not a valid relation-type (RFC 8288 sec. 3.3): " + JSON.stringify(lv.rel)); }
+      if (!_relHasAlternate(lv.rel)) continue;
+      // RFC 8288 sec. 3.2: an `anchor` overrides the link's CONTEXT. A certificate alternate's context is the
+      // certificate itself (the download URL); a link anchored to another resource is an alternate of THAT
+      // resource, not this certificate -- skip it. No anchor, or one resolving to the download URL, is ours.
+      if (lv.anchor != null) {
+        // Validate the RAW anchor with the same RFC 3986 rules as a target BEFORE resolving: otherwise a
+        // repairable anchor (an encoded dot-segment) could traverse to the certificate URL and SPOOF a context
+        // match. A non-canonical anchor is not a reliable context -> skip.
+        if (_linkUriInvalid(lv.anchor)) continue;
+        var au;
+        try { au = new URL(lv.anchor, base); } catch (_ae) { continue; }
+        // A repaired anchor query ("?x='" re-encoded to "?x=%27") must not byte-match a base carrying "?x=%27":
+        // "'" is a reserved sub-delim, not equivalent to its escape (RFC 3986 sec. 6.2.2.2), so a resolution that
+        // re-encoded it is a non-canonical anchor -> unreliable context, skip.
+        if (_queryRepaired(lv.anchor, au)) continue;
+        if (au.href !== baseHref) continue;
+      }
+      var resolved;
+      try { resolved = _resolveLocation(lv.uri, base); }   // resolves a relative ref + enforces the https gate
+      catch (e) {
+        // A non-https alternate is a security-relevant anomaly -> fail the whole header closed. A target that is a
+        // valid RFC 3986 reference but not a canonical ACME request URL (literal dot-segments, or a sub-delim
+        // WHATWG would re-encode in a special-scheme query) cannot be signed AND requested byte-identically
+        // (RFC 8555 sec. 6.4), so it is merely UNUSABLE -> skip THIS alternate and keep the others (sec. 7.4.2
+        // permits several), rather than discarding every valid alternate over one non-canonical spelling.
+        if (e && e.code === "acme/insecure-url") throw E("acme/bad-link", "a rel=\"alternate\" Link target is not an https URL: " + JSON.stringify(lv.uri), e);
+        continue;
+      }
+      // Origin-gate: an alternate is fetched with the ACCOUNT-KEY-signed POST-as-GET, so an untrusted (TLS-
+      // delivered but unsigned) Link header MUST NOT steer that authenticated request to a different origin
+      // (SSRF). Confine alternates to the certificate download's own origin -- the same "possibly compromised
+      // directory" threat the cross-origin mTLS-credential strip already defends (RFC 8555 sec. 7.4.2
+      // alternates are the CA's own chains, served alongside the certificate).
+      var parsed = new URL(resolved);
+      if (parsed.origin !== baseOrigin) throw E("acme/bad-link", "a rel=\"alternate\" Link target is not on the certificate download's origin (SSRF guard): " + JSON.stringify(lv.uri));
+      // Dedup by the RFC 3986 sec. 6.2.2-normalized href (lowercased scheme+host, no default :443, no dot-segments,
+      // unreserved pct-escapes decoded), so equivalent spellings ("acme.example" vs "ACME.EXAMPLE:443", "/alt" vs
+      // "/%61lt") collapse to one fetch (CWE-770 amplification) -- while the VERBATIM resolved string is what is
+      // fetched + signed (RFC 8555 sec. 6.4 exact-URL match).
+      var key = _dedupKey(parsed.href);
+      if (!seen[key]) { seen[key] = true; out.push(resolved); }
+    }
+  }
+  return out;
+}
+
 /**
  * @primitive  pki.acme.client
  * @signature  pki.acme.client(directoryUrl, opts) -> client
@@ -1230,9 +1677,9 @@ function _splitPemChain(text) {
  * 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`,
+ * object: `directory`, `newAccount`, `newOrder`, `newAuthz`, `getOrder` / `getAuthorization` / `getChallenge`,
  * `respondToChallenge`, `finalize`, `pollOrder` / `pollAuthorization`, `downloadCertificate`,
- * `revokeCert`, `deactivateAccount` / `deactivateAuthorization`, `keyChange`, `renewalInfo`.
+ * `revokeCert`, `deactivateAccount` / `deactivateAuthorization`, `keyChange`, `renewalInfo`, `renewalWindow`.
  *
  * @opts
  *   - `accountKey` / `accountJwk` / `alg` -- REQUIRED: the account private key, its public JWK, and the JWS alg.
@@ -1240,6 +1687,9 @@ function _splitPemChain(text) {
  *   - `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.
+ *   - `newAuthz(identifier)` -- pre-authorize a single identifier (RFC 8555 sec. 7.4.1) -> { authorization, url }.
+ *   - `downloadCertificate(url, { selectChain, maxAlternates })` -- pick among RFC 8555 sec. 7.4.2 alternate chains: `selectChain({certificate, chain, certificates})` returns the first truthy candidate (primary first, then bounded `Link rel="alternate"` chains, confined to the download's own origin); the result adds `alternates` (the resolved alternate URLs).
+ *   - `renewalWindow(certDer, { random, clock, replaced, previous })` -- the RFC 9773 ARI renewal decision: composes `renewalInfo`, selects a uniform-random instant in the suggested window -> { suggestedWindow, selectedTime, renewNow, retryAfterSeconds, explanationURL }. Pass a prior result back as `previous` to REUSE its selectedTime while the CA's window is unchanged (RFC 9773 sec. 4.2), so repeated refreshes keep one stable renewal instant.
  * @example
  *   var acme = pki.acme.client("https://acme.example/directory", { accountKey, accountJwk, alg: "ES256", transport });
  *   var acct = await acme.newAccount({ termsOfServiceAgreed: true });
@@ -1463,6 +1913,36 @@ function client(directoryUrl, opts) {
       });
     });
   }
+  function _newAuthz(identifier) {
+    return Promise.resolve().then(function () {
+    // Reject a wildcard / bad AUTHORIZATION identifier BEFORE any network (sec. 7.4.1); the builder re-checks. Bind
+    // to the CANONICAL { type, value } (a single validated read), so the wire body, the sent identifier, and the
+    // returned-authz comparison below all use the same values -- never a getter that could re-read differently.
+    var canon = _validateIdentifier(identifier);
+    return _resource("newAuthz").then(function (url) {
+      // 201 (Created) is the norm (RFC 8555 sec. 7.4.1), but a CA that returns an already-existing authorization
+      // (the out-of-band valid case) MAY answer 200 (OK) -- the authz was not newly created -- just as newAccount
+      // accepts 200 for an existing account. Accept both; the Location + object are validated below regardless.
+      return _post(url, newAuthz, { identifier: canon }, "kid", undefined, [200, 201]).then(function (res) {
+        var loc = res.headers["location"];
+        if (!_isString(loc)) throw E("acme/no-authorization-url", "newAuthz did not return an authorization URL in a Location header (RFC 8555 sec. 7.4.1)");
+        var authz = validate("authorization", _json(res));
+        // Bind the returned authorization to the SUBMITTED identifier (sec. 7.4.1): a server returning an authz
+        // for a different identifier is not silently accepted. The submitted identifier is always non-wildcard
+        // (_validateIdentifier rejects a leading *.), so an authz the CA marks wildcard:true (sec. 7.1.4 -- it
+        // authorizes *.<value>, a BROADER grant than requested) is a mismatch, not the authorization asked for.
+        if (!authz.identifier || authz.identifier.type !== canon.type || authz.identifier.value !== canon.value || authz.wildcard === true) throw E("acme/identifier-mismatch", "the returned authorization does not match the requested identifier (RFC 8555 sec. 7.4.1)");
+        // A pre-authorization's status "MUST be 'pending' unless the server has out-of-band information about the
+        // client's authorization status" (sec. 7.4.1): the normal case is a fresh "pending" authz the caller then
+        // fulfils, but the CA MAY instead return an already-"valid" authz (the identifier is already authorized for
+        // this account -- no challenge to answer). Both are usable; only a terminal failed state ("invalid"/
+        // "deactivated"/"expired"/"revoked") is not the authorization the pre-auth flow can proceed with.
+        if (authz.status !== "pending" && authz.status !== "valid") throw E("acme/unexpected-authorization-status", "newAuthz returned an authorization that is neither pending nor already valid (status " + JSON.stringify(authz.status) + "); RFC 8555 sec. 7.4.1");
+        return { authorization: authz, 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)); }); }
@@ -1519,17 +1999,63 @@ function client(directoryUrl, opts) {
   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: [] };
+  // Read + strictly validate a downloaded chain response into { certificate, chain, certificates }. The caller
+  // routes through _post (okStatuses [200]), so a non-200 has already thrown _serverProblem before this runs.
+  function _readCertChain(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 };
+  }
+  function _fetchCertChain(url) { return _post(url, postAsGet, null, "kid", "application/pem-certificate-chain").then(_readCertChain); }
+
+  function _downloadCertificate(url, opts) {
+    opts = opts || {};
+    // Prelude in a resolved-promise .then so a bad opt / URL is a REJECTION, uniform for a .catch caller.
+    return Promise.resolve().then(function () {
+      var select = opts.selectChain;
+      if (select !== undefined && typeof select !== "function") throw E("acme/bad-input", "downloadCertificate opts.selectChain must be a function");
+      var maxAlt = guard.limits.cap(opts.maxAlternates, "maxAlternates", DEFAULT_MAX_ALTERNATES, { E: E, code: "acme/bad-input", min: 0, max: 64 });
+      var dlUrl = _clientUrl(url);
+      return _post(dlUrl, postAsGet, null, "kid", "application/pem-certificate-chain").then(function (res) {
+        var primary = _readCertChain(res);
+        // The Link header is UNTRUSTED. Parse it now but DEFER any malformed-header error: a malformed Link is
+        // fatal only if the alternates are actually needed (the primary itself is rejected below). So a broken
+        // or hostile Link can never deny a valid primary download -- whether the caller is selecting or not.
+        var alternates = [], linkError = null;
+        try { alternates = _parseLinkAlternates(res.headers, dlUrl); }
+        catch (e) { linkError = e; }
+        function result(cand) { return { certificate: cand.certificate, chain: cand.chain, certificates: cand.certificates, alternates: alternates }; }
+        if (!select) return result(primary);
+        // Selection: consider the PRIMARY first, then each alternate in header order, bounded by maxAlt
+        // (CWE-770 fetch amplification). selectChain MAY be async -- await its result (Promise.resolve wraps a
+        // sync return too) so a returned Promise is never treated as always-truthy. The first truthy wins. An
+        // alternate whose end-entity certificate differs from the primary's violates sec. 7.4.2 ("starting with
+        // the same end-entity certificate") -- fail closed rather than accept a substituted leaf. A predicate
+        // throw / rejection propagates unswallowed. Exhausting the budget with alternates left unfetched is
+        // acme/too-many-alternates; fetching every alternate with no match is acme/no-matching-chain.
+        return Promise.resolve(select(primary)).then(function (primaryMatch) {
+          if (primaryMatch) return result(primary);
+          // The primary was rejected, so the alternates ARE needed now -- a malformed Link finally fails closed.
+          if (linkError) throw linkError;
+          var leaf = primary.certificate, toFetch = alternates.slice(0, maxAlt), overBudget = alternates.length > maxAlt, idx = 0;
+          function next() {
+            if (idx >= toFetch.length) {
+              if (overBudget) throw E("acme/too-many-alternates", "no acceptable chain within the maxAlternates=" + maxAlt + " fetch budget (RFC 8555 sec. 7.4.2, CWE-770)");
+              throw E("acme/no-matching-chain", "no downloaded chain satisfied selectChain (RFC 8555 sec. 7.4.2)");
+            }
+            return _fetchCertChain(toFetch[idx++]).then(function (cand) {
+              if (!cand.certificate.equals(leaf)) throw E("acme/bad-alternate", "an alternate chain did not start with the same end-entity certificate (RFC 8555 sec. 7.4.2)");
+              return Promise.resolve(select(cand)).then(function (m) { return m ? result(cand) : next(); });
+            });
+          }
+          return next();
+        });
+      });
     });
   }
 
@@ -1582,10 +2108,23 @@ function client(directoryUrl, opts) {
   }
 
   // ARI RenewalInfo (RFC 9773 sec. 4.1) -- the SOLE UNAUTHENTICATED GET (no JWS, no nonce).
-  function _renewalInfo(certDer) {
+  function _renewalInfo(certDer, clockFn, retryAfterCapSeconds) {
     if (!Buffer.isBuffer(certDer)) throw E("acme/bad-input", "renewalInfo requires a DER certificate Buffer");
+    var _rawClk = typeof clockFn === "function" ? clockFn : clock;   // renewalWindow may pass a per-call clock
+    // The clock MUST return finite epoch ms: a NaN / Infinity would make the expiry comparison below silently
+    // false and bypass the RFC 9773 sec. 4.3 gate, so the validating wrapper fails closed on a non-finite value.
+    function clk() { var t = _rawClk(); if (typeof t !== "number" || !isFinite(t)) throw E("acme/bad-input", "the renewalInfo clock returned a non-finite value"); return t; }
+    // RFC 9773 sec. 4.3: a client MUST NOT check a certificate's RenewalInfo after it has expired. Gate BEFORE the
+    // unauthenticated GET -- the same expiry test renewalWindow applies -- so the raw verb cannot query a dead cert.
+    var notAfterMs = x509.parse(certDer).validity.notAfter.getTime();
+    // allow:nan-date-comparison-unguarded -- notAfter is a codec-parsed cert date (asn1 readTime rejects a NaN instant).
+    if (clk() > notAfterMs) throw E("acme/certificate-expired", "the certificate is already past its notAfter; a client MUST NOT check RenewalInfo after it has expired (RFC 9773 sec. 4.3)");
     var certId = ariCertId(certDer);
     return _resource("renewalInfo").then(function (base) {
+      // Re-check expiry immediately BEFORE the GET: the directory fetch above (uncached) can take long enough that a
+      // certificate close to notAfter crosses it in between, and RFC 9773 sec. 4.3 forbids the query after expiry.
+      // allow:nan-date-comparison-unguarded -- notAfterMs is a codec-parsed cert date; clk() is validated finite.
+      if (clk() > notAfterMs) throw E("acme/certificate-expired", "the certificate expired before the RenewalInfo request could be issued; a client MUST NOT check RenewalInfo after expiry (RFC 9773 sec. 4.3)");
       // 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);
@@ -1596,16 +2135,107 @@ function client(directoryUrl, opts) {
         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;
+        if (typeof ra === "string" && ra.trim() !== "") {
+          // renewalWindow passes a cap: the Retry-After is ADVISORY there and is clamped anyway, so a huge or
+          // unparseable value must clamp / drop to null (renewalWindow then defaults) rather than discard the
+          // validated window. The raw renewalInfo verb (no cap) stays strict -- a bad Retry-After fails closed.
+          var raOpts = { now: clk(), E: E, code: "acme/bad-retry-after" };
+          if (typeof retryAfterCapSeconds === "number") { raOpts.cap = retryAfterCapSeconds; raOpts.lenient = true; }
+          retryAfterSeconds = retryAfter.parse(ra, raOpts).retryAfterSeconds;
+        }
         return { renewalInfo: obj, retryAfterSeconds: retryAfterSeconds };
       });
     });
   }
 
+  // ARI renewal-window decision (RFC 9773 sec. 4.2 / 4.3) -- a pure, timer-less helper that composes the
+  // unauthenticated renewalInfo GET, picks a uniform-random instant in the CA's suggested window, and
+  // returns the decision as DATA. It never sleeps or schedules: an auto-renewing daemon is an explicit
+  // future opt-in, not a hidden timer inside the thin client.
+  function _renewalWindow(certDer, o) {
+    o = o || {};
+    return Promise.resolve().then(function () {
+      if (!Buffer.isBuffer(certDer)) throw E("acme/bad-input", "renewalWindow requires a DER certificate Buffer");
+      if (o.random !== undefined && typeof o.random !== "function") throw E("acme/bad-input", "renewalWindow opts.random must be a function returning a number in [0, 1]");
+      if (o.clock !== undefined && typeof o.clock !== "function") throw E("acme/bad-input", "renewalWindow opts.clock must be a function returning epoch milliseconds");
+      // replaced is the sec. 4.3 "MUST NOT act on a replaced certificate" signal: require a real boolean so a
+      // truthy non-boolean (a caller storing replacement state as a timestamp/object) cannot fail OPEN past
+      // the gate below (=== true would let it through) and issue the RenewalInfo GET the RFC forbids.
+      if (o.replaced !== undefined && typeof o.replaced !== "boolean") throw E("acme/bad-input", "renewalWindow opts.replaced must be a boolean");
+      // opts.previous is a prior renewalWindow RESULT the caller stored: RFC 9773 sec. 4.2 says the client SHOULD
+      // store the selected time and reuse it, so refreshing ARI (a later call after retryAfterSeconds) keeps the
+      // SAME renewal instant while the CA's window is unchanged rather than re-randomizing and jittering it.
+      if (o.previous !== undefined && !_isObject(o.previous)) throw E("acme/bad-input", "renewalWindow opts.previous must be a prior renewalWindow result object");
+      // A per-call clock (documented opt) overrides the client's receipt clock for the WHOLE decision -- the
+      // expiry gate, the renew-now comparison, and the RenewalInfo Retry-After parse -- so a caller can ask
+      // "should I renew as of time T?" deterministically without reconfiguring the client. Every READING must
+      // be a finite epoch ms: a NaN / Infinity would make each relational comparison silently false and bypass
+      // the expiry gate, so the validating wrapper fails closed on a non-finite value.
+      var _clk = typeof o.clock === "function" ? o.clock : clock;
+      function clk() { var t = _clk(); if (typeof t !== "number" || !isFinite(t)) throw E("acme/bad-input", "the renewalWindow clock returned a non-finite value"); return t; }
+      // RFC 9773 sec. 4.3: a client MUST NOT act on renewal info for a certificate it can no longer use --
+      // one already past its notAfter (nothing to renew) or one the caller knows has been replaced. Gate
+      // BEFORE the fetch so a decommissioned certificate never even reaches the CA.
+      var notAfter = x509.parse(certDer).validity.notAfter;
+      var now = clk();
+      // Exclusive of notAfter: X.509 validity is inclusive of notAfter (a cert is still valid AT it), matching
+      // path-validate's `t > notAfter` expiry test -- only a cert strictly past notAfter has nothing to renew.
+      // allow:nan-date-comparison-unguarded -- notAfter is a codec-parsed cert date (asn1 readTime rejects a NaN
+      // instant) and the window start/end below are rfc3339-validated by validateRenewalInfo; neither is NaN.
+      if (now > notAfter.getTime()) throw E("acme/certificate-expired", "the certificate is already past its notAfter; there is nothing to renew (RFC 9773 sec. 4.3)");
+      if (o.replaced === true) throw E("acme/certificate-replaced", "the caller asserts this certificate has already been replaced (RFC 9773 sec. 4.3)");
+      return _renewalInfo(certDer, clk, RENEWAL_RETRY_MAX_SECONDS).then(function (ri) {
+        var w = ri.renewalInfo.suggestedWindow;
+        // start/end are grammar+calendar-validated RFC 3339 by validateRenewalInfo (an inverted window has
+        // already thrown acme/bad-renewal-window), so neither Date.parse is NaN and end > start here.
+        var startMs = Date.parse(w.start), endMs = Date.parse(w.end);
+        // Bound the window by the certificate's own expiry: a renewal instant AFTER notAfter is useless (you
+        // must renew BEFORE the cert dies), so a CA suggestedWindow that extends past notAfter is clamped to it
+        // -- selection stays uniform within the still-valid sub-window. If the whole window is past notAfter,
+        // effStart collapses to effEnd (renew at the last valid instant).
+        var notAfterMs = notAfter.getTime();
+        var effEnd = Math.min(endMs, notAfterMs), effStart = Math.min(startMs, effEnd);
+        // RFC 9773 sec. 4.2: if the caller passed a prior result (opts.previous) whose suggestedWindow is UNCHANGED,
+        // REUSE its selectedTime (clamped to the still-valid, notAfter-bounded window) instead of drawing again, so
+        // repeated ARI refreshes converge on one stable renewal instant. A changed window (or no prior) draws fresh.
+        var pw = o.previous && _isObject(o.previous.suggestedWindow) ? o.previous.suggestedWindow : null;
+        var selectedMs;
+        if (pw && pw.start === w.start && pw.end === w.end && _isString(o.previous.selectedTime)) {
+          var prevMs = Date.parse(o.previous.selectedTime);
+          if (!isFinite(prevMs)) throw E("acme/bad-input", "renewalWindow opts.previous.selectedTime must be an RFC 3339 date-time");
+          selectedMs = Math.max(effStart, Math.min(effEnd, prevMs));
+        } else {
+          // Validate the draw's TYPE, never coerce: Number(null)/Number(false) -> 0, Number("0.5") -> 0.5 would
+          // silently accept a non-number callback return. Require an actual number in [0, 1].
+          var draw = o.random ? o.random() : _defaultRandom();
+          if (typeof draw !== "number" || !(draw >= 0 && draw <= 1)) throw E("acme/bad-input", "renewalWindow opts.random must return a number in [0, 1]");
+          // select a uniform-random instant across the (validity-bounded) window to spread renewals; if it is
+          // already in the past, the caller should renew immediately.
+          selectedMs = Math.round(effStart + draw * (effEnd - effStart));
+        }
+        var retryAfterSeconds = ri.retryAfterSeconds == null ? RENEWAL_RETRY_DEFAULT_SECONDS :
+          Math.max(RENEWAL_RETRY_MIN_SECONDS, Math.min(RENEWAL_RETRY_MAX_SECONDS, ri.retryAfterSeconds));
+        return {
+          suggestedWindow: w,
+          selectedTime: new Date(selectedMs).toISOString(),
+          // Decide renew-now against a FRESH clock read: the RenewalInfo GET may itself span the selected
+          // instant, so the pre-fetch `now` (used above only for the expiry gate) could be stale here. Also
+          // renew now when the SELECTED instant lands at or past notAfter -- whether the whole window opened
+          // after expiry or a straddling window's draw hit the clamp endpoint, there is no margin left, so
+          // waiting for the (clamped) time would leave the cert to expire unrenewed.
+          renewNow: selectedMs <= clk() || selectedMs >= notAfterMs,
+          retryAfterSeconds: retryAfterSeconds,
+          explanationURL: _isString(ri.renewalInfo.explanationURL) ? ri.renewalInfo.explanationURL : null,
+        };
+      });
+    });
+  }
+
   return {
     directory: _directory,
     newAccount: _newAccount,
     newOrder: _newOrder,
+    newAuthz: _newAuthz,
     getOrder: _getOrder,
     getAuthorization: _getAuthorization,
     getChallenge: _getChallenge,
@@ -1619,6 +2249,7 @@ function client(directoryUrl, opts) {
     deactivateAuthorization: _deactivateAuthorization,
     keyChange: _keyChange,
     renewalInfo: _renewalInfo,
+    renewalWindow: _renewalWindow,
   };
 }
 
@@ -1639,6 +2270,7 @@ module.exports = {
   newAccount: newAccount,
   externalAccountBinding: externalAccountBinding,
   newOrder: newOrder,
+  newAuthz: newAuthz,
   finalize: finalize,
   challengeResponse: challengeResponse,
   deactivate: deactivate,

package/lib/http-retry-after.js

@@ -70,25 +70,34 @@ function httpDateMs(s, refMs) {
 // 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.
+// opts.cap (seconds) clamps a value above the cap to the cap instead of rejecting it; opts.lenient surfaces
+// an otherwise-rejected value as a null retryAfterSeconds -- both for a caller (e.g. an ARI poll cadence)
+// for whom the value is advisory and must not discard the response. 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)");
+    // opts.cap (seconds): a caller that will clamp anyway (e.g. an ARI poll cadence) wants a delay ABOVE its
+    // ceiling reduced to the ceiling, not rejected -- so a valid-but-huge value never discards the response.
+    if (typeof opts.cap === "number" && n > opts.cap) { out.retryAfterSeconds = opts.cap; return out; }
+    // opts.lenient: a caller for whom the value is purely advisory wants an UNPARSEABLE one surfaced as
+    // null (retryAfterSeconds stays null) rather than a hard reject that would discard the whole response.
+    if (!Number.isSafeInteger(n) || n > MAX_RETRY_AFTER_SECONDS) { if (opts.lenient) return out; 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));
+  if (isNaN(when)) { if (opts.lenient) return out; 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)");
+    if (typeof opts.cap === "number" && d > opts.cap) { out.retryAfterSeconds = opts.cap; return out; }
+    if (d > MAX_RETRY_AFTER_SECONDS) { if (opts.lenient) return out; throw _fail(opts, "the Retry-After date is beyond the supported horizon (" + MAX_RETRY_AFTER_SECONDS + " seconds)"); }
     out.retryAfterSeconds = d;
   }
   return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "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:ea40d20f-ad92-403e-8de1-cfd14bead6ba",
+  "serialNumber": "urn:uuid:3a0c2231-58bb-4cd0-ae0c-88a58b06b1bf",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-01T18:47:21.356Z",
+    "timestamp": "2026-08-02T13:10:19.880Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.28",
+      "bom-ref": "@blamejs/pki@0.3.29",
       "type": "application",
       "name": "pki",
-      "version": "0.3.28",
+      "version": "0.3.29",
       "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.28",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.28",
+      "ref": "@blamejs/pki@0.3.29",
       "dependsOn": []
     }
   ]