@blamejs/pki 0.5.7 → 0.5.8

package/lib/schema-c509.js

@@ -7,10 +7,10 @@
  * @title  C509
  * @intro  C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert). A compact CBOR
  *   re-encoding of an X.509 v3 certificate: a deterministic-CBOR array of exactly 11 elements
- *   (10 TBS fields + the issuer signature). Two modes -- c509CertificateType 2 = natively-signed
- *   C509, 3 = a CBOR re-encoding of a DER X.509 certificate that inverts byte-for-byte to the
+ *   (10 TBS fields + the issuer signature). Two modes: c509CertificateType 2 is a natively-signed
+ *   C509, and 3 is a CBOR re-encoding of a DER X.509 certificate that inverts byte-for-byte to the
  *   original DER (so the original signature still verifies). It decodes CBOR, not DER, so it is
- *   reached by an explicit pki.schema.c509.parse call and is NOT auto-routed by pki.schema.parse.
+ *   reached by an explicit pki.schema.c509.parse call and is never auto-routed by pki.schema.parse.
  * @card  Composes the shipped pki.cbor codec (core-deterministic, fail-closed) + the X.509 model.
  */
 
@@ -36,9 +36,9 @@ function _err(code, message, cause) { return new C509Error(code, message, cause)
 var MAX_EPOCH_SECONDS = 8640000000000n;
 
 // The C509 integer registries (draft-20 sec. 8.6/sec. 8.8/sec. 8.14/sec. 8.15): a C509 int is a compact ALIAS of an
-// OID, resolved to the SAME name oid.byName returns for the DER form. Declared as int -> registered
-// OID NAME (never a dotted-decimal literal -- the oid-dotted-decimal-literal gate); oid.byName then
-// yields the dotted string. A row whose target name is not registered fails closed at module load.
+// OID, resolved to the same name oid.byName returns for the DER form. Declared as int -> registered
+// OID NAME (never a dotted-decimal literal, which the oid-dotted-decimal-literal gate enforces);
+// oid.byName then yields the dotted string. A row whose target name is not registered fails closed at module load.
 function _name(n) { var d = oid.byName(n); if (!d) { throw new Error("schema-c509: unregistered OID name " + JSON.stringify(n)); } return n; }
 
 // sec. 8.14 issuerSignatureAlgorithm / signature (the subset v1 covers; negative = legacy SHA-1 values).
@@ -58,8 +58,8 @@ var PK_ALG_BY_INT = {
 var EC_FIELD_BYTES = { "prime256v1": 32, "secp384r1": 48, "secp521r1": 66 };
 
 // sec. 8.6 RDN attribute types (abs(int) -> name; the sign selects the X.509 string type: positive utf8String,
-// negative printableString). An attribute whose value is ALWAYS an IA5String is instead "unambiguously
-// represented using a non-negative int" (draft sec. 3.1.4) -- emailAddress is int 0, so its value reconstructs
+// negative printableString). An attribute whose value is always an IA5String is instead "unambiguously
+// represented using a non-negative int" (draft sec. 3.1.4). emailAddress is int 0, so its value reconstructs
 // as an IA5String and its sign carries no string-type meaning.
 var ATTR_BY_INT = {
   0: _name("emailAddress"),
@@ -98,7 +98,7 @@ var EXT_BY_INT = {
   30: _name("inhibitAnyPolicy"),
   31: _name("subjectInfoAccess"),
   // RFC 3779 resource-delegation extensions, and their RFC 8360 "v2" twins, which the draft
-  // encodes "exactly like" the originals -- same two codecs, four registry rows (sec. 8.8).
+  // encodes "exactly like" the originals: same two codecs, four registry rows (sec. 8.8).
   32: _name("ipAddrBlocks"),
   33: _name("autonomousSysIds"),
   34: _name("ipAddrBlocksV2"),
@@ -107,7 +107,7 @@ var EXT_BY_INT = {
   38: _name("tlsFeature"),
 };
 // The extensions whose compact CBOR value form (sec. 3.3) is invertible to/from the DER extnValue.
-// A registered extension NOT in this set carries its value as the ~oid + byte-string form (sec. 3.7).
+// A registered extension outside this set carries its value as the ~oid + byte-string form (sec. 3.7).
 var EXT_COMPACT = {
   subjectKeyIdentifier: 1, keyUsage: 1, basicConstraints: 1, authorityKeyIdentifier: 1,
   extKeyUsage: 1, inhibitAnyPolicy: 1, ocspNoCheck: 1, tlsFeature: 1,
@@ -130,7 +130,7 @@ Object.keys(EKU_BY_INT).forEach(function (k) { EKU_TO_INT[oid.byName(EKU_BY_INT[
 
 // The shared pkix namespace + GeneralName leaves the general-name value codec composes for the DER ->
 // CBOR direction (the CVE-2009-2408 IA5 control-byte guard, the otherName/directoryName shape, the
-// iPAddress length and RFC 9549 subtree-base length are all enforced there -- never re-validated by hand).
+// iPAddress length and RFC 9549 subtree-base length are all enforced there, never re-validated by hand).
 var NS = pkix.makeNS("c509", C509Error, oid);
 var GN_LEAF = pkix.generalName(NS, { decodeValue: true });                       // SAN-form GeneralName leaf
 var GN_LEAF_SUBTREE = pkix.generalName(NS, { decodeValue: true, subtreeBase: true }); // name-constraints subtree base
@@ -138,7 +138,7 @@ var GN_LEAF_SUBTREE = pkix.generalName(NS, { decodeValue: true, subtreeBase: tru
 // sec. 8.13 C509 General Names registry: for the standard forms the C509 int == the RFC 5280 sec. 4.2.1.6
 // GeneralName CHOICE context tag (1 rfc822Name, 2 dNSName, 4 directoryName, 6 URI, 7 iPAddress, 8
 // registeredID); the _generalNameToDer / _generalNameFromDer switches carry that mapping directly.
-// x400Address [3] and ediPartyName [5] have no registry row -- a GeneralNames carrying either is not
+// x400Address [3] and ediPartyName [5] have no registry row, so a GeneralNames carrying either is not
 // compact-encodable (the enclosing extension falls back to ~oid + byte-string).
 // The id-on otherName specials get their own negative C509 ints (sec. 8.13 / sec. 3.3): int -> the id-on
 // type-id OID name; the derived inverse keys on the resolved OID so a decode selects the negative int.
@@ -180,8 +180,8 @@ Object.keys(PQ_BY_INT).forEach(function (k) { PQ_TO_INT[oid.byName(PQ_BY_INT[k])
 // ---- field readers (the unwrapped ~biguint / ~time / ~oid contracts; draft-20 sec. 3.1) ----
 
 // ~biguint (sec. 3.1.2): a BARE byte string (major type 2), big-endian magnitude, the non-negative
-// leading 0x00 OMITTED. NOT the shipped read.biguint (which requires the tag-2 wrapper and rejects
-// <= 8-byte content). A leading 0x00 is non-minimal; content over the cap is rejected.
+// leading 0x00 OMITTED. This is not the shipped read.biguint, which requires the tag-2 wrapper and
+// rejects <= 8-byte content. A leading 0x00 is non-minimal; content over the cap is rejected.
 function _biguint(node, code, label) {
   if (!node || node.majorType !== 2) throw _err(code, label + " must be an unwrapped CBOR byte string (~biguint)");
   var b = node.content;
@@ -223,11 +223,11 @@ function _algorithm(node, byInt, code, label) {
   if (node.majorType === 4 && node.children && node.children.length === 2) {
     var a = _oidName(node.children[0], code, label);
     // The [~oid, params] form carries the DER parameters as a CBOR byte string; a non-byte-string here
-    // is malformed and cannot be reconstructed (b.raw would append garbage) -- fail closed.
+    // is malformed and cannot be reconstructed (b.raw would append garbage), so it fails closed.
     if (node.children[1].majorType !== 2) throw _err(code, label + " algorithm parameters must be a CBOR byte string");
-    // The parameters carry ONE complete DER element spliced into the reconstruction. An empty byte
+    // The parameters carry one complete DER element spliced into the reconstruction. An empty byte
     // string is no element at all: it rebuilds the same AlgorithmIdentifier as the bare ~oid form,
-    // which is how the CDDL already spells "no parameters" -- so accepting it would give one
+    // which is how the CDDL already spells "no parameters", so accepting it would give one
     // algorithm two encodings, and one X.509 signature would cover both.
     if (node.children[1].content.length === 0) throw _err(code, label + " algorithm parameters must not be an empty byte string; omit them with the bare ~oid form (draft sec. 3.1.3)");
     return { name: a.name, oid: a.oid, parameters: node.children[1].content };
@@ -253,13 +253,13 @@ function _specialText(node) {
   throw _err("c509/bad-name", "an attribute value is not a C509 SpecialText (text / bytes / tag-48)");
 }
 
-// draft sec. 3.1.4 fixes WHICH of the three SpecialText spellings a value takes -- the choice belongs to
+// draft sec. 3.1.4 fixes which of the three SpecialText spellings a value takes; the choice belongs to
 // the specification, not the sender. A text string of an even length >= 2 drawn only from '0'-'9'/'a'-'f'
 // is encoded as a byte string; a text string of the form "HH-HH-HH-HH-HH-HH-HH-HH" is encoded as a tag-48
 // MAC address, 48-bit when it matches "HH-HH-HH-FF-FE-HH-HH-HH" and 64-bit otherwise; anything else is a
 // text string. Accepting a second spelling of one value would give the reconstructed certificate more than
 // one C509 encoding, so a single X.509 signature would cover them all and two distinct byte strings would
-// name one certificate. NOT enforced for a natively signed certificate: sec. 3.1.4 says bytes and tag 48
+// name one certificate. A natively signed certificate is exempt: sec. 3.1.4 says bytes and tag 48
 // there "do not correspond to any predefined text string encoding and may also be used for other attribute
 // types", so no canonical text spelling exists to hold one to.
 var _HEX_OPTIMIZED = /^(?:[0-9a-f]{2})+$/;
@@ -291,10 +291,10 @@ function _assertCanonicalSpecialText(node, isNative, E) {
 // commonName | an array of RDNAttributes. Surfaces { dn, rdns, eui64? } shape-compatible with x509.
 // An rdn's (attribute type, sign) pair DECLARES an X.509 string type, so its text must be valid for that type --
 // a printableString sign over a non-PrintableString character, a non-ASCII emailAddress (IA5String-only), or a
-// value outside the type's SIZE. Assert it by running the SAME builder the reconstruction uses, so a Name this
+// value outside the type's SIZE. Assert it by running the same builder the reconstruction uses, so a Name this
 // parse accepts is always one it can rebuild, and a natively-signed certificate (which never reconstructs) is
-// held to the identical rule. Applied to BOTH Name forms -- the array form and the bare single-commonName form.
-// The builder's asn1/* fault is re-thrown in this module's domain rather than leaking onto the parse surface.
+// held to the identical rule. Both Name forms get it: the array form and the bare single-commonName form.
+// The builder's asn1/* fault is re-thrown in this module's domain so it cannot leak onto the parse surface.
 function _assertAttrValue(rdn) {
   try { _reconAttrValue(rdn); }
   catch (e) {
@@ -309,11 +309,11 @@ function _name509(node, isSubject, isNative) {
   if (node.majorType === 3 || node.majorType === 2 || node.majorType === 6) {
     var sv = _specialText(node);
     _assertCanonicalSpecialText(node, isNative, "c509/bad-name");
-    // The bare form is a single commonName -- hold its value to the SAME rules the array form applies, so a
+    // The bare form is a single commonName. Its value is held to the same rules the array form applies, so a
     // natively-signed certificate (which never reconstructs) cannot carry a value the reconstruction would refuse.
     // A tag-48 MAC renders to a fixed 17-character EUI-64 string that satisfies every value rule by
-    // construction, and _reconAttrValue short-circuits on eui64 before any of them -- so asserting here would
-    // be a no-op. The rules bind on the TEXT forms below.
+    // construction, and _reconAttrValue short-circuits on eui64 before any of them, which makes an assertion
+    // here a no-op. The rules bind on the TEXT forms below.
     if (sv.eui64) return { rdns: [{ type: "commonName", eui64: sv.eui64 }], eui64: sv.eui64, dn: "CN=" + _macToEui64String(sv.eui64) };
     var val = sv.text !== undefined ? sv.text : sv.hex;
     var bareRdn = { type: "commonName", value: val };
@@ -325,23 +325,23 @@ function _name509(node, isSubject, isNative) {
   var parts = [];
   var kids = node.children || [];
   // Each RDN attribute is an (attributeType, attributeValue) pair; an odd-length array is a dangling
-  // attribute type with no value -- reject rather than silently drop the trailing element.
+  // attribute type with no value, so the whole Name is rejected.
   if (kids.length % 2 !== 0) throw _err("c509/bad-name", "a C509 Name array must be attribute-type/value pairs (dangling attribute type)");
   // RFC 5280 sec. 4.1.2.4 -- the issuer MUST be a non-empty distinguished name (only the SUBJECT may be empty,
-  // for the subjectAltName case). An empty issuer array would reconstruct a certificate this toolkit's OWN
+  // for the subjectAltName case). An empty issuer array would reconstruct a certificate this toolkit's own
   // x509.parse refuses to load (x509/bad-issuer), so the codec must not produce one.
   if (kids.length === 0 && !isSubject) throw _err("c509/bad-name", "the issuer Name must not be empty (RFC 5280 sec. 4.1.2.4)");
   for (var i = 0; i + 1 < kids.length; i += 2) {
-    // The attributeType slot must be a CBOR integer (major type 0/1). Guard the major type BEFORE the read
+    // The attributeType slot must be a CBOR integer (major type 0/1). Guard the major type before the read
     // so a non-integer type slot fails in this module's own domain (c509/bad-name), matching the value slot,
-    // rather than leaking cbor.read.int's cbor/unexpected-major fault onto the parse surface. Reached with
+    // and cbor.read.int's cbor/unexpected-major fault never leaks onto the parse surface. Reached with
     // attacker-controlled bytes via the sec. 8.13 directoryName general name (subjectAltName, authorityKey-
     // Identifier issuer, cRLDistributionPoints cRLIssuer, nameConstraints subtree base) and the top-level Name.
     if (kids[i].majorType !== 0 && kids[i].majorType !== 1) throw _err("c509/bad-name", "a C509 Name attribute type must be a CBOR integer");
     var ti = Number(cbor.read.int(kids[i]));
     // draft sec. 3.1.4: "in natively signed C509 certificates all CBOR ints SHALL be non-negative." The sign
-    // exists ONLY to reproduce the string type of an original X.509 DER, which a native certificate does not
-    // have -- so a negative attributeType there is an encoding no conformant producer emits, and accepting it
+    // exists only to reproduce the string type of an original X.509 DER, which a native certificate does not
+    // have. A negative attributeType there is an encoding no conformant producer emits, and accepting it
     // would let this parser read a natively-signed name a conformant peer must reject.
     if (isNative && ti < 0) throw _err("c509/bad-name", "a natively signed C509 Name attribute type integer must be non-negative (draft sec. 3.1.4), got " + ti);
     var tname = ATTR_BY_INT[Math.abs(ti)];
@@ -349,7 +349,7 @@ function _name509(node, isSubject, isNative) {
     var v = _specialText(kids[i + 1]);
     _assertCanonicalSpecialText(kids[i + 1], isNative, "c509/bad-name");
     var vv = v.text !== undefined ? v.text : (v.hex !== undefined ? v.hex : _macToEui64String(v.eui64));
-    // The RENDERED text is what carries into the rdn -- deliberately NOT the raw eui64, because the EUI shortcut
+    // The rdn carries the RENDERED text, because the EUI shortcut
     // in _reconAttrValue is unconditional and would take precedence over the attribute's declared string type,
     // rebuilding a tag-48 emailAddress or countryName as a UTF8String. Only the bare-SpecialText form above is
     // always a commonName and may carry it; here the value is held to whatever type the attribute integer declares.
@@ -361,21 +361,21 @@ function _name509(node, isSubject, isNative) {
   // sec. 3.1.4: "If Name contains a single 'common name' attribute with attributeType = +1, it is for
   // compactness encoded as just the SpecialText containing the single attribute value." The array
   // spelling of that one case is therefore a second encoding of a name that already has a canonical
-  // one. Only +1 has a bare form -- a negative (printableString) commonName keeps the array.
+  // one. Only +1 has a bare form; a negative (printableString) commonName keeps the array.
   if (!isNative && rdns.length === 1 && rdns[0].type === "commonName" && !rdns[0].printable) {
     throw _err("c509/bad-name", "a Name holding a single +1 commonName must be encoded as a bare SpecialText, not an array (draft sec. 3.1.4)");
   }
   return { rdns: rdns, dn: parts.join(", ") };
 }
-// The rendered dn uses the SAME spelling as every other name renderer here (schema-pkix): the RDNs in
-// certificate order joined by ", ", which is what `openssl x509 -subject` prints -- so one certificate
+// The rendered dn uses the same spelling as every other name renderer here (schema-pkix): the RDNs in
+// certificate order joined by ", ", which is what `openssl x509 -subject` prints. One certificate therefore
 // has one dn string whichever parser read it, and the interop gate can pin both against openssl. It is
 // deliberately not the RFC 4514 / LDAP distinguishedName (which reverses the RDNs and drops the space).
 // What IS taken from RFC 4514 is sec. 2.4 value escaping, through the shared guard: raw concatenation
 // would let a single attribute whose value contains a comma render identically to a genuine multi-RDN
-// name (a spoofable identity string, and the ONLY name surface a natively signed certificate has, since
+// name (a spoofable identity string, and the only name surface a natively signed certificate has, since
 // it never reconstructs DER), and would carry control bytes into logs.
-// The SAME label table schema-pkix renders with (pki.C.NAMES.DN_SHORT), not a local list: a hand-rolled
+// The label table is the one schema-pkix renders with (pki.C.NAMES.DN_SHORT), not a local list: a hand-rolled
 // one covers whichever attributes it was written for and silently renders the rest by their long name,
 // so the same certificate would still read differently depending on which parser produced the string.
 function _shortName(n) { return (n && constants.NAMES.DN_SHORT[n]) || n; }
@@ -387,7 +387,7 @@ function _shortName(n) { return (n && constants.NAMES.DN_SHORT[n]) || n; }
 // the compact form only when it round-trips byte-for-byte (else the ~oid + byte-string fallback).
 
 // A CBOR unsigned integer node -> its BigInt value (major type 0 guarantees non-negative). Arbitrary
-// precision: a DER INTEGER holds any width, so no cap -- the round-trip guard verifies the reconstruction.
+// precision: a DER INTEGER holds any width, so there is no cap; the round-trip guard verifies the reconstruction.
 function _cborUint(node, label) {
   if (node.majorType !== 0) throw _err("c509/bad-extensions", "a " + label + " value must be a CBOR unsigned integer");
   return cbor.read.int(node);
@@ -398,10 +398,10 @@ function _cborIntVal(node, label) {
   return cbor.read.int(node);
 }
 // A non-negative reconstruct-side count (a policyConstraints / inhibitAnyPolicy SkipCerts, a basicConstraints
-// pathLenConstraint) narrowed to [0, 2^31-1] via the SAME guard.range.uint31 the toolkit's own DER decoders
-// (schema-pkix) bound these INTEGER (0..MAX) counts through. A native CBOR value past 2^31-1 fails closed here
-// rather than reconstructing a DER the toolkit's own decoder would then reject -- the reconstruct path must
-// produce nothing that decoder rejects. Returns a Number; b.integer narrows it to the minimal DER INTEGER.
+// pathLenConstraint) narrowed to [0, 2^31-1] through guard.range.uint31, the same bound the toolkit's own DER
+// decoders (schema-pkix) put on these INTEGER (0..MAX) counts. A native CBOR value past 2^31-1 fails closed
+// here; it never reconstructs a DER the toolkit's own decoder would then reject, because the reconstruct path
+// must produce nothing that decoder rejects. Returns a Number; b.integer narrows it to the minimal DER INTEGER.
 function _boundCount(value, label) {
   return guard.range.uint31(value, _err, "c509/bad-extensions", label + " (0..2^31-1)");
 }
@@ -414,7 +414,7 @@ function _ekuPurposeOid(node) {
     return oid.byName(nm);
   }
   // A ~oid KeyPurposeId routes through _oidName, which validates the BER OID content and remaps an oid/*
-  // fault to c509/bad-extensions (fault preserved as .cause) -- a non-byte-string node fails closed there too.
+  // fault to c509/bad-extensions (fault preserved as .cause). A non-byte-string node fails closed there too.
   return _oidName(node, "c509/bad-extensions", "an extKeyUsage KeyPurposeId").oid;
 }
 
@@ -424,8 +424,8 @@ function _ekuPurposeOid(node) {
 // authorityInfoAccess, ...), so a tag/int mapping bug cannot diverge across them. The DER -> CBOR side
 // composes the shared pkix.generalName leaf; the CBOR -> DER side builds directly with asn1.build.*, the
 // exact inverse. Every encode stays behind the extension-level byte-exact round-trip guard
-// (_tryCompactExtValue), so a member the codec cannot invert byte-for-byte falls the WHOLE extension back
-// to the conformant ~oid + byte-string form (sec. 3.7) -- never a partial GeneralNames.
+// (_tryCompactExtValue), so a member the codec cannot invert byte-for-byte falls the whole extension back
+// to the conformant ~oid + byte-string form (sec. 3.7). A partial GeneralNames is never emitted.
 
 // The unwrapped ~oid CBOR form (a bare byte string of the BER OID content octets; RFC 9090).
 function _oidCbor(dotted) { return cbor.build.byteString(asn1.encodeOidContent(dotted)); }
@@ -434,13 +434,13 @@ function _isCborNull(node) { return node.majorType === 7 && node.ai === 22; }
 
 // A CBOR text node -> the IA5String content octets of an IMPLICIT [n] GeneralName (rfc822Name/dNSName/URI).
 // IA5String is 7-bit ASCII, so a code point > 0x7f cannot be one; a control byte (C0/DEL) is an injection
-// vector (CVE-2009-2408) the shared name guard rejects -- matching the pkix.generalName decode side, so a
+// vector (CVE-2009-2408) the shared name guard rejects. That matches the pkix.generalName decode side, so a
 // value it rejects also fails the reconstruction direction (no round-trip guard runs on decode).
 function _ia5Bytes(node, tag) {
   if (node.majorType !== 3) throw _err("c509/bad-extensions", "a GeneralName [" + tag + "] value must be a CBOR text string (IA5String)");
   var s = cbor.read.textString(node);
   // An empty IA5 GeneralName is rejected by the shared pkix.generalName leaf (a non-empty rfc822Name /
-  // dNSName / URI), so reject it on the reconstruction side too rather than emit an empty [n] IA5String.
+  // dNSName / URI), so the reconstruction side rejects it too.
   if (s.length === 0) throw _err("c509/bad-extensions", "a GeneralName [" + tag + "] IA5String must be non-empty");
   for (var i = 0; i < s.length; i++) { if (s.charCodeAt(i) > 0x7f) throw _err("c509/bad-extensions", "a GeneralName [" + tag + "] IA5String has a non-ASCII code point"); }
   var buf = Buffer.from(s, "latin1");
@@ -503,7 +503,7 @@ function _generalNamesToDer(node, isNative) {
   return out;
 }
 // The inverse: a list of DER GeneralName nodes -> the flat CBOR items, or null if ANY member is not
-// compact-representable (the whole enclosing extension then falls back -- never a partial GeneralNames).
+// compact-representable (the whole enclosing extension then falls back, and no partial GeneralNames is produced).
 function _generalNamesFromDer(gnNodes) {
   var out = [];
   for (var i = 0; i < gnNodes.length; i++) {
@@ -514,7 +514,7 @@ function _generalNamesFromDer(gnNodes) {
   return out;
 }
 
-// otherName [0] IMPLICIT SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY } -- the context tag
+// otherName [0] IMPLICIT SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY }. The context tag
 // REPLACES the SEQUENCE tag (RFC 5280 IMPLICIT tagging), so the [0] node holds type-id then value directly
 // (no inner universal SEQUENCE). The generic form (C509 int 0) carries [ ~oid(type-id), bytes(the [0]
 // EXPLICIT inner value's raw TLV) ]; the id-on specials (-1/-2/-3) carry the RFC 4108 / RFC 9598 /
@@ -525,7 +525,7 @@ function _otherNameToDer(node, intVal) {
     if (node.majorType !== 4 || !node.children || node.children.length !== 2) throw _err("c509/bad-extensions", "a generic otherName value must be a CBOR [ ~oid, bytes ] pair");
     typeId = _oidName(node.children[0], "c509/bad-extensions", "an otherName type-id").oid;
     if (node.children[1].majorType !== 2) throw _err("c509/bad-extensions", "an otherName value must be a CBOR byte string (the [0] EXPLICIT inner TLV)");
-    // The [0] EXPLICIT inner TLV is an ANY spliced verbatim -- strict-validate it, not just its framing.
+    // The [0] EXPLICIT inner TLV is an ANY spliced verbatim: strict-validate it, not just its framing.
     inner = _requireStrictDerTlv(node.children[1].content, "c509/bad-extensions", "an otherName value");
   } else if (intVal === -1) {   // id-on-hardwareModuleName: [ ~oid(hwType), bytes(hwSerialNum) ] -> HardwareModuleName
     if (node.majorType !== 4 || !node.children || node.children.length !== 2) throw _err("c509/bad-extensions", "an id-on-hardwareModuleName value must be a CBOR [ ~oid, bytes ] pair");
@@ -566,8 +566,9 @@ function _otherNameFromDer(v) {
   }
   if (inner.tagClass !== "universal" || inner.tagNumber !== asn1.TAGS.OCTET_STRING) return null;   // onInt === -3: MACAddress ::= OCTET STRING
   var mac; try { mac = asn1.read.octetString(inner); } catch (_e4) { return null; }
-  // nosemgrep: pki-non-constant-time-secret-compare -- mac is a PUBLIC hardware MAC address (an EUI-48/64
-  // identifier, RFC 9542 / lamps-macaddress), not a MAC / HMAC / auth tag / secret; this is a length check.
+  // mac is a PUBLIC hardware MAC address (an EUI-48/64 identifier, RFC 9542 / lamps-macaddress), not a
+  // MAC / HMAC / auth tag / secret; this is a length check.
+  // nosemgrep: pki-non-constant-time-secret-compare
   if (mac.length !== 6 && mac.length !== 8) return null;
   return [cbor.build.int(-3n), cbor.build.byteString(mac)];
 }
@@ -621,23 +622,23 @@ function _ncIpFromDer(buf) {
 //
 // An RFC 3779 IPAddress is a BIT STRING whose unused-bit count carries the prefix length, so the
 // draft maps it to the byte sequence `unusedBits || value`, which "preserves the exact information
-// contained in the ASN.1 BIT STRING" -- lossless even for a prefix ending in zero bits. Per
-// IPAddressFamily the draft then picks ONE of two forms and makes the choice a SHALL: if any of the
+// contained in the ASN.1 BIT STRING", which stays lossless even for a prefix ending in zero bits. Per
+// IPAddressFamily the draft then picks one of two forms and makes the choice a SHALL: if any of the
 // family's byte sequences exceeds 8 octets the whole family uses the bytes form, otherwise the int
 // form. Accepting the wrong one would give one DER two CBOR encodings, so decode enforces it.
 //
-// The int form is the big-endian integer of `(unusedBits + 1) || value` -- the +1 guarantees a
-// non-zero leading octet, which is what makes the minimal big-endian representation unambiguous --
+// The int form is the big-endian integer of `(unusedBits + 1) || value`. The +1 guarantees a
+// non-zero leading octet, which is what makes the minimal big-endian representation unambiguous,
 // and every IPAddress after the first is stored as the DIFFERENCE from its predecessor. The chain
 // runs flat over each address in order (a range contributes min then max) and RESETS at each
 // family, so a family always opens with an absolute value.
 //
 // These integers reach 2^64-1: an IPv6 /48 already exceeds 2^53, and the draft's own A.5 vector
 // lands there. Everything below is BigInt end to end and bounds through guard.range.uint64 (the
-// BigInt-preserving guard) -- never the uint31 counter bound, which would reject a valid prefix.
+// BigInt-preserving guard). The uint31 counter bound is never used here; it would reject a valid prefix.
 
 // An asn1 node exposes tagClass + tagNumber (never a combined `.tag`), so a universal-type test
-// has to check both -- a context-tagged [16] must not read as a SEQUENCE.
+// has to check both: a context-tagged [16] must not read as a SEQUENCE.
 function _isUniversal(n, tagNumber) { return !!n && n.tagClass === "universal" && n.tagNumber === tagNumber; }
 
 // `unusedBits || value` -> the (unusedBits+1)||value integer. Returns null if the sequence cannot
@@ -650,7 +651,7 @@ function _ipSeqToInt(seq) {
   return BigInt("0x" + Buffer.concat([head, seq.subarray(1)]).toString("hex"));
 }
 // The inverse: the minimal big-endian octets of `n`, with the leading octet decremented back to the
-// unused-bit count. Returns null when `n` cannot be an encoded IPAddress -- a leading octet outside
+// unused-bit count. Returns null when `n` cannot be an encoded IPAddress: a leading octet outside
 // 1..8 is not a DER unused-bit count, and past 8 octets the family was required to use the bytes form.
 function _ipIntToSeq(n) {
   if (n < 1n) return null;
@@ -662,7 +663,7 @@ function _ipIntToSeq(n) {
 }
 // The address width in octets of an address family, from its AFI (RFC 3779 sec. 2.2.3.3). Only a
 // family whose width is known can have its canonical form checked, so an unrecognized AFI yields
-// null and the caller declines to compact rather than compacting something it cannot verify.
+// null and the caller declines to compact; it will not compact something it cannot verify.
 var _IP_WIDTH = { 1: 4, 2: 16 };
 
 // The lowest address an `unusedBits || value` sequence denotes, as `width` big-endian octets. DER
@@ -680,7 +681,7 @@ function _ipHigh(seq, width) {
   for (var i = bits; i < width * 8; i++) v[i >> 3] |= 0x80 >> (i & 7);
   return v;
 }
-// Big-endian octet-string compare, and "is `b` the immediate successor of `a`" -- the test that
+// Big-endian octet-string compare, and "is `b` the immediate successor of `a`": the test that
 // distinguishes a legal gap from a contiguous pair the RFC requires be merged.
 function _ipOctCmp(a, b) {
   for (var i = 0; i < a.length; i++) { if (a[i] !== b[i]) return a[i] - b[i]; }
@@ -694,7 +695,7 @@ function _ipIsSuccessor(a, b) {
 }
 
 // RFC 3779 sec. 2.2.3.7: "any range of addresses that can be encoded as a prefix MUST be encoded
-// using an IPAddress element", with the choice fixed by the spec's own pseudocode -- let N be the
+// using an IPAddress element", with the choice fixed by the spec's own pseudocode. Let N be the
 // count of matching leading bits of the low and high addresses; if every remaining bit of the low
 // is zero AND every remaining bit of the high is one, the span IS the N-bit prefix and the range
 // form is forbidden. Two encodings of one address span would otherwise both be legal.
@@ -727,9 +728,9 @@ function _famOctCmp(a, b) {
 
 // Is `unusedBits || value` a sequence DER would accept as a BIT STRING? The declared unused low
 // bits MUST be zero (RFC 3779 sec. 2.2.3.8 restates the DER rule), and a value with no octets can
-// only declare zero unused bits. Checked HERE rather than left to the BIT STRING builder, because
-// the builder's fault is an asn1/* error surfacing out of a CBOR-layer decode -- a caller handed a
-// malformed compact value should see this module's own verdict, not the ASN.1 layer's.
+// only declare zero unused bits. The check lives here, not in the BIT STRING builder: the builder's
+// fault is an asn1/* error surfacing out of a CBOR-layer decode, and a caller handed a malformed
+// compact value should see this module's own verdict, not the ASN.1 layer's.
 function _ipSeqBitsClear(seq) {
   var unused = seq[0], value = seq.subarray(1);
   if (!value.length) return unused === 0;
@@ -739,7 +740,7 @@ function _ipSeqBitsClear(seq) {
 
 // RFC 3779 sec. 2.2.3.6 fixes the canonical form of an address list: entries sorted on
 // `<lowest address> | <prefix length>` (which is neither the DER byte order nor the compact integer
-// order -- the RFC warns about the first and the second sorts the same wrong way), no pair
+// order; the RFC warns about the first and the second sorts the same wrong way), no pair
 // overlapping, and any contiguous pair combined into one entry. All three bind together: a list
 // violating any of them is not the one canonical encoding of its address set, so this codec
 // declines to compact it and the extension keeps its original bytes.
@@ -759,20 +760,20 @@ function _ipRangesCanonical(bounds) {
 // One family's IntIPAddressChoice / IPAddressChoice -> the DER IPAddressOrRange SEQUENCE list.
 // The int form stores each address after the first as a DIFFERENCE from its predecessor, flat over
 // every address in order (a range contributes min then max); the chain resets at each family, which
-// is why `prev` starts null here rather than being threaded across families. The reconstructed
-// ABSOLUTE is what gets bounded -- the delta itself is an arbitrary CBOR int and bounding it would
+// is why `prev` starts null here and is never threaded across families. The reconstructed
+// ABSOLUTE is what gets bounded: the delta itself is an arbitrary CBOR int, and bounding it would
 // miss a chain that walks out of range in steps.
 function _ipChoiceToDer(items, afi) {
   var out = [], prev = null, sawBytes = false, sawInt = false, seqs = [];
   // An address may not be wider than its family: RFC 3779 sec. 2.2.3.8 sizes an IPAddress by the
   // family, so a 5-octet address under AFI 1 is not an IPv4 address at all. Without this, a native
-  // C509 would reconstruct into a DER carrying an over-wide address -- one the RFC forbids and an
-  // independent validator refuses -- from CBOR this codec had accepted. The mirror check lives on
-  // the encode side; both directions have to hold or the pair is not a bijection.
+  // C509 this codec had accepted would reconstruct into a DER carrying an over-wide address that the
+  // RFC forbids and an independent validator refuses. The mirror check lives on the encode side;
+  // both directions have to hold or the pair is not a bijection.
   // Without the family's address width none of the RFC 3779 rules below can be evaluated: the
   // width bound has nothing to compare against, and the low/high bounds that drive the order,
   // overlap, adjacency and endpoint checks cannot be computed at all. Accepting such a family
-  // would therefore wave every one of those checks through -- so a family this codec cannot
+  // would therefore wave every one of those checks through. A family this codec cannot
   // measure is refused outright, matching the encode side, which declines to compact it. An
   // `inherit` family is unaffected: it carries no addresses and never reaches here.
   var width = _IP_WIDTH[afi];
@@ -833,9 +834,9 @@ function _ipChoiceToDer(items, afi) {
   if (sawBytes && !seqs.some(function (s) { return s.length > 8; })) {
     throw _err("c509/bad-extensions", "an IPAddressFamily whose addresses all fit 8 octets must use the integer form (sec. 3.3)");
   }
-  // The SAME RFC 3779 sec. 2.2.3.6 canonical form the encode side requires, enforced here too.
+  // The same RFC 3779 sec. 2.2.3.6 canonical form the encode side requires, enforced here too.
   // draft sec. 3.3 says "The limitations specified in [RFC3779] apply here as well", so a compact
-  // list that is unsorted, overlapping, or unmerged is malformed C509 -- and reconstructing it
+  // list that is unsorted, overlapping, or unmerged is malformed C509, and reconstructing it
   // would emit a certificate an independent validator refuses, from CBOR this codec had accepted.
   // Both directions must hold or the pair is not a bijection.
   for (var r = 0; r < bounds.length; r++) {
@@ -848,7 +849,7 @@ function _ipChoiceToDer(items, afi) {
 }
 
 // DER IPAddressChoice (a SEQUENCE of BIT STRING / SEQUENCE-of-two-BIT-STRING) -> the compact CBOR
-// array. The form is chosen per family and is a SHALL: the bytes form applies to the WHOLE family
+// array. The form is chosen per family and is a SHALL: the bytes form applies to the whole family
 // as soon as any one sequence exceeds 8 octets, otherwise every member takes the delta-coded int
 // form. Returns null on any shape the compact form cannot carry exactly.
 function _ipChoiceFromDer(ch, afi) {
@@ -869,12 +870,12 @@ function _ipChoiceFromDer(ch, afi) {
     groups.push(pair);
     for (var k = 0; k < pair.length; k++) flat.push(pair[k]);
   }
-  // The list must be in RFC 3779 sec. 2.2.3.6 canonical form -- sorted, non-overlapping, and with
+  // The list must be in RFC 3779 sec. 2.2.3.6 canonical form: sorted, non-overlapping, and with
   // every contiguous pair already merged. A list that is not is not the one canonical encoding of
-  // its address set, so it is NOT re-encoded into a conforming one: this returns null and the
+  // its address set, so it is never re-encoded into a conforming one. This returns null and the
   // extension rides the byte-string form, keeping its exact bytes and leaving the defect visible to
   // a validator. Checking overlap and adjacency needs the family's address width, so a family whose
-  // AFI this codec does not know declines too, rather than compacting what it cannot verify.
+  // AFI this codec does not know declines too, since there is no way to verify what it would compact.
   // Defense-in-depth, and deliberately explicit: without the width the bound arithmetic below would
   // fault and the caller's catch would produce the same fallback, so this line changes no observable
   // verdict and no vector can isolate it. It stays because a fallback that depends on an exception
@@ -890,7 +891,7 @@ function _ipChoiceFromDer(ch, afi) {
     // No vector can isolate this line today, because the encode path's round-trip self-verify
     // re-parses what it produced and the decode rule rejects it there, yielding the same fallback.
     // It stays explicit because that makes encode's correctness depend on decode continuing to
-    // throw -- soften the decode rule and this path would silently start compacting again.
+    // throw: soften the decode rule and this path would silently start compacting again.
     if (bg.length === 2 && _ipRangeIsPrefix(blo, bhi)) return null;
     bounds.push({ lo: blo, hi: bhi });
   }
@@ -981,8 +982,8 @@ function _reasonsBitsToDer(value) {
   // ReasonFlags bit 0 is reserved "unused" (RFC 5280 sec. 4.2.1.13; the reason bits are 1..8), so a value
   // that sets it is not a valid ReasonFlags even though the shared 9-bit range check would accept it. Bit 0
   // is a legitimate keyUsage bit (digitalSignature), so this reason-specific reject lives here, not in the
-  // shared named-bit helper -- a malformed native C509 reasons value fails closed rather than reconstructing
-  // a semantically invalid X.509 ReasonFlags.
+  // shared named-bit helper. A malformed native C509 reasons value fails closed; it never reconstructs
+  // into a semantically invalid X.509 ReasonFlags.
   if ((value & 1) !== 0) throw _err("c509/bad-extensions", "a cRLDistributionPoints reasons value must not set the reserved unused ReasonFlags bit 0 (RFC 5280 sec. 4.2.1.13)");
   var c = _namedBitsToContent(value);
   if (c == null) throw _err("c509/bad-extensions", "a cRLDistributionPoints reasons value must be within the 9 defined ReasonFlags bits");
@@ -999,7 +1000,7 @@ function _serialIntContent(node) {
 // ---- certificatePolicies (draft-20 sec. 3.3 / sec. 8.9 / sec. 8.10; RFC 5280 sec. 4.2.1.4) ----
 // A CBOR text -> a UNIVERSAL IA5String TLV, running the same 7-bit + CVE-2009-2408 control-byte guard the
 // general-name IA5 arms use (never the bare b.ia5, which permits control bytes). Non-empty (the general-name
-// IA5 arms reject empty too; a CPSuri parity tightening -- RFC 5280 sets no SIZE floor on CPSuri).
+// IA5 arms reject empty too; this is a CPSuri parity tightening, since RFC 5280 sets no SIZE floor on CPSuri).
 function _ia5Universal(text, label) {
   if (text.length === 0) throw _err("c509/bad-extensions", label + " must be non-empty");
   for (var i = 0; i < text.length; i++) { if (text.charCodeAt(i) > 0x7f) throw _err("c509/bad-extensions", label + " must be a 7-bit IA5String"); }
@@ -1021,7 +1022,7 @@ function _policyIdFromDer(dotted) {
   return i !== undefined ? cbor.build.int(BigInt(i)) : _oidCbor(dotted);
 }
 // (qualifierId CBOR, qualifier-text CBOR) -> one DER PolicyQualifierInfo SEQUENCE { policyQualifierId OID,
-// qualifier ANY DEFINED BY }. The qualifierId resolves to a sec. 8.10 int ONLY: a ~oid / unregistered
+// qualifier ANY DEFINED BY }. The qualifierId resolves to a sec. 8.10 int and nothing else: a ~oid / unregistered
 // qualifierId has no defined qualifier:text semantics, so it is not compact-representable (fail closed, never
 // guess the ANY type). id-qt-cps -> CPSuri IA5String; id-qt-unotice -> UserNotice { explicitText utf8String }.
 function _qualifierToDer(qidNode, qtextNode) {
@@ -1031,11 +1032,11 @@ function _qualifierToDer(qidNode, qtextNode) {
   if (qtextNode.majorType !== 3) throw _err("c509/bad-extensions", "a policyQualifier value must be a CBOR text string");
   var text = cbor.read.textString(qtextNode);
   if (qi === 1) return b.sequence([b.oid(oid.byName("cps")), _ia5Universal(text, "a CPSuri")]);   // CPSuri ::= IA5String
-  // id-qt-unotice: UserNotice ::= SEQUENCE { explicitText utf8String } -- noticeRef omitted. Only the SIZE
+  // id-qt-unotice: UserNotice ::= SEQUENCE { explicitText utf8String }, noticeRef omitted. Only the SIZE
   // (1..200) FLOOR is enforced: an empty explicitText is a degenerate value no encoder can have produced,
   // while RFC 5280 sec. 4.2.1.4 directs certificate users to gracefully handle a notice ABOVE 200
-  // characters, and draft-20 sec. 3.3's compact predicate is SIZE-silent -- so an over-long notice
-  // transcodes rather than being refused.
+  // characters, and draft-20 sec. 3.3's compact predicate is SIZE-silent. An over-long notice
+  // therefore transcodes and is not refused.
   if (text.length === 0) throw _err("c509/bad-extensions", "a UserNotice explicitText must be non-empty (DisplayText SIZE 1..200)");
   return b.sequence([b.oid(oid.byName("unotice")), b.sequence([b.utf8(text)])]);
 }
@@ -1052,7 +1053,7 @@ function _qualifierFromDer(pq) {
     var uri; try { uri = asn1.read.string(q); } catch (_e) { return null; }
     return [cbor.build.int(1n), cbor.build.textString(uri)];
   }
-  // id-qt-unotice: SEQUENCE { explicitText utf8String } ONLY (noticeRef absent).
+  // id-qt-unotice: SEQUENCE { explicitText utf8String } and nothing more (noticeRef absent).
   if (q.tagClass !== "universal" || q.tagNumber !== asn1.TAGS.SEQUENCE || !q.children || q.children.length !== 1) return null;
   var dt = q.children[0];
   if (dt.tagClass !== "universal" || dt.tagNumber !== asn1.TAGS.UTF8_STRING) return null;
@@ -1062,7 +1063,7 @@ function _qualifierFromDer(pq) {
 
 // One CBOR DistributionPointName [ fullName, reasons, cRLIssuer ] -> one DER DistributionPoint SEQUENCE.
 // distributionPoint [0] is EXPLICIT (it wraps the DistributionPointName CHOICE); fullName [0], reasons [1],
-// cRLIssuer [2] are IMPLICIT (RFC 5280 sec. 4.2.1.13) -- mixing these is the classic byte-exactness trap.
+// cRLIssuer [2] are IMPLICIT (RFC 5280 sec. 4.2.1.13); mixing these is the classic byte-exactness trap.
 function _dpToDer(dpNode, isNative) {
   if (dpNode.majorType !== 4 || !dpNode.children || dpNode.children.length !== 3) throw _err("c509/bad-extensions", "a DistributionPoint must be a CBOR [ fullName, reasons, cRLIssuer ] array");
   var fullName = dpNode.children[0], reasons = dpNode.children[1], crlIssuer = dpNode.children[2];
@@ -1200,7 +1201,7 @@ function _extValueToDer(name, node, isNative) {
       if (node.majorType !== 4 || !node.children || node.children.length < 1) throw _err("c509/bad-extensions", "a " + name + " value must be a CBOR array of DistributionPoints or a bare URI text (sec. 3.3)");
       return b.sequence(node.children.map(function (dp) { return _dpToDer(dp, isNative); }));
     // IPAddrBlocks (and its RFC 8360 v2 twin): a FLAT array of (AFI, SAFI, choice) triples --
-    // IPAddressFamily is a parenthesized CDDL group, so it splices rather than nesting.
+    // IPAddressFamily is a parenthesized CDDL group, so it splices and does not nest.
     case "ipAddrBlocks":
     case "ipAddrBlocksV2": {
       if (node.majorType !== 4 || !node.children) throw _err("c509/bad-extensions", "an IPAddrBlocks value must be a CBOR array");
@@ -1248,7 +1249,7 @@ function _extValueToDer(name, node, isNative) {
       }
       // The deltas are `uint` in the draft's CDDL precisely because RFC 3779 sec. 3.2.3.4 sorts AS
       // ids by increasing value: a negative delta would walk the chain backwards. That section also
-      // forbids a pair overlapping and requires a contiguous series to be one range -- the same
+      // forbids a pair overlapping and requires a contiguous series to be one range: the same
       // three rules the encode side applies, tracked here across members through `asPrevHigh`.
       // A negative delta needs no separate test: on the first entry it drives the absolute below
       // zero and the range guard refuses it, and on any later entry it lands at or below the
@@ -1284,8 +1285,8 @@ function _extValueToDer(name, node, isNative) {
         var quals = cpKids[cpi + 1];
         if (quals.majorType !== 4 || !quals.children) throw _err("c509/bad-extensions", "a certificatePolicies qualifiers slot must be a CBOR array");
         // A policy OID MUST NOT appear more than once (RFC 5280 sec. 4.2.1.4); the toolkit's own DER decoder
-        // rejects a duplicate (schema-pkix certExtensionDecoders), so reconstruct fails closed rather than
-        // producing a certificatePolicies extension that decoder would reject.
+        // rejects a duplicate (schema-pkix certExtensionDecoders), so reconstruct fails closed here and
+        // never produces a certificatePolicies extension that decoder would reject.
         var policyOid = _policyIdToDerOid(cpKids[cpi]);
         if (seenPolicy[policyOid]) throw _err("c509/bad-extensions", "a certificatePolicies policy OID must not appear more than once (RFC 5280 sec. 4.2.1.4)");
         seenPolicy[policyOid] = true;
@@ -1474,7 +1475,7 @@ function _extValueFromDer(name, der) {
       // RFC 3779 sec. 3.2.3.4 fixes the canonical form the same way sec. 2.2.3.6 does for addresses:
       // sorted by increasing value, no pair overlapping, and any contiguous series already merged
       // into one range. `asPrevHigh` carries the previous entry's upper bound so all three hold
-      // ACROSS members -- checking only within a range would let a descending or adjacent pair
+      // ACROSS members. Checking only within a range would let a descending or adjacent pair
       // through. A list that is not canonical is left uncompacted with its bytes intact.
       var asOut = [], asPrevOut = null, asPrevHigh = null;
       for (var aoi = 0; aoi < inner.children.length; aoi++) {
@@ -1565,39 +1566,40 @@ function _extValueFromDer(name, der) {
 // ---- subjectDirectoryAttributes compact value codec (draft-20 sec. 3.3 / 8.6 / 8.8, RFC 5280 sec. 4.2.1.8) ----
 // SubjectDirectoryAttributes ::= SEQUENCE SIZE(1..MAX) OF Attribute ::= SEQUENCE { type, values SET OF value }.
 // The compact form is a flat CBOR array [ type1, values1, ... ] where each values slot is ITSELF a non-empty
-// CBOR array -- an Attribute's SET may hold more than one value, unlike a Name's single-value RDN. type is a
+// CBOR array, since an Attribute's SET may hold more than one value where a Name's RDN holds one. type is a
 // sec. 8.6 registry int (the sign selects the string type) with text values, or an unwrapped ~oid with raw DER
 // value bytes (an unregistered type stays compact via its own ~oid form, never dropping the whole extension).
 // The extension-level _tryCompactExtValue round-trip guard is the byte-exactness net.
 
-// A ~oid-form attributeValue must be exactly ONE non-empty, well-formed DER AttributeValue TLV. An empty byte
+// A ~oid-form attributeValue must be exactly one non-empty, well-formed DER AttributeValue TLV. An empty byte
 // string would build a SET OF SIZE 0 (RFC 5280 sec. 4.2.1.8 requires at least one value); a byte string carrying
 // more than one TLV would fan one declared value into several SET members (draft-20 sec. 3.3: one `bytes` is one
 // AttributeValue). There is no downstream DER decoder to catch either (SDA ships c509-only), so the reconstruct
-// arm self-enforces the single-TLV shape rather than splice a degenerate or invalid Attribute.
+// arm self-enforces the single-TLV shape, so a degenerate or invalid Attribute is never spliced.
 // ---- the shared strict-DER gate for a raw-spliced ANY value --------------------------------------
 // Several reconstruct sites splice CALLER/ATTACKER-supplied bytes into the rebuilt certificate verbatim (an
 // AlgorithmIdentifier's `parameters`, a generic otherName's `value [0] EXPLICIT ANY`, a subjectDirectoryAttributes
-// `~oid`-form AttributeValue). asn1.decode validates TLV FRAMING ONLY -- it rejects truncation, trailing bytes and
-// non-minimal lengths, and enforces the DER primitive/constructed rules, but it does NOT check per-type CONTENT:
+// `~oid`-form AttributeValue). asn1.decode validates TLV framing alone. It rejects truncation, trailing bytes and
+// non-minimal lengths, and enforces the DER primitive/constructed rules, but it does not check per-type content:
 // it frames an empty INTEGER, the reserved end-of-contents tag 0, and an out-of-alphabet string quite happily.
-// Splicing those produces a certificate an independent decoder refuses to load, and one this toolkit's OWN readers
-// reject -- so every such site routes through the one gate below instead of a bare asn1.decode.
+// Splicing those produces a certificate an independent decoder refuses to load, and one this toolkit's own readers
+// reject. Every such site therefore routes through the one gate below instead of a bare asn1.decode.
 
 // Every universal PRIMITIVE tag whose content this toolkit can strictly validate, mapped to its reader. A
-// universal primitive OUTSIDE this map has no strict content validator here, so it is REJECTED rather than
-// spliced unchecked. The documented residual: a value whose type this toolkit cannot yet strictly validate is
-// not compact-representable -- VideotexString / GraphicString / GeneralString / ObjectDescriptor / REAL (no
-// content reader in this toolkit), and a fractional-seconds GeneralizedTime (the X.690 sec. 11.7 relaxation is deliberately scoped to the codec
+// universal primitive outside this map has no strict content validator here, so the gate REJECTS it and
+// nothing is spliced unchecked. The documented residual: a value whose type this toolkit cannot yet strictly
+// validate is not compact-representable. The ASN.1 types in that residual are `VideotexString` /
+// `GraphicString` / `GeneralString` / `ObjectDescriptor` / `REAL` (no content reader in this toolkit), and a
+// fractional-seconds GeneralizedTime (the X.690 sec. 11.7 relaxation is deliberately scoped to the codec
 // and RFC 3161 timestamping, and must not creep into a third consumer). On the ENCODE path such a value simply
 // degrades to the byte-exact ~oid + byte-string form, losing nothing; on the DECODE path it is a fail-closed
-// verdict rather than a guess.
+// verdict.
 var _ANY_VALUE_READERS = (function () {
   var m = {}, R = asn1.read, T = asn1.TAGS;
   m[T.BOOLEAN] = R.boolean; m[T.INTEGER] = R.integer; m[T.ENUMERATED] = R.enumerated;
   m[T.BIT_STRING] = R.bitString; m[T.OCTET_STRING] = R.octetString; m[T.NULL] = R.nullValue;
   m[T.OBJECT_IDENTIFIER] = R.oid; m[T.UTC_TIME] = R.time; m[T.GENERALIZED_TIME] = R.time;
-  // NumericString reads through its OWN reader: it is not a DirectoryString type, and routing it through
+  // NumericString reads through its own reader: it is not a DirectoryString type, and routing it through
   // read.string would fold it into the RFC 5280 sec. 7.1 name-comparison identity class (see asn1-der.js).
   m[T.NUMERIC_STRING] = R.numericString;
   [T.UTF8_STRING, T.PRINTABLE_STRING, T.IA5_STRING, T.TELETEX_STRING, T.VISIBLE_STRING, T.BMP_STRING, T.UNIVERSAL_STRING].forEach(function (t) { m[t] = R.string; });
@@ -1605,11 +1607,11 @@ var _ANY_VALUE_READERS = (function () {
 })();
 
 // A universal SET's required member order depends on a type the ANY does not carry: X.690 sec. 11.6 orders a
-// SET OF by the members' full encodings, while a structured SET is ordered by TAG (X.680 sec. 8.6) -- and the two
-// differ whenever the constructed bit does (a SEQUENCE member, tag 16, sorts BEFORE a PrintableString, tag 19, by
-// tag but AFTER it by octets). A structured SET cannot repeat a tag, so a repeated tag proves SET OF and the
+// SET OF by the members' full encodings, while a structured SET is ordered by TAG (X.680 sec. 8.6), and the two
+// differ whenever the constructed bit does (a SEQUENCE member, tag 16, sorts before a PrintableString, tag 19, by
+// tag but after it by octets). A structured SET cannot repeat a tag, so a repeated tag proves SET OF and the
 // octet rule binds; with all-distinct tags either reading is possible, so accept a value that satisfies EITHER
-// (rejecting only what is non-canonical under BOTH readings -- sound in both directions, never a guess).
+// (rejecting only what is non-canonical under both readings: sound in both directions, never a guess).
 var _TAG_CLASS_RANK = { universal: 0, application: 1, context: 2, private: 3 };
 function _setOrderOk(kids) {
   var i, dup = false, seen = {};
@@ -1622,7 +1624,7 @@ function _setOrderOk(kids) {
   for (i = 1; i < kids.length; i++) {
     if (Buffer.compare(kids[i - 1].bytes, kids[i].bytes) > 0) octetAsc = false;
     // Tag order ranks by CLASS first (universal < application < context < private, X.680 sec. 8.6), then by tag
-    // number -- compare the class's NUMBER, never its name (the names do not sort in class order).
+    // number. Compare the class's NUMBER: the names do not sort in class order.
     var pc = _TAG_CLASS_RANK[kids[i - 1].tagClass], cc = _TAG_CLASS_RANK[kids[i].tagClass];
     if (pc !== cc ? pc > cc : kids[i - 1].tagNumber > kids[i].tagNumber) tagAsc = false;
   }
@@ -1632,7 +1634,7 @@ function _setOrderOk(kids) {
 // Strict-validate a decoded DER element at ANY depth, in the caller's error domain. Rejects the reserved EOC tag
 // 0; runs a universal primitive through its strict content reader (or rejects a type with none); recurses into a
 // constructed element's children; and holds a universal SET to a canonical order. Only SEQUENCE and SET are
-// accepted as universal CONSTRUCTED types -- an EXTERNAL / EMBEDDED PDV / CHARACTER STRING has mandatory
+// accepted as universal CONSTRUCTED types. An EXTERNAL / EMBEDDED PDV / CHARACTER STRING has mandatory
 // components this gate cannot verify (the degenerate empty form is not a valid encoding of any of them), so it is
 // refused for the same reason an unvalidatable primitive is. A NON-universal element (a legitimately context- or
 // application-tagged ANY) passes on its framing, but its constructed children are still walked.
@@ -1650,14 +1652,14 @@ function _strictDerElement(node, code, label) {
     return;
   }
   if (node.tagClass === "universal") {
-    // Validate-or-reject: a universal primitive with no strict content reader is NOT accepted on framing alone
+    // Validate-or-reject: a universal primitive with no strict content reader is never accepted on framing alone
     // (asn1.decode frames a malformed NumericString "12 01 40" happily), so the map is exhaustive by refusal.
     var reader = _ANY_VALUE_READERS[node.tagNumber];
     if (!reader) throw _err(code, label + " of universal type " + node.tagNumber + " has no strict DER content validator here");
     try { reader(node); } catch (e) { throw _err(code, label + " is not a valid DER element for its type", e); }
   }
 }
-// Raw ANY bytes about to be spliced verbatim must be exactly ONE non-empty, well-formed AND strictly-valid DER
+// Raw ANY bytes about to be spliced verbatim must be exactly one non-empty, well-formed AND strictly-valid DER
 // element: framing + no-trailing-data via asn1.decode, then content / structure / SET order via
 // _strictDerElement, both reported in the CALLER's error domain. Returns the bytes so a call site can wrap a
 // splice inline. Used by every reconstruct site that emits caller-supplied ANY bytes verbatim.
@@ -1669,8 +1671,8 @@ function _requireStrictDerTlv(content, code, label) {
   return content;
 }
 
-// asn1.build.set SORTS its members, so handing it a non-canonically-ordered values list would SILENTLY rewrite
-// the declared order -- many distinct C509 encodings would reconstruct one and the same certificate. Require the
+// asn1.build.set SORTS its members, so handing it a non-canonically-ordered values list would silently rewrite
+// the declared order, and many distinct C509 encodings would reconstruct one and the same certificate. Require the
 // declared order to already BE canonical, so the compact form maps one-to-one onto the DER it rebuilds.
 function _derSetInDeclaredOrder(vals) {
   for (var i = 1; i < vals.length; i++) {
@@ -1692,12 +1694,12 @@ function _sdaToDer(node, isNative) {
     var vals = [];
     if (typeNode.majorType === 0 || typeNode.majorType === 1) {          // int form: a sec. 8.6 registry alias, text values
       var ti = Number(cbor.read.int(typeNode));
-      // draft sec. 3.1.4 applies to EVERY int in a natively signed certificate, not just the top-level Name's.
+      // draft sec. 3.1.4 applies to every int in a natively signed certificate, not just the top-level Name's.
       if (isNative && ti < 0) throw _err("c509/bad-extensions", "a natively signed C509 subjectDirectoryAttributes attribute type integer must be non-negative (draft sec. 3.1.4), got " + ti);
       var tname = ATTR_BY_INT[Math.abs(ti)];
       if (tname === undefined) throw _err("c509/bad-extensions", "a subjectDirectoryAttributes attribute type int " + ti + " has no C509 sec. 8.6 registry row");
       // countryName / serialNumber carry a CHARACTER restriction (draft sec. 3.1.4 "SHALL contain only
-      // characters from the 74-character ASCII subset permitted by PrintableString"), NOT a sign override --
+      // characters from the 74-character ASCII subset permitted by PrintableString"), and not a sign override --
       // _reconAttrValue asserts the charset and honours the declared string type. Requiring the negative sign
       // here would also make these attributes unrepresentable in a NATIVE certificate, whose ints SHALL all be
       // non-negative (same sec.), so the rule is the charset, not the sign.
@@ -1728,12 +1730,12 @@ function _sdaToDer(node, isNative) {
 
 // One DER Attribute's SET members -> the int-form { sign, values:[CBOR text] }, or null when the int form is
 // not confidently byte-exact (an unregistered type, a non-utf8/printable value, or a SET mixing utf8String and
-// printableString -- one sign cannot express it). A null routes that ONE attribute to the always-byte-exact
+// printableString, which one sign cannot express). A null routes that one attribute to the always-byte-exact
 // ~oid + raw-bytes form (a still-compact sec. 3.3 SDA form); the extension round-trip guard is the ultimate net.
 function _sdaTryIntForm(tint, name, valueNodes) {
   if (tint === undefined) return null;
   var i;
-  // An IA5String-only attribute (emailAddress) rides its non-negative int with IA5String values -- its type,
+  // An IA5String-only attribute (emailAddress) rides its non-negative int with IA5String values. Its type,
   // not a sign, fixes the string type, so it is matched separately from the utf8/printable sign convention.
   if (name === "emailAddress") {
     var mails = [];
@@ -1783,10 +1785,10 @@ function _sdaFromDer(node) {
 
 // Encode-side guard: emit the compact value only when it decodes back to the EXACT DER extnValue, so a
 // non-canonical or unrepresentable value can never produce a lossy compact form (it falls back to ~oid).
-// A value _extValueFromDer produced but _extValueToDer cannot reconstruct -- an empty GeneralNames the DER
-// builder rejects (an AKI authorityCertIssuer [1] with no members), or any future codec asymmetry -- is
-// NOT compact-representable: the round-trip reconstruction throwing is treated identically to a byte
-// mismatch, so encode() falls back to the ~oid form rather than raising on a certificate x509.parse
+// Some values _extValueFromDer produced cannot be reconstructed by _extValueToDer: an empty GeneralNames the
+// DER builder rejects (an AKI authorityCertIssuer [1] with no members), or any future codec asymmetry. None of
+// them is compact-representable, and the round-trip reconstruction throwing is treated identically to a byte
+// mismatch. encode() falls back to the ~oid form and does not raise on a certificate x509.parse
 // accepts. The final encode() self-verify still gates byte-exactness end to end.
 function _tryCompactExtValue(name, der) {
   var compact = _extValueFromDer(name, der);
@@ -1812,7 +1814,7 @@ function _extensions(node, isNative) {
   var out = [];
   var kids = node.children || [];
   // Each extension is an (extensionID, extensionValue) pair; an odd-length array is a dangling
-  // extension identifier with no value -- reject rather than silently drop the trailing element.
+  // extension identifier with no value, so the whole extensions array is rejected.
   if (kids.length % 2 !== 0) throw _err("c509/bad-extensions", "a C509 extensions array must be id/value pairs (dangling extension identifier)");
   // sec. 3.1.10: "If the CBOR array contains exactly two ints and the absolute value of the first int is
   // 2 (corresponding to keyUsage), the CBOR array is omitted and the 'extensions' field is encoded as a
@@ -1831,10 +1833,10 @@ function _extensions(node, isNative) {
       if (name === undefined) throw _err("c509/bad-extensions", "extension type integer " + ei + " has no C509 registry row");
       extOid = oid.byName(name); critical = ei < 0;
       // A registered extension with a compact value form (sec. 3.3) decodes its specific CBOR value to the
-      // DER extnValue inner content. A registered extension WITHOUT one (subjectAltName, until the general-
+      // DER extnValue inner content. A registered extension without one (subjectAltName, until the general-
       // name value codec lands) can only reconstruct a byte-string value (the raw DER extnValue); a
-      // non-byte-string value there is an unsupported compact form and MUST fail closed -- a text/array value
-      // is NOT raw DER, and copying its bytes would reconstruct a structurally invalid extension.
+      // non-byte-string value there is an unsupported compact form and MUST fail closed. A text/array value
+      // is not raw DER, and copying its bytes would reconstruct a structurally invalid extension.
       if (EXT_COMPACT[name]) {
         valContent = _extValueToDer(name, valNode, isNative);
       } else if (valNode.majorType === 2) {
@@ -1845,7 +1847,7 @@ function _extensions(node, isNative) {
     } else {
       var r = _oidName(idNode, "c509/bad-extensions", "an extension id");
       name = r.name; extOid = r.oid;
-      // ~oid extension (sec. 3.1.10): the extnValue is a byte string -- BARE (non-critical) or wrapped in a
+      // ~oid extension (sec. 3.1.10): the extnValue is a byte string, either BARE (non-critical) or wrapped in a
       // single-element array (critical). Validate the shape so a malformed value fails closed at decode.
       critical = valNode.majorType === 4;
       if (critical) {
@@ -1866,7 +1868,7 @@ function _extensions(node, isNative) {
 // ---- type-3 DER reconstruction (byte-exact inversion; draft-20 sec. 3 / sec. 5) ----
 // Type 3 is an INVERTIBLE transform: the reconstruction reproduces the ORIGINAL DER Certificate
 // byte-for-byte (so the original signature verifies). A field outside the covered set fails closed
-// (c509/non-invertible) -- never a partial or best-effort DER.
+// (c509/non-invertible); it never emits a partial or best-effort DER.
 
 // A C509 tag-48 MAC (RFC 9542) reconstructs to the commonName EUI-64 string: a 6-byte value is a 48-bit
 // MAC expanded to the EUI-64 HH-HH-HH-FF-FE-HH-HH-HH by inserting FF-FE; an 8-byte value is the EUI-64.
@@ -1894,7 +1896,7 @@ function _reconAttrValue(rdn) {
   if (rdn.type === "emailAddress") return b.ia5(s);
   // serialNumber / countryName carry a CHARACTER restriction, not a string-type override: draft sec. 3.1.4
   // "SHALL contain only characters from the 74-character ASCII subset permitted by PrintableString". Enforce
-  // that on the CHARACTERS and still honour the sign for the string type -- coercing them to PrintableString
+  // that on the CHARACTERS and still honour the sign for the string type. Coercing them to PrintableString
   // regardless of sign would make the +N and -N encodings of one value reconstruct IDENTICAL DER, so a single
   // X.509 signature would cover two distinct C509 encodings (a malleability window in the type-3 transform).
   // b.printable IS the PrintableString charset authority -- run it for the assert even when the sign selects
@@ -1925,8 +1927,8 @@ function _reconSpki(spkAlg, keyBytes, rsaKey) {
     if (!fieldSize) throw _err("c509/non-invertible", "unsupported EC curve " + spkAlg.curve);
     if (!keyBytes || keyBytes.length === 0) throw _err("c509/non-invertible", "the EC subjectPublicKey byte string is empty");
     var head = keyBytes[0], point;
-    // The point length must match the curve field size for its encoding -- an uncompressed 0x04 point is
-    // 1 + 2*fieldSize, a compressed 0x02/0x03/0xFE/0xFD point is 1 + fieldSize -- so a truncated / padded
+    // The point length must match the curve field size for its encoding: an uncompressed 0x04 point is
+    // 1 + 2*fieldSize, and a compressed 0x02/0x03/0xFE/0xFD point is 1 + fieldSize. A truncated / padded
     // point cannot be re-emitted as a valid (or byte-exact) SubjectPublicKeyInfo.
     if (head === 0x04) {
       if (keyBytes.length !== 1 + 2 * fieldSize) throw _err("c509/non-invertible", "uncompressed EC point length " + keyBytes.length + " does not match " + spkAlg.curve);
@@ -1984,7 +1986,7 @@ function _reconExtensions(exts) {
 function _reconAlgId(alg) {
   var fields = [b.oid(alg.oid)];
   if (alg.parameters && alg.parameters.length) {
-    // AlgorithmIdentifier.parameters is ANY, spliced verbatim -- so it gets the SAME strict gate as every other
+    // AlgorithmIdentifier.parameters is ANY, spliced verbatim, so it gets the same strict gate as every other
     // raw-ANY splice, not just a framing check. Framing alone admits an empty INTEGER / reserved tag 0 / a
     // non-minimal INTEGER, each of which reconstructs an AlgorithmIdentifier that an independent X.509 decoder
     // refuses to load and that this toolkit's own readers reject.
@@ -2014,18 +2016,18 @@ function _reconstructDer(r, sigNode) {
     _reconSpki(r.subjectPublicKeyAlgorithm, r.subjectPublicKey, r.rsaPublicKey),
   ];
   // RFC 5280 sec. 4.1: the [3] extensions field is OPTIONAL and, when present, SHALL contain at least one
-  // extension -- an empty C509 extensions array reconstructs to an OMITTED field, not an empty SEQUENCE.
+  // extension, so an empty C509 extensions array reconstructs to an OMITTED field, not an empty SEQUENCE.
   if (r.extensions.length) tbsFields.push(_reconExtensions(r.extensions));
   var tbs = b.sequence(tbsFields);
   // The signature is re-wrapped as a DER ECDSA-Sig-Value from the fixed-width r||s, so only an ECDSA
   // signature algorithm is in the type-3 reconstruction covered set (an RSA/EdDSA signature is raw bytes,
-  // not r||s -- rejected rather than mis-wrapped). A wrong-length r||s surfaces the caller's typed code.
+  // not r||s, so it is rejected). A wrong-length r||s surfaces the caller's typed code.
   if (!/^ecdsa/i.test(r.signatureAlgorithm.name || "")) {
     throw _err("c509/non-invertible", "type-3 signature reconstruction covers only ECDSA; got " + r.signatureAlgorithm.name);
   }
-  // The fixed-width r||s must split at a real curve field width -- P-256/384/521 = 64/96/132 bytes
+  // The fixed-width r||s must split at a real curve field width: P-256/384/521 = 64/96/132 bytes
   // (RFC 9053 sec. 2.1). A width that is not 2x a supported field size is not a valid ECDSA signature and
-  // cannot be re-wrapped byte-exact; surface the caller's typed code rather than split at a bogus offset.
+  // cannot be re-wrapped byte-exact, so it surfaces the caller's typed code.
   var coordLen = r.signatureValue.length / 2;
   if (coordLen !== 32 && coordLen !== 48 && coordLen !== 66) {
     throw _err("c509/bad-signature", "the type-3 ECDSA signature width " + r.signatureValue.length + " is not a valid fixed-width r||s (expected 64/96/132 for P-256/384/521)");
@@ -2047,7 +2049,7 @@ function _reconstructDer(r, sigNode) {
  * Returns the decoded fields (c509CertificateType 2 native or 3 re-encoded); a malformed shape throws a
  * typed C509Error carrying the inner cbor/asn1 fault as .cause. It decodes CBOR, not DER, so it is
  * reached by an explicit call and is not auto-routed by pki.schema.parse. The type-2 signedData and the
- * raw signature are surfaced RAW (a native verifier hashes them without re-serialization).
+ * raw signature are surfaced as-is (a native verifier hashes them without re-serialization).
  *
  * @example
  *   // the RFC 7925 profiled certificate from draft-ietf-cose-cbor-encoded-cert Appendix A.1 (type 3)
@@ -2304,13 +2306,13 @@ function _encodeC509Array(r) {
  * @spec       draft-ietf-cose-cbor-encoded-cert, RFC 8949, RFC 9090
  * @related    pki.schema.c509.parse
  *
- * Encode a C509 certificate to its deterministic-CBOR bytes -- the producing-side inverse of
+ * Encode a C509 certificate to its deterministic-CBOR bytes. This is the producing-side inverse of
  * `pki.schema.c509.parse`. `input` is either a DER X.509 v3 certificate (a Buffer or PEM string), which is
  * forward-transformed to a **type-3** C509 (a compact CBOR re-encoding whose signature is copied from the
  * source and re-expressed as a fixed-width r||s, so `parse(encode(der)).reconstructedDer` reproduces the
  * original DER byte for byte and the original signature still verifies), or a `pki.schema.c509.parse`
  * result object, which is re-emitted to its native deterministic-CBOR array. The emission is canonical
- * deterministic CBOR (RFC 8949 sec. 4.2) -- shortest-form heads, definite lengths, sorted map keys, and the
+ * deterministic CBOR (RFC 8949 sec. 4.2): shortest-form heads, definite lengths, sorted map keys, and the
  * registry integer shorthand for every registered algorithm / attribute / extension. It is signing-free (a
  * byte transform, like `pki.ct.encodeSctList`); a shape outside the covered set throws a typed `C509Error`.
  *
@@ -2318,7 +2320,7 @@ function _encodeC509Array(r) {
  * carry. It is resolved authoritatively (never a magnitude guess, and matching issuer/subject Names are not
  * taken as proof of self-signing): from `opts.issuerCurve`, or from the RFC 5480 standard digest<->curve
  * pairing the signature algorithm implies. A certificate signed with a non-standard digest/curve pairing
- * (its r/s wider than the digest's standard curve) fails closed -- supply the issuer curve via
+ * (its r/s wider than the digest's standard curve) fails closed; supply the issuer curve via
  * `opts.issuerCurve`.
  *
  * @opts