@blamejs/pki 0.3.27 → 0.3.28

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.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.
+
+### Added
+
+- pki.est.serverkeygen(baseUrl, csr, opts?) requests a server-generated key pair + certificate (RFC 7030 sec. 4.4): it POSTs the CSR (application/pkcs10, identical encoding to simpleenroll) to /.well-known/est/serverkeygen and returns { certificates, privateKey } for a cleartext PKCS#8 PrivateKeyInfo key part, { certificates, encryptedKey } for a CMS EnvelopedData key part (surfaced structurally, never decrypted), or { retry, retryAfterSeconds, retryAfterDate } on a 202. The certificates are returned raw (no leaf is selected -- the CA generated the key, so the issued certificate carries the generated public key, not the throwaway CSR key). A cleartext key is bound to its certificate before it is surfaced: the delivered private key's public half must match exactly one returned certificate, so a key mis-associated with the returned certificate set is refused rather than handed back unusable. Whether the key part must be encrypted, and to which recipient, is derived from the CSR's DecryptKeyIdentifier (a symmetric key-encryption key) or AsymmetricDecryptKeyIdentifier (an asymmetric key) attribute; the recipient MECHANISM is preserved and required to match the RecipientInfo arm, so a symmetric KEK recipient never satisfies an advertised asymmetric key (or vice versa) merely because the identifier bytes coincide. An opts value that contradicts the CSR is refused, and a cleartext key delivered where the CSR requested encryption is refused, as is an encrypted key delivered where the CSR advertised no decryption key to open it (an unusable, unsolicited credential). The delivered key's channel must negotiate a confidentiality-bearing cipher (a NULL / anonymous / EXPORT suite is refused). https-only, explicit-anchor, and the full redirect / auth / budget machinery of the enrollment verbs apply.
+- pki.est.csrattrs(baseUrl, opts?) fetches the CA's CSR-attributes policy (RFC 7030 sec. 4.5, RFC 9908): a 200 application/csrattrs body is parsed and returned as { available: true, attrs, plan }, where plan is the enroll-attribute plan the caller builds its next CSR from; a 204 or 404 is { available: false } (a valid "CSR Attributes Response not available"); an empty CsrAttrs is a complete empty policy. The verb never applies attributes to a CSR itself. Server authentication is not required for this policy GET, but a 401 is honored so the auth path stays available.
+- HTTP Digest access authentication (RFC 7616) is available on every EST verb as an alternative to HTTP Basic via opts.auth = { scheme: "digest", username, password }. SHA-256 and SHA-512-256 are supported; MD5 and MD5-sess are refused unless opts.auth.allowMD5 is set, and a legacy no-qop (RFC 2069) challenge is refused unless opts.auth.allowLegacyQop is set. Among multiple offered challenges the most secure USABLE one is chosen -- a challenge this client cannot answer under its policy (an unsupported or disallowed algorithm, or a qop mode it does not accept) never shadows a lower-ranked usable one, so the client authenticates on a usable offer instead of picking the strongest and failing; when no offer is usable it fails closed with the specific reason rather than downgrading to a weaker scheme. A server stale=true re-challenge is answered under a bounded opts.auth.maxStaleRetries budget. The response is scoped to the challenge's protection space: within an origin it is preemptively reused only for the URIs the challenge's domain directive covers (a quoted directive -- a malformed unquoted one is refused, not silently widened; an absolute-URI entry is matched by its authority as well as its path, so an entry naming a different host never widens the scope to this one; the query is kept in the comparison, so an entry scoped to one query does not cover a different one), and a same-origin resource outside that scope is authenticated afresh (bounded) -- classified by whether the request actually carried a credential, so a resource sent unauthenticated is never mistaken for a rejected one -- rather than sent the first realm's response or blocked outright. A non-ASCII username under a charset=UTF-8 challenge is carried in the RFC 5987 username* extended form (percent-encoded UTF-8) rather than the legacy quoted field a server would read as ISO-8859-1, and a non-ASCII realm's incoming header octets are hashed unchanged, so a UTF-8 realm contributes the same octets the server used and the response matches an RFC 7616 server. As with Basic, the credential is answered only on the origin the caller authenticated to -- never sent to a redirected origin, and never as a silent Basic downgrade of a Digest challenge.
+
 ## v0.3.27 — 2026-07-31
 
 pki.cmp.session drives a full CMP certificate enrollment end to end -- build, transfer, and verify every leg of an ir/cr/kur/p10cr exchange, with every response protection-checked before its body is read.

package/README.md

