@blamejs/pki 0.5.7 → 0.5.8

package/lib/cmc-verify.js

@@ -8,13 +8,13 @@
  * @intro Interpret an RFC 5272 Full PKI Response. `verify(response, sent)` takes the response
  *   a CA returned and the state the client retained from its request, binds the two together
  *   (transaction identifier, the Sender/Recipient Nonce echo, the Data Return echo), reads the
- *   ordered status verdicts, and reduces them to ONE terminal outcome: `issued`, `pending`,
+ *   ordered status verdicts, and reduces them to one terminal outcome: `issued`, `pending`,
  *   `confirm-required`, `pop-required` or `rejected`. The issued certificates come from the CMS
  *   certificate bag, where RFC 5272 sec. 4.2 puts them. Nothing here is trusted: the bag and any
  *   Publish Trust Anchors control are surfaced as DATA for the caller to validate through
  *   `pki.path.validate`.
  * @spec RFC 5272, RFC 5273, RFC 6402
- * @card Interpret a CMC Full PKI Response into one terminal verdict -- transaction and nonce
+ * @card Interpret a CMC Full PKI Response into one terminal verdict: transaction and nonce
  *   binding, the status verdicts, the certificate bag surfaced untrusted.
  */
 
@@ -53,7 +53,7 @@ var OUTCOME_BY_STATUS = {
 
 // Which outcome governs when a response carries SEVERAL status controls (sec.
 // 6.1 requires a client to cope with that). Ranked worst-first so the verdict can
-// never be improved by the ORDER the controls happen to appear in -- reporting
+// never be improved by the order the controls happen to appear in: reporting
 // the first one seen would let a server bury a failure behind a success.
 var OUTCOME_SEVERITY = { rejected: 4, "pop-required": 3, "confirm-required": 2, pending: 1, issued: 0 };
 
@@ -67,9 +67,9 @@ function _singleValue(control, what) {
 // The single instance of a control, or null when absent.
 //
 // Body-part identity is unique per element, so a responder can legally carry the
-// SAME control type twice under different bodyPartIDs. Taking the first match
+// same control type twice under different bodyPartIDs. Taking the first match
 // would let an attacker pair one correct echo with a contradictory one and still
-// satisfy the binding -- so a duplicate is refused as ambiguous rather than
+// satisfy the binding, so a duplicate is refused as ambiguous instead of
 // resolved. The exchange either has one answer or it has none.
 function _findControl(controls, attrType, what) {
   var found = null;
@@ -90,7 +90,7 @@ function _octets(control, what) {
 // The certificate / CRL bag, from whichever carrier holds it. A SignedData keeps
 // them at the top level; an AuthenticatedData keeps them under `originatorInfo`
 // (RFC 5652 sec. 9.1). Both carriers are accepted for a Full PKI Response, so
-// reading only the SignedData shape would silently return an empty bag -- and
+// reading only the SignedData shape would silently return an empty bag, and
 // "no certificates were issued" is exactly the wrong thing to report when some
 // were.
 function _bagOf(parsedCms, originatorKey, topKey) {
@@ -106,10 +106,30 @@ function _bagOf(parsedCms, originatorKey, topKey) {
  * Both halves are CONDITIONAL on what the client sent, which is the subtlety: a
  * client that sent no transactionId cannot demand one back, and a client that
  * sent no senderNonce has nothing to compare a recipientNonce against. What is
- * NOT conditional is the converse -- having sent one, an absent or differing echo
+ * not conditional is the converse: having sent one, an absent or differing echo
  * is a refusal, because that is exactly the replay the nonce exists to stop.
+ *
+ * Returns which halves ran, because "conditional" and "checked" are different
+ * facts and the verdict has to be able to tell them apart.
  */
 function _assertBound(body, sent) {
+  // A zero-length value binds nothing. An empty senderNonce echoes equal in every
+  // exchange that also used one, so counting its presence would report boundToRequest
+  // true for a response captured from any of them -- the exact replay this gate exists
+  // to refuse, passing because the comparison it ran was vacuous. The same holds for an
+  // empty transactionId or dataReturn: a binding has to carry entropy to be a binding.
+  function _carries(v) {
+    if (v == null) return false;
+    if (typeof v === "string") return v.length > 0;
+    if (Buffer.isBuffer(v) || v instanceof Uint8Array) return v.length > 0;
+    return true;   // an integer or other scalar identifier is its own value
+  }
+  var bound = {
+    transactionId: _carries(sent.transactionId),
+    senderNonce: _carries(sent.senderNonce),
+    dataReturn: _carries(sent.dataReturn),
+    bodyPartIDs: Array.isArray(sent.bodyPartIDs),
+  };
   if (sent.transactionId != null) {
     var txControl = _findControl(body.controls, OID_TRANSACTION_ID, "Transaction Identifier");
     if (!txControl) {
@@ -132,8 +152,8 @@ function _assertBound(body, sent) {
       throw E("cmc/nonce-mismatch",
         "the request carried a Sender Nonce, so the response MUST reflect it back as a Recipient Nonce control (RFC 5272 sec. 6.6)");
     }
-    // Constant-time and by FULL value: guard.crypto.constantTimeEqual gates the
-    // length first, so a truncation or a prefix is an honest false rather than a
+    // Constant-time and by full value: guard.crypto.constantTimeEqual gates the
+    // length first, so a truncation or a prefix is an honest false and not a
     // match on the bytes that happen to line up.
     if (!guard.crypto.constantTimeEqual(_octets(rn, "Recipient Nonce"), Buffer.from(sent.senderNonce))) {
       throw E("cmc/nonce-mismatch", "the response Recipient Nonce does not match the Sender Nonce the request sent");
@@ -142,7 +162,7 @@ function _assertBound(body, sent) {
 
   // RFC 5272 sec. 6.4: "If the Data Return control appears in a Full PKI Request,
   // the server MUST return it as part of the PKI Response." The data is opaque to
-  // the server, so the check is that the SAME bytes came back.
+  // the server, so the check is that the same bytes came back.
   if (sent.dataReturn != null) {
     var dr = _findControl(body.controls, OID_DATA_RETURN, "Data Return");
     if (!dr) {
@@ -175,14 +195,14 @@ function _assertBound(body, sent) {
     var known = Object.create(null);
     sent.bodyPartIDs.forEach(function (id) { known[String(id)] = true; });
     // 0 is reserved as the reference to the enclosing PKIData itself (sec. 3.2.1),
-    // so a status about the request AS A WHOLE is in the set by definition.
+    // so a status about the request as a whole is in the set by definition.
     known["0"] = true;
     body.statuses.forEach(function (s) {
       (s.bodyList || []).forEach(function (ref) {
         var path = ref.bodyPartPath;
         // A bodyPartPath descends INTO a nested message. Checking only its head would
-        // accept `[a part we sent, 999]` -- a status about something arbitrary, wearing a
-        // reference that passes -- so the WHOLE path is matched against the paths the
+        // accept `[a part we sent, 999]`, a status about something arbitrary wearing a
+        // reference that passes, so the whole path is matched against the paths the
         // request actually composed. Those are retained by reading each nested message
         // back; a nested message that could not be read back contributes none, so a path
         // into it finds no match and is refused. Either way the tail is never waved through.
@@ -201,6 +221,34 @@ function _assertBound(body, sent) {
       });
     });
   }
+
+  // Every check above is conditional on the caller having retained something, so a
+  // caller who retained nothing runs none of them and still gets a full verdict
+  // (`issued`, signature verified, certificates surfaced) off a Full PKI Response
+  // captured from any earlier exchange with the same CA. That is the CWE-294 this
+  // module names as its defence, and leaving it opt-in leaves the defence off for
+  // whoever did not know to ask.
+  //
+  // The posture here is the one _assertAuthentic already takes for the carrier
+  // signature, applied to the other question: check it when the caller supplies
+  // what it takes, and refuse when nothing does, unless the caller names that. The
+  // two opt-outs stay separate because they answer separate questions. A replayed
+  // response is authentic, so `allowUnverified` covering it would let "I could not
+  // check the signature" stand in for "I did not check which exchange this
+  // answers".
+  //
+  // bodyPartIDs does not count toward it. Identifiers are allocated per message
+  // from a small range (sec. 3.2.2), so the same set recurs across requests and a
+  // status naming one says nothing about which request it answers.
+  bound.boundToRequest = bound.transactionId || bound.senderNonce || bound.dataReturn;
+  if (!bound.boundToRequest && sent.allowUnbound !== true) {
+    throw E("cmc/unbound-response",
+      "nothing ties this response to a request. Pass what the request retained (`transactionId`, " +
+      "`senderNonce`, whose echo is the replay defence of RFC 5272 sec. 6.6, or `dataReturn`) so the " +
+      "echo can be checked, or `allowUnbound: true` to interpret a response that could be a replay of " +
+      "any earlier exchange with this CA");
+  }
+  return bound;
 }
 
 // The worst outcome across every status control, with success assumed when there
@@ -234,7 +282,7 @@ function _governingStatus(statuses, outcome) {
  * @defends    cmc-response-replay (CWE-294)
  * @related    pki.schema.cmc.parse, pki.path.validate, pki.cms.verify
  *
- * Interpret a Full PKI Response into ONE terminal verdict. `response` is the DER or a PEM `CMS`
+ * Interpret a Full PKI Response into one terminal verdict. `response` is the DER or a PEM `CMS`
  * block; an already-parsed message is interpreted too, but only under `allowUnverified: true`,
  * because both carriers authenticate over BYTES and a parsed object the caller still owns pins
  * none. `sent` is what the client retained from its request --
@@ -245,6 +293,16 @@ function _governingStatus(statuses, outcome) {
  * with `cmc/body-part-unknown`, which the transaction and nonce cannot catch, since a server can
  * echo both correctly while reporting on something else.
  *
+ * Because each half is conditional, a caller who retains nothing runs none of them. A Full PKI
+ * Response captured from any earlier exchange with the same CA would then read as this request's
+ * answer, correctly signed. That case is refused as `cmc/unbound-response` unless the caller names
+ * it with `allowUnbound: true`, a separate opt-out from `allowUnverified` because it answers a
+ * separate question: a replayed response is authentic. `bodyPartIDs` alone does not satisfy it,
+ * since identifiers are allocated per message from a small range (RFC 5272 sec. 3.2.2) and the
+ * same set recurs across requests. The verdict reports which halves ran as `bound.transactionId`,
+ * `bound.senderNonce`, `bound.dataReturn` and `bound.bodyPartIDs`, with `boundToRequest` for the
+ * roll-up.
+ *
  * The verdict carries the response's own `cmsSequence` and `otherMsgs` raw, because a request whose
  * only arm was the other-message form has no certificate to return and RFC 5272 sec. 4.1 puts its
  * answer there instead.
@@ -269,9 +327,9 @@ function _governingStatus(statuses, outcome) {
  *
  * The other carrier sec. 3.2 permits, AuthenticatedData, is authenticated by its MAC instead: pass
  * `recipient` with the key material and the MAC is checked through `pki.cms.decrypt`, so a caller
- * who holds the key gets an authenticated verdict rather than the unauthenticated opt-out.
+ * who holds the key gets an authenticated verdict instead of the unauthenticated opt-out.
  *
- * Nothing is trusted here. `certificates` is the CMS certificate bag -- where RFC 5272 sec. 4.2
+ * Nothing is trusted here. `certificates` is the CMS certificate bag, where RFC 5272 sec. 4.2
  * puts the issued certificates -- surfaced raw for the caller to run through `pki.path.validate`,
  * and a Publish Trust Anchors control is surfaced as `publishTrustAnchors` with `trusted: false`,
  * never added to any store (RFC 5272 sec. 6.15 makes accepting one a four-part manual decision).
@@ -288,6 +346,9 @@ function _governingStatus(statuses, outcome) {
  *     `signatureVerified: true`; the content it authenticates is bound to the content the verdict
  *     was read from, so a MAC over other bytes cannot stand in for it.
  *   - `allowUnverified` (boolean) -- interpret without verifying the carrier; sets `signatureVerified: false`.
+ *   - `allowUnbound` (boolean) -- interpret a response nothing ties to a request; sets
+ *     `boundToRequest: false`. Needed only when none of `transactionId`, `senderNonce` or
+ *     `dataReturn` was retained, and what it accepts is a possible replay.
  * @example
  *   var b = pki.asn1.build, oid = pki.oid;
  *   var sid = b.sequence([b.sequence([b.set([b.sequence([b.oid(oid.byName("commonName")),
@@ -301,9 +362,10 @@ function _governingStatus(statuses, outcome) {
  *   var encap = b.sequence([b.oid(oid.byName("id-cct-PKIResponse")), b.explicit(0, b.octetString(body))]);
  *   var sd = b.sequence([b.integer(3n), b.set([]), encap, b.set([si])]);
  *   var der = b.sequence([b.oid(oid.byName("signedData")), b.explicit(0, sd)]);
- *   var v = await pki.cmc.verify(der, { allowUnverified: true });
+ *   var v = await pki.cmc.verify(der, { allowUnverified: true, allowUnbound: true });
  *   v.outcome;             // "issued" -- no status control means success is assumed
  *   v.signatureVerified;   // false -- the opt-out was named, so nothing was checked
+ *   v.boundToRequest;      // false: nothing ties this response to a request either
  */
 function verify(response, sent) {
   // Both snapshots are taken SYNCHRONOUSLY, here, before anything is deferred.
@@ -398,7 +460,10 @@ function _snapshotSent(sent) {
     out.recipient = r;
   }
   if (Array.isArray(out.certs)) out.certs = out.certs.map(_copyAnyBytes);
+  // Both opt-outs normalized to a strict boolean off the ORIGINAL object, so a
+  // truthy-but-not-true value cannot switch a check off by accident.
   out.allowUnverified = sent.allowUnverified === true;
+  out.allowUnbound = sent.allowUnbound === true;
   return out;
 }
 
@@ -415,8 +480,7 @@ function _verify(response, sent) {
   }
 
   return _assertAuthentic(body, sent, response).then(function (signatureVerified) {
-    _assertBound(body, sent);
-    return _shape(body, sent, signatureVerified);
+    return _shape(body, sent, signatureVerified, _assertBound(body, sent));
   });
 }
 
@@ -555,7 +619,7 @@ function _assertAuthentic(body, sent, responseBytes) {
   });
 }
 
-function _shape(body, sent, signatureVerified) {
+function _shape(body, sent, signatureVerified, bound) {
   var outcome = _reduceOutcome(body.statuses);
   var governing = _governingStatus(body.statuses, outcome);
   var anchors = _findControl(body.controls, OID_TRUSTED_ANCHORS, "Publish Trust Anchors");
@@ -591,6 +655,18 @@ function _shape(body, sent, signatureVerified) {
     // Whether the CARRIER's signature was checked. False only via the explicit
     // allowUnverified opt-out -- there is no path that leaves it false silently.
     signatureVerified: signatureVerified,
+    // Which halves of the exchange binding ran (RFC 5272 sec. 6.6 / 6.4). Each is
+    // conditional on the caller having retained the value, so a bare `outcome`
+    // cannot say whether this response answers this request or an earlier one.
+    // These can. `boundToRequest` is false only via the explicit allowUnbound
+    // opt-out; nothing leaves it false silently.
+    bound: {
+      transactionId: bound.transactionId,
+      senderNonce: bound.senderNonce,
+      dataReturn: bound.dataReturn,
+      bodyPartIDs: bound.bodyPartIDs,
+    },
+    boundToRequest: bound.boundToRequest,
     // Whether anything in here was TRUSTED, which is never: the certificate bag
     // and any Publish Trust Anchors control are the caller's to path-validate.
     trusted: false,
@@ -610,33 +686,33 @@ function _shape(body, sent, signatureVerified) {
  * @related    pki.cmc.verify, pki.schema.cmc.parse, pki.cms.sign
  *
  * Build and sign an RFC 5272 Full PKI Request. `spec.requests` is the list of certification
- * requests, each naming exactly one arm -- `tcr` (a PKCS#10 CSR), `crm` (a CRMF CertReqMsg, or the
+ * requests, each naming exactly one arm: `tcr` (a PKCS#10 CSR), `crm` (a CRMF CertReqMsg, or the
  * CertReqMessages `pki.crmf.build` returns when it carries exactly one) or `orm`
  * (`{ type, value }`). `spec.controls` are additional controls as `{ type, value }`, and `signer`
  * is the `{ cert, key }` that signs the enclosing CMS SignedData.
  *
  * Body part identifiers are allocated automatically, unique across the whole message and never 0
- * (RFC 5272 sec. 3.2.2). A caller may pin one, and a clash is REFUSED rather than renumbered --
+ * (RFC 5272 sec. 3.2.2). A caller may pin one, and a clash is refused, never renumbered, because
  * silently moving an identifier would break any control that already referenced it. For a `crm`
  * arm the identity is the CertReqMsg's own `certReqId`, read back out of the supplied message.
  *
  * `spec.identityProof: { secret, identity? }` attaches an Identity Proof V2 control whose witness is
- * computed over the reqSequence bytes exactly as they are emitted (sec. 6.2.1 step 1 -- "encoded
+ * computed over the reqSequence bytes exactly as they are emitted (sec. 6.2.1 step 1: "encoded
  * exactly as it appears in the Full PKI Request including the sequence type and length"). Supplying
- * `identity` also emits the Identification control naming the shared secret, and -- per sec. 6.2.3 --
- * derives the MAC key from `hash(secret || identity)` rather than `hash(secret)`: the two travel
+ * `identity` also emits the Identification control naming the shared secret and, per sec. 6.2.3,
+ * derives the MAC key from `hash(secret || identity)` in place of `hash(secret)`: the two travel
  * together because the control's presence is what changes the derivation. And
  * `spec.popLink: { secret }` attaches a POP Link Witness V2 together with the POP Link Random
  * control that PL1 requires in the same request. `spec.renewal: true` marks a renewal, which MUST
- * carry neither Identification nor Identity Proof (sec. 3.2 (a)) -- asking for both is refused
- * rather than silently dropped.
+ * carry neither Identification nor Identity Proof (sec. 3.2 (a)), so asking for both is refused
+ * and never silently dropped.
  *
  * `spec.transactionId` (number|bigint), `spec.senderNonce` and `spec.dataReturn` (bytes) attach the
- * exchange-binding controls (RFC 5272 sec. 6.6 / 6.4) -- the same three `pki.cmc.verify` checks the
- * response against. They are named fields rather than something to hand-encode into
+ * exchange-binding controls (RFC 5272 sec. 6.6 / 6.4), the same three `pki.cmc.verify` checks the
+ * response against. They are named fields, not something to hand-encode into
  * `spec.controls`, because a request that quietly omits them has no replay defence and neither end
  * can tell: the verifier only enforces the halves the client says it sent. An unrecognized spec
- * field is refused for the same reason -- a misspelling would otherwise build and sign a message
+ * field is refused for the same reason: a misspelling would otherwise build and sign a message
  * that simply does not carry what was asked for.
  *
  * @opts

package/lib/cmp-build.js

@@ -19,8 +19,8 @@
  * @card Build a CMP PKIMessage with signature or PBMAC1 protection.
  */
 //
-// RFC 9810 Appendix A is DEFINITIONS EXPLICIT TAGS: every context tag in the PKIMessage envelope --
-// each PKIHeader [0..8] optional, every PKIBody [n] arm, protection [0], extraCerts [1] -- is an EXPLICIT
+// RFC 9810 Appendix A is DEFINITIONS EXPLICIT TAGS: every context tag in the PKIMessage envelope
+// (each PKIHeader [0..8] optional, every PKIBody [n] arm, protection [0], extraCerts [1]) is an EXPLICIT
 // wrapper (asn1.build.explicit), the exact inverse of the RFC 4211 CRMF interior (IMPLICIT TAGS). The two
 // IMPLICIT islands are foreign imports produced wholesale by pki.crmf.build (the CertReqMessages /
 // CertTemplate interior) and embedded verbatim, never re-encoded here. Protection is computed over the
@@ -67,7 +67,7 @@ var KNOWN_BODY_KEYS = {
   ir: 1, cr: 1, kur: 1, p10cr: 1, certConf: 1, pollReq: 1, genm: 1, rr: 1,   // request-side
   ip: 1, cp: 1, kup: 1, ccp: 1, krp: 1, rp: 1, genp: 1, error: 1, pollRep: 1, pkiconf: 1,   // CA/responder-side
 };
-// The PKIBody arm -> its EXPLICIT context tag number (schema-cmp.js BODY_ARMS). rr is [11], NOT [15].
+// The PKIBody arm -> its EXPLICIT context tag number (schema-cmp.js BODY_ARMS). rr is [11], not [15].
 var BODY_TAG = {
   ir: 0, cr: 2, p10cr: 4, kur: 7, rr: 11, genm: 21, certConf: 24, pollReq: 25,
   ip: 1, cp: 3, kup: 8, krp: 10, rp: 12, ccp: 14, pkiconf: 19, genp: 22, error: 23, pollRep: 26,
@@ -88,7 +88,7 @@ var PBMAC1_MIN_ITER = 1000;       // RFC 8018 sec. 4.2 recommended minimum -- re
 var PBMAC1_PRF = { "SHA-256": "hmacWithSHA256", "SHA-384": "hmacWithSHA384", "SHA-512": "hmacWithSHA512" };
 var PBMAC1_MAC_OID = { "SHA-256": "hmacWithSHA256", "SHA-384": "hmacWithSHA384", "SHA-512": "hmacWithSHA512" };
 var PBMAC1_PRF_HLEN = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };   // PBKDF2 PRF output length (one derived block)
-// PKIFailureInfo named bits (RFC 9810 sec. 5.2.3), position = bit index -- mirrors schema-cmp's decode list;
+// PKIFailureInfo named bits (RFC 9810 sec. 5.2.3), position = bit index, mirroring schema-cmp's decode list;
 // the build -> parse round-trip cross-checks the positions against the parser.
 var FAIL_INFO_NAMES = ["badAlg", "badMessageCheck", "badRequest", "badTime", "badCertId", "badDataFormat",
   "wrongAuthority", "incorrectData", "missingTimeStamp", "badPOP", "certRevoked", "certConfirmed",
@@ -97,7 +97,7 @@ var FAIL_INFO_NAMES = ["badAlg", "badMessageCheck", "badRequest", "badTime", "ba
   "unsupportedVersion", "notAuthorized", "systemUnavail", "systemFailure", "duplicateCertReq"];
 var FAIL_INFO_INDEX = {};
 FAIL_INFO_NAMES.forEach(function (n, i) { FAIL_INFO_INDEX[n] = i; });
-// CertStatus.hashAlg names the hash used to compute certHash -- restrict it to hash algorithms, not any OID.
+// CertStatus.hashAlg names the hash used to compute certHash, restricted to hash algorithms and not any OID.
 var CERT_CONF_HASH_ALGS = { sha1: 1, sha256: 1, sha384: 1, sha512: 1, "sha3-256": 1, "sha3-512": 1 };
 
 // ---- small shared encoders (byte-exact inverses of schema-cmp.js readers) ----
@@ -107,7 +107,7 @@ function _reqOctets(v, what) {
   return b.octetString(buf);
 }
 
-// PKIFreeText ::= SEQUENCE SIZE (1..MAX) OF UTF8String -- non-empty, every element UTF8String.
+// PKIFreeText ::= SEQUENCE SIZE (1..MAX) OF UTF8String: non-empty, every element UTF8String.
 function _encodePkiFreeText(strings, code, what) {
   if (!Array.isArray(strings) || !strings.length) throw _err(code, what + " must be a non-empty array of strings");
   return b.sequence(strings.map(function (s) {
@@ -193,7 +193,7 @@ function _encodeHeader(headerSpec, protectionAlgDer, pvno) {
 // or a bigint (a large value beyond 2^53), reject a non-integer / other type. Returns a BigInt for b.integer.
 function _reqIdInt(v, code, what) { return guard.range.authoredInteger(v, _err, code, what); }
 
-// PKIFailureInfo ::= BIT STRING (named bits, RFC 9810 sec. 5.2.3) -- a minimal NamedBitList from bit names.
+// PKIFailureInfo ::= BIT STRING (named bits, RFC 9810 sec. 5.2.3): a minimal NamedBitList from bit names.
 function _encodeFailInfo(names, code) {
   if (!Array.isArray(names)) throw _err(code, "statusInfo.failInfo must be an array of PKIFailureInfo bit names");
   return b.namedBitString(names.map(function (n) {
@@ -288,7 +288,7 @@ function _encodeCertOrEncCert(coec, state) {
   }
   if (coec.encryptedCert != null) {
     // encryptedCert [1] wraps an EncryptedKey (pre-encoded DER hatch in v1). Like the privateKey, only the
-    // EnvelopedData [0] form is cmp2021 -- the deprecated EncryptedValue (a universal SEQUENCE) is cmp2000.
+    // EnvelopedData [0] form is cmp2021; the deprecated EncryptedValue (a universal SEQUENCE) is cmp2000.
     var ec = _b.reqDer(coec.encryptedCert, "certifiedKeyPair.encryptedCert (a pre-encoded EncryptedKey DER)");
     var ecNode;
     try { ecNode = asn1.decode(ec); } catch (e) { throw _err("cmp/bad-cert-response", "certifiedKeyPair.encryptedCert is not valid DER", e); }
@@ -475,7 +475,7 @@ function _encodeBody(bodySpec, key, opts) {
 
 
 // Resolve the protection selector to { protectionAlgDer, computeBits(protectedPartDer)->Promise<Buffer> },
-// senderSpki, senderScheme } BEFORE the header is built (protectionAlg is opts-derived, not header-derived).
+// senderSpki, senderScheme } before the header is built (protectionAlg is opts-derived, not header-derived).
 function _resolveProtection(opts) {
   var hasSig = opts.key != null || opts.cert != null;
   var hasMac = opts.mac != null;
@@ -517,11 +517,11 @@ function _resolveProtection(opts) {
   if (!PBMAC1_PRF[prf]) throw _err("cmp/bad-input", "opts.mac.prf must be SHA-256 / SHA-384 / SHA-512");
   var iterationCount = m.iterationCount != null ? m.iterationCount : PBMAC1_DEFAULT_ITER;
   if (typeof iterationCount !== "number" || !Number.isInteger(iterationCount) || iterationCount < PBMAC1_MIN_ITER) throw _err("cmp/bad-input", "opts.mac.iterationCount must be at least " + PBMAC1_MIN_ITER + " (RFC 8018 sec. 4.2)");
-  // Bound the PBKDF2 work factors BEFORE deriving -- a huge iterationCount / keyLength is self-inflicted work.
+  // Bound the PBKDF2 work factors before deriving: a huge iterationCount or keyLength is self-inflicted work.
   if (iterationCount > constants.LIMITS.PBKDF2_MAX_ITERATIONS) throw _err("cmp/bad-input", "opts.mac.iterationCount exceeds the PBKDF2 work-factor cap " + constants.LIMITS.PBKDF2_MAX_ITERATIONS);
   var keyLength = m.keyLength != null ? m.keyLength : PBMAC1_DEFAULT_KEYLEN;
   // RFC 9579 sec. 9 floor (>= 20 bytes): produce only messages the verifier (pki.cmp.verify, same floor) can
-  // accept -- a shorter derived key is refused at production time rather than emitted as an unverifiable message.
+  // accept, so a shorter derived key is refused at production time and never emitted as an unverifiable message.
   if (typeof keyLength !== "number" || !Number.isInteger(keyLength) || keyLength < PBMAC1_MIN_KEYLEN) throw _err("cmp/bad-input", "opts.mac.keyLength must be an integer >= " + PBMAC1_MIN_KEYLEN + " bytes (RFC 9579 sec. 9)");
   if (keyLength > PBMAC1_MAX_KEYLEN) throw _err("cmp/bad-input", "opts.mac.keyLength exceeds the cap " + PBMAC1_MAX_KEYLEN + " bytes");
   // Bound the COMBINED work: a keyLength spanning multiple PRF blocks costs iterationCount HMACs per block, so
@@ -530,7 +530,7 @@ function _resolveProtection(opts) {
   var blocks = Math.ceil(keyLength / PBMAC1_PRF_HLEN[prf]);
   if (iterationCount * blocks > constants.LIMITS.PBKDF2_MAX_ITERATIONS) throw _err("cmp/bad-input", "opts.mac combined work (iterationCount " + iterationCount + " x " + blocks + " derived blocks) exceeds the PBKDF2 work-factor cap " + constants.LIMITS.PBKDF2_MAX_ITERATIONS);
   var salt = m.salt != null ? _b.reqDer(m.salt, "opts.mac.salt") : Buffer.from(webcrypto.webcrypto.getRandomValues(new Uint8Array(PBMAC1_DEFAULT_SALT_BYTES)));
-  // RFC 8018 sec. 4.1 (64-bit) floor: an empty / short salt loses precomputation resistance -- produce only
+  // RFC 8018 sec. 4.1 (64-bit) floor: an empty or short salt loses precomputation resistance, so produce only
   // messages pki.cmp.verify (same floor) accepts, refusing a below-minimum salt at construction time.
   if (salt.length < PBMAC1_MIN_SALT) throw _err("cmp/bad-input", "opts.mac.salt must be at least " + PBMAC1_MIN_SALT + " octets (RFC 8018 sec. 4.1)");
   if (salt.length > constants.LIMITS.PBKDF2_MAX_SALT) throw _err("cmp/bad-input", "opts.mac.salt exceeds " + constants.LIMITS.PBKDF2_MAX_SALT + " bytes");
@@ -550,7 +550,7 @@ function _resolveProtection(opts) {
 // ---- orchestrator ----
 
 function build(message, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // Every caller-owned argument copied at entry and released when the call settles; see the note
   // on the same call in x509-sign. `opts.mac.secret` is why the copy has to be deep: it sits a
   // level below the options object and is read by the PBMAC1 derivation after the first turn.
   return guard.bytes.fixedCall(CmpError, "cmp/bad-input", [
@@ -626,23 +626,23 @@ function _collectExtraCerts(opts, protCertDer) {
  * single-key object naming the arm. Request-side: `{ ir }` / `{ cr }` / `{ kur }` (a `CertReqMessages` spec
  * delegated to `pki.crmf.build`; the proof-of-possession key is `key` on the arm spec), `{ p10cr }` (a PKCS#10
  * CertificationRequest DER), `{ certConf }`, `{ pollReq }`, `{ genm }`, `{ rr }`. CA/responder-side: `{ ip }` /
- * `{ cp }` / `{ kup }` / `{ ccp }` (a `CertRepMessage` -- `caPubs` + `response` of `CertResponse` each with a
+ * `{ cp }` / `{ kup }` / `{ ccp }` (a `CertRepMessage`: `caPubs` plus `response` of `CertResponse` each with a
  * `PKIStatusInfo` and, under a granting status, a `certifiedKeyPair`), `{ rp }` (`RevRepContent`), `{ genp }`,
  * `{ error }` (`ErrorMsgContent`), `{ pollRep }`, `{ krp }` (`KeyRecRepContent`), `{ pkiconf }` (NULL). The
- * message is protected: `opts` carries EXACTLY
- * ONE of `{ key, cert }` (a signature under the sender key over the message -- any registry algorithm, RSA
+ * message is protected: `opts` carries exactly
+ * one of `{ key, cert }` (a signature under the sender key over the message, using any registry algorithm: RSA
  * / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite, resolved from the certificate) or `{ mac }` (a PBMAC1
  * shared-secret MAC). The protection is computed over the exact DER of the virtual
  * `ProtectedPart ::= SEQUENCE { header, body }` and self-verified before the message is returned. The
  * emitted PKIMessage round-trips byte-identically through `pki.schema.cmp.parse`.
  *
  * @opts
- *   - `key` (Buffer|CryptoKey) + `cert` (Buffer) -- signature protection under the sender key; `cert` is
+ *   - `key` (Buffer|CryptoKey) + `cert` (Buffer): signature protection under the sender key; `cert` is
  *     the signer certificate (its SPKI resolves the algorithm) and is placed in `extraCerts`.
- *   - `mac` ({ secret, salt?, iterationCount?, prf?, keyLength? }) -- PBMAC1 protection from a shared secret.
- *   - `extraCerts` (array of Buffer) -- additional certificates to carry in `extraCerts [1]`.
- *   - `pem` (boolean|string) -- return a PEM `CMP` block instead of DER.
- *   - `pss` (boolean) / `digestAlgorithm` (string) -- signature-protection algorithm options.
+ *   - `mac` ({ secret, salt?, iterationCount?, prf?, keyLength? }): PBMAC1 protection from a shared secret.
+ *   - `extraCerts` (array of Buffer): additional certificates to carry in `extraCerts [1]`.
+ *   - `pem` (boolean|string): return a PEM `CMP` block instead of DER.
+ *   - `pss` (boolean) / `digestAlgorithm` (string): signature-protection algorithm options.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -839,17 +839,17 @@ function wellKnownUrl(base, opts) {
  * @related    pki.cmp.build, pki.cmp.wellKnownUrl, pki.schema.cmp.parse, pki.transport.https
  *
  * POST a DER `PKIMessage` to a CMP endpoint and return the parsed response `PKIMessage`, over the shared
- * `pki.transport`. RFC 9811 transfers every CMP exchange identically -- one HTTP POST of a DER PKIMessage,
- * one response PKIMessage -- so a single stateless verb carries `ir` / `cr` / `kur` / `p10cr` / `certConf`
+ * `pki.transport`. RFC 9811 transfers every CMP exchange identically, as one HTTP POST of a DER PKIMessage
+ * and one response PKIMessage, so a single stateless verb carries `ir` / `cr` / `kur` / `p10cr` / `certConf`
  * / `pollReq` / `rr` / `genm` and their responses; the caller builds and protects the message upstream with
  * `pki.cmp.build` and hands the finished bytes here. `message` is a DER `Buffer`/`Uint8Array` or a PEM `CMP`
- * string, sent VERBATIM (the message-layer protection covers these exact bytes -- they are never re-encoded).
+ * string, sent verbatim (the message-layer protection covers these exact bytes; they are never re-encoded).
  * The response is classified fail-closed: HTTP 200 carrying an `application/pkixcmp` body is parsed and
  * resolved; another 2xx is `cmp/unexpected-status` (RFC 9811 requires 200); a 3xx is `cmp/redirect-not-followed`
  * (never auto-followed, sec. 3.1/5); a 4xx/5xx carrying a well-formed CMP `error` PKIMessage FORWARDS that
  * integrity-protected verdict (sec. 1.2/3.1) with the HTTP status surfaced as data, while a 4xx/5xx that is
  * not a CMP `error` message (no body, an undecodable body, or a non-error arm) is `cmp/http-error`.
- * Protection is SURFACED, not verified -- the client confers no trust; the
+ * Protection is surfaced, not verified: the client confers no trust, and the
  * caller (or a future `pki.cmp.verify`) checks the response protection using the raw `headerBytes`/`bodyBytes`.
  * By default the transport is https-only and requires an explicit trust anchor; there is no client scheme
  * gate, so an operator who injects an http-capable transport reaches the RFC-9811-permitted plain-HTTP path.