@blamejs/pki 0.5.6 → 0.5.8

package/lib/cmc-build.js

@@ -2,7 +2,7 @@
 // Copyright (c) blamejs contributors
 "use strict";
 //
-// @internal -- the pki.cmc.build implementation. So the pki.cmc namespace has ONE @module home,
+// @internal -- the pki.cmc.build implementation. So the pki.cmc namespace has one @module home,
 // the operator-facing @module pki.cmc + the @primitive pki.cmc.build documentation block live in
 // cmc-verify.js, which re-exports this build function.
 //
@@ -19,8 +19,8 @@
  * The witness rule is the load-bearing one. RFC 5272 sec. 6.2.1 step 1 says the
  * value to be validated is "The PKIData reqSequence field (encoded exactly as it
  * appears in the Full PKI Request including the sequence type and length)". So
- * the reqSequence TLV is built ONCE and both the message and the witness are
- * derived from that single buffer -- computing the witness over a second
+ * the reqSequence TLV is built once and both the message and the witness are
+ * derived from that single buffer; computing the witness over a second
  * serialization would agree with itself while disagreeing with the wire the
  * moment any encoding detail differed.
  */
@@ -46,10 +46,10 @@ var OID_IDENTIFICATION = O("id-cmc-identification");
 var OID_SHA256 = O("sha256");
 var OID_HMAC_SHA256 = O("hmacWithSHA256");
 
-// The identity-bearing controls a renewal must NOT carry: RFC 5272 sec. 3.2 (a)
-// -- "The Identification and Identity Proof controls are absent."
+// The identity-bearing controls a renewal must not carry: RFC 5272 sec. 3.2 (a),
+// "The Identification and Identity Proof controls are absent."
 //
-// "Identity Proof" is BOTH versions: the original id-cmc-identityProof (sec.
+// "Identity Proof" covers both versions: the original id-cmc-identityProof (sec.
 // 6.2.2) and identityProofV2 (sec. 6.2.1). Listing only V2 would leave a renewal
 // able to carry the v1 control, which is the same nonconformance the rule names.
 var RENEWAL_FORBIDDEN = {};
@@ -57,14 +57,14 @@ RENEWAL_FORBIDDEN[OID_IDENTIFICATION] = "Identification";
 RENEWAL_FORBIDDEN[O("id-cmc-identityProof")] = "Identity Proof";
 RENEWAL_FORBIDDEN[OID_IDENTITY_PROOF_V2] = "Identity Proof V2";
 
-// RFC 6402 sec. 2.6: responseBody appears ONLY in a PKIResponse. Enforced at
-// BUILD time as well as at parse, so a caller cannot emit a message its own
+// RFC 6402 sec. 2.6: responseBody appears only in a PKIResponse. Enforced at
+// build time as well as at parse, so a caller cannot emit a message its own
 // decoder would refuse.
 var OID_RESPONSE_BODY = O("id-cmc-responseBody");
 
 // RFC 5272 sec. 6.2.1 says "Implementations MUST be able to support tokens at
-// least 16 characters long" -- a requirement on what an implementation must be
-// ABLE to accept, not a floor every token has to clear. Reading it as a minimum
+// least 16 characters long", a requirement on what an implementation must be
+// able to accept, not a floor every token has to clear. Reading it as a minimum
 // inverts it, and would refuse a shorter secret a CA legitimately provisioned.
 // The shared secret's strength is the deploying CA's policy; what this layer can
 // say is that an empty string is not a credential at all.
@@ -72,12 +72,12 @@ var OID_RESPONSE_BODY = O("id-cmc-responseBody");
 var POP_LINK_RANDOM_BYTES = 64;
 
 // The spec fields pki.cmc.build understands. Anything else is a caller mistake
