@blamejs/pki 0.5.7 → 0.5.8

package/lib/cmp-session.js

@@ -7,14 +7,14 @@
 // surface (build / transfer / wellKnownUrl / verify) so the whole pki.cmp namespace wires through here
 // (index.js requires this file as `cmp`).
 //
-// pki.cmp.session -- the STATEFUL CMP enrollment-transaction orchestrator (the pki.acme.client analogue).
+// pki.cmp.session -- the stateful CMP enrollment-transaction orchestrator (the pki.acme.client analogue).
 // It composes the shipped message layer (build / transfer / verify) into a single enroll(request): mint a
-// stable transactionID, build + protect + transfer a request, VERIFY every response's protection BEFORE
+// stable transactionID, build + protect + transfer a request, verify every response's protection before
 // reading its body, chain the nonces (recipNonce echoes the peer's senderNonce, a fresh senderNonce per
 // request) and the transactionID (RFC 9810 sec. 5.1.1 anti-replay / anti-interleave), interpret the
 // CertResponse PKIStatus (grant -> extract the cert, waiting -> a bounded pollReq/pollRep loop, rejection
 // -> a terminal verdict), and confirm (certConf -> pkiConf, unless implicitConfirm was granted). The
-// single invariant is transfer -> verify (fail-closed) -> ONLY THEN read the body off the verdict.
+// single invariant is transfer -> verify (fail-closed) -> only then read the body off the verdict.
 
 var cmp = require("./cmp-verify");   // re-exports build / transfer / wellKnownUrl / verify (the whole message layer)
 var asn1 = require("./asn1-der");
@@ -35,12 +35,12 @@ function _err(code, message, cause) { return new CmpError(code, message, cause);
 var OID_IMPLICIT_CONFIRM = oid.byName("implicitConfirm");   // classify a granted implicitConfirm by its IMMUTABLE OID
 
 // The certification-path build/validate engine, injected by path-validate (the crl/ocsp/cmp-verify seam) so
-// the session can VALIDATE the issued leaf certificate's signature + chain -- x509.parse is structural only.
+// the session can validate the issued leaf certificate's signature + chain; x509.parse is structural only.
 var _engine = null;
 function setEngine(engine) { _engine = engine; }
 
-// The signature algorithms whose OID conveys NO message hash -- EdDSA (the hash is the scheme) and the FIPS
-// PQC signatures (ML-DSA / SLH-DSA, internally hashed). ONLY these may take the certConf SHA-256 + explicit
+// The signature algorithms whose OID conveys no message hash: EdDSA (the hash is the scheme) and the FIPS
+// PQC signatures (ML-DSA / SLH-DSA, internally hashed). Only these may take the certConf SHA-256 + explicit
 // hashAlg fallback (RFC 9810 sec. 5.3.18); any other indeterminate/non-signature AlgorithmIdentifier (e.g.
 // rsaEncryption, an ML-KEM OID) is refused. Resolved to a dotted-OID set at load (never a runtime lookup).
 var HASHLESS_SIG_OIDS = {};
@@ -58,8 +58,8 @@ var SIG_OID_TO_HASH = {};
 });
 var OID_RSASSA_PSS = oid.byName("rsassaPss");
 var OID_RSA_ENCRYPTION = oid.byName("rsaEncryption");
-// Message-digest OID -> the WebCrypto digest name, for the RSASSA-PSS hashAlgorithm parameter -- dispatched by
-// the IMMUTABLE OID (never oid.name, which pki.oid.register can rename). Resolved to a dotted-OID map at load.
+// Message-digest OID -> the WebCrypto digest name, for the RSASSA-PSS hashAlgorithm parameter, dispatched by
+// the immutable OID (never oid.name, which pki.oid.register can rename). Resolved to a dotted-OID map at load.
 var HASH_OID_TO_DIGEST = {};
 [["sha256", "SHA-256"], ["sha384", "SHA-384"], ["sha512", "SHA-512"]].forEach(function (row) { var o = oid.byName(row[0]); if (o) HASH_OID_TO_DIGEST[o] = row[1]; });
 // A composite signature's declared prehash (COMPOSITE_ALGS[oid].ph) -> the certConf hashAlg field value.
