@blamejs/pki 0.6.14 → 0.6.15

package/lib/asn1-der.js

@@ -35,30 +35,17 @@ var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
-// The list test at each builder door decides whether a caller's argument is refused. Read at the
-// moment it runs, a replacement answering true admits a non-list and the door it guards is gone.
 var _isArray = intrinsic.isArray;
 var _charCodeAt = intrinsic.uncurry(String.prototype.charCodeAt);
 
 var Asn1Error = frameworkError.Asn1Error;
 var OidError = frameworkError.OidError;
 
-// (code, message) -> Asn1Error, the factory shape the composed guards throw
-// through so a malformed codec argument keeps the asn1/* typed verdict.
 function _asn1Error(c, m) { return new Asn1Error(c, m); }
 
-// (code, message) -> OidError, the factory the OID string guard throws through
-// so build.oid keeps its oid/* typed verdict (oid/bad-input, oid/bad-arc).
 function _oidErr(c, m) { return new OidError(c, m); }
 
-// ---- Tag constants (universal class) --------------------------------
 
-// L1 -- the ASN.1 universal-type descriptor registry: the single source of
-// truth for the codec's type metadata. Each entry is DECLARATIVE DATA --
-// { tag, form } where form is the DER encoding form ("primitive" or
-// "constructed", X.690 sec. 8/sec. 10.2). TAGS and the two structural type-sets below
-// are all DERIVED from it, so registering a universal type is one descriptor
-// entry and the decoder's form checks (below) cover it automatically.
 var UNIVERSAL_TYPES = {
   BOOLEAN:           { tag: 0x01, form: "primitive" },
   INTEGER:           { tag: 0x02, form: "primitive" },
@@ -84,8 +71,6 @@ var UNIVERSAL_TYPES = {
   BMP_STRING:        { tag: 0x1e, form: "primitive" },
 };
 
-// TAGS { name: tag }, derived from the registry; the public constant consumers
-// read (pki.asn1.TAGS.INTEGER, ...).
 var TAGS = {};
 Object.keys(UNIVERSAL_TYPES).forEach(function (k) { TAGS[k] = UNIVERSAL_TYPES[k].tag; });
 
@@ -95,15 +80,6 @@ var CLASS_CONTEXT     = 0x80;
 var CLASS_PRIVATE     = 0xc0;
 var CONSTRUCTED_BIT   = 0x20;
 
-// X.690 sec. 8.9.1 / sec. 8.11.1 / sec. 10.2 (DER), the mirror rules: an
-// always-constructed universal type (SEQUENCE, SET, and the SEQUENCE-based
-// EXTERNAL / EMBEDDED PDV / unrestricted CHARACTER STRING) MUST be encoded
-// constructed, and every other universal type MUST be encoded primitive. The
-// constructed-capable set is derived from the registry above and keyed by tag
-// for an O(1) decode-time form check. It is a whitelist: a universal tag
-// outside it, a registered primitive type and an unregistered one
-// (GeneralString, ObjectDescriptor, REAL, ...) alike, has no
-// DER constructed form, so the default is reject.
 var CONSTRUCTED_ONLY_UNIVERSAL_TAGS = Object.create(null);
 Object.keys(UNIVERSAL_TYPES).forEach(function (k) {
   var d = UNIVERSAL_TYPES[k];
@@ -116,7 +92,6 @@ function _className(bits) {
     case CLASS_APPLICATION: return "application";
     case CLASS_CONTEXT:     return "context";
     case CLASS_PRIVATE:     return "private";
-    // Coverage residual -- tagClassBits is (first & 0xc0), always one of the 4 enumerated class values; the default arm is unreachable defensive code.
     default:                return "universal";
   }
 }
@@ -125,7 +100,6 @@ function _asBuffer(input, who) {
   return guard.bytes.view(input, Asn1Error, "asn1/not-buffer", who);
 }
 
-// ---- Decoder --------------------------------------------------------
 
 /**
  * @primitive  pki.asn1.decode
@@ -169,15 +143,8 @@ function _asBuffer(input, who) {
 function decode(input, opts) {
   opts = opts || {};
   var buf = _asBuffer(input, "decode");
-  // A size/depth cap opt: absent means the constants.LIMITS default; a provided
-  // value must be a non-negative integer (guard.limits.cap). depthCap also
-  // refuses a maxDepth above the stack-safe ceiling so a raised cap cannot drive
-  // recursive descent into a bare RangeError instead of the typed asn1/too-deep.
   var maxBytes = guard.limits.cap(opts.maxBytes, "maxBytes", constants.LIMITS.DER_MAX_BYTES);
   var maxDepth = guard.limits.depthCap(opts.maxDepth, "maxDepth", constants.LIMITS.DER_MAX_DEPTH);
-  // Total decoded-node ceiling: the eager node tree lets a dense run of tiny TLVs
-  // amplify a small input into a huge tree, so a per-node counter fails closed at
-  // the cap (the memory-fanout class the CBOR codec closed with CBOR_MAX_ITEMS).
   var maxItems = guard.limits.cap(opts.maxItems, "maxItems", constants.LIMITS.DER_MAX_ITEMS);
   if (buf.length > maxBytes) {
     throw new Asn1Error("asn1/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
@@ -194,7 +161,7 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
   if (depth > maxDepth) {
     throw new Asn1Error("asn1/too-deep", "nesting exceeds depth cap " + maxDepth);
   }
-  if (ctr) ctr.tick();   // one decoded node -> one tick (memory-fanout cap)
+  if (ctr) ctr.tick();
   var p = start;
   if (p >= limit) throw new Asn1Error("asn1/truncated", "expected an identifier octet");
   var first = buf[p]; p += 1;
@@ -203,7 +170,6 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
   var tagNumber = first & 0x1f;
 
   if (tagNumber === 0x1f) {
-    // High-tag-number form: base-128, minimal (no leading 0x80).
     tagNumber = 0;
     var seen = 0;
     for (;;) {
@@ -222,29 +188,10 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
     }
   }
 
-  // X.690 8.9.1 / 8.11.1 -- an always-constructed universal type (SEQUENCE, SET,
-  // EXTERNAL, EMBEDDED PDV, CHARACTER STRING) is always constructed; a
-  // primitive-tagged one is not valid DER (and would decode to a leaf that
-  // constructed-structure consumers dereference as a parent). Driven by the
-  // registry-derived set, not a hardcoded tag list.
   if (tagClassBits === CLASS_UNIVERSAL && CONSTRUCTED_ONLY_UNIVERSAL_TAGS[tagNumber] && !constructed) {
     throw new Asn1Error("asn1/bad-tlv", "a universal constructed-only type (SEQUENCE/SET/EXTERNAL/EMBEDDED PDV/CHARACTER STRING) must be constructed");
   }
 
-  // X.690 sec. 8.x / sec. 10.2 -- the mirror rule: a universal type other than
-  // SEQUENCE/SET (INTEGER, OID, BOOLEAN, every restricted string type --
-  // registered or not -- times, BIT/OCTET STRING, REAL, ...) encoded
-  // constructed is not valid DER. Without this a constructed string tag
-  // decodes to a childless node that later paths (an X.509 DN attribute
-  // value) would hex-render or dereference instead of failing closed; the
-  // constructed-capable set is a whitelist so an UNREGISTERED string type
-  // (a constructed GeneralString) cannot slip past the form check either.
-  // The ber mode licenses exactly one constructed primitive-only type -- the
-  // OCTET STRING (the streamed content carrier RFC 7292 sec. 4.1 permits); its
-  // segments are reassembled below. Every other primitive-only type stays
-  // primitive even in BER. Reassembly re-copies each nesting level's payload,
-  // so nesting is capped on the way down: real producers segment one level
-  // deep, and a deep chain multiplies transient memory without carrying data.
   if (tagClassBits === CLASS_UNIVERSAL && constructed && !CONSTRUCTED_ONLY_UNIVERSAL_TAGS[tagNumber]) {
     if (!(ber && tagNumber === TAGS.OCTET_STRING)) {
       throw new Asn1Error("asn1/constructed-primitive-type", "a universal primitive-only type must be encoded primitive in DER");
@@ -261,8 +208,6 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
   if (lenByte < 0x80) {
     length = lenByte;
   } else if (lenByte === 0x80) {
-    // X.690 sec. 8.1.3.6 -- indefinite length is only defined for a constructed
-    // encoding; the value runs to the end-of-contents octets.
     if (!ber || !constructed) {
       throw new Asn1Error("asn1/indefinite-length", "indefinite length is not valid DER");
     }
@@ -326,12 +271,6 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
     bytes:        buf.subarray(start, end),
   };
 
-  // BER reassembly: a constructed OCTET STRING's segments concatenate into
-  // one primitive content, so every downstream reader sees the value a
-  // single-segment encoding would carry; `bytes` keeps the original wire
-  // range for raw round-trip surfaces. Nested constructed segments arrive
-  // already reassembled by the recursion (their nesting depth is capped on
-  // the way down -- see the strDepth check above).
   if (ber && constructed && tagClassBits === CLASS_UNIVERSAL && tagNumber === TAGS.OCTET_STRING) {
     var segments = [];
     for (var s = 0; s < children.length; s++) {
@@ -344,17 +283,12 @@ function _decodeTLV(buf, start, limit, depth, maxDepth, ber, strDepth, ctr) {
     node.constructed = false;
     node.children = null;
   }
-  // A context-tagged constructed node from a ber decode may be an IMPLICIT
-  // streamed string (the tag hides the underlying type), which only the
-  // schema-driven typed reader can identify -- mark it so readers reassemble
-  // exactly those nodes and a strict decode's verdicts never change.
   if (ber && constructed && tagClassBits === CLASS_CONTEXT && node.children) {
     node.ber = true;
   }
   return { node: node, end: end };
 }
 
-// ---- Node assertions ------------------------------------------------
 
 function _expectUniversal(node, tag, who) {
   if (node.tagClass !== "universal" || node.tagNumber !== tag) {
@@ -367,7 +301,6 @@ function _expectPrimitive(node, who) {
   if (node.constructed) throw new Asn1Error("asn1/expected-primitive", who + ": expected a primitive encoding");
 }
 
-// ---- Typed readers --------------------------------------------------
 
 function readBoolean(node) {
   _expectUniversal(node, TAGS.BOOLEAN, "readBoolean");
@@ -379,21 +312,10 @@ function readBoolean(node) {
   throw new Asn1Error("asn1/bad-boolean", "DER BOOLEAN must be 0x00 or 0xFF, got 0x" + v.toString(16));
 }
 
-// INTEGER and ENUMERATED share DER content encoding (a two's-complement big-endian
-// value) but are DISTINCT universal types. This decodes that shared content -- the
-// caller asserts the tag first. `typeName` names the type in error messages; the
-// stable error codes stay the integer family (a caller switching on `code` treats
-// both alike since the encoding is identical).
 function _readIntegerLikeContent(node, typeName, who) {
   _expectPrimitive(node, who);
   var c = node.content;
   if (c.length === 0) throw new Asn1Error("asn1/bad-integer", typeName + " must have at least 1 content octet");
-  // Defense-in-depth: refuse an over-cap magnitude before touching BigInt.
-  // A one-shot hex parse is linear, but the length still bounds worst-case
-  // work -- reject a hostile length prefix up front. The cap bounds the
-  // MAGNITUDE; a positive INTEGER whose top bit is set carries one leading
-  // 0x00 DER sign octet, so allow cap + 1 content bytes (an RSA-131072
-  // modulus is 16384 magnitude bytes plus that sign pad).
   if (c.length > constants.LIMITS.DER_MAX_INTEGER_BYTES + 1) {
     throw new Asn1Error("asn1/integer-too-large",
       typeName + " content " + c.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
@@ -403,32 +325,20 @@ function _readIntegerLikeContent(node, typeName, who) {
     if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative " + typeName);
   }
   var neg = (c[0] & 0x80) !== 0;
-  // Coverage residual -- the c.length===0 guard above throws, so c.length is always >=1 here; the 0n alternate is unreachable.
   var mag = c.length ? BigInt("0x" + Buffer.from(c).toString("hex")) : 0n;
   return neg ? mag - (1n << BigInt(c.length * 8)) : mag;
 }
 
-// read.integer is STRICT on the tag: an ENUMERATED node (which shares INTEGER's
-// content encoding) is NOT accepted here. Coercing an ENUMERATED to an INTEGER is a
-// type confusion -- an INTEGER-pinned field (a certificate/CSR version, a serial
-// number, a cRLNumber) encoded as ENUMERATED would slip past a lenient reader.
-// Read ENUMERATED values with read.enumerated.
 function readInteger(node) {
   _expectUniversal(node, TAGS.INTEGER, "readInteger");
   return _readIntegerLikeContent(node, "INTEGER", "readInteger");
 }
 
-// read.enumerated reads an ENUMERATED value; its content rules are identical to
-// INTEGER (non-empty, minimally encoded, magnitude within the cap).
 function readEnumerated(node) {
   _expectUniversal(node, TAGS.ENUMERATED, "readEnumerated");
   return _readIntegerLikeContent(node, "ENUMERATED", "readEnumerated");
 }
 
-// Read a [tag] IMPLICIT INTEGER -- a context-class PRIMITIVE node whose content is an
-// integer body (the IMPLICIT tag replaces the universal INTEGER tag). Same minimal
-// two's-complement content rules as a universal INTEGER. The integer counterpart of
-// readBitStringImplicit, for the RFC 3161 Accuracy millis [0] / micros [1] fields.
 function readIntegerImplicit(node, tag) {
   if (node.tagClass !== "context" || node.tagNumber !== tag) {
     throw new Asn1Error("asn1/unexpected-tag", "readIntegerImplicit: expected context tag [" + tag +
@@ -437,9 +347,6 @@ function readIntegerImplicit(node, tag) {
   return _readIntegerLikeContent(node, "INTEGER", "readIntegerImplicit");
 }
 
-// The BIT STRING content decoder (the leading unused-bit octet + body, with the
-// DER zero-pad rule). Shared by the universal reader and the IMPLICIT
-// context-tagged reader -- the caller asserts the tag first.
 function _readBitStringContent(node, who) {
   _expectPrimitive(node, who);
   var c = node.content;
@@ -447,8 +354,6 @@ function _readBitStringContent(node, who) {
   var unusedBits = c[0];
   if (unusedBits > 7) throw new Asn1Error("asn1/bad-bit-string", "unused-bit count " + unusedBits + " > 7");
   if (unusedBits > 0 && c.length === 1) throw new Asn1Error("asn1/bad-bit-string", "unused bits declared over an empty body");
-  // X.690 11.2.1 -- the declared unused low bits of the final octet must be
-  // zero in DER.
   if (unusedBits > 0 && c.length > 1) {
     var mask = (1 << unusedBits) - 1;
     if ((c[c.length - 1] & mask) !== 0) throw new Asn1Error("asn1/bad-bit-string", "DER requires unused bits to be zero");
@@ -461,10 +366,6 @@ function readBitString(node) {
   return _readBitStringContent(node, "readBitString");
 }
 
-// Read a [tag] IMPLICIT BIT STRING -- a context-class PRIMITIVE node whose content
-// is a bit-string body (identical content rules to a universal BIT STRING). The
-// IMPLICIT tag replaces the universal one, so there is no inner universal node.
-// Used for the PKCS#8 OneAsymmetricKey publicKey [1] (RFC 5958 sec. 2).
 function readBitStringImplicit(node, tag) {
   if (node.tagClass !== "context" || node.tagNumber !== tag) {
     throw new Asn1Error("asn1/unexpected-tag", "readBitStringImplicit: expected context tag [" + tag +
@@ -479,16 +380,6 @@ function readOctetString(node) {
   return node.content;
 }
 
-// Read a [tag] IMPLICIT OCTET STRING -- a context-class PRIMITIVE node whose
-// content is the octet-string body (the IMPLICIT tag replaces the universal one,
-// so there is no inner universal node). Primitive-only, like its universal
-// counterpart, so a strict decode's constructed/streamed form is rejected.
-// A node from a ber decode (the `ber` marker) may carry the streamed form --
-// the context tag hides the underlying type from the decoder, so THIS reader
-// is where a [tag] IMPLICIT OCTET STRING's segments reassemble (the shape CMS
-// ciphertext streams as). Used for the CMS SignerIdentifier
-// subjectKeyIdentifier [0] (RFC 5652 sec. 5.3) and EncryptedContentInfo
-// encryptedContent [0] (sec. 6.1).
 function readOctetStringImplicit(node, tag) {
   if (node.tagClass !== "context" || node.tagNumber !== tag) {
     throw new Asn1Error("asn1/unexpected-tag", "readOctetStringImplicit: expected context tag [" + tag +
@@ -516,10 +407,6 @@ function readNull(node) {
   return null;
 }
 
-// Read a [tag] IMPLICIT BOOLEAN -- a context-class PRIMITIVE node whose single
-// content octet obeys the DER BOOLEAN rules (0x00 FALSE / 0xFF TRUE; anything
-// else rejected). The IMPLICIT tag replaces the universal BOOLEAN tag. Used for
-// the RFC 5280 sec. 5.2.5 IssuingDistributionPoint scope flags.
 function readBooleanImplicit(node, tag) {
   if (node.tagClass !== "context" || node.tagNumber !== tag) {
     throw new Asn1Error("asn1/unexpected-tag", "readBooleanImplicit: expected context tag [" + tag +
@@ -533,10 +420,6 @@ function readBooleanImplicit(node, tag) {
   throw new Asn1Error("asn1/bad-boolean", "DER BOOLEAN must be 0x00 or 0xFF, got 0x" + v.toString(16));
 }
 
-// Read a [tag] IMPLICIT NULL -- a context-class PRIMITIVE node with empty content.
-// The IMPLICIT tag replaces the universal NULL tag, so there is no inner universal
-// node. The empty-content and primitive-form rules of a universal NULL still hold.
-// Used for the OCSP CertStatus good [0] / unknown [2] arms (RFC 6960 sec. 4.2.1).
 function readNullImplicit(node, tag) {
   if (node.tagClass !== "context" || node.tagNumber !== tag) {
     throw new Asn1Error("asn1/unexpected-tag", "readNullImplicit: expected context tag [" + tag +
@@ -576,16 +459,11 @@ function decodeOidContent(buf) {
   for (var i = 0; i < buf.length; i++) {
     var b = buf[i];
     if (i === arcStart && b === 0x80) throw new OidError("oid/non-minimal", "non-minimal sub-identifier (leading 0x80)");
-    // Cap the continuation-byte run so a single arc can't drive unbounded
-    // BigInt growth before it terminates.
     if (i - arcStart >= constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES) {
       throw new OidError("oid/subidentifier-too-large",
         "OID sub-identifier exceeds " + constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES + " octets");
     }
     if ((b & 0x80) === 0) {
-      // Terminal octet: fold the whole [arcStart..i] slice base-128 in one
-      // bounded pass (the run is capped above), no per-bit accumulation
-      // across the full OID content.
       var value = 0n;
       for (var k = arcStart; k <= i; k++) value = value * 128n + BigInt(buf[k] & 0x7f);
       arcs.push(value);
@@ -607,7 +485,6 @@ function _decodeText(buf, encoding) {
   return buf.toString(encoding);
 }
 
-// IA5String is 7-bit ASCII (T.50 / IA5) -- every content octet is 0x00..0x7F.
 function _decodeIa5(buf) {
   for (var i = 0; i < buf.length; i++) {
     if (buf[i] > 0x7F) throw new Asn1Error("asn1/bad-ia5-string", "IA5String requires 7-bit ASCII");
@@ -615,8 +492,6 @@ function _decodeIa5(buf) {
   return buf.toString("latin1");
 }
 
-// VisibleString (ISO 646 IRV / X.690) is the printable ASCII range 0x20..0x7E
-// -- no control characters and no bytes with the high bit set.
 function _decodeVisible(buf) {
   for (var i = 0; i < buf.length; i++) {
     if (buf[i] < 0x20 || buf[i] > 0x7E) throw new Asn1Error("asn1/bad-visible-string", "VisibleString must be 0x20..0x7E");
@@ -624,23 +499,12 @@ function _decodeVisible(buf) {
   return buf.toString("latin1");
 }
 
-// PrintableString is restricted to A-Z a-z 0-9 space and ' ( ) + , - . / : = ?
 function _decodePrintable(buf) {
   var s = buf.toString("latin1");
   if (!isPrintableString(s)) throw new Asn1Error("asn1/bad-printable-string", "PrintableString has characters outside the restricted set");
   return s;
 }
 
-// NumericString (X.680 sec. 41, Table 9) permits ONLY the digits and SPACE. It carries the X.520 syntax of the
-// x121Address and internationalISDNNumber directory attributes.
-//
-// It is read through its OWN reader, deliberately NOT through readString. Every type readString returns a
-// plain string for enters the RFC 5280 sec. 7.1 name-comparison identity class, and
-// guard.name.dnEqual -- the single choke point for name chaining, revocation-issuer matching and name
-// constraints -- compares the strings it returns. Admitting NumericString there would make a NumericString
-// attribute value compare EQUAL to a PrintableString / UTF8String one with the same characters, silently
-// widening distinguished-name identity across the whole toolkit. A caller that genuinely wants this type asks
-// for it by name.
 function readNumericString(node) {
   _expectUniversal(node, TAGS.NUMERIC_STRING, "readNumericString");
   _expectPrimitive(node, "readNumericString");
@@ -649,8 +513,6 @@ function readNumericString(node) {
   return s;
 }
 
-// UTF8String must be well-formed UTF-8; a lenient decoder substitutes U+FFFD
-// for invalid sequences, silently mangling hostile input into valid text.
 function _decodeUtf8Strict(buf) {
   try {
     return new TextDecoder("utf-8", { fatal: true }).decode(buf);
@@ -677,8 +539,6 @@ function readString(node) {
 
 function _decodeUtf16be(buf) {
   if (buf.length % 2 !== 0) throw new Asn1Error("asn1/bad-bmp-string", "BMPString length must be even");
-  // BMPString encodes BMP scalar values only; a UTF-16 surrogate code unit
-  // here is a lone surrogate, not valid text.
   for (var i = 0; i < buf.length; i += 2) {
     var u = (buf[i] << 8) | buf[i + 1];
     if (u >= 0xD800 && u <= 0xDFFF) throw new Asn1Error("asn1/bad-bmp-string", "code point out of range");
@@ -693,8 +553,6 @@ function _decodeUtf32be(buf) {
   var out = "";
   for (var i = 0; i < buf.length; i += 4) {
     var cp = (buf[i] * 0x1000000) + (buf[i + 1] << 16) + (buf[i + 2] << 8) + buf[i + 3];
-    // Reject non-scalar values (> U+10FFFF or a surrogate) before
-    // String.fromCodePoint would throw a bare RangeError / emit a lone surrogate.
     if (cp > 0x10FFFF || (cp >= 0xD800 && cp <= 0xDFFF)) {
       throw new Asn1Error("asn1/bad-universal-string", "code point out of range");
     }
@@ -703,9 +561,6 @@ function _decodeUtf32be(buf) {
   return out;
 }
 
-// Exactly `count` ASCII digits at `start`, as an integer, or null on any non-digit or short read.
-// Character-scanned so no regex match protocol -- a live, replaceable `exec` -- stands between the
-// codec and the time field it slices out.
 function _digitsToInt(s, start, count) {
   if (start + count > s.length) return null;
   var v = 0;
@@ -717,12 +572,6 @@ function _digitsToInt(s, start, count) {
   return v;
 }
 
-// The fixed DER time layout, scanned into its components, or null on any format violation:
-// yearLen digits (2 for UTCTime YY, 4 for GeneralizedTime YYYY), then MM DD HH MM SS, then --
-// when allowFrac -- the X.690 sec. 11.7 fractional-seconds profile (a "." decimal separator, never
-// ",", and a non-empty fraction), then a terminating "Z" as the final character with nothing after.
-// `ms` is the first three fraction digits right-zero-padded (matching (frac + "000").slice(0,3));
-// `fracLastIsZero` carries the sec. 11.7.3 trailing-zero check the caller enforces.
 function _scanTimeFields(s, yearLen, allowFrac) {
   var pos = 0;
   var year = _digitsToInt(s, pos, yearLen); if (year === null) return null; pos += yearLen;
@@ -733,7 +582,7 @@ function _scanTimeFields(s, yearLen, allowFrac) {
   var sec = _digitsToInt(s, pos, 2); if (sec === null) return null; pos += 2;
   var hasFrac = false, ms = 0, fracLastIsZero = false;
   if (allowFrac) {
-    if (_charCodeAt(s, pos) !== 46) return null; // "."
+    if (_charCodeAt(s, pos) !== 46) return null;
     pos += 1;
     var f = [0, 0, 0], fi = 0;
     while (pos < s.length) {
@@ -742,21 +591,16 @@ function _scanTimeFields(s, yearLen, allowFrac) {
       if (fi < 3) f[fi] = c - 48;
       fi += 1; pos += 1;
     }
-    if (fi === 0) return null; // a non-empty fraction is required
+    if (fi === 0) return null;
     hasFrac = true;
     fracLastIsZero = _charCodeAt(s, pos - 1) === 48;
     ms = f[0] * 100 + f[1] * 10 + f[2];
   }
-  if (pos !== s.length - 1 || _charCodeAt(s, pos) !== 90) return null; // trailing "Z", nothing after
+  if (pos !== s.length - 1 || _charCodeAt(s, pos) !== 90) return null;
   return { year: year, month: month, day: day, hour: hour, min: min, sec: sec,
            hasFrac: hasFrac, ms: ms, fracLastIsZero: fracLastIsZero };
 }
 
-// readTime(node, opts?) -- opts.allowFractional enables the RFC 3161 / X.690 sec. 11.7
-// fractional-seconds GeneralizedTime profile. Fractional is OFF by default because
-// most profiles (RFC 5280 certificate/CRL Validity, sec. 4.1.2.5.2) require the integer-
-// second YYYYMMDDHHMMSSZ form and MUST NOT include a fraction; only callers that
-// permit sub-second precision (TSP genTime) pass allowFractional.
 function readTime(node, opts) {
   if (node.tagClass !== "universal") throw new Asn1Error("asn1/expected-time", "readTime: not a universal time type");
   _expectPrimitive(node, "readTime");
@@ -766,7 +610,6 @@ function readTime(node, opts) {
     t = _scanTimeFields(s, 2, false);
     if (!t) throw new Asn1Error("asn1/bad-utctime", "UTCTime must be YYMMDDHHMMSSZ, got " + JSON.stringify(s));
     year = t.year;
-    // RFC 5280 sec. 4.1.2.5.1 -- YY < 50 => 20YY, else 19YY.
     year += (year < 50) ? 2000 : 1900;
   } else if (node.tagNumber === TAGS.GENERALIZED_TIME) {
     t = _scanTimeFields(s, 4, false);
@@ -774,13 +617,6 @@ function readTime(node, opts) {
       if (!(opts && opts.allowFractional)) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSSZ, got " + JSON.stringify(s));
       t = _scanTimeFields(s, 4, true);
       if (!t) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSS[.fraction]Z, got " + JSON.stringify(s));
-      // X.690 sec. 11.7.3 -- the fractional part MUST NOT end in a zero (and is non-empty
-      // by the scan). ".5Z" is valid; ".50Z" and ".500Z" are non-canonical. X.690
-      // sec. 11.7 places NO cap on the fraction length (RFC 3161 sec. 2.4.2 gives the 5-digit
-      // example 19990609001326.34352Z), so a fraction of any length is accepted; the
-      // returned Date is millisecond-precision, and a caller needing the exact fraction
-      // reads it from node.content (the raw bytes, surfaced losslessly like the OID /
-      // serial paths).
       if (t.fracLastIsZero) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime fraction must not have trailing zeros, got " + JSON.stringify(s));
     }
     year = t.year;
@@ -792,22 +628,11 @@ function readTime(node, opts) {
   var hour  = t.hour;
   var min   = t.min;
   var sec   = t.sec;
-  // Build from the LITERAL year via setUTCFullYear: the Date.UTC() / new Date()
-  // constructors remap a year in 0..99 to 1900..1999, which would corrupt a
-  // GeneralizedTime year below 100 (0099 -> 1999). setUTCFullYear(year, ...)
-  // takes the year literally and uses that year's own calendar, so years
-  // below 100 and proleptic leap years are handled correctly.
-  // A fractional GeneralizedTime carries sub-second precision; surface it on the
-  // Date at millisecond resolution (the first three fraction digits, zero-padded).
   var ms = (node.tagNumber === TAGS.GENERALIZED_TIME && t.hasFrac) ? t.ms : 0;
   var d = new Date(0);
   d.setUTCFullYear(year, month - 1, day);
   d.setUTCHours(hour, min, sec, ms);
-  // Coverage residual -- scan-validated fields are finite integers and Date rolls over (never NaN); out-of-range is caught by the component round-trip check below.
   if (isNaN(guard.time.instantOf(d))) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
-  // Date/setUTC* silently roll over out-of-range fields (Feb 30 -> Mar 2,
-  // month 13 -> next Jan, hour 25 -> +1 day). Reject unless every component
-  // round-trips exactly.
   if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day ||
       d.getUTCHours() !== hour || d.getUTCMinutes() !== min || d.getUTCSeconds() !== sec) {
     throw new Asn1Error("asn1/bad-time", "time component out of range " + JSON.stringify(s));
@@ -815,7 +640,6 @@ function readTime(node, opts) {
   return d;
 }
 
-// ---- Encoder / builders ---------------------------------------------
 
 function encodeLength(n) {
   if (typeof n !== "number" || !isFinite(n) || n < 0 || Math.floor(n) !== n) {
@@ -829,24 +653,12 @@ function encodeLength(n) {
   return Buffer.concat([Buffer.from([0x80 | bytes.length]), Buffer.from(bytes)]);
 }
 
-// The DER of a universal SEQUENCE recovered from a decoded IMPLICIT [n] SEQUENCE
-// `node`, whose context tag replaced the universal 0x30 on the wire (e.g. an RFC
-// 4211 CertTemplate publicKey [6] SubjectPublicKeyInfo, or a POPOSigningKey
-// poposkInput [0]): the field's value is imported / signed as a standalone SEQUENCE,
-// not as the context-tagged wire form. A constructed node exposes its content as
-// `children` (not `content`), so the content is those children's DER concatenated;
-// the identifier becomes the SEQUENCE tag and the length is canonical DER.
 function sequenceTlv(node) {
-  // Coverage residual -- a decoded node with content==null is always constructed with a children array; the || [] guards a non-decoder-built node and is unreachable via decode.
   var content = node.content != null ? node.content : Buffer.concat((node.children || []).map(function (c) { return c.bytes; }));
   return Buffer.concat([Buffer.from([TAGS.SEQUENCE | CONSTRUCTED_BIT]), encodeLength(content.length), content]);
 }
 
 function encodeIdentifier(classBits, constructed, tagNumber) {
-  // Mirror encodeLength's input guard: a negative tag corrupts the identifier
-  // octet (-1 emits 0xff..), and a fractional tag is silently bit-truncated to
-  // a DIFFERENT tag -- an entry-point builder handed a bad tag throws instead
-  // of emitting malformed or non-round-trippable DER.
   if (typeof tagNumber !== "number" || !isFinite(tagNumber) || tagNumber < 0 || Math.floor(tagNumber) !== tagNumber) {
     throw new Asn1Error("asn1/bad-tag", "tag number must be a non-negative integer");
   }
@@ -855,8 +667,6 @@ function encodeIdentifier(classBits, constructed, tagNumber) {
   var body = [];
   var v = tagNumber;
   do { body.unshift(v & 0x7f); v = Math.floor(v / 128); } while (v > 0);
-  // Symmetric with the decoder's 4-octet high-tag-number cap, so the encoder
-  // can't emit an identifier decode() refuses as hostile.
   if (body.length > 4) throw new Asn1Error("asn1/tag-too-large", "high-tag-number too large");
   for (var i = 0; i < body.length - 1; i++) body[i] |= 0x80;
   return Buffer.concat([Buffer.from([lead | 0x1f]), Buffer.from(body)]);
@@ -878,9 +688,6 @@ function encodeIdentifier(classBits, constructed, tagNumber) {
  *   pki.asn1.encode(0x00, false, pki.asn1.TAGS.NULL, Buffer.alloc(0));
  */
 function encodeTLV(classBits, constructed, tagNumber, content) {
-  // A Buffer content is re-viewed so a detached backing store fails closed with a
-  // typed asn1/not-buffer instead of a raw TypeError out of Buffer.concat; an
-  // array / undefined content stays the normal builder path.
   var body = Buffer.isBuffer(content) ? guard.bytes.view(content, Asn1Error, "asn1/not-buffer", "encodeTLV content") : Buffer.from(content || []);
   var id = encodeIdentifier(classBits, constructed, tagNumber);
   return Buffer.concat([id, encodeLength(body.length), body]);
@@ -912,9 +719,6 @@ function intToDer(v) {
 }
 
 function encodeOidContent(dotted) {
-  // Canonical dotted-decimal + X.660 arc bounds live in the one string-OID guard,
-  // so build.oid cannot emit bytes that decode to a DIFFERENT OID than the string
-  // names (a leading-zero arc) or an arc that can never DER-encode.
   guard.identifier.assertCanonicalOid(dotted, _oidErr, "oid/bad-input", "OID", "oid/bad-arc");
   var arcs = dotted.split(".").map(function (p) { return BigInt(p); });
   var a1 = arcs[0], a2 = arcs[1];
@@ -924,8 +728,6 @@ function encodeOidContent(dotted) {
     var body = [];
     var v = subids[s];
     do { body.unshift(Number(v & 0x7fn)); v >>= 7n; } while (v > 0n);
-    // Keep the encoder symmetric with the decoder's per-arc cap so build.oid
-    // can't emit a sub-identifier read.oid would reject as hostile.
     if (body.length > constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES) {
       throw new OidError("oid/subidentifier-too-large",
         "OID sub-identifier exceeds " + constants.LIMITS.OID_MAX_SUBIDENTIFIER_BYTES + " octets");
@@ -936,13 +738,11 @@ function encodeOidContent(dotted) {
   return Buffer.from(out);
 }
 
-// PrintableString (X.680): A-Z a-z 0-9 space and ' ( ) + , - . / : = ? -- checked by character scan (no
-// regex). NumericString: digits and space only.
 function _isPrintableChar(c) {
-  if ((c >= 65 && c <= 90) || (c >= 97 && c <= 122) || (c >= 48 && c <= 57)) return true;   // A-Z a-z 0-9
+  if ((c >= 65 && c <= 90) || (c >= 97 && c <= 122) || (c >= 48 && c <= 57)) return true;
   switch (c) {
-    case 32: case 39: case 40: case 41: case 43: case 44: case 45: case 46: case 47:        // space ' ( ) + , - . /
-    case 58: case 61: case 63:                                                              // : = ?
+    case 32: case 39: case 40: case 41: case 43: case 44: case 45: case 46: case 47:
+    case 58: case 61: case 63:
       return true;
     default: return false;
   }
@@ -960,8 +760,6 @@ function _isNumericString(s) {
 function _fmtTwo(n) { return (n < 10 ? "0" : "") + n; }
 
 function _generalizedTimeString(date) {
-  // GeneralizedTime is YYYYMMDDHHMMSSZ -- a year below 1000 must still emit
-  // four digits, or read.time rejects the short (12-14 char) content.
   var y = date.getUTCFullYear();
   if (y < 0 || y > 9999) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime year " + y + " outside 0000..9999");
   var yyyy = ("000" + y).slice(-4);
@@ -971,8 +769,6 @@ function _generalizedTimeString(date) {
 }
 
 function _utcTimeString(date) {
-  // RFC 5280 sec. 4.1.2.5.1 restricts UTCTime to 1950..2049; a year outside that
-  // wraps to the wrong century (2050 -> "50" -> decodes as 1950).
   var y = date.getUTCFullYear();
   if (y < 1950 || y > 2049) throw new Asn1Error("asn1/bad-utctime", "UTCTime year " + y + " outside 1950..2049; use GeneralizedTime");
   var yy = y % 100;
@@ -1007,27 +803,15 @@ var build = {
   oid:      function (dotted) { return _universal(TAGS.OBJECT_IDENTIFIER, false, encodeOidContent(dotted)); },
   octetString: function (buf) { return _universal(TAGS.OCTET_STRING, false, _asBuffer(buf, "build.octetString")); },
   bitString: function (buf, unusedBits) {
-    // An integer in 0..7 (X.690 sec. 8.6.2.2). A fractional / non-finite count
-    // would be silently bit-truncated into a DIFFERENT value when written into
-    // the leading octet -- the shared integer cap rejects it like the other
-    // numeric builder inputs (encodeLength, the tag number).
     var u = guard.limits.cap(unusedBits == null ? 0 : unusedBits, "unusedBits", 0, { E: _asn1Error, code: "asn1/bad-bit-string", min: 0, max: 7 });
     var body = _asBuffer(buf, "build.bitString");
-    // X.690 8.6.2.3: an empty BIT STRING has no content octets, so its
-    // unused-bit count must be zero -- there are no bits to leave unused.
     if (u > 0 && body.length === 0) throw new Asn1Error("asn1/bad-bit-string", "empty BIT STRING must declare zero unused bits");
-    // Stay canonical: refuse a tail whose declared unused low bits are set.
     if (u > 0 && body.length > 0) {
       var mask = (1 << u) - 1;
       if ((body[body.length - 1] & mask) !== 0) throw new Asn1Error("asn1/bad-bit-string", "unused bits must be zero");
     }
     return _universal(TAGS.BIT_STRING, false, Buffer.concat([Buffer.from([u]), body]));
   },
-  // A minimal DER NamedBitList BIT STRING (X.690 sec. 11.2.2): the asserted `positions` (0-based bit
-  // indices, 0 = the MSB of the first octet) with every trailing zero bit removed and the unused-bit
-  // count set below the last set bit. The single home the keyUsage / PKIFailureInfo / any named-bit
-  // encoder composes, so the minimal-encoding rule lives once (the CHECK side is
-  // schema.assertMinimalNamedBits). No bits asserted -> the empty BIT STRING.
   namedBitString: function (positions) {
     if (!_isArray(positions)) throw new Asn1Error("asn1/bad-bit-string", "namedBitString requires an array of bit positions");
     var hi = -1, i, p;
@@ -1043,9 +827,6 @@ var build = {
   },
   utf8:     function (s) { return _universal(TAGS.UTF8_STRING, false, Buffer.from(String(s), "utf8")); },
   ia5:      function (s) {
-    // Validate the INPUT code points, not the latin1 output bytes: latin1
-    // truncates a code point > 0xFF to its low byte (U+0141 -> 0x41), which
-    // would silently pass a non-IA5 character through as a different one.
     s = String(s);
     for (var i = 0; i < s.length; i++) {
       if (_charCodeAt(s, i) > 0x7F) throw new Asn1Error("asn1/bad-ia5-string", "IA5String requires 7-bit ASCII");
@@ -1058,9 +839,6 @@ var build = {
     return _universal(TAGS.PRINTABLE_STRING, false, Buffer.from(s, "latin1"));
   },
   bmpString: function (s) {
-    // BMPString (UCS-2, X.680) encodes each character as a 2-byte big-endian BMP scalar value -- the exact
-    // inverse of _decodeUtf16be. A surrogate code unit (U+D800..U+DFFF), whether lone or half of a >U+FFFF
-    // pair, cannot be a BMPString character, so it is rejected rather than silently emitted.
     s = String(s);
     var out = Buffer.alloc(s.length * 2);
     for (var i = 0; i < s.length; i++) {
@@ -1075,7 +853,6 @@ var build = {
   generalizedTime: function (date) { return _universal(TAGS.GENERALIZED_TIME, false, Buffer.from(_generalizedTimeString(date), "latin1")); },
   sequence: function (children) { return _universal(TAGS.SEQUENCE, true, Buffer.concat(_asBufferArray(children, "build.sequence"))); },
   set:      function (children) {
-    // DER (X.690 11.6) requires SET component encodings in ascending order.
     var arr = _asBufferArray(children, "build.set").slice();
     arr.sort(Buffer.compare);
     return _universal(TAGS.SET, true, Buffer.concat(arr));
@@ -1085,14 +862,9 @@ var build = {
     arr.sort(Buffer.compare);
     return _universal(TAGS.SET, true, Buffer.concat(arr));
   },
-  // Context-tagged constructions for [n] EXPLICIT / IMPLICIT tagging.
   explicit: function (tagNumber, inner) { return encodeTLV(CLASS_CONTEXT, true, tagNumber, _asBuffer(inner, "build.explicit")); },
   contextPrimitive:   function (tagNumber, content) { return encodeTLV(CLASS_CONTEXT, false, tagNumber, _asBuffer(content, "build.contextPrimitive")); },
   contextConstructed: function (tagNumber, content) { return encodeTLV(CLASS_CONTEXT, true, tagNumber, _asBuffer(content, "build.contextConstructed")); },
-  // IMPLICIT [tag] retag of an already-encoded UNIVERSAL TLV: replace the source's tag with a context-class
-  // [tag] identifier, PRESERVING the source's primitive/constructed bit and content octets (X.680 sec. 30.6).
-  // A single home for the tag replacement so no format module re-inlines the P/C-bit handling (a decode of
-  // the source validates it is exactly one well-formed TLV; its content is the trailing `length` octets).
   implicit: function (tagNumber, tlv) {
     var buf = _asBuffer(tlv, "build.implicit");
     var node = decode(buf);
@@ -1100,14 +872,8 @@ var build = {
   },
   raw:      function (buf) { return _asBuffer(buf, "build.raw"); },
 };
-// Frozen at load so a builder method cannot be replaced afterward: every format module captures `build`
-// and calls its methods to produce emitted DER, so a mutable `build.contextPrimitive` (or any builder)
-// would let co-resident code steer the bytes a certificate carries. Freezing closes that once, toolkit-wide.
 intrinsic.freeze(build);
 
-// A raw INTEGER/ENUMERATED content Buffer must satisfy the same DER shape
-// read.integer enforces: non-empty and minimally encoded (no redundant sign
-// octet). A BigInt/number goes through intToDer, which is minimal by build.
 function _intContent(v, who) {
   if (Buffer.isBuffer(v)) {
     if (v.length === 0) throw new Asn1Error("asn1/bad-integer", who + ": INTEGER content is empty");
@@ -1117,8 +883,6 @@ function _intContent(v, who) {
     }
   }
   var content = Buffer.isBuffer(v) ? v : intToDer(v);
-  // Symmetric with read.integer's per-value ceiling (magnitude + DER sign
-  // octet), so a builder can't emit an INTEGER the decoder would refuse.
   if (content.length > constants.LIMITS.DER_MAX_INTEGER_BYTES + 1) {
     throw new Asn1Error("asn1/integer-too-large", who + ": INTEGER content " + content.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
   }
@@ -1134,8 +898,6 @@ module.exports = {
   TAGS:          TAGS,
   decode:        decode,
   isPrintableString: isPrintableString,
-  // `encode` is the documented public name for the low-level TLV encoder;
-  // `encodeTLV` remains as the descriptive alias.
   encode:        encodeTLV,
   encodeTLV:     encodeTLV,
   encodeLength:  encodeLength,