@blamejs/pki 0.8.12 → 0.8.15

package/lib/trust.js

@@ -46,11 +46,16 @@ var _charCodeAt = intrinsic.uncurry(String.prototype.charCodeAt);
 var _strSlice = intrinsic.uncurry(String.prototype.slice);
 var x509 = require("./schema-x509");
 var pkix = require("./schema-pkix");
+var oid = require("./oid");
+var nodeFs = require("fs");
+var nodeTls = require("tls");
+var trustanchorSchema = require("./schema-trustanchor");
 
 var TrustError = errors.TrustError;
 var LIMITS = constants.LIMITS;
 
 function E(code, message, cause) { return new TrustError(code, message, cause); }
+var _NS = pkix.makeNS("trust", TrustError, oid);
 
 var PURPOSES = ["serverAuth", "emailProtection", "codeSigning"];
 
@@ -351,14 +356,30 @@ function _mkAnchor(cert, meta) {
     label: meta.label,
     mozillaCaPolicy: meta.mozillaCaPolicy,
   };
-  _DERIVED_FROM.set(entry, {
+  /** @internal The certificate's own basic constraints are associated with the anchor, so its
+   * pathLenConstraint bounds the path below it (RFC 5937 sec. 3.2). */
+  var certPathLen = pkix.anchorPathLenFromExtensions(cert.extensions, _NS, "the trust anchor certificate");
+  if (certPathLen !== null) {
+    var cc = intrinsic.create(null);
+    cc.pathLenConstraint = certPathLen;
+    guard.verdict.set(entry, "constraints", cc);
+  }
+  var derived = {
     name: _copyName(cert.subject),
     publicKey: Buffer.from(spki.bytes),
     algorithm: spki.algorithm.oid,
     parameters: spki.algorithm.parameters == null ? spki.algorithm.parameters : Buffer.from(spki.algorithm.parameters),
-    purposes: _copyPurposes(meta.purposes),
+    purposes: _purposesOrNull(meta.purposes),
     distrustAfter: _copyDistrustAfter(meta.distrustAfter),
-  });
+  };
+  /** @internal An independent copy, so editing the entry's own constraints cannot change what
+   * `anchor()` enforces; it reads this record where there is one. */
+  if (certPathLen !== null) {
+    var dc = intrinsic.create(null);
+    dc.pathLenConstraint = certPathLen;
+    derived.constraints = dc;
+  }
+  _DERIVED_FROM.set(entry, derived);
   return entry;
 }
 var _DERIVED_FROM = new WeakMap();
@@ -371,27 +392,39 @@ function _copyPurposes(src) {
   });
 }
 
+/** @internal An EXPLICIT null purposes set stays null; an absent one still defaults to all-false,
+ *  which is the fail-closed reading of a store entry that named no purpose.
+ *
+ *  The two differ because the formats do. A store that lists a root and grants it nothing says
+ *  something, and all-false is how that is written. A format carrying no purpose bits at all, such
+ *  as an RFC 5914 trust anchor, says nothing: turning that into all-false would read as "trusted
+ *  for no purpose" and make `pki.path.validate` demand a purpose to check a constraint the anchor
+ *  never stated. The `anchor` entry gate directly below reads a null the same way, refusing an
+ *  entry whose `purposes` is `!= null` and letting a null through as absent. */
+function _purposesOrNull(src) { return src === null ? null : _copyPurposes(src); }
+
 function _copyDistrustAfter(src) {
   var out = intrinsic.create(null);
   if (!src || typeof src !== "object") return out;
-  Object.keys(src).forEach(function (k) {
-    out[k] = guard.time.isDate(src[k]) ? new Date(guard.time.instantOf(src[k])) : src[k];
-  });
+  var names = guard.identifier.optionNames(src);
+  for (var i = 0; i < names.length; i++) {
+    out[names[i]] = guard.time.isDate(src[names[i]]) ? new Date(guard.time.instantOf(src[names[i]])) : src[names[i]];
+  }
   return out;
 }
 
 function _copyName(name) {
   if (!name || !Array.isArray(name.rdns)) return name;
-  var out = Object.assign({}, name);
+  var out = guard.identifier.ownOptions(name);
   out.rdns = guard.list.copyMap(name.rdns, function (rdn) {
-    return Array.isArray(rdn) ? guard.list.copyMap(rdn, function (atv) { return Object.assign({}, atv); }) : rdn;
+    return Array.isArray(rdn) ? guard.list.copyMap(rdn, function (atv) { return guard.identifier.ownOptions(atv); }) : rdn;
   });
   out.bytes = Buffer.isBuffer(name.bytes) ? Buffer.from(name.bytes) : name.bytes;
   return out;
 }
 
 function _datesEqual(x, y) {
-  var kx = Object.keys(x).sort(), ky = Object.keys(y).sort();
+  var kx = guard.identifier.optionNames(x).sort(), ky = guard.identifier.optionNames(y).sort();
   if (kx.join(",") !== ky.join(",")) return false;
   return kx.every(function (k) { return guard.time.instantOf(x[k]) === guard.time.instantOf(y[k]); });
 }
