@blamejs/pki 0.6.14 → 0.6.16

package/lib/trust.js

@@ -41,8 +41,6 @@ var errors = require("./framework-error");
 var asn1 = require("./asn1-der");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides which trust bits an anchor carries.
 var _hasOwn = intrinsic.hasOwn;
 var _charCodeAt = intrinsic.uncurry(String.prototype.charCodeAt);
 var _strSlice = intrinsic.uncurry(String.prototype.slice);
@@ -54,40 +52,27 @@ var LIMITS = constants.LIMITS;
 
 function E(code, message, cause) { return new TrustError(code, message, cause); }
 
-// The three NSS purposes an anchor carries; the keys double as the
-// `opts.checkPurpose` vocabulary `pki.path.validate` consumes.
 var PURPOSES = ["serverAuth", "emailProtection", "codeSigning"];
 
-// CKA_TRUST_* attribute -> purpose key.
 var PURPOSE_ATTRS = [
   ["CKA_TRUST_SERVER_AUTH", "serverAuth"],
   ["CKA_TRUST_EMAIL_PROTECTION", "emailProtection"],
   ["CKA_TRUST_CODE_SIGNING", "codeSigning"],
 ];
 
-// The recognized CK_TRUST vocabulary. Only CKT_NSS_TRUSTED_DELEGATOR grants a
-// purpose; the rest are recognized-but-untrusted (fail-closed: an absent or
-// non-delegator bit never defaults to trusted). A token outside this set is a
-// typed trust/bad-trust-value, never a silent false.
 var CKT_RECOGNIZED = Object.create(null);
 ["CKT_NSS_TRUSTED_DELEGATOR", "CKT_NSS_TRUSTED", "CKT_NSS_MUST_VERIFY_TRUST",
   "CKT_NSS_TRUST_UNKNOWN", "CKT_NSS_NOT_TRUSTED", "CKT_NSS_VALID_DELEGATOR"]
   .forEach(function (t) { CKT_RECOGNIZED[t] = true; });
 var CKT_DELEGATOR = "CKT_NSS_TRUSTED_DELEGATOR";
 
-// An attribute line: `CKA_<NAME> <type> [<value>]`. The value grammar is
-// per-type (a quoted UTF8 string, a single token, or nothing for
-// MULTILINE_OCTAL whose payload follows on its own lines).
-// ---- certdata scanners by character (no regex) ----------------------------------------------------
-function _isNameChar(c) { return (c >= 65 && c <= 90) || (c >= 48 && c <= 57) || c === 95; }   // A-Z 0-9 _
+function _isNameChar(c) { return (c >= 65 && c <= 90) || (c >= 48 && c <= 57) || c === 95; }
 function _isDigitCode(c) { return c >= 48 && c <= 57; }
-function _isDateSepCode(c) { return c === 46 || c === 47 || c === 45; }   // . / -
-function _isOctalDigit(c) { return c >= 48 && c <= 55; }   // 0-7
+function _isDateSepCode(c) { return c === 46 || c === 47 || c === 45; }
+function _isOctalDigit(c) { return c >= 48 && c <= 55; }
 function _isWsCode(c) { return pkix.isJsWhitespace(c); }
-function _containsWs(s) { for (var i = 0; i < s.length; i++) { if (_isWsCode(_charCodeAt(s, i))) return true; } return false; }   // /\s/.test(s)
+function _containsWs(s) { for (var i = 0; i < s.length; i++) { if (_isWsCode(_charCodeAt(s, i))) return true; } return false; }
 