@@ -216,7 +216,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.pkcs12` | Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores — key bags via the PKCS#8 parser, shrouded keys (algorithm surfaced, ciphertext opaque), cert / CRL / secret bags raw and byte-exact, encrypted and enveloped safes structurally via CMS, `friendlyName` / `localKeyId` decoded, and the exact MAC byte range (`macedBytes`) plus RFC 9579 PBMAC1 recognition for external verification; BER accepted exactly where §4.1 requires it, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.cmp` | Parse DER / PEM RFC 9810 Certificate Management Protocol messages (PKIMessage) — the header (version, sender / recipient incl. the anonymous NULL-DN, nonces, transaction id, general info), the 27-arm body (certificate requests via the CRMF parser, an encrypted certificate's EnvelopedData via CMS, response / revocation / confirmation / error / support / polling arms structural, the rest raw), and the exact `headerBytes` / `bodyBytes` slices an external verifier reconstructs the protected part from; the CMP-before-OCSP dispatch order is enforced, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.csrattrs` | Parse DER EST CSR Attributes (`CsrAttrs`, RFC 8951 §3.5 / RFC 9908) — the `AttrOrOID` items a server sends to shape an enrollment: bare OIDs, attributes with raw values, and decoded views of the RFC 9908 meaningful types (extension requests, EC/RSA key-type conventions, the certification-request-info template). Unknown types tolerated (surfaced raw), fail-closed on structure and the RFC 9908 semantic MUSTs — `parse` |
-| `pki.est` | RFC 7030 / 8951 / 9908 Enrollment over Secure Transport — the thin client verbs `cacerts` / `simpleenroll` / `simplereenroll` drive the RFC 7030 flow over `pki.transport` (inject your own, or the fail-closed default): https-only, an explicit trust anchor required, same-origin redirects followed but a downgrade / loop refused, a 202 Retry-After surfaced (never slept), HTTP Basic answered only after the server is authenticated, and the issued certificate chosen by public-key match. Under them, the transport-agnostic codecs they compose — the RFC 8951 base64 transfer codec (blind to Content-Transfer-Encoding), the `multipart/mixed` splitter, the certs-only + serverkeygen response validators over CMS, the enroll-attribute builders, and the HTTP response classifier — `cacerts`, `simpleenroll`, `simplereenroll`, `transferDecode`/`transferEncode`, `parseCertsOnly`, `findIssuedCert`, `classifyResponse`, `paths`, and the builders |
+| `pki.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` |
@@ -272,9 +272,9 @@ certificate and writes a DER (or `--pem`) SignedData to `--out` or stdout.
 
 ### What's coming
 
-The remaining EST network verbs (`/serverkeygen`, `/csrattrs`, `/fullcmc`) and
-HTTP Digest auth, SCEP and CMC enrollment, and additional NIST-on-ramp PQC
-signatures as the OID registry admits them are on the roadmap and ride this same
+The remaining EST network verb (`/fullcmc`), SCEP and CMC enrollment, and
+additional NIST-on-ramp PQC signatures as the OID registry admits them are on
+the roadmap and ride this same
 core. See
 [ROADMAP.md](ROADMAP.md) for the full plan and current status of each area, and
 [CHANGELOG.md](CHANGELOG.md) for what has landed.

package/lib/constants.js

@@ -161,6 +161,10 @@ var LIMITS = {
   // document plus multipart/header overhead (16 MiB * 4/3 ~= 21.3 MiB); 24 MiB
   // clears it. An operator may only tighten it DOWNWARD via opts.maxResponseBytes.
   HTTP_MAX_RESPONSE_BYTES: BYTES.mib(24),
+  // A single untrusted WWW-Authenticate challenge header, bounded BEFORE the string
+  // is copied/tokenized so a hostile server cannot drive unbounded work parsing it
+  // (CWE-770). 8 KiB clears any realistic multi-scheme Digest challenge.
+  HTTP_AUTH_HEADER_MAX_BYTES: BYTES.kib(8),
   // Deterministic-CBOR codec ceilings (RFC 8949), the DER neighbours' siblings:
   // a whole-document cap refused before the walk, a nesting cap, and a per-value
   // bignum ceiling the document cap can't provide. Unlike DER_MAX_INTEGER_BYTES,

package/lib/est.js

@@ -57,10 +57,13 @@ var constants = require("./constants");
 var cms = require("./schema-cms");
 var x509 = require("./schema-x509");
 var pkcs8 = require("./schema-pkcs8");
+var key = require("./key");
 var csr = require("./schema-csr");
+var csrattrsFmt = require("./schema-csrattrs");   // aliased: the `csrattrs` name is the verb + the public export
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var httpTransport = require("./http-transport");
+var httpDigest = require("./http-digest");
 var retryAfter = require("./http-retry-after");
 
 var EstError = frameworkError.EstError;
@@ -175,7 +178,10 @@ function splitMultipartMixed(body, contentType) {
     var rawHeaders = seg.slice(0, sep);
     var partBody = seg.slice(sep).replace(/^(\r?\n){2}/, "").replace(/\r?\n$/, "");
     var headers = {};
-    rawHeaders.split(/\r?\n/).forEach(function (line) {
+    // Unfold MIME part headers (RFC 5322 sec. 2.2.3 / RFC 2046): a CRLF immediately followed by whitespace is a
+    // FOLD, not a header break, so it is removed before the split -- a Content-Type whose smime-type parameter
+    // continues on the next line must be read whole, not truncated.
+    rawHeaders.replace(/\r?\n(?=[ \t])/g, "").split(/\r?\n/).forEach(function (line) {
       var col = line.indexOf(":");
       if (col > 0) headers[line.slice(0, col).trim().toLowerCase()] = line.slice(col + 1).trim();
     });
@@ -235,14 +241,24 @@ function findIssuedCert(certs, target) {
 // Collect every key-identifier (subjectKeyIdentifier / KEKIdentifier) a set of
 // RecipientInfos names, across the ktri / kari / kekri / kemri arms -- the
 // byte identifiers a client's advertised decryptKeyID would match.
-function _recipientKeyIds(recipientInfos) {
+// The key-identifier bytes each RecipientInfo arm names, filtered by MECHANISM (RFC 7030 sec. 4.4.1): an
+// ASYMMETRIC decryption key (AsymmetricDecryptKeyIdentifier) is named by a subjectKeyIdentifier on a
+// KeyTrans / KeyAgree / KEM arm, a SYMMETRIC key (DecryptKeyIdentifier) by the keyIdentifier of a KEK arm.
+// Filtering keeps a symmetric KEK arm from satisfying an advertised asymmetric key (and vice-versa) merely
+// because the identifier bytes coincide -- the returned key would be unusable with the mechanism requested.
+// kind: "asymmetric" | "symmetric" | undefined (any, for a direct caller that did not state the mechanism).
+function _recipientKeyIds(recipientInfos, kind) {
   var ids = [];
   function push(v) { if (Buffer.isBuffer(v)) ids.push(v); }
   (recipientInfos || []).forEach(function (r) {
-    if (r.rid) push(r.rid.subjectKeyIdentifier);
-    if (r.kemri && r.kemri.rid) push(r.kemri.rid.subjectKeyIdentifier);   // KEMRecipientInfo (RFC 9629, under the ori arm)
-    if (r.kekid) push(r.kekid.keyIdentifier);
-    (r.recipientEncryptedKeys || []).forEach(function (rek) { if (rek.rid) push(rek.rid.subjectKeyIdentifier); });
+    if (kind !== "symmetric") {
+      if (r.rid) push(r.rid.subjectKeyIdentifier);
+      if (r.kemri && r.kemri.rid) push(r.kemri.rid.subjectKeyIdentifier);   // KEMRecipientInfo (RFC 9629, under the ori arm)
+      (r.recipientEncryptedKeys || []).forEach(function (rek) { if (rek.rid) push(rek.rid.subjectKeyIdentifier); });
+    }
+    if (kind !== "asymmetric") {
+      if (r.kekid) push(r.kekid.keyIdentifier);
+    }
   });
   return ids;
 }
@@ -266,11 +282,23 @@ function _recipientIssuerSerials(recipientInfos) {
 // form the server may have used to name the same requested key.
 function _recipientMatches(recipientInfos, opts) {
   if (Buffer.isBuffer(opts.expectedRecipientKeyId) &&
-      _recipientKeyIds(recipientInfos).some(function (id) { return id.equals(opts.expectedRecipientKeyId); })) return true;
+      _recipientKeyIds(recipientInfos, opts.expectedRecipientKind).some(function (id) { return id.equals(opts.expectedRecipientKeyId); })) return true;
   var ias = opts.expectedRecipientIssuerSerial;
   if (ias && Buffer.isBuffer(ias.issuer) && ias.serialNumber != null) {
-    var want = typeof ias.serialNumber === "bigint" ? ias.serialNumber : BigInt(ias.serialNumber);
-    if (_recipientIssuerSerials(recipientInfos).some(function (r) { return r.issuer.equals(ias.issuer) && r.serialNumber === want; })) return true;
+    // Validate the caller-supplied serial BEFORE BigInt() so a bad value is a typed est/bad-input, never a
+    // raw SyntaxError / RangeError leaking from the codec (the single choke point for both the serverkeygen
+    // verb and the public parseServerKeygenResponse).
+    var sn = ias.serialNumber, want;
+    if (typeof sn === "bigint" && sn >= 0n) want = sn;
+    else if (typeof sn === "number" && Number.isSafeInteger(sn) && sn >= 0) want = BigInt(sn);
+    else if (typeof sn === "string" && /^[0-9]+$/.test(sn)) want = BigInt(sn);
+    else throw E("est/bad-input", "expectedRecipientIssuerSerial.serialNumber must be a NON-NEGATIVE bigint, a safe non-negative integer, or a decimal digit string (a certificate serial is non-negative, RFC 5280 sec. 4.1.2.2)");
+    // An issuerAndSerialNumber names an ASYMMETRIC recipient -- a certificate identity the server derived from
+    // an AsymmetricDecryptKeyIdentifier (RFC 7030 sec. 4.4.2); a symmetric KEK recipient has none. So a SYMMETRIC
+    // request must NOT be satisfied by an asymmetric arm's issuer+serial, or the client would accept ciphertext
+    // undecryptable with the symmetric key it requested. The key-id branch applies the same mechanism filter.
+    if (opts.expectedRecipientKind !== "symmetric" &&
+        _recipientIssuerSerials(recipientInfos).some(function (r) { return r.issuer.equals(ias.issuer) && r.serialNumber === want; })) return true;
   }
   return false;
 }
@@ -337,6 +365,11 @@ function parseServerKeygenResponse(body, contentType, opts) {
   }
   if (!keyPart || !certPart) throw E("est/bad-multipart", "a serverkeygen response needs one key part and one certificate part");
   if (opts.requestedEncryption && !encrypted) throw E("est/expected-encrypted-key", "encryption was requested but the private-key part is cleartext (RFC 7030 sec. 4.4.2)");
+  // The reverse is also a mismatch: the CSR advertised NO key-encryption key (requestedEncryption explicitly
+  // false), yet the server returned an EnvelopedData. The client holds nothing to decrypt it, so an unsolicited
+  // encrypted key is an unusable credential, not a success (RFC 7030 sec. 4.4.2). (An undefined requestedEncryption
+  // -- a low-level caller not stating the mode -- stays permissive.)
+  if (opts.requestedEncryption === false && encrypted) throw E("est/unexpected-encrypted-key", "the server returned an encrypted key but the CSR advertised no DecryptKeyIdentifier / AsymmetricDecryptKeyIdentifier to decrypt it (RFC 7030 sec. 4.4.2)");
   var out = { certificates: parseCertsOnly(transferDecode(certPart.body)).certificates };
   if (encrypted) {
     // The server-generated key MUST be a CMS EnvelopedData (RFC 7030 sec. 4.4.2);
@@ -360,7 +393,13 @@ function parseServerKeygenResponse(body, contentType, opts) {
     }
     out.encryptedKey = parsedKey;
   } else {
-    out.privateKey = pkcs8.parse(transferDecode(keyPart.body));
+    var keyDer = transferDecode(keyPart.body);
+    out.privateKey = pkcs8.parse(keyDer);
+    // The raw cleartext PrivateKeyInfo DER is surfaced so a semantic layer can bind the key to its
+    // certificate (the public-key coherence check the verb runs). Structural parsing itself never
+    // does the crypto derivation -- mirroring parseCertsOnly, which splits certs while the enroll
+    // verb picks the issued one by public-key match.
+    out.privateKeyDer = keyDer;
   }
   return out;
 }
@@ -677,15 +716,35 @@ function _redirectTarget(current, location, method, opts) {
   return resolved;
 }
 
-// Does WWW-Authenticate advertise a Basic challenge? The quoted-string contents are blanked first
-// (a quoted auth-param may contain a comma + "Basic", e.g. `Digest realm="x, Basic required"`, which
-// must NOT be read as a Basic challenge), then Basic is matched as an auth-scheme TOKEN (at the start
-// or after a comma-separated challenge, followed by whitespace / a comma / end) -- never a substring,
-// so `Digest realm="basic"` / `Bearer error="basic required"` are not taken as Basic either.
-function _hasBasicChallenge(www) {
+// Does WWW-Authenticate advertise the given auth-scheme as a TOKEN? The quoted-string contents are blanked
+// first (a quoted auth-param may contain a comma + the scheme name, e.g. `Digest realm="x, Basic required"`,
+// which must NOT be read as a Basic challenge), then the scheme is matched at the start or after a
+// comma-separated challenge, followed by whitespace / a comma / end -- never a substring, so `Digest
+// realm="basic"` is not taken as Basic. `scheme` is always our own literal ("Basic" / "Digest").
+function _offersScheme(www, scheme) {
   var s = String(www || "").replace(/"(?:[^"\\]|\\.)*"/g, "\"\"");
-  return /(?:^|,)\s*Basic(?=[\s,]|$)/i.test(s);
+  return new RegExp("(?:^|,)\\s*" + scheme + "(?=[\\s,]|$)", "i").test(s);
+}
+// The chosen HTTP auth scheme: an explicit opts.auth.scheme wins; a legacy opts.username / opts.password
+// WITHOUT opts.auth means Basic (backwards compatible); otherwise none. There is NO scheme:"auto" -- a
+// Basic<->Digest downgrade is never silently chosen (a MITM stripping Digest to Basic must not succeed).
+function _authScheme(opts) {
+  if (opts.auth && opts.auth.scheme != null) {
+    var sc = String(opts.auth.scheme).toLowerCase();
+    if (sc !== "basic" && sc !== "digest") throw E("est/bad-input", "opts.auth.scheme must be \"basic\" or \"digest\"");
+    return sc;
+  }
+  if (opts.username !== undefined || opts.password !== undefined) return "basic";
+  return null;
 }
+function _authUser(opts) { return opts.auth && opts.auth.username !== undefined ? opts.auth.username : opts.username; }
+function _authPass(opts) { return opts.auth && opts.auth.password !== undefined ? opts.auth.password : opts.password; }
+// Credentials present -- an EMPTY username is allowed (RFC 7030 sec. 3.2.3), so "defined" (not "truthy").
+function _hasCreds(opts) { return _authUser(opts) !== undefined || _authPass(opts) !== undefined; }
+var DIGEST_CODES = { unsupportedAlgorithm: "est/digest-unsupported-algorithm", weakAlgorithm: "est/digest-weak-algorithm", noQop: "est/digest-no-qop", badChallenge: "est/digest-bad-challenge" };
+// The Digest answer policy, from opts.auth. The SAME object drives challenge SELECTION (parseChallenge) and
+// the ANSWER (answer), so the client never selects a challenge under one policy then answers under another.
+function _digestPolicy(opts) { return { allowMD5: !!(opts.auth && opts.auth.allowMD5), allowLegacyQop: !!(opts.auth && opts.auth.allowLegacyQop), codes: DIGEST_CODES }; }
 
 // The redirect-follow + HTTP-auth-retry loop. Returns the terminal transport response
 // ({status, headers, body}) -- a 2xx, a 202, or a non-401 4xx/5xx. A 3xx is followed
@@ -696,6 +755,9 @@ function _hasBasicChallenge(www) {
 function _drive(method, url, body, headers, opts, transport, budgets) {
   var redirects = 0;
   var authTried = false;
+  var staleRetries = 0;   // bounded re-answers to a Digest stale=true re-challenge (a fresh nonce), never an open loop
+  var authSpaces = 0;     // distinct Digest protection spaces (realms) entered beyond the first -- bounded so a server cannot loop with an endless stream of new realms
+  var lastDigestNonce = null;   // the nonce just answered -- a stale=true retry MUST carry a DIFFERENT (fresh) nonce
   var initialOrigin = url.origin;   // the origin the caller intended to authenticate to
   // The per-hop TLS: the origin-specific identity (mTLS cert/key + pinned SNI) is sent ONLY to the caller's
   // configured origin; a cross-origin hop gets a narrowed copy with those stripped (checkServerIdentity kept).
@@ -709,14 +771,30 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
     }
     return t;
   }
-  // The per-hop Authorization: the HTTP Basic credential (established after a 401 on the caller's origin) is
-  // sent ONLY to that origin. A cross-origin hop travels unauthenticated, but a redirect back to the origin
-  // restores it -- so an authenticated flow that bounces off-origin and returns still completes (mirrors _tlsFor).
+  // The per-hop Authorization, sent ONLY to the caller's origin (a cross-origin hop travels unauthenticated; a
+  // redirect back to the origin restores it -- mirrors _tlsFor). A Basic credential is target-INDEPENDENT, so it
+  // is cached whole in authValue. A Digest response is bound to the request method + target, so the CHALLENGE is
+  // cached and the answer is (re)computed for the CURRENT method / uri on every hop -- a same-origin redirect (or
+  // a 303 POST->GET) then gets a target-correct answer instead of a stale one the server would reject.
   var authValue = null;
+  var digestChallenge = null;
+  var digestNcByNonce = Object.create(null);   // nonce string -> count of requests answered under THAT nonce, tracked PER NONCE so a nonce reissued after others were used never repeats an nc (RFC 7616 sec. 3.4); bounded by the total answered 401s; a null-proto map so an attacker-chosen nonce (e.g. "__proto__") is an ordinary key
+  var digestSent = false;   // whether the LAST request actually carried a Digest Authorization -- the DIRECT signal that a following 401 rejects a credential, vs. is a fresh challenge for a request sent unauthenticated
   function _headersFor(u) {
-    if (!authValue || u.origin !== initialOrigin) return headers;
+    digestSent = false;
+    if (u.origin !== initialOrigin || (!authValue && !digestChallenge)) return headers;
     var hh = Object.assign({}, headers);
-    hh.authorization = authValue;
+    if (digestChallenge) {
+      // Preemptively reuse the cached answer only WITHIN the challenge's protection space (RFC 7616 sec. 3.5):
+      // a same-origin redirect to a URI outside the challenge's `domain` is sent unauthenticated, so the target
+      // resource's own challenge drives a fresh authentication instead of receiving an Authorization computed
+      // for the wrong protection space.
+      if (!httpDigest.inProtectionSpace(digestChallenge, u.origin, u.pathname + u.search)) return headers;
+      var nkey = digestChallenge.nonce;
+      digestNcByNonce[nkey] = (digestNcByNonce[nkey] || 0) + 1;
+      hh.authorization = httpDigest.answer(digestChallenge, { method: method, uri: u.pathname + u.search, username: _authUser(opts), password: _authPass(opts), body: body, nc: digestNcByNonce[nkey], policy: _digestPolicy(opts) }, E);
+      digestSent = true;
+    } else { hh.authorization = authValue; }
     return hh;
   }
   function step() {
@@ -751,17 +829,65 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
         return step();
       }
       if (status === 401) {
-        if (authTried) throw E("est/auth-required", "the server rejected the credentialed request (RFC 7030 sec. 3.2.3)");
-        // Answer a challenge ONLY on the origin the caller targeted: a 401 arriving after a
-        // cross-origin redirect is a different server, and the client MUST NOT send its credentials
-        // there (RFC 7030 sec. 3.6 -- credentials go only to an authorized server the caller chose).
+        // Answer a challenge ONLY on the origin the caller targeted: a 401 arriving after a cross-origin
+        // redirect is a different server, and the client MUST NOT send its credentials there (RFC 7030 sec. 3.6).
         if (url.origin !== initialOrigin) throw E("est/auth-required", "refusing to send HTTP credentials to a redirected origin (RFC 7030 sec. 3.6)");
         var www = String(h["www-authenticate"] || "");
-        if (!_hasBasicChallenge(www)) throw E("est/auth-required", "the server requires an unsupported HTTP authentication scheme (only Basic is supported): " + www);
-        if (opts.username === undefined && opts.password === undefined) throw E("est/auth-required", "the server requires HTTP authentication but no credentials were supplied (RFC 7030 sec. 3.2.3)");
+        // Bound the attacker-controlled challenge header BEFORE any scheme scan / copy (_offersScheme, the parser):
+        // an injected transport without its own header limit must not cause unbounded allocation or work despite
+        // the parser's own cap being applied later (CWE-400). The cap matches the Digest parser's.
+        if (www.length > constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES) throw E("est/auth-required", "the WWW-Authenticate header exceeds the " + constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES + "-byte cap (RFC 7030 sec. 3.2.3)");
+        var scheme = _authScheme(opts);
+        if (scheme === null) throw E("est/auth-required", "the server requires HTTP authentication but no credentials were supplied (RFC 7030 sec. 3.2.3)");
+        if (scheme === "digest") {
+          if (!_offersScheme(www, "Digest")) throw E("est/auth-required", "opts.auth.scheme is \"digest\" but the server offered no Digest challenge: " + www);
+          if (!_hasCreds(opts)) throw E("est/auth-required", "Digest authentication requires opts.auth.username / password (RFC 7030 sec. 3.2.3)");
+          // In a credential-rejection context (this request carried a Digest answer), bias selection toward a
+          // RETRYABLE stale=true offer so a stronger stale=false offer does not shadow one that could re-answer.
+          var selPol = _digestPolicy(opts);
+          selPol.preferStale = digestSent;
+          selPol.priorNonce = lastDigestNonce;   // a retryable stale offer must carry a nonce DIFFERENT from the one just rejected
+          selPol.priorRealm = digestChallenge && digestChallenge.realm;   // ...and be for the SAME realm that was rejected (a different realm is a new space, not a retry)
+          selPol.requestOrigin = url.origin;                       // prefer an offer whose protection space actually covers THIS request --
+          selPol.requestTarget = url.pathname + url.search;        // one scoped elsewhere cannot authenticate it and must not shadow one that can
+          var ch = httpDigest.parseChallenge(www, E, "est/digest-bad-challenge", selPol);
+          if (!ch) throw E("est/auth-required", "the server offered no usable Digest challenge: " + www);
+          // Whether this 401 REJECTS a credential turns on the DIRECT signal (RFC 7616 sec. 3.3 / 3.5): did the
+          // request that received it actually CARRY a Digest answer for THIS protection space? A request sent
+          // unauthenticated -- the first attempt, or one whose target lay outside the cached challenge's domain --
+          // has not authenticated, so its 401 (even in the same realm) is a FRESH challenge to answer, never a
+          // rejection. A credentialed request refused in the SAME realm IS a rejection of that credential: only a
+          // stale=true re-challenge carrying a FRESH nonce may retry (a repeated nonce with stale=true is a
+          // self-contradictory / hostile server -> terminate). Any fresh authentication -- the first, a newly
+          // entered protection space, or an unauthenticated resource -- is bounded (maxRedirects) against a loop.
+          if (digestSent && digestChallenge && ch.realm === digestChallenge.realm) {
+            if (!(ch.stale && ch.nonce !== lastDigestNonce && staleRetries < budgets.maxStaleRetries)) throw E("est/auth-required", "the server rejected the credentialed Digest request (RFC 7030 sec. 3.2.3)");
+            staleRetries += 1;
+          } else {
+            if (authTried && authSpaces >= budgets.maxRedirects) throw E("est/auth-required", "the server demanded Digest authentication for too many distinct protection spaces (RFC 7616 sec. 3.3)");
+            if (authTried) authSpaces += 1;
+            authTried = true;
+            staleRetries = 0;   // a fresh authentication (new space / unauthenticated resource) restarts the stale budget
+          }
+          lastDigestNonce = ch.nonce;
+          // Cache the CHALLENGE, not a fixed answer: _headersFor computes the response for the CURRENT method /
+          // request-target on each hop, so a same-origin redirect (or a 303 POST->GET) gets a target-correct answer
+          // rather than a stale one. A policy fault (MD5 / no-qop / unsupported) surfaces from _headersFor on the
+          // immediate re-send (the transport is not reached, so a rejected leg still proves calls did not advance).
+          // The nonce-count is tracked PER NONCE (digestNcByNonce), so a nonce reissued after other nonces were
+          // used in between resumes its own count -- a (nonce, nc) pair is never replayed, without a reset here.
+          digestChallenge = ch;
+          return step();
+        }
+        // Basic (default / explicit): the one-shot semantics unchanged.
+        if (authTried) throw E("est/auth-required", "the server rejected the credentialed request (RFC 7030 sec. 3.2.3)");
+        if (!_offersScheme(www, "Basic")) throw E("est/auth-required", "the server requires an unsupported HTTP authentication scheme (only Basic and Digest are supported): " + www);
+        // An explicit auth.scheme:"basic" with no credentials must fail closed too (an empty username stays legal),
+        // never transmit a "Basic Og==" (base64 of ":") the operator never supplied.
+        if (!_hasCreds(opts)) throw E("est/auth-required", "the server requires HTTP authentication but no credentials were supplied (RFC 7030 sec. 3.2.3)");
         // Establish the credential as origin-scoped state (_headersFor attaches it only on the initial origin),
         // never a mutation of the shared headers that would leak across a cross-origin redirect.
-        authValue = "Basic " + Buffer.from((opts.username || "") + ":" + (opts.password || ""), "utf8").toString("base64");
+        authValue = "Basic " + Buffer.from((_authUser(opts) || "") + ":" + (_authPass(opts) || ""), "utf8").toString("base64");
         authTried = true;
         return step();
       }
@@ -794,7 +920,9 @@ function _client(op, method, baseUrl, body, headers, opts) {
     timeout: guard.limits.cap(opts.timeout, "timeout", DEFAULT_TIMEOUT, { E: E, code: "est/bad-input", min: 1, max: MAX_TIMEOUT }),
     maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "est/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
     maxRedirects: guard.limits.cap(opts.maxRedirects, "maxRedirects", 5, { E: E, code: "est/bad-input", min: 0, max: 32 }),
+    maxStaleRetries: guard.limits.cap(opts.auth && opts.auth.maxStaleRetries, "maxStaleRetries", 1, { E: E, code: "est/bad-input", min: 0, max: 8 }),
   };
+  _authScheme(opts);   // config-time: a bad opts.auth.scheme throws est/bad-input here, never deferred to a 401
   return _drive(method, url, body, Object.assign({}, headers), opts, transport, budgets);
 }
 
@@ -944,10 +1072,205 @@ function simplereenroll(baseUrl, csrInput, opts) {
   });
 }
 
+// ---- /serverkeygen (RFC 7030 sec. 4.4) ----------------------------------
+
+// Derive the server-generated-key ENCRYPTION coherence from the CSR the caller actually POSTs (RFC 7030
+// sec. 4.4.1): a DecryptKeyIdentifier / AsymmetricDecryptKeyIdentifier attribute names the key-encryption
+// key the server must encrypt the generated private key to. Binding the expected recipient to the CSR (not a
+// free-floating opts boolean) closes the drift where a cleartext key rides past a caller who forgot the flag.
+function _serverkeygenEncryptionFromCsr(csrDer) {
+  var attrs = csr.parse(csrDer).attributes || [];
+  var keyId = null, kind = null;
+  for (var i = 0; i < attrs.length; i++) {
+    if (attrs[i].type !== OID_DECRYPT_KEY_ID && attrs[i].type !== OID_ASYMM_DECRYPT_KEY_ID) continue;
+    // DecryptKeyIdentifier names a SYMMETRIC key-encryption key; AsymmetricDecryptKeyIdentifier an ASYMMETRIC
+    // one (RFC 7030 sec. 4.4.1). The mechanism is preserved so the returned key part is matched to a compatible
+    // RecipientInfo arm, not merely one whose identifier bytes coincide.
+    var thisKind = attrs[i].type === OID_ASYMM_DECRYPT_KEY_ID ? "asymmetric" : "symmetric";
+    var vals = attrs[i].values || [];
+    if (vals.length !== 1) throw E("est/bad-input", "a serverkeygen key-identifier attribute must carry exactly one value (RFC 7030 sec. 4.4.1)");
+    var id;
+    try { id = asn1.read.octetString(asn1.decode(vals[0])); }
+    catch (e) { throw E("est/bad-input", "a serverkeygen key-identifier attribute value is not a valid OCTET STRING", e); }
+    if (keyId !== null && !keyId.equals(id)) throw E("est/bad-input", "the CSR advertised two different serverkeygen key identifiers (RFC 7030 sec. 4.4.1)");
+    if (kind !== null && kind !== thisKind) throw E("est/bad-input", "the CSR advertised both a symmetric (DecryptKeyIdentifier) and an asymmetric (AsymmetricDecryptKeyIdentifier) serverkeygen key -- the recipient mechanism is ambiguous (RFC 7030 sec. 4.4.1)");
+    keyId = id; kind = thisKind;
+  }
+  return { requestedEncryption: keyId !== null, expectedRecipientKeyId: keyId, expectedRecipientKind: kind };
+}
+
+// The delivered private key rides TLS confidentiality alone: a NULL / anonymous / EXPORT suite MUST NOT be
+// used to carry it (RFC 7030 sec. 4.4, sec. 6). Assert (never reconfigure) the negotiated cipher when the
+// transport surfaces it; an injected transport that reports no cipher is trusted (the test/loopback channel).
+function _assertConfidentialCipher(res) {
+  if (!res || !res.tls || !res.tls.cipher) return;
+  var c = res.tls.cipher;
+  var name = (String(c.name || "") + " " + String(c.standardName || "")).toUpperCase();
+  // EXPORT covers the RFC/IANA name; the OpenSSL short names use an EXP prefix followed by a separator OR a
+  // digit run (EXP-RC4-MD5, EXP1024-RC4-SHA), so match EXP before either -- a bare `\bEXP\b` misses EXP1024.
+  if (/NULL|ANON|EXPORT|\bEXP[-_0-9]|\bA(EC)?DH\b/.test(name)) throw E("est/weak-cipher", "the serverkeygen channel negotiated a NULL / anonymous / EXPORT cipher (" + (c.standardName || c.name) + "), which cannot protect the delivered private key (RFC 7030 sec. 4.4)");
+}
+
+// A case-insensitive header lookup: the injectable transport seam only promises { status, headers, body }, so a
+// hostile / non-Node transport may deliver "Content-Type" in any casing -- read it case-insensitively (classifyResponse
+// normalizes internally, but the multipart boundary is read from the header directly here).
+function _ciHeader(headers, name) {
+  headers = headers || {};
+  if (headers[name] !== undefined) return headers[name];
+  var lname = name.toLowerCase(), keys = Object.keys(headers);
+  for (var i = 0; i < keys.length; i++) { if (keys[i].toLowerCase() === lname) return headers[keys[i]]; }
+  return null;
+}
+
+async function _serverkeygenResult(res, opts, derived) {
+  var verdict = classifyResponse(res.status, res.headers, res.body, { op: "serverkeygen", now: opts.now });
+  // A 202 is an enrollment posture (RFC 7030 sec. 4.4 treats /serverkeygen as an enroll): surfaced, never slept.
+  if (verdict.status === "retry") return { retry: true, retryAfterSeconds: verdict.retryAfterSeconds, retryAfterDate: verdict.retryAfterDate };
+  if (verdict.status !== "ok") throw E("est/http-error", "an EST serverkeygen response must be HTTP 200 or 202 (RFC 7030 sec. 4.4.2), got " + res.status);
+  var bodyLen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "utf8");
+  if (bodyLen === 0) throw E("est/empty-body", "a 200 serverkeygen response carried an empty body (RFC 7030 sec. 4.4.2)");
+  _assertConfidentialCipher(res);
+  // parseServerKeygenResponse does the per-part transfer-decode; the recipient coherence is bound to the CSR.
+  var out = parseServerKeygenResponse(res.body, _ciHeader(res.headers, "content-type"), {
+    requestedEncryption: derived.requestedEncryption,
+    expectedRecipientKeyId: derived.expectedRecipientKeyId,
+    expectedRecipientKind: derived.expectedRecipientKind,
+    expectedRecipientIssuerSerial: opts.expectedRecipientIssuerSerial,
+  });
+  // Bind a CLEARTEXT server-generated key to its certificate (RFC 7030 sec. 4.4.2): the CA generated
+  // this pair and issued a certificate over its PUBLIC half, so the delivered PrivateKeyInfo's public key
+  // MUST equal EXACTLY ONE returned certificate's SubjectPublicKeyInfo -- a key unrelated to every
+  // certificate is an unusable / mis-associated credential, and a key matching more than one leaves the
+  // issued certificate ambiguous. Mirrors simpleenroll's findIssuedCert public-key match; the encrypted
+  // key stays opaque, so its recipient coherence is bound in the parser instead. The public half is
+  // derived through the key engine (never re-serialized here); a key whose public half cannot be derived
+  // is not bindable and fails closed.
+  if (out.privateKeyDer) {
+    var spki;
+    try { spki = await key.publicFromPrivate(out.privateKeyDer); }
+    catch (e) { throw E("est/key-cert-mismatch", "the cleartext server-generated private key's public half could not be derived to bind it to a returned certificate (RFC 7030 sec. 4.4.2)", e); }
+    var bound = findIssuedCert(out.certificates, spki);
+    if (!bound) throw E("est/key-cert-mismatch", "the cleartext server-generated private key matches no returned certificate's public key (RFC 7030 sec. 4.4.2)");
+    if (findIssuedCert(out.certificates.filter(function (c) { return c !== bound; }), spki)) throw E("est/ambiguous-issued-cert", "more than one returned certificate carries the server-generated key; the issued certificate is ambiguous (RFC 7030 sec. 4.4.2)");
+    delete out.privateKeyDer;
+  }
+  return out;
+}
+
+/**
+ * @primitive  pki.est.serverkeygen
+ * @signature  pki.est.serverkeygen(baseUrl, csr, opts?) -> Promise<{ certificates, privateKey } | { certificates, encryptedKey } | { retry, retryAfterSeconds, retryAfterDate }>
+ * @since      0.3.28
+ * @status     experimental
+ * @spec       RFC 7030, RFC 8951
+ * @related    pki.est.simpleenroll, pki.est.parseServerKeygenResponse
+ *
+ * Request a SERVER-GENERATED key pair + certificate: POST the CSR (base64 DER, `Content-Type:
+ * application/pkcs10`, identical request encoding to `simpleenroll`) to
+ * `<baseUrl>/.well-known/est/serverkeygen`. The two-part `multipart/mixed` response is surfaced as
+ * `{ certificates, privateKey }` (a cleartext PKCS#8 `PrivateKeyInfo`) or `{ certificates,
+ * encryptedKey }` (the CMS `EnvelopedData` the caller decrypts out-of-band with its key-encryption key --
+ * the verb NEVER decrypts, so it is not a decryption oracle), or `{ retry, retryAfterSeconds }` on a 202.
+ * The certificates are RAW/unordered -- unlike `simpleenroll` no leaf is picked, because the CA generated
+ * the key so the issued certificate's public key is the generated one, not the throwaway CSR key. A CLEARTEXT
+ * key is bound to its certificate before it resolves: the delivered private key's public half MUST match
+ * EXACTLY ONE returned certificate (`est/key-cert-mismatch` on none, `est/ambiguous-issued-cert` on more than
+ * one), so a mis-associated key is refused rather than handed back unusable.
+ * The encryption requirement + expected recipient are DERIVED from the CSR's own DecryptKeyIdentifier /
+ * AsymmetricDecryptKeyIdentifier attribute; an `opts` value that contradicts the CSR is `est/bad-input`
+ * (a cleartext-key downgrade cannot slip past). The delivered key's channel is asserted confidentiality-
+ * bearing (a NULL / anonymous / EXPORT cipher is `est/weak-cipher`). https-only, explicit-anchor, and the
+ * whole redirect / auth / budget machinery of `simpleenroll` apply.
+ *
+ * @opts
+ *   - `requestedEncryption` / `expectedRecipientKeyId` / `expectedRecipientIssuerSerial` -- OPTIONAL
+ *     overrides of the CSR-derived recipient coherence; a value that contradicts the CSR is `est/bad-input`.
+ *   - every option of pki.est.simpleenroll (transport, tls, label, budgets, credentials incl. `auth`).
+ * @example
+ *   var r = await pki.est.serverkeygen("https://ca.example", csrDer,
+ *     { transport: function () { return Promise.resolve({ status: 202, headers: { "retry-after": "60" }, body: "" }); } });
+ *   r.retry;   // true -- a 202 is surfaced, never slept
+ */
+function serverkeygen(baseUrl, csrInput, opts) {
+  opts = opts || {};
+  return Promise.resolve().then(function () {
+    var csrDer = _csrDer(csrInput);
+    var derived = _serverkeygenEncryptionFromCsr(csrDer);
+    if (opts.requestedEncryption !== undefined && !!opts.requestedEncryption !== derived.requestedEncryption) throw E("est/bad-input", "opts.requestedEncryption (" + !!opts.requestedEncryption + ") contradicts the CSR's advertised key-encryption attribute (" + derived.requestedEncryption + ") (RFC 7030 sec. 4.4.1)");
+    if (opts.expectedRecipientKeyId !== undefined) {
+      if (!Buffer.isBuffer(opts.expectedRecipientKeyId)) throw E("est/bad-input", "opts.expectedRecipientKeyId must be a Buffer");
+      if (derived.expectedRecipientKeyId && !opts.expectedRecipientKeyId.equals(derived.expectedRecipientKeyId)) throw E("est/bad-input", "opts.expectedRecipientKeyId contradicts the key identifier the CSR advertised (RFC 7030 sec. 4.4.1)");
+    }
+    if (opts.expectedRecipientIssuerSerial != null) {
+      var eis = opts.expectedRecipientIssuerSerial;
+      if (typeof eis !== "object" || Buffer.isBuffer(eis) || !Buffer.isBuffer(eis.issuer)) throw E("est/bad-input", "opts.expectedRecipientIssuerSerial must be { issuer: Buffer, serialNumber }");
+      var s = eis.serialNumber;
+      if (!((typeof s === "bigint" && s >= 0n) || (typeof s === "number" && Number.isSafeInteger(s) && s >= 0) || (typeof s === "string" && /^[0-9]+$/.test(s)))) throw E("est/bad-input", "opts.expectedRecipientIssuerSerial.serialNumber must be a NON-NEGATIVE bigint, a safe non-negative integer, or a decimal digit string (a certificate serial is non-negative, RFC 5280 sec. 4.1.2.2)");
+    }
+    // A recipient expectation implies the key part MUST be encrypted to that recipient; if the CSR advertised no
+    // key-encryption attribute the coherence check below never runs, so a compromised CA could deliver the key
+    // to a recipient IT controls (or cleartext) while the caller believes its pin was enforced. Refuse the
+    // contradiction at config time (RFC 7030 sec. 4.4.1) -- the caller must advertise the KEK in the CSR.
+    if ((opts.expectedRecipientKeyId !== undefined || opts.expectedRecipientIssuerSerial != null) && !derived.requestedEncryption) {
+      throw E("est/bad-input", "a recipient expectation (expectedRecipientKeyId / expectedRecipientIssuerSerial) implies an encrypted key, but the CSR advertised no DecryptKeyIdentifier / AsymmetricDecryptKeyIdentifier attribute (RFC 7030 sec. 4.4.1)");
+    }
+    return _client("serverkeygen", "POST", baseUrl, transferEncode(csrDer), { accept: "multipart/mixed", "content-type": "application/pkcs10" }, opts)
+      .then(function (res) { return _serverkeygenResult(res, opts, derived); });
+  });
+}
+
+// ---- /csrattrs GET (RFC 7030 sec. 4.5, RFC 9908) ------------------------
+
+function _csrattrsResult(res, opts) {
+  var verdict = classifyResponse(res.status, res.headers, res.body, { op: "csrattrs", now: opts.now });
+  // 204 / 404 = "CSR Attributes Response not available" -- a valid NONE outcome, not an error (RFC 7030 sec. 4.5.2).
+  if (verdict.status === "none-available") return { available: false, attrs: null };
+  // A 202 is nonconforming for a policy GET (sec. 4.5.2 lists only 200 / 204 / 404).
+  if (verdict.status === "retry") throw E("est/http-error", "a /csrattrs response must be HTTP 200, 204, or 404, not 202 (RFC 7030 sec. 4.5.2)");
+  if (verdict.status !== "ok") throw E("est/http-error", "an EST csrattrs response must be HTTP 200 / 204 / 404 (RFC 7030 sec. 4.5.2), got " + res.status);
+  var bodyLen = Buffer.isBuffer(res.body) ? res.body.length : Buffer.byteLength(String(res.body == null ? "" : res.body), "utf8");
+  // An empty HTTP body is distinct from a valid EMPTY CsrAttrs (`30 00` / base64 `MAA=`), which parses as {items:[]}.
+  if (bodyLen === 0) throw E("est/empty-body", "a 200 csrattrs response carried an empty body (RFC 7030 sec. 4.5.2)");
+  var attrs = csrattrsFmt.parse(transferDecode(res.body));
+  return { available: true, attrs: attrs, plan: buildEnrollAttributes(attrs) };
+}
+
+/**
+ * @primitive  pki.est.csrattrs
+ * @signature  pki.est.csrattrs(baseUrl, opts?) -> Promise<{ available: true, attrs, plan } | { available: false, attrs: null }>
+ * @since      0.3.28
+ * @status     experimental
+ * @spec       RFC 7030, RFC 8951, RFC 9908
+ * @related    pki.est.simpleenroll, pki.est.buildEnrollAttributes
+ *
+ * Fetch the CA's CSR-attributes policy: GET `<baseUrl>/.well-known/est/csrattrs` (`Accept:
+ * application/csrattrs`). A 200 body is base64-decoded, parsed as an RFC 9908 `CsrAttrs`, and returned
+ * with a `plan` (`buildEnrollAttributes`) the caller applies to its NEXT CSR -- the verb NEVER auto-applies
+ * attributes to a CSR (single responsibility). A 204 or 404 is `{ available: false }` (a valid "no specific
+ * attributes"), NOT an error; an empty SEQUENCE (`30 00`) is a COMPLETE empty policy (`attrs.items` empty),
+ * distinct from an empty HTTP body (`est/empty-body`). Server auth is NOT required for this policy GET but a
+ * 401 is tolerated (the shared auth path stays live). https-only + explicit-anchor as elsewhere.
+ *
+ * @opts
+ *   - every transport / tls / label / budget / credential option of the other verbs.
+ * @example
+ *   var r = await pki.est.csrattrs("https://ca.example",
+ *     { transport: function () { return Promise.resolve({ status: 404, headers: {}, body: "" }); } });
+ *   r.available;   // false -- a 404 is "no CSR-attributes policy available"
+ */
+function csrattrs(baseUrl, opts) {
+  opts = opts || {};
+  return Promise.resolve().then(function () {
+    return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts);
+  }).then(function (res) { return _csrattrsResult(res, opts); });
+}
+
 module.exports = {
   cacerts: cacerts,
   simpleenroll: simpleenroll,
   simplereenroll: simplereenroll,
+  serverkeygen: serverkeygen,
+  csrattrs: csrattrs,
   transferDecode: transferDecode,
   transferEncode: transferEncode,
   splitMultipartMixed: splitMultipartMixed,

package/lib/http-digest.js

@@ -0,0 +1,379 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- NOT on pki.*. HTTP Digest access authentication (RFC 7616): parse an UNTRUSTED
+// WWW-Authenticate challenge (fail-closed, quoted-string-honoring) and compute the Authorization
+// response header (byte-exact A1/A2/KD). Prefix-agnostic: every thrown code comes from the caller's
+// E(code, msg) FACTORY (never a defineClass class -- feedback_guard_error_factory_not_class) and its
+// policy.codes map, so pki.est composes it now and pki.acme / pki.cmp can reuse it as config, not a fork.
+//
+// The challenge is attacker-shaped: a comma inside a quoted value is NOT a delimiter (the _hasBasicChallenge
+// substring-scan bug class), a missing realm / nonce is REJECTED not defaulted, and an unsupported / weak
+// algorithm or a no-qop challenge fails closed rather than downgrading (feedback_guards_fail_closed_not_guess).
+
+var crypto = require("crypto");
+var constants = require("./constants");
+
+// Algorithm registry (a data row, not a switch -- Hard rule #2): rank orders the RFC 7616 sec. 3.7
+// "most secure the client can use" selection (SHA-512-256 > SHA-256 > MD5); an unknown algorithm ranks 0.
+var ALGS = {
+  "SHA-512-256": { hash: "sha512-256", rank: 3, sess: false }, "SHA-512-256-SESS": { hash: "sha512-256", rank: 3, sess: true },
+  "SHA-256": { hash: "sha256", rank: 2, sess: false }, "SHA-256-SESS": { hash: "sha256", rank: 2, sess: true },
+  "MD5": { hash: "md5", rank: 1, sess: false }, "MD5-SESS": { hash: "md5", rank: 1, sess: true },
+};
+var DEFAULT_CODES = {
+  unsupportedAlgorithm: "digest/unsupported-algorithm", weakAlgorithm: "digest/weak-algorithm",
+  noQop: "digest/no-qop", badChallenge: "digest/bad-challenge",
+};
+
+// H = lowercase-hex digest; the octet string is fed as latin1 so a UTF-8-encoded credential (charset=UTF-8)
+// is hashed over its exact bytes. KD(secret, data) = H(secret ":" data).
+function H(hash, s) { return crypto.createHash(hash).update(s, "latin1").digest("hex"); }
+function KD(hash, secret, data) { return H(hash, secret + ":" + data); }
+function _qstr(v) { return "\"" + String(v).replace(/(["\\])/g, "\\$1") + "\""; }
+
+// Split a header at commas that are OUTSIDE a quoted-string (a quoted comma is a literal, not a delimiter).
+function _commaSplitOutsideQuotes(s) {
+  var out = [], buf = "", inQ = false, esc = false;
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charAt(i);
+    if (esc) { buf += c; esc = false; continue; }
+    if (inQ && c === "\\") { buf += c; esc = true; continue; }
+    if (c === "\"") { inQ = !inQ; buf += c; continue; }
+    if (c === "," && !inQ) { out.push(buf); buf = ""; continue; }
+    buf += c;
+  }
+  out.push(buf);
+  return out;
+}
+// Index of the first '=' OUTSIDE a quoted-string, or -1.
+function _firstEqOutsideQuotes(s) {
+  var inQ = false, esc = false;
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charAt(i);
+    if (esc) { esc = false; continue; }
+    if (inQ && c === "\\") { esc = true; continue; }
+    if (c === "\"") { inQ = !inQ; continue; }
+    if (c === "=" && !inQ) return i;
+  }
+  return -1;
+}
+function _unq(s) { return s.slice(1, -1).replace(/\\(.)/g, "$1"); }   // only ever called on a well-formed quoted-string (see _closedQuote)
+// A well-formed quoted-string: opens with ", closes with an UNESCAPED " that is the LAST character (nothing trails
+// it). An unterminated / trailing-garbage quoted-string is malformed (RFC 7230 sec. 3.2.6) and rejected.
+function _closedQuote(s) {
+  if (s.length < 2 || s.charAt(0) !== "\"") return false;
+  var esc = false;
+  for (var i = 1; i < s.length; i++) {
+    var c = s.charAt(i);
+    if (esc) { esc = false; continue; }
+    if (c === "\\") { esc = true; continue; }
+    if (c === "\"") return i === s.length - 1;
+  }
+  return false;
+}
+// A control octet (RFC 7230 sec. 3.2.6 quoted-string / qdtext forbids CTL except HTAB). Scanned with charCodeAt
+// rather than a control-char regex literal (which eslint no-control-regex correctly refuses).
+function _hasCtl(s) {
+  for (var i = 0; i < s.length; i++) { var c = s.charCodeAt(i); if ((c < 0x20 && c !== 0x09) || c === 0x7f) return true; }
+  return false;
+}
+
+// Split a WWW-Authenticate header into [{ scheme, paramText }]. A comma-separated segment whose pre-'='
+// text is "token WS token" (a scheme name before the first auth-param key), or a bare token with no '=',
+// STARTS a new challenge; a "key=value" segment is a param continuation of the current challenge.
+function _splitChallenges(s) {
+  var segs = _commaSplitOutsideQuotes(s);
+  var out = [], cur = null;
+  for (var i = 0; i < segs.length; i++) {
+    var seg = segs[i].replace(/^\s+|\s+$/g, "");
+    if (seg === "") continue;
+    var eq = _firstEqOutsideQuotes(seg);
+    var pre = (eq < 0 ? seg : seg.slice(0, eq)).replace(/^\s+|\s+$/g, "");
+    var ws = /^(\S+)\s+(\S[\s\S]*)$/.exec(pre);
+    if (eq < 0) { cur = { scheme: seg, paramText: "" }; out.push(cur); }        // a bare scheme token (e.g. "Basic")
+    else if (ws) { cur = { scheme: ws[1], paramText: seg.replace(/^\s*\S+\s+/, "") }; out.push(cur); }   // "scheme firstKey=..."
+    else if (cur) { cur.paramText = cur.paramText ? cur.paramText + "," + seg : seg; }                   // "key=value" continuation
+  }
+  return out;
+}
+// Parse a challenge's params into { key(lower): { value, quoted } }; a repeated key is malformed (fail closed).
+function _parseParams(paramText, E, code) {
+  var segs = _commaSplitOutsideQuotes(paramText), map = Object.create(null);
+  for (var i = 0; i < segs.length; i++) {
+    var seg = segs[i].replace(/^\s+|\s+$/g, "");
+    if (seg === "") continue;
+    var eq = _firstEqOutsideQuotes(seg);
+    if (eq < 0) throw E(code, "malformed Digest auth-param (no '='): " + JSON.stringify(seg));
+    var key = seg.slice(0, eq).replace(/^\s+|\s+$/g, "").toLowerCase();
+    var rawVal = seg.slice(eq + 1).replace(/^\s+|\s+$/g, "");
+    var quoted = rawVal.charAt(0) === "\"";
+    if (quoted && !_closedQuote(rawVal)) throw E(code, "an unterminated or trailing-garbage Digest quoted-string (RFC 7230 sec. 3.2.6)");
+    if (Object.prototype.hasOwnProperty.call(map, key)) throw E(code, "repeated Digest auth-param " + JSON.stringify(key));
+    var value = quoted ? _unq(rawVal) : rawVal;
+    // Reject a control octet in any value (CR / LF / NUL / ...): it is a MUST-reject per RFC 7230 qdtext AND a
+    // header-injection sink -- an unescaped CR/LF reflected into the outgoing Authorization would split the header.
+    if (_hasCtl(value)) throw E(code, "a Digest auth-param value contains a control character (RFC 7230 sec. 3.2.6)");
+    map[key] = { value: value, quoted: quoted };
+  }
+  return map;
+}
+// Structural validation of ONE Digest challenge's params (RFC 7616 sec. 3.3). Throws on any violation.
+function _validateDigest(paramText, E, code) {
+  var p = _parseParams(paramText, E, code);
+  if (!p.realm || !p.realm.quoted || p.realm.value === "") throw E(code, "a Digest challenge requires a non-empty quoted realm (RFC 7616 sec. 3.3)");
+  if (!p.nonce || !p.nonce.quoted || p.nonce.value === "") throw E(code, "a Digest challenge requires a non-empty quoted nonce (RFC 7616 sec. 3.3)");
+  if (p.algorithm && p.algorithm.quoted) throw E(code, "the Digest algorithm must be a token, not a quoted-string (RFC 7616 sec. 3.3)");
+  var qop = [];
+  if (p.qop) {
+    if (!p.qop.quoted) throw E(code, "the Digest qop must be a quoted list (RFC 7616 sec. 3.3)");
+    qop = p.qop.value.split(",").map(function (x) { return x.replace(/^\s+|\s+$/g, "").toLowerCase(); }).filter(Boolean);
+    // A qop directive that is PRESENT but lists no value (qop="" / qop=", ,") is malformed -- it is NOT the
+    // absent-qop (RFC 2069) case. Reject it rather than silently collapsing to a no-qop response the server
+    // cannot accept (RFC 7616 sec. 3.3). Only an OMITTED qop directive selects the legacy no-qop path.
+    if (qop.length === 0) throw E(code, "a present Digest qop directive must list at least one value (RFC 7616 sec. 3.3)");
+  }
+  // domain (RFC 7616 sec. 3.3): a QUOTED, space-separated list of URIs defining the protection space. An
+  // UNQUOTED domain is malformed and rejected (fail closed like realm / nonce / qop) rather than silently
+  // widened -- widening a mis-encoded scope to "the whole server" would send credentials MORE broadly than the
+  // server intended. Surfaced as an array of the listed URIs, or null when omitted / quoted-empty -- which per
+  // the RFC means "all URIs on the responding server" (the answer may be reused for any same-origin URI, sec. 3.5).
+  if (p.domain && !p.domain.quoted) throw E(code, "the Digest domain must be a quoted-string (RFC 7616 sec. 3.3)");
+  var domain = (p.domain && p.domain.value.replace(/^\s+|\s+$/g, "") !== "")
+    ? p.domain.value.replace(/^\s+|\s+$/g, "").split(/\s+/) : null;
+  // charset (RFC 7616 sec. 3.3): the ONLY permitted value is the UNQUOTED token "UTF-8". A quoted charset, or any
+  // other value, is malformed -- answering it would hash the credentials in the wrong encoding -- so it is
+  // rejected (and thus skipped during multi-offer selection in favour of a conforming offer).
+  if (p.charset && (p.charset.quoted || String(p.charset.value).toUpperCase() !== "UTF-8")) throw E(code, "the Digest charset must be the unquoted token UTF-8 (RFC 7616 sec. 3.3)");
+  // stale (RFC 7616 sec. 3.3) is the unquoted token "true" or "false". A quoted or otherwise invalid value
+  // (stale=maybe) is malformed and rejected (thus skipped in selection) rather than parsed as a false flag that
+  // could shadow a conforming offer.
+  if (p.stale) {
+    var sv = String(p.stale.value).toLowerCase();
+    if (p.stale.quoted || (sv !== "true" && sv !== "false")) throw E(code, "the Digest stale directive must be the unquoted token true or false (RFC 7616 sec. 3.3)");
+  }
+  // userhash (RFC 7616 sec. 3.3) is likewise the unquoted token "true" or "false". A quoted or otherwise invalid
+  // value is malformed and rejected (skipped in selection) rather than silently changing how the username is sent.
+  if (p.userhash) {
+    var uhv = String(p.userhash.value).toLowerCase();
+    if (p.userhash.quoted || (uhv !== "true" && uhv !== "false")) throw E(code, "the Digest userhash directive must be the unquoted token true or false (RFC 7616 sec. 3.3)");
+  }
+  // opaque (RFC 7616 sec. 3.3) is a quoted-string echoed back verbatim. An UNQUOTED opaque is malformed and
+  // rejected (skipped in selection) rather than accepted, where it could shadow a conforming offer.
+  if (p.opaque && !p.opaque.quoted) throw E(code, "the Digest opaque directive must be a quoted-string (RFC 7616 sec. 3.3)");
+  return {
+    scheme: "Digest", realm: p.realm.value, nonce: p.nonce.value, qop: qop, domain: domain,
+    algorithm: p.algorithm ? p.algorithm.value.toUpperCase() : "MD5",
+    opaque: p.opaque ? p.opaque.value : null,
+    stale: !!(p.stale && String(p.stale.value).toLowerCase() === "true"),
+    userhash: !!(p.userhash && String(p.userhash.value).toLowerCase() === "true"),
+    charset: p.charset ? p.charset.value : null,
+  };
+}
+
+// parseChallenge(www, E, code, policy?) -> the most-secure USABLE structurally-valid Digest challenge,
+//   OR null (no Digest challenge present),  OR throw E(code) (a Digest challenge present but none valid).
+// Selection is policy-aware: a challenge answer() would refuse under the active policy (an unsupported /
+// MD5-when-disallowed algorithm, or a qop this client cannot satisfy) is ranked BELOW every usable one, so a
+// higher-algorithm-rank but unusable offer (e.g. a SHA-512-256 no-qop challenge under the default policy)
+// never shadows a lower-ranked usable one (e.g. SHA-256 with qop="auth") -- RFC 7616 sec. 3.3. When NO
+// challenge is usable the highest-algorithm-rank one is still returned, so answer() reports the specific
+// policy reason (which opt to set) rather than a generic "no challenge".
+function parseChallenge(www, E, code, policy) {
+  var pol = policy || {};
+  var codes = pol.codes || DEFAULT_CODES;
+  // preferStale marks a CREDENTIAL-REJECTION context (a 401 answering a credentialed request in the same space):
+  // there, a stale=true offer is RETRYABLE with a fresh nonce while a stale=false offer is a terminal rejection,
+  // so a retryable offer must outrank a stronger non-retryable one (RFC 7616 sec. 3.3). In the initial context
+  // it is not set and stale plays no part.
+  var preferStale = !!pol.preferStale;
+  var raw = String(www == null ? "" : www);
+  if (raw.length > constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES) throw E(code, "the WWW-Authenticate header exceeds the " + constants.LIMITS.HTTP_AUTH_HEADER_MAX_BYTES + "-byte cap");
+  var challenges = _splitChallenges(raw);
+  var best = null, bestUsable = false, bestApplicable = false, bestStale = false, bestRank = -1, sawDigest = false;
+  for (var i = 0; i < challenges.length; i++) {
+    if (challenges[i].scheme.toLowerCase() !== "digest") continue;
+    sawDigest = true;
+    var parsed;
+    // A MALFORMED offer is skipped, not fatal: parseChallenge's contract is to throw only when NO valid Digest
+    // offer exists (RFC 7616 sec. 3.3), so a bad offer alongside a good one still authenticates on the good one.
+    try { parsed = _validateDigest(challenges[i].paramText, E, code); }
+    catch (_e) {
+      continue;
+    }
+    var alg = ALGS[parsed.algorithm];
+    var rank = alg ? alg.rank : 0;
+    var usable = _rejection(parsed, pol, codes) === null;
+    // APPLICABLE: the offer's own protection space covers the CURRENT request target (RFC 7616 sec. 3.5). An
+    // offer whose `domain` excludes this request cannot authenticate it (the caller would omit the credential),
+    // so it must not shadow a weaker offer that does apply. Only checked when the caller supplies the request
+    // context; otherwise every offer is treated as applicable.
+    var applicable = pol.requestTarget === undefined ? true : inProtectionSpace(parsed, pol.requestOrigin, pol.requestTarget);
+    // A RETRYABLE offer (only meaningful in the rejection context) is stale=true, carries a FRESH nonce, AND is
+    // for the SAME realm whose credential was just rejected -- the conditions under which the caller re-answers.
+    // A stale offer for a DIFFERENT realm is a new protection space (not a retry), and a stale offer repeating
+    // the prior nonce cannot re-answer, so neither must out-rank a weaker genuinely retryable offer (RFC 7616 sec. 3.3).
+    var retryable = preferStale && !!parsed.stale && parsed.nonce !== pol.priorNonce && parsed.realm === pol.priorRealm;
+    // Usability dominates; then an offer that APPLIES to this request; then (in a rejection) a retryable offer;
+    // then the stronger algorithm.
+    if (best === null ||
+        (usable && !bestUsable) ||
+        (usable === bestUsable && applicable && !bestApplicable) ||
+        (usable === bestUsable && applicable === bestApplicable && retryable && !bestStale) ||
+        (usable === bestUsable && applicable === bestApplicable && retryable === bestStale && rank > bestRank)) {
+      best = parsed; bestUsable = usable; bestApplicable = applicable; bestStale = retryable; bestRank = rank;
+    }
+  }
+  if (best) return best;
+  if (sawDigest) throw E(code, "no valid Digest challenge: every Digest offer was malformed (missing realm / nonce or a bad directive, RFC 7616 sec. 3.3)");
+  return null;
+}
+
+// Credential octets for the given charset (RFC 7616 sec. 4): UTF-8 -> the exact UTF-8 bytes; else the
+// string as-is (ASCII / latin1). H() hashes over latin1, so a UTF-8 credential is fed as its octet string.
+function _octets(s, charset) {
+  var v = s == null ? "" : String(s);
+  return (charset && String(charset).toUpperCase() === "UTF-8") ? Buffer.from(v, "utf8").toString("latin1") : v;
+}
+
+// Does the string carry any non-ASCII code unit (> U+007F)? Such a UTF-8 username is sent via `username*`.
+function _hasNonAscii(s) {
+  s = String(s == null ? "" : s);
+  for (var i = 0; i < s.length; i++) { if (s.charCodeAt(i) > 0x7F) return true; }
+  return false;
+}
+
+// RFC 5987 / RFC 8187 percent-encoding of a string's UTF-8 octets: attr-char (ALPHA / DIGIT / "!#$&+-.^_`|~")
+// is kept literal, every other octet is %XX (upper-hex). Used for the Digest `username*` extended value.
+function _pctEncodeUtf8(s) {
+  var bytes = Buffer.from(String(s == null ? "" : s), "utf8");
+  var out = "";
+  for (var i = 0; i < bytes.length; i++) {
+    var b = bytes[i];
+    if ((b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) ||
+        b === 0x21 || b === 0x23 || b === 0x24 || b === 0x26 || b === 0x2B || b === 0x2D ||
+        b === 0x2E || b === 0x5E || b === 0x5F || b === 0x60 || b === 0x7C || b === 0x7E) {
+      out += String.fromCharCode(b);
+    } else {
+      out += "%" + (b < 0x10 ? "0" : "") + b.toString(16).toUpperCase();
+    }
+  }
+  return out;
+}
+
+// The policy gates a parsed challenge must clear to be answerable (RFC 7616 sec. 3.4): a supported
+// algorithm, MD5 only when allowed, and a qop this client can satisfy (auth / auth-int, or no-qop only when
+// allowLegacyQop). Returns a { code, msg } rejection or null. This is the SINGLE definition both answer()
+// and parseChallenge() consult, so challenge SELECTION can never rank a challenge as usable that answer()
+// would then refuse (or vice-versa) -- the two cannot drift.
+function _rejection(challenge, pol, codes) {
+  var alg = ALGS[challenge.algorithm];
+  if (!alg) return { code: codes.unsupportedAlgorithm, msg: "unsupported Digest algorithm " + challenge.algorithm + " (supported: SHA-512-256, SHA-256, MD5)" };
+  if (alg.hash === "md5" && !pol.allowMD5) return { code: codes.weakAlgorithm, msg: "MD5 Digest refused by default (RFC 7616 sec. 3.4 discourages it); set opts.auth.allowMD5 for legacy interop" };
+  if (challenge.qop.length === 0) {
+    if (!pol.allowLegacyQop) return { code: codes.noQop, msg: "a no-qop (RFC 2069) Digest challenge is refused by default; set opts.auth.allowLegacyQop for legacy interop" };
+  } else if (challenge.qop.indexOf("auth") === -1 && challenge.qop.indexOf("auth-int") === -1) {
+    return { code: codes.badChallenge, msg: "the Digest qop offered no member this client supports (auth / auth-int)" };
+  }
+  return null;
+}
+
+// answer(challenge, { method, uri, username, password, body, policy, rng }, E) -> the Authorization header value.
+function answer(challenge, params, E) {
+  var pol = params.policy || {};
+  var codes = pol.codes || DEFAULT_CODES;
+  var rej = _rejection(challenge, pol, codes);
+  if (rej) throw E(rej.code, rej.msg);
+  var alg = ALGS[challenge.algorithm];
+  var useQop = challenge.qop.indexOf("auth") !== -1 ? "auth" : (challenge.qop.indexOf("auth-int") !== -1 ? "auth-int" : null);
+  var cnonce = String((params.rng || function () { return crypto.randomBytes(18).toString("base64"); })());
+  // The realm is used with its incoming header OCTETS unchanged (RFC 7616 sec. 4). The realm arrives from the
+  // wire, so a transport that exposes header bytes as Latin-1 (the Node default) already presents the server's
+  // UTF-8 octets one-per-char; re-encoding them as UTF-8 (as user / pass, which come from the caller as Unicode
+  // strings, correctly do) would DOUBLE-encode and make the digest disagree with the server. H() hashes over
+  // Latin-1, so the raw realm string contributes exactly the octets the server used.
+  var realm = challenge.realm, nonce = challenge.nonce;
+  // Normalize UTF-8 credentials to NFC before hashing (RFC 7616 sec. 4): a server hashes the normalized form,
+  // so a canonically-decomposed username / password (e + combining accent vs the precomposed char) must be
+  // composed first or HA1 disagrees. The SAME normalized username feeds A1, userhash, and username*.
+  var isUtf8 = String(challenge.charset || "").toUpperCase() === "UTF-8";
+  var pUser = params.username == null ? "" : String(params.username);
+  var pPass = params.password == null ? "" : String(params.password);
+  if (isUtf8) { pUser = pUser.normalize("NFC"); pPass = pPass.normalize("NFC"); }
+  var user = _octets(pUser, challenge.charset);
+  var pass = _octets(pPass, challenge.charset);
+  var HA1 = H(alg.hash, user + ":" + realm + ":" + pass);
+  if (alg.sess) HA1 = H(alg.hash, HA1 + ":" + nonce + ":" + cnonce);
+  var A2 = (useQop === "auth-int")
+    ? params.method + ":" + params.uri + ":" + H(alg.hash, params.body == null ? "" : params.body)
+    : params.method + ":" + params.uri;
+  var HA2 = H(alg.hash, A2);
+  // The nonce-count: a (nonce, nc) pair MUST NOT be reused (RFC 7616 sec. 3.4), so a request that REUSES a nonce
+  // (a same-origin redirect, an auth-int retry) increments nc; a fresh nonce restarts at 1. The caller supplies
+  // the count for this nonce (default 1); formatted as 8 lowercase hex.
+  var ncNum = (typeof params.nc === "number" && params.nc >= 1) ? Math.floor(params.nc) : 1;
+  var nc = ("0000000" + ncNum.toString(16)).slice(-8);
+  var response = useQop
+    ? KD(alg.hash, HA1, nonce + ":" + nc + ":" + cnonce + ":" + useQop + ":" + HA2)
+    : KD(alg.hash, HA1, nonce + ":" + HA2);
+  // The username field (RFC 7616 sec. 3.4). userhash=true sends H(username:realm) for privacy (sec. 3.4.4) --
+  // an ASCII hex value; A1 above still used the REAL username. Otherwise a charset=UTF-8 username containing
+  // non-ASCII characters MUST be carried in the extended `username*` form (RFC 5987 / RFC 8187 percent-encoded
+  // UTF-8), because a server reads the legacy quoted `username` as ISO-8859-1 and could not resolve the account;
+  // `username` and `username*` MUST NOT both appear. An ASCII (or userhash) username uses the legacy quoted form.
+  var parts;
+  if (!challenge.userhash && isUtf8 && _hasNonAscii(pUser)) {
+    parts = ["username*=UTF-8''" + _pctEncodeUtf8(pUser)];
+  } else {
+    var sentUser = challenge.userhash ? H(alg.hash, _octets(pUser, challenge.charset) + ":" + realm) : _octets(pUser, challenge.charset);
+    parts = ["username=" + _qstr(sentUser)];
+  }
+  parts.push("realm=" + _qstr(realm), "nonce=" + _qstr(nonce), "uri=" + _qstr(params.uri), "algorithm=" + challenge.algorithm);
+  if (useQop) { parts.push("qop=" + useQop); parts.push("nc=" + nc); }
+  // The cnonce directive is emitted whenever the server needs it to recompute the response: under a qop, and
+  // also under a -sess algorithm whose A1 folds in the cnonce even with no qop (RFC 7616 sec. 3.4.2 / 3.9.1).
+  if (useQop || alg.sess) { parts.push("cnonce=" + _qstr(cnonce)); }
+  parts.push("response=" + _qstr(response));
+  if (challenge.opaque != null) parts.push("opaque=" + _qstr(challenge.opaque));
+  if (challenge.userhash) parts.push("userhash=true");
+  return "Digest " + parts.join(", ");
+}
+
+// Parse one domain URI entry (RFC 7616 sec. 3.3) into { origin, full }: an abs_path ("/a", "/a?x=1") is
+// relative to the responding server -> origin null (any same-origin request); an ABSOLUTE URI carries its own
+// authority -> origin "scheme://authority" (lowercased, default port normalized) and matches ONLY a request to
+// that SAME origin, since an entry to a different host names a protection space on a different server. `full` is
+// the pathname + query the request URI is prefix-compared against. A relative / unparseable absolute entry -> null.
+function _domainEntry(d) {
+  d = String(d == null ? "" : d);
+  if (d.charAt(0) === "/") return { origin: null, full: d };
+  // An absolute entry is parsed through the URL constructor so its origin is NORMALIZED the same way the
+  // request's URL.origin is -- an explicit default port (https :443 / http :80) is dropped, so a domain naming
+  // "https://h:443/x" still matches a request whose origin normalizes to "https://h". A relative / unparseable
+  // entry throws and never matches (fail closed).
+  try { var u = new URL(d); return { origin: u.origin.toLowerCase(), full: (u.pathname || "/") + (u.search || "") }; }
+  catch (_e) { return null; }
+}
+
+// inProtectionSpace(challenge, requestOrigin, requestPathAndSearch) -> is the request within the challenge's
+// protection space? An absent / empty domain means "all URIs on the responding server" (RFC 7616 sec. 3.3), so
+// any same-origin request matches; otherwise membership is by LITERAL URI PREFIX (RFC 7616 sec. 3.5 / RFC 2617
+// sec. 1.2): the request's pathname + query must have a listed domain URI as a prefix, and for an absolute entry
+// the same origin. The query is part of the prefix, so /enroll?tenant=a does not cover /enroll?tenant=b while a
+// query-less /enroll covers its whole subtree (including /enroll?...). Used to scope where a cached answer is reused.
+function inProtectionSpace(challenge, requestOrigin, requestPathAndSearch) {
+  var domain = challenge && challenge.domain;
+  if (!domain || !domain.length) return true;
+  var origin = String(requestOrigin == null ? "" : requestOrigin).toLowerCase();
+  var full = String(requestPathAndSearch == null ? "" : requestPathAndSearch);
+  for (var i = 0; i < domain.length; i++) {
+    var e = _domainEntry(domain[i]);
+    if (e === null) continue;
+    if (e.origin !== null && e.origin !== origin) continue;   // an absolute entry to a DIFFERENT origin is a different protection space
+    if (full.indexOf(e.full) === 0) return true;
+  }
+  return false;
+}
+
+module.exports = { parseChallenge: parseChallenge, answer: answer, inProtectionSpace: inProtectionSpace };

package/lib/http-transport.js

@@ -353,9 +353,11 @@ function httpsTransport(defaults) {
       timer = setTimeout(function () { fail(C("timeout"), "the request timed out after " + prep.timeout + "ms"); }, prep.timeout);
       try {
         req = nodeHttps.request(prep.options, function (res) {
-          // Capture the TLS session facts while the socket is live -- getProtocol() /
-          // getPeerCertificate() return null once the socket detaches at stream end.
+          // Capture the TLS session facts while the socket is live -- getProtocol() / getCipher() /
+          // getPeerCertificate() return null once the socket detaches at stream end. The negotiated cipher lets a
+          // caller refuse a NULL / anonymous / EXPORT suite before it trusts confidentiality (RFC 7030 sec. 4.4).
           var proto = res.socket && res.socket.getProtocol ? res.socket.getProtocol() : null;
+          var cipher = res.socket && res.socket.getCipher ? res.socket.getCipher() : null;
           var peer = res.socket && res.socket.getPeerCertificate ? res.socket.getPeerCertificate() : null;
           // Pre-check a declared content-length so an oversized body is refused before it streams.
           var declared = parseInt((res.headers || {})["content-length"], 10);
@@ -389,7 +391,7 @@ function httpsTransport(defaults) {
               status: res.statusCode,
               headers: lower,
               body: Buffer.from(buf.subarray(0, len)),
-              tls: { protocol: proto, peerCertificate: peer && peer.raw ? peer.raw : null },
+              tls: { protocol: proto, cipher: cipher, peerCertificate: peer && peer.raw ? peer.raw : null },
             });
           });
           res.on("error", function (e) { fail(C("transport-error"), "the response stream failed", e); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "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:98a7ec9f-9442-4c90-b486-f206cdde5325",
+  "serialNumber": "urn:uuid:ea40d20f-ad92-403e-8de1-cfd14bead6ba",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-31T20:40:18.144Z",
+    "timestamp": "2026-08-01T18:47:21.356Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.27",
+      "bom-ref": "@blamejs/pki@0.3.28",
       "type": "application",
       "name": "pki",
-      "version": "0.3.27",
+      "version": "0.3.28",
       "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.27",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.28",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.27",
+      "ref": "@blamejs/pki@0.3.28",
       "dependsOn": []
     }
   ]