@blamejs/pki 0.9.5 → 0.9.7

package/lib/trust.js

@@ -1035,6 +1035,7 @@ function anchor(entry, opts) {
       !entry.name || !intrinsic.isArray(entry.name.rdns))) {
     throw E("trust/bad-input", "anchor expects a trust-store entry ({ name, publicKey, algorithm, ... })");
   }
+  // allow:caller-option-presence-tested-against-undefined -- absence means no purpose restricts the bundle, so a null must be refused
   if (opts.purpose !== undefined) {
     if (_arrIndexOf(PURPOSES, opts.purpose) === -1) {
       throw E("trust/bad-input", "anchor: opts.purpose must be one of " + _arrJoin(PURPOSES, " | "));
@@ -1226,7 +1227,7 @@ var _BUNDLE_PATHS = [
 ];
 
 var _SYSTEM_ANCHOR_OPTS = intrinsic.assign(intrinsic.create(null), {
-  path: 1, allowNodeBundle: 1, maxBytes: 1,
+  path: 1, allowNodeBundle: 1, maxBytes: 1, distrustedKeys: 1,
 });
 
 /** @internal What an operator runs to produce a bundle this verb can read, per platform. Named in
@@ -1306,9 +1307,85 @@ function _readBundleText(chosen, maxBytes) {
   return raw;
 }
 
+/**
+ * @primitive  pki.trust.spkiDigest
+ * @signature  pki.trust.spkiDigest(cert) -> string
+ * @since      0.9.6
+ * @status     stable
+ * @spec       RFC 5280
+ * @related    pki.path.validate, pki.trust.systemAnchors, pki.transport.https
+ *
+ * The SHA-256 digest of a certificate's DER SubjectPublicKeyInfo in canonical form, as 64 lower-case
+ * hexadecimal characters. Canonical form is an uncompressed EC point with its named curve and an RSA
+ * key with NULL parameters, which is how nearly every certificate encodes a key, so for those it is
+ * the digest of the bytes the certificate carries and the SPKI SHA-256 root programs publish. This is
+ * the entry `distrustedKeys` takes on `pki.path.validate`, `pki.path.build`,
+ * `pki.trust.systemAnchors`, the TLS policy of `pki.transport.https`, and the verbs that validate a
+ * chain on a caller's behalf. Every certificate that carries the same key has the same digest, however
+ * it encodes the key, so one entry covers a CA certificate and each of its cross-signatures. `cert` is
+ * DER bytes, a PEM string, or a `pki.schema.x509.parse` result. An identifier that restricts a key to
+ * one use names the same key: id-ecDH and id-ecMQV read as ecPublicKey, and RSASSA-PSS and RSAES-OAEP
+ * read as rsaEncryption. A key node does not read, such as a composite or stateful hash-based key, is
+ * digested as the certificate encodes it, and a composite key is its own key, so listing one of its
+ * component keys does not list the composite.
+ *
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"] } },
+ *     { key: await pki.key.export(pair.privateKey) });
+ *   pki.trust.spkiDigest(der).length;   // 64
+ */
+function spkiDigest(cert) {
+  if (cert === undefined || cert === null) throw E("trust/bad-input", "spkiDigest takes a certificate (DER, PEM, or a parsed certificate)");
+  var spki;
+  if (typeof cert === "string") spki = x509.parse(x509.pemDecode(cert, "CERTIFICATE")).subjectPublicKeyInfo.bytes;
+  else if (guard.bytes.isByteSource(cert)) spki = x509.parse(guard.bytes.snapshotSource(cert, E, "trust/bad-input", "the certificate")).subjectPublicKeyInfo.bytes;
+  else if (typeof cert === "object" && cert.subjectPublicKeyInfo && guard.bytes.isByteSource(cert.subjectPublicKeyInfo.bytes)) {
+    spki = guard.bytes.snapshotSource(cert.subjectPublicKeyInfo.bytes, E, "trust/bad-input", "the certificate's subjectPublicKeyInfo.bytes");
+  } else {
+    throw E("trust/bad-input", "spkiDigest takes a certificate (DER, PEM, or a parsed certificate)");
+  }
+  return guard.distrust.keyDigest(spki);
+}
+
+/**
+ * @primitive  pki.trust.knownCompromisedKeys
+ * @signature  pki.trust.knownCompromisedKeys() -> Array<{ spkiSha256, name, reason, sources }>
+ * @since      0.9.7
+ * @status     stable
+ * @spec       CA/Browser Forum TLS BR
+ * @related    pki.trust.spkiDigest, pki.path.validate, pki.transport.https, pki.x509.sign
+ *
+ * The keys every verb in this toolkit refuses because their private key is public. Each record holds
+ * `spkiSha256`, the `pki.trust.spkiDigest` value of the key; `name`, the subject common name of a
+ * certificate that carries it, or the product's CA name for a key published without a certificate;
+ * `reason`, how the private key became public; and `sources`, the URLs where that is recorded. Each
+ * record is frozen, and the array is a new one on every call.
+ *
+ * The toolkit also refuses an elliptic curve key on P-256, P-384, P-521 or secp256k1 whose private key
+ * is an integer below 256, or below 256 short of the group order, whether or not it is listed here.
+ *
+ * Path validation fails a chain whose trust anchor, intermediate or target carries such a key with
+ * `path/compromised-key`. `pki.trust.systemAnchors` skips such a certificate with the reason
+ * `trust/compromised-key`. `pki.transport.https` refuses a server whose certificate chain carries one
+ * with `transport/server-key-compromised`, and a proxy with `transport/proxy-key-compromised`.
+ * `pki.x509.sign`, `pki.csr.sign` and `pki.crmf.build` refuse to certify, sign with or request a
+ * certificate for one, with `x509/compromised-key`, `csr/compromised-key` and `crmf/compromised-key`.
+ * None of these refusals can be turned off.
+ *
+ * @example
+ *   var listed = pki.trust.knownCompromisedKeys();
+ *   listed[0].spkiSha256.length;   // 64
+ */
+function knownCompromisedKeys() {
+  return guard.distrust.knownCompromised();
+}
+
 /**
  * @primitive  pki.trust.systemAnchors
- * @signature  pki.trust.systemAnchors(opts?) -> { anchors, source, path, skipped }
+ * @signature  pki.trust.systemAnchors(opts?) -> { anchors, intermediates, source, path, skipped }
  * @since      0.8.15
  * @status     stable
  * @spec       RFC 7468 (PEM), RFC 5280
@@ -1321,16 +1398,37 @@ function _readBundleText(chosen, maxBytes) {
  * bundle carries that is not a certificate is listed in `skipped` with the label that named it,
  * rather than dropped.
  *
+ * Only a self-issued certificate becomes an anchor. A certificate whose issuer name differs from its
+ * subject name is listed in `skipped` with the reason `trust/not-self-issued` and returned, as DER,
+ * in `intermediates`, which `pki.path.build` takes as `candidates`. A Windows store export includes
+ * the Intermediate Certification Authorities store, which holds certificates the host has seen
+ * rather than ones it trusts, and OpenSSL's default verification also requires a self-issued
+ * certificate at the top of a chain. A certificate whose names cannot be compared, because an
+ * attribute value carries a control byte, is listed in `skipped` with that reason and is returned in
+ * neither list.
+ *
+ * A certificate whose key is listed in `opts.distrustedKeys` is neither an anchor nor an
+ * intermediate; it is listed in `skipped` with the reason `trust/distrusted-key`. A certificate whose
+ * private key is public (see `pki.trust.knownCompromisedKeys`) is skipped the same way with the reason
+ * `trust/compromised-key`, whether or not a list is given. A bundle left with no anchor is refused
+ * with `trust/no-anchors`.
+ *
  * 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`.
+ * explicit `opts.allowNodeBundle`. Node's set is the Mozilla list as of the Node release that
+ * compiled it, so a root that Mozilla has since removed stays in it until Node is upgraded;
+ * `opts.distrustedKeys` removes one sooner.
  *
  * @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.
+ *   - `allowNodeBundle` -- `true` returns Node's compiled-in set when no bundle can be read.
+ *     It takes `true`, `false`, `null` or an absent option, and any other value is refused with
+ *     `trust/bad-input`.
  *   - `maxBytes` -- cap the bundle read (default `C.LIMITS.TRUST_MAX_BYTES`).
+ *   - `distrustedKeys` -- SHA-256 digests of SubjectPublicKeyInfo values (64 hex characters or 32
+ *     bytes each, see `pki.trust.spkiDigest`) whose certificates are left out.
  *
  * @example
  *   // Read the host's bundle where there is one, and say so when there is not. Check `source`
@@ -1347,9 +1445,12 @@ function systemAnchors(opts) {
     "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 allowNodeBundle = guard.identifier.booleanOption(opts.allowNodeBundle, E, "trust/bad-input",
+    "systemAnchors: opts.allowNodeBundle");
+  var distrusted = guard.distrust.keys(opts.distrustedKeys, E, "trust/bad-input", "systemAnchors: opts.distrustedKeys");
 
   var chosen = null;
-  if (opts.path !== undefined) {
+  if (opts.path != null) {
     if (typeof opts.path !== "string" || opts.path.length === 0) {
       throw E("trust/bad-input", "systemAnchors: opts.path must be a non-empty string");
     }
@@ -1364,7 +1465,7 @@ function systemAnchors(opts) {
      * 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;
+      if (!allowNodeBundle || !e || e.code !== "trust/no-readable-store") throw e;
       text = null;
       chosen = null;
     }
@@ -1382,15 +1483,38 @@ function systemAnchors(opts) {
   }
 
   if (text === null) {
-    if (opts.allowNodeBundle !== true) {
+    if (!allowNodeBundle) {
       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 _anchorsFromPems(nodeTls.rootCertificates, "node-bundled", null, distrusted);
+  }
+  return _anchorsFromBundle(text, chosen, distrusted);
+}
+
+/** @internal Why a parsed bundle certificate is not an anchor, or null when it is one. A
+ * distrusted key is reported first, so a listed intermediate is not offered as a candidate either.
+ * The name comparison is the RFC 5280 sec. 7.1 one, and a name it cannot compare (a control byte
+ * in an attribute value) is reported rather than thrown, so one malformed entry does not refuse the
+ * whole bundle. */
+function _systemEntryRefusal(cert, distrusted) {
+  var compromised = guard.distrust.compromised(cert.subjectPublicKeyInfo.bytes);
+  if (compromised !== null) return { intermediate: false, reason: "trust/compromised-key: " + compromised };
+  if (guard.distrust.has(distrusted, cert.subjectPublicKeyInfo.bytes)) {
+    return { intermediate: false, reason: "trust/distrusted-key: the certificate's key is listed in opts.distrustedKeys" };
+  }
+  var selfIssued;
+  try { selfIssued = guard.name.dnEqual(cert.subject.rdns, cert.issuer.rdns, E, "trust/bad-input", "the bundle certificate"); }
+  catch (e) {
+    return { intermediate: false, reason: (e && e.code ? e.code : "trust/bad-input") + ": " + guard.text.describeThrown(e) };
   }
-  return _anchorsFromBundle(text, chosen);
+  if (!selfIssued) {
+    return { intermediate: true, reason: "trust/not-self-issued: the issuer name differs from the subject name, so the " +
+      "certificate is not a root; it is returned in intermediates for chain building" };
+  }
+  return null;
 }
 
 /** @internal A line that reads as a BEGIN boundary but does not start one, because RFC 7468 sec. 2
@@ -1429,7 +1553,7 @@ function _reportUnusableBoundaries(bytes, rows, skipped) {
 /** @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) {
+function _anchorsFromBundle(text, chosen, distrusted) {
   var rows;
   try { rows = pkix.pemDecodeBundle(text, {}, errors.PemError); }
   catch (e) {
@@ -1440,7 +1564,7 @@ function _anchorsFromBundle(text, chosen) {
     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 = [];
+  var anchors = [], skipped = [], intermediates = [];
   _reportUnusableBoundaries(text, rows, skipped);
   for (var i = 0; i < rows.length; i++) {
     var row = rows[i];
@@ -1479,40 +1603,53 @@ function _anchorsFromBundle(text, chosen) {
       guard.list.append(skipped, { index: row.index, offset: row.offset, label: row.label, reason: why });
       continue;
     }
+    var refusal = _systemEntryRefusal(cert, distrusted);
+    if (refusal !== null) {
+      guard.list.append(skipped, { index: row.index, offset: row.offset, label: row.label, reason: refusal.reason });
+      if (refusal.intermediate) guard.list.append(intermediates, intrinsic.bufferFrom(row.der));
+      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");
+      " carries no self-issued certificate this read admits, so it names no trust anchor");
   }
-  return _systemResult(anchors, "ca-bundle", chosen, skipped);
+  return _systemResult(anchors, intermediates, "ca-bundle", chosen, skipped);
 }
 
-function _anchorsFromPems(pems, source, chosen) {
-  var anchors = [], skipped = [];
+function _anchorsFromPems(pems, source, chosen, distrusted) {
+  var anchors = [], skipped = [], intermediates = [];
   for (var i = 0; i < pems.length; i++) {
-    var cert = null, why = null;
-    try { cert = x509.parse(x509.pemDecode(pems[i], "CERTIFICATE")); }
+    var cert = null, why = null, der = null;
+    try { der = x509.pemDecode(pems[i], "CERTIFICATE"); cert = x509.parse(der); }
     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;
     }
+    var refusal = _systemEntryRefusal(cert, distrusted);
+    if (refusal !== null) {
+      guard.list.append(skipped, { index: i, offset: null, label: "CERTIFICATE", reason: refusal.reason });
+      if (refusal.intermediate) guard.list.append(intermediates, intrinsic.bufferFrom(der));
+      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);
+  if (anchors.length === 0) throw E("trust/no-anchors", "the " + source + " set carries no self-issued certificate this read admits");
+  return _systemResult(anchors, intermediates, 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) {
+function _systemResult(anchors, intermediates, source, chosen, skipped) {
   var out = intrinsic.create(null);
   guard.verdict.set(out, "anchors", anchors);
+  guard.verdict.set(out, "intermediates", intermediates);
   guard.verdict.set(out, "source", source);
   guard.verdict.set(out, "path", chosen);
   guard.verdict.set(out, "skipped", skipped);
@@ -1528,4 +1665,6 @@ module.exports = intrinsic.freeze({
   systemAnchors: systemAnchors,
   discoversBundles: discoversBundles,
   anchor: anchor,
+  spkiDigest: spkiDigest,
+  knownCompromisedKeys: knownCompromisedKeys,
 });

package/lib/trustanchor-build.js

@@ -1,6 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
+// codebase-patterns:allow-file caller-option-presence-tested-against-undefined
+/** @internal Every member of a trust anchor RESTRICTS what it may certify: a policy set,
+ * policy flags, name constraints, a path length. A `null` here is a malformed spec rather
+ * than an option left out, because reading it as an omission would drop a restriction the
+ * caller named and build a WIDER anchor than they described without saying so. Presence is
+ * asked against `undefined` alone, and a null member is refused by the builder's own typed
+ * error, which the nested-record vector in schema-trustanchor.test.js pins. */
 /**
  * @module     pki.trustanchor
  * @nav        Trust
@@ -98,7 +105,15 @@ function _certPathDer(spec) {
     throw _err("trustanchor/bad-input", "certPath.taName must be a non-empty distinguished name (RFC 5914 sec. 2)");
   }
   var kids = [b.raw(nameDer)];
-  /** @internal The RFC 5914 module is IMPLICIT TAGS, so a context tag REPLACES the member's own
+  /** @internal Presence is asked as "not undefined" here, and deliberately not as "not
+   * absent", which is how a caller option is read everywhere else. These members RESTRICT
+   * what the anchor may certify: a policy set, policy flags, name constraints and a path
+   * length. Reading a `null` as an omission would drop the restriction the caller named and
+   * build a WIDER anchor than they described, without saying so. A member given as `null`
+   * is a malformed spec and is refused by the builder's own typed error, which the
+   * nested-record vector in schema-trustanchor.test.js pins.
+   *
+   * The RFC 5914 module is IMPLICIT TAGS, so a context tag REPLACES the member's own
    * universal tag rather than wrapping it. `b.implicit` re-tags the value it is given; only the
    * three members the module writes EXPLICIT beside get a wrapper. */
   if (spec.certificate !== undefined) {

package/lib/tsp-sign.js

@@ -650,6 +650,9 @@ function _buildTsaChains(leaf, pool) {
  *                      certificate when `certReq` was false) and an intermediate absent from the
  *                      token can still verify and chain.
  * @opts  revocationChecker  Passed through to `pki.path.validate`.
+ * @opts  distrustedKeys  SHA-256 digests of SubjectPublicKeyInfo DER (64 hexadecimal characters or
+ *                      32 bytes each, see `pki.trust.spkiDigest`). A listed key on the TSA chain,
+ *                      the anchor included, fails the token with `tsp/untrusted-tsa`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
@@ -664,7 +667,7 @@ function _buildTsaChains(leaf, pool) {
  *   res.valid;     // boolean; pass opts.trustAnchors to also chain the TSA cert to a root
  *   res.genTime;   // Date, read from the verified eContent
  */
-var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), { certs: 1, trustAnchors: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1, allowWeakDigests: 1 });
+var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), { certs: 1, trustAnchors: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1, allowWeakDigests: 1, distrustedKeys: 1 });
 
 function _anyCritical(extensions) {
   return guard.list.anyMatches(extensions, function (e) { return !!e && !!e.critical; });
@@ -684,6 +687,8 @@ async function verify(token, data, opts) {
   if (opts.certs != null && (!Array.isArray(opts.certs) || !guard.list.allMatch(opts.certs, function (c) { return guard.bytes.isByteSource(c); }))) {
     throw _err("tsp/bad-input", "pki.tsp.verify opts.certs must be an array of DER certificate Buffers");
   }
+  /** @internal Typed here, ahead of the path step, whose throws all become `tsp/untrusted-tsa`. */
+  var distrustedKeys = guard.distrust.keys(opts.distrustedKeys, _err, "tsp/bad-input", "pki.tsp.verify opts.distrustedKeys");
   var tokenDer = _tokenDer(token);
   var parsed = schemaTsp.parseToken(tokenDer);
   var tst = parsed.tstInfo;
@@ -732,6 +737,7 @@ async function verify(token, data, opts) {
       async function validateAt(chain, when) {
         var res = await pathValidate.validate(chain, {
           time: when, trustAnchors: opts.trustAnchors, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
+          distrustedKeys: distrustedKeys,
         });
         if (_moreEstablished(res.revocationChecked, revocationChecked)) revocationChecked = res.revocationChecked;
         if (anchorConstraints == null && res.anchorConstraints != null) anchorConstraints = res.anchorConstraints;

package/lib/webauthn-mds.js

@@ -122,7 +122,7 @@ var CERT_SCOPED_STATUS = intrinsic.freeze(intrinsic.assign(intrinsic.create(null
 
 var _BLOB_OPTS = intrinsic.assign(intrinsic.create(null), {
   rootCertificates: 1, time: 1, previousNo: 1, requireRollbackCheck: 1, allowStale: 1,
-  statusPolicy: 1, rejectUnknownStatus: 1,
+  statusPolicy: 1, rejectUnknownStatus: 1, distrustedKeys: 1,
 });
 
 function _isPlainObject(v) { return !!v && typeof v === "object" && !intrinsic.isArray(v); }
@@ -218,8 +218,9 @@ function _verifyMetadataBlob(blob, opts) {
   if (!intrinsic.isArray(roots) || roots.length === 0) {
     throw _err("webauthn/metadata-no-root", "verifying a metadata BLOB requires opts.rootCertificates -- the FIDO root(s) to anchor it to; this library bundles none");
   }
-  if (o.time !== undefined) guard.time.assertValid(o.time, _err, "webauthn/bad-input", "opts.time");
-  var at = o.time === undefined ? new intrinsic.Date() : o.time;
+  if (o.time != null) guard.time.assertValid(o.time, _err, "webauthn/bad-input", "opts.time");
+  var at = o.time == null ? new intrinsic.Date() : o.time;
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (o.previousNo !== undefined && (!intrinsic.isSafeInteger(o.previousNo) || o.previousNo < 0)) {
     throw _err("webauthn/bad-input", "opts.previousNo must be a non-negative safe integer");
   }
@@ -228,13 +229,18 @@ function _verifyMetadataBlob(blob, opts) {
       throw _err("webauthn/bad-input", "opts." + k + " must be a boolean");
     }
   });
+  // allow:caller-option-presence-tested-against-undefined -- absence means any status is accepted, so a null must be refused rather than widen the policy
   if (o.statusPolicy !== undefined && typeof o.statusPolicy !== "function" &&
       o.statusPolicy !== "any" && o.statusPolicy !== "latest-by-date") {
     throw _err("webauthn/bad-input", "opts.statusPolicy must be \"any\", \"latest-by-date\", or a function");
   }
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (o.requireRollbackCheck === true && o.previousNo === undefined) {
     throw _err("webauthn/metadata-no-baseline", "opts.requireRollbackCheck was set without opts.previousNo, so there is no baseline to compare against");
   }
+  /** @internal Typed here, before the chain walk, because the walk turns a validation rejection into
+   *  an untrusted verdict, and a malformed list must be reported as the caller's input fault. */
+  var distrusted = guard.distrust.keys(o.distrustedKeys, _err, "webauthn/bad-input", "opts.distrustedKeys");
   opts = o;
   var anchors = intrinsic.mapList(roots, function (r, i) { return _asCert(r, "opts.rootCertificates[" + i + "]"); });
 
@@ -351,14 +357,17 @@ function _verifyMetadataBlob(blob, opts) {
   }, function (e) { throw _err("webauthn/unsupported-algorithm", "the metadata BLOB x5c leaf key could not be imported for " + header.alg, e); });
   var anchored = intrinsic.chain(verified, function (ok) {
     if (!ok) throw _err("webauthn/verify-failed", "the metadata BLOB signature does not verify under its x5c leaf key");
-    return _chainToAnchor(chain, anchors, at);
+    return _chainToAnchor(chain, anchors, at, undefined, undefined, distrusted);
   });
   return intrinsic.chain(anchored, function () {
     return _parsePayload(segs[1], at, opts);
   });
 }
 
-function _chainToAnchor(chain, anchors, at, what, code) {
+/** @internal `distrusted` is a list `guard.distrust.keys` returned, or null. It reaches every
+ *  validation below, and the self-presented anchor, which is trusted without one, is refused here
+ *  when its key is listed. */
+function _chainToAnchor(chain, anchors, at, what, code, distrusted) {
   var subject = what || "metadata BLOB certificate chain";
   var faultCode = code || "webauthn/metadata-untrusted";
   var ordered = _reverse(intrinsic.copyList(chain));
@@ -381,12 +390,20 @@ function _chainToAnchor(chain, anchors, at, what, code) {
       var path = intrinsic.copyList(ordered);
       var strippedAnchor = false;
       if (path.length && _isAnchorItself(path[0], anchor)) { path = intrinsic.copyList(path, 1); strippedAnchor = true; }
-      if (path.length === 0) return strippedAnchor;
+      if (path.length === 0) {
+        var anchorRefusal = strippedAnchor ? guard.distrust.refusal(distrusted, anchor.subjectPublicKeyInfo.bytes, "opts.distrustedKeys") : null;
+        if (anchorRefusal !== null) {
+          lastFault = _err(faultCode, "the " + subject + " is a trust anchor whose key " + anchorRefusal);
+          return false;
+        }
+        return strippedAnchor;
+      }
       var verdict = pathValidate.validate(path, {
         time: at,
         trustAnchors: { name: anchor.subject, publicKey: anchor.subjectPublicKeyInfo.bytes,
           algorithm: anchor.subjectPublicKeyInfo.algorithm.oid,
           parameters: anchor.subjectPublicKeyInfo.algorithm.parameters },
+        distrustedKeys: distrusted || null,
       });
       return intrinsic.chain(verdict, function (r) { return !!(r && r.valid); },
         function (e) { lastFault = e; return false; });
@@ -443,6 +460,7 @@ function _parsePayload(seg, at, opts) {
   if (!_isPlainObject(payload)) throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must be a JSON object");
   if (typeof payload.legalHeader !== "string") throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must carry a string legalHeader");
   if (!intrinsic.isSafeInteger(payload.no) || payload.no < 0) throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must carry a non-negative integer no");
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (opts.previousNo !== undefined && payload.no <= opts.previousNo) {
     throw _err("webauthn/metadata-rollback", "the metadata BLOB no " + payload.no + " does not exceed the previously held " + opts.previousNo);
   }
@@ -525,7 +543,9 @@ function _parsePayload(seg, at, opts) {
   });
   var result = { no: payload.no, legalHeader: payload.legalHeader, nextUpdate: payload.nextUpdate,
     stale: stale, allowStale: opts.allowStale === true,
+    // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
     rollbackChecked: opts.previousNo !== undefined,
+    // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
     previousNo: opts.previousNo === undefined ? null : opts.previousNo,
     entries: entries, byAaguid: byAaguid, byKeyIdentifier: byKeyIdentifier,
     statusPolicy: opts.statusPolicy || "any", rejectUnknownStatus: opts.rejectUnknownStatus === true };
@@ -558,7 +578,8 @@ function metadataAnchors(entry, opts) {
   if (typeof opts !== "object" || intrinsic.isArray(opts)) throw _err("webauthn/bad-input", "metadataAnchors opts must be an object");
   guard.identifier.assertKnownKeys(opts, _ANCHOR_OPTS, _err, "webauthn/bad-input", "metadataAnchors opts has an unknown key ");
   opts = guard.identifier.ownOptions(opts);
-  if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+  if (opts.time != null) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+  // allow:caller-option-presence-tested-against-undefined -- a trust input: absence means no metadata anchor is applied, so a null must be refused
   if (opts.metadata !== undefined) {
     if (!isVerifiedResult(opts.metadata)) {
       throw _err("webauthn/bad-input", "metadataAnchors opts.metadata expects a verifyMetadataBlob result -- an object that merely resembles one has not been through the signature and chain checks");
@@ -571,7 +592,8 @@ function metadataAnchors(entry, opts) {
    *  freshness and every status report's effective date are compared against, so a replacement
    *  answering with an earlier one accepts expired metadata and suppresses a report already in
    *  effect. */
-  var at = opts.time === undefined ? new intrinsic.Date() : opts.time;
+  var at = opts.time == null ? new intrinsic.Date() : opts.time;
+  // allow:caller-option-presence-tested-against-undefined -- a trust input: absence means no metadata anchor is applied, so a null must be refused
   if (opts.metadata !== undefined) assertFresh(opts.metadata, at, "metadataAnchors");
   if (statusDenied(entry, opts.metadata, opts.certificate, at)) {
     throw _err("webauthn/metadata-status", "the metadata entry for this authenticator carries a disqualifying status report, so it registers no anchors to trust");