@blamejs/pki 0.9.4 → 0.9.6

package/lib/cms-digest.js

@@ -51,7 +51,7 @@ var _DIGEST_OPTS = intrinsic.assign(intrinsic.create(null), {
 var _VERIFY_DIGEST_OPTS = intrinsic.assign(intrinsic.create(null), { content: 1 });
 
 function _digestName(opts) {
-  var name = opts.digestAlgorithm === undefined ? "sha256" : opts.digestAlgorithm;
+  var name = opts.digestAlgorithm == null ? "sha256" : opts.digestAlgorithm;
   var key = guard.text.keyOf(name);
   if (!NODE_DIGEST[key]) {
     throw _err("cms/unsupported-algorithm", "unsupported digest algorithm " + guard.text.showValue(name) +
@@ -78,7 +78,8 @@ function _digestName(opts) {
  * @opts
  *   - `digestAlgorithm` (string) -- `sha256` (default), `sha384` or `sha512`.
  *   - `contentType` (string) -- the encapsulated content type by OID name, default `data`.
- *   - `detached` (boolean) -- omit the content, leaving the digest to travel alone.
+ *   - `detached` (boolean) -- omit the content, leaving the digest to travel alone. A value other
+ *     than `true`, `false`, `null` or an absent option is refused `cms/bad-input`.
  *   - `pem` (boolean) -- return a PEM `CMS` block instead of DER.
  * @example
  *   var der = await pki.cms.digest(Buffer.from("hello"));
@@ -94,14 +95,18 @@ async function _digest(content, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.digest options");
   guard.identifier.assertKnownKeys(opts, _DIGEST_OPTS, _err, "cms/bad-input",
     "pki.cms.digest has an unknown option ");
+  /** @internal Whether the content rides in the message is decided below by comparing this option
+   *  to `true`, so a value of any other type attached a content the caller asked to leave out. */
+  var detached = guard.identifier.booleanOption(opts.detached, _err, "cms/bad-input",
+    "pki.cms.digest opts.detached");
   var raw = guard.bytes.source(content, CmsError, "cms/bad-input", "content");
   var alg = _digestName(opts);
-  var ctName = opts.contentType === undefined ? "data" : opts.contentType;
+  var ctName = opts.contentType == null ? "data" : opts.contentType;
   var ctOid = O(ctName);
   if (!ctOid) throw _err("cms/bad-input", "opts.contentType is not a known OID name: " + guard.text.showValue(ctName));
 
   var value = guard.crypto.digest(NODE_DIGEST[alg], raw);
-  var eciChildren = opts.detached === true
+  var eciChildren = detached
     ? [b.oid(ctOid)]
     : [b.oid(ctOid), b.explicit(0, b.octetString(raw))];
   var dd = b.sequence([
@@ -164,7 +169,7 @@ async function _verifyDigest(input, opts) {
   guard.der.assertParams(parsed.digestAlgorithm.parameters, "absentOrNull", _err,
     "cms/unsupported-algorithm", parsed.digestAlgorithm.name + " digest algorithm (RFC 5754 sec. 2)");
   var embedded = parsed.encapContentInfo.eContent;
-  var supplied = opts.content === undefined ? null
+  var supplied = opts.content == null ? null
     : guard.bytes.snapshotSource(opts.content, CmsError, "cms/bad-input", "opts.content");
   if (embedded != null && supplied != null) {
     throw _err("cms/bad-input", "the DigestedData carries its own content, so opts.content is redundant");

package/lib/cms-encrypt.js

@@ -649,7 +649,12 @@ function authenticate(content, recipients, opts) {
 
 async function _authenticateImpl(content, recipients, opts) {
   opts = opts || intrinsic.create(null);
-  var withAttrs = opts.authenticatedAttributes !== false;
+  /** @internal Typed before it is used, because this switch picks the option set the door below
+   *  checks against as well as the message that gets built: with `authenticatedAttributes: false`
+   *  the MAC covers the content octets directly, so a value of any other type selected a
+   *  structurally different message than the caller asked for and said nothing. */
+  var withAttrs = guard.identifier.booleanOptionDefaultOn(opts.authenticatedAttributes, _err,
+    "cms/bad-input", "pki.cms.authenticate opts.authenticatedAttributes");
   guard.identifier.assertKnownKeys(opts, withAttrs ? _AUTHENTICATE_OPTS_ATTRS : _AUTHENTICATE_OPTS_BARE,
     _err, "cms/bad-input", function (k) {
       return "pki.cms.authenticate has an unknown option " + JSON.stringify(k) +

package/lib/cms-sign.js

@@ -186,6 +186,19 @@ function _algorithmProtectionPair(attrOid, digestAlgId, armAlgId, armTag) {
  *  The emitter below reads the same option again, which is sound because the options door refuses
  *  one supplied through an accessor, own or inherited, before any value is read: two reads of a
  *  plain field are one answer. */
+/** @internal The three switches these verbs document, typed where the options arrive. Each is read
+ *  further down by comparing it to `false`, which answers for a value of any other type as the
+ *  state the caller did not ask for: measured, `certificates: "false"` embedded the signer
+ *  certificate the caller asked to withhold, and `detached: "false"` is read as "not detached" by
+ *  the shape test and as "detached" by the content test, emitting an attached SignedData with no
+ *  content in it. Typed here, those comparisons read a value already known to be a boolean.
+ *  `detached` is not an option every one of these verbs accepts; an absent one types as absent. */
+function _assertSignSwitches(opts, verb) {
+  guard.identifier.booleanOptionDefaultOn(opts.certificates, _err, "cms/bad-input", verb + " opts.certificates");
+  guard.identifier.booleanOptionDefaultOn(opts.signedAttributes, _err, "cms/bad-input", verb + " opts.signedAttributes");
+  guard.identifier.booleanOption(opts.detached, _err, "cms/bad-input", verb + " opts.detached");
+}
+
 function _assertProtectionPlaceable(opts) {
   var wanted = cms.algorithmProtectionOid(opts.algorithmProtection, _err);
   if (opts.signedAttributes === false && wanted) {
@@ -373,6 +386,7 @@ function _signDispatch(content, signers, opts) {
 async function _signStream(stream, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.sign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertSignSwitches(opts, "pki.cms.sign");
   _assertProtectionPlaceable(opts);
   if (opts.detached !== true) {
     throw _err("cms/bad-input", "a streaming (async-iterable) content requires opts.detached: true; an attached " +
@@ -413,6 +427,7 @@ async function _signStream(stream, signers, opts) {
 function _sign(content, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.sign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertSignSwitches(opts, "pki.cms.sign");
   _assertProtectionPlaceable(opts);
   var contentBuf = _toBuf(content, "content");
   var list = Array.isArray(signers) ? _b.reqDenseArray(signers, "the signer list") : [signers];
@@ -680,6 +695,7 @@ function countersign(cmsInput, signers, opts) {
 function _countersign(cmsInput, signers, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.countersign options");
   guard.identifier.assertKnownKeys(opts, KNOWN_COUNTERSIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
+  _assertSignSwitches(opts, "pki.cms.countersign");
   _assertProtectionPlaceable(opts);
   var list = Array.isArray(signers) ? signers : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.countersign requires at least one countersigner");

package/lib/cms-verify.js

@@ -761,6 +761,7 @@ async function _verifyOneTimestamp(attr, targetSig, claimedSigningTime, opts) {
       trustAnchors: opts.timestampTrustAnchors,
       revocationChecker: opts.timestampRevocationChecker,
       allowWeakDigests: opts.allowWeakDigests === true,
+      distrustedKeys: opts.distrustedKeys,
     });
   } catch (e) {
     return guard.verdict.of({ valid: false, trusted: false, genTime: null,
@@ -975,6 +976,10 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts, allowWeakDiges
  *                 trust decision from the signer: an operator may anchor one and not the other.
  * @opts  timestampRevocationChecker  A revocation checker for the TSA chain, as `pki.path.validate`
  *                 takes one. Each row reports what it established in `revocationChecked`.
+ * @opts  distrustedKeys  SHA-256 digests of SubjectPublicKeyInfo DER (64 hexadecimal characters or
+ *                 32 bytes each, see `pki.trust.spkiDigest`), applied to the signer chain and to the
+ *                 TSA chain of every timestamp row. A listed key on a chain, the anchor included,
+ *                 reports that signer or that row as not trusted.
  * @opts  requireAlgorithmProtection  Fail a signer that carries no RFC 6211
  *                 `CMSAlgorithmProtection` attribute, with `cms/missing-algorithm-protection`. Off
  *                 by default: RFC 6211 says nothing about absence and RFC 8933 sec. 4.1 makes
@@ -1026,7 +1031,7 @@ var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), { certs: 1, content:
    *  leaving the signer unanchored, or the reverse, and one `trustAnchors` for both would make those
    *  two answers one. */
   timestampCerts: 1, timestampTrustAnchors: 1, timestampRevocationChecker: 1,
-  requireAlgorithmProtection: 1 });
+  requireAlgorithmProtection: 1, distrustedKeys: 1 });
 
 function verify(input, opts) {
   return guard.async.deferred(function () { return _verify(input, opts); });
@@ -1043,12 +1048,15 @@ async function _verify(input, opts) {
   var allowWeakDigests = opts.allowWeakDigests === true;
   var requireProtection = guard.identifier.booleanOption(opts.requireAlgorithmProtection, _err,
     "cms/bad-input", "pki.cms.verify opts.requireAlgorithmProtection");
+  /** @internal Typed here, before any signer is judged: the signer chain is built only for a signer
+   *  that verified, and every throw from a timestamp verify becomes a row. One list serves both. */
+  var distrustedKeys = guard.distrust.keys(opts.distrustedKeys, _err, "cms/bad-input", "pki.cms.verify opts.distrustedKeys");
   var parsed = guard.parsed.acceptDerived(input, "cms", function (bytes) {
     return cms.parse(_snapshotIfBytes(bytes, "pki.cms.verify"));
   }, _err, "cms/bad-input", "the SignedData");
   if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
-  var trustCfg = _snapshotTrust(opts);
-  var tsTrustCfg = _snapshotTimestampTrust(opts, allowWeakDigests);
+  var trustCfg = _snapshotTrust(opts, distrustedKeys);
+  var tsTrustCfg = _snapshotTimestampTrust(opts, allowWeakDigests, distrustedKeys);
   var parsedCerts = [];
   (parsed.certificates || []).forEach(function (c) { _addCert(parsedCerts, c && c.bytes ? c.bytes : c); });
   (opts.certs || []).forEach(function (c) { _addCert(parsedCerts, c); });
@@ -1130,7 +1138,7 @@ function _cloneAnchorValue(v, depth) {
   }
   return out;
 }
-function _snapshotTrust(opts) {
+function _snapshotTrust(opts, distrustedKeys) {
   var raw = opts.trustAnchors;
   var anchors = null;
   if (raw != null) {
@@ -1140,9 +1148,10 @@ function _snapshotTrust(opts) {
   }
   return {
     trustAnchors: anchors,
-    time: guard.time.isDate(opts.time) ? new intrinsic.Date(guard.time.instantOf(opts.time)) : (opts.time === undefined ? new intrinsic.Date() : opts.time),
+    time: guard.time.isDate(opts.time) ? new intrinsic.Date(guard.time.instantOf(opts.time)) : (opts.time == null ? new intrinsic.Date() : opts.time),
     requiredEku: Array.isArray(opts.requiredEku) ? guard.list.snapshot(opts.requiredEku) : opts.requiredEku,
     checkPurpose: opts.checkPurpose,
+    distrustedKeys: distrustedKeys,
   };
 }
 
@@ -1153,7 +1162,7 @@ function _snapshotTrust(opts) {
  *  authorities. The certificates are copied by value, since a caller holding the array could swap an
  *  entry after the row that read it. The checker is a function and is captured as the one reference
  *  every row calls. */
-function _snapshotTimestampTrust(opts, allowWeakDigests) {
+function _snapshotTimestampTrust(opts, allowWeakDigests, distrustedKeys) {
   var certs = opts.timestampCerts;
   var anchors = opts.timestampTrustAnchors;
   return {
@@ -1167,6 +1176,7 @@ function _snapshotTimestampTrust(opts, allowWeakDigests) {
       }),
     timestampRevocationChecker: opts.timestampRevocationChecker,
     allowWeakDigests: allowWeakDigests,
+    distrustedKeys: distrustedKeys,
   };
 }
 
@@ -1200,7 +1210,7 @@ async function _applyTrust(res, parsedCerts, cfg) {
   if (!anchors.length) {
     throw _err("cms/bad-input", "opts.trustAnchors is empty -- name at least one root, or omit it to state that the signer is not being anchored");
   }
-  if (cfg.time !== undefined) guard.time.assertValid(cfg.time, _err, "cms/bad-input", "opts.time");
+  if (cfg.time != null) guard.time.assertValid(cfg.time, _err, "cms/bad-input", "opts.time");
   var purposes = _engine.resolvePurposeOpts({ requiredEku: cfg.requiredEku, checkPurpose: cfg.checkPurpose });
   intrinsic.forEach(anchors, function (a) {
     _engine.toAnchor(a);
@@ -1210,7 +1220,7 @@ async function _applyTrust(res, parsedCerts, cfg) {
     var s = res.signers[_si];
     {
       if (s.ok !== true || !s.cert) { s.trusted = false; continue; }
-      var buildOpts = { trustAnchors: anchors, intermediates: pool, validate: true, time: at };
+      var buildOpts = { trustAnchors: anchors, intermediates: pool, validate: true, time: at, distrustedKeys: cfg.distrustedKeys };
       if (cfg.requiredEku != null) buildOpts.requiredEku = cfg.requiredEku;
       if (cfg.checkPurpose != null) buildOpts.checkPurpose = cfg.checkPurpose;
       if (!_keyUsagePermitsSigning(parsedCerts, s.cert)) { s.trusted = false; continue; }
@@ -1275,16 +1285,20 @@ function _addCert(out, der) {
  * the same content as the buffered form.
  *
  * @opts  detached          Omit the encapsulated content (a detached signature; the verifier
- *                          supplies the content). Default false.
+ *                          supplies the content). Default false. A value other than `true`,
+ *                          `false`, `null` or an absent option is refused `cms/bad-input`.
  * @opts  eContentType      The encapsulated content type (an OID name). Default `data`.
  * @opts  signedAttributes  Include signed attributes (content-type, message-digest, signing-time);
- *                          false signs the content directly. Default true.
+ *                          false signs the content directly. Default true. A value other than
+ *                          `true`, `false`, `null` or an absent option is refused `cms/bad-input`.
  * @opts  additionalSignedAttributes  Extra signed attributes to add to every SignerInfo, each
  *                          `{ type, values }` (`type` an OID name or dotted string, `values` an
  *                          array of DER value `Buffer`s). Covered by the signature.
  * @opts  signingTime       A `Date` for the signing-time attribute, or false to omit it.
  * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
- * @opts  certificates      Embed the signer certificates in the output. Default true.
+ * @opts  certificates      Embed the signer certificates in the output. Default true. A value other
+ *                          than `true`, `false`, `null` or an absent option is refused
+ *                          `cms/bad-input`.
  * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
  * @opts  unsignedAttributes  Unsigned attributes for every SignerInfo, each `{ type, values }`
  *                          (`type` an OID name or dotted string, `values` an array of DER value
@@ -1341,12 +1355,15 @@ var sign = cmsSign.sign;
  *                              instead of the primary signature (a nested countersignature).
  * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; never a
  *                              content-type). Default true; false signs the target signature octets
- *                              directly.
+ *                              directly. A value other than `true`, `false`, `null` or an absent
+ *                              option is refused `cms/bad-input`.
  * @opts  signingTime           A `Date` for the countersignature's signing-time, or false to omit it.
  * @opts  additionalSignedAttributes  Extra signed attributes on the countersignature (a content-type
  *                              is rejected, RFC 5652 sec. 11.4).
  * @opts  sid                   `"issuerAndSerial"` (default) or `"ski"`.
- * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default true.
+ * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default
+ *                              true. A value other than `true`, `false`, `null` or an absent option
+ *                              is refused `cms/bad-input`.
  * @opts  algorithmProtection   Emit the RFC 6211 `CMSAlgorithmProtection` attribute on the
  *                              countersignature, copying ITS own digest and signature algorithm
  *                              identifiers rather than the countersigned signature's. Off by
@@ -1440,7 +1457,8 @@ var encrypt = cmsEncrypt.encrypt;
  * @opts digestAlgorithm The authenticated-attributes message-digest hash (defaults to the MAC hash).
  * @opts authenticatedAttributes Include the content-type + message-digest authenticated attributes
  *                          (the default, and required for a non-`data` content type); false MACs the
- *                          content directly.
+ *                          content directly. A value other than `true`, `false`, `null` or an absent
+ *                          option is refused `cms/bad-input`.
  * @opts authAttrs Extra authenticated attributes appended to the content-type + message-digest pair.
  * @opts contentType The encapsulated content type (an OID name). Default `data`.
  * @opts keyIdentifier `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.

package/lib/constants.js

@@ -165,6 +165,7 @@ var LIMITS = Object.assign(Object.create(null), {
   MERKLE_MAX_PROOF_NODES: 65,
   MERKLE_MAX_LEAVES: 1048576,
   PROXY_MAX_TLS_ANCHORS: 256,
+  DISTRUSTED_KEYS_MAX: 4096,
   PATH_MAX_CERTS: 100,
   PATH_MAX_POLICY_NODES: 4096,
   PATH_BUILD_MAX_DEPTH: 20,

package/lib/crl-sign.js

@@ -770,16 +770,16 @@ function isRevoked(crl, serialNumber, opts) {
     return "pki.crl.isRevoked has an unknown option " + JSON.stringify(k) +
       "; it takes `time` and `historicalMode`";
   });
-  if (o.historicalMode !== undefined && o.time === undefined) {
+  if (o.historicalMode != null && o.time == null) {
     throw _err("crl/bad-input", "pki.crl.isRevoked opts.historicalMode says how to read an entry " +
       "against the instant asked about, so it needs opts.time as well");
   }
-  if (o.historicalMode !== undefined && typeof o.historicalMode !== "boolean") {
+  if (o.historicalMode != null && typeof o.historicalMode !== "boolean") {
     throw _err("crl/bad-input", "pki.crl.isRevoked opts.historicalMode must be a boolean");
   }
   var parsed = _coerceCrl(crl);
   var hex = _serialHexOf(serialNumber);
-  if (o.time !== undefined) {
+  if (o.time != null) {
     guard.time.assertValid(o.time, _err, "crl/bad-input", "pki.crl.isRevoked opts.time");
     var at = guard.time.instantOf(o.time);
     if (at < guard.time.instantOf(parsed.thisUpdate)) {

package/lib/csr-sign.js

@@ -114,7 +114,7 @@ function _possessionStatement(spec) {
       "privateKeyPossessionStatement needs the certificate: this verb resolves the signature algorithm from its key and checks the signature against it. Pass includeCertificate: false to leave it off the wire, which RFC 9883 sec. 3 allows");
   }
   var certDer = _b.reqDer(spec.certificate, "privateKeyPossessionStatement certificate");
-  var include = spec.includeCertificate === undefined ? true : spec.includeCertificate;
+  var include = spec.includeCertificate == null ? true : spec.includeCertificate;
   if (include !== true && include !== false) {
     throw _err("csr/bad-input", "privateKeyPossessionStatement includeCertificate is a flag, so it is true, false or omitted");
   }
@@ -172,7 +172,11 @@ function _relatedCertRequest(spec) {
  * subject-owned set `pki.x509.sign` takes, or an array of pre-encoded Extension DER) and
  * `challengePassword`. An extension the issuing CA assigns (authorityKeyIdentifier, the
  * certificate-transparency pair, the CA version and previous-certificate hash, ocspNoCheck) is not a
- * request and is refused by name. `key` (or
+ * request and is refused by name. The per-extension criticality flags `pki.x509.sign` takes
+ * (`keyUsageCritical`, default true, and `extendedKeyUsageCritical`,
+ * `certificatePoliciesCritical`, `policyMappingsCritical`, `qcStatementsCritical`,
+ * `tlsFeatureCritical`, each default false) apply here too; each is a boolean, and a value other
+ * than `true`, `false`, `null` or an absent flag is refused `csr/bad-input`. `key` (or
  * `{ key }`) is the subject's own PKCS#8 private key, WebCrypto CryptoKey, or signer
  * `{ algorithm, publicKey, sign }`, so the request is self-signed
  * to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the

package/lib/ct.js

@@ -1216,6 +1216,9 @@ function _trustValue(v, field) {
   return v;
 }
 
+/** @internal The settings `_tlsForFetch` reads. A setting not on the list is refused at the door. */
+var _TLS_KNOWN = intrinsic.freeze(guard.identifier.pickSettings(null, ["anchors", "useSystemStore", "cert", "key",
+  "minVersion", "servername", "checkServerIdentity", "distrustedKeys"]));
 function _tlsForFetch(opts) {
   /** @internal A record with NO prototype where the caller supplied no TLS at all, because the empty
    *  object a literal gives inherits from `Object.prototype` and every field below is then answerable
@@ -1232,9 +1235,12 @@ function _tlsForFetch(opts) {
   anchors = intrinsic.isArray(anchors)
     ? guard.list.copyMap(anchors, function (a, i) { return _trustValue(a, "opts.tls.anchors[" + i + "]"); })
     : _trustValue(anchors, "opts.tls.anchors");
+  /** @internal The distrust list is typed into a frozen copy. `guard.distrust.keys` reads each entry
+   *  through its descriptor and refuses an accessor, a hole and a Proxy, so no caller code runs. */
+  var distrustedKeys = guard.distrust.keys(t.distrustedKeys, _ctErr, "ct/bad-input", "opts.tls.distrustedKeys");
   return { anchors: anchors, useSystemStore: t.useSystemStore, cert: _trustValue(t.cert, "opts.tls.cert"),
     key: _trustValue(t.key, "opts.tls.key"), minVersion: t.minVersion, servername: t.servername,
-    checkServerIdentity: t.checkServerIdentity };
+    checkServerIdentity: t.checkServerIdentity, distrustedKeys: distrustedKeys };
 }
 
 function _sameOrigin(a, b) { return _urlOrigin(new _URL(a)) === _urlOrigin(new _URL(b)); }
@@ -1418,6 +1424,7 @@ function _settleDecisive(o, keyName) {
     guard.identifier.refuseAccessorFields(o.tls,
       guard.identifier.readableNames(o.tls, _ctErr, "ct/bad-input", "opts.tls"),
       _ctErr, "ct/bad-input", "opts.tls");
+    guard.identifier.assertKnownKeys(o.tls, _TLS_KNOWN, _ctErr, "ct/bad-input", "unknown opts.tls setting ");
     /** @internal And the ELEMENTS of the anchor list, which refusing accessors on `tls` itself does not
      *  reach. An accessor on `anchors[0]` runs when the list is copied, and one that overwrote
      *  `sth.rootHash` with the leaf being proven had an empty audit path verify. The refusal has to go
@@ -1652,11 +1659,17 @@ async function verifySth(sth, logKey) {
  *
  * `treeSize` and `timestamp` come back as `BigInt`, since both are uint64 on the wire.
  *
+ * `opts.tls.distrustedKeys` lists SHA-256 SubjectPublicKeyInfo digests (see pki.trust.spkiDigest). A
+ * log server whose chain carries a listed key is refused with `ct/server-key-distrusted`, and a
+ * malformed list is `ct/bad-input`. A `tls` setting other than `anchors`, `useSystemStore`, `cert`,
+ * `key`, `minVersion`, `servername`, `checkServerIdentity` and `distrustedKeys` is refused
+ * `ct/bad-input`. The other sec. 4 messages read it the same way.
+ *
  * @opts
  *   url:              string,    // the log's base URL, with or without the ct/v1/ prefix
  *   logKey:           BufferSource, // the log's SubjectPublicKeyInfo, pinned by the caller
  *   transport:        function,  // optional (request) => Promise<{ status, headers, body }>
- *   tls:              object,    // optional { anchors, useSystemStore, ... } when no transport is given
+ *   tls:              object,    // optional { anchors, useSystemStore, distrustedKeys, ... } when no transport is given
  *   headers:          object,    // optional extra request headers
  *   timeout:          number,    // optional per-request timeout in milliseconds
  *   maxResponseBytes: number,    // optional response cap
@@ -2194,7 +2207,7 @@ function _b64Array(obj, name, code, label, exactLen, maxCount) {
  * @opts signerKey REQUIRED and caller-pinned -- the distributor SubjectPublicKeyInfo as a DER Buffer; no baked-in key.
  * @opts sigUrl OPTIONAL -- the detached `log_list.sig` URL (https, must share the log-list URL's origin); default `url` with `.json` -> `.sig` (a non-.json url requires an explicit sigUrl).
  * @opts transport OPTIONAL injectable `transport(request) -> Promise<{status,headers,body}>` (default `pki.transport.https`); the test seam.
- * @opts tls OPTIONAL `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }` threaded to the default transport (ignored when a transport is injected); `rejectUnauthorized` is always on.
+ * @opts tls OPTIONAL `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity, distrustedKeys }` threaded to the default transport (ignored when a transport is injected); `rejectUnauthorized` is always on. `distrustedKeys` lists SHA-256 SubjectPublicKeyInfo digests (see pki.trust.spkiDigest): a distributor whose chain carries a listed key is refused with `ct/server-key-distrusted`, and a malformed list is `ct/bad-input`. A setting not named in that list is refused `ct/bad-input`.
  * @opts headers OPTIONAL extra request headers (the request-framing headers are stripped; the verb owns the GET method).
  * @opts timeout OPTIONAL ms budget, default 30s (cap-validated).
  * @opts maxResponseBytes OPTIONAL per-GET size cap, default 4 MiB, tightenable DOWNWARD only.