@@ -929,7 +962,7 @@ function anchor(entry, opts) {
       throw E("trust/purpose-not-trusted", "this root is not a trusted delegator for " + opts.purpose);
     }
   }
-  if (!derived && (entry.purposes != null || (entry.distrustAfter && Object.keys(entry.distrustAfter).length))) {
+  if (!derived && (entry.purposes != null || (entry.distrustAfter && guard.identifier.optionNames(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");
   }
   var nameConstraints = _copyNameConstraints(opts.nameConstraints);
@@ -940,18 +973,476 @@ function anchor(entry, opts) {
     parameters: Buffer.isBuffer(meta.parameters) ? Buffer.from(meta.parameters)
       : (meta.parameters !== undefined ? meta.parameters : null),
     distrustAfter: _copyDistrustAfter(meta.distrustAfter),
-    purposes: _copyPurposes(meta.purposes),
+    purposes: _purposesOrNull(meta.purposes),
   };
   /** @internal Set only when an overlay was supplied, so an anchor without one is the object this
    * verb returned before the option existed, and defined rather than assigned: an accessor planted
    * on Object.prototype under this name would otherwise take the assignment and leave the anchor
    * carrying no restriction at all. */
   if (nameConstraints) guard.verdict.set(out, "nameConstraints", nameConstraints);
+  /** @internal The RFC 5914 anchor's own constraints, kept separate from the `nameConstraints`
+   * overlay a caller may also supply: RFC 5937 sec. 3.2 intersects every permitting set rather than
+   * letting one replace another, so the two have to reach the validator as two statements.
+   *
+   * Read from `meta`, which is the derived record when there is one and the caller's entry when
+   * there is not, so a copy of an entry keeps the restrictions the original carried. They can only
+   * narrow a validation, so an entry that states them is safe to honor whoever built it. */
+  if (meta.constraints) guard.verdict.set(out, "constraints", _copyConstraints(meta.constraints));
+  return out;
+}
+
+/** @internal Copied entry by entry, for the same reason every other anchor field is: what the
+ *  validator enforces must be what this verb read, not what a caller's object answers later. */
+function _copyConstraints(c) {
+  var out = intrinsic.create(null);
+  if (c.nameConstraints) {
+    out.nameConstraints = {
+      permitted: _copySubtrees(c.nameConstraints.permitted, "permitted"),
+      excluded: _copySubtrees(c.nameConstraints.excluded, "excluded"),
+    };
+  }
+  if (c.policySet) out.policySet = intrinsic.map(c.policySet, function (p) { return p; });
+  if (c.policyFlags) {
+    var f = intrinsic.create(null);
+    intrinsic.forEach(trustanchorSchema.policyFlagBits, function (k) { f[k] = c.policyFlags[k] === true; });
+    out.policyFlags = f;
+  }
+  if (c.pathLenConstraint !== undefined) out.pathLenConstraint = c.pathLenConstraint;
+  return out;
+}
+
+/** @internal An RFC 5914 anchor's constraints, in the shape `pki.path.validate` reads them. Each
+ *  field is absent rather than null when the anchor states nothing, so an anchor that constrains
+ *  nothing is the object this module produced before the format existed. */
+function _anchorConstraintsOf(taInfo) {
+  var cp = taInfo.certPath;
+  /** @internal `exts` is where RFC 5914 sec. 2.6 says an anchor associates any extension outside
+   * the four `certPath` already carries, and basic constraints is one of them, so a path length
+   * stated there binds as much as one stated in `certPath` (RFC 5937 sec. 3.2). Where both state
+   * one, the stricter wins: an anchor may only narrow. */
+  var extsPathLen = pkix.anchorPathLenFromExtensions(taInfo.exts, _NS, "the TrustAnchorInfo exts");
+  if (cp === null) {
+    if (extsPathLen === null) return null;
+    var only = intrinsic.create(null);
+    only.pathLenConstraint = extsPathLen;
+    return only;
+  }
+  var out = intrinsic.create(null);
+  var any = false;
+  if (cp.nameConstr !== null) {
+    out.nameConstraints = {
+      permitted: intrinsic.map(cp.nameConstr.permittedSubtrees || [], _subtreeOf),
+      excluded: intrinsic.map(cp.nameConstr.excludedSubtrees || [], _subtreeOf),
+    };
+    any = true;
+  }
+  if (cp.policySet !== null) {
+    out.policySet = intrinsic.map(cp.policySet, function (p) { return p.policyIdentifier; });
+    any = true;
+  }
+  if (cp.policyFlags !== null) { out.policyFlags = cp.policyFlags; any = true; }
+  var pathLen = pkix.lowerPathLen(cp.pathLenConstraint, extsPathLen);
+  if (pathLen !== null) { out.pathLenConstraint = pathLen; any = true; }
+  return any ? out : null;
+}
+function _subtreeOf(st) { return { tag: st.base.tagNumber, base: st.base.value }; }
+
+/**
+ * @primitive  pki.trust.parseTrustAnchorList
+ * @signature  pki.trust.parseTrustAnchorList(input, opts?) -> { anchors }
+ * @since      0.8.13
+ * @status     stable
+ * @spec       RFC 5914, RFC 5937 sec. 3.2
+ * @related    pki.trust.anchor, pki.schema.trustanchor.parse, pki.path.validate
+ *
+ * Read an RFC 5914 `TrustAnchorList` into the trust-store entries `pki.trust.anchor` takes, the
+ * same shape `parseCertdata` and `parseCcadbCsv` produce. Each entry carries the anchor's name,
+ * public key and algorithm, so a list published by a root program drives `pki.path.validate`
+ * without the operator mapping it by hand.
+ *
+ * A `taInfo` anchor's constraints ride on the entry and are applied as RFC 5937 section 3.2 states,
+ * which is that the stricter of the anchor's value and the caller's always wins: its name
+ * constraints intersect the caller's permitted subtrees and union its excluded ones, its
+ * `policySet` intersects `opts.userInitialPolicySet`, each of its `policyFlags` may turn the
+ * matching `initial*` option on and never off, and its `pathLenConstraint` bounds the path.
+ *
+ * The `certificate` and `tbsCert` arms carry no constraints of their own, so an entry from either
+ * is the anchor that certificate's subject and key describe.
+ *
+ * @opts
+ *   - `maxBytes` / `maxDepth` / `maxItems` (integer) -- decode caps for the parse.
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = pki.trustanchor.build({ anchors: [{ taInfo: {
+ *     pubKey: await pki.key.export(pair.publicKey), keyId: Buffer.alloc(20, 1),
+ *     certPath: { taName: "CN=Example Root" } } }] });
+ *   pki.trust.parseTrustAnchorList(der).anchors.length;   // -> 1
+ */
+function parseTrustAnchorList(input, opts) {
+  var list = trustanchorSchema.parse(input, opts);
+  var out = [];
+  intrinsic.forEach(list.anchors, function (a, i) {
+    guard.list.append(out, _entryFromAnchor(a, i));
+  });
+  return { anchors: out };
+}
+
+function _entryFromAnchor(a, i) {
+  if (a.kind === "certificate" || a.kind === "tbsCert") {
+    var cert = a.kind === "certificate" ? a.certificate : a.tbsCert;
+    return _mkAnchor(cert, { distrustAfter: {}, purposes: null, label: null, mozillaCaPolicy: false });
+  }
+  var info = a.taInfo;
+  if (info.certPath === null) {
+    throw E("trust/bad-input", "anchors[" + i + "] is a TrustAnchorInfo carrying no certPath, so it names no " +
+      "distinguished name to chain to; a trust anchor needs one (RFC 5914 sec. 2)");
+  }
+  var spki = info.pubKey;
+  var constraints = _anchorConstraintsOf(info);
+  var entry = {
+    name: info.certPath.taName,
+    publicKey: spki.bytes,
+    algorithm: spki.algorithm.oid,
+    parameters: spki.algorithm.parameters,
+    subjectDer: info.certPath.taName.bytes,
+    distrustAfter: {},
+    purposes: null,
+    label: info.taTitle,
+    mozillaCaPolicy: false,
+  };
+  /** @internal On the ENTRY, not only in the derived record behind it. The entry carries a name, a
+   * public key and an algorithm, which is exactly the anchor tuple `pki.path.validate` accepts, so
+   * an operator passing `parseTrustAnchorList(der).anchors` straight to `trustAnchors` is doing the
+   * obvious thing. Keeping the constraints out of reach of that call would hand them an
+   * UNCONSTRAINED anchor and silently drop every restriction the list stated. */
+  if (constraints) guard.verdict.set(entry, "constraints", constraints);
+  _DERIVED_FROM.set(entry, {
+    name: _copyName(info.certPath.taName),
+    publicKey: intrinsic.bufferFrom(spki.bytes),
+    algorithm: spki.algorithm.oid,
+    parameters: spki.algorithm.parameters == null ? spki.algorithm.parameters : intrinsic.bufferFrom(spki.algorithm.parameters),
+    purposes: null,
+    distrustAfter: _copyDistrustAfter({}),
+    /** @internal Its OWN copy, not the object the entry carries. The derived record is what
+     * `anchor` trusts in preference to the entry, precisely because the entry is reachable: a
+     * caller who edits `entry.constraints` would otherwise be editing what the anchor enforces,
+     * which is the one thing this record exists to prevent for the name and the key. */
+    constraints: constraints === null ? null : _copyConstraints(constraints),
+  });
+  return entry;
+}
+
+/** @internal The bundle paths a Unix host keeps its CA set in, in the order a reader should try
+ *  them. Each is a concatenated PEM file the distribution maintains. macOS and Windows keep theirs
+ *  in a binary keychain and a registry-backed store, so neither has a path here. */
+var _BUNDLE_PATHS = [
+  "/etc/ssl/certs/ca-certificates.crt",
+  "/etc/pki/tls/certs/ca-bundle.crt",
+  "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",
+  "/etc/ssl/ca-bundle.pem",
+  "/etc/ssl/cert.pem",
+  "/usr/local/share/certs/ca-root-nss.crt",
+];
+
+var _SYSTEM_ANCHOR_OPTS = intrinsic.assign(intrinsic.create(null), {
+  path: 1, allowNodeBundle: 1, maxBytes: 1,
+});
+
+/** @internal What an operator runs to produce a bundle this verb can read, per platform. Named in
+ *  the refusal, because the alternative an operator reaches for otherwise is Node's compiled-in
+ *  set, which is not what their host trusts. */
+function _exportHint() {
+  if (process.platform === "darwin") {
+    return "export the host's roots with: security find-certificate -a -p " +
+      "/System/Library/Keychains/SystemRootCertificates.keychain > roots.pem";
+  }
+  if (process.platform === "win32") {
+    return "export the host's roots with: certutil -store ROOT";
+  }
+  return "point opts.path at the CA bundle this host keeps";
+}
+
+/**
+ * @primitive  pki.trust.discoversBundles
+ * @signature  pki.trust.discoversBundles(platform) -> boolean
+ * @since      0.8.15
+ * @status     stable
+ * @spec       RFC 5280
+ * @defends    trust-store-misattribution (CWE-345)
+ * @related    pki.trust.systemAnchors
+ *
+ * Whether `systemAnchors` searches for a CA bundle on this platform. A Unix host's bundle IS the
+ * set its TLS stack trusts. macOS keeps its trust decisions in Keychain and Windows in a
+ * registry-backed store, and on macOS `/etc/ssl/cert.pem` can exist as OpenSSL's own copy, which
+ * is not the host's trust and omits both locally installed roots and Keychain overrides. Reporting
+ * that file as the host's anchors is the misattribution this verb exists to prevent, so those
+ * platforms are refused rather than searched. `opts.path` still reads an exported bundle anywhere.
+ *
+ * @example
+ *   pki.trust.discoversBundles("linux");  // -> true
+ *   pki.trust.discoversBundles("darwin"); // -> false
+ */
+function discoversBundles(platform) {
+  if (typeof platform !== "string" || platform.length === 0) {
+    throw E("trust/bad-input", "discoversBundles takes a process.platform string");
+  }
+  return platform !== "darwin" && platform !== "win32";
+}
+
+/** @internal Reads at most `maxBytes + 1` so the cap bounds what is ALLOCATED rather than being
+ *  checked after an unbounded read: a file far above the cap must not reach memory first. */
+function _readBundleText(chosen, maxBytes) {
+  var fd = null, raw, read;
+  try {
+    fd = nodeFs.openSync(chosen, "r");
+    var buf = intrinsic.bufferAlloc(maxBytes + 1);
+    /** @internal readSync may return fewer bytes than asked for, so the prefix of one call is not
+     * the file. Taking it as the whole bundle would drop the roots below the break with nothing
+     * reported, and would let a file above the cap pass the check underneath it. */
+    read = 0;
+    for (;;) {
+      var got = nodeFs.readSync(fd, buf, read, (maxBytes + 1) - read, read);
+      if (got === 0) break;
+      read += got;
+      if (read >= maxBytes + 1) break;
+    }
+    raw = buf.subarray(0, read);
+  } catch (e) {
+    throw E("trust/no-readable-store", "no CA bundle could be read at " + guard.text.showValue(chosen) +
+      "; " + _exportHint() + ", or pass opts.allowNodeBundle to use the Mozilla set compiled into " +
+      "Node, which is NOT what this host trusts", e);
+  } finally {
+    if (fd !== null) {
+      try { nodeFs.closeSync(fd); }
+      // allow:swallow-unverified the descriptor is released on a best-effort basis
+      catch (_e) { void 0; }
+    }
+  }
+  if (read > maxBytes) {
+    throw E("trust/too-large", "the CA bundle at " + guard.text.showValue(chosen) +
+      " is larger than the " + maxBytes + "-byte cap this read admits");
+  }
+  return raw;
+}
+
+/**
+ * @primitive  pki.trust.systemAnchors
+ * @signature  pki.trust.systemAnchors(opts?) -> { anchors, source, path, skipped }
+ * @since      0.8.15
+ * @status     stable
+ * @spec       RFC 7468 (PEM), RFC 5280
+ * @defends    trust-store-misattribution (CWE-345), trust-store-parser-DoS (CWE-770)
+ * @related    pki.trust.parseCertdata, pki.trust.parseCcadbCsv, pki.trust.anchor, pki.path.validate
+ *
+ * Read the host's CA bundle into the trust anchors `pki.path.validate` consumes. `source` names
+ * which set was read: `"ca-bundle"` for a file on this host, with `path` naming it, or
+ * `"node-bundled"` for the Mozilla set compiled into Node, whose `path` is `null`. A block the
+ * bundle carries that is not a certificate is listed in `skipped` with the label that named it,
+ * rather than dropped.
+ *
+ * A host whose roots are not in a readable PEM file is refused, and the refusal names the command
+ * that exports them. macOS keeps its roots in a binary keychain and Windows in a registry-backed
+ * store, and reading either means running another program, which this toolkit does not do. Falling
+ * back to Node's set instead would report anchors the host does not use, so that takes the
+ * explicit `opts.allowNodeBundle`.
+ *
+ * @opts
+ *   - `path` -- read this file instead of searching the per-platform list.
+ *   - `allowNodeBundle` -- return Node's compiled-in set when no bundle can be read.
+ *   - `maxBytes` -- cap the bundle read (default `C.LIMITS.TRUST_MAX_BYTES`).
+ *
+ * @example
+ *   // Read the host's bundle where there is one, and say so when there is not. Check `source`
+ *   // before trusting the answer: "node-bundled" is Node's compiled-in set, not this machine's.
+ *   var store = pki.trust.systemAnchors({ allowNodeBundle: true });
+ *   console.log(store.source);            // -> "ca-bundle" on a Unix host, else "node-bundled"
+ *   console.log(store.anchors.length > 0); // -> true
+ *   console.log(store.skipped.length >= 0); // -> true (entries named, never dropped silently)
+ */
+function systemAnchors(opts) {
+  opts = opts || {};
+  guard.identifier.assertPlainRecord(opts, E, "trust/bad-input", "systemAnchors opts");
+  guard.identifier.assertKnownKeys(opts, _SYSTEM_ANCHOR_OPTS, E, "trust/bad-input",
+    "unknown systemAnchors option ");
+  var maxBytes = guard.limits.cap(opts.maxBytes, "systemAnchors: opts.maxBytes",
+    LIMITS.TRUST_MAX_BYTES, { E: E, code: "trust/bad-input", min: 1, max: LIMITS.TRUST_MAX_BYTES });
+
+  var chosen = null;
+  if (opts.path !== undefined) {
+    if (typeof opts.path !== "string" || opts.path.length === 0) {
+      throw E("trust/bad-input", "systemAnchors: opts.path must be a non-empty string");
+    }
+    chosen = opts.path;
+  }
+
+  var text = null;
+  if (chosen !== null) {
+    /** @internal `allowNodeBundle` says what to do when there is NO readable bundle, so an absent
+     * file falls back to Node's set under it. A bundle that EXISTS and breaks the cap does not:
+     * the caller asked about that file, and a resource refusal must never quietly swap the trust
+     * set a validation runs against for a different one. */
+    try { text = _readBundleText(chosen, maxBytes); }
+    catch (e) {
+      if (opts.allowNodeBundle !== true || !e || e.code !== "trust/no-readable-store") throw e;
+      text = null;
+      chosen = null;
+    }
+  } else if (discoversBundles(process.platform)) {
+    for (var i = 0; i < _BUNDLE_PATHS.length && text === null; i++) {
+      /** @internal Readability is established by READING, not by a stat: a candidate that exists
+       * but cannot be opened must not stop the search and strand a readable one below it. */
+      try { text = _readBundleText(_BUNDLE_PATHS[i], maxBytes); chosen = _BUNDLE_PATHS[i]; }
+      catch (e) {
+        if (e && e.code === "trust/too-large") throw e;
+        // allow:swallow-unverified a candidate this host cannot read is not this host's bundle
+        text = null;
+      }
+    }
+  }
+
+  if (text === null) {
+    if (opts.allowNodeBundle !== true) {
+      throw E("trust/no-readable-store", "this host keeps no CA bundle this toolkit can read" +
+        (chosen === null ? "" : " at " + guard.text.showValue(chosen)) + "; " + _exportHint() +
+        ", or pass opts.allowNodeBundle to use the Mozilla set compiled into Node, which is NOT " +
+        "what this host trusts");
+    }
+    return _anchorsFromPems(nodeTls.rootCertificates, "node-bundled", null);
+  }
+  return _anchorsFromBundle(text, chosen);
+}
+
+/** @internal A line that reads as a BEGIN boundary but does not start one, because RFC 7468 sec. 2
+ *  puts the boundary at the start of a line and this one is indented or trailed. The decoder is
+ *  right to pass over it as explanatory text, and in a trust bundle that is an anchor the operator
+ *  believes they installed and does not have. Reported with the offset, never a throw: the file is
+ *  readable and the other roots in it are usable. */
+/** @internal The bytes of "-----BEGIN ", held as codes because this directory scans by character
+ *  code rather than by pattern. */
+var _BEGIN_MARK = [0x2d, 0x2d, 0x2d, 0x2d, 0x2d, 0x42, 0x45, 0x47, 0x49, 0x4e, 0x20];
+
+function _reportUnusableBoundaries(bytes, rows, skipped) {
+  var used = intrinsic.create(null);
+  for (var r = 0; r < rows.length; r++) used[rows[r].offset] = true;
+  var lineStart = 0;
+  for (var i = 0; i <= bytes.length; i++) {
+    if (i !== bytes.length && bytes[i] !== 0x0a) continue;
+    var at = lineStart;
+    while (at < i && (bytes[at] === 0x20 || bytes[at] === 0x09)) at += 1;
+    var indented = at > lineStart;
+    var matches = indented && at + _BEGIN_MARK.length <= i;
+    for (var m = 0; matches && m < _BEGIN_MARK.length; m++) {
+      if (bytes[at + m] !== _BEGIN_MARK[m]) matches = false;
+    }
+    if (matches && used[at] !== true) {
+      guard.list.append(skipped, {
+        index: null, offset: at, label: null,
+        reason: "pem/unusable-boundary: a BEGIN boundary at byte " + at + " does not start its " +
+          "line, so RFC 7468 sec. 2 reads it as text and the object it opens is not decoded",
+      });
+    }
+    lineStart = i + 1;
+  }
+}
+
+/** @internal Every certificate block becomes an anchor and every other block is reported, because
+ *  a bundle an operator assembled by hand is exactly where a key or a CRL ends up, and a reader
+ *  that drops one silently leaves them believing it was read. */
+function _anchorsFromBundle(text, chosen) {
+  var rows;
+  try { rows = pkix.pemDecodeBundle(text, {}, errors.PemError); }
+  catch (e) {
+    if (e && e.code === "pem/no-block") {
+      throw E("trust/no-anchors", "the CA bundle at " + guard.text.showValue(chosen) +
+        " carries no PEM block, so it names no trust anchor", e);
+    }
+    throw E("trust/bad-bundle", "the CA bundle at " + guard.text.showValue(chosen) +
+      " is not readable as PEM: " + guard.text.describeThrown(e), e);
+  }
+  var anchors = [], skipped = [];
+  _reportUnusableBoundaries(text, rows, skipped);
+  for (var i = 0; i < rows.length; i++) {
+    var row = rows[i];
+    if (row.label === "TRUSTED CERTIFICATE") {
+      /** @internal OpenSSL's TRUSTED CERTIFICATE is a Certificate followed by an X509_CERT_AUX
+       * carrying the purposes the operator trusted it FOR. Reading the leading certificate and
+       * dropping the aux would hand back a root restricted to one purpose as an unrestricted
+       * anchor, which is a widening, so the block is reported until the aux is read. */
+      guard.list.append(skipped, {
+        index: row.index, offset: row.offset, label: row.label,
+        reason: "trust/aux-not-read: an OpenSSL trusted certificate carries the purposes it is " +
+          "trusted for in a trailing X509_CERT_AUX this reader does not decode, and ingesting it " +
+          "without them would widen the trust it states; convert it with " +
+          "`openssl x509 -in <file> -out <file>.pem` and pass the result",
+      });
+      continue;
+    }
+    if (row.label !== "CERTIFICATE") {
+      guard.list.append(skipped, {
+        index: row.index, offset: row.offset, label: row.label,
+        reason: "trust/not-a-certificate-block: a " + guard.text.showValue(row.label) +
+          " block names no trust anchor",
+      });
+      continue;
+    }
+    var cert = null, why = null;
+    try { cert = x509.parse(row.der); }
+    catch (e) { why = (e && e.code ? e.code : "trust/not-a-certificate") + ": " + guard.text.describeThrown(e); }
+    if (cert === null) {
+      /** @internal Reported, not thrown. A host CA bundle is distribution-managed and real ones
+       * carry certificates this toolkit refuses: the Mozilla set Node ships has a root encoding
+       * pre-2050 dates as GeneralizedTime against the RFC 5280 sec. 4.1.2.5 MUST. Refusing the
+       * whole file would leave the operator with no anchors over a root they do not control,
+       * and relaxing the reader to admit it would weaken every other caller. The entry is named
+       * with the reason instead, so a missing anchor is visible rather than silent. */
+      guard.list.append(skipped, { index: row.index, offset: row.offset, label: row.label, reason: why });
+      continue;
+    }
+    guard.list.append(anchors, _mkAnchor(cert, {
+      distrustAfter: {}, purposes: null, label: null, mozillaCaPolicy: false,
+    }));
+  }
+  if (anchors.length === 0) {
+    throw E("trust/no-anchors", "the CA bundle at " + guard.text.showValue(chosen) +
+      " carries no certificate, so it names no trust anchor");
+  }
+  return _systemResult(anchors, "ca-bundle", chosen, skipped);
+}
+
+function _anchorsFromPems(pems, source, chosen) {
+  var anchors = [], skipped = [];
+  for (var i = 0; i < pems.length; i++) {
+    var cert = null, why = null;
+    try { cert = x509.parse(x509.pemDecode(pems[i], "CERTIFICATE")); }
+    catch (e) { why = (e && e.code ? e.code : "trust/not-a-certificate") + ": " + guard.text.describeThrown(e); }
+    if (cert === null) {
+      guard.list.append(skipped, { index: i, offset: null, label: "CERTIFICATE", reason: why });
+      continue;
+    }
+    guard.list.append(anchors, _mkAnchor(cert, {
+      distrustAfter: {}, purposes: null, label: null, mozillaCaPolicy: false,
+    }));
+  }
+  if (anchors.length === 0) throw E("trust/no-anchors", "the " + source + " set carries no certificate");
+  return _systemResult(anchors, source, chosen, skipped);
+}
+
+/** @internal Defined rather than assigned, and a fresh list each call: the caller owns what it is
+ *  handed, so emptying it must not change what the next call returns. */
+function _systemResult(anchors, source, chosen, skipped) {
+  var out = intrinsic.create(null);
+  guard.verdict.set(out, "anchors", anchors);
+  guard.verdict.set(out, "source", source);
+  guard.verdict.set(out, "path", chosen);
+  guard.verdict.set(out, "skipped", skipped);
   return out;
 }
 
 module.exports = {
   parseCertdata: parseCertdata,
   parseCcadbCsv: parseCcadbCsv,
+  parseTrustAnchorList: parseTrustAnchorList,
+  systemAnchors: systemAnchors,
+  discoversBundles: discoversBundles,
   anchor: anchor,
 };