@blamejs/pki 0.6.14 → 0.6.15

package/lib/cmc-build.js

@@ -1,44 +1,22 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- the pki.cmc.build implementation. So the pki.cmc namespace has one @module home,
+// @internal
 // the operator-facing @module pki.cmc + the @primitive pki.cmc.build documentation block live in
-// cmc-verify.js, which re-exports this build function.
-//
-/**
- * RFC 5272 Full PKI Request production -- the producing half of `pki.cmc`.
- *
- * `build(spec, signer, opts)` assembles a PKIData (all four sequences, each
- * possibly empty), allocates a unique body part identifier for every element,
- * attaches controls through an OID-keyed encoder registry that enforces the RFC
- * 6402 placement rules, computes the Identity Proof / POP Link witnesses over the
- * bytes it is about to EMIT, and signs the result through `pki.cms.sign` with
- * `eContentType: id-cct-PKIData`.
- *
- * 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
- * serialization would agree with itself while disagreeing with the wire the
- * moment any encoding detail differed.
- */
+
 
 var nodeCrypto = require("node:crypto");
 var asn1 = require("./asn1-der");
-var pkiBuild = require("./pki-build");   // reqDenseArray: reject a sparse/nullish caller array as a typed cmc/bad-input
-var csr = require("./schema-csr");    // to read the Subject Key Identifier a tcr request declares
-require("./path-validate");   // side-effect: path-validate injects its signature engine into csr-verify at load
-var csrVerify = require("./csr-verify");   // verify an embedded tcr request's proof-of-possession before signing it
-var crmf = require("./schema-crmf");  // ... and the one a crm request declares
-var cmcFmt = require("./schema-cmc");  // to read the assembled message back before signing it
+var pkiBuild = require("./pki-build");
+var csr = require("./schema-csr");
+require("./path-validate");
+var csrVerify = require("./csr-verify");
+var crmf = require("./schema-crmf");
+var cmcFmt = require("./schema-cmc");
 var oid = require("./oid");
 var cmsSign = require("./cms-sign");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides which controls a request carries.
 var _hasOwn = intrinsic.hasOwn;
 var frameworkError = require("./framework-error");
 
@@ -53,44 +31,18 @@ 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."
-//
-// "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 = {};
 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
-// 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
-// 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.
-// PL1: R "SHOULD be at least 512 bits in length".
 var POP_LINK_RANDOM_BYTES = 64;
 
-// The spec fields pki.cmc.build understands. Anything else is a caller mistake
-// caught at the entry point, never silently dropped from the message.
 var KNOWN_SPEC_KEYS = {
   requests: 1, controls: 1, cmsSequence: 1, otherMsgSequence: 1,
-  // `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
-  // 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
-  // pki.cmc.verify names these same three when checking the response: a builder
-  // that made the caller hand-encode them while the verifier took them by name is
-  // the asymmetry that lets a request ship with no replay defense.
   transactionId: 1, senderNonce: 1, dataReturn: 1,
 };
 
