@blamejs/pki 0.9.4 → 0.9.6

package/lib/smime.js

@@ -63,7 +63,7 @@ var SIGN_OPTS = Object.assign(Object.create(null), {
 });
 var VERIFY_OPTS = Object.assign(Object.create(null), {
   certs: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, strictMicalg: 1,
-  legacyHeaderProtection: 1, expectedSender: 1, allowWeakDigests: 1,
+  legacyHeaderProtection: 1, expectedSender: 1, allowWeakDigests: 1, distrustedKeys: 1,
 });
 var ENCRYPT_OPTS = Object.assign(Object.create(null), {
   entity: 1, contentType: 1, protectHeaders: 1, headers: 1, hcp: 1,
@@ -76,12 +76,23 @@ var DECOMPRESS_OPTS = Object.assign(Object.create(null), { maxOutputBytes: 1 });
 /** @internal Checks the option names and RETURNS the options taken once. A verb reads one option to
  *  decide whether a rule applies and reads it again for the value the rule uses, and an option
  *  reached through an accessor answers each read separately. Callers assign the return value. */
+/** @internal Header protection is turned on below by comparing this option to `true`, so a value
+ *  of any other type sent the message with the RFC 9788 protection the caller asked for left off.
+ *  Typed at the one door every verb here passes through, which is before the entity is built. */
+function _assertSmimeSwitches(opts, verb) {
+  guard.identifier.booleanOption(opts.protectHeaders, _err, "smime/bad-input",
+    "pki.smime." + verb + " opts.protectHeaders");
+}
+
 function _knownOpts(opts, known, verb) {
   guard.identifier.assertKnownKeys(opts, known, _err, "smime/bad-input", function (k) {
     return "unknown option " + JSON.stringify(k) + " for pki.smime." + verb + " -- accepted: " +
       Object.keys(known).sort().join(", ");
   });
-  return guard.identifier.snapshotOptions(opts, known);
+  /** @internal Typed on the snapshot, which is the object the verb goes on to read. */
+  var settled = guard.identifier.snapshotOptions(opts, known);
+  _assertSmimeSwitches(settled, verb);
+  return settled;
 }
 
 function _isPkcs7(type, kind) {
@@ -580,9 +591,9 @@ function _hpSurface(content, outerEnt, expectedMode, authenticated, legacyEnable
 
 function _cmsSignOpts(opts, detached) {
   var o = { detached: detached };
-  if (opts.signingTime !== undefined) o.signingTime = opts.signingTime;
+  if (opts.signingTime != null) o.signingTime = opts.signingTime;
   if (opts.sid) o.sid = opts.sid;
-  if (opts.signedAttributes !== undefined) o.signedAttributes = opts.signedAttributes;
+  if (opts.signedAttributes != null) o.signedAttributes = opts.signedAttributes;
   if (opts.additionalSignedAttributes) o.additionalSignedAttributes = opts.additionalSignedAttributes;
   return o;
 }
@@ -654,7 +665,7 @@ function _base64Body(der) {
  * @opts entity      treat `content` as a complete MIME entity (default: wrap it as text/plain).
  * @opts contentType the wrapped entity's Content-Type (default `text/plain; charset=utf-8`).
  * @opts signingTime a `Date` for the CMS signing-time attribute, or false to omit it.
- * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`), inlining `opts.headers` on the signed payload + the outer display headers.
+ * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`), inlining `opts.headers` on the signed payload + the outer display headers. A value other than `true`, `false`, `null` or an absent option is refused `smime/bad-input`.
  * @opts headers     the Non-Structural fields to protect + display: an object `{ Name: value }` or an array `[{ name, value }]` (Subject / From / To / Date / ...); used with `protectHeaders`.
  * @opts hcp         the Header Confidentiality Policy applied to the OUTER display copies: `"hcp_baseline"` (default) or `"hcp_no_confidentiality"`. A signed message's payload is not encrypted, so this governs presentation, not secrecy; used with `protectHeaders`.
  * @opts sid                       forwarded to cms.sign: the SignerIdentifier form, `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
@@ -770,6 +781,9 @@ function _capped(msg) {
  * @opts time         the instant the signer's chain is judged at (default now). Only read with `trustAnchors`.
  * @opts requiredEku  key purposes the SIGNER certificate must carry. Defaults to `["emailProtection"]`.
  * @opts checkPurpose the purpose the ANCHOR's own trust metadata must permit. Defaults to `"emailProtection"`.
+ * @opts distrustedKeys SHA-256 digests of SubjectPublicKeyInfo DER (64 hexadecimal characters or 32 bytes
+ *                    each, see `pki.trust.spkiDigest`), forwarded to `cms.verify` with `trustAnchors`. A
+ *                    listed key on the signer's chain, the anchor included, reports the signer as not trusted.
  * @opts strictMicalg reject a `multipart/signed` whose `micalg` disagrees with the SignerInfo digest.
  * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): a Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner message's headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }`, where `headers` is an ordered `[{ name, value }]` array (retaining legally-repeated fields such as `Received`) and the mode is inferred from the envelope (`clear` here). They are not placed under `protectedHeaders`, and `present` stays `false`. Consuming `headerProtection.legacy.headers` is an explicit choice: a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, so this is a heuristic (RFC 9788 sec. 4.10.2: "not based on any strong end-to-end guarantees"); cross-check `legacy.fromMismatch`. Anything not precisely identified (a nested crypto layer, an `hp=` on the inner message, a non-`message/rfc822` payload, a duplicate of a singleton field, or a duplicate Content-Type) reports `legacy: null`. Off by default. The signed-and-encrypted form (RFC 9788 Appendix C.3.17) is a documented gap (`legacy: null` at `decrypt`; surfaces as `clear` only via the caller's re-`verify` step), because the non-recursive layered API exposes no single seam holding both the inner signature verdict and the outer header section.
  * @example
@@ -784,6 +798,7 @@ function _capped(msg) {
 async function verify(message, opts) {
   opts = opts || _create(null);
   opts = _knownOpts(opts, VERIFY_OPTS, "verify");
+  var distrustedKeys = guard.distrust.keys(opts.distrustedKeys, _err, "smime/bad-input", "pki.smime.verify opts.distrustedKeys");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   var vOpts = {};
@@ -792,8 +807,9 @@ async function verify(message, opts) {
     vOpts.trustAnchors = opts.trustAnchors;
     vOpts.requiredEku = opts.requiredEku != null ? opts.requiredEku : ["emailProtection"];
     vOpts.checkPurpose = opts.checkPurpose != null ? opts.checkPurpose : "emailProtection";
+    if (distrustedKeys !== null) vOpts.distrustedKeys = distrustedKeys;
   }
-  if (opts.time !== undefined) vOpts.time = opts.time;
+  if (opts.time != null) vOpts.time = opts.time;
   if (opts.allowWeakDigests === true) vOpts.allowWeakDigests = true;
   if (_isPkcs7(ct.type, "mime")) {
     if (ct.params["smime-type"] && ct.params["smime-type"] !== "signed-data") throw _err("smime/unsupported-type", "unsupported smime-type " + JSON.stringify(ct.params["smime-type"]) + " (only signed-data)");
@@ -843,10 +859,10 @@ function _envelopedTypeOf(der, badParseCode) {
 
 function _cmsEncryptOpts(opts) {
   var o = {};
-  if (opts.contentEncryptionAlgorithm !== undefined) o.contentEncryptionAlgorithm = opts.contentEncryptionAlgorithm;
-  if (opts.oaepHash !== undefined) o.oaepHash = opts.oaepHash;
-  if (opts.keyIdentifier !== undefined) o.keyIdentifier = opts.keyIdentifier;
-  if (opts.ukm !== undefined) o.ukm = opts.ukm;
+  if (opts.contentEncryptionAlgorithm != null) o.contentEncryptionAlgorithm = opts.contentEncryptionAlgorithm;
+  if (opts.oaepHash != null) o.oaepHash = opts.oaepHash;
+  if (opts.keyIdentifier != null) o.keyIdentifier = opts.keyIdentifier;
+  if (opts.ukm != null) o.ukm = opts.ukm;
   return o;
 }
 
@@ -875,7 +891,7 @@ function _cmsEncryptOpts(opts) {
  *
  * @opts entity                     treat `content` as a complete MIME entity (default: wrap it as text/plain).
  * @opts contentType                the wrapped entity's MIME Content-Type (default `text/plain; charset=utf-8`).
- * @opts protectHeaders             enable RFC 9788 header protection (`hp="cipher"`): inline `opts.headers` inside the ciphertext, emit HCP-processed outer copies, and embed the authenticated HP-Outer records (RFC 9788 sec. 2.2) documenting which fields were left visible outside.
+ * @opts protectHeaders             enable RFC 9788 header protection (`hp="cipher"`): inline `opts.headers` inside the ciphertext, emit HCP-processed outer copies, and embed the authenticated HP-Outer records (RFC 9788 sec. 2.2) documenting which fields were left visible outside. A value other than `true`, `false`, `null` or an absent option is refused `smime/bad-input`.
  * @opts headers                    the Non-Structural fields to protect (object `{ Name: value }` or array `[{ name, value }]`); the real values, hidden by the HCP.
  * @opts hcp                        the Header Confidentiality Policy: `"hcp_baseline"` (the default, obscuring Subject and removing Comments/Keywords) or `"hcp_no_confidentiality"` (leave all outer values visible). Per RFC 9788 sec. 3.2.1 / sec. 11.4, `hcp_baseline` deliberately does not strip `Bcc` (removing it can break deliverability to a Bcc'd recipient); to keep a blind recipient out of the plaintext outer headers, omit `Bcc` from `opts.headers`.
  * @opts contentEncryptionAlgorithm forwarded to cms.encrypt: `"aes-256-gcm"` (default) / `"aes-128-gcm"` / `"aes-256-cbc"` / `"aes-128-cbc"`.
@@ -961,12 +977,12 @@ async function decrypt(message, keyMaterial, opts) {
   var smimeType = _envelopedTypeOf(der, "smime/unsupported-type");
   if (opts.strictSmimeType && st && stLower !== smimeType.toLowerCase()) throw _err("smime/smime-type-mismatch", "the header smime-type " + JSON.stringify(st) + " disagrees with the CMS body (" + smimeType + ")");
   var cmsOpts = {};
-  if (opts.recipientIndex !== undefined) cmsOpts.recipientIndex = opts.recipientIndex;
-  if (opts.maxIterations !== undefined) cmsOpts.maxIterations = opts.maxIterations;
+  if (opts.recipientIndex != null) cmsOpts.recipientIndex = opts.recipientIndex;
+  if (opts.maxIterations != null) cmsOpts.maxIterations = opts.maxIterations;
   /** @internal Forwarded rather than re-decided here: an S/MIME body is a CMS structure and the rule about
    *  RSAES-PKCS1-v1_5 over an unauthenticated content belongs to the verb that opens it. An
    *  `openssl smime -encrypt` or `openssl cms -encrypt` message is exactly that combination by default. */
-  if (opts.allowUnauthenticatedRsa15 !== undefined) cmsOpts.allowUnauthenticatedRsa15 = opts.allowUnauthenticatedRsa15;
+  if (opts.allowUnauthenticatedRsa15 != null) cmsOpts.allowUnauthenticatedRsa15 = opts.allowUnauthenticatedRsa15;
   var res = await cms.decrypt(der, keyMaterial, cmsOpts);
   return Object.assign({
     content: res.content, smimeType: smimeType, authenticated: res.authenticated,
@@ -1003,7 +1019,7 @@ async function compress(content, opts) {
   opts = _knownOpts(opts, COMPRESS_OPTS, "compress");
   var entity = _entityBytes(content, opts);
   var cOpts = {};
-  if (opts.level !== undefined) cOpts.level = opts.level;
+  if (opts.level != null) cOpts.level = opts.level;
   var der = _toBuf(await cms.compress(entity, cOpts));
   var head = _pkcs7MimeHead("compressed-data", "smime.p7z");
   return _capped(Buffer.concat([head, _base64Body(der), mime.CRLF]));
@@ -1042,7 +1058,7 @@ async function decompress(message, opts) {
   if (st && st.toLowerCase() !== "compressed-data") throw _err("smime/unsupported-type", "unsupported smime-type " + JSON.stringify(st) + " (only compressed-data)");
   var der = _decodeCms(ent);
   var dOpts = {};
-  if (opts.maxOutputBytes !== undefined) dOpts.maxOutputBytes = opts.maxOutputBytes;
+  if (opts.maxOutputBytes != null) dOpts.maxOutputBytes = opts.maxOutputBytes;
   var res = await cms.decompress(der, dOpts);
   return { content: res.content, contentType: res.contentType, contentTypeName: res.contentTypeName, compressionAlgorithm: res.compressionAlgorithm };
 }

package/lib/tls-cert-compress.js

@@ -88,7 +88,7 @@ var HEADER_BYTES = 8;
 
 function _resolveCap(opts) {
   var cap = C.LIMITS.TLS_CERT_MSG_MAX_BYTES;
-  if (opts.maxOutputBytes !== undefined) {
+  if (opts.maxOutputBytes != null) {
     var mo = opts.maxOutputBytes;
     if (typeof mo !== "number" || !isFinite(mo) || mo <= 0 || Math.floor(mo) !== mo) {
       throw _err("tls/bad-input", "opts.maxOutputBytes must be a positive integer");
@@ -99,6 +99,7 @@ function _resolveCap(opts) {
 }
 
 function _resolveAllowed(opts) {
+  // allow:caller-option-presence-tested-against-undefined -- absence accepts every codec this build supports, so a null must be refused rather than widen the allowlist
   if (opts.allowedAlgorithms === undefined) return SUPPORTED.slice();
   var list = opts.allowedAlgorithms;
   if (!Array.isArray(list)) throw _err("tls/bad-input", "opts.allowedAlgorithms must be an array of algorithm names or numbers");
@@ -263,7 +264,7 @@ function decompressCertificate(bytes, opts) {
  */
 function parseCertificateMessage(bytes, opts) {
   opts = opts || intrinsic.create(null);
-  var type = opts.certificateType === undefined ? "X509" : opts.certificateType;
+  var type = opts.certificateType == null ? "X509" : opts.certificateType;
   if (type !== "X509" && type !== "RawPublicKey") {
     throw _err("tls/bad-input", "opts.certificateType must be \"X509\" or \"RawPublicKey\"");
   }
@@ -330,7 +331,7 @@ function compressCertificate(certificateMessage, opts) {
       " bytes, over the " + C.LIMITS.TLS_CERT_MSG_MAX_BYTES + "-byte handshake framing limit");
   }
   var view = guard.bytes.snapshot(viewed, TlsError, "tls/bad-input", "the certificate message");
-  var sel = opts.algorithm === undefined ? "zlib" : opts.algorithm;
+  var sel = opts.algorithm == null ? "zlib" : opts.algorithm;
   var name = (typeof sel === "number") ? ALG_BY_NUMBER[sel] : sel;
   if (typeof name !== "string" || SUPPORTED.indexOf(name) === -1) {
     throw _err("tls/unsupported-algorithm", "opts.algorithm names an algorithm this toolkit cannot compress: " + JSON.stringify(sel));
@@ -338,12 +339,12 @@ function compressCertificate(certificateMessage, opts) {
   if (view.length < MIN_CERT_MSG_BYTES) {
     throw _err("tls/bad-input", "a Certificate message is at least " + MIN_CERT_MSG_BYTES + " bytes (RFC 8446 sec. 4.4.2)");
   }
-  if (opts.level !== undefined && (typeof opts.level !== "number" || !isFinite(opts.level) || Math.floor(opts.level) !== opts.level)) {
+  if (opts.level != null && (typeof opts.level !== "number" || !isFinite(opts.level) || Math.floor(opts.level) !== opts.level)) {
     throw _err("tls/bad-input", "opts.level must be an integer");
   }
   var stream;
   try {
-    stream = COMPRESS[name](view, opts.level !== undefined ? LEVEL_OPT[name](opts.level) : undefined);
+    stream = COMPRESS[name](view, opts.level != null ? LEVEL_OPT[name](opts.level) : undefined);
   } catch (e) {
     throw _err("tls/bad-input", "the certificate message could not be compressed (check opts.level)", e);
   }

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,52 @@ 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.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 +1365,35 @@ 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 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 +1410,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 +1430,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 +1448,36 @@ 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);
+  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) {
+  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) };
+  }
+  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 +1516,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 +1527,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 +1566,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 +1628,5 @@ module.exports = intrinsic.freeze({
   systemAnchors: systemAnchors,
   discoversBundles: discoversBundles,
   anchor: anchor,
+  spkiDigest: spkiDigest,
 });

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

@@ -123,7 +123,9 @@ function _signingCertV2(certDer, hashName) {
  * @opts  nonce         The request nonce to echo (a number or BigInt), for replay protection.
  * @opts  accuracy      The genTime +/- accuracy, as `{ seconds?, millis?, micros? }`, naming at
  *                      least one field; omit it to make no accuracy claim.
- * @opts  ordering      Whether tokens from this TSA are strictly ordered in time (boolean).
+ * @opts  ordering      Whether tokens from this TSA are strictly ordered in time (boolean). A value
+ *                      other than `true`, `false`, `null` or an absent option is refused
+ *                      `tsp/bad-input`.
  * @opts  certHashAlgorithm  The ESSCertIDv2 hash algorithm name. Default `sha256`.
  * @opts  digestAlgorithm / pss  Passed through to `pki.cms.sign` (the signer digest algorithm, RSA-PSS padding).
  * @opts  additionalSignedAttributes  Extra signed attributes to carry on the token, as `[{ type, values }]` (forwarded to `pki.cms.sign`).
@@ -163,6 +165,11 @@ function _sign(messageImprint, tsa, opts) {
   }
   guard.identifier.assertKnownKeys(opts, _SIGN_OPTS, _err, "tsp/bad-input", "pki.tsp.sign has an unknown option ");
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.sign options must be an object");
+  /** @internal The ordering claim is emitted below only for the boolean `true`, so a value of any
+   *  other type left the TSTInfo saying the opposite of what the caller asked, which is what RFC
+   *  3161 sec. 2.4.2 has a relying party read to compare two tokens from this TSA. `certReq` on the
+   *  request verb has been typed since it was written; this is the same read. */
+  guard.identifier.booleanOption(opts.ordering, _err, "tsp/bad-input", "pki.tsp.sign opts.ordering");
   if (tsa && typeof tsa === "object" && !Buffer.isBuffer(tsa)) {
     guard.identifier.assertKnownKeys(tsa, _TSA_KEYS, _err, "tsp/bad-input", function (k) {
       return "unknown TSA field " + JSON.stringify(k) +
@@ -643,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);
@@ -657,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; });
@@ -677,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;
@@ -725,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;