@blamejs/pki 0.5.7 → 0.5.8

package/lib/schema-pkix.js

@@ -10,7 +10,7 @@
 // returns an asn1-schema that walks the corresponding ASN.1 structure and emits
 // the caller's own <prefix>/* error codes. x509.js, crl.js, and future CMS/CSR
 // parsers compose these so AlgorithmIdentifier / Name / Extension are defined
-// once, not re-derived per format. This module is internal infrastructure -- the
+// once, not re-derived per format. This module is internal infrastructure: the
 // operator-facing surface is the parsers that consume it.
 
 var asn1 = require("./asn1-der");
@@ -36,7 +36,7 @@ var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
 // lenient Buffer.from would otherwise let several distinct PEM texts alias one
 // DER (PEM-layer malleability) and silently drop trailing content bits.
 function pemDecode(text, label, PemError) {
-  // guard.text.decode caps the raw byte length BEFORE the latin1 string copy:
+  // guard.text.decode caps the raw byte length before the latin1 string copy:
   // converting first would allocate a full-size string for input the cap is
   // about to reject, and a buffer above Node's max string length would escape as
   // an untyped ERR_STRING_TOO_LONG instead of pem/too-large.
@@ -51,7 +51,7 @@ function pemDecode(text, label, PemError) {
   return guard.encoding.base64(b64, null, function (c, msg) { return new PemError(c, msg); }, "pem/bad-base64", "PEM base64 body");
 }
 
-// pemDecodeAll(text, label, PemError): decode EVERY PEM block under the STRICT
+// pemDecodeAll(text, label, PemError): decode every PEM block under the strict
 // RFC 7468 profile for application/pem-certificate-chain (RFC 8555 sec. 9.1) --
 // each block must carry `label` (default CERTIFICATE), explanatory text MUST NOT
 // appear before/between/after blocks (errata 5983: certchain = stricttextualmsg
@@ -81,13 +81,13 @@ function pemDecodeAll(text, label, PemError) {
 // alphanumeric words separated by single spaces, a subset of the RFC 7468
 // sec. 3 label grammar). Anything else (lowercase, a leading/trailing space,
 // an embedded "-----" or newline) would emit armor pemDecode itself rejects
-// or corrupt the armor grammar -- a config-time authoring fault, thrown here.
+// or corrupt the armor grammar: a config-time authoring fault, thrown here.
 function pemEncode(der, label, PemError) {
   if (typeof label !== "string" || !/^[A-Z0-9]+( [A-Z0-9]+)*$/.test(label)) {
     throw new PemError("pem/bad-label", "pemEncode requires an uppercase A-Z0-9 label with single spaces");
   }
   // Re-view through the byte guard: a string input would silently utf8-armor into
-  // a bogus PEM, and a detached-backed Buffer would armor an empty body -- both
+  // a bogus PEM, and a detached-backed Buffer would armor an empty body; both
   // fail closed (a Uint8Array / Buffer of real DER re-views cleanly).
   var buf = guard.bytes.view(der, PemError, "pem/bad-input", "pemEncode DER input");
   var b64 = buf.toString("base64").replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
@@ -101,7 +101,7 @@ function coerceToDer(input, opts) {
   if (typeof input === "string") return pemDecode(input, opts.pemLabel, opts.PemError);
   if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
     // Route the DER Buffer / Uint8Array through the shared byte guard so a
-    // detached backing store fails closed here for EVERY format that composes
+    // detached backing store fails closed here for every format that composes
     // this boundary (x509/crl/csr/pkcs8/cms/pkcs12), not per-format.
     var buf = guard.bytes.view(input, opts.ErrorClass, opts.prefix + "/bad-input", "parse");
     return _isPemArmor(buf) ? pemDecode(buf, opts.pemLabel, opts.PemError) : buf;
@@ -109,11 +109,11 @@ function coerceToDer(input, opts) {
   throw new opts.ErrorClass(opts.prefix + "/bad-input", "parse expects a DER Buffer or a PEM string");
 }
 
-// Does a Buffer carry PEM armor (a .pem read with fs.readFileSync) rather than
+// Does a Buffer carry PEM armor (a .pem read with fs.readFileSync) instead of
 // raw DER? It does iff "-----BEGIN" appears and everything before it is TEXT
-// (UTF-8 BOM / whitespace / RFC 7468 explanatory preamble). DER is binary -- its
-// leading tag+length bytes are non-printable -- so a non-SEQUENCE DER (a bare
-// SET / INTEGER) is NOT misrouted here; it decodes and fails closed structurally.
+// (UTF-8 BOM / whitespace / RFC 7468 explanatory preamble). DER is binary and its
+// leading tag+length bytes are non-printable, so a non-SEQUENCE DER (a bare
+// SET / INTEGER) is not misrouted here; it decodes and fails closed structurally.
 function _isPemArmor(buf) {
   var head = buf.slice(0, 4096).toString("latin1");
   var idx = head.indexOf("-----BEGIN");
@@ -130,9 +130,9 @@ function _isPemArmor(buf) {
 // Decode the DER root, wrapping a codec fault in the caller's <prefix>/bad-der.
 function decodeRoot(der, opts) {
   // A format whose wire encoding is normatively BER (RFC 7292 PKCS#12) opts
-  // in to the codec's ber mode for the WHOLE decode. BER-vs-DER divergence is
-  // not always a decode-time throw -- a definite-length constructed IMPLICIT
-  // OCTET STRING decodes strictly and only diverges at the typed reader -- so
+  // in to the codec's ber mode for the whole decode. BER-vs-DER divergence is
+  // not always a decode-time throw: a definite-length constructed IMPLICIT
+  // OCTET STRING decodes strictly and only diverges at the typed reader, so
   // a strict-first-retry-on-throw boundary would miss legal BER shapes. A
   // strict-DER input decodes identically under the ber mode, every other
   // strictness verdict included.
@@ -150,7 +150,7 @@ function runParse(input, opts) {
 }
 
 // Distinguished-name attribute short labels (RFC 4514 sec. 3 + common use).
-// RFC 4514 short names for the DN string representation -- the single source is
+// RFC 4514 short names for the DN string representation; the single source is
 // pki.C.NAMES.DN_SHORT (shared with the human-readable renderer so the two can't drift).
 var DN_SHORT = constants.NAMES.DN_SHORT;
 
@@ -158,7 +158,7 @@ var DN_SHORT = constants.NAMES.DN_SHORT;
 // The error/OID namespace every format module walks its schema under:
 // { prefix, E:(code,message,cause)=>new ErrorClass(...), oid }. Factored so a
 // format declares it in one line instead of repeating the error-constructor
-// closure (a caller that never passes a cause is unaffected -- withCause ignores
+// closure (a caller that never passes a cause is unaffected, since withCause ignores
 // an undefined third arg).
 function makeNS(prefix, ErrorClass, oidModule) {
   return { prefix: prefix, E: function (code, message, cause) { return new ErrorClass(code, message, cause); }, oid: oidModule };
@@ -166,9 +166,9 @@ function makeNS(prefix, ErrorClass, oidModule) {
 
 // A bounded universal-INTEGER version reader. `accept` maps each legal wire value
 // (as a decimal string) to its surfaced version number; any other value is a
-// <prefix>/bad-version fault. The one genuine per-format divergence -- the cert
+// <prefix>/bad-version fault. The one genuine per-format divergence, the cert
 // rejects 0 and maps 1->2/2->3, a CRL accepts only 1->2, a CSR only 0->1, a PKCS#8
-// 0->1/1->2 -- is expressed purely as the accept map (RFC 5280 sec. 4.1.2.1 / sec. 5.1.2.1,
+// 0->1/1->2, is expressed purely as the accept map (RFC 5280 sec. 4.1.2.1 / sec. 5.1.2.1,
 // RFC 2986 sec. 4.1, RFC 5958 sec. 2). read.integer is strict, so an ENUMERATED-tagged
 // version is rejected at the leaf (asn1/*).
 function versionReader(ns, accept) {
@@ -185,11 +185,11 @@ function versionReader(ns, accept) {
 // universal SEQUENCE, byte-identical to every existing caller.
 //
 // Parameter-rule tiering: only the params-MUST-BE-ABSENT families (ML-DSA,
-// SLH-DSA, the Edwards/Montgomery curves -- new registrations with no legacy
+// SLH-DSA, the Edwards/Montgomery curves), new registrations with no legacy
 // corpus) are enforced at parse time, in the build below. The CLASSICAL
 // per-OID rules (RSA parameters MUST be NULL, RFC 3279 sec. 2.2.1/2.3.1;
 // ecdsa-with-SHA2 parameters MUST be omitted, RFC 5758 sec. 3.2) are
-// deliberately NOT parse-time rejects: a long tail of deployed certificates
+// deliberately not parse-time rejects: a long tail of deployed certificates
 // omits the RSA NULL, so the parse tier stays interop-lenient for those
 // families and the strict classical check runs on the signature-verification
 // path (path-validate's signature-algorithm registry), where the verdict
@@ -205,11 +205,11 @@ function algorithmIdentifier(ns, opts) {
     arity: { min: 1 }, code: ns.prefix + "/bad-algorithm-identifier", what: "AlgorithmIdentifier",
     build: function (m, ctx) {
       var dotted = m.fields.algorithm.value;
-      // For every algorithm the registry marks parameters-absent -- the PQC
+      // The registry marks several algorithm families parameters-absent: the PQC
       // signature families (ML-DSA RFC 9881, SLH-DSA RFC 9909/9814), the
       // Edwards/Montgomery curves (RFC 8410), ML-KEM (RFC 9936), and the HKDF
-      // identifiers (RFC 8619) -- the `parameters` field MUST be absent: no
-      // explicit NULL, no bytes. Enforced ONCE here so every consumer of the
+      // identifiers (RFC 8619). For all of them the `parameters` field MUST be
+      // absent: no explicit NULL, no bytes. Enforced ONCE here so every consumer of the
       // shared AlgorithmIdentifier inherits the rule; the guard-parity bug
       // class is structurally impossible.
       if (m.fields.parameters.present && ctx.oid.paramsMustBeAbsent(dotted)) {
@@ -221,7 +221,7 @@ function algorithmIdentifier(ns, opts) {
   });
 }
 
-// pbkdf2Params(ns): PBKDF2-params (RFC 8018 sec. 5.2) constrained to the RFC 9579 PBMAC1 profile -- the
+// pbkdf2Params(ns): PBKDF2-params (RFC 8018 sec. 5.2) constrained to the RFC 9579 PBMAC1 profile, where the
 // salt uses the OCTET STRING choice and keyLength MUST be present (a MacData / PKIProtection consumer
 // cannot infer the derived MAC key size, RFC 9579 sec. 4.b/5). Shared by the PKCS#12 MacData reader and
 // the CMP PBMAC1 protection reader: one ns-parameterized decoder so neither format re-derives the shape.
@@ -238,26 +238,28 @@ function pbkdf2Params(ns) {
       if (!m.fields.keyLength.present) {
         throw ctx.E(ctx.prefix + "/bad-mac-data", "PBMAC1 PBKDF2-params must carry keyLength (RFC 9579 sec. 5)");
       }
-      // guard.range.positiveInt31 bounds + narrows each counter atomically -- a value past the bound
+      // guard.range.positiveInt31 bounds + narrows each counter atomically, so a value past the bound
       // would round silently and hand a verifier wrong inputs.
       var iterationCount = guard.range.positiveInt31(m.fields.iterationCount.value, ctx.E, ctx.prefix + "/bad-mac-data", "PBKDF2 iterationCount");
       var keyLength = guard.range.positiveInt31(m.fields.keyLength.value, ctx.E, ctx.prefix + "/bad-mac-data", "PBKDF2 keyLength");
       var prf = m.fields.prf.present ? m.fields.prf.value.result : null;
-      // X.690 sec. 11.5 -- the prf DEFAULT is algid-hmacWithSHA1 (hmacWithSHA1 with NULL parameters,
+      // X.690 sec. 11.5: the prf DEFAULT is algid-hmacWithSHA1 (hmacWithSHA1 with NULL parameters,
       // i.e. the 2-byte DER 05 00, RFC 8018 sec. 5.2); an explicit prf byte-equal to that default is
       // non-canonical and rejects. hmacWithSHA1 with ABSENT parameters is a different value and decodes.
-      // This is a public structural check on the algorithm parameters -- not a secret compare -- so a
+      // This is a public structural check on the algorithm parameters, not a secret compare, so a
       // direct byte test on the (fixed 2-octet) NULL encoding, not a timing-safe comparison.
       var pp = prf ? prf.parameters : null;
-      // nosemgrep: pki-non-constant-time-secret-compare -- pp is the PUBLIC algorithm-identifier parameters
-      // field (a fixed 2-octet NULL encoding), not a MAC / tag / secret; a timing-safe compare is inapplicable.
+      // pp is the public algorithm-identifier parameters field, a fixed 2-octet NULL encoding.
+      // No MAC, tag or secret is involved, so a timing-safe compare has nothing to protect.
+      // nosemgrep: pki-non-constant-time-secret-compare
       if (prf && prf.oid === hmacSha1 && pp !== null && pp.length === 2 && pp[0] === 0x05 && pp[1] === 0x00) {
         throw ctx.E(ctx.prefix + "/bad-mac-data", "a PBKDF2 prf equal to its DEFAULT algid-hmacWithSHA1 must be omitted (X.690 sec. 11.5, RFC 8018 sec. 5.2)");
       }
       // The PBKDF2 prf HMAC AlgorithmIdentifier likewise carries NULL (or absent) parameters (RFC 8018 App. B.1):
       // reject a present-but-non-NULL prf parameter (e.g. an INTEGER) instead of discarding it, since the prf
       // hash is dispatched by OID alone. (An absent prf, and hmacWithSHA1 with absent params, remain valid above.)
-      // nosemgrep: pki-non-constant-time-secret-compare -- pp is the PUBLIC algorithm-identifier parameters node.
+      // pp is the public algorithm-identifier parameters node.
+      // nosemgrep: pki-non-constant-time-secret-compare
       if (prf && pp !== null && !(pp.length === 2 && pp[0] === 0x05 && pp[1] === 0x00)) {
         throw ctx.E(ctx.prefix + "/bad-mac-data", "the PBKDF2 prf parameters must be absent or NULL (RFC 8018 App. B.1)");
       }
@@ -293,12 +295,13 @@ function pbmac1Params(ns) {
       }
       var scheme = m.fields.messageAuthScheme.value.result;
       // RFC 8018 App. B.1: an HMAC messageAuthScheme AlgorithmIdentifier carries NULL (or absent) parameters,
-      // matching the builder (_hmacAlgId emits the 2-byte 05 00). Reject any OTHER parameter encoding rather than
-      // silently discarding it -- _verifyMac dispatches by the scheme OID alone, so a mismatched / malformed
+      // matching the builder (_hmacAlgId emits the 2-byte 05 00). Any other parameter encoding is
+      // rejected: _verifyMac dispatches by the scheme OID alone, so a mismatched / malformed
       // parameter (e.g. an INTEGER) must not slip through unvalidated. A direct byte test on the fixed 2-octet
       // NULL encoding of the PUBLIC parameters, not a secret compare.
       var sp = scheme.parameters;
-      // nosemgrep: pki-non-constant-time-secret-compare -- sp is the PUBLIC algorithm-identifier parameters node.
+      // sp is the public algorithm-identifier parameters node.
+      // nosemgrep: pki-non-constant-time-secret-compare
       if (sp !== null && !(sp.length === 2 && sp[0] === 0x05 && sp[1] === 0x00)) {
         throw ctx.E(ctx.prefix + "/bad-mac-data", "the PBMAC1 messageAuthScheme parameters must be absent or NULL (RFC 8018 App. B.1)");
       }
@@ -314,12 +317,12 @@ function pbmac1Params(ns) {
 // attrValueToString(ns): the AttributeValue decode-leaf. A malformed KNOWN
 // string type (invalid UTF-8, a non-IA5 byte, a PrintableString character
 // outside its set, ...) surfaces as an asn1/bad-* content error and must fail
-// closed -- do NOT hex-encode it away, or the decoder's strict string validation
+// closed. Do not hex-encode it away, or the decoder's strict string validation
 // is silently bypassed on the DN path. A value that is simply not a decodable
-// primitive string is NOT malformed and stays representable: an ANY-typed
+// primitive string is not malformed and stays representable: an ANY-typed
 // non-string tag (asn1/expected-string) or a constructed universal type such as
 // a SEQUENCE (asn1/expected-primitive) renders per RFC 4514 sec. 2.4 as "#" plus the
-// hex of its FULL DER encoding (node.bytes), round-tripping intact.
+// hex of its complete DER encoding (node.bytes), round-tripping intact.
 // A GENUINE string whose first character is '#' or '\' is surfaced with a
 // leading '\' escape (RFC 4514 sec. 2.4) so it can never collide with the
 // '#'+hex form; the encode direction strips that one leading escape back off.
@@ -331,8 +334,9 @@ function attrValueToString(ns) {
       if (!e || (e.code !== "asn1/expected-string" && e.code !== "asn1/expected-primitive")) {
         throw ns.E(ns.prefix + "/bad-atv", "malformed string in attribute value: " + ((e && e.message) || String(e)));
       }
-      // NumericString is deliberately NOT read by asn1.read.string -- a value that returns a plain string joins
-      // the RFC 5280 sec. 7.1 name-comparison identity class, and NumericString is not a DirectoryString type.
+      // asn1.read.string does not read NumericString, and that is deliberate: a value that returns a plain
+      // string joins the RFC 5280 sec. 7.1 name-comparison identity class, and NumericString is not a
+      // DirectoryString type.
       // It does have its own strict reader though, so VALIDATE the content here (an out-of-alphabet value is
       // malformed DER and must not be accepted merely because it falls to the opaque form) while still
       // surfacing it in the type-distinct RFC 4514 hex form, which keeps it out of that identity class.
@@ -347,9 +351,9 @@ function attrValueToString(ns) {
   }, function (value) {
     // encode: a leading '\' escapes the next character (the decode's escape of a
     // literal '#'/'\'); a "#hex" form (RFC 4514 sec. 2.4) round-trips its raw DER
-    // verbatim -- the hex is validated (even-length hex digits encoding exactly one
-    // DER TLV) and throws rather than silently emitting truncated bytes, since
-    // Buffer.from(str, "hex") stops at the first invalid character. Any other
+    // verbatim. The hex is validated (even-length hex digits encoding exactly one
+    // DER TLV) and throws on anything else, since Buffer.from(str, "hex") stops at
+    // the first invalid character and would emit truncated bytes. Any other
     // string encodes as UTF8String (the decode does not preserve the original
     // string type, so this is the canonical re-encoding, not a byte-exact one).
     if (typeof value === "string" && value.charAt(0) === "\\") return asn1.build.utf8(value.slice(1));
@@ -371,17 +375,17 @@ function attrValueToString(ns) {
 
 // The always-escape specials of RFC 4514 sec. 2.4, plus its positional rules:
 // NUL escapes as \00, a trailing space as '\ ', and a leading '#' or space as
-// '\#' / '\ ' -- without them the rendered dn is ambiguous (a literal '#0500'
+// '\#' / '\ '. Without them the rendered dn is ambiguous (a literal '#0500'
 // value would be indistinguishable from the hexstring form) and leading /
 // trailing spaces would be silently significant.
 // RFC 4514 sec. 2.4 attribute-value escaping is the single guard-name primitive
-// (pki.inspect reuses the dn this produces rather than re-escaping the already-
+// (pki.inspect reuses the dn this produces and does not re-escape the already-
 // escaped value), so the display escaper can't diverge from a re-inline elsewhere.
 var _escapeDnValue = guard.name.escapeDnValue;
 
 // The dn RENDERING of a surfaced AttributeValue: the '#'-leading hex form (a
-// non-string value) renders bare -- escaping its '#' would turn the RFC 4514
-// hexstring form into an escaped literal -- while a genuine string (surfaced
+// non-string value) renders bare, since escaping its '#' would turn the RFC 4514
+// hexstring form into an escaped literal. A genuine string (surfaced
 // with its leading '#'/'\' escape, see attrValueToString) is unescaped back to
 // the semantic string and then rendered with the full escape set.
 function _dnDisplayValue(v) {
@@ -395,12 +399,12 @@ function _dnDisplayValue(v) {
 // sec. 5.1.2.4-5.1.2.6): a date through the year 2049 MUST be UTCTime and
 // GeneralizedTime is reserved for 2050 onward, so a GeneralizedTime carrying a
 // 1950..2049 date is a non-conforming second encoding of a representable value
-// and is rejected (<prefix>/bad-time) -- accepting it would let two wire forms
+// and is rejected (<prefix>/bad-time); accepting it would let two wire forms
 // alias one abstract time (a parser-differential channel). The engine's
 // schema.time already applies the cutover on ENCODE; this leaf composes it and
 // enforces the same rule on DECODE. A GeneralizedTime-only field (an RFC 3161
-// genTime, a CRL invalidityDate, an RFC 5755 AttCertValidityPeriod) must NOT
-// take this leaf -- its syntax has no UTCTime alternative to cut over to.
+// genTime, a CRL invalidityDate, an RFC 5755 AttCertValidityPeriod) must not
+// take this leaf, whose syntax has no UTCTime alternative to cut over to.
 function time(ns) {
   var base = schema.time(ns);
   return schema.decode(function (n, ctx) {
@@ -432,10 +436,10 @@ function attributeTypeAndValue(ns) {
   });
 }
 function relativeDistinguishedName(ns) {
-  // RelativeDistinguishedName ::= SET SIZE (1..MAX) -- an empty SET {} is malformed.
+  // RelativeDistinguishedName ::= SET SIZE (1..MAX), so an empty SET {} is malformed.
   return schema.setOf(attributeTypeAndValue(ns), { assert: "set", min: 1, code: ns.prefix + "/bad-rdn", what: "RelativeDistinguishedName" });
 }
-// opts.implicitTag (optional): read the Name as a [tag] IMPLICIT RDNSequence -- the
+// opts.implicitTag (optional): read the Name as a [tag] IMPLICIT RDNSequence. The
 // context tag REPLACES the universal SEQUENCE tag, so the node is a context-class
 // constructed [tag] whose children ARE the RDN SETs (the CRMF CertTemplate issuer
 // [3] / subject [5] IMPLICIT arm, RFC 4211 sec. 5). With no opts the shape is a bare
@@ -456,9 +460,9 @@ function name(ns, opts) {
       parts.push(atvParts.join("+"));
     });
     // `dn` is a DISPLAY string, and its spelling is `openssl x509 -subject`: the RDNs in the
-    // certificate's own order, joined by ", ". That is deliberately NOT the RFC 4514 / LDAP
+    // certificate's own order, joined by ", ". That is deliberately not the RFC 4514 / LDAP
     // distinguishedName, which reverses the RDNs and joins them with a bare comma (`openssl -nameopt
-    // RFC2253`) -- so this string must never be handed to an LDAP client. What IS taken from RFC 4514
+    // RFC2253`), so this string must never be handed to an LDAP client. What IS taken from RFC 4514
     // is sec. 2.4 value escaping, so an attribute value holding a comma cannot read as two RDNs. The
     // interop gate pins this against openssl's own output. Identity never flows through this string:
     // guard.name.dnEqual compares the DER under RFC 5280 sec. 7.1, and `bytes` below carries the raw
@@ -475,28 +479,29 @@ function name(ns, opts) {
 }
 
 // GeneralName ::= CHOICE (RFC 5280 sec. 4.2.1.6). A validate-and-surface-raw leaf for a
-// caller that keeps the value RAW but needs it to be a well-formed GeneralName: it
+// caller that keeps the value raw but needs it to be a well-formed GeneralName: it
 // checks the chosen alternative's tag, form (constructed vs primitive per X.690
-// sec. 10.2), and content -- otherName [0] is a SEQUENCE { type-id OID, value [0] EXPLICIT
+// sec. 10.2), and content, then surfaces the value raw ({ bytes, tagClass, tagNumber }).
+// The content rule per alternative: otherName [0] is a SEQUENCE { type-id OID, value [0] EXPLICIT
 // }; x400Address [3] / ediPartyName [5] are non-empty constructed; directoryName [4]
 // EXPLICIT wraps a valid Name; rfc822Name [1] / dNSName [2] / uniformResourceIdentifier
 // [6] are primitive non-empty IA5String (7-bit); iPAddress [7] is a 4- or 16-octet
-// OCTET STRING; registeredID [8] is a primitive OBJECT IDENTIFIER -- then surfaces the
-// value RAW ({ bytes, tagClass, tagNumber }). `opts.code` is the caller's error code
+// OCTET STRING; registeredID [8] is a primitive OBJECT IDENTIFIER.
+// `opts.code` is the caller's error code
 // (e.g. ocsp/bad-requestor-name, tsp/bad-tsa). Shared so the two parsers cannot drift.
 // opts.decodeValue (default false): in addition to the raw { bytes, tagClass,
-//   tagNumber }, surface the DECODED `value` per arm -- IA5 text (string), an
+//   tagNumber }, surface the DECODED `value` per arm: IA5 text (string), an
 //   iPAddress Buffer, a directoryName { rdns, dn }, a registeredID OID string,
 //   or an otherName { typeId, valueBytes }. The path validator's name-constraint
 //   matcher needs the decoded value; the tsp/ocsp/attrcert consumers pass no
 //   flag and get the byte-identical raw-only shape.
 // opts.subtreeBase (default false): the GeneralSubtree.base form (RFC 5280
-//   sec. 4.2.1.10) -- an iPAddress base is an address+mask (8 octets IPv4 / 32 IPv6),
-//   NOT the 4/16-octet SAN address form. Only the iPAddress size rule changes.
+//   sec. 4.2.1.10). An iPAddress base is an address+mask (8 octets IPv4 / 32 IPv6),
+//   and not the 4/16-octet SAN address form. Only the iPAddress size rule changes.
 // A GeneralizedTime-only leaf. Several formats fix their times to
 // GeneralizedTime and reject UTCTime (OCSP RFC 6960, TSP RFC 3161 sec. 2.4.2,
 // CMP RFC 9810 sec. 5.1.1, attribute-certificate validity RFC 5755 sec. 4.2.6);
-// ONE ns-parameterized factory owns the tag assert so the per-format code and
+// a single ns-parameterized factory owns the tag assert, so the per-format code and
 // message differ but the check cannot drift. opts.allowFractional enables the
 // X.690 sec. 11.7 fractional-seconds profile (the RFC 3161 genTime).
 function generalizedTime(ns, opts) {
@@ -529,8 +534,8 @@ function utf8Text(ns, opts) {
 // A raw NON-EMPTY universal SEQUENCE leaf -- surfaces the exact TLV bytes of an
 // embedded element (a Certificate, a CertificateList, a PKIPublicationInfo)
 // after asserting the SEQUENCE tag and at least one child. An empty SEQUENCE
-// (30 00) has the right tag but is none of those structures, so it rejects
-// rather than surfacing degenerate bytes to certificate processing.
+// (30 00) has the right tag but is none of those structures, so it rejects and
+// no degenerate bytes reach certificate processing.
 function rawNonEmptySequence(ns, opts) {
   opts = opts || {};
   var code = opts.code || (ns.prefix + "/bad-sequence");
@@ -543,8 +548,8 @@ function rawNonEmptySequence(ns, opts) {
   });
 }
 
-// CRLReason ::= ENUMERATED (RFC 5280 sec. 5.3.1) -- value 7 is unused/reserved.
-// The ONE canonical value->name table every consumer validates against: the
+// CRLReason ::= ENUMERATED (RFC 5280 sec. 5.3.1). Value 7 is unused/reserved.
+// The single canonical value->name table every consumer validates against: the
 // CRL reasonCode decoder surfaces the numeric code, the OCSP RevokedInfo
 // decoder the name; both draw the legal set from here so they cannot drift.
 // CRLReason ENUMERATED value names -- the single source is pki.C.NAMES.CRL_REASON
@@ -580,7 +585,7 @@ function generalName(ns, opts) {
         }
         if (decodeValue) value = { typeId: typeId, valueBytes: ov.children[0].bytes };
       } else if (t === 4) {
-        // directoryName [4] EXPLICIT Name -- validate the wrapped RDNSequence.
+        // directoryName [4] EXPLICIT Name: validate the wrapped RDNSequence.
         if (n.children.length !== 1) throw ctx.E(code, "GeneralName directoryName [4] must wrap exactly one Name");
         var dnMatch = schema.walk(NAME, n.children[0], ctx);
         if (decodeValue) value = dnMatch.result;
@@ -589,7 +594,7 @@ function generalName(ns, opts) {
       if (constructed) throw ctx.E(code, "GeneralName [" + t + "] must be primitive (X.690 sec. 10.2)");
       if (GN_IA5[t]) {
         if (n.content.length === 0) throw ctx.E(code, "GeneralName [" + t + "] must be a non-empty IA5String");
-        // 7-bit IA5, no C0/DEL control byte -- an embedded NUL/control in a
+        // 7-bit IA5, no C0/DEL control byte. An embedded NUL/control in a
         // dNSName/rfc822Name/URI enables a name-truncation bypass (CVE-2009-2408).
         guard.name.assertPrintableIa5(n.content, ctx.E, code, "GeneralName [" + t + "]");
         if (decodeValue) value = n.content.toString("latin1");
@@ -619,10 +624,10 @@ function generalName(ns, opts) {
 // element is validated by generalName (its CHOICE alternative's form + content) and
 // surfaced raw, so a caller carrying a GeneralNames field cannot accept a malformed
 // element by treating the whole sequence as opaque bytes. Returns { names, bytes }
-// where each `names[i]` is the generalName leaf's return -- { bytes, tagClass,
-// tagNumber } and, when opts.decodeValue is set, the decoded `value` -- and `bytes`
+// where each `names[i]` is the generalName leaf's return: { bytes, tagClass,
+// tagNumber } plus, when opts.decodeValue is set, the decoded `value`. `bytes`
 // is the raw outer DER.
-// `opts.implicitTag` handles a [tag] IMPLICIT GeneralNames -- the context tag REPLACES
+// `opts.implicitTag` handles a [tag] IMPLICIT GeneralNames, where the context tag REPLACES
 // the universal SEQUENCE tag (RFC 5755 Holder.entityName [1]); otherwise it is a bare
 // universal SEQUENCE OF. `opts.code` is the caller's error code. Shared so the x509 /
 // attribute-certificate / (future) CRMF parsers validate a GeneralNames identically.
@@ -641,11 +646,11 @@ function generalNames(ns, opts) {
 
 // DistributionPointName ::= CHOICE { fullName [0] IMPLICIT GeneralNames,
 // nameRelativeToCRLIssuer [1] IMPLICIT RelativeDistinguishedName } (RFC 5280
-// sec. 4.2.1.13). The caller hands the CHOICE node itself -- the alternative
-// INSIDE the [0]-tagged distributionPoint field wrapper (a context tag on a
+// sec. 4.2.1.13). The caller hands the CHOICE node itself: the alternative
+// inside the [0]-tagged distributionPoint field wrapper (a context tag on a
 // CHOICE-typed field is always EXPLICIT, so the wire nests [0]{ [0]|[1] ... }).
-// fullName surfaces each element's RAW GeneralName DER as { kind: "fullName",
-// names: [Buffer, ...] } -- the byte-exact comparison key the sec. 5.2.5
+// fullName surfaces each element's raw GeneralName DER as { kind: "fullName",
+// names: [Buffer, ...] }, the byte-exact comparison key the sec. 5.2.5
 // "identical encoding MUST be used" correspondence rule requires;
 // nameRelativeToCRLIssuer surfaces its full [1]-tagged TLV as { kind: "rdn",
 // bytes: Buffer } (byte-identical [1] TLVs are byte-identical RDN fragments).
@@ -660,7 +665,7 @@ function distributionPointName(ns, node, code) {
     return { kind: "fullName", names: gns.names.map(function (n) { return n.bytes; }) };
   }
   if (node && node.tagClass === "context" && node.tagNumber === 1) {
-    // [1] IMPLICIT RelativeDistinguishedName -- the context tag replaces the
+    // In [1] IMPLICIT RelativeDistinguishedName the context tag replaces the
     // SET tag, so the node's direct children are the AttributeTypeAndValues.
     schema.walk(schema.implicitSetOf(1, attributeTypeAndValue(ns), {
       min: 1, code: code, what: "DistributionPointName nameRelativeToCRLIssuer" }), node, ns);
@@ -670,15 +675,15 @@ function distributionPointName(ns, node, code) {
 }
 
 // A certificate's keyUsage as the named booleans the shared sec. 4.2.1 decoder produces, or null
-// when the certificate carries no keyUsage extension -- which places no restriction (sec. 4.2.1.3),
-// a distinct answer from "carries one that permits nothing".
+// when the certificate carries no keyUsage extension. An absent extension places no restriction
+// (sec. 4.2.1.3), a distinct answer from "carries one that permits nothing".
 //
 // Declared here because "may this certificate do X" is asked at five boundaries and the answer has
 // to be the same at all of them. keyUsage is a NamedBitList: DER drops its trailing zero bits
 // (X.690 sec. 11.2.2) and sec. 4.2.1.3 requires at least one bit set. A boundary that reads the
 // bits with a plain BIT STRING read applies neither, so the same certificate is authorized there
-// and rejected as malformed by the issuing side and the path validator -- one extension with two
-// readings, and the permissive one deciding.
+// and rejected as malformed by the issuing side and the path validator. One extension gets two
+// readings, and the permissive one decides.
 //
 // `E(code, message, cause)` is the caller's typed error factory, so each boundary keeps its own
 // domain while the RULE stays single-homed.
@@ -701,8 +706,8 @@ function keyUsageOf(ns, cert, E, code, label) {
 // onlySomeReasons [3] ReasonFlags OPTIONAL, indirectCRL [4] DEFAULT FALSE,
 // onlyContainsAttributeCerts [5] DEFAULT FALSE } (RFC 5280 sec. 5.2.5).
 //
-// Declared here rather than in a consumer because the extension answers a
-// question -- which certificates does this CRL speak for -- that both the path
+// It is declared here and not in a consumer because the extension answers the
+// question "which certificates does this CRL speak for", which both the path
 // validator and the standalone CRL verbs act on, and a scope flag read by a hand
 // walk over the raw children is read by the reader's own rules instead of the
 // encoding's. Each flag is an IMPLICIT BOOLEAN, so `implicitBoolean` is what
@@ -714,7 +719,7 @@ function keyUsageOf(ns, cert, E, code, label) {
 //
 // A present DEFAULT-FALSE flag encoding FALSE is well-formed at the leaf but is
 // still an encoding DER forbids (X.690 sec. 11.5 omits the default), so the
-// caller decides what that means for it -- reported as a value of `false`
+// caller decides what that means for it. It is reported as a value of `false`
 // against a `present` of true, never silently normalized away.
 function issuingDistributionPoint(code) {
   return schema.seq([
@@ -744,7 +749,7 @@ var _T = asn1.TAGS;
 
 // assertPolicyQualifiers(qNode, fail) -- RFC 5280 sec. 4.2.1.4: a PolicyInformation's
 // policyQualifiers is a non-empty SEQUENCE OF PolicyQualifierInfo, each a SEQUENCE
-// { policyQualifierId OID, qualifier } of EXACTLY two members led by an OID. The
+// { policyQualifierId OID, qualifier } of exactly two members led by an OID. The
 // structure is validated fail-closed; the qualifier body stays opaque (surfaced
 // raw by the caller). `fail(msg)` throws the caller's typed code. Shared by the
 // certificatePolicies extension decoder and the RFC 5035 ESS SigningCertificate
@@ -764,8 +769,8 @@ function assertPolicyQualifiers(qNode, fail) {
 }
 
 // DisplayText ::= CHOICE { ia5String, visibleString, bmpString, utf8String } each SIZE (1..200)
-// -- RFC 5280 sec. 4.2.1.4. The bound is deliberately NOT enforced here, and that is a normative
-// requirement rather than a gap: the same section closes with "While the explicitText has a maximum
+// -- RFC 5280 sec. 4.2.1.4. The bound is deliberately not enforced here. That is a normative
+// requirement and not a gap: the same section closes with "While the explicitText has a maximum
 // size of 200 characters, some non-conforming CAs exceed this limit. Therefore, certificate users
 // SHOULD gracefully handle explicitText with more than 200 characters." A decoder IS the certificate
 // user that note addresses, so refusing an over-long notice would violate a SHOULD and reject
@@ -804,11 +809,11 @@ function _isDisplayTextNode(n) {
 // Reading the content bytes directly would repair the value instead: `toString("utf8")` substitutes
 // U+FFFD for invalid sequences and a hand-rolled UCS-2 loop drops a trailing odd octet, so a caller
 // would render or measure text the certificate does not contain. Returns null when the value does
-// not decode, so the caller can take its own fallback rather than trust a repair.
+// not decode, leaving the fallback to the caller.
 // An undecodable value yields an entry whose `text` and `chars` are null but whose `field` and
 // `tagNumber` are still present. The two are separable facts: which ASN.1 string type was used is
 // established by the tag alone, so a rule about the ENCODING stays answerable even when the contents
-// do not decode, while every rule that reads the TEXT must skip the entry rather than analyze a
+// do not decode, while every rule that reads the TEXT must skip the entry and not analyze a
 // repair. Collapsing both into "not analyzable" would let a prohibited encoding escape its finding
 // by also being malformed inside.
 function _dtEntry(field, node) {
@@ -817,29 +822,29 @@ function _dtEntry(field, node) {
   try { text = asn1.read.string(node); } catch (_e) { text = null; }
   return { field: field, tagNumber: node.tagNumber, text: text, chars: text === null ? null : displayTextChars(text) };
 }
-// A NoticeReference names its notice by ORGANIZATION **and** NUMBER -- the organization alone does not
+// A NoticeReference names its notice by ORGANIZATION **and** NUMBER. The organization alone does not
 // identify which notice is meant, so a consumer that surfaced only the text would lose the lookup key.
 // Returns null when the numbers are absent, wrongly shaped, or contain a member that is not a readable
-// INTEGER: an incompletely decoded reference must NOT be presentable, because dropping the members that
-// failed would render a partial reference indistinguishable from a whole one -- the same defect as
+// INTEGER: an incompletely decoded reference must not be presentable, because dropping the members that
+// failed would render a partial reference indistinguishable from a whole one. That is the same defect as
 // omitting the numbers entirely, in a form that is harder to notice. Numbers are decimal strings.
 function _noticeNumbers(node) {
   if (!node || node.tagClass !== "universal" || node.tagNumber !== _T.SEQUENCE || !node.children) return null;
   var nums = [], ok = true;
   node.children.forEach(function (n) {
-    // allow:swallow-unverified a non-INTEGER member makes the whole reference undecodable; the caller falls back rather than rendering part of it
+    // allow:swallow-unverified a non-INTEGER member makes the whole reference undecodable, and the caller falls back
     try { nums.push(String(asn1.read.integer(n))); } catch (_e) { ok = false; }
   });
   return ok ? nums : null;
 }
-// Every DisplayText member is returned, including one whose contents did not decode -- that entry
+// Every DisplayText member is returned, including one whose contents did not decode; that entry
 // carries its tag with a null `text`. A caller that RENDERS the notice must check that every entry
 // decoded before showing any of it (a partial notice is indistinguishable from a complete one); a
 // caller that only classifies the encoding can read the tags regardless.
 // The LAYOUT is validated before any member is read: UserNotice fixes the order (noticeRef first) and
 // the cardinality (each member at most once, nothing else present). Collecting every recognized member
-// and ignoring the rest would accept a duplicated explicitText, a reversed order, or an extra member,
-// and the caller -- which can only see whether the entries it got look complete -- would then present
+// and ignoring the rest would accept a duplicated explicitText, a reversed order, or an extra member.
+// The caller can only see whether the entries it got look complete, so it would then present
 // a structurally invalid notice as a whole one. A malformed layout yields NO entries, so a renderer
 // falls back to hex and a reporter measures nothing.
 function userNoticeTexts(qualifier) {
@@ -914,7 +919,7 @@ function certExtensionDecoders(ns) {
     if (kids[i] && kids[i].tagClass === "universal" && kids[i].tagNumber === _T.INTEGER) {
       if (!cA) throw ns.E(C, "BasicConstraints pathLenConstraint is only permitted when cA is TRUE (RFC 5280 sec. 4.2.1.9)");
       var pl = readInt(kids[i], C, "pathLenConstraint");
-      // guard.range.uint31 bounds the decoded BigInt and narrows atomically -- a
+      // guard.range.uint31 bounds the decoded BigInt and narrows atomically. A
       // value past the safe-integer range would otherwise round silently and be
       // compared as a path-length ceiling.
       pathLen = guard.range.uint31(pl, ns.E, C, "BasicConstraints pathLenConstraint (RFC 5280 sec. 4.2.1.9)"); i++;
@@ -932,7 +937,7 @@ function certExtensionDecoders(ns) {
     if (n.tagClass !== "universal" || n.tagNumber !== _T.BIT_STRING) throw ns.E(C, "KeyUsage must be a BIT STRING (RFC 5280 sec. 4.2.1.3)");
     var bs;
     try { bs = asn1.read.bitString(n); } catch (e) { throw ns.E(C, "KeyUsage must be a well-formed BIT STRING", e); }
-    // At least one bit MUST be set (RFC 5280 sec. 4.2.1.3) -- an all-zero value (a
+    // At least one bit MUST be set (RFC 5280 sec. 4.2.1.3), so an all-zero value (a
     // non-empty byte run of only zero bits, e.g. 03 02 07 00) is malformed too.
     var anyBit = false;
     for (var z = 0; z < bs.bytes.length; z++) { if (bs.bytes[z] !== 0) { anyBit = true; break; } }
@@ -946,7 +951,7 @@ function certExtensionDecoders(ns) {
     });
     // Any bit beyond the 9 named positions is a reserved/unknown usage. RFC 5280 tolerates it,
     // but a "MUST be the ONLY bit" rule (e.g. RFC 9935 sec. 5 ML-KEM keyEncipherment-only) needs
-    // to see it -- so surface it rather than silently drop bits >= 9.
+    // to see it, so bits >= 9 are surfaced on `reservedBitsSet`.
     var reserved = false;
     for (var bit2 = KU_BITS.length; bit2 < bs.bytes.length * 8 && !reserved; bit2++) {
       if ((bs.bytes[bit2 >> 3] & (0x80 >> (bit2 & 7))) !== 0) reserved = true;
@@ -999,7 +1004,7 @@ function certExtensionDecoders(ns) {
     var seen = {};
     return kids.map(function (pi) {
       // PolicyInformation ::= SEQUENCE { policyIdentifier, policyQualifiers
-      // SEQUENCE SIZE(1..MAX) OPTIONAL } -- exactly one or two fields; a second
+      // SEQUENCE SIZE(1..MAX) OPTIONAL }. Exactly one or two fields; a second
       // field, if present, MUST be a SEQUENCE. Extra/mis-typed fields are malformed.
       if (pi.tagClass !== "universal" || pi.tagNumber !== _T.SEQUENCE || !pi.children || pi.children.length < 1 || pi.children.length > 2) {
         throw ns.E(C, "PolicyInformation must be a SEQUENCE { policyIdentifier, policyQualifiers? }");
@@ -1069,7 +1074,7 @@ function certExtensionDecoders(ns) {
     return guard.range.uint31(v, ns.E, C, "InhibitAnyPolicy skip count (RFC 5280 sec. 4.2.1.14)");
   }
 
-  // subjectAltName / issuerAltName ::= GeneralNames -- decoded values surfaced.
+  // subjectAltName / issuerAltName ::= GeneralNames, with decoded values surfaced.
   function altName(buf) {
     var C = ns.prefix + "/bad-extension-value";
     var n = decodeTop(buf, C, "GeneralNames");
@@ -1080,7 +1085,7 @@ function certExtensionDecoders(ns) {
   // (RFC 5280 sec. 4.2.2.1); AccessDescription ::= SEQUENCE { accessMethod OBJECT IDENTIFIER, accessLocation
   // GeneralName }. Surfaces [{ accessMethod: <dotted OID>, accessLocation: { tag, value } }] in wire order --
   // accessLocation is the shared generalName leaf (its context tag number + decoded value, so a control-byte
-  // URI is rejected by the CVE-2009-2408 guard). BOTH accessMethods surface (id-ad-caIssuers AND id-ad-ocsp):
+  // URI is rejected by the CVE-2009-2408 guard). Both accessMethods surface (id-ad-caIssuers AND id-ad-ocsp):
   // a consumer filters by accessMethod (caIssuers for issuer fetching, ocsp for responder discovery). An empty
   // SEQUENCE violates SIZE(1..MAX) and is malformed. A composed decoder + registry row, not a hand-roll.
   function authorityInfoAccess(buf) {
@@ -1149,7 +1154,7 @@ function certExtensionDecoders(ns) {
   // which owns the inner peel + the bounded TLS decode; structure is decoded, the
   // signature stays raw and unverified. The registry contract is that a decoder
   // throws a `<prefix>/bad-*` code, so the CT module's own `ct/*` fault is wrapped
-  // and carried as `.cause` rather than leaking a foreign namespace here.
+  // and carried as `.cause`, so a foreign namespace never leaks out here.
   function sctList(buf) {
     var C = ns.prefix + "/bad-extension-value";
     try { return ct.parseSctList(buf); }
@@ -1172,13 +1177,13 @@ function certExtensionDecoders(ns) {
   // distributionPoint [0] DistributionPointName OPTIONAL, reasons [1]
   // ReasonFlags OPTIONAL, cRLIssuer [2] GeneralNames OPTIONAL }. "a
   // DistributionPoint MUST NOT consist of only the reasons field; either
-  // distributionPoint or cRLIssuer MUST be present" -- a reasons-only (or
+  // distributionPoint or cRLIssuer MUST be present". A reasons-only (or
   // empty) DistributionPoint is malformed. The DistributionPointName is
-  // surfaced through the shared helper (raw name encodings -- the sec. 5.2.5
+  // surfaced through the shared helper (raw name encodings, the sec. 5.2.5
   // correspondence key); `reasons` stays a raw BIT STRING ({ unusedBits,
   // bytes }); cRLIssuer is a validated GeneralNames with decoded values.
-  // FreshestCRL ::= CRLDistributionPoints (sec. 4.2.1.15), so the SAME decoder
-  // serves both OIDs -- one codec, both registry rows.
+  // FreshestCRL ::= CRLDistributionPoints (sec. 4.2.1.15), so the same decoder
+  // serves both OIDs: one codec, both registry rows.
   function crlDistributionPoints(buf) {
     var C = ns.prefix + "/bad-crl-distribution-points";
     var kids = seqChildren(buf, C, "CRLDistributionPoints");
@@ -1202,7 +1207,7 @@ function certExtensionDecoders(ns) {
           try { bs = asn1.read.bitStringImplicit(f, 1); }
           catch (e) { throw ns.E(C, "DistributionPoint reasons [1] must be an IMPLICIT ReasonFlags BIT STRING", e); }
           // ReasonFlags is a NamedBitList, so DER requires trailing zero bits be
-          // dropped (X.690 sec. 11.2.2) -- the same rule the keyUsage decoder
+          // dropped (X.690 sec. 11.2.2), the same rule the keyUsage decoder
           // enforces above. Without it two different encodings of one reason set
           // both parse, and RFC 5280 sec. 6.3.3(d)(1) would intersect the CRL's
           // onlySomeReasons against a value the encoding rules forbid.
@@ -1247,9 +1252,9 @@ function certExtensionDecoders(ns) {
     }
     var nras = [];
     if (node.children[i]) {
-      // nameRegistrationAuthorities ::= SEQUENCE SIZE (1..MAX) OF GeneralName -- decode + fully validate
+      // nameRegistrationAuthorities ::= SEQUENCE SIZE (1..MAX) OF GeneralName. Decode and fully validate
       // each element through the shared GeneralName decoder (context tag [0]..[8] + per-alternative
-      // structure), rather than surfacing arbitrary bytes as a name-registration authority.
+      // structure); arbitrary bytes never surface as a name-registration authority.
       nras = schema.walk(generalNames(ns, { decodeValue: true, code: C }), node.children[i], ns).result.names;
       i++;
     }
@@ -1283,7 +1288,7 @@ function certExtensionDecoders(ns) {
     return {
       currency: currency,
       // MonetaryValue amount and exponent are unconstrained INTEGERs (the amount non-negative in practice);
-      // bound each only to the safe-integer range so it narrows to a Number losslessly -- an artificial
+      // bound each only to the safe-integer range so it narrows to a Number losslessly. An artificial
       // tighter bound (uint31, or a small exponent window) would false-reject a valid MonetaryValue, and a
       // wider one would round silently and mis-state the limit.
       amount: guard.range.int(readInt(node.children[1], C, "QcLimitValue amount"), 0n, 9007199254740991n, ns.E, C, "QcLimitValue amount"),
@@ -1304,7 +1309,7 @@ function certExtensionDecoders(ns) {
     }) };
   };
   // ETSI EN 319 412-5 V2.5.1 additions: QcIdentMethod (SEQUENCE OF OID, like QcType) and
-  // QcQSCDlegislation (SEQUENCE OF CountryName, like QcCClegislation) -- registered ids, decoded.
+  // QcQSCDlegislation (SEQUENCE OF CountryName, like QcCClegislation). Both are registered ids, decoded.
   qcInfoByOid[O("qcIdentMethod")] = function (node, C) {
     var oids = _qcOidSeq(node, C, "QcIdentMethod");
     return { methods: oids, methodNames: oids.map(function (d) { return ns.oid.name(d) || null; }) };
@@ -1333,9 +1338,9 @@ function certExtensionDecoders(ns) {
     return out;
   }
 
-  // [MS-WCCE] szOID-CERTIFICATE_TEMPLATE -- CertificateTemplateOID ::= SEQUENCE {
+  // [MS-WCCE] szOID-CERTIFICATE_TEMPLATE. CertificateTemplateOID ::= SEQUENCE {
   //   templateID OID, templateMajorVersion INTEGER OPTIONAL, templateMinorVersion INTEGER OPTIONAL }.
-  // The two versions are DWORDs (0..2^32-1), NOT uint31 -- a CA key/template revision with bit 31
+  // The two versions are DWORDs (0..2^32-1) and not uint31: a CA key/template revision with bit 31
   // set is a legal DWORD, so bound to the whole safe-integer range, never guard.range.uint31.
   function msCertificateTemplate(buf) {
     var C = ns.prefix + "/bad-ms-certificate-template";
@@ -1352,7 +1357,7 @@ function certExtensionDecoders(ns) {
     return { templateID: id, name: ns.oid.name(id) || null, templateMajorVersion: ver(1, "templateMajorVersion"), templateMinorVersion: ver(2, "templateMinorVersion") };
   }
 
-  // [MS-CRTD] szOID-ENROLL_CERTTYPE_EXTENSION -- the legacy v1 template name as a BARE BMPString.
+  // [MS-CRTD] szOID-ENROLL_CERTTYPE_EXTENSION carries the legacy v1 template name as a BARE BMPString.
   // asn1.read.string accepts any universal string tag, so the explicit BMP_STRING assert is the guard.
   function msEnrollCertType(buf) {
     var C = ns.prefix + "/bad-ms-enroll-cert-type";
@@ -1361,7 +1366,7 @@ function certExtensionDecoders(ns) {
     try { return asn1.read.string(n); } catch (e) { throw ns.E(C, "the enroll cert-type name must be a well-formed BMPString", e); }
   }
 
-  // [MS-WCCE] szOID-CERTSRV_CA_VERSION -- INTEGER (0..2^32-1) = (caKeyIndex << 16) | certIndex.
+  // [MS-WCCE] szOID-CERTSRV_CA_VERSION is an INTEGER (0..2^32-1) = (caKeyIndex << 16) | certIndex.
   function msCaVersion(buf) {
     var C = ns.prefix + "/bad-ms-ca-version";
     var n = decodeTop(buf, C, "CACertVersion");
@@ -1370,7 +1375,7 @@ function certExtensionDecoders(ns) {
     return { caVersion: v, caKeyIndex: v >>> 16, certIndex: v & 0xffff };
   }
 
-  // [MS-WCCE] szOID-CERTSRV_PREVIOUS_CERT_HASH -- the SHA-1 thumbprint of the prior CA certificate.
+  // [MS-WCCE] szOID-CERTSRV_PREVIOUS_CERT_HASH holds the SHA-1 thumbprint of the prior CA certificate.
   // AD CS stamps the Windows certificate THUMBPRINT here, which Windows computes with SHA-1 regardless
   // of the certificate's signature algorithm, so the OCTET STRING is exactly 20 octets. An empty or
   // other-length value is malformed renewal metadata and fails closed.
@@ -1418,7 +1423,7 @@ function certExtensionDecoders(ns) {
 // and the RFC 5280 sec. 4.2 per-OID uniqueness.
 function extension(ns) {
   return schema.decode(function (ext) {
-    // Extension ::= SEQUENCE { extnID, critical DEFAULT FALSE, extnValue } -- a
+    // Extension ::= SEQUENCE { extnID, critical DEFAULT FALSE, extnValue } is a
     // UNIVERSAL SEQUENCE of exactly 2 (critical omitted) or 3 children. A
     // context-tagged item (e.g. [5]{OID, OCTET STRING}) or a wrong child count
     // is malformed; assert the tag, don't just count children (fail closed).
@@ -1441,7 +1446,7 @@ function extension(ns) {
   });
 }
 // opts.implicitTag (optional): read Extensions as a [tag] IMPLICIT SEQUENCE OF
-// Extension -- the context tag REPLACES the universal SEQUENCE tag, for the CRMF
+// Extension, where the context tag REPLACES the universal SEQUENCE tag, for the CRMF
 // CertTemplate extensions [9] (RFC 4211 sec. 5). With no opts the shape is a bare
 // universal SEQUENCE OF, byte-identical to every existing caller.
 function extensions(ns, opts) {
@@ -1458,8 +1463,8 @@ function extensions(ns, opts) {
 
 // SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier,
 // subjectPublicKey BIT STRING } (RFC 5280 sec. 4.1.2.7, RFC 2986 sec. 4.1). Asserted as a
-// universal SEQUENCE -- a context-tagged or SET-tagged constructed node carrying
-// two well-formed children is NOT a SubjectPublicKeyInfo. Shared by the
+// universal SEQUENCE, so a context-tagged or SET-tagged constructed node carrying
+// two well-formed children is not a SubjectPublicKeyInfo. Shared by the
 // certificate and CSR parsers.
 // opts.implicitTag (optional): read the SubjectPublicKeyInfo as a [tag] IMPLICIT
 // SEQUENCE (a context-class constructed node whose children are algorithm +
@@ -1479,7 +1484,7 @@ function spki(ns, opts) {
         publicKey: { unusedBits: m.fields.subjectPublicKey.value.unusedBits, bytes: m.fields.subjectPublicKey.value.bytes },
         // `bytes` is the importable SubjectPublicKeyInfo DER. In IMPLICIT [tag]
         // mode the wire node leads with the context tag, so recover the SEQUENCE
-        // encoding a consumer imports / hashes rather than the [tag] wire form.
+        // encoding a consumer imports / hashes, and not the [tag] wire form.
         bytes: opts.implicitTag != null ? asn1.sequenceTlv(m.node) : m.node.bytes,
       };
     },
@@ -1487,7 +1492,7 @@ function spki(ns, opts) {
 }
 
 // Attribute ::= SEQUENCE { type OBJECT IDENTIFIER, values SET OF AttributeValue }.
-// AttributeValue is ANY, kept as raw DER (node.bytes) -- an unrecognized attribute
+// AttributeValue is ANY, kept as raw DER (node.bytes), so an unrecognized attribute
 // type never fails the parse. values is SET SIZE (1..MAX) by default: an empty SET
 // is rejected; there is NO SET-OF uniqueness. Shared by the CSR (requested
 // attributes, RFC 2986 sec. 4.1) and PKCS#8 (private-key attributes, RFC 5958 sec. 2).
@@ -1546,8 +1551,8 @@ function rootSequenceChildren(root, minLen, maxLen) {
 // bound parser so a format declares its configuration once and never re-writes the
 // coerce -> decode -> walk wrapper. `opts`: { pemLabel, PemError, ErrorClass,
 // prefix, what, topSchema, ns }.
-// The top-level schema's reject code -- the verdict for a DER that is not this
-// structure at all -- is `<prefix>/not-a-<structure>` (x509/not-a-certificate,
+// The top-level schema's reject code, the verdict for a DER that is not this
+// structure at all, is `<prefix>/not-a-<structure>` (x509/not-a-certificate,
 // cms/not-a-content-info, ...). Three codes predate that convention and stay
 // frozen on the public error-code surface (ocsp/bad-ocsp-response,
 // tsp/bad-response, crmf/bad-cert-req-messages); a new format follows the
@@ -1558,10 +1563,10 @@ function makeParser(opts) {
 
 // makeRecordingParser(opts, kind) -> a parser that also records the bytes it read.
 //
-// The pairing is here rather than repeated per format because it is one decision, not four: a
+// The pairing lives here and is not repeated per format, because it is one decision, not four: a
 // structure whose parse feeds a VERDICT needs its fields bound to the byte string they came from,
 // since a parsed structure presents the signed range, the signature and the fields that range
-// encodes as separate properties -- and a caller can hand back a genuine range beside substituted
+// encodes as separate properties, and a caller can hand back a genuine range beside substituted
 // fields. `kind` is the tag the matching door re-derives under, so a certificate cannot be presented
 // where a CRL is expected. The record lives in guard-parsed, off the object, unreachable through it.
 function makeRecordingParser(opts, kind) {
@@ -1576,10 +1581,10 @@ function makeRecordingParser(opts, kind) {
 // shape, the arity, the signature extraction and the raw tbs / outer-signature
 // bytes (for the cert/CRL outer==inner agreement check) are owned here once, and
 // each format's `opts.build(envelope, ctx)` shapes its own object from the
-// envelope. A CSR's build simply omits the agreement check -- its CRI has no inner
-// signature AlgorithmIdentifier -- so the omission is structural, not a copy that
+// envelope. A CSR's build simply omits the agreement check, since its CRI has no inner
+// signature AlgorithmIdentifier. The omission is structural, not a copy that
 // forgot a guard.
-// signatureValue is surfaced RAW as { unusedBits, bytes }: for the envelope
+// signatureValue is surfaced raw as { unusedBits, bytes }: for the envelope
 // family, octet alignment is a verify-layer rule (path-validate rejects
 // unusedBits != 0 for certification paths; an external verifier must do the
 // same). A format with no in-tree verify layer (OCSP, CMP protection, CRMF