@@ -98,22 +50,11 @@ 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
-// 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
-// reserved for the reference to the current PKIData. The allocator therefore
-// 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
-  // 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);
   var next = 1;
   function assertValid(requested, what) {
@@ -143,7 +84,7 @@ function makeIdAllocator() {
         return next;
       }
       assertValid(requested, what);
-      if (pending[requested]) { delete pending[requested]; return requested; }   // consume our own reservation
+      if (pending[requested]) { delete pending[requested]; return requested; }
       if (used[requested]) {
         throw E("cmc/bad-input",
           "bodyPartID " + requested + " is used more than once; identifiers MUST be unique within a single PKIData (RFC 5272 sec. 3.2.2)");
@@ -154,28 +95,8 @@ function makeIdAllocator() {
   };
 }
 
-// ---- requests --------------------------------------------------------
-
-// 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 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
-// 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
-// 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`
-// is not a harmless extra: the request would be auto-allocated a DIFFERENT
-// identifier while a control the caller wrote still references the intended one,
-// and the builder would sign a message whose halves point at different requests.
+
 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
-// 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
-// conforming server can reproduce.
 var KNOWN_CONTROL_KEYS = { type: 1, value: 1 };
 var KNOWN_IDENTITY_PROOF_KEYS = { identity: 1, secret: 1 };
 var KNOWN_POP_LINK_KEYS = { secret: 1 };
@@ -192,12 +113,6 @@ 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
-  // 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,
-  // 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)) {
@@ -210,23 +125,12 @@ function fixedRequestId(req, index) {
   return req.bodyPartID == null ? null : req.bodyPartID;
 }
 
-// Verify each embedded PKCS#10 (tcr) request's proof-of-possession before the message is signed. A CSR
-// whose self-signature does not verify under its own subjectPKInfo is one the CA will reject (RFC 5272
-// sec. 4.1), so refusing it here -- through the shared inbound-PoP seam pki.csr.verify uses -- keeps the
-// producer from signing a request that cannot be acted on, the same "do not sign what the recipient
-// refuses" discipline the assembled-message readback already applies. The crm / orm arms carry their own
-// POP structures (CRMF POPOSigningKey etc.), validated by their own parse; only tcr is a bare CSR.
-// `await`, not `.then`: the PoP verdict is read through the native promise job, not the replaceable
-// Promise.prototype.then a co-resident could swap to force `ok` true and slip an unverified request past.
 async function _assertTcrPops(requests) {
   for (var i = 0; i < requests.length; i++) {
     if (requests[i] && requests[i].tcr != null) await _assertOneTcrPop(requests[i].tcr, i);
   }
 }
 async function _assertOneTcrPop(tcr, i) {
-  // encodeRequest already validated this tcr's structure synchronously (it runs before this async pass),
-  // so the re-parse here only recovers the parse the PoP check verifies over; on the shipped path it
-  // cannot fail, and a sync throw surfaces as a rejection through build's async boundary regardless.
   var parsed = csr.parse(_der(tcr, "a tcr certificationRequest"));
   if (!(await csrVerify.verifyCsrSignature(parsed))) {
     throw E("cmc/bad-popo", "a tcr request [" + i + "] failed its proof-of-possession: the PKCS#10 signature does not verify under the request's own subject public key (RFC 5272 sec. 6.3), so a CA would reject it -- refusing it here rather than signing it");
@@ -235,11 +139,6 @@ async function _assertOneTcrPop(tcr, i) {
 
 function encodeRequest(req, ids, index) {
   if (req.tcr != null) {
-    // 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 enrollment
-    // no CA can act on, and the producer is where that is cheap to catch.
     try { csr.parse(_der(req.tcr, "a tcr certificationRequest")); }
     catch (e) {
       throw E("cmc/bad-input", "a tcr request must be a PKCS#10 CertificationRequest: " +
@@ -250,23 +149,12 @@ function encodeRequest(req, ids, index) {
   }
   if (req.crm != null) {
     var msg = _asCertReqMsg(_der(req.crm, "a crm CertReqMsg"));
-    // Parsed as the CertReqMsg it is, the same way a tcr is parsed as a
-    // CertificationRequest: the readback checks the CMC structure around the
-    // request, and would pass a SEQUENCE that merely starts like one.
     try { crmf.parse(b.sequence([msg])); }
     catch (e) {
       throw E("cmc/bad-input", "a crm request must be an RFC 4211 CertReqMsg: " +
         (e && e.message ? e.message : "it did not parse as one"), e);
     }
-    // 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
-    // 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, 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)) };
@@ -283,18 +171,6 @@ 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
-// 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)
-//   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, 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);
   var first = node.children && node.children[0];
@@ -302,7 +178,7 @@ function _asCertReqMsg(der) {
     throw E("cmc/bad-input", "a crm arm must be a CertReqMsg or a CertReqMessages carrying one");
   }
   var grand = first.children[0];
-  if (grand.tagClass === "universal" && grand.tagNumber === asn1.TAGS.INTEGER) return der;   // already a CertReqMsg
+  if (grand.tagClass === "universal" && grand.tagNumber === asn1.TAGS.INTEGER) return der;
   if (node.children.length !== 1) {
     throw E("cmc/bad-input",
       "a crm arm carries exactly one CertReqMsg; this CertReqMessages holds " + node.children.length +
@@ -311,8 +187,6 @@ function _asCertReqMsg(der) {
   return first.bytes;
 }
 
-// A CertReqMsg's identity: CertReqMsg ::= SEQUENCE { certReq CertRequest, ... },
-// CertRequest ::= SEQUENCE { certReqId INTEGER, ... }.
 function _certReqIdOf(msg) {
   var node = asn1.decode(msg);
   var certReq = node.children && node.children[0];
@@ -323,10 +197,6 @@ function _certReqIdOf(msg) {
   return guard.range.int(v, 0n, 4294967295n, E, "cmc/bad-input", "a crm certReqId");
 }
 
-// A pre-encoded TaggedContentInfo / OtherMsg supplied by the caller. Only its
-// 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, never discovered later by the parser.
 function _claimRawElement(el, ids, what) {
   var der = _der(el, what);
   var node = asn1.decode(der);
@@ -339,24 +209,11 @@ function _claimRawElement(el, ids, what) {
   return der;
 }
 
-// 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
-// values means no value. Also refuses two hand-encoded copies, since the same
-// ambiguity arrives that way.
 var BINDING_BY_OID = {};
 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,
-// 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
-// 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
-// checked by READING the value, so a wrong tag and a malformed encoding of the
-// right one are refused alike.
 var BINDING_READER = {
   transactionId: function (node) { return asn1.read.integer(node); },
   senderNonce: function (node) { return asn1.read.octetString(node); },
@@ -390,8 +247,6 @@ function _assertNoDuplicateBinding(callerControls, spec) {
   });
 }
 
-// A Transaction Identifier is an unbounded INTEGER on the wire; the shared authoring
-// guard normalizes the number-or-bigint a caller naturally has.
 function _asBigInt(v, what) { return guard.range.authoredInteger(v, E, "cmc/bad-input", what); }
 
 function _der(v, what) {
@@ -403,20 +258,7 @@ function _oidOf(v) {
   return oid.isDottedDecimal(v) ? v : O(v);
 }
 
-// ---- controls --------------------------------------------------------
-
-// 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
-// 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.
-// a request has no verdict of its own to report, so one written here is a fabricated
-// answer to a question nobody asked.
-//
-// Only the BUILDER refuses these. pki.schema.cmc keeps decoding them wherever they
-// appear, because the spec states a placement MUST for id-cmc-responseBody alone --
-// refusing the rest on the wire would reject a message the ASN.1 permits, and this
-// decoder's job is to surface what arrived, not to judge who should have sent it.
+
 var REQUEST_FORBIDDEN_CONTROL = {};
 REQUEST_FORBIDDEN_CONTROL[OID_RESPONSE_BODY] =
   "id-cmc-responseBody may appear only in the control sequence of a PKIResponse (RFC 6402 sec. 2.6)";
@@ -435,14 +277,8 @@ function encodeControl(attrType, values, ids) {
   return b.sequence([b.integer(BigInt(id)), b.oid(attrType), b.set(values)]);
 }
 
-// ---- 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 " +
@@ -450,13 +286,6 @@ 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 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
-// cleared; what this closes is every copy the toolkit itself makes of it.
 function _ownSecret(buf, owned) {
   owned.push(buf);
   return buf;
@@ -464,18 +293,6 @@ 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 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.
-  // 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.
-  // 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.
   var owned = [];
   var key = null;
   try {
@@ -497,10 +314,6 @@ function identityProofV2(secret, reqSequenceBytes, identity) {
   }
 }
 
-// PopLinkWitnessV2 ::= SEQUENCE { keyGenAlgorithm, macAlgorithm, witness }.
-// key = keyGen(shared-secret); witness = MAC(R, key), with R carried alongside in
-// the POP Link Random control -- PL1 makes that control mandatory in the same
-// request, which is why the two are produced together and never separately.
 function popLinkWitnessV2(secret, R) {
   _assertSecret(secret, "a POP Link Witness V2 control");
   var key = nodeCrypto.createHash("sha256").update(secret, "utf8").digest();
@@ -515,10 +328,6 @@ 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) {
-  // 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);
@@ -530,14 +339,7 @@ async 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:
-  // 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
-  // them has no replay defense, 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 ");
-  // Density up front: requests is iterated by both the forEach below and the map that encodes it, and a
-  // hole would survive either (map/forEach skip it) to reach b.sequence as a native error.
   var requests = spec.requests != null ? pkiBuild.reqDenseArray(spec.requests, "requests", E, "cmc/bad-input") : [];
   if (!Array.isArray(requests)) throw E("cmc/bad-input", "spec.requests must be an array");
   var callerControls = spec.controls || [];
@@ -545,17 +347,6 @@ async function _build(spec, signer, opts) {
 
   var ids = makeIdAllocator();
 
-  // 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, 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
-  // element would then be rejected as a duplicate of whatever displaced it.
   requests.forEach(function (r, i) {
     var fixed = fixedRequestId(r, i);
     if (fixed != null) ids.reserve(fixed, "request " + i);
@@ -567,15 +358,9 @@ async function _build(spec, signer, opts) {
     return _claimRawElement(el, ids, "an otherMsgSequence element (index " + i + ")");
   });
 
-  // Now the requests: a fixed identifier is re-claimed as a no-op against the
-  // reservation above, and only the ones that omitted it are allocated. The
-  // reqSequence bytes this produces are what the Identity Proof witness covers.
   var encodedRequests = requests.map(function (r, i) { return encodeRequest(r, ids, i); });
   var reqSequenceBytes = b.sequence(encodedRequests.map(function (r) { return r.der; }));
 
-  // A renewal carries neither identity control. Refusing the combination is the
-  // point: dropping the control silently would emit a message that looks like a
-  // renewal to us and an identity-proofed request to nobody.
   if (spec.renewal) {
     if (spec.identityProof) {
       throw E("cmc/bad-input",
@@ -588,13 +373,6 @@ async function _build(spec, signer, opts) {
           "a renewal request carries no " + forbidden + " control (RFC 5272 sec. 3.2 (a))");
       }
     }
-    // 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
-    // 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.
     var renewalSigners = Array.isArray(signer) ? signer : [signer];
     for (var si = 0; si < renewalSigners.length; si++) {
       var rs = renewalSigners[si];
@@ -618,15 +396,6 @@ async function _build(spec, signer, opts) {
     controls.push(encodeControl(_oidOf(c.type), [_der(c.value, "a control value")], ids));
   });
 
-  // 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 defense, 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, before signing something no one can bind to.
   _assertNoDuplicateBinding(callerControls, spec);
   if (spec.transactionId != null) {
     controls.push(encodeControl(OID_TRANSACTION_ID,
@@ -648,10 +417,6 @@ async function _build(spec, signer, opts) {
     if (identity != null && typeof identity !== "string") {
       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
-    // 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));
     controls.push(encodeControl(OID_IDENTITY_PROOF_V2,
       [identityProofV2(spec.identityProof.secret, reqSequenceBytes, identity)], ids));
@@ -665,18 +430,11 @@ async function _build(spec, signer, opts) {
       throw E("cmc/bad-input", "popLinkRandomBytes must be a positive integer");
     }
     var R = nodeCrypto.randomBytes(rBytes);
-    // Both are emitted together: PL1 makes the Random control mandatory whenever
-    // the witness is present, so producing one without the other is not an option
-    // the API offers.
     controls.push(encodeControl(OID_POP_LINK_RANDOM, [b.octetString(R)], ids));
     controls.push(encodeControl(O("id-cmc-popLinkWitnessV2"),
       [popLinkWitnessV2(spec.popLink.secret, R)], ids));
   }
 
-  // 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
-  // over, which is the whole of IP1.
   var pkiData = b.sequence([
     b.sequence(controls),
     b.raw(reqSequenceBytes),
@@ -684,14 +442,6 @@ async function _build(spec, signer, opts) {
     b.sequence(otherMsgSequence),
   ]);
 
-  // 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
-  // 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, so no message goes out whose recipient (this
-  // toolkit's own decoder included) cannot read it.
   try {
     cmcFmt.parsePkiData(pkiData);
   } catch (e) {
@@ -702,28 +452,12 @@ async function _build(spec, signer, opts) {
 
   _assertKeyOnlySigner(signer, requests);
 
-  // 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
-  // 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 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 = [];
   var copiedSigner = _copySigners(signer, ownedKeyBytes);
   function _wipeOwnedKeys() {
     if (ownedKeyBytes.length) guard.secret.zeroizeAll(ownedKeyBytes, CmcError, "cmc/bad-input", "the signer key copy");
     ownedKeyBytes.length = 0;
   }
-  // Verify every embedded tcr proof-of-possession BEFORE signing: do not sign a request the CA will
-  // reject. `await`, not a `.then` chain, so the PoP gate and the sign are sequenced through native
-  // promise jobs a co-resident cannot swap; the finally clears the signer key copy on every path,
-  // the rejecting one included.
   try {
     await _assertTcrPops(requests);
     return await cmsSign.sign(pkiData, copiedSigner, { eContentType: "id-cct-PKIData", pem: opts.pem });
@@ -732,15 +466,6 @@ async 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
-// 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
-// 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 is.
 function _copySigners(signer, owned) {
   function one(s) {
     if (!s || typeof s !== "object") return s;
@@ -751,25 +476,13 @@ function _copySigners(signer, owned) {
     }
     return out;
   }
-  // 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) {
     if (!isSecret) {
-      // A public signer field (cert / spki / keyIdentifier DER): any BufferSource is
-      // snapshotted to a private Buffer so a caller cannot mutate it in a later turn;
-      // an ArrayBuffer or DataView is accepted, not silently turned into an empty object.
-      // A non-byte descriptor or scalar (a parsed certificate, a CryptoKey handle) passes
-      // through untouched.
       if (guard.bytes.isByteSource(v)) return guard.bytes.snapshotSource(v, CmcError, "cmc/bad-input", "a signer field");
       return v;
     }
-    // The private key stays on the ownership contract: a Buffer is copied, a Uint8Array is
-    // copied, and every copy is collected so it can be zeroized once signing settles.
     if (Buffer.isBuffer(v) || v instanceof Uint8Array) return _own(Buffer.from(v), true);   // allow:byte-source-narrow -- private key bytes (Buffer borrowed / Uint8Array copied+wiped)
-    if (!v || typeof v !== "object" || typeof v.type === "string") return v;   // CryptoKey / scalar
+    if (!v || typeof v !== "object" || typeof v.type === "string") return v;
     var c = {}, ck;
     for (ck in v) {
       if (!_hasOwn(v, ck)) continue;
@@ -778,8 +491,6 @@ function _copySigners(signer, owned) {
     }
     return c;
   }
-  // A composite key's components are listed too: each is PKCS#8 bytes that actually sign, so
-  // leaving them out would wipe the wrapper and keep the secrets it was wrapping.
   function _own(buf, isSecret) {
     if (isSecret && owned) owned.push(buf);
     return buf;
@@ -787,38 +498,11 @@ function _copySigners(signer, owned) {
   return Array.isArray(signer) ? signer.map(one) : one(signer);
 }
 
-/**
- * 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, and not with
- * an already-certified key:
- *
- *   a. that request MUST include a Subject Key Identifier extension;
- *   b. the subjectKeyIdentifier form of SignerIdentifier MUST be used;
- *   c. its value MUST be the Subject Key Identifier that request specifies.
- *
- * (b) is structural and pki.cms.sign already emits only that form for a key-only
- * 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,
- * not the CA's to guess.
- *
- * 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 that carries a certificate is untouched: it identifies itself by that
- * certificate, and the clause does not reach it.
- */
+
 function _assertKeyOnlySigner(signer, requests) {
   var all = Array.isArray(signer) ? signer : [signer];
   var keyOnly = all.filter(function (x) { return x && x.cert == null && x.spki != null; });
   if (!keyOnly.length) return;
-  // Sec. 3.2's fourth rule: "If the request key is used for signing, there MUST be
-  // only one SignerInfo in the SignedData." A request key has no certificate and
-  // so no independent identity; letting it sign alongside others would produce a
-  // message whose signer set the CA cannot reason about.
   if (all.length !== 1) {
     throw E("cmc/bad-signer",
       "a Full PKI Request signed with a certification request's own key MUST carry exactly one SignerInfo, " +
@@ -827,7 +511,6 @@ function _assertKeyOnlySigner(signer, requests) {
   keyOnly.forEach(function (so) { _assertKeyOnlySignerBinding(so, requests); });
 }
 
-// The sec. 3.2a/3.2c binding for a single key-only signer.
 function _assertKeyOnlySignerBinding(so, requests) {
   var id = so.keyIdentifier;
   if (!guard.bytes.isByteSource(id)) {
@@ -842,24 +525,14 @@ 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
-    // "included in the TaggedRequest tcr or crm fields", so reading only PKCS#10
-    // would reject every conforming CRMF enrollment of a brand-new key.
     var declaredBy;
     try {
       declaredBy = req && req.tcr != null ? _csrKeyIdentity(req.tcr)
         : (req && req.crm != null ? _crmKeyIdentity(req.crm) : null);
-    } catch (_e) { declaredBy = null; }   // a request this layer cannot read declares nothing
+    } catch (_e) { declaredBy = null; }
     if (req && (req.tcr != null || req.crm != null)) sawRequest = true;
     if (!declaredBy || !declaredBy.ski) continue;
     declaredSki = true;
-    // 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 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) &&
         declaredBy.spki && guard.crypto.constantTimeEqual(declaredBy.spki, signerSpki)) {
       return;
@@ -880,14 +553,8 @@ 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
-// 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 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;
@@ -895,19 +562,12 @@ function _crmKeyIdentity(crmDer) {
     if (e.name !== "subjectKeyIdentifier" || found) return;
     found = asn1.read.octetString(asn1.decode(e.value));
   });
-  // RFC 4211 sec. 4.1: the requested key may live in the signature POP's
-  // 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];
   var pk = (tmpl && tmpl.publicKey) ||
     (msg0 && msg0.popo && msg0.popo.poposkInput && msg0.popo.poposkInput.publicKey);
   return { ski: found, spki: Buffer.isBuffer(pk) ? pk : (pk && pk.bytes) || null };
 }
 
-// { ski, spki } for a PKCS#10 certification request. Read through the shipped CSR
-// parser and the extensionRequest attribute it already decodes, so the extension
-// rules are not restated here.
 function _csrKeyIdentity(csrDer) {
   var parsed = csr.parse(_der(csrDer, "a tcr certificationRequest"));
   var found = null;
@@ -915,8 +575,6 @@ function _csrKeyIdentity(csrDer) {
     if (a.name !== "extensionRequest") return;
     (a.extensions || []).forEach(function (e) {
       if (e.name !== "subjectKeyIdentifier" || found) return;
-      // extnValue holds a DER SubjectKeyIdentifier ::= OCTET STRING; the identifier
-      // is its contents, not the TLV.
       found = asn1.read.octetString(asn1.decode(e.value));
     });
   });