@blamejs/pki 0.5.7 → 0.5.8

package/lib/schema-cms.js

@@ -12,13 +12,13 @@
  *   CMS handling per RFC 5652 (sec. 3 ContentInfo envelope). `parse` turns a DER or PEM
  *   (`CMS`) message into a structured object and is an OID-dispatch envelope --
  *   ContentInfo reads its `contentType` and structurally decodes SignedData (sec. 5),
- *   EnvelopedData (sec. 6, with all five RecipientInfo kinds -- key-transport,
+ *   EnvelopedData (sec. 6, with all five RecipientInfo kinds: key-transport,
  *   key-agreement per RFC 5753, KEK, password, and other, including the RFC 9629
  *   KEMRecipientInfo carried under `id-ori-kem` with ML-KEM per RFC 9936),
  *   EncryptedData (sec. 8), AuthenticatedData (sec. 9), and AuthEnvelopedData (RFC 5083,
  *   with RFC 5084 AES-GCM/CCM parameter validation); the remaining PKCS#7 content
  *   types are recognized and rejected with a precise `cms/unsupported-content-type`
- *   rather than a generic unknown-format error. A SignedData surfaces its version,
+ *   in place of a generic unknown-format error. A SignedData surfaces its version,
  *   digest algorithms, encapsulated content, certificate / CRL sets, and signer
  *   infos; an EnvelopedData its recipient infos and encrypted content info; an
  *   EncryptedData its encrypted content info; an AuthenticatedData its MAC
@@ -27,11 +27,11 @@
  *   content, validated AEAD parameters, and raw `mac`.
  *
  *   CMS is a signed container: the bytes an external verifier must hash are
- *   surfaced RAW and never re-serialized. `encapContentInfo.eContent` is the raw
+ *   surfaced raw and never re-serialized. `encapContentInfo.eContent` is the raw
  *   content (or `null` for a detached signature); each SignerInfo's `signature` is
  *   raw, and `signedAttrsBytes` is the on-wire `[0]` SignedAttributes TLV so a
  *   verifier can re-tag it to the universal SET the signature is computed over
- *   (sec. 5.4) -- `authAttrsBytes` plays the same role for the sec. 9.2 MAC input and the
+ *   (sec. 5.4); `authAttrsBytes` plays the same role for the sec. 9.2 MAC input and the
  *   RFC 5083 sec. 2.2 AAD. Embedded certificates and CRLs are surfaced as raw DER +
  *   their outer tag, validated against the closed CertificateChoices /
  *   RevocationInfoChoice tag sets, so an obsolete alternative never fails the
@@ -63,7 +63,7 @@ var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var ATTRIBUTE = pkix.attribute(NS);
 var NAME = pkix.name(NS);
 
-// CMSVersion ::= INTEGER -- the SignedData version is {1,3,4,5} and the SignerInfo
+// CMSVersion ::= INTEGER, where the SignedData version is {1,3,4,5} and the SignerInfo
 // version is {1,3} (RFC 5652 sec. 5.1, sec. 5.3). Wider accept maps than any other format.
 var SIGNED_DATA_VERSION = pkix.versionReader(NS, { "1": 1, "3": 3, "4": 4, "5": 5 });
 var SIGNER_VERSION = pkix.versionReader(NS, { "1": 1, "3": 3 });
@@ -188,7 +188,7 @@ function _checkContentBindingAttrs(attrs, mode) {
       // content-type attribute (what it signs has no content type).
       if (mode === "countersig") throw NS.E("cms/misplaced-attr", "a countersignature's signedAttrs must not carry a content-type attribute (RFC 5652 sec. 11.4)");
       if (a.values.length !== 1) throw NS.E("cms/bad-content-type-attr", "the content-type attribute must be single-valued");
-      // ContentType ::= OBJECT IDENTIFIER (RFC 5652 sec. 11.1) -- validate the value's
+      // ContentType ::= OBJECT IDENTIFIER (RFC 5652 sec. 11.1): validate the value's
       // full syntax (tag AND minimal base-128 OID content), not just the tag, so a
       // truncated / non-minimal subidentifier is rejected here, not at verify time.
       try { asn1.read.oid(asn1.decode(a.values[0])); }
@@ -196,7 +196,7 @@ function _checkContentBindingAttrs(attrs, mode) {
     } else if (a.type === OID_MESSAGE_DIGEST) {
       md += 1;
       if (a.values.length !== 1) throw NS.E("cms/bad-message-digest-attr", "the message-digest attribute must be single-valued");
-      // MessageDigest ::= OCTET STRING (RFC 5652 sec. 11.2) -- validate the full syntax.
+      // MessageDigest ::= OCTET STRING (RFC 5652 sec. 11.2): validate the full syntax.
       try { asn1.read.octetString(asn1.decode(a.values[0])); }
       catch (e) { throw NS.E("cms/bad-message-digest-attr", "the message-digest attribute value must be an OCTET STRING", e); }
     } else if (a.type === OID_SIGNING_TIME) {
@@ -214,7 +214,7 @@ function _checkContentBindingAttrs(attrs, mode) {
 
 // looksLikeSignedAttributes(bytes) -> boolean.
 //
-// Does `bytes` parse as a DER SignedAttributes block -- a SET OF Attribute carrying BOTH the
+// Does `bytes` parse as a DER SignedAttributes block, a SET OF Attribute carrying both the
 // content-type and message-digest attributes RFC 5652 sec. 5.3 makes mandatory whenever signed
 // attributes are present?
 //
@@ -224,20 +224,20 @@ function _checkContentBindingAttrs(attrs, mode) {
 // re-presented as one made over content: drop the signedAttrs field and set the encapsulated
 // content to the DER of those same attributes. Sec. 5.4 then says the signature is over the content
 // itself, which is exactly what it covers, and with no attributes there is no message-digest or
-// content-type attribute left to disagree. The proposed standards fixes are protocol changes -- a
-// context string naming which mode was signed -- that no verifier can apply on its own.
+// content-type attribute left to disagree. The proposed standards fixes are protocol changes (a
+// context string naming which mode was signed) that no verifier can apply on its own.
 //
 // What a verifier CAN do is refuse the shape. Every message produced by the attack has, as its
 // content, the encoded SignedAttributes of a real message, and sec. 5.3 requires those to carry
 // both attributes named above. That makes their presence a NECESSARY condition of the attack rather
 // than a guess, and the shape is one ordinary content does not have: a certificate, a JSON payload,
 // arbitrary bytes, and even a SET OF other attributes all fail it. The cost is a message whose
-// legitimate content really is an encoded SignedAttributes block signed WITHOUT attributes, which
+// legitimate content really is an encoded SignedAttributes block signed without attributes, which
 // is refused as genuinely ambiguous -- sign it with attributes and it is unambiguous again.
 //
 // One mandatory attribute value, held to all three conditions a real SignedAttributes meets:
 // exactly one value (RFC 5652 sec. 11.1 / sec. 11.2 make both single-valued), the right tag, and a
-// body that actually READS as that type. All three together, for each attribute -- checking the
+// body that actually reads as that type. All three together, for each attribute; checking the
 // cardinality and the tag while letting an undecodable body through would refuse content the real
 // SignedAttributes parser could never have produced, which is the false positive this whole
 // detector is shaped to avoid.
@@ -280,10 +280,10 @@ function looksLikeSignedAttributes(bytes) {
   if (!schema.isUniversal(node, asn1.TAGS.SET) || !node.constructed) return false;
   var kids = node.children || [];
   if (!kids.length) return false;
-  // Every rule _checkContentBindingAttrs applies to a REAL SignedAttributes is applied here, and
+  // Every rule _checkContentBindingAttrs applies to a real SignedAttributes is applied here, and
   // for one reason: the detector must match only what a conforming block can be. A set the real
   // parser would have rejected cannot be the preimage of any signature, so matching it would refuse
-  // content no attack could have produced. Enumerated against that function rather than discovered
+  // content no attack could have produced. Enumerated against that function, never discovered
   // one rule at a time -- no duplicate attribute types (sec. 5.3), content-type single-valued and a
   // readable OID (sec. 11.1), message-digest single-valued and a readable OCTET STRING (sec. 11.2),
   // signing-time when present single-valued and a readable Time (sec. 11.3).
@@ -317,7 +317,7 @@ function looksLikeSignedAttributes(bytes) {
     // deliberately not applied: this decoder caps values per attribute as a resource limit of its
     // own, and a limit this implementation chose is not a fact about what a signature can cover.
     // An external signer may sign a conforming set larger than that cap, and the stripped message
-    // presents those bytes as opaque content where the cap never applies -- refusing to recognize
+    // presents those bytes as opaque content where the cap never applies, so refusing to recognize
     // it because of a local limit would miss exactly the preimage the attack reuses.
     var n = (vs.children || []).length;
     if (n < 1) return false;
@@ -325,7 +325,7 @@ function looksLikeSignedAttributes(bytes) {
     // The two mandatory attributes are checked down to their VALUES, not just their type OIDs.
     // RFC 5652 sec. 11.1 makes content-type a single OBJECT IDENTIFIER and sec. 11.2 makes
     // message-digest a single OCTET STRING, so a set carrying those OIDs over an empty or
-    // wrongly-typed value CANNOT be the preimage of a real signature -- and refusing it would be a
+    // wrongly-typed value cannot be the preimage of a real signature, and refusing it would be a
     // false positive on content that merely resembles the shape. The detector has to stay a
     // necessary condition of the attack; anything broader costs a legitimate caller.
     var vals = vs.children || [];
@@ -344,17 +344,17 @@ function looksLikeSignedAttributes(bytes) {
   return sawContentType && sawMessageDigest;
 }
 
-// RFC 5652 sec. 5.3 / sec. 9.3 -- when a content-type attribute is present, it MUST
+// RFC 5652 sec. 5.3 / sec. 9.3: when a content-type attribute is present, it MUST
 // be single-valued (sec. 11.1) and its value MUST equal the eContentType (a
 // cross-field consistency both parsed here). Shared by SignedData signedAttrs,
-// AuthenticatedData authAttrs, and AuthEnvelopedData authAttrs -- the single-value
+// AuthenticatedData authAttrs, and AuthEnvelopedData authAttrs, where the single-value
 // rule holds even where content-type is not REQUIRED (RFC 5083), so an
 // expected-first-value-plus-extra set can never surface as ambiguous.
 function _assertContentTypeMatchesAttrs(attrs, eContentType) {
   for (var i = 0; i < attrs.length; i++) {
     if (attrs[i].type !== OID_CONTENT_TYPE) continue;
     if (attrs[i].values.length !== 1) throw NS.E("cms/bad-content-type-attr", "the content-type attribute must be single-valued (RFC 5652 sec. 11.1)");
-    // ContentType ::= OBJECT IDENTIFIER -- validate the value's full syntax (tag AND
+    // ContentType ::= OBJECT IDENTIFIER: validate the value's full syntax (tag and
     // minimal base-128 OID content) with the CMS typed verdict, so a malformed value
     // on a path that does not run _checkContentBindingAttrs (AuthEnvelopedData,
     // RFC 5083 sec. 2.1) surfaces cms/bad-content-type-attr, not the raw asn1/* error.
@@ -366,8 +366,8 @@ function _assertContentTypeMatchesAttrs(attrs, eContentType) {
 }
 
 // RFC 5652 sec. 5.3 -- an attribute set MUST NOT include multiple instances of the
-// same attribute type. AuthEnvelopedData authAttrs (RFC 5083 sec. 2.1) gets ONLY this
-// duplicate check -- NOT the content-type/message-digest presence rules (RFC 5652
+// same attribute type. AuthEnvelopedData authAttrs (RFC 5083 sec. 2.1) gets only this
+// duplicate check, and not the content-type/message-digest presence rules (RFC 5652
 // sec. 11.1/sec. 11.2 bind only signed-data and authenticated-data), so it must not reuse
 // _checkContentBindingAttrs, which would over-enforce.
 function _checkNoDuplicateAttrs(attrs) {
@@ -418,7 +418,7 @@ function _validateAeadParams(alg, macLen) {
   }
   var legal = kind === "gcm" ? AEAD_GCM_ICVLENS : AEAD_CCM_ICVLENS;
   if (!legal.has(icvLen)) throw NS.E("cms/bad-aead-params", "the AES-" + K + " aes-ICVlen " + icvLen + " is not an allowed value (RFC 5084)");
-  // X.690 sec. 11.5: a DEFAULT value MUST be omitted in DER -- an encoded ICVlen equal
+  // X.690 sec. 11.5: a DEFAULT value MUST be omitted in DER, so an encoded ICVlen equal
   // to the default 12 is non-canonical.
   if (icvEncoded && icvLen === 12) throw NS.E("cms/non-canonical-default", "the AEAD aes-ICVlen equal to the DEFAULT 12 MUST be omitted (X.690 sec. 11.5)");
   // RFC 5084 sec. 3.1/sec. 3.2: aes-ICVlen MUST match the AuthEnvelopedData mac length.
@@ -426,7 +426,7 @@ function _validateAeadParams(alg, macLen) {
   return { kind: kind, nonce: nonce, icvLen: icvLen };
 }
 
-// RFC 5652 sec. 5.3 / sec. 9.1 + RFC 5083 sec. 2.1 -- a signed / authenticated attribute SET
+// RFC 5652 sec. 5.3 / sec. 9.1 + RFC 5083 sec. 2.1: a signed / authenticated attribute SET
 // MUST be DER encoded even when the enclosing structure was decoded as BER (its
 // bytes feed the sec. 5.4 / sec. 9.2 re-tagged hash / MAC input, so a non-DER TLV makes
 // the surfaced raw bytes unusable for verification). Strictly re-decoding the
@@ -437,8 +437,8 @@ function _assertDerEncodedAttrs(node, code) {
   catch (e) { throw NS.E(code, "the attribute set must be DER encoded even inside a BER envelope (RFC 5652 sec. 5.3)", e); }
 }
 
-// A CertificateChoices / RevocationInfoChoice element, surfaced RAW (its DER +
-// outer tag) rather than recursively parsed -- the obsolete CHOICE alternatives
+// A CertificateChoices / RevocationInfoChoice element, surfaced raw (its DER +
+// outer tag) and never recursively parsed: the obsolete CHOICE alternatives
 // (extendedCertificate, attribute certs, otherRevocationInfo) never fail the
 // parse, and a caller re-parses a `certificate`/`CertificateList` element itself.
 function rawElement(item) {
@@ -515,7 +515,7 @@ var ISSUER_AND_SERIAL = schema.seq([
 });
 
 // SignerIdentifier ::= CHOICE { issuerAndSerialNumber IssuerAndSerialNumber,
-//   subjectKeyIdentifier [0] IMPLICIT OCTET STRING } (RFC 5652 sec. 5.3) -- the arm is
+//   subjectKeyIdentifier [0] IMPLICIT OCTET STRING } (RFC 5652 sec. 5.3), where the arm is
 // disambiguated by tag (universal SEQUENCE vs context [0]).
 var SIGNER_IDENTIFIER = schema.choice([
   { when: { tagClass: "universal", tagNumber: asn1.TAGS.SEQUENCE }, schema: ISSUER_AND_SERIAL },
@@ -526,10 +526,10 @@ var SIGNER_IDENTIFIER = schema.choice([
 //   signedAttrs [0] IMPLICIT OPTIONAL, signatureAlgorithm, signature OCTET STRING,
 //   unsignedAttrs [1] IMPLICIT OPTIONAL } (RFC 5652 sec. 5.3). signedAttrs/unsignedAttrs
 // are positional optionals (a required signatureAlgorithm sits between them, so
-// they cannot be a trailing block). ONE definition drives both consumers -- the
+// they cannot be a trailing block). One definition drives both consumers: the
 // signerInfos of a SignedData (mode "content") and a countersignature attribute
 // value (mode "countersig", RFC 5652 sec. 11.4: syntactically a SignerInfo whose
-// signedAttrs MUST carry message-digest and MUST NOT carry content-type) -- so
+// signedAttrs MUST carry message-digest and MUST NOT carry content-type), so
 // the two can never diverge structurally.
 function makeSignerInfo(mode) {
   return schema.seq([
@@ -574,7 +574,7 @@ function makeSignerInfo(mode) {
         // sec. 11.4 -- every countersignature value IS a SignerInfo (validated by
         // content, never accepted on the attribute type alone). Multiple
         // countersignature instances are explicitly permitted here, and a
-        // countersignature's own unsignedAttrs may nest further ones -- the
+        // countersignature's own unsignedAttrs may nest further ones, so the
         // recursion is bounded by the decoder's depth cap.
         for (var u = 0; u < unsignedAttrs.length; u++) {
           if (unsignedAttrs[u].type !== OID_COUNTERSIGNATURE) continue;
@@ -605,7 +605,7 @@ var COUNTERSIGNATURE_SIGNER_INFO = makeSignerInfo("countersig");
 // SignedData ::= SEQUENCE { version CMSVersion, digestAlgorithms SET OF,
 //   encapContentInfo, certificates [0] IMPLICIT OPTIONAL, crls [1] IMPLICIT
 //   OPTIONAL, signerInfos SET OF } (RFC 5652 sec. 5.1). digestAlgorithms and
-//   signerInfos are min:0 -- a degenerate certs-only SignedData carries neither.
+//   signerInfos are min:0, since a degenerate certs-only SignedData carries neither.
 var SIGNED_DATA = schema.seq([
   schema.field("version", SIGNED_DATA_VERSION),
   schema.field("digestAlgorithms", schema.setOf(ALGORITHM_IDENTIFIER, { min: 0, code: "cms/bad-digest-algorithms", what: "digestAlgorithms" })),
@@ -658,10 +658,10 @@ var T = asn1.TAGS;
 
 // EncryptedContentInfo ::= SEQUENCE { contentType OID, contentEncryptionAlgorithm
 //   AlgorithmIdentifier, encryptedContent [0] IMPLICIT OCTET STRING OPTIONAL } (RFC
-//   5652 sec. 6.1). encryptedContent is [0] IMPLICIT (context PRIMITIVE) -- its content
+//   5652 sec. 6.1). encryptedContent is [0] IMPLICIT (context primitive), so its content
 //   octets ARE the ciphertext directly, so it reads through implicitOctetString(0),
-//   NOT the [0] EXPLICIT shape ENCAP_CONTENT_INFO uses (which would double-strip a
-//   length header). The ciphertext + algorithm parameters are surfaced RAW.
+//   and not the [0] EXPLICIT shape ENCAP_CONTENT_INFO uses (which would double-strip a
+//   length header). The ciphertext + algorithm parameters are surfaced raw.
 var ENCRYPTED_CONTENT_INFO = schema.seq([
   schema.field("contentType", schema.oidLeaf()),
   schema.field("contentEncryptionAlgorithm", ALGORITHM_IDENTIFIER),
@@ -678,7 +678,7 @@ var ENCRYPTED_CONTENT_INFO = schema.seq([
 });
 
 // RecipientIdentifier ::= CHOICE { issuerAndSerialNumber, subjectKeyIdentifier [0]
-//   IMPLICIT OCTET STRING } (RFC 5652 sec. 6.2.1) -- structurally identical to
+//   IMPLICIT OCTET STRING } (RFC 5652 sec. 6.2.1), structurally identical to
 //   SignerIdentifier; reuse ISSUER_AND_SERIAL + the implicitOctetString(0) leaf.
 var RECIPIENT_IDENTIFIER = schema.choice([
   { when: { tagClass: "universal", tagNumber: T.SEQUENCE }, schema: ISSUER_AND_SERIAL },
@@ -712,7 +712,7 @@ var KEY_TRANS_RECIPIENT_INFO = schema.seq([
 });
 
 // OriginatorPublicKey ::= SEQUENCE { algorithm, publicKey BIT STRING } (RFC 5753
-//   sec. 3.1.1), reached as originatorKey [1] IMPLICIT -- SPKI-shaped but cannot reuse
+//   sec. 3.1.1), reached as originatorKey [1] IMPLICIT: SPKI-shaped but cannot reuse
 //   pkix.spki (which asserts a universal SEQUENCE), so assert:"constructed".
 var ORIGINATOR_PUBLIC_KEY = schema.seq([
   schema.field("algorithm", ALGORITHM_IDENTIFIER),
@@ -732,7 +732,7 @@ var ORIGINATOR_IDENTIFIER_OR_KEY = schema.choice([
 
 // RecipientKeyIdentifier (RFC 5652 sec. 6.2.2) and KEKIdentifier (sec. 6.2.3) are one
 //   shape -- { <keyId> OCTET STRING, date GeneralizedTime OPTIONAL, other
-//   OtherKeyAttribute OPTIONAL } -- differing only in the key-id field's name and
+//   OtherKeyAttribute OPTIONAL }, differing only in the key-id field's name and
 //   the enclosing tag form. One factory defines both so the OPTIONAL handling
 //   (date and the raw-surfaced OtherKeyAttribute) cannot diverge between them.
 function keyIdentifierSchema(keyIdName, assert, code, what) {
@@ -752,7 +752,7 @@ function keyIdentifierSchema(keyIdName, assert, code, what) {
   });
 }
 
-// Reached as rKeyId [0] IMPLICIT (a SEQUENCE -- constructed, unlike ktri's [0] leaf).
+// Reached as rKeyId [0] IMPLICIT (a SEQUENCE, constructed, unlike ktri's [0] leaf).
 var RECIPIENT_KEY_IDENTIFIER = keyIdentifierSchema("subjectKeyIdentifier",
   "constructed", "cms/bad-recipient-key-identifier", "RecipientKeyIdentifier");
 
@@ -945,7 +945,7 @@ var RECIPIENT_INFO = schema.choice([
 ], { code: "cms/bad-recipient-info", what: "RecipientInfo" });
 
 // OriginatorInfo ::= [0] IMPLICIT SEQUENCE { certs [0] IMPLICIT OPTIONAL, crls [1]
-//   IMPLICIT OPTIONAL } (RFC 5652 sec. 6.1). Members surfaced RAW (their outer tag feeds
+//   IMPLICIT OPTIONAL } (RFC 5652 sec. 6.1). Members surfaced raw (their outer tag feeds
 //   the version rule).
 var ORIGINATOR_INFO = schema.seq([
   schema.optional("certs", schema.implicitSetOf(0, schema.any(), { min: 1, code: "cms/bad-originator-certs", what: "certs" }), { tag: 0 }),
@@ -977,8 +977,8 @@ function _expectedEnvelopedDataVersion(originatorInfo, recipientInfos, hasUnprot
 }
 
 // RFC 5652 sec. 9.1 -- the exact AuthenticatedData CMSVersion, from originatorInfo's raw
-// cert/crl outer tags ONLY. Unlike EnvelopedData sec. 6.1, the recipient-info kinds do
-// NOT influence the version. IF originatorInfo present AND (other-cert [3] OR
+// cert/crl outer tags only. Unlike EnvelopedData sec. 6.1, the recipient-info kinds do
+// not influence the version. If originatorInfo is present and (other-cert [3] or
 // other-crl [1]) -> 3; ELSE IF originatorInfo present AND v2AttrCert [2] -> 1; ELSE 0.
 function _expectedAuthDataVersion(originatorInfo) {
   if (!originatorInfo) return 0;
@@ -991,7 +991,7 @@ function _expectedAuthDataVersion(originatorInfo) {
 // EnvelopedData ::= SEQUENCE { version, originatorInfo [0] IMPLICIT OPTIONAL,
 //   recipientInfos RecipientInfos (SET SIZE 1..MAX), encryptedContentInfo,
 //   unprotectedAttrs [1] IMPLICIT OPTIONAL } (RFC 5652 sec. 6.1). recipientInfos is
-//   min:1 (an empty SET is non-conformant -- the INVERSE of SignedData's degenerate
+//   min:1 (an empty SET is non-conformant, the inverse of SignedData's degenerate
 //   signerInfos).
 var ENVELOPED_DATA = schema.seq([
   schema.field("version", ENVELOPED_DATA_VERSION),
@@ -1021,7 +1021,7 @@ var ENVELOPED_DATA = schema.seq([
 });
 
 // EncryptedData ::= SEQUENCE { version, encryptedContentInfo, unprotectedAttrs [1]
-//   IMPLICIT OPTIONAL } (RFC 5652 sec. 8) -- no recipients, no originatorInfo; the CEK is
+//   IMPLICIT OPTIONAL } (RFC 5652 sec. 8): no recipients, no originatorInfo; the CEK is
 //   distributed out of band. version is 0, or 2 iff unprotectedAttrs are present.
 var ENCRYPTED_DATA = schema.seq([
   schema.field("version", ENCRYPTED_DATA_VERSION),
@@ -1150,7 +1150,7 @@ var AUTH_ENVELOPED_DATA = schema.seq([
       // sec. 2.2 AAD is the re-tagged DER SET). No content-type/message-digest
       // presence rules bind here (sec. 11.1/sec. 11.2 name signed-data and
       // authenticated-data; sec. 2.1 says message-digest SHOULD NOT appear), so only
-      // the duplicate rule, the sec. 11 placement rows, and -- when a content-type
+      // the duplicate rule, the sec. 11 placement rows, and, when a content-type
       // attribute IS present -- the value == contentType coherence apply.
       _assertDerEncodedAttrs(m.fields.authAttrs.node, "cms/bad-auth-attrs");
       authAttrs = m.fields.authAttrs.value.items.map(function (it) { return it.value.result; });
@@ -1265,8 +1265,8 @@ var CONTENT_INFO = schema.seq([
  * `{ type: "ori", oriType, oriValue, kemri }` with the parsed KEMRecipientInfo in
  * `kemri`. Every result additionally carries `contentType` (the dotted OID) and
  * `contentTypeName` (its registry name) naming which of the five shapes was
- * dispatched. Raw byte ranges an external verifier hashes -- `eContent`,
- * `signature`, `signedAttrsBytes`, `authAttrsBytes`, `mac` -- are surfaced
+ * dispatched. The raw byte ranges an external verifier hashes (`eContent`,
+ * `signature`, `signedAttrsBytes`, `authAttrsBytes`, `mac`) are surfaced
  * exactly as on the wire. The remaining PKCS#7 types throw `cms/unsupported-content-type`; an
  * unrecognized OID throws `cms/unknown-content-type`; a malformed structure
  * throws a typed `CmsError` (`cms/*`) and a leaf-level codec fault surfaces as

package/lib/schema-crl.js

@@ -19,7 +19,7 @@
  *   rules, and the raw `tbsCertList` bytes are returned for signature checking.
  *
  * @card
- *   Parse DER / PEM X.509 CRLs into structured, validated fields -- revoked
+ *   Parse DER / PEM X.509 CRLs into structured, validated fields: revoked
  *   serials with real-`Date` revocation times, named extensions, fail-closed.
  */
 
@@ -34,14 +34,14 @@ var PemError = frameworkError.PemError;
 var TAGS = asn1.TAGS;
 
 
-// CRLReason ::= ENUMERATED (RFC 5280 sec. 5.3.1) -- value 7 is unused/reserved.
+// CRLReason ::= ENUMERATED (RFC 5280 sec. 5.3.1). Value 7 is unused/reserved.
 // The legal set lives once in pkix.CRL_REASON_NAMES (shared with the OCSP
 // RevokedInfo decoder, which surfaces the name; this decoder the numeric code).
 var CRL_REASONS = pkix.CRL_REASON_NAMES;
 
-// Extension-value decoding is keyed off the STABLE dotted OID (resolved once at
-// load from the canonical name), not the mutable display name -- a caller's
-// pki.oid.register() display override must not change parse behaviour.
+// Extension-value decoding is keyed off the stable dotted OID (resolved once at
+// load from the canonical name) and not the mutable display name, so a caller's
+// pki.oid.register() display override cannot change parse behaviour.
 var OID_CRL_NUMBER = oid.byName("cRLNumber");
 var OID_REASON_CODE = oid.byName("reasonCode");
 var OID_INVALIDITY_DATE = oid.byName("invalidityDate");
@@ -58,9 +58,9 @@ var EXTENSIONS = pkix.extensions(NS);
 // UTCTime). invalidityDate stays GeneralizedTime-only (sec. 5.3.2, decodeExt).
 var TIME = pkix.time(NS);
 
-// CRL Version ::= INTEGER { v1(0), v2(1) } -- a BARE INTEGER (not [0] EXPLICIT).
+// CRL Version ::= INTEGER { v1(0), v2(1) }, a bare INTEGER (not [0] EXPLICIT).
 // A CRL is at most v2; reject an explicit v1 (DER forbids the default) and any
-// value >= 2. Do NOT reuse the certificate readVersion (it maps 2 -> v3).
+// value >= 2. Do not reuse the certificate readVersion (it maps 2 -> v3).
 var CRL_VERSION = pkix.versionReader(NS, { "1": 2 });
 
 // The three cheap, high-value CRL extension values are decoded from their raw

package/lib/schema-crmf.js

@@ -24,13 +24,13 @@
  *   when supplied, MUST be 2 (RFC 4211 sec. 5); certReqId is an unbounded signed
  *   INTEGER (the RFC 9483 `-1` sentinel is legal). The `CertRequest` byte range
  *   the proof-of-possession signature covers, and each `poposkInput`, are surfaced
- *   RAW for a downstream verifier; registration controls / info values and the
- *   keyEncipherment / keyAgreement POP arms are surfaced RAW rather than recursed.
+ *   raw for a downstream verifier; registration controls / info values and the
+ *   keyEncipherment / keyAgreement POP arms are surfaced raw and never recursed.
  *   DER-only, fail-closed.
  *
  * @card
  *   Parse DER / PEM RFC 4211 CertReqMessages into requested-certificate templates,
- *   proof-of-possession, and registration controls -- dual-accepted names, raw
+ *   proof-of-possession, and registration controls: dual-accepted names, raw
  *   verifier inputs, fail-closed.
  */
 
@@ -102,7 +102,7 @@ var OPTIONAL_VALIDITY = schema.seq([
 });
 
 // ---- ProofOfPossession (sec. 4) ------------------------------------------
-// raVerified [0] NULL -- the RA has already verified POP out of band.
+// raVerified [0] NULL: the RA has already verified POP out of band.
 var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
   try { asn1.read.nullImplicit(n, 0); }
   catch (e) { throw ctx.E("crmf/bad-popo", "raVerified [0] must be an IMPLICIT NULL", e); }
@@ -110,9 +110,9 @@ var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
 });
 
 // When poposkInput is present the POP signature is over the DER of the
-// POPOSigningKeyInput VALUE (RFC 4211 sec. 4.1), which is a SEQUENCE -- but on the wire
+// POPOSigningKeyInput value (RFC 4211 sec. 4.1), which is a SEQUENCE. But on the wire
 // poposkInput is an IMPLICIT [0] field, so its bytes lead with the context tag
-// (0xA0) rather than the SEQUENCE tag a verifier hashes. `asn1.sequenceTlv` recovers
+// (0xA0) and not the SEQUENCE tag a verifier hashes. `asn1.sequenceTlv` recovers
 // the SEQUENCE-tagged signed region from the field's content; `signedBytes` is that
 // region and `bytes` keeps the raw wire [0] TLV, so a verifier can use either
 // encoding its peer produced.
@@ -120,7 +120,7 @@ var POPO_RAVERIFIED = schema.decode(function (n, ctx) {
 // POPOSigningKeyInput ::= SEQUENCE { authInfo CHOICE { sender [0] GeneralName,
 // publicKeyMAC PKMACValue }, publicKey SubjectPublicKeyInfo } (sec. 4.1). Structurally
 // validated (not deferred raw), so an empty or malformed poposkInput fails closed
-// rather than surfacing a signed region that was never a well-formed POP input.
+// and never surfaces a signed region that was not a well-formed POP input.
 // PKMACValue ::= SEQUENCE { algId AlgorithmIdentifier, value BIT STRING }. The
 // MAC value is octet-string algorithm output handed to an external verifier;
 // with no in-tree POP verify layer, octet alignment is enforced at parse.
@@ -130,7 +130,7 @@ var PKMAC_VALUE = schema.seq([
 ], {
   assert: "sequence", arity: { exact: 2 }, code: "crmf/bad-popo", what: "PKMACValue",
   build: function (m, ctx) {
-    // The parsed BIT STRING structure { unusedBits, bytes } -- a structural
+    // The parsed BIT STRING structure { unusedBits, bytes }, a structural
     // octet-alignment check on the unused-bit COUNT, not a comparison of the
     // MAC secret (there is no in-tree POP verify), so no timing oracle exists.
     var macBitString = m.fields.value.value;
@@ -142,7 +142,7 @@ var PKMAC_VALUE = schema.seq([
 });
 
 // authInfo CHOICE: sender [0] GeneralName is EXPLICIT (GeneralName is itself a
-// CHOICE); publicKeyMAC is a bare PKMACValue SEQUENCE -- disjoint by tag class.
+// CHOICE); publicKeyMAC is a bare PKMACValue SEQUENCE, disjoint by tag class.
 var POPOSK_AUTH_INFO = schema.choice([
   { when: { tagClass: "context", tagNumber: 0 }, schema: schema.explicit(0, pkix.generalName(NS, { code: "crmf/bad-popo" }), { code: "crmf/bad-popo" }) },
   { when: { tagClass: "universal", tagNumber: TAGS.SEQUENCE }, schema: PKMAC_VALUE },
@@ -154,7 +154,7 @@ var POPOSK_INPUT = schema.seq([
 ], { assert: "implicit", implicitTag: 0, arity: { exact: 2 }, code: "crmf/bad-popo", what: "POPOSigningKeyInput" });
 
 // POPOSigningKey ::= SEQUENCE { poposkInput [0] POPOSigningKeyInput OPTIONAL,
-// algorithmIdentifier AlgorithmIdentifier, signature BIT STRING } -- IMPLICIT [1].
+// algorithmIdentifier AlgorithmIdentifier, signature BIT STRING }, IMPLICIT [1].
 var POPO_SIGNING_KEY = schema.seq([
   schema.optional("poposkInput", schema.decode(function (n, ctx) {
     // Validate the full POPOSigningKeyInput structure fail-closed, then surface the
@@ -187,9 +187,9 @@ var POPO_SIGNING_KEY = schema.seq([
 // keyEncipherment [2] / keyAgreement [3] POPOPrivKey (sec. 4). POPOPrivKey is a
 // 5-arm CHOICE { thisMessage [0], subsequentMessage [1], dhMAC [2], agreeMAC [3],
 // encryptedKey [4] }, so X.680 sec. 31.2.7 forces the outer [2]/[3] tag to be EXPLICIT
-// (a CHOICE has no single tag to replace). Validate that shell -- a constructed
-// wrapper around exactly one inner context [0]..[4] alternative -- before surfacing
-// the arm RAW, so a primitive / empty / mis-tagged node is rejected rather than
+// (a CHOICE has no single tag to replace). Validate that shell, a constructed
+// wrapper around exactly one inner context [0]..[4] alternative, before surfacing
+// the arm raw, so a primitive, empty or mis-tagged node is rejected and never
 // reported to a verifier as a well-formed POP. The inner alternative's own value
 // (incl. the encryptedKey [4] EnvelopedData) stays deferred to the verify layer.
 // POPOPrivKey ::= CHOICE { thisMessage [0] BIT STRING (deprecated), subsequentMessage
@@ -240,7 +240,7 @@ function popoPrivKey(type) {
       try { schema.embeddedDer(PKMAC_VALUE, asn1.sequenceTlv(inner), NS, { code: "crmf/bad-popo", what: "agreeMAC [3] PKMACValue" }); }
       catch (e) { throw ctx.E("crmf/bad-popo", "agreeMAC [3] must be a PKMACValue SEQUENCE { algId, BIT STRING } (RFC 4211 sec. 4.2)", e); }
     }
-    // encryptedKey [4] EnvelopedData -- validate the CMS structure fail-closed by
+    // encryptedKey [4] EnvelopedData: validate the CMS structure fail-closed by
     // composing the shared EnvelopedData decoder (retag the IMPLICIT [4] to the
     // universal SEQUENCE it decodes as). The EncKeyWithID identity check lives inside
     // the ENCRYPTED content, so it stays a verify-layer concern.
@@ -248,12 +248,12 @@ function popoPrivKey(type) {
       var env;
       try { env = cms.walkEnvelopedData(asn1.decode(asn1.sequenceTlv(inner))); }
       catch (e) { throw ctx.E("crmf/bad-popo", "encryptedKey [4] must be a well-formed EnvelopedData (RFC 4211 sec. 4.2, RFC 5652 sec. 6.1)", e); }
-      // RFC 4211 sec. 4.2 -- the enveloped content type MUST be id-ct-encKeyWithID (the
+      // RFC 4211 sec. 4.2: the enveloped content type MUST be id-ct-encKeyWithID (the
       // ContentType OID is in the clear even though the content itself is encrypted).
       if (env.encryptedContentInfo.contentType !== oid.byName("encKeyWithID")) {
         throw ctx.E("crmf/bad-popo", "encryptedKey [4] EnvelopedData content type MUST be id-ct-encKeyWithID (RFC 4211 sec. 4.2)");
       }
-      // The encrypted key material MUST be present -- CMS allows a detached
+      // The encrypted key material MUST be present. CMS allows a detached
       // EnvelopedData (encryptedContent OPTIONAL), but a POP with no key to verify
       // or archive is meaningless. The shared CMS assert rejects a null OR
       // zero-length attached ciphertext (the rule the EST / PKCS#12 siblings hold).
@@ -275,7 +275,7 @@ var PROOF_OF_POSSESSION = schema.choice([
 
 // ---- Controls / regInfo (sec. 5, sec. 6, sec. 7) ---------------------------------
 // AttributeTypeAndValue ::= SEQUENCE { type OBJECT IDENTIFIER, value ANY DEFINED BY
-// type }. The list is decoded; each value stays RAW (the per-OID value semantics
+// type }. The list is decoded; each value stays raw (the per-OID value semantics
 // are deferred). Shared shape for both controls and regInfo.
 var CONTROL = schema.seq([
   schema.field("type", schema.oidLeaf()),
@@ -293,10 +293,10 @@ var CONTROLS = schema.seqOf(CONTROL, { assert: "sequence", min: 1, code: "crmf/b
 // regInfo ::= SEQUENCE SIZE(1..MAX) OF AttributeTypeAndValue (sec. 7).
 var REG_INFO = schema.seqOf(CONTROL, { assert: "sequence", min: 1, code: "crmf/bad-reg-info", what: "regInfo", build: mapControls });
 
-// ---- CertTemplate (sec. 5) -- the IMPLICIT-TAGS core ----------------------
+// ---- CertTemplate (sec. 5), the IMPLICIT-TAGS core ------------------------
 // CertTemplate ::= SEQUENCE { version [0], serialNumber [1], signingAlg [2],
 // issuer [3] Name, validity [4] OptionalValidity, subject [5] Name, publicKey [6]
-// SubjectPublicKeyInfo, issuerUID [7], subjectUID [8], extensions [9] } -- every
+// SubjectPublicKeyInfo, issuerUID [7], subjectUID [8], extensions [9] }, where every
 // field IMPLICIT and OPTIONAL, so the whole body is one ascending [0..9] trailing
 // run. issuer/subject Name and the [4] validity times are the CHOICE exceptions.
 var CERT_TEMPLATE = schema.seq([
@@ -323,9 +323,9 @@ var CERT_TEMPLATE = schema.seq([
     // existing certificate -- serialNumber and issuer present -- inside a CMP
     // RevDetails (RFC 9810 sec. 5.3.9). Every field is surfaced so both the request
     // omission check and the revocation consumer read them off one result.
-    // The ONE profile override: RFC 9810 Appendix D.6 profiles the CMP
+    // The single profile override: RFC 9810 Appendix D.6 profiles the CMP
     // cross-certification (ccr) template as "version v1 or v3", so the caller
-    // opts in to v1 (0) via ctx.allowV1Version -- the same base-section-vs-
+    // opts in to v1 (0) via ctx.allowV1Version, the same base-section-vs-
     // profile-appendix override mechanism as the signingAlg relaxation below.
     if (f.version.present && f.version.value !== 2n &&
         !(ctx.allowV1Version && f.version.value === 0n)) {
@@ -365,7 +365,7 @@ var CERT_REQUEST = schema.seq([
     // hazard), so a request template that sets any of them is rejected
     // fail-closed. The check lives HERE, not in CERT_TEMPLATE, because the same
     // structure legitimately carries serialNumber/issuer in a CMP RevDetails.
-    // A cross-certification request (ccr) is the ONE exception: RFC 9810 Appendix
+    // A cross-certification request (ccr) is the one exception: RFC 9810 Appendix
     // D.6 profiles its template with signingAlg PRESENT (the requesting CA states
     // the algorithm it wants the cross-certificate signed with), so the caller
     // relaxes that single field via ctx.allowSigningAlg; serialNumber and the UID
@@ -406,7 +406,7 @@ var CERT_REQ_MSG = schema.seq([
     // to sign / MAC over, and a verifier would be bound to the wrong identity/key.
     var complete = certReq.certTemplate.subject !== null && certReq.certTemplate.publicKey !== null;
     // RFC 4211 sec. 4.1 -- for a signature POP, poposkInput's presence is fixed by the
-    // CertTemplate: it MUST be omitted when the template carries BOTH subject and
+    // CertTemplate: it MUST be omitted when the template carries both subject and
     // publicKey (the signature is then over the DER of the CertRequest), and MUST be
     // present otherwise.
     if (popo && popo.type === "signature") {
@@ -438,7 +438,7 @@ var CERT_REQ_MSG = schema.seq([
   },
 });
 
-// CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (sec. 3) -- an empty sequence
+// CertReqMessages ::= SEQUENCE SIZE(1..MAX) OF CertReqMsg (sec. 3), where an empty sequence
 // is malformed. The top-level reject code predates the
 // `<prefix>/not-a-<structure>` convention and stays frozen on the public
 // error-code surface.
@@ -461,16 +461,16 @@ var CERT_REQ_MESSAGES = schema.seqOf(CERT_REQ_MSG, {
  * `{ messages: [ { certReq, popo, regInfo } ] }`. Each `certReq` is
  * `{ certReqId, certReqIdHex, certTemplate, controls, certReqBytes }`, and
  * `certTemplate` carries the requestable certificate fields (`version`, `issuer`,
- * `validity`, `subject`, `publicKey`, `extensions` -- each `null` when absent). The
+ * `validity`, `subject`, `publicKey`, `extensions`, each `null` when absent). The
  * CA-assigned / deprecated fields RFC 4211 sec. 5 requires a request to omit
  * (`serialNumber`, `signingAlg`, `issuerUID`, `subjectUID`) are rejected, not
  * surfaced. `popo` is
  * `null`, `{ type: "raVerified" }`, `{ type: "signature", poposkInput,
  * algorithmIdentifier, signature }`, or `{ type: "keyEncipherment" |
  * "keyAgreement", method, bytes }` (where `method` is the POPOPrivKey alternative --
- * `thisMessage` / `subsequentMessage` / `dhMAC` / `agreeMAC` / `encryptedKey` -- each
+ * `thisMessage` / `subsequentMessage` / `dhMAC` / `agreeMAC` / `encryptedKey`, each
  * structurally validated, the `encryptedKey` EnvelopedData included). When present, `poposkInput` is
- * `{ bytes, signedBytes, publicKey }` -- `bytes` is the raw wire `[0]` TLV,
+ * `{ bytes, signedBytes, publicKey }`, where `bytes` is the raw wire `[0]` TLV,
  * `signedBytes` is the `POPOSigningKeyInput` re-tagged to the `SEQUENCE` DER the
  * signature actually covers, and `publicKey` is the canonical
  * `SubjectPublicKeyInfo` DER the RFC 4211 sec. 4.1 template-match check compares
@@ -503,7 +503,7 @@ var parse = pkix.makeParser({
  * @related    pki.schema.crmf.parse
  *
  * Extract the DER bytes from a PEM block (RFC 4211 registers no RFC 7468 label, so
- * the first block is taken unless `label` is given -- CRMF rides inside CMP / EST as
+ * the first block is taken unless `label` is given; CRMF rides inside CMP / EST as
  * DER in practice). Throws `PemError` on a missing envelope or a non-base64 body.
  *
  * @example

package/lib/schema-csr.js

@@ -25,7 +25,7 @@
  *   certificate/CRL guards.
  *
  * @card
- *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields -- subject DN,
+ *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields: subject DN,
  *   public key, requested attributes, signature, fail-closed.
  */
 
@@ -45,14 +45,14 @@ var NS = pkix.makeNS("csr", CsrError, oid);
 var NAME = pkix.name(NS);
 var SPKI = pkix.spki(NS);
 
-// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 sec. 4.1). A BARE
-// mandatory INTEGER whose ONLY legal value is 0 -- the inverse of the cert/CRL
+// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 sec. 4.1). A bare
+// mandatory INTEGER whose one legal value is 0, the inverse of the cert/CRL
 // readers, which reject 0 as the DER-forbidden default. Surface v1 as 1. A
 // cert-shaped [0] EXPLICIT wrapper at this position makes asn1.read.integer throw
 // asn1/* (fail-closed).
 var CSR_VERSION = pkix.versionReader(NS, { "0": 1 });
 
-// Attribute ::= SEQUENCE { type OID, values SET OF ANY } -- the shared pkix factory
+// Attribute ::= SEQUENCE { type OID, values SET OF ANY }, the shared pkix factory
 // under the csr NS (values raw DER, SET SIZE(1..MAX), no uniqueness). The same
 // factory serves the PKCS#8 private-key attributes.
 var ATTRIBUTE = pkix.attribute(NS);
@@ -76,8 +76,8 @@ var DIRECTORY_STRING_TAGS = [
 var RECOGNIZED_ATTRIBUTE_VALUE = {};
 RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("extensionRequest")] = function (node, ctx) {
   // Surface the requested extensions decoded (same {oid,name,critical,value}
-  // shape as a certificate's extensions) so a CA pipeline -- and the EST
-  // re-enroll guard -- reads them off the attribute instead of re-walking the
+  // shape as a certificate's extensions) so a CA pipeline, and the EST
+  // re-enroll guard, read them off the attribute instead of re-walking the
   // raw Extensions bytes. Returned as an enrichment merged onto the attribute.
   try { return { extensions: schema.walk(EXTENSIONS, node, ctx).result }; }
   catch (e) {
@@ -101,7 +101,7 @@ RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("challengePassword")] = function (node, ct
 //   subjectPKInfo SubjectPublicKeyInfo, attributes [0] IMPLICIT SET OF Attribute }.
 // attributes is a REQUIRED field (a CRI omitting [0] is a missing-required-field
 // fault, not silently accepted) modeled as an IMPLICIT [0] SET OF with min:0 (an
-// empty attributes SET is legal). subject MAY be empty -- no non-empty-DN guard.
+// empty attributes SET is legal). subject MAY be empty, so there is no non-empty-DN guard.
 var CERTIFICATION_REQUEST_INFO = schema.seq([
   schema.field("version", CSR_VERSION),
   schema.field("subject", NAME),
@@ -134,11 +134,11 @@ var CERTIFICATION_REQUEST_INFO = schema.seq([
 });
 
 // CertificationRequest ::= SEQUENCE { certificationRequestInfo, signatureAlgorithm,
-//   signature BIT STRING } -- the shared SIGNED envelope. DIVERGENCE from the
-// cert/CRL builders: OMIT the outer-vs-inner signatureAlgorithm agreement check
-// (the CRI has no inner signature AlgorithmIdentifier) and the non-empty-subject
-// guard (a CSR subject MAY be empty). The omission is structural -- this build
-// simply never references the agreement bytes.
+//   signature BIT STRING }, the shared SIGNED envelope. It diverges from the
+// cert/CRL builders by omitting the outer-vs-inner signatureAlgorithm agreement
+// check (the CRI has no inner signature AlgorithmIdentifier) and the
+// non-empty-subject guard (a CSR subject MAY be empty). The omission is
+// structural: this build simply never references the agreement bytes.
 var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO, {
   code: "csr/not-a-certification-request", what: "CertificationRequest",
   build: function (e) {