@@ -83,7 +83,7 @@ var DEFAULT_CERT_REQ_ID = 0;   // the CRMF single-request certReqId when the cal
 var P10CR_CERT_REQ_ID = -1;    // a PKCS#10 request has no CRMF id; a conforming cp identifies it with the -1 sentinel (RFC 9483)
 var ENROLL_ARMS = { ir: 1, cr: 1, kur: 1, p10cr: 1 };   // the initial request arms enroll() accepts
 // The response body arm each enrollment request is answered by (RFC 9810 sec. 5.3.2/5.3.4): ir->ip, cr/p10cr
-// ->cp, kur->kup. A response of a DIFFERENT cert-response arm than the request is misrouted -- never confirmed.
+// ->cp, kur->kup. A response on a different cert-response arm than the request is misrouted, never confirmed.
 var RESPONSE_ARM = { ir: "ip", cr: "cp", kur: "kup", p10cr: "cp" };
 
 // PKIStatus codes (RFC 9810 sec. 5.2.3): 0 accepted, 1 grantedWithMods, 2 rejection, 3 waiting.
@@ -100,18 +100,18 @@ function _certReqIdEq(a, b) { return a != null && b != null && BigInt(a) === Big
 function _asCertList(v) { return v == null ? [] : (Array.isArray(v) ? v.slice() : [v]); }
 
 // Append session-supplied pool material (a CA-delivered caPubs, a cached protection-signer chain part-derived
-// from the response's UNSIGNED extraCerts) to a `base` pool (the caller's OWN intermediates) up to the path
+// from the response's unsigned extraCerts) to a `base` pool (the caller's own intermediates) up to the path
 // builder's candidate ceiling, deduped against each other AND the base's Buffer entries so a copy of an existing
 // candidate never spends a slot. The base is never truncated (if it alone exceeds the ceiling, that is a genuine
 // config error path.build reports). So neither a legitimate caPubs nor a meddler's extraCerts flood can push a
-// valid caller pool over the ceiling and fail an otherwise-valid grant. Used for BOTH the response signer path
+// valid caller pool over the ceiling and fail an otherwise-valid grant. Used for both the response signer path
 // (cmp.verify) and the issued-leaf path (path.build), the two places session material joins a caller pool.
 function _boundedPool(base, added) {
-  // Dedup the BASE (the priority pool) FIRST: duplicate copies would otherwise inflate its length, drive the
-  // remaining room to zero, and evict genuinely needed added material even though the DISTINCT candidate count is
+  // Dedup the base (the priority pool) first: duplicate copies would otherwise inflate its length, drive the
+  // remaining room to zero, and evict genuinely needed added material even though the distinct candidate count is
   // small (path.build dedups internally, so dropping exact duplicates is behavior-preserving). An uncanonicalizable
   // entry is kept as-is (path.build judges it) and cannot dedup an added cert. The base holds the priority material
-  // (a signed response's OWN delivered issuers + the cached chain, or the grant's caPubs) so it is never truncated;
+  // (a signed response's own delivered issuers + the cached chain, or the grant's caPubs) so it is never truncated;
   // the added caller pool fills the remaining room to the candidate ceiling.
   var ceiling = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES;
   var seen = Object.create(null), distinctBase = [];
@@ -122,21 +122,21 @@ function _boundedPool(base, added) {
   added.forEach(function (c) { var k = _certIdentity(c); if (k != null && seen[k]) return; if (k != null) seen[k] = 1; useful.push(c); });
   return distinctBase.concat(useful.slice(0, room));
 }
-// A canonical byte identity for a certificate in ANY form path.build accepts -- a DER Buffer, a PEM string, or
-// an already-parsed certificate object -- so a caller intermediate supplied as PEM or parsed still dedups against
+// A canonical byte identity for a certificate in any form path.build accepts (a DER Buffer, a PEM string, or
+// an already-parsed certificate object), so a caller intermediate supplied as PEM or parsed still dedups against
 // a byte-identical DER caPubs / cached certificate and does not spend a scarce candidate slot on a copy. The
-// identity is the tbsCertificate bytes PLUS the signature (mirroring cmp.verify's _certKey): a meddler controls
-// the unsigned extraCerts ordering, so a corrupted-signature copy sharing a valid issuer's TBS must NOT collapse
-// onto it and evict the valid one. Returns null when the identity cannot be derived; a NON-deduped entry is safe
+// identity is the tbsCertificate bytes plus the signature (mirroring cmp.verify's _certKey): a meddler controls
+// the unsigned extraCerts ordering, so a corrupted-signature copy sharing a valid issuer's TBS must not collapse
+// onto it and evict the valid one. Returns null when the identity cannot be derived; a non-deduped entry is safe
 // (a redundant slot), a wrong merge (dropping a distinct or the only valid certificate) is not.
-// The identity comes from the SAME derivation every other certificate door uses: the bytes the
-// parser recorded, never the fields of the object handed in. This is a dedupe rather than a verdict,
-// and no collision attack on it is apparent -- carrying another certificate's exact tbsBytes AND
+// The identity comes from the same derivation every other certificate door uses: the bytes the
+// parser recorded, never the fields of the object handed in. This is a dedupe, not a verdict,
+// and no collision attack on it is apparent, since carrying another certificate's exact tbsBytes and
 // signature means being that certificate. But "no attack is apparent" is the reasoning that put a
 // completeness-only door on nine deciding boundaries, so it is not the reasoning this uses: one
 // derivation for certificates, everywhere, and the exceptions have to argue for themselves.
 //
-// Failure returns null rather than throwing, which is this function's own contract and is why the
+// Failure returns null instead of throwing, which is this function's own contract and is why the
 // door is wrapped: an underivable identity is a redundant pool slot, while a wrong merge (dropping
 // a distinct or the only valid certificate) is not. So a rebuilt entry simply does not dedupe.
 function _certIdentity(cert) {
@@ -150,9 +150,9 @@ function _certIdentity(cert) {
 }
 
 // A canonical identity for a SubjectPublicKeyInfo: the algorithm OID + the AlgorithmIdentifier parameters +
-// the raw subjectPublicKey BIT STRING. The parameters ARE part of the key identity (an EC curve OID, an
-// RSASSA-PSS constraint set) and are kept -- EXCEPT for rsaEncryption, whose parameters are NULL or omitted,
-// both naming the same key. So the issued-cert key-match compares KEYS (with their constraints), not byte
+// the raw subjectPublicKey BIT STRING. The parameters are part of the key identity (an EC curve OID, an
+// RSASSA-PSS constraint set) and are kept, with one exception: rsaEncryption, whose parameters are NULL or
+// omitted, both naming the same key. So the issued-cert key-match compares keys (with their constraints), not byte
 // encodings, and neither rejects an equivalent rsaEncryption re-encoding nor accepts a constraint-changed key.
 function _spkiKeyIdentity(spkiDer) {
   var node = asn1.decode(spkiDer);   // SEQUENCE { AlgorithmIdentifier { OID, params? }, BIT STRING }
@@ -161,10 +161,10 @@ function _spkiKeyIdentity(spkiDer) {
   var pn = algId.children[1];
   var params;
   if (algOid === OID_RSA_ENCRYPTION) {
-    // rsaEncryption parameters MUST be absent or a NULL (RFC 3279 sec. 2.3.1). Normalize ONLY those two
-    // equivalent forms to "" so a NULL-vs-omitted re-encoding matches. ANY other value (a malformed empty OCTET
-    // STRING the parser/importer may tolerate, or a changed parameter) keeps its bytes -- so a parameter-changed
-    // certificate a stricter consumer rejects gets a DISTINCT identity and the key-match refuses it.
+    // rsaEncryption parameters MUST be absent or a NULL (RFC 3279 sec. 2.3.1). Normalize only those two
+    // equivalent forms to "" so a NULL-vs-omitted re-encoding matches. Any other value (a malformed empty OCTET
+    // STRING the parser/importer may tolerate, or a changed parameter) keeps its bytes, so a parameter-changed
+    // certificate a stricter consumer rejects gets a distinct identity and the key-match refuses it.
     params = (pn == null || _isDerNull(pn)) ? "" : pn.bytes.toString("latin1");
   } else {
     // Every other algorithm's parameters ARE part of the key identity (an EC curve OID, an RSASSA-PSS constraint set).
@@ -176,28 +176,28 @@ function _spkiKeyIdentity(spkiDer) {
 // as equivalent to an absent parameter.
 function _isDerNull(pn) { return pn.tagClass === "universal" && pn.tagNumber === 5 && pn.content.length === 0; }
 
-// The BOUNDED, distinct, parseable extraCerts of an already-verified response, cached so a later leg that
-// omits extraCerts can rebuild the signer path -- MIRRORING cmp.verify's own extraCerts bounding: dedup, drop
+// The bounded, distinct, parseable extraCerts of an already-verified response, cached so a later leg that
+// omits extraCerts can rebuild the signer path, mirroring cmp.verify's own extraCerts bounding: dedup, drop
 // any non-X.509 entry, cap at MAX_EXTRA_CERTS, and stop after MAX_EXTRA_SCAN entries. So a meddler appending a
 // flood of unsigned certs cannot make an otherwise-valid enrollment fail when the cache reaches path.build.
 var MAX_EXTRA_CERTS = 32, MAX_EXTRA_SCAN = 256;
-// The caller intermediates pool is capped BELOW the path-builder candidate ceiling, reserving room for the CA's
-// OWN authenticated material (a response's extraCerts + the cached signer chain, or the grant's caPubs + cache --
-// each <= MAX_EXTRA_CERTS). So the authenticated certs AND the whole caller pool ALWAYS fit in ONE candidate pool:
-// no priority attempt has to choose between them, and a chain assembled from BOTH sources validates in one build.
-var CAPUBS_MAX = 2 * MAX_EXTRA_CERTS;   // the leaf's authenticated issuer material (caPubs) -- bounded so caPubs + cached chain + the caller pool fit under the ceiling
-// The caller intermediates pool is capped below the path-builder ceiling by the room the session's OWN material
-// can occupy. A SIGNATURE session reserves CAPUBS_MAX (a grant's caPubs, leaf validation) PLUS MAX_EXTRA_CERTS (the
-// response's extraCerts + cached SIGNER chain -- the signer-path pool). A MAC session authenticates the response by
-// the shared secret and NEVER adds a signer chain (its cache gate is isSig), so it reserves ONLY CAPUBS_MAX -- its
+// The caller intermediates pool is capped below the path-builder candidate ceiling, reserving room for the CA's
+// own authenticated material (a response's extraCerts + the cached signer chain, or the grant's caPubs + cache,
+// each <= MAX_EXTRA_CERTS). So the authenticated certs and the whole caller pool always fit in one candidate pool:
+// no priority attempt has to choose between them, and a chain assembled from both sources validates in one build.
+var CAPUBS_MAX = 2 * MAX_EXTRA_CERTS;   // the leaf's authenticated issuer material (caPubs), bounded so caPubs + cached chain + the caller pool fit under the ceiling
+// The caller intermediates pool is capped below the path-builder ceiling by the room the session's own material
+// can occupy. A signature session reserves CAPUBS_MAX (a grant's caPubs, leaf validation) plus MAX_EXTRA_CERTS (the
+// response's extraCerts + cached signer chain, the signer-path pool). A MAC session authenticates the response by
+// the shared secret and never adds a signer chain (its cache gate is isSig), so it reserves CAPUBS_MAX alone; its
 // sole pool is _validateLeaf's caPubs + caller. So every candidate pool the session builds holds the whole caller
-// pool AND all authenticated material at once -- one build, no priority choice, no retry.
+// pool and all authenticated material at once: one build, no priority choice, no retry.
 var SESSION_MAX_INTERMEDIATES = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES - CAPUBS_MAX - MAX_EXTRA_CERTS;   // signature
 var SESSION_MAX_INTERMEDIATES_MAC = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES - CAPUBS_MAX;                 // MAC (no signer chain reserved)
 // A verify verdict whose failure a DIFFERENT candidate pool or the cached/prebound signer might still recover:
 // extraCerts is outside the protected part, so a signer that did not resolve, a wrong-key/wrong-subject decoy
 // selected first, or an untrusted chain can all be retried. A transaction-integrity failure (transactionID /
-// recipNonce mismatch) is NOT here -- it is decoy-independent and re-running would only mask the real desync.
+// recipNonce mismatch) is deliberately absent: it is decoy-independent, and re-running would only mask the desync.
 function _isRecoverableVerify(code) {
   return code === "cmp/signer-cert-not-found" || code === "cmp/protection-failed" ||
     code === "cmp/sender-mismatch" || code === "cmp/untrusted-signer";
@@ -219,8 +219,8 @@ function _responseExtraCerts(responseBytes) {
   return out;
 }
 
-// Normalize a caller-supplied CRMF certReqId to the value the session echoes + matches, the SAME way
-// crmf-sign._certReqId encodes it: a number or bigint is kept; a STRING (decimal or 0x-hex) is parsed via
+// Normalize a caller-supplied CRMF certReqId to the value the session echoes + matches, the same way
+// crmf-sign._certReqId encodes it: a number or bigint is kept; a string (decimal or 0x-hex) is parsed via
 // BigInt so a supported form ("5" / "0x5") is not silently replaced by the default; anything else -> `dflt`.
 function _normalizeCertReqId(cid, dflt) {
   if (typeof cid === "bigint" || typeof cid === "number") return cid;
@@ -251,11 +251,11 @@ function _pssDigest(paramsBytes) {
   return null;
 }
 
-// The certConf certHash algorithm (RFC 9810 sec. 5.3.18): use the SAME hash the certificate signature uses.
-// If the signatureAlgorithm OID conveys the hash (sha256WithRSAEncryption / ecdsaWithSHA384 / ...) use THAT
-// hash and OMIT hashAlg. For id-RSASSA-PSS the hash is carried in the params, so decode it and likewise omit
+// The certConf certHash algorithm (RFC 9810 sec. 5.3.18): use the same hash the certificate signature uses.
+// If the signatureAlgorithm OID conveys the hash (sha256WithRSAEncryption / ecdsaWithSHA384 / ...) use that
+// hash and omit hashAlg. For id-RSASSA-PSS the hash is carried in the params, so decode it and likewise omit
 // hashAlg. Only when the hash is genuinely not conveyed (Ed25519 / Ed448; ML-DSA / SLH-DSA) is SHA-256 used
-// and DECLARED in the explicit hashAlg field so the CA recomputes certHash under the same stated hash.
+// and declared in the explicit hashAlg field so the CA recomputes certHash under the same stated hash.
 function _certConfHash(certDer) {
   var sa;
   try { sa = x509.parse(certDer).signatureAlgorithm; }
@@ -265,10 +265,10 @@ function _certConfHash(certDer) {
   // hashAlg; id-RSASSA-PSS -> the hash from its parameters, no hashAlg.
   if (HASHLESS_SIG_OIDS[sa.oid]) return { digest: "SHA-256", hashAlg: "sha256" };
   // A composite signature (draft-ietf-lamps-pq-composite-sigs): compute certHash under the composite's own
-  // declared PREHASH digest (COMPOSITE_ALGS[oid].ph) and DECLARE it in the explicit hashAlg. If the prehash is
-  // not a certConf-representable hash (SHAKE256, which the CMP CertStatus hashAlg cannot name), FAIL closed --
+  // declared prehash digest (COMPOSITE_ALGS[oid].ph) and declare it in the explicit hashAlg. If the prehash is
+  // not a certConf-representable hash (SHAKE256, which the CMP CertStatus hashAlg cannot name), fail closed:
   // substituting SHA-256 would send a certHash under a hash that contradicts the signature's declared prehash,
-  // which a conforming CA rejects. Refuse rather than confirm under a false algorithm (RFC 9810 sec. 5.3.18).
+  // which a conforming CA rejects. Refuse, never confirm under a false algorithm (RFC 9810 sec. 5.3.18).
   var comp = compositeSig.COMPOSITE_ALGS[sa.oid];
   if (comp) {
     var ha = COMPOSITE_PH_HASHALG[comp.ph];
@@ -281,8 +281,8 @@ function _certConfHash(certDer) {
     if (pd) return { digest: pd, hashAlg: null };
     throw _err("cmp/bad-cert-response", "the issued RSASSA-PSS certificate's hash cannot be resolved from its parameters (RFC 4055); the certConf hash is indeterminate");
   }
-  // Any other AlgorithmIdentifier -- an unregistered OID, or a registered NON-signature / indeterminate one
-  // (rsaEncryption, an ML-KEM OID, ...): the required certConf hash cannot be determined. Do NOT guess
+  // Any other AlgorithmIdentifier (an unregistered OID, or a registered non-signature / indeterminate one
+  // such as rsaEncryption or an ML-KEM OID): the required certConf hash cannot be determined. Do not guess
   // SHA-256 (a wrong certHash the CA rejects); fail the transaction closed before confirming.
   throw _err("cmp/bad-cert-response", "the issued certificate's signature algorithm does not determine a certConf hash (an unrecognized or non-signature algorithm); the transaction is refused (RFC 9810 sec. 5.3.18)");
 }
@@ -295,46 +295,46 @@ function _certConfHash(certDer) {
  * @spec       RFC 9810, RFC 9811, RFC 9483
  * @related    pki.cmp.build, pki.cmp.verify, pki.cmp.transfer
  *
- * A stateful RFC 9810 CMP enrollment-transaction orchestrator -- the `pki.acme.client` analogue. It drives
+ * A stateful RFC 9810 CMP enrollment-transaction orchestrator, the `pki.acme.client` analogue. It drives
  * an enrollment (`ir` / `cr` / `kur` / `p10cr`) end to end over the shared `pki.transport` (inject
  * `opts.transport`, else a fail-closed `pki.transport.https`), composing the shipped message layer
  * (`build` / `transfer` / `verify`). It mints a stable 128-bit `transactionID`, and on every request a
- * FRESH `senderNonce`, echoing the peer's last `senderNonce` back as `recipNonce` (RFC 9810 sec. 5.1.1
- * anti-replay / anti-interleave). The load-bearing invariant: every response is protection-VERIFIED and
- * nonce-bound to this exchange BEFORE its body is read -- so a meddler who flips an HTTP response cannot
+ * fresh `senderNonce`, echoing the peer's last `senderNonce` back as `recipNonce` (RFC 9810 sec. 5.1.1
+ * anti-replay / anti-interleave). The load-bearing invariant: every response is protection-verified and
+ * nonce-bound to this exchange before its body is read, so a meddler who flips an HTTP response cannot
  * forge a granted status or a poison `checkAfter`. A `waiting` status drives a bounded `pollReq`/`pollRep`
  * loop (an injectable sleeper, capped by `maxPolls` + `maxTotalWait`); a grant extracts the issued cert and
  * confirms it (`certConf` -> `pkiConf`, unless an `implicitConfirm` was granted). A verified `rejection` /
- * `error` or a poll-budget timeout is a terminal typed VERDICT the caller reads (`outcome`:
+ * `error` or a poll-budget timeout is a terminal typed verdict the caller reads (`outcome`:
  * `issued` / `rejected` / `poll-timeout`); a tampered / unverifiable / desynchronized response is a
- * hard-stop `CmpError` throw. Exactly ONE protection flavor: `{ key, cert }` (signature) XOR `{ mac }`
- * (PBMAC1). A crypto-valid response is not enough -- the signer must chain to a supplied trust anchor
+ * hard-stop `CmpError` throw. Exactly one protection flavor: `{ key, cert }` (signature) XOR `{ mac }`
+ * (PBMAC1). A crypto-valid response is not enough: the signer must chain to a supplied trust anchor
  * (signature) or the shared secret must match (MAC); a valid-but-untrusted response is a hard stop, so the
  * signature flavor REQUIRES `opts.trustAnchors` at construction. Returns a session with `enroll(request)`,
  * and read-only `transactionID` + `transcript` (each leg's request/response bytes, retained up to a
  * transaction-wide cap; a later leg beyond the cap keeps its metadata + `byteLength` but drops the payload as
  * `bytes: null, truncated: true`, so a padded-response flood across polls cannot exhaust memory). The granted certificate must be valid X.509, carry the key
- * the request submitted (else it is a misrouted certificate the caller cannot use), and -- for the signature
- * flavor -- have its signature + chain validated to a supplied trust anchor before it is confirmed. The `certConf`
- * `certHash` uses the certificate's signature hash -- from the OID when it conveys one, or from the
+ * the request submitted (else it is a misrouted certificate the caller cannot use), and, for the signature
+ * flavor, have its signature + chain validated to a supplied trust anchor before it is confirmed. The `certConf`
+ * `certHash` uses the certificate's signature hash: from the OID when it conveys one, or from the
  * RSASSA-PSS parameters when it does not, with `hashAlg` omitted; only a truly hashless signature
  * (Ed25519 / Ed448, ML-DSA / SLH-DSA) computes under SHA-256 and declares an explicit `hashAlg`
  * (RFC 9810 sec. 5.3.18). The `certReqId` echoed in `pollReq` / `certConf` and matched in every
  * `CertResponse` is the caller's CRMF request id (`request.ir.certReqId`, ...) when supplied, else the
- * single-request default. One transaction per session -- a second or concurrent `enroll`, or a batched
+ * single-request default. One transaction per session: a second or concurrent `enroll`, or a batched
  * CRMF request, is refused (a local build error leaves the session retryable). The returned `chain` is the
  * issued leaf plus any authenticated `caPubs` the CA delivered (chain material, never trust anchors); a
  * server-generated (central key generation) private key is out of scope and the grant is refused.
  *
  * @opts
  *   - `url` -- REQUIRED: the CMP endpoint URL.
- *   - `key` + `cert` -- signature protection (the enrolling key pair + its cert), XOR `mac: { secret, ... }` -- PBMAC1 protection.
- *   - `trustAnchors` -- REQUIRED for the signature flavor (chains + authenticates the CA's response signer cert); OPTIONAL for a MAC session, where it validates the ISSUED certificate's own signature + chain before confirmation (not the response protection). `intermediates` -- extra chain pool.
- *   - `sender` / `recipient` -- header GeneralNames; default the signer cert's subject DN (sender) and a NULL-DN (recipient). A signature-protection certificate with an EMPTY subject (identified only by its subjectAltName) REQUIRES an explicit `sender` -- the empty subject cannot name the requester for a peer that binds the sender to the SAN.
+ *   - `key` + `cert` -- signature protection (the enrolling key pair + its cert), XOR `mac: { secret, ... }` for PBMAC1 protection.
+ *   - `trustAnchors` -- REQUIRED for the signature flavor (chains + authenticates the CA's response signer cert); OPTIONAL for a MAC session, where it validates the issued certificate's own signature + chain before confirmation (not the response protection). `intermediates` supplies an extra chain pool.
+ *   - `sender` / `recipient` -- header GeneralNames; default the signer cert's subject DN (sender) and a NULL-DN (recipient). A signature-protection certificate with an empty subject (identified only by its subjectAltName) REQUIRES an explicit `sender`, because the empty subject cannot name the requester for a peer that binds the sender to the SAN.
  *   - `senderKID` / `recipKID` -- optional key identifiers emitted on every request header, so a CA selecting among several shared secrets (senderKID) or recipient keys resolves the right credential.
- *   - `expectedSender` -- optional CA signer CERTIFICATE (DER Buffer / PEM string / already-parsed `pki.schema.x509.parse` object); when set, every signed response's authenticated header sender MUST bind to it under the RFC 5280 sec. 7 subject-or-subjectAltName rule cmp.verify uses, so a re-encoded-but-equivalent DN and an empty-subject CA named only by a directoryName SAN both match. Given as bytes/PEM it ALSO resolves a first response that omits its own extraCerts (a CA that assumes the client already holds its certificate). Absent, the session pins the first signed response's signer certificate and requires every later leg's sender to bind to it -- rejecting a switch to a different trusted signer while permitting same-identity certificate/key rotation.
+ *   - `expectedSender` -- optional CA signer certificate (DER Buffer / PEM string / already-parsed `pki.schema.x509.parse` object); when set, every signed response's authenticated header sender MUST bind to it under the RFC 5280 sec. 7 subject-or-subjectAltName rule cmp.verify uses, so a re-encoded-but-equivalent DN and an empty-subject CA named only by a directoryName SAN both match. Given as bytes/PEM it also resolves a first response that omits its own extraCerts (a CA that assumes the client already holds its certificate). Absent, the session pins the first signed response's signer certificate and requires every later leg's sender to bind to it, rejecting a switch to a different trusted signer while permitting same-identity certificate/key rotation.
  *   - `implicitConfirm` -- request implicit confirmation (skip the certConf leg when the CA grants it).
- *   - `acceptCert` -- an async policy `(certDer, { status, grantedWithMods }) => boolean` consulted before the certConf; return true to accept, anything else to veto (a `grantedWithMods` certificate the CA changed). A veto sends a REJECTING certConf and yields `outcome: "rejected"` with the certificate still surfaced. Incompatible with `implicitConfirm` (no reject leg exists) -- the combination throws at construction.
+ *   - `acceptCert` -- an async policy `(certDer, { status, grantedWithMods }) => boolean` consulted before the certConf; return true to accept, anything else to veto (a `grantedWithMods` certificate the CA changed). A veto sends a rejecting certConf and yields `outcome: "rejected"` with the certificate still surfaced. Incompatible with `implicitConfirm` (no reject leg exists), so the combination throws at construction.
  *   - `transport` -- injectable transport(request) -> {status, headers, body}; default pki.transport.https.
  *   - `tls` / `headers` / `timeout` / `maxResponseBytes` -- transport config + budgets.
  *   - `maxPolls` / `maxTotalWait` / `sleep` -- poll-loop budgets + an injectable sleeper; `time` -- verify-time clock.