-// caught at the entry point rather than silently dropped from the message.
+// caught at the entry point, never silently dropped from the message.
 var KNOWN_SPEC_KEYS = {
   requests: 1, controls: 1, cmsSequence: 1, otherMsgSequence: 1,
-  // NOT `identification`: the Identification control is attached through
+  // `identification` is deliberately absent: the Identification control is attached through
   // identityProof.identity, which is what emits it. Listing a key nothing reads
-  // would recreate the very hole this table closes -- accepted at the door and
+  // would recreate the very hole this table closes, accepted at the door and
   // silently absent from the message.
   identityProof: 1, popLink: 1, renewal: 1,
   // The exchange binding (RFC 5272 sec. 6.6 / 6.4). First-class here because
@@ -91,20 +91,20 @@ var OID_TRANSACTION_ID = O("id-cmc-transactionId");
 var OID_SENDER_NONCE = O("id-cmc-senderNonce");
 var OID_DATA_RETURN = O("id-cmc-dataReturn");
 
-// AlgorithmIdentifier { OID } with no parameters -- the form the MAC / hash
+// AlgorithmIdentifier { OID } with no parameters: the form the MAC / hash
 // algorithm identifiers in these two controls take.
 function algId(o) { return b.sequence([b.oid(o)]); }
 
 // ---- body part identity ---------------------------------------------
 
-// RFC 5272 sec. 3.2.2: identifiers are unique across the WHOLE message and 0 is
+// RFC 5272 sec. 3.2.2: identifiers are unique across the whole message and 0 is
 // reserved for the reference to the current PKIData. The allocator therefore
-// starts at 1, and a caller-supplied value is validated rather than adjusted --
+// starts at 1, and a caller-supplied value is validated, never adjusted;
 // silently renumbering would break any control that already references it.
 function makeIdAllocator() {
   var used = Object.create(null);
   // Reserved ahead of allocation and not yet consumed by the element that owns
-  // it. Kept distinct from `used` so an element re-claiming its OWN reservation
+  // it. Kept distinct from `used` so an element re-claiming its own reservation
   // is a no-op, while a second element asking for the same value is still the
   // duplicate the rule forbids.
   var pending = Object.create(null);
@@ -151,11 +151,11 @@ function makeIdAllocator() {
 
 // TaggedRequest ::= CHOICE { tcr [0], crm [1], orm [2] }, IMPLICIT tags. For the
 // crm arm the identity is the CertReqMsg's own certReqId (sec. 3.2.2), so it is
-// read back out of the supplied message rather than allocated -- allocating one
+// read back out of the supplied message and never allocated; allocating one
 // would put a second, contradictory identifier on the wire.
-// The identifier a request FIXES, or null when it leaves the choice to us. Read
+// The identifier a request fixes, or null when it leaves the choice to us. Read
 // in a pre-pass so every caller-determined value is reserved before a single
-// generated one is handed out -- otherwise acceptance depends on the order the
+// generated one is handed out; otherwise acceptance depends on the order the
 // caller happened to write the list in, which is not a property of the message.
 // The fields a request descriptor understands -- the same door KNOWN_SPEC_KEYS
 // closes on the spec, on the objects nested inside it. A misspelled `bodyPartID`
@@ -165,9 +165,9 @@ function makeIdAllocator() {
 var KNOWN_REQUEST_KEYS = { tcr: 1, crm: 1, orm: 1, bodyPartID: 1 };
 // The same door on the other descriptors nested in a spec. A control's identifier
 // is always allocated, so a `bodyPartID` written on one is ignored outright; and a
-// misspelled `identity` does not merely go missing -- the Identification control
+// misspelled `identity` does not merely go missing: the Identification control
 // it would have emitted is what tells the server to derive the Identity Proof key
-// from the secret AND the identity, so the message would carry a witness no
+// from the secret and the identity, so the message would carry a witness no
 // conforming server can reproduce.
 var KNOWN_CONTROL_KEYS = { type: 1, value: 1 };
 var KNOWN_IDENTITY_PROOF_KEYS = { identity: 1, secret: 1 };
@@ -185,12 +185,12 @@ function fixedRequestId(req, index) {
       "each request names exactly one of tcr / crm / orm, got " + (arms.length ? arms.join(" + ") : "none") +
       " (request " + index + ")");
   }
-  // A crm arm's identity is its CertReqMsg's own certReqId, so it is ALWAYS fixed
-  // -- there is nothing to allocate and nothing that may displace it. A caller who
-  // ALSO writes bodyPartID is stating an identity, and the only reason to state one
+  // A crm arm's identity is its CertReqMsg's own certReqId, so it is always fixed:
+  // there is nothing to allocate and nothing that may displace it. A caller who
+  // also writes bodyPartID is stating an identity, and the only reason to state one
   // is that something already references it; taking the certReqId silently would
-  // sign a message whose control points at no request in it. Equal is accepted --
-  // the caller is agreeing with the message, not overriding it.
+  // sign a message whose control points at no request in it. Equal is accepted,
+  // since the caller is agreeing with the message, not overriding it.
   if (req.crm != null) {
     var crmId = _certReqIdOf(_asCertReqMsg(_der(req.crm, "a crm CertReqMsg")));
     if (req.bodyPartID != null && _asBigInt(req.bodyPartID, "a crm request bodyPartID") !== BigInt(crmId)) {
@@ -205,7 +205,7 @@ function fixedRequestId(req, index) {
 
 function encodeRequest(req, ids, index) {
   if (req.tcr != null) {
-    // A tcr arm IS a PKCS#10 CertificationRequest, so it is parsed rather than
+    // A tcr arm is a PKCS#10 CertificationRequest, so it is parsed and never
     // taken on the tag: the readback of the assembled message checks the CMC
     // structure around it, and would pass an empty SEQUENCE here as happily as a
     // real request. Signing a request body that is not one produces an enrolment
@@ -231,12 +231,12 @@ function encodeRequest(req, ids, index) {
     // CLAIM, not just read. The certReqId was reserved in the pre-pass with every
     // other caller-determined identifier; leaving the reservation outstanding lets
     // a later cmsSequence or otherMsg element asking for the same number be taken
-    // for its owner, and the message would then carry the identifier twice -- a
+    // for its owner, and the message would then carry the identifier twice: a
     // PKIData this toolkit's own parser refuses. The tcr and orm arms already
     // claim; this arm is the same rule.
     var certReqId = ids.claim(_certReqIdOf(msg), "a crm request");
-    // IMPLICIT [1]: the tag REPLACES the CertReqMsg SEQUENCE tag, so the content
-    // is re-headered rather than nested.
+    // IMPLICIT [1]: the tag replaces the CertReqMsg SEQUENCE tag, so the content
+    // is re-headered, not nested.
     var node = asn1.decode(msg);
     var headerLen = node.header.end - node.header.start;
     return { bodyPartID: certReqId, der: b.contextConstructed(1, node.bytes.subarray(headerLen)) };
@@ -253,17 +253,17 @@ function encodeRequest(req, ids, index) {
   };
 }
 
-// A TaggedRequest's crm arm carries ONE CertReqMsg, but `pki.crmf.build` returns
-// a CertReqMessages (SEQUENCE SIZE(1..MAX) OF CertReqMsg) -- which is what a
+// A TaggedRequest's crm arm carries one CertReqMsg, but `pki.crmf.build` returns
+// a CertReqMessages (SEQUENCE SIZE(1..MAX) OF CertReqMsg), which is what a
 // caller naturally has in hand. Both are accepted, told apart structurally:
 //
 //   CertReqMsg      ::= SEQUENCE { certReq CertRequest, ... }   first child is a
-//                       SEQUENCE whose OWN first child is an INTEGER (certReqId)
+//                       SEQUENCE whose own first child is an INTEGER (certReqId)
 //   CertReqMessages ::= SEQUENCE OF CertReqMsg                  first child is a
 //                       CertReqMsg, whose own first child is a SEQUENCE
 //
-// A CertReqMessages carrying more than one message is REFUSED rather than having
-// its first taken: each CertReqMsg is its own TaggedRequest with its own identity,
+// A CertReqMessages carrying more than one message is refused, never reduced to
+// its first: each CertReqMsg is its own TaggedRequest with its own identity,
 // so silently dropping the rest would emit a request the caller did not ask for.
 function _asCertReqMsg(der) {
   var node = asn1.decode(der);
@@ -294,9 +294,9 @@ function _certReqIdOf(msg) {
 }
 
 // A pre-encoded TaggedContentInfo / OtherMsg supplied by the caller. Only its
-// leading bodyPartID is read -- the payload is the caller's and stays untouched --
+// leading bodyPartID is read (the payload is the caller's and stays untouched),
 // so the identifier joins the same allocation space every other element draws
-// from and a collision is refused here rather than discovered by the parser.
+// from and a collision is refused here, never discovered later by the parser.
 function _claimRawElement(el, ids, what) {
   var der = _der(el, what);
   var node = asn1.decode(der);
@@ -309,9 +309,9 @@ function _claimRawElement(el, ids, what) {
   return der;
 }
 
-// The binding controls have a named spec field AND can be hand-encoded into
+// The binding controls have a named spec field and can also be hand-encoded into
 // spec.controls. Emitting both would put two of the same control in one message,
-// and duplicates of these three are what decide what the response must echo -- two
+// and duplicates of these three are what decide what the response must echo: two
 // values means no value. Also refuses two hand-encoded copies, since the same
 // ambiguity arrives that way.
 var BINDING_BY_OID = {};
@@ -319,9 +319,9 @@ BINDING_BY_OID[O("id-cmc-transactionId")] = "transactionId";
 BINDING_BY_OID[O("id-cmc-senderNonce")] = "senderNonce";
 BINDING_BY_OID[O("id-cmc-dataReturn")] = "dataReturn";
 
-// ... and the type each one carries. The CMC parser keeps every control value RAW,
+// ... and the type each one carries. The CMC parser keeps every control value raw,
 // so nothing downstream of the builder objects to a Transaction Identifier encoded
-// as an OCTET STRING -- but these three are read, not carried: pki.cmc.verify
+// as an OCTET STRING. But these three are read, not carried: pki.cmc.verify
 // compares them against the response, and pki.est.fullcmc reads them back out of
 // the request before it goes out. A hand-encoded value of the wrong type therefore
 // signs a request that this toolkit's own client will refuse to send. The type is
@@ -365,8 +365,7 @@ function _assertNoDuplicateBinding(callerControls, spec) {
 function _asBigInt(v, what) { return guard.range.authoredInteger(v, E, "cmc/bad-input", what); }
 
 function _der(v, what) {
-  if (Buffer.isBuffer(v)) return v;
-  if (v instanceof Uint8Array) return Buffer.from(v);
+  if (Buffer.isBuffer(v) || v instanceof Uint8Array) return guard.bytes.snapshot(v, CmcError, "cmc/bad-input", what);
   throw E("cmc/bad-input", what + " must be DER bytes");
 }
 function _oidOf(v) {
@@ -378,9 +377,9 @@ function _oidOf(v) {
 
 // TaggedAttribute ::= SEQUENCE { bodyPartID, attrType, attrValues SET OF ANY }.
 // Controls this builder will not put in a Full PKI Request. A row per control with
-// the reason it does not belong in this direction -- id-cmc-responseBody by an
+// the reason it does not belong in this direction: id-cmc-responseBody by an
 // explicit RFC 6402 sec. 2.6 MUST NOT, the two status controls because RFC 5272
-// sec. 6.1 makes them what a SERVER emits and a client processes in a PKI Response:
+// sec. 6.1 makes them what a server emits and a client processes in a PKI Response.
 // a request has no verdict of its own to report, so one written here is a fabricated
 // answer to a question nobody asked.
 //
@@ -409,6 +408,11 @@ function encodeControl(attrType, values, ids) {
 // ---- the witnesses ---------------------------------------------------
 
 function _assertSecret(secret, what) {
+  // An entry-tier argument check: this tests the TYPE and whether the string is empty, and
+  // compares no secret-dependent content. The length of a caller's own argument is already
+  // known to that caller, so there is no secret for a timing-safe compare to protect. The
+  // MAC comparisons this rule exists for route through guard.crypto.constantTimeEqual.
+  // nosemgrep: pki-non-constant-time-secret-compare
   if (typeof secret !== "string" || secret.length === 0) {
     throw E("cmc/bad-input",
       what + " requires the shared secret as a non-empty string; got " +
@@ -418,10 +422,10 @@ function _assertSecret(secret, what) {
 
 // IdentifyProofV2 ::= SEQUENCE { hashAlgID, macAlgID, witness OCTET STRING }.
 // key = hash(shared-secret as a UTF8 string); witness = MAC(reqSequenceBytes, key).
-// `reqSequenceBytes` is the buffer that will BE the message's reqSequence -- not
+// `reqSequenceBytes` is the buffer that becomes the message's reqSequence, never
 // a re-encode of it (RFC 5272 sec. 6.2.1 step 1).
 // Tracks a buffer this module allocated that carries secret material, so the caller clears it
-// on every exit. The shared secret ARRIVES as a JS string, which is immutable and cannot be
+// on every exit. The shared secret arrives as a JS string, which is immutable and cannot be
 // cleared; what this closes is every copy the toolkit itself makes of it.
 function _ownSecret(buf, owned) {
   owned.push(buf);
@@ -431,17 +435,17 @@ function _ownSecret(buf, owned) {
 function identityProofV2(secret, reqSequenceBytes, identity) {
   _assertSecret(secret, "an Identity Proof V2 control");
   // RFC 5272 sec. 6.2.3: the Identification control is OPTIONAL ("servers MAY
-  // require" it), but when it IS present the key derivation is ALTERED -- "the
+  // require" it), but when it is present the key derivation changes: "the
   // hash of the concatenation of the shared-secret and the UTF8 identity value
   // (without the type and length bytes) are hashed rather than just the
   // shared-secret". Same controls on the wire, different key: a producer that
   // emits the Identification control while hashing the secret alone computes a
   // witness every conforming server rejects.
-  // EVERY allocation that carries the shared secret is cleared, not only the derived key.
+  // Every allocation that carries the shared secret is cleared, not only the derived key.
   // The derivation input holds the secret in the clear, and with an identity present the
-  // concatenation leaves two more copies of it behind -- the operand and the joined buffer.
+  // concatenation leaves two more copies of it behind: the operand and the joined buffer.
   // Wiping the key while those survive clears the cheapest copy and keeps the rest. The
-  // derivation runs INSIDE the try so a throw partway still reaches the clear.
+  // derivation runs inside the try so a throw partway still reaches the clear.
   var owned = [];
   var key = null;
   try {
@@ -481,17 +485,13 @@ function popLinkWitnessV2(secret, R) {
 // The operator-facing @primitive block for this function lives beside its
 // re-export in cmc-verify.js, the pki.cmc @module home.
 function build(spec, signer, opts) {
-  // Assembled SYNCHRONOUSLY. _build reads the spec, every request buffer and the
-  // signer as it goes, so deferring that work would read them a turn after the
-  // call -- and a caller reusing a pooled CSR buffer, or reaching back into the
-  // spec on the next line, would have the message signed over something other
-  // than what was handed in. Only the signing itself is async, and by then the
-  // bytes are fixed.
-  try {
-    return _build(spec, signer, opts);
-  } catch (e) {
-    return Promise.reject(e);   // the surface stays promise-rejecting, never throwing
-  }
+  // Every caller-owned argument copied at entry and released when the call settles; see the note
+  // on the same call in x509-sign. It matters most here: the Identity Proof and POP Link witnesses
+  // are computed over the bytes this builder is about to emit, so a spec that changed in between
+  // would witness a different request than the one that goes out.
+  return guard.bytes.fixedCall(CmcError, "cmc/bad-input", [
+    [spec, "the CMC request spec"], [signer, "the signer"], [opts, "pki.cmc.build options"],
+  ], _build);
 }
 
 function _build(spec, signer, opts) {
@@ -500,9 +500,9 @@ function _build(spec, signer, opts) {
     throw E("cmc/bad-input", "the CMC request spec must be an object");
   }
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("cmc/bad-input", "pki.cmc.build options must be an object");
-  // A misspelled or unsupported spec field fails OPEN in the quietest way there is:
+  // A misspelled or unsupported spec field fails open in the quietest way there is:
   // the message builds, is signed, and simply does not carry what was asked for.
-  // That is worst for the exchange-binding fields below -- a request built without
+  // That is worst for the exchange-binding fields below: a request built without
   // them has no replay defence, and pki.cmc.verify cannot enforce a binding the
   // client never sent, so the omission is invisible from both ends.
   guard.identifier.assertKnownKeys(spec, KNOWN_SPEC_KEYS, E, "cmc/bad-input", "unknown spec field ");
@@ -513,16 +513,16 @@ function _build(spec, signer, opts) {
 
   var ids = makeIdAllocator();
 
-  // EVERY identifier the CALLER determines is reserved before a single generated
+  // Every identifier the caller determines is reserved before a single generated
   // one is handed out. There are four sources, and reserving only some of them
-  // makes acceptance depend on the order the caller wrote things in rather than
-  // on the message:
+  // makes acceptance depend on the order the caller wrote things in, not on
+  // the message:
   //   1. a request's explicit bodyPartID
   //   2. a crm arm's certReqId, which is fixed by the CertReqMsg itself
   //   3. a cmsSequence element's bodyPartID
   //   4. an otherMsgSequence element's bodyPartID
   // Auto-allocation walks upward from 1, so anything minted before these were
-  // claimed could take a value the caller already spent -- and the caller's own
+  // claimed could take a value the caller already spent, and the caller's own
   // element would then be rejected as a duplicate of whatever displaced it.
   requests.forEach(function (r, i) {
     var fixed = fixedRequestId(r, i);
@@ -559,7 +559,7 @@ function _build(spec, signer, opts) {
     // A renewal is authenticated by the certificate being renewed: sec. 6.3.3 says
     // "the outermost signature layer is created using the current signing
     // certificate, which allows the original identity to be associated with the
-    // certification request". That identity is the whole mechanism -- it is what
+    // certification request". That identity is the whole mechanism: it is what
     // replaces the Identity Proof this mode just refused. A key-only signer has no
     // certificate and so carries no prior identity, leaving a message with nothing
     // for the CA to authenticate the renewal against.
@@ -588,13 +588,13 @@ function _build(spec, signer, opts) {
 
   // The exchange binding (RFC 5272 sec. 6.6 Transaction Identifier / Sender Nonce,
   // sec. 6.4 Data Return). These are what pki.cmc.verify checks the response
-  // against, and a request that omits them has no replay defence -- so they are
-  // named fields here rather than something the caller hand-encodes into
+  // against, and a request that omits them has no replay defence, so they are
+  // named fields here and not something the caller hand-encodes into
   // spec.controls and can silently get wrong.
   // A named field and a hand-encoded control of the same type would emit the
-  // control TWICE, and a message carrying two of them has no single value the
-  // response can be bound to -- this toolkit's own /fullcmc refuses exactly that.
-  // Refuse it at the source rather than sign something no one can bind to.
+  // control twice, and a message carrying two of them has no single value the
+  // response can be bound to; this toolkit's own /fullcmc refuses exactly that.
+  // Refuse it at the source, before signing something no one can bind to.
   _assertNoDuplicateBinding(callerControls, spec);
   if (spec.transactionId != null) {
     controls.push(encodeControl(OID_TRANSACTION_ID,
@@ -617,7 +617,7 @@ function _build(spec, signer, opts) {
       throw E("cmc/bad-input", "identityProof.identity is the UTF8String the Identification control carries");
     }
     // The pair is emitted together when an identity is given, because the two are
-    // coupled: the Identification control tells the server WHICH shared secret to
+    // coupled: the Identification control tells the server which shared secret to
     // look up, and its presence is what changes how the key is derived. Letting a
     // caller supply one without the other would put that coupling out of reach.
     if (identity != null) controls.push(encodeControl(OID_IDENTIFICATION, [b.utf8(identity)], ids));
@@ -642,8 +642,8 @@ function _build(spec, signer, opts) {
   }
 
   // PKIData ::= SEQUENCE { controlSequence, reqSequence, cmsSequence,
-  // otherMsgSequence } -- all four emitted, the unused ones empty (sec. 3.2.1).
-  // reqSequenceBytes is spliced in as the SAME buffer the witness was computed
+  // otherMsgSequence }: all four emitted, the unused ones empty (sec. 3.2.1).
+  // reqSequenceBytes is spliced in as the same buffer the witness was computed
   // over, which is the whole of IP1.
   var pkiData = b.sequence([
     b.sequence(controls),
@@ -653,13 +653,13 @@ function _build(spec, signer, opts) {
   ]);
 
   // Read the assembled message back through the shipped parser before signing it.
-  // Every arm here splices CALLER-supplied DER -- a tcr's CertificationRequest, a
-  // cmsSequence TaggedContentInfo, an otherMsg's value -- and checking each shape
+  // Every arm here splices caller-supplied DER (a tcr's CertificationRequest, a
+  // cmsSequence TaggedContentInfo, an otherMsg's value), and checking each shape
   // by hand would restate the parser's rules in a second place, where they would
   // drift and where a newly added arm would silently miss them. One round-trip
   // covers them all, including arms not yet written: whatever the parser refuses,
-  // this refuses at build time rather than emitting a message whose recipient --
-  // this toolkit's own decoder included -- cannot read it.
+  // this refuses at build time, so no message goes out whose recipient (this
+  // toolkit's own decoder included) cannot read it.
   try {
     cmcFmt.parsePkiData(pkiData);
   } catch (e) {
@@ -673,13 +673,13 @@ function _build(spec, signer, opts) {
   // The signer is copied for the same reason the message was assembled at the
   // call: cms.sign reads `key` inside its own promise chain, so a caller who
   // swaps signer.key on the next line would have the request signed by the
-  // replacement while the original certificate stays embedded -- a message whose
+  // replacement while the original certificate stays embedded: a message whose
   // signature does not belong to the certificate beside it.
   //
   // cms.sign resolves eContentType through oid.byName, so it takes the registry
-  // NAME; handing it the dotted value resolves to undefined.
-  // Copying a private key makes a SECOND copy of a secret, so it is cleared once signing has
-  // settled rather than left for the collector -- the same discipline the MAC keys above follow.
+  // name; handing it the dotted value resolves to undefined.
+  // Copying a private key makes a second copy of a secret, so it is cleared once signing has
+  // settled and never left for the collector, the same discipline the MAC keys above follow.
   // The clear covers the rejecting path too: a wrong or malformed key is the case a caller can
   // reach, and a success-only wipe would keep the secret exactly when it matters.
   var ownedKeyBytes = [];
@@ -699,12 +699,12 @@ function _build(spec, signer, opts) {
 // Each signer descriptor, and every byte value in it. cms.sign reads these inside
 // its own promise chain, so both levels matter: re-pointing signer.key is one way
 // to change who signs, and rewriting the PKCS#8 buffer it already points at is
-// the other. A CryptoKey handle is passed through as-is -- it is an opaque
+// the other. A CryptoKey handle is passed through as-is: it is an opaque
 // reference the caller is meant to share, and there is nothing to copy.
-// `owned` collects the buffers THIS function allocated that hold PRIVATE KEY material, so the
+// `owned` collects the buffers this function allocated that hold private key material, so the
 // caller can clear them once signing has settled. Only the key is listed: the other copied
 // values are certificates and identifiers, which are public and outlive the call by design.
-// The caller's own key is never written to -- only our copy of it.
+// The caller's own key is never written to; only our copy of it is.
 function _copySigners(signer, owned) {
   function one(s) {
     if (!s || typeof s !== "object") return s;
@@ -715,9 +715,9 @@ function _copySigners(signer, owned) {
     }
     return out;
   }
-  // One level further for a COMPOSITE key, which is an object of component keys
-  // ({ mldsa, trad }) rather than a buffer. Copying only the top level would leave
-  // those components -- the actual PKCS#8 bytes that sign -- the caller's to
+  // One level further for a composite key, which is an object of component keys
+  // ({ mldsa, trad }) and not a buffer. Copying only the top level would leave
+  // those components, the actual PKCS#8 bytes that sign, the caller's to
   // replace or zeroize while cms.sign reads them in a later turn. A CryptoKey is
   // an opaque handle and is passed through as-is.
   function copyValue(v, isSecret) {
@@ -742,7 +742,7 @@ function _copySigners(signer, owned) {
 
 /**
  * RFC 5272 sec. 3.2, the three rules that apply when the signature is made with
- * the private key of a certification request the message carries rather than with
+ * the private key of a certification request the message carries, and not with
  * an already-certified key:
  *
  *   a. that request MUST include a Subject Key Identifier extension;
@@ -753,15 +753,15 @@ function _copySigners(signer, owned) {
  * signer. (a) and (c) are about agreement between the signer and the requests
  * beside it, which is checked here: an identifier the requests never declare
  * leaves the CA unable to tie the signature to the key being enrolled, so the
- * request is signed but unusable -- and it is the producer's job to catch that,
+ * request is signed but unusable, and it is the producer's job to catch that,
  * not the CA's to guess.
  *
- * This lives HERE rather than in pki.cms.sign because it is a CMC rule: only this
+ * This lives here, not in pki.cms.sign, because it is a CMC rule: only this
  * layer knows the content is a PKIData and which requests are in it. Teaching the
  * generic CMS signer to parse CMC content would put the protocol's rules in the
  * wrong module.
  *
- * A signer WITH a certificate is untouched -- it identifies itself by that
+ * A signer that carries a certificate is untouched: it identifies itself by that
  * certificate, and the clause does not reach it.
  */
 function _assertKeyOnlySigner(signer, requests) {
@@ -780,7 +780,7 @@ function _assertKeyOnlySigner(signer, requests) {
   keyOnly.forEach(function (so) { _assertKeyOnlySignerBinding(so, requests); });
 }
 
-// The sec. 3.2a/3.2c binding for ONE key-only signer.
+// The sec. 3.2a/3.2c binding for a single key-only signer.
 function _assertKeyOnlySignerBinding(so, requests) {
   var id = so.keyIdentifier;
   var idBytes = (Buffer.isBuffer(id) || id instanceof Uint8Array) ? Buffer.from(id) : null;
@@ -795,7 +795,7 @@ function _assertKeyOnlySignerBinding(so, requests) {
   var declaredSki = false, sawRequest = false;
   for (var i = 0; i < requests.length; i++) {
     var req = requests[i];
-    // BOTH key-bearing arms: sec. 3.2 says the signing key may belong to a request
+    // Both key-bearing arms: sec. 3.2 says the signing key may belong to a request
     // "included in the TaggedRequest tcr or crm fields", so reading only PKCS#10
     // would reject every conforming CRMF enrolment of a brand-new key.
     var declaredBy;
@@ -806,11 +806,11 @@ function _assertKeyOnlySignerBinding(so, requests) {
     if (req && (req.tcr != null || req.crm != null)) sawRequest = true;
     if (!declaredBy || !declaredBy.ski) continue;
     declaredSki = true;
-    // The identifier AND the key. Matching the identifier alone would accept a
-    // signer holding key A while the request it points at asks to certify key B --
+    // The identifier and the key together. Matching the identifier alone would accept a
+    // signer holding key A while the request it points at asks to certify key B:
     // the SKI is caller-chosen, so the two can be made to agree while the keys do
     // not, and a CA resolving the SID to the requested key could then not verify
-    // the carrier at all. The identifier says WHICH request; the key is what makes
+    // the carrier at all. The identifier says which request; the key is what makes
     // the claim true. The comparison runs through the toolkit's shared byte
     // equality; neither value here is secret, but there is one way to compare.
     if (guard.crypto.constantTimeEqual(declaredBy.ski, idBytes) &&
@@ -833,14 +833,14 @@ function _assertKeyOnlySignerBinding(so, requests) {
     "to be the one asking for this very public key (RFC 5272 sec. 3.2)");
 }
 
-// { ski, spki } for a CRMF certification request -- the identifier it declares and
+// { ski, spki } for a CRMF certification request: the identifier it declares and
 // the key it asks to have certified. The CertTemplate carries extensions directly,
 // so there is no attribute wrapper to unwrap; the extnValue is the same DER
 // SubjectKeyIdentifier OCTET STRING.
 function _crmKeyIdentity(crmDer) {
   var msg = _asCertReqMsg(_der(crmDer, "a crm CertReqMsg"));
   // pki.schema.crmf reads CertReqMessages (SEQUENCE OF CertReqMsg); one message is
-  // wrapped rather than decoded here, so the CRMF rules stay in the CRMF parser.
+  // wrapped here and decoded there, so the CRMF rules stay in the CRMF parser.
   var msgs = crmf.parse(b.sequence([msg])).messages;
   var tmpl = msgs && msgs[0] && msgs[0].certReq && msgs[0].certReq.certTemplate;
   var found = null;
@@ -849,7 +849,7 @@ function _crmKeyIdentity(crmDer) {
     found = asn1.read.octetString(asn1.decode(e.value));
   });
   // RFC 4211 sec. 4.1: the requested key may live in the signature POP's
-  // POPOSigningKeyInput rather than the CertTemplate, and the CRMF parser surfaces
+  // POPOSigningKeyInput instead of the CertTemplate, and the CRMF parser surfaces
   // it there. Reading only the template would refuse a key-only signer whose
   // request is perfectly conforming.
   var msg0 = msgs && msgs[0];