@blamejs/pki 0.5.6 → 0.5.8

package/lib/schema-cmc.js

@@ -16,10 +16,10 @@
  *   the CMS layer, dispatches on that content type, and decodes the message.
  *
  *   Every body part carries a `BodyPartID`, and the identifier MUST be unique
- *   across the WHOLE message rather than within one sequence; 0 is reserved as
+ *   across the whole message, not merely within one sequence; 0 is reserved as
  *   the reference to the enclosing PKIData and is never an element's own
- *   identity. Controls are surfaced as an ordered list with their values RAW: an
- *   unrecognized control is DATA, not a fault, because the rule that a server
+ *   identity. Controls are surfaced as an ordered list with their values raw: an
+ *   unrecognized control is data, not a fault, because the rule that a server
  *   fails an unrecognized control binds the server, not the client reading a
  *   response. The status controls (`CMCStatusInfo` v1 and `CMCStatusInfoV2`) are
  *   collected in wire order -- a response may carry several verdicts, and the
@@ -31,7 +31,7 @@
  *
  * @spec RFC 5272, RFC 5273, RFC 5274, RFC 6402
  * @card
- *   Decode RFC 5272 CMC Full PKI Requests and Responses inside CMS -- controls
+ *   Decode RFC 5272 CMC Full PKI Requests and Responses inside CMS: controls
  *   with raw values, tagged requests (PKCS#10 / CRMF / other), ordered status
  *   verdicts with the RFC 6402 two-module OtherStatusInfo ambiguity resolved,
  *   whole-message body-part identity, raw reqSequence bytes, fail-closed.
@@ -61,20 +61,20 @@ var OID_STATUS_INFO_V2 = O("id-cmc-statusInfoV2");
 var OID_RESPONSE_BODY = O("id-cmc-responseBody");
 var OID_RA_IDENTITY_WITNESS = O("id-cmc-raIdentityWitness");
 
-// BodyPartID ::= INTEGER (0..4294967295) -- RFC 5272 sec. 3.2.2.
+// BodyPartID ::= INTEGER (0..4294967295), RFC 5272 sec. 3.2.2.
 var BODY_PART_MAX = 4294967295n;
 
 // CMCStatus ::= INTEGER { success(0), failed(2), pending(3), noSupport(4),
-// confirmRequired(5), popRequired(6), partial(7) } -- RFC 5272 sec. 6.1.3.
-// 1 is RESERVED: it is neither a success nor a failure, so it is refused rather
-// than folded into either.
+// confirmRequired(5), popRequired(6), partial(7) }, RFC 5272 sec. 6.1.3.
+// 1 is reserved: it is neither a success nor a failure, so it is refused and
+// never folded into either.
 var STATUS_BY_VALUE = {
   0: "success", 2: "failed", 3: "pending", 4: "noSupport",
   5: "confirmRequired", 6: "popRequired", 7: "partial",
 };
 
-// CMCFailInfo ::= INTEGER { ... } -- RFC 5272 sec. 6.1.4. Values outside this set
-// are surfaced numerically rather than refused: sec. 6.1.4 reserves 1000..1999
+// CMCFailInfo ::= INTEGER { ... }, RFC 5272 sec. 6.1.4. Values outside this set
+// are surfaced numerically and never refused: sec. 6.1.4 reserves 1000..1999
 // for private extended reasons, so an unknown number is legal data.
 var FAIL_INFO_BY_VALUE = {
   0: "badAlg", 1: "badMessageCheck", 2: "badRequest", 3: "badTime", 4: "badCertId",
@@ -83,10 +83,10 @@ var FAIL_INFO_BY_VALUE = {
   13: "authDataFail",
 };
 
-// The CMS content types a Full PKI Request / Response may ride in -- RFC 5272
+// The CMS content types a Full PKI Request / Response may ride in, per RFC 5272
 // sec. 3.2 ("encapsulated in either a SignedData or an AuthenticatedData") and
 // sec. 4.2, which says the same of the response.
-// The names are the OID REGISTRY's, read off `oid.name(...)` rather than the
+// The names are the OID registry's, read off `oid.name(...)` and never taken from the
 // spec's prose: RFC 5652 calls the type AuthenticatedData, the registry row is
 // `authData`, and hard-coding the prose spelling would reject every conforming
 // AuthenticatedData response while looking correct.
@@ -124,12 +124,12 @@ function readBodyPartIdentity(node) {
 // ---- controls --------------------------------------------------------
 
 // TaggedAttribute ::= SEQUENCE { bodyPartID BodyPartID, attrType OBJECT
-// IDENTIFIER, attrValues SET OF AttributeValue } -- RFC 5272 sec. 3.2.1.1.
-// attrValues are surfaced RAW: this decoder does not know every control, and
-// PD7's "fail on an unrecognized control" binds the SERVER, not a client reading
-// a response, so an unknown value is data to hand on rather than a fault.
+// IDENTIFIER, attrValues SET OF AttributeValue }, RFC 5272 sec. 3.2.1.1.
+// attrValues are surfaced raw: this decoder does not know every control, and
+// PD7's "fail on an unrecognized control" binds the server, not a client reading
+// a response, so an unknown value is data to hand on, never a fault.
 //
-// The placement rule is NOT checked here: it depends on which message the control
+// The placement rule is not checked here: it depends on which message the control
 // sits in, which the enclosing walk knows and this shape does not.
 var TAGGED_ATTRIBUTE = schema.seq([
   schema.field("bodyPartID", schema.decode(readBodyPartIdentity)),
@@ -163,8 +163,8 @@ function assertControlPlacement(control, where) {
 // ---- status controls -------------------------------------------------
 
 // BodyPartReference ::= CHOICE { bodyPartID BodyPartID, bodyPartPath BodyPartPath }
-// -- an INTEGER and a SEQUENCE, so the arms are tag-disjoint. BodyPartPath is
-// SEQUENCE SIZE(1..MAX), so an empty one is malformed rather than "no path".
+// (an INTEGER and a SEQUENCE, so the arms are tag-disjoint). BodyPartPath is
+// SEQUENCE SIZE(1..MAX), so an empty one is malformed, never "no path".
 function parseBodyPartReference(node) {
   if (node.tagClass === "universal" && node.tagNumber === TAGS.INTEGER) {
     return { bodyPartID: readBodyPartId(node), bodyPartPath: null };
@@ -189,7 +189,7 @@ function parseBodyPartReference(node) {
  *
  *   universal INTEGER   -> failInfo
  *   context [1]         -> extendedFailInfo (2008 module)
- *   universal SEQUENCE  -> disambiguate on the FIRST child's tag:
+ *   universal SEQUENCE  -> disambiguate on the first child's tag:
  *                            OCTET STRING -> pendInfo  (PendInfo ::= SEQUENCE
  *                              { pendToken OCTET STRING, pendTime GeneralizedTime })
  *                            OBJECT IDENTIFIER -> extendedFailInfo
@@ -201,8 +201,8 @@ function parseBodyPartReference(node) {
  */
 function parseOtherStatusInfo(node, version) {
   // The extendedFailInfo arm belongs to CMCStatusInfoV2 alone. RFC 5272 sec. 6.1.1
-  // gives the v1 otherInfo exactly two arms -- `CHOICE { failInfo CMCFailInfo,
-  // pendInfo PendInfo }` -- so accepting the third here would read a failure
+  // gives the v1 otherInfo exactly two arms, `CHOICE { failInfo CMCFailInfo,
+  // pendInfo PendInfo }`, so accepting the third here would read a failure
   // verdict out of a v1 control that cannot legally express one, and the
   // disambiguation below would be answering a question v1 never asks.
   var extendedAllowed = version !== 1;
@@ -221,7 +221,7 @@ function parseOtherStatusInfo(node, version) {
     // unwrap. Both RFC 6402 modules are IMPLICIT: A.1 (rfc6402.txt:805) and A.2
     // (rfc6402.txt:1314) each open `DEFINITIONS IMPLICIT TAGS ::=`, and the
     // EXPLICIT-override rule does not apply here because the tagged type is a
-    // plain SEQUENCE rather than a CHOICE or an open type. Reading this arm as
+    // plain SEQUENCE, not a CHOICE or an open type. Reading this arm as
     // EXPLICIT would reject every conforming 2008-module response.
     return { failInfo: null, failInfoName: null, pendInfo: null, extendedFailInfo: readExtendedFailInfo(node.children, "[1] extendedFailInfo") };
   }
@@ -230,8 +230,8 @@ function parseOtherStatusInfo(node, version) {
     if (!first) throw E("cmc/ambiguous-status-info", "an empty OtherStatusInfo SEQUENCE matches neither pendInfo nor extendedFailInfo");
     if (first.tagClass === "universal" && first.tagNumber === TAGS.OCTET_STRING) {
       if (node.children.length !== 2) throw E("cmc/bad-status-info", "PendInfo must be { pendToken, pendTime }");
-      // pendTime is a GeneralizedTime specifically, so assert the tag rather than
-      // accept either time form -- a UTCTime here is a different encoding, and
+      // pendTime is a GeneralizedTime specifically, so assert the tag and do not
+      // accept either time form: a UTCTime here is a different encoding, and
       // reading it anyway would let a two-digit year through the retry clock.
       var timeNode = node.children[1];
       if (timeNode.tagClass !== "universal" || timeNode.tagNumber !== TAGS.GENERALIZED_TIME) {
@@ -256,7 +256,7 @@ function parseOtherStatusInfo(node, version) {
 }
 
 // ExtendedFailInfo ::= SEQUENCE { failInfoOID OBJECT IDENTIFIER, failInfoValue ANY }
-// The OID is surfaced raw and NEVER mapped onto a CMCFailInfo: RFC 5272 sec.
+// The OID is surfaced raw and never mapped onto a CMCFailInfo: RFC 5272 sec.
 // 6.1.1 makes internalCAError only a MAY for an unrecognized extended error, and
 // synthesizing it would report a reason the responder did not send.
 function readExtendedFailInfo(children, what) {
@@ -285,7 +285,7 @@ function parseStatusInfo(valueDer, version, bodyPartID) {
   var statusName = STATUS_BY_VALUE[statusNum];
   if (!statusName) {
     // 1 is reserved and everything above 7 is unassigned. An unknown status is
-    // not a verdict in either direction, so it is refused rather than mapped.
+    // not a verdict in either direction, so it is refused and never mapped.
     throw E("cmc/bad-status", "unknown CMCStatus " + statusNum + " (1 is reserved; RFC 5272 sec. 6.1.3)");
   }
 
@@ -337,7 +337,7 @@ function parseStatusInfo(valueDer, version, bodyPartID) {
 // The cross-field coupling (RFC 5272 sec. 6.1.1 / 6.1.2): failInfo and
 // extendedFailInfo are "present only if cMCStatus contains the value failed",
 // and pendInfo "MUST be populated for a cMCStatus value of pending or partial".
-// A message whose status and detail disagree is refused rather than reconciled --
+// A message whose status and detail disagree is refused, never reconciled:
 // the two halves would otherwise let a caller read a verdict neither field states.
 function _assertStatusCoherent(s) {
   var isFailed = s.status === "failed";
@@ -363,8 +363,8 @@ function _assertStatusCoherent(s) {
 //                           orm [2] SEQUENCE { bodyPartID, requestMessageType,
 //                                              requestMessageValue } }
 // The CMC module is IMPLICIT TAGS, so each context tag REPLACES the arm's own
-// universal tag -- the [0] node's direct children are the TaggedCertificationRequest
-// fields, NOT a nested SEQUENCE. An EXPLICIT encoding is therefore a different
+// universal tag: the [0] node's direct children are the TaggedCertificationRequest
+// fields, not a nested SEQUENCE. An EXPLICIT encoding is therefore a different
 // (and invalid) message, which is what C5 pins.
 // An IMPLICIT context-tagged constructed node re-encoded under the universal
 // SEQUENCE tag it stands in for. IMPLICIT tagging REPLACES the tag and leaves the
@@ -402,8 +402,8 @@ function parseTaggedRequest(node) {
     // bodyPartID field of the other objects", and sec. 6.5.2 repeats it
     // ("... either the bodyPartID of a TaggedCertificationRequest (PKCS #10) or
     // the certReqId of the CertRequest within a CertReqMsg (CRMF)"). So the
-    // certReqId is read here and carried into the SAME whole-message uniqueness
-    // check every other body part is bound by -- returning null would silently
+    // certReqId is read here and carried into the same whole-message uniqueness
+    // check every other body part is bound by; returning null would silently
     // exempt this arm from it.
     //
     //   CertReqMsg  ::= SEQUENCE { certReq CertRequest, popo OPTIONAL, regInfo OPTIONAL }
@@ -445,7 +445,7 @@ function parseTaggedRequest(node) {
 // ---- body-part identity ----------------------------------------------
 
 // RFC 5272 sec. 3.2.2: "The body part identifier MUST be unique within a single
-// PKIData or PKIResponse." The scope is the WHOLE message -- a checker that ran
+// PKIData or PKIResponse." The scope is the whole message: a checker that ran
 // per-sequence would accept a control and a request that collide, which is
 // exactly the shape B2 pins.
 function assertUniqueBodyPartIds(ids) {
@@ -463,8 +463,8 @@ function assertUniqueBodyPartIds(ids) {
 // ---- the two message bodies ------------------------------------------
 
 // The two message bodies as engine schemas. Declaring them means the engine owns
-// the positional reads, the field arity and the SET-OF ordering -- the bug class
-// a hand-rolled cursor keeps reintroducing -- while the rules that genuinely span
+// the positional reads, the field arity and the SET-OF ordering (the bug class
+// a hand-rolled cursor keeps reintroducing), while the rules that genuinely span
 // fields (whole-message body-part uniqueness, control placement, the status
 // cross-checks) run in the build / the caller, which is where they can see
 // everything they need.
@@ -486,9 +486,9 @@ var REQ_SEQUENCE = schema.seqOf(schema.decode(parseTaggedRequest),
 
 // TaggedContentInfo ::= SEQUENCE { bodyPartID, contentInfo } (RFC 5272 sec.
 // 3.2.1.3) and OtherMsg ::= SEQUENCE { bodyPartID, otherMsgType, otherMsgValue }
-// (sec. 3.2.1.4). Neither payload is interpreted here -- the ContentInfo is a
-// CMS object the caller decodes, the OtherMsg value is by definition arbitrary --
-// but BOTH carry a body part identity, and sec. 3.2.2's uniqueness rule covers
+// (sec. 3.2.1.4). Neither payload is interpreted here (the ContentInfo is a
+// CMS object the caller decodes, the OtherMsg value is by definition arbitrary),
+// but both carry a body part identity, and sec. 3.2.2's uniqueness rule covers
 // "each element of a PKIData or PKIResponse". Decoding just the identifier is
 // what lets that rule cover them without this layer claiming to understand the
 // payload.
@@ -498,8 +498,8 @@ var TAGGED_CONTENT_INFO = schema.seq([
 ], {
   assert: "sequence", arity: { exact: 2 }, code: "cmc/bad-cms-sequence", what: "a TaggedContentInfo",
   build: function (m) {
-    // The payload stays RAW -- this layer does not decode a content type it may
-    // not know -- but it must still BE a ContentInfo: SEQUENCE { contentType
+    // The payload stays raw, since this layer does not decode a content type it may
+    // not know, but it must still be a ContentInfo: SEQUENCE { contentType
     // OBJECT IDENTIFIER, content [0] EXPLICIT ANY OPTIONAL } (RFC 5652 sec. 3).
     // Surfacing an INTEGER, or anything else that cannot be one, as a content
     // info would hand the caller a "CMS message" no CMS reader will accept, which
@@ -511,9 +511,9 @@ var TAGGED_CONTENT_INFO = schema.seq([
       throw E("cmc/bad-cms-sequence",
         "a TaggedContentInfo carries a CMS ContentInfo, which leads with its contentType OBJECT IDENTIFIER (RFC 5652 sec. 3)");
     }
-    // READ the contentType rather than inspecting its tag. An OBJECT IDENTIFIER
-    // TLV can carry content no OID reader will accept -- empty, or a subidentifier
-    // padded to a non-minimal encoding -- and a tag check waves both through. The
+    // Read the contentType; do not merely inspect its tag. An OBJECT IDENTIFIER
+    // TLV can carry content no OID reader will accept (empty, or a subidentifier
+    // padded to a non-minimal encoding) and a tag check waves both through. The
     // toolkit's own CMS parser refuses them, so accepting them here would let the
     // builder sign a "CMS message" pki.schema.cms.parse will not read back. The
     // VALUE is still not interpreted: this layer only establishes that there is a
@@ -523,10 +523,10 @@ var TAGGED_CONTENT_INFO = schema.seq([
       throw E("cmc/bad-cms-sequence",
         "a TaggedContentInfo carries a CMS ContentInfo, whose contentType must be a readable OBJECT IDENTIFIER (RFC 5652 sec. 3)", e);
     }
-    // The WHOLE envelope, not just its first field: content is `[0] EXPLICIT ANY
+    // The whole envelope, not just its first field: content is `[0] EXPLICIT ANY
     // DEFINED BY contentType OPTIONAL`, so at most one more element and it is that
     // tag. An INTEGER sitting where the content belongs, or a third field, is not
-    // a ContentInfo any CMS reader will take -- and stopping at the leading OID
+    // a ContentInfo any CMS reader will take, and stopping at the leading OID
     // would surface it as one.
     if (kids.length > 2) {
       throw E("cmc/bad-cms-sequence",
@@ -539,9 +539,9 @@ var TAGGED_CONTENT_INFO = schema.seq([
         throw E("cmc/bad-cms-sequence",
           "a CMS ContentInfo's second field is the [0] EXPLICIT content (RFC 5652 sec. 3)");
       }
-      // EXPLICIT wraps EXACTLY ONE value (X.690 sec. 8.14). Checking the tag alone
-      // would let an EMPTY wrapper, or one holding several values, read as a content
-      // info -- shapes pki.schema.cms.parse refuses as cms/not-a-content-info, so the
+      // EXPLICIT wraps exactly one value (X.690 sec. 8.14). Checking the tag alone
+      // would let an empty wrapper, or one holding several values, read as a content
+      // info: shapes pki.schema.cms.parse refuses as cms/not-a-content-info, so the
       // builder's readback would pass a message its own CMS reader will not accept.
       if (!content.children || content.children.length !== 1) {
         throw E("cmc/bad-cms-sequence",
@@ -569,7 +569,7 @@ var OTHER_MSG = schema.seq([
 });
 
 // PKIData ::= SEQUENCE { controlSequence, reqSequence, cmsSequence,
-//   otherMsgSequence } -- RFC 5272 sec. 3.2.1. All FOUR are mandatory though each
+//   otherMsgSequence }, RFC 5272 sec. 3.2.1. All four are mandatory though each
 // may be empty, so `arity: { exact: 4 }` is the rule, not a convenience.
 var PKI_DATA = schema.seq([
   schema.field("controlSequence", CONTROL_SEQUENCE),
@@ -591,7 +591,7 @@ var PKI_DATA = schema.seq([
       // The raw reqSequence TLV, tag and length included: the Identity Proof V2
       // witness is computed over exactly these bytes "encoded exactly as it
       // appears in the Full PKI Request" (RFC 5272 sec. 6.2.1), so it is taken
-      // off the matched NODE rather than re-encoded from the decoded requests.
+      // off the matched node, never re-encoded from the decoded requests.
       reqSequenceBytes: m.fields.reqSequence.node.bytes,
     };
   },
@@ -621,7 +621,7 @@ var PKI_RESPONSE = schema.seq([
 });
 
 // Collect the status controls out of an already-parsed control list, in wire
-// order. Absence is NOT an error: RFC 5272 sec. 6.1.2 says "If no status exists
+// order. Absence is not an error: RFC 5272 sec. 6.1.2 says "If no status exists
 // for a Simple or Full PKI Request, then the value of success is assumed", so a
 // response with no status control is a successful one.
 function _collectStatuses(controls) {
@@ -648,9 +648,9 @@ function _finishBody(body, where) {
     return c.attrType !== OID_STATUS_INFO && c.attrType !== OID_STATUS_INFO_V2 && c.attrName === null;
   });
   // RFC 5272 sec. 3.2.2 scopes uniqueness to "each element of a PKIData or
-  // PKIResponse", and FOUR element kinds carry an identity. Enumerated here in
+  // PKIResponse", and four element kinds carry an identity. Enumerated here in
   // one place so the rule cannot hold for some of them and quietly lapse for the
-  // rest: controls (sec. 3.2.1.1), requests (sec. 3.2.1.2 -- the tcr/orm
+  // rest: controls (sec. 3.2.1.1), requests (sec. 3.2.1.2, the tcr/orm
   // bodyPartID and the crm arm's certReqId), content infos (sec. 3.2.1.3) and
   // other messages (sec. 3.2.1.4).
   var ids = [];
@@ -699,10 +699,10 @@ function parsePkiData(input) {
  * @spec       RFC 5272 sec. 4.2.1
  * @related    pki.schema.cmc.parse, pki.schema.cmc.parsePkiData
  *
- * Decode a bare `PKIResponse` body. A PKIResponse has THREE sequences -- there is
- * no `reqSequence` -- and all three are mandatory though each may be empty. The
+ * Decode a bare `PKIResponse` body. A PKIResponse has three sequences (there is
+ * no `reqSequence`) and all three are mandatory though each may be empty. The
  * status controls are collected in wire order; a response may legitimately carry
- * several, and carrying NONE means success (RFC 5272 sec. 6.1.2).
+ * several, and carrying none means success (RFC 5272 sec. 6.1.2).
  *
  * @example
  *   var b = pki.asn1.build;
@@ -730,9 +730,9 @@ function parsePkiResponse(input) {
  * is DER, a PEM `CMS` block, or an already-parsed `pki.schema.cms` object. The CMS
  * layer is peeled, the encapsulated content type selects the body
  * (`id-cct-PKIData` -> a request, `id-cct-PKIResponse` -> a response), and any
- * other content type is refused as not-CMC rather than guessed at.
+ * other content type is refused as not-CMC, never guessed at.
  *
- * The parsed CMS is returned on `cms` so a caller can verify the signature -- this
+ * The parsed CMS is returned on `cms` so a caller can verify the signature; this
  * decoder never does: reading a message and trusting it are separate steps, and
  * RFC 5272 sec. 3.2.1.3.4 makes the signature check the caller's obligation.
  *

package/lib/schema-cmp.js

@@ -10,9 +10,9 @@
  *
  * @intro
  *   Certificate Management Protocol handling per RFC 9810 (which obsoletes
- *   RFC 4210 and RFC 9480). `parse` decodes a `PKIMessage` -- the protected
+ *   RFC 4210 and RFC 9480). `parse` decodes a `PKIMessage`, the protected
  *   transport envelope CMP enrollment, revocation, confirmation, and support
- *   exchanges ride -- into its header (version, sender / recipient
+ *   exchanges ride, into its header (version, sender / recipient
  *   GeneralNames including the NULL-DN anonymous form, nonces, transaction
  *   id, free text, general info), its body, its protection bits, and its
  *   extra certificates.
@@ -29,7 +29,7 @@
  *   or signature itself. DER-only, fail-closed.
  *
  * @card
- *   Parse DER / PEM RFC 9810 CMP PKIMessages -- header, 27-arm body (requests
+ *   Parse DER / PEM RFC 9810 CMP PKIMessages: header, 27-arm body (requests
  *   via CRMF, encrypted certs via CMS, the rest structural or raw),
  *   protection inputs surfaced byte-exact for external verification,
  *   fail-closed.
@@ -67,7 +67,7 @@ var PKI_FREE_TEXT = schema.seqOf(UTF8_TEXT, {
   build: function (m) { return m.items.map(function (it) { return it.value; }); },
 });
 
-// PKIStatus ::= INTEGER {0..6} (sec. 5.2.3) -- a value whitelist, surfaced named.
+// PKIStatus ::= INTEGER {0..6} (sec. 5.2.3): a value whitelist, surfaced named.
 var PKI_STATUS_NAMES = ["accepted", "grantedWithMods", "rejection", "waiting",
   "revocationWarning", "revocationNotification", "keyUpdateWarning"];
 var PKI_STATUS = schema.decode(function (n, ctx) {
@@ -97,17 +97,17 @@ var PKI_FAILURE_INFO = schema.decode(function (n, ctx) {
   return { bits: bits, raw: bs };
 });
 
-// PollRep checkAfter is a delay in seconds -- negative poisons scheduling, and
+// PollRep checkAfter is a delay in seconds; a negative one poisons scheduling, and
 // the value surfaces as an exact number or not at all.
 var CHECK_AFTER = schema.decode(function (n, ctx) {
   return guard.range.uint31(asn1.read.integer(n), ctx.E, "cmp/bad-poll-rep", "checkAfter delay in seconds (RFC 9810 sec. 5.3.22)");
 });
 
-// A raw certificate / CRL / publication-info element -- surfaced byte-exact for
+// A raw certificate / CRL / publication-info element, surfaced byte-exact for
 // downstream parsing, but structurally a universal SEQUENCE: a CMPCertificate
 // is a Certificate, and CertificateList / PKIPublicationInfo are SEQUENCEs, so
 // a primitive (an INTEGER) or wrong-tag element is not a valid structure and
-// rejects rather than handing arbitrary bytes to certificate processing. The
+// rejects, never handing arbitrary bytes to certificate processing. The
 // `code` names the containing structure (a shared leaf cannot know its context).
 function rawSequence(code) {
   return pkix.rawNonEmptySequence(NS, { code: code, message: "expected a non-empty universal SEQUENCE (Certificate / CertificateList / PKIPublicationInfo)" });
@@ -140,10 +140,10 @@ var INFO_TYPE_AND_VALUE = schema.seq([
       throw ctx.E("cmp/bad-info-value", "a recognized fixed-syntax id-it (implicitConfirm / confirmWaitTime / certProfile) must carry its infoValue (RFC 9810 sec. 5.1.1)");
     }
     if (valueNode !== null) {
-      // A recognized id-it value is validated by CONTENT, not just tag: run the
+      // A recognized id-it value is validated by content, not just tag: run the
       // strict typed reader so a well-tagged but malformed payload (a non-empty
       // NULL, a GeneralizedTime carrying garbage, an invalid-UTF-8 string)
-      // rejects rather than being surfaced as valid CMP.
+      // rejects and is never surfaced as valid CMP.
       if (t === OID_IMPLICIT_CONFIRM) {
         if (!(valueNode.tagClass === "universal" && valueNode.tagNumber === TAGS.NULL)) {
           throw ctx.E("cmp/bad-info-value", "an implicitConfirm value must be NULL (RFC 9810 sec. 5.1.1.1)");
@@ -276,14 +276,14 @@ var CERT_STATUS = schema.seq([
   },
 });
 
-// CertConfirmContent ::= SEQUENCE OF CertStatus -- an EMPTY sequence is legal
+// CertConfirmContent ::= SEQUENCE OF CertStatus, where an empty sequence is legal
 // (reject-all, sec. 5.3.18), so no SIZE floor.
 var CERT_CONFIRM_CONTENT = schema.seqOf(CERT_STATUS, {
   code: "cmp/bad-cert-status", what: "CertConfirmContent",
   build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
 });
 
-// GenMsgContent / GenRepContent ::= SEQUENCE OF InfoTypeAndValue -- no SIZE
+// GenMsgContent / GenRepContent ::= SEQUENCE OF InfoTypeAndValue, with no SIZE
 // bound, empty legal (sec. 5.3.19/.20).
 var GEN_MSG_CONTENT = schema.seqOf(INFO_TYPE_AND_VALUE, {
   code: "cmp/bad-info-type-and-value", what: "GenMsgContent",
@@ -291,7 +291,7 @@ var GEN_MSG_CONTENT = schema.seqOf(INFO_TYPE_AND_VALUE, {
 });
 
 // RevDetails ::= SEQUENCE { certDetails CertTemplate, crlEntryDetails
-// Extensions OPTIONAL } (sec. 5.3.9) -- the CertTemplate interior (an IMPLICIT
+// Extensions OPTIONAL } (sec. 5.3.9). The CertTemplate interior (an IMPLICIT
 // TAGS module) is owned by the CRMF parser and walked NS-bound there.
 var CERT_TEMPLATE_LEAF = schema.decode(function (n) { return crmf.walkCertTemplate(n); });
 var REV_DETAILS = schema.seq([
@@ -353,20 +353,20 @@ var REV_REP_CONTENT = schema.seq([
 // EncryptedKey ::= CHOICE { encryptedValue EncryptedValue (deprecated),
 // envelopedData [0] EnvelopedData } (sec. 5.2.2). EncryptedKey is imported from
 // the RFC 4211 CRMF module, which is IMPLICIT TAGS, so `envelopedData [0]` is
-// an IMPLICIT context tag REPLACING the EnvelopedData SEQUENCE tag -- the [0]
-// node's children ARE the EnvelopedData fields, no inner wrapper. Retag it to
+// an IMPLICIT context tag replacing the EnvelopedData SEQUENCE tag: the [0]
+// node's children are the EnvelopedData fields, with no inner wrapper. Retag it to
 // the universal SEQUENCE the CMS walker expects, exactly as the sibling CRMF
 // `encryptedKey [4] EnvelopedData` POP arm does (schema-crmf.js). The
-// deprecated encryptedValue arm surfaces RAW -- never field-walked, so nothing
+// deprecated encryptedValue arm surfaces raw and is never field-walked, so nothing
 // dereferences its optional interior (absent algorithm parameters crash
 // consumers that walk it blindly).
 var ENCRYPTED_KEY = schema.choice([
   { when: { tagClass: "universal", tagNumber: TAGS.SEQUENCE },
     schema: schema.decode(function (n, ctx) {
       // An RFC 4211 sec. 2 EncryptedValue REQUIRES encValue (its final BIT STRING
-      // field), so an EMPTY SEQUENCE has the right tag but is not any valid
-      // EncryptedValue -- require at least one child rather than surface a
-      // degenerate structure as encrypted certificate/key bytes (the same
+      // field), so an empty SEQUENCE has the right tag but is not any valid
+      // EncryptedValue. Require at least one child, so no degenerate structure
+      // surfaces as encrypted certificate/key bytes (the same
       // non-empty rule every raw-SEQUENCE surface in this module applies).
       if (!(n.children && n.children.length >= 1)) {
         throw ctx.E("cmp/bad-cert-response", "an EncryptedValue must be a non-empty SEQUENCE (RFC 4211 sec. 2)");
@@ -391,9 +391,9 @@ var ENCRYPTED_KEY = schema.choice([
       if (env.recipientInfos.length !== 1) {
         throw ctx.E("cmp/bad-cert-response", "an EncryptedKey EnvelopedData must contain exactly one RecipientInfo (RFC 9810 sec. 5.2.2)");
       }
-      // The ciphertext IS the encrypted certificate / private key here, so an
-      // EnvelopedData with no ciphertext to decrypt -- absent (detached, CMS
-      // permits it) OR present-but-empty -- must reject (RFC 9810 sec. 5.2.2/sec. 5.3.4;
+      // The ciphertext is the encrypted certificate / private key here, so an
+      // EnvelopedData with no ciphertext to decrypt, whether absent (detached, CMS
+      // permits it) or present-but-empty, must reject (RFC 9810 sec. 5.2.2/sec. 5.3.4;
       // the same rule the CRMF encryptedKey POP arm enforces).
       var ct = env.encryptedContentInfo.encryptedContent;
       if (ct === null || ct.length === 0) {
@@ -456,9 +456,9 @@ var CERT_RESPONSE = schema.seq([
       throw ctx.E("cmp/bad-cert-response",
         "a CertResponse must not carry both failInfo and certifiedKeyPair (RFC 9810 sec. 5.3.4)");
     }
-    // A certifiedKeyPair is present ONLY when the status grants the certificate:
-    // accepted (0) or grantedWithMods (1). Any other status -- rejection, waiting,
-    // the revocation / keyUpdate warnings -- denies or defers the request, so a
+    // A certifiedKeyPair is present only when the status grants the certificate:
+    // accepted (0) or grantedWithMods (1). Any other status (rejection, waiting,
+    // the revocation / keyUpdate warnings) denies or defers the request, so a
     // certificate under it is a malformed response even when no explicit failInfo
     // bit is set (a rejection is commonly signalled by status alone). Keying the
     // rule off failInfo presence alone would let a bare-rejection status ship a
@@ -477,8 +477,8 @@ var CERT_RESPONSE = schema.seq([
 });
 
 // CertRepMessage ::= SEQUENCE { caPubs [1] OPTIONAL, response SEQUENCE OF
-// CertResponse } (sec. 5.3.4) -- the optional precedes the required field (the
-// x509-version shape). caPubs surface raw: the parser confers NO trust.
+// CertResponse } (sec. 5.3.4), where the optional precedes the required field (the
+// x509-version shape). caPubs surface raw: the parser confers no trust.
 var CERT_REP_MESSAGE = schema.seq([
   schema.optional("caPubs", schema.seqOf(rawSequence("cmp/bad-cert-rep"), {
     min: 1, code: "cmp/bad-cert-rep", what: "caPubs",
@@ -502,7 +502,7 @@ var CERT_REP_MESSAGE = schema.seq([
 // Certificate OPTIONAL, caCerts [1] SEQUENCE OF Certificate OPTIONAL,
 // keyPairHist [2] SEQUENCE OF CertifiedKeyPair OPTIONAL } (sec. 5.3.8). The
 // keyPairHist CertifiedKeyPairs can carry the same EnvelopedData form as the
-// enrollment responses, so krp is decoded (not surfaced raw) -- the operator sees
+// enrollment responses, so krp is decoded (not surfaced raw) and the operator sees
 // the status / key history and the cross-field EnvelopedData version check runs.
 var KEY_REC_REP_CONTENT = schema.seq([
   schema.field("status", PKI_STATUS_INFO),
@@ -579,8 +579,8 @@ var DECODED_ARMS = {
 };
 
 // The open-CHOICE dispatch: tag -> arm name; walk where a schema exists;
-// surface every other defined arm raw as { arm, tag, bytes } -- `decoded` is
-// ABSENT (not null) on raw arms, so its presence discriminates decoded-empty
+// surface every other defined arm raw as { arm, tag, bytes }, where `decoded` is
+// absent (not null) on raw arms, so its presence discriminates decoded-empty
 // (pkiconf decodes to null) from recognized-undecoded. `nested` [20] is never
 // auto-recursed: a self-nesting tower amplifies per-level walk products, so
 // the operator re-feeds its bytes to parse explicitly.
@@ -625,7 +625,7 @@ var BODY = schema.decode(function (n, ctx) {
 
 // ---- the message envelope -----------------------------------------------------
 
-// PKIProtection ::= BIT STRING -- raw bits for the external verifier. Every
+// PKIProtection ::= BIT STRING: raw bits for the external verifier. Every
 // RFC 9481 MSG_SIG_ALG / MSG_MAC_ALG output is an octet string, so the BIT
 // STRING must be octet-aligned; with no in-tree CMP verify layer this is
 // enforced at parse (the posture the OCSP signature shares), fail-closed.
@@ -644,7 +644,7 @@ var PROTECTION = schema.decode(function (n, ctx) {
 // span structures: protection presence <=> protectionAlg presence (sec. 5.1.1,
 // both directions), and a certConf hashAlg requires pvno cmp2021(3)
 // (sec. 5.3.18). headerBytes / bodyBytes are the exact wire slices protection is
-// computed over (as DER-SEQUENCE(headerBytes || bodyBytes)) -- surfaced raw,
+// computed over (as DER-SEQUENCE(headerBytes || bodyBytes)), surfaced raw and
 // never re-encoded.
 var PKI_MESSAGE = schema.seq([
   schema.field("header", PKI_HEADER),
@@ -674,7 +674,7 @@ var PKI_MESSAGE = schema.seq([
         }
       }
     }
-    // RFC 9810 sec. 5.2.2 / sec. 7 -- EnvelopedData is cmp2021(3) syntax: a response
+    // RFC 9810 sec. 5.2.2 / sec. 7: EnvelopedData is cmp2021(3) syntax, so a response
     // carrying it (an encryptedCert or a privateKey in the envelopedData form)
     // under pvno < 3 is a version mismatch, the same version gate the certConf
     // hashAlg rule applies. The deprecated EncryptedValue form is the pre-2021
@@ -701,10 +701,10 @@ var PKI_MESSAGE = schema.seq([
     // CertRepMessage syntax "with the restriction that no encrypted private key
     // can be sent": cross-certification certifies an existing CA's public key,
     // so there is no key generation and CertifiedKeyPair.privateKey has no
-    // meaning. Reject a ccp that carries one rather than surface the key
-    // material; the field stays legal in the enrollment responses (ip/cp/kup).
+    // meaning. Reject a ccp that carries one; never surface the key
+    // material. The field stays legal in the enrollment responses (ip/cp/kup).
     if (body.arm === "ccp" && body.decoded && body.decoded.response) {
-      // RFC 9810 Appendix D.6 -- a one-way cross-certification response carries
+      // RFC 9810 Appendix D.6: a one-way cross-certification response carries
       // exactly one CertResponse (multiple cross-certificates go in separate
       // PKIMessages), the mirror of the ccr one-CertReqMsg rule.
       if (body.decoded.response.length !== 1) {
@@ -717,10 +717,10 @@ var PKI_MESSAGE = schema.seq([
         }
       }
     }
-    // RFC 9810 sec. 5.3.11 -- a cross-certification request (ccr) MUST NOT send the
+    // RFC 9810 sec. 5.3.11: a cross-certification request (ccr) MUST NOT send the
     // private key to the responding CA (the requesting CA generates and holds
-    // it). The private-key-carrying POP choices -- encryptedKey (cmp2021) and the
-    // deprecated thisMessage (cmp2000) -- are therefore forbidden in a ccr; the
+    // it). The private-key-carrying POP choices, encryptedKey (cmp2021) and the
+    // deprecated thisMessage (cmp2000), are therefore forbidden in a ccr; the
     // MAC (dhMAC / agreeMAC) and indirect (subsequentMessage) methods carry no
     // key. Checked before the version gate so a ccr always gets the ccr verdict.
     if (body.arm === "ccr" && body.decoded && body.decoded.messages) {
@@ -863,22 +863,22 @@ var PKI_MESSAGE = schema.seq([
  * structurally; `pkiconf` decodes to `null`; every other defined arm --
  * `p10cr` (feed `body.bytes` to `pki.schema.csr.parse`), the
  * challenge-response and announcement arms, and `nested` (never
- * auto-recursed) -- surfaces raw with `decoded` absent. `certReqId` values
+ * auto-recursed) surfaces raw with `decoded` absent. `certReqId` values
  * are BigInt and accept the protocol's -1 sentinel.
  *
  * Protection is surfaced, not verified: `protection` carries the raw,
- * octet-aligned BIT STRING (unused bits are rejected at parse -- every
+ * octet-aligned BIT STRING (unused bits are rejected at parse, since every
  * RFC 9481 protection algorithm emits whole octets), and the MAC or
  * signature is computed over the DER of the virtual
- * `ProtectedPart ::= SEQUENCE { header, body }` -- reconstruct it as a DER
+ * `ProtectedPart ::= SEQUENCE { header, body }`, which you reconstruct as a DER
  * SEQUENCE wrapping exactly `headerBytes || bodyBytes`. `extraCerts` are
- * raw DER certificates and are NOT covered by protection.
+ * raw DER certificates and are not covered by protection.
  *
  * Throws `CmpError` when the bytes are not a well-formed PKIMessage, and
  * `Asn1Error` when the underlying DER is malformed. The request-arm interiors
  * (`ir` / `cr` / `kur` / `krr` / `ccr`, and an `rr` entry's `certDetails`) are
  * walked by the CRMF parser, so a malformed interior throws `CrmfError` with a
- * `crmf/*` code -- all `PkiError` subclasses.
+ * `crmf/*` code; all are `PkiError` subclasses.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");