@blamejs/pki 0.3.26 → 0.3.28

package/lib/cmp-verify.js

@@ -94,7 +94,7 @@ function _verdict(m, type, protectionAlg, valid, trusted, code, reason, signer)
     trusted: trusted,
     protectionType: type,
     protectionAlg: protectionAlg ? { oid: protectionAlg.oid, name: protectionAlg.name || null } : null,
-    signer: signer ? { cert: signer.der, spki: signer.spki, subject: signer.subject } : null,
+    signer: signer ? { cert: signer.der, spki: signer.spki, subject: signer.subject, chain: signer.chain || null } : null,
     transactionID: m.header.transactionID || null,
     senderNonce: m.header.senderNonce || null,
     recipNonce: m.header.recipNonce || null,
@@ -496,6 +496,10 @@ async function _verifySignature(m, protectedPart, protectionAlg, protection, opt
   // the caller to anchor. With a trust store the signer cert gets the FULL RFC 5280 sec. 6.1 path gates.
   if (opts.trustAnchors == null) return _ok(m, "signature", protectionAlg, false, signer);
   var trust = await _chainSigner(signer, m, opts, extra);
+  // Surface the ACTUAL validated chain (signer + the intermediates path.build used) on a trusted verdict, so a
+  // caller can cache exactly the certificates that established trust rather than the UNSIGNED extraCerts a peer
+  // can pad -- an appended-but-unused certificate never enters this chain.
+  if (trust.chain) signer.chain = trust.chain;
   return _verdict(m, "signature", protectionAlg, true, trust.trusted, trust.trusted ? null : "cmp/untrusted-signer", trust.reason, signer);
 }
 
@@ -545,7 +549,17 @@ async function _chainSigner(signer, m, opts, extra) {
   try {
     var res = await _engine.build(signer.der, buildOpts);
     if (!res || res.valid !== true) return { trusted: false, reason: "the signer certificate did not chain to a supplied trust anchor" };
-    return { trusted: true, reason: null };
+    // res.path is the ordered certificates path.build assembled (signer + the intermediates it used), as PARSED
+    // objects whose byte fields are subarrays of the (possibly multi-MB) response allocation. Map each back to its
+    // source DER (the signer, or a DER pool entry) and return an INDEPENDENT copy, so a caller caching the chain
+    // holds standalone buffers -- never slices pinning the whole response. Only certs on the trusted path enter it,
+    // so unsigned extraCerts padding is excluded. (A path cert sourced from an already-parsed intermediate carries
+    // no DER to copy and is omitted; for a Buffer/DER pool -- the cmp.session case -- the chain is complete.)
+    var byKey = Object.create(null);
+    var skey = _certKey(signer.parsed); if (skey) byKey[skey] = signer.der;
+    pool.forEach(function (c) { if (Buffer.isBuffer(c) || c instanceof Uint8Array) { var k = _certKey(c); if (k && !byKey[k]) byKey[k] = c; } });
+    var chain = res.path.map(function (pc) { var k = _certKey(pc); var d = k ? byKey[k] : null; return d ? Buffer.from(d) : null; }).filter(Boolean);
+    return { trusted: true, reason: null, chain: chain };
   } catch (e) {
     // A config-tier fault from path.build (an invalid opts.time, an empty / malformed trustAnchors or
     // intermediate) is a DEPLOYMENT error, not an untrusted signer -- rethrow it as cmp/bad-input so it is
@@ -669,9 +683,12 @@ async function _verify(message, opts) {
  * Returns a verdict (never a bare boolean): `{ valid, trusted, protectionType, protectionAlg, signer,
  * transactionID, senderNonce, recipNonce, header, body, code?, reason? }`. `valid` is whether the
  * protection is cryptographically intact under the declared algorithm; `trusted` is whether a MAC secret
- * matched or a signature signer certificate chained to a supplied trust anchor. A well-formed but
- * unverifiable message is a `{ valid: false }` verdict carrying a `cmp/*` code, not a throw; only malformed
- * input (a non-PKIMessage, a bad required opt, a flavor/credential mismatch) throws a typed `CmpError`.
+ * matched or a signature signer certificate chained to a supplied trust anchor. On a trusted signature
+ * verdict `signer.chain` is the validated certificate path as independent DER buffers (the signer plus the
+ * intermediates that chained it to the anchor) -- the certificates actually used, never the unsigned
+ * `extraCerts` a peer can pad, and never a slice pinning the response allocation. A
+ * well-formed but unverifiable message is a `{ valid: false }` verdict carrying a `cmp/*` code, not a throw;
+ * only malformed input (a non-PKIMessage, a bad required opt, a flavor/credential mismatch) throws a typed `CmpError`.
  *
  * @opts
  *   - `sharedSecret` (string|Buffer) -- the PBMAC1 secret; REQUIRED for a MAC-protected message (UTF-8).
@@ -702,4 +719,5 @@ module.exports = {
   wellKnownUrl: cmpBuild.wellKnownUrl,
   verify: verify,
   setEngine: setEngine,
+  senderBoundToCert: _senderBoundToCert,
 };

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,