-// An attribute line `CKA_<NAME> [<type> [<value>]]`, matching
-// /^(CKA_[A-Z0-9_]+)(?:\s+(\S+)(?:\s+(.*))?)?$/. Returns [name, type|undefined, value|undefined] or null.
 function _parseAttrLine(s) {
   var n = s.length;
   if (_strSlice(s, 0, 4) !== "CKA_") return null;
@@ -108,17 +93,13 @@ function _parseAttrLine(s) {
   return [name, type, _strSlice(s, p)];
 }
 
-// A single double-quoted value with no interior quote (matching /^"([^"]*)"$/): the inner content, or
-// null. Empty content ("\"\"") returns "" (a valid value), distinct from the null no-match.
 function _unquote(s) {
   var n = s.length;
-  if (n < 2 || _charCodeAt(s, 0) !== 34 || _charCodeAt(s, n - 1) !== 34) return null;   // surrounding "
-  for (var i = 1; i < n - 1; i++) if (_charCodeAt(s, i) === 34) return null;             // no interior "
+  if (n < 2 || _charCodeAt(s, 0) !== 34 || _charCodeAt(s, n - 1) !== 34) return null;
+  for (var i = 1; i < n - 1; i++) if (_charCodeAt(s, i) === 34) return null;
   return _strSlice(s, 1, n - 1);
 }
 
-// String.prototype.split(/\s+/): the pieces between whitespace runs (a leading/trailing run yields a
-// "" element; "" -> [""]). Index assignment (not .push) so the scanner adds no live intrinsic read.
 function _splitWhitespace(s) {
   var out = [], i = 0, n = s.length, pieceStart = 0;
   while (i < n) {
@@ -132,23 +113,21 @@ function _splitWhitespace(s) {
   return out;
 }
 
-// Exactly three octal digits (matching /^[0-7]{3}$/).
 function _isOctal3(d) {
   if (d.length !== 3) return false;
   for (var i = 0; i < 3; i++) { if (!_isOctalDigit(_charCodeAt(d, i))) return false; }
   return true;
 }
 
-// String.prototype.split(/\r\n|\n|\r/): split on CRLF, LF, or CR line terminators.
 function _splitLines(text) {
   var out = [], start = 0, i = 0, n = text.length;
   while (i < n) {
     var c = _charCodeAt(text, i);
-    if (c === 13) {                                            // CR (consume a following LF as one)
+    if (c === 13) {
       out[out.length] = _strSlice(text, start, i);
       if (i + 1 < n && _charCodeAt(text, i + 1) === 10) i += 1;
       i += 1; start = i;
-    } else if (c === 10) {                                     // LF
+    } else if (c === 10) {
       out[out.length] = _strSlice(text, start, i);
       i += 1; start = i;
     } else i += 1;
@@ -157,8 +136,6 @@ function _splitLines(text) {
   return out;
 }
 
-// A Y-M-D date with dotted/dashed/slashed separators, matching /^(\d{4})[./-](\d{1,2})[./-](\d{1,2})$/.
-// Returns [year, month, day] (raw digit strings) or null.
 function _parseYmd(s) {
   var n = s.length;
   for (var a = 0; a < 4; a++) if (!_isDigitCode(_charCodeAt(s, a))) return null;
@@ -177,15 +154,7 @@ function _parseYmd(s) {
   return [year, month, day];
 }
 
-// ---------------------------------------------------------------------------
-// certdata.txt lexer -- line-oriented, C.LIMITS-bounded, fail-closed
-// ---------------------------------------------------------------------------
 
-// Decode a MULTILINE_OCTAL body: whitespace-separated runs of `\ooo` escapes
-// (exactly a backslash + three octal digits, \000..\377), terminated by a line
-// that is exactly `END`. Every fault is refused before the byte lands: an
-// escape past \377, a short or non-octal escape, a stray token, a blank line
-// or EOF before END, or a blob past TRUST_MAX_OCTAL_BYTES.
 function _readOctalBody(lines, idx) {
   var out = [];
   var cap = LIMITS.TRUST_MAX_OCTAL_BYTES;
@@ -197,14 +166,14 @@ function _readOctalBody(lines, idx) {
     for (var c = 0; c < chunks.length; c++) {
       var chunk = chunks[c];
       for (var k = 0; k < chunk.length; k += 4) {
-        if (chunk.charCodeAt(k) !== 92 /* backslash */) {
+        if (chunk.charCodeAt(k) !== 92 ) {
           throw E("trust/bad-octal", "MULTILINE_OCTAL expects \\ooo escapes, got " + JSON.stringify(chunk.slice(k, k + 4)));
         }
         var d = chunk.slice(k + 1, k + 4);
         if (!_isOctal3(d)) {
           throw E("trust/bad-octal", "a MULTILINE_OCTAL escape is a backslash + exactly three octal digits, got " + JSON.stringify("\\" + d));
         }
-        if (d.charCodeAt(0) > 51 /* '3' */) {
+        if (d.charCodeAt(0) > 51 ) {
           throw E("trust/bad-octal", "octal escape \\" + d + " exceeds \\377 (one byte)");
         }
         if (out.length >= cap) throw E("trust/bad-block", "MULTILINE_OCTAL blob exceeds LIMITS.TRUST_MAX_OCTAL_BYTES");
@@ -215,10 +184,6 @@ function _readOctalBody(lines, idx) {
   throw E("trust/bad-octal", "MULTILINE_OCTAL body reached end of input before END");
 }
 
-// Lex the object stream: a `#` line is a comment, the preamble ends at
-// BEGINDATA, blank lines delimit object blocks, each block is typed
-// `CKA_* <type> <value>` attribute lines. Returns [{ attrs }] where attrs maps
-// the attribute name to { type, value | bytes }.
 function _lexObjects(text) {
   var lines = _splitLines(text);
   var n = lines.length;
@@ -243,7 +208,6 @@ function _lexObjects(text) {
     var rawVal = m[2] !== undefined ? m[2].trim() : undefined;
     if (!type) throw E("trust/bad-block", "attribute line is missing its type token: " + name);
     if (!cur) {
-      // Refuse the block bomb before lexing another block's payloads.
       if (objects.length >= LIMITS.TRUST_MAX_OBJECTS) throw E("trust/bad-block", "certdata object count exceeds LIMITS.TRUST_MAX_OBJECTS");
       cur = { attrs: Object.create(null) };
     }
@@ -272,8 +236,6 @@ function _lexObjects(text) {
       if (rawVal === undefined || _containsWs(rawVal)) throw E("trust/bad-block", name + " " + type + " must carry a single token value");
       entry = { type: type, value: rawVal };
     } else {
-      // An unknown value type cannot be lexed safely (its value grammar is
-      // unknown), so fail closed instead of guessing past it.
       throw E("trust/bad-block", "unrecognized attribute type " + JSON.stringify(type) + " on " + name);
     }
     cur.attrs[name] = entry;
@@ -283,9 +245,6 @@ function _lexObjects(text) {
   return objects;
 }
 
-// ---------------------------------------------------------------------------
-// certdata semantics -- pairing, distrust-after, purpose bits
-// ---------------------------------------------------------------------------
 
 function _requireOctal(obj, name, what) {
   var a = obj.attrs[name];
@@ -295,11 +254,6 @@ function _requireOctal(obj, name, what) {
   return a.bytes;
 }
 
-// The NSS distrust-after payload is the bare ASCII of a YYMMDDHHMMSSZ UTCTime
-// (13 bytes) or a YYYYMMDDHHMMSSZ GeneralizedTime (15 bytes), with no DER tag or
-// length. Synthesize the minimal TLV and route it through the strict asn1
-// time reader so the Z-terminator / mandatory-seconds / component-rollover /
-// RFC 5280 sec. 4.1.2.5.1 2050-pivot rules are enforced once, never re-derived.
 function _strictTime(payload, code, label) {
   var tlv;
   if (payload.length === 13) tlv = Buffer.concat([Buffer.from([0x17, 0x0d]), payload]);
@@ -309,8 +263,6 @@ function _strictTime(payload, code, label) {
   catch (e) { throw E(code, label + " does not decode as a strict time", e); }
 }
 
-// CKA_NSS_*_DISTRUST_AFTER: either `CK_BBOOL CK_FALSE` (no distrust-after in
-// force) or a MULTILINE_OCTAL bare-ASCII time. Anything else fails closed.
 function _distrustDate(obj, name) {
   var a = obj.attrs[name];
   if (!a) return null;
@@ -331,16 +283,13 @@ function _certEntry(obj) {
   var issuer = _requireOctal(obj, "CKA_ISSUER", "certificate");
   var serial = _requireOctal(obj, "CKA_SERIAL_NUMBER", "certificate");
 
-  // Fail-closed cross-check (the pairing key vs the parsed DER): a block whose
-  // own identity octets disagree with its certificate would let trust metadata
-  // attach to the wrong root -- a trust-elevation bug, not a tolerable skew.
   if (!issuer.equals(cert.issuer.bytes)) {
     throw E("trust/pairing-mismatch", "CKA_ISSUER disagrees with the certificate's issuer DER");
   }
   var serialContentHex;
   try {
     var sn = asn1.decode(serial);
-    asn1.read.integer(sn); // strict INTEGER (tag + minimal content)
+    asn1.read.integer(sn);
     serialContentHex = sn.content.toString("hex");
   } catch (e) {
     throw E("trust/pairing-mismatch", "CKA_SERIAL_NUMBER is not a DER INTEGER", e);
@@ -371,7 +320,7 @@ function _certEntry(obj) {
     label: label ? label.value : null,
     mozillaCaPolicy: !!(policy && policy.value === true),
     distrustAfter: distrustAfter,
-    purposes: null, // attached by the paired CKO_NSS_TRUST object
+    purposes: null,
   };
 }
 
@@ -381,50 +330,28 @@ function _trustEntry(obj) {
   var purposes = { serverAuth: false, emailProtection: false, codeSigning: false };
   PURPOSE_ATTRS.forEach(function (pair) {
     var a = obj.attrs[pair[0]];
-    if (!a) return; // an absent bit is untrusted (fail-closed)
+    if (!a) return;
     if (a.type !== "CK_TRUST") throw E("trust/bad-block", pair[0] + " must be CK_TRUST");
     purposes[pair[1]] = a.value === CKT_DELEGATOR;
   });
   return { key: issuer.toString("hex") + "/" + serial.toString("hex"), purposes: purposes };
 }
 
-// ---------------------------------------------------------------------------
-// Anchor assembly + dedup (shared by both sources)
-// ---------------------------------------------------------------------------
 
 function _mkAnchor(cert, meta) {
   var spki = cert.subjectPublicKeyInfo;
   var entry = {
-    name: cert.subject,                    // the object with .rdns (name chaining)
-    publicKey: spki.bytes,                 // the full SPKI SEQUENCE TLV
-    algorithm: spki.algorithm.oid,         // the SPKI public-key algorithm OID
-    parameters: spki.algorithm.parameters, // e.g. an EC namedCurve (Buffer|null)
+    name: cert.subject,
+    publicKey: spki.bytes,
+    algorithm: spki.algorithm.oid,
+    parameters: spki.algorithm.parameters,
     subjectDer: cert.subject.bytes,
     distrustAfter: meta.distrustAfter,
     purposes: meta.purposes,
     label: meta.label,
     mozillaCaPolicy: meta.mozillaCaPolicy,
   };
-  // A trust anchor is the pair (name, key) per RFC 5280 sec. 6.1.1, so those two fields are one
-  // fact about one certificate, and they were derived here from one. `anchor()` re-derives them
-  // instead of reading them back, so an entry rebuilt with a substituted key cannot carry the
-  // store's NAME and its per-purpose trust metadata over to a key the store never vouched for.
-  // Recorded off the object, so rebuilding the entry loses the record along with the binding.
-  // Copied, not aliased. The record and the entry would otherwise hold the same Buffer and the same
-  // name object, so overwriting the entry's publicKey in place (otherSpki.copy(entry.publicKey)
-  // for an equal-length key) would overwrite the record with it, and re-deriving would hand back
-  // exactly the substituted key. A record that changes with the thing it is meant to pin is not one.
-  //
-  // The store's METADATA is recorded with them, and for the stronger reason: `purposes` IS the
-  // authorization -- it is what the purpose gate reads to decide whether this root may vouch for
-  // TLS -- and `distrustAfter` is the date that authorization ends. Pinning the key while reading
-  // the authorization off the mutable entry pins the less important half: `entry.purposes.serverAuth
-  // = true` would then produce a server-auth anchor from a root the store marked for e-mail only,
-  // and deleting a distrust date would outlast the store's own policy. Everything the anchor asserts
-  // now comes from what the store read.
   _DERIVED_FROM.set(entry, {
-    // The RDN entries are copied too, not just the arrays holding them: a shallow slice shares
-    // every attribute object, so editing one in place would still reach the record.
     name: _copyName(cert.subject),
     publicKey: Buffer.from(spki.bytes),
     algorithm: spki.algorithm.oid,
@@ -436,10 +363,6 @@ function _mkAnchor(cert, meta) {
 }
 var _DERIVED_FROM = new WeakMap();
 
-// The per-purpose distrust dates, with fresh Date objects. A Date is mutable, so handing back the
-// entry's own would let a consumer move the date this anchor is judged against.
-// The three trust bits, normalized to booleans. Read by the purpose gate and handed back on every
-// anchor, so it is built fresh from whichever source is authoritative and never shared.
 function _copyPurposes(src) {
   return {
     serverAuth: !!src && src.serverAuth === true,
@@ -457,16 +380,6 @@ function _copyDistrustAfter(src) {
   return out;
 }
 
-// A parsed Name, copied faithfully: every field the parser assigns, at every level, with nothing
-// mutable shared. Used on both sides of the record, writing it in and handing it out, so
-// neither direction shares an object with the caller.
-//
-// Faithful, not "the fields the path validator reads", because this Name is handed back on
-// pki.trust.anchor and is the same structure pki.schema.x509.parse produces. A copy that keeps the
-// subset one consumer needs silently degrades it for every other reader: an attribute would lose
-// its registry `name`, so a caller walking anchor.name.rdns would see a different shape depending
-// on whether the anchor came from a store entry or straight from the parser. Each attribute value
-// is a string and so needs no copy of its own; the DER does.
 function _copyName(name) {
   if (!name || !Array.isArray(name.rdns)) return name;
   var out = Object.assign({}, name);
@@ -501,11 +414,6 @@ function _anchorsAgree(x, y) {
     _datesEqual(x.distrustAfter, y.distrustAfter);
 }
 
-// Dedup by (subjectDer, publicKey): one root appearing twice (a duplicated
-// block, or certdata + CCADB merged by the operator) collapses to one anchor,
-// while a distinct root that merely shares a subject DN has a different key and
-// survives. Two entries for one root that disagree on trust metadata are
-// ambiguous, so they fail closed instead of silently picking one.
 function _dedupAnchors(anchors) {
   var seen = Object.create(null);
   var out = [];
@@ -520,9 +428,6 @@ function _dedupAnchors(anchors) {
   return out;
 }
 
-// ---------------------------------------------------------------------------
-// Public surface
-// ---------------------------------------------------------------------------
 
 /**
  * @primitive  pki.trust.parseCertdata
@@ -586,9 +491,6 @@ function parseCertdata(text) {
       var e = _certEntry(obj);
       var prev = byKey[e.key];
       if (prev) {
-        // A byte-identical duplicated block collapses; two certificate
-        // objects claiming one (issuer, serial) with different content are a
-        // forged identity -- fail closed.
         if (!prev.der.equals(e.der) || prev.label !== e.label ||
             prev.mozillaCaPolicy !== e.mozillaCaPolicy ||
             !_datesEqual(prev.distrustAfter, e.distrustAfter)) {
@@ -601,12 +503,11 @@ function parseCertdata(text) {
     } else if (cls.value === "CKO_NSS_TRUST") {
       trusts.push(_trustEntry(obj));
     }
-    // Any other class (CKO_NSS_BUILTIN_ROOT_LIST, ...) is not a root: skipped.
   });
 
   trusts.forEach(function (t) {
     var c = byKey[t.key];
-    if (!c) return; // a trust object with no certificate object grants nothing
+    if (!c) return;
     if (c.purposes) {
       if (!_purposesEqual(c.purposes, t.purposes)) {
         throw E("trust/pairing-mismatch", "two trust objects for one certificate disagree on purpose bits");
@@ -628,9 +529,6 @@ function parseCertdata(text) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// CCADB CSV -- a small RFC 4180 sub-lexer + header-keyed column mapping
-// ---------------------------------------------------------------------------
 
 var CSV_REQUIRED = [
   "Common Name or Certificate Name",
@@ -640,10 +538,6 @@ var CSV_REQUIRED = [
   "PEM Info",
 ];
 
-// RFC 4180 field lexer: quoted fields, embedded commas / newlines, `""`
-// escapes. Strict: a quote may only open at the start of a field, nothing may
-// follow a closing quote but a separator, and an unterminated quote at EOF is
-// a framing violation. Row and field ceilings are refused as they are hit.
 function _csvRows(text) {
   var rows = [], row = [], field = "";
   var inQuotes = false, quoted = false, closed = false;
@@ -685,16 +579,6 @@ function _csvRows(text) {
   return rows;
 }
 
-// `Trust Bits` is set-valued (`Websites; Email`) and CCADB spells it in two
-// vocabularies: the Mozilla-report labels (Websites / Email / Code) and the
-// EKU-derived trust-bit names current exports carry (Server Authentication /
-// Secure Email / Code Signing). Both map to the same purposes. The KNOWN CCADB
-// purposes the anchor model does not track (Client Authentication, Document
-// Signing, Time Stamping, OCSP Signing) are tolerated and grant NOTHING -- a
-// purpose is only ever granted by a recognized delegator token, so ignoring an
-// unmapped one fails closed. An empty cell grants nothing; a token outside the
-// known universe is still surfaced (a silently-skipped NEW bit would hide
-// vocabulary drift), never guessed.
 var _TRUST_BIT_TOKENS = {
   "websites": "serverAuth", "server authentication": "serverAuth",
   "email": "emailProtection", "secure email": "emailProtection",
@@ -717,11 +601,6 @@ function _trustBits(cell) {
   return purposes;
 }
 
-// The CCADB distrust columns are DATE-only. Expand Y-M-D to the end-of-day
-// ...T23:59:59Z instant -- the same instant NSS encodes as `...235959Z` -- by
-// synthesizing a GeneralizedTime and routing through the strict reader (which
-// also rejects a rolled-over calendar date). Dotted, dashed, and slashed
-// separators are accepted (the export format has drifted between them).
 function _csvDate(cell, label) {
   var s = String(cell).trim();
   if (s === "") return null;
@@ -729,9 +608,6 @@ function _csvDate(cell, label) {
   if (!m) throw E("trust/bad-csv", label + " must be a Y-M-D date, got " + JSON.stringify(s));
   var pad = function (x) { return x.length === 1 ? "0" + x : x; };
   var payload = Buffer.from(m[0] + pad(m[1]) + pad(m[2]) + "235959Z", "latin1");
-  // _strictTime tags every rejection (a rolled-over month/day among them) with the code passed here,
-  // so the re-throw carries it unchanged; the wrap normalizes any other failure to the same typed code
-  // so a bad row is always trust/bad-csv, never an untyped exception escaping parseCcadbCsv.
   try { return _strictTime(payload, "trust/bad-csv", label); }
   catch (e) {
     if (e && e.code === "trust/bad-csv") throw e;
@@ -739,9 +615,6 @@ function _csvDate(cell, label) {
   }
 }
 
-// A CCADB `PEM Info` cell: the PEM certificate, commonly wrapped in one layer
-// of single quotes (a spreadsheet-import guard) -- strip that layer, then
-// parse strictly.
 function _pemCell(cell) {
   var s = String(cell).trim();
   if (s.charAt(0) === "'") s = s.slice(1);
@@ -796,14 +669,10 @@ function parseCcadbCsv(text) {
   var rows = _csvRows(text);
   if (rows.length === 0) throw E("trust/bad-csv", "CSV input carries no header row");
 
-  // trim() also strips a leading U+FEFF, so a BOM-prefixed export resolves
-  // its first header cell normally.
   var header = rows[0].map(function (h) { return h.trim(); });
   var col = Object.create(null);
   header.forEach(function (h, idx) {
     if (col[h] !== undefined) {
-      // Two columns with one REQUIRED name make the mapping ambiguous (which
-      // Trust Bits column binds?) -- fail closed rather than silently pick.
       if (CSV_REQUIRED.indexOf(h) !== -1) throw E("trust/bad-csv", "duplicate required column " + JSON.stringify(h));
       return;
     }
@@ -829,7 +698,7 @@ function parseCcadbCsv(text) {
       distrustAfter: distrustAfter,
       purposes: _trustBits(row[col["Trust Bits"]]),
       label: label === "" ? null : label,
-      mozillaCaPolicy: false, // certdata-only metadata
+      mozillaCaPolicy: false,
     }));
   }
   return { anchors: _dedupAnchors(anchors) };
@@ -877,9 +746,6 @@ function parseCcadbCsv(text) {
  *   await pki.path.validate([pki.schema.x509.parse(der)],
  *     { time: new Date("2026-06-01T00:00:00Z"), trustAnchors: anchor, checkPurpose: "serverAuth" });
  */
-// `purpose` is the only option, and it gates the authorization itself, so a near-miss spelling must not
-// pass silently: a caller who wrote the plural `purposes` (or carried a sibling's word) would otherwise get
-// the anchor with NO purpose restriction rather than an error naming the option they meant.
 var _ANCHOR_OPTS = { purpose: 1 };
 function anchor(entry, opts) {
   if (!entry || typeof entry !== "object") {
@@ -887,18 +753,8 @@ function anchor(entry, opts) {
   }
   opts = guard.identifier.optionsObject(opts, E, "trust/bad-input", "pki.trust.anchor options");
   guard.identifier.assertKnownKeys(opts, _ANCHOR_OPTS, E, "trust/bad-input", "unknown pki.trust.anchor option ");
-  // Where this entry came from a store, everything the anchor asserts is read from the record the
-  // store minted, not from the entry -- the entry is a plain object the caller holds and can write
-  // to. `purposes` is the authorization itself, so an entry whose serverAuth bit was flipped after
-  // parsing must not open the gate, and a distrust date deleted from it must not outlive the
-  // store's policy.
   var derived = _DERIVED_FROM.get(entry);
   var meta = derived || entry;
-  // The tuple-shape check runs on the ENTRY only when there is no record, because only then are the
-  // entry's own fields what the anchor is built from. With a record, an entry a caller has since
-  // emptied still anchors to exactly what the store read: the answer does not depend on the object
-  // the caller is holding, in either direction. Without one, the caller is asserting a bare
-  // (name, key) anchor of their own and its shape is what there is to check.
   if (!derived && (!Buffer.isBuffer(entry.publicKey) || typeof entry.algorithm !== "string" ||
       !entry.name || !Array.isArray(entry.name.rdns))) {
     throw E("trust/bad-input", "anchor expects a trust-store entry ({ name, publicKey, algorithm, ... })");
@@ -911,37 +767,15 @@ function anchor(entry, opts) {
       throw E("trust/purpose-not-trusted", "this root is not a trusted delegator for " + opts.purpose);
     }
   }
-  // Where this entry came from a store, the (name, key) pair is re-derived from the certificate it
-  // was read out of rather than read back off the entry. Both halves are one fact about one
-  // certificate, so an entry rebuilt with a substituted publicKey would otherwise carry the store's
-  // name and its per-purpose trust metadata onto a key the store never vouched for. An entry a
-  // caller built themselves has no such record and is their own assertion, which is what a bare
-  // trust-anchor tuple is.
-  //
-  // An entry carrying the store's METADATA is claiming to be a store entry. The metadata is the
-  // root program's statement -- these purposes, until this date -- and it is a statement about a
-  // KEY. Without the record there is nothing binding it to the key the entry now names, so a copy
-  // with a substituted publicKey would carry the program's word onto a key it never saw. A caller
-  // asserting a bare (name, key) anchor of their own carries no metadata and is unaffected.
   if (!derived && (entry.purposes != null || (entry.distrustAfter && Object.keys(entry.distrustAfter).length))) {
     throw E("trust/bad-input", "this entry carries a trust store's per-purpose metadata but is not the entry the store produced -- it has been rebuilt, and the metadata is a statement about the key the store read, not about whichever key the copy now names. Pass pki.trust.parseCertdata / parseCcadbCsv output unmodified");
   }
-  // Copies OUT as well as in. Handing back the record's own Buffer lets a consumer write through
-  // the returned anchor into the record -- copy an equal-length SPKI over anchor.publicKey and the
-  // next anchor() call re-derives the substituted key while still carrying the store's purposes and
-  // distrust dates. Guarding only the write INTO the record leaves the same door open in the other
-  // direction, so every call hands back fresh values.
   return {
     name: _copyName(meta.name),
     publicKey: Buffer.isBuffer(meta.publicKey) ? Buffer.from(meta.publicKey) : meta.publicKey,
     algorithm: meta.algorithm,
     parameters: Buffer.isBuffer(meta.parameters) ? Buffer.from(meta.parameters)
       : (meta.parameters !== undefined ? meta.parameters : null),
-    // The METADATA comes from the same source as the key, and is copied for the same reason on the
-    // way out: handing back the record's own object let a consumer write
-    // `anchor(entry).purposes.serverAuth = true` and have the next call pass a gate the store never
-    // opened. `distrustAfter` holds Dates, which are mutable in the same way. Everything on this
-    // object is fresh, so two anchors from one entry share nothing.
     distrustAfter: _copyDistrustAfter(meta.distrustAfter),
     purposes: _copyPurposes(meta.purposes),
   };