@blamejs/pki 0.9.4 → 0.9.6

package/lib/acme.js

@@ -321,10 +321,41 @@ function _checkType(kind, field, value, obj) {
   return null;
 }
 
-function _codeSlug(kind) {
-  var out = "";
-  for (var i = 0; i < kind.length; i++) { var c = _charCodeAt(kind, i); if (c >= 65 && c <= 90) out += "-"; out += _charAt(kind, i); }
-  return _lower(out);
+/** @internal The code each resource kind is refused with, written out. A code assembled at
+ *  runtime from the kind is not a frozen contract: it cannot be read off the source, so the
+ *  api-snapshot recorded the stem and none of these six, and renaming or losing one would
+ *  have passed every gate. An unknown kind cannot reach here (the caller's kind is checked
+ *  first), and falls back to the module's general input code rather than inventing one. */
+var BAD_BY_KIND = intrinsic.assign(intrinsic.create(null), {
+  directory: "acme/bad-directory",
+  account: "acme/bad-account",
+  order: "acme/bad-order",
+  authorization: "acme/bad-authorization",
+  challenge: "acme/bad-challenge",
+  renewalInfo: "acme/bad-renewal-info",
+  ordersList: "acme/bad-orders-list",
+});
+/** @internal The table above is written out so the codes can be read off the source, and this
+ *  holds it to SPECS so it cannot drift from the kinds that use it: a kind added to SPECS
+ *  without a code here would have been refused with the general input code, losing the one
+ *  that names the resource. Measured the hard way, by omitting `ordersList`. */
+(function () {
+  var kinds = _objectKeys(SPECS);
+  for (var i = 0; i < kinds.length; i++) {
+    if (BAD_BY_KIND[kinds[i]] === undefined) {
+      throw new Error("acme: SPECS kind " + kinds[i] + " has no entry in BAD_BY_KIND");
+    }
+  }
+  var coded = _objectKeys(BAD_BY_KIND);
+  for (var j = 0; j < coded.length; j++) {
+    if (SPECS[coded[j]] === undefined) {
+      throw new Error("acme: BAD_BY_KIND names " + coded[j] + ", which is not a SPECS kind");
+    }
+  }
+})();
+function _badKindCode(kind) {
+  var code = BAD_BY_KIND[guard.text.keyOf(kind)];
+  return code === undefined ? "acme/bad-input" : code;
 }
 
 /** @internal The NAMED members of a caller's resource object, read ONCE each into a plain record. A
@@ -363,7 +394,7 @@ var SPEC_NAMES = intrinsic.create(null);
 })();
 
 function _validate(kind, obj, pre) {
-  if (!_isObject(obj)) throw E("acme/bad-" + _codeSlug(kind), "an ACME " + kind + " must be a JSON object");
+  if (!_isObject(obj)) throw E(_badKindCode(kind), "an ACME " + kind + " must be a JSON object");
   var spec = SPECS[kind];
   /** @internal Every own member is read ONCE, here, before any check runs, and every check below decides
    *  from this reading. The walk used to read `obj[field.name]` three times per field, for the closed-enum
@@ -396,7 +427,7 @@ function _validate(kind, obj, pre) {
       throw E("acme/bad-status", "the " + kind + " " + field.name + " " + JSON.stringify(value) + " is not a recognized value");
     }
     var err = _checkType(kind, field, value, read);
-    if (err) throw E("acme/bad-" + _codeSlug(kind), "the " + kind + " field " + JSON.stringify(field.name) + " " + err);
+    if (err) throw E(_badKindCode(kind), "the " + kind + " field " + JSON.stringify(field.name) + " " + err);
   }
   return obj;
 }
@@ -866,16 +897,16 @@ function newAccount(o) {
   o = _gateRequestOpts(o, "newAccount");
   if (!_isObject(o.jwk)) throw E("acme/bad-input", "newAccount must embed the account public jwk (RFC 8555 sec. 7.3)");
   var payload = {};
-  if (o.contact !== undefined) { _assertContacts(o.contact); payload.contact = o.contact; }
-  if (o.termsOfServiceAgreed !== undefined) {
+  if (o.contact != null) { _assertContacts(o.contact); payload.contact = o.contact; }
+  if (o.termsOfServiceAgreed != null) {
     if (typeof o.termsOfServiceAgreed !== "boolean") throw E("acme/bad-input", "termsOfServiceAgreed must be a boolean");
     payload.termsOfServiceAgreed = o.termsOfServiceAgreed;
   }
-  if (o.onlyReturnExisting !== undefined) {
+  if (o.onlyReturnExisting != null) {
     if (typeof o.onlyReturnExisting !== "boolean") throw E("acme/bad-input", "onlyReturnExisting must be a boolean");
     payload.onlyReturnExisting = o.onlyReturnExisting;
   }
-  if (o.externalAccountBinding !== undefined) {
+  if (o.externalAccountBinding != null) {
     if (!_isObject(o.externalAccountBinding)) throw E("acme/bad-input", "externalAccountBinding must be an EAB inner JWS object");
     payload.externalAccountBinding = o.externalAccountBinding;
   }
@@ -969,9 +1000,9 @@ function newOrder(o) {
   o = _gateRequestOpts(o, "newOrder");
   if (!Array.isArray(o.identifiers) || o.identifiers.length === 0) throw E("acme/bad-order", "newOrder requires a non-empty identifiers array (RFC 8555 sec. 7.4)");
   var payload = { identifiers: o.identifiers.map(_validateOrderIdentifier) };
-  if (o.notBefore !== undefined) { if (!_isRfc3339(o.notBefore)) throw E("acme/bad-order", "notBefore must be an RFC 3339 date-time"); payload.notBefore = o.notBefore; }
-  if (o.notAfter !== undefined) { if (!_isRfc3339(o.notAfter)) throw E("acme/bad-order", "notAfter must be an RFC 3339 date-time"); payload.notAfter = o.notAfter; }
-  if (o.replaces !== undefined) { if (!_isString(o.replaces)) throw E("acme/bad-order", "replaces must be an ARI certID string (RFC 9773 sec. 5)"); payload.replaces = o.replaces; }
+  if (o.notBefore != null) { if (!_isRfc3339(o.notBefore)) throw E("acme/bad-order", "notBefore must be an RFC 3339 date-time"); payload.notBefore = o.notBefore; }
+  if (o.notAfter != null) { if (!_isRfc3339(o.notAfter)) throw E("acme/bad-order", "notAfter must be an RFC 3339 date-time"); payload.notAfter = o.notAfter; }
+  if (o.replaces != null) { if (!_isString(o.replaces)) throw E("acme/bad-order", "replaces must be an ARI certID string (RFC 9773 sec. 5)"); payload.replaces = o.replaces; }
   return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
   });
 }
@@ -1154,7 +1185,7 @@ async function finalize(o) {
   if (!guard.bytes.isByteSource(o.csr)) throw E("acme/bad-input", "finalize requires a DER CSR BufferSource (opts.csr)");
   var csrBuf = guard.bytes.snapshotSource(o.csr, E, "acme/bad-input", "the finalize CSR");
   var ids = null;
-  if (identifiers !== undefined) {
+  if (identifiers != null) {
     if (!Array.isArray(identifiers) || identifiers.length === 0) throw E("acme/bad-input", "finalize identifiers must be the non-empty order identifier array");
     ids = [];
     for (var ii = 0; ii < identifiers.length; ii++) {
@@ -1165,7 +1196,7 @@ async function finalize(o) {
     }
   }
   var parsed = csr.parse(csrBuf);
-  if (accountJwk !== undefined) {
+  if (accountJwk != null) {
     var accountSpki = await _jwkToSpki(accountJwk);
     if (parsed.subjectPublicKeyInfo && Buffer.isBuffer(parsed.subjectPublicKeyInfo.bytes) &&
         parsed.subjectPublicKeyInfo.bytes.equals(accountSpki)) {
@@ -1202,7 +1233,7 @@ function challengeResponse(o) {
   return _promised(function () {
     if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
     o = _gateRequestOpts(o, "challengeResponse");
-    var payload = o.payload !== undefined ? o.payload : {};
+    var payload = o.payload != null ? o.payload : {};
     if (!_isObject(payload)) throw E("acme/bad-input", "a challenge response payload must be a JSON object (RFC 8555 sec. 7.5.1)");
     return _signOuter({ key: o.key, alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload);
   });
@@ -1301,7 +1332,7 @@ function revokeCert(o) {
   var hasJwk = _hasOwn(o, "jwk");
   if (hasKid === hasJwk) throw E("acme/bad-input", "revokeCert must be signed with EXACTLY ONE of the account kid or the certificate jwk (RFC 8555 sec. 7.6)");
   var payload = { certificate: jose.base64url.encode(certBuf) };
-  if (o.reason !== undefined) {
+  if (o.reason != null) {
     if (typeof o.reason !== "number" || !isFinite(o.reason) || Math.floor(o.reason) !== o.reason || CRL_REASONS.indexOf(o.reason) === -1) {
       throw E("acme/bad-revocation-reason", "reason must be an assigned RFC 5280 CRLReason (0-6, 8-10; value 7 is unassigned)");
     }
@@ -1514,10 +1545,17 @@ function _queryRepaired(rawRef, resolvedUrl) {
   return qi !== -1 && rawRef.slice(qi).split("#")[0] !== _urlSearch(resolvedUrl);
 }
 var _defaultSleep = require("./sleep").sleep;
-/** @internal The settings this client forwards to its transport. */
-var TLS_SETTINGS = ["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity"];
+/** @internal The settings this client forwards to its transport. The distrust list is typed here, when
+ *  the client is built, and the frozen copy is the one every request carries. A setting not on the list
+ *  is refused. */
+var TLS_SETTINGS = ["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity", "distrustedKeys"];
+var TLS_KNOWN = intrinsic.freeze(guard.identifier.pickSettings(null, TLS_SETTINGS));
 function _clientTls(o) {
-  return guard.identifier.pickSettings(o.tls, TLS_SETTINGS);
+  var tls = o.tls;
+  guard.identifier.assertKnownKeys(tls, TLS_KNOWN, E, "acme/bad-input", "unknown opts.tls setting ");
+  var t = guard.identifier.pickSettings(tls, TLS_SETTINGS);
+  t.distrustedKeys = guard.distrust.keys(t.distrustedKeys, E, "acme/bad-input", "opts.tls.distrustedKeys");
+  return t;
 }
 function _splitPemChain(text) {
   var ders;
@@ -1877,7 +1915,7 @@ function _parseLinkNext(headers, base) { var m = _parseLinkRelation(headers, bas
  * @opts
  *   - `accountKey` / `accountJwk` / `alg` -- REQUIRED: the account private key, its public JWK, and the JWS alg.
  *   - `transport` -- injectable `transport(request) -> Promise<{status, headers, body}>`; default pki.transport.https. It must return a promise of the response; anything else is `acme/bad-input`.
- *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity } for the default transport.
+ *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity, distrustedKeys } for the default transport. `distrustedKeys` lists SHA-256 SubjectPublicKeyInfo digests (see pki.trust.spkiDigest); a server whose chain carries a listed key is refused with `acme/server-key-distrusted`, on every request including a cross-origin one, and a malformed list is `acme/bad-input` when the client is built. A setting not named in that list is refused `acme/bad-input` when the client is built.
  *   - `timeout` / `maxResponseBytes` / `maxRedirects` -- transport budgets; `maxNonceRetries` -- badNonce retry cap (default 1).
  *   - `proxy` -- reach the ACME server through a forward HTTP proxy (`{ url, auth?, tls? }`; see pki.transport).
  *   - `maxPolls` / `maxTotalWait` / `sleep` -- poll-loop budgets + an injectable sleeper; `clock` -- an injectable receipt clock (default Date.now) for a Retry-After HTTP-date.
@@ -1976,14 +2014,16 @@ function client(directoryUrl, opts) {
   var resignKeys = _resignKeysOf(opts.resignKeys);
 
   var transport = checkedTransport;
+  /** @internal One record answers both the trust-anchor check and every request. */
+  var clientTls = _clientTls(opts);
   if (!transport) {
-    var t0 = opts.tls != null ? opts.tls : intrinsic.create(null);
+    var t0 = clientTls;
     var hasAnchors = t0.anchors !== undefined && t0.anchors !== null && !(Array.isArray(t0.anchors) && t0.anchors.length === 0);
     if (!hasAnchors && t0.useSystemStore !== true) throw E("acme/no-trust-anchors", "no explicit trust anchor and tls.useSystemStore not set to true (RFC 8555 sec. 6.1)");
     transport = httpTransport.https({ E: E, errPrefix: "acme" });
   }
   var budgets = {
-    tls: _clientTls(opts),
+    tls: clientTls,
     proxy: httpTransport.snapshotProxy(opts.proxy),
     timeout: guard.limits.cap(opts.timeout, "timeout", CLIENT_DEFAULT_TIMEOUT, { E: E, code: "acme/bad-input", min: 1, max: CLIENT_MAX_TIMEOUT }),
     maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "acme/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
@@ -2234,17 +2274,17 @@ function client(directoryUrl, opts) {
 
   function _bindingSpec(opts) {
     var spki = opts.expectedSpki, ids = opts.identifiers, req = opts.requireBinding;
-    if (spki !== undefined) {
+    if (spki != null) {
       if (!guard.bytes.isByteSource(spki)) throw E("acme/bad-input", "downloadCertificate opts.expectedSpki must be a DER SubjectPublicKeyInfo BufferSource");
       spki = guard.bytes.snapshotSource(spki, AcmeError, "acme/bad-input", "downloadCertificate expectedSpki");
     }
-    if (ids !== undefined) {
+    if (ids != null) {
       if (!_isArrayI(ids) || ids.length === 0) throw E("acme/bad-input", "downloadCertificate opts.identifiers must be the non-empty order identifier array");
       ids = _mapI(ids, _validateOrderIdentifier);
     }
-    if (req !== undefined && typeof req !== "boolean") throw E("acme/bad-input", "downloadCertificate opts.requireBinding must be a boolean");
-    var require_ = req === undefined ? true : req;
-    if (require_ && spki === undefined && ids === undefined) {
+    if (req != null && typeof req !== "boolean") throw E("acme/bad-input", "downloadCertificate opts.requireBinding must be a boolean");
+    var require_ = req == null ? true : req;
+    if (require_ && spki == null && ids == null) {
       throw E("acme/binding-required",
         "downloadCertificate needs the material that binds the issued certificate to this order -- " +
         "opts.expectedSpki (the DER SubjectPublicKeyInfo the CSR asked to have certified) and/or " +
@@ -2258,7 +2298,7 @@ function client(directoryUrl, opts) {
     var leaf;
     try { leaf = x509.parse(leafDer); }
     catch (e) { throw E("acme/bad-certificate-chain", "the downloaded end-entity certificate did not parse (RFC 8555 sec. 7.4.2)", e); }
-    if (spec.spki !== undefined) {
+    if (spec.spki != null) {
       var got = leaf.subjectPublicKeyInfo && leaf.subjectPublicKeyInfo.bytes;
       if (!_isBuffer(got) || !guard.crypto.constantTimeEqual(got, spec.spki)) {
         throw E("acme/certificate-key-mismatch",
@@ -2266,7 +2306,7 @@ function client(directoryUrl, opts) {
           "to have certified, so it cannot be used with the private key held here (RFC 8555 sec. 7.4)");
       }
     }
-    if (spec.ids !== undefined) {
+    if (spec.ids != null) {
       var have = _certIdentifierSet(leaf), want = _orderIdentifierSet(spec.ids);
       var haveKeys = _objectKeys(have), wantKeys = _objectKeys(want);
       var mismatch = haveKeys.length !== wantKeys.length ||
@@ -2284,7 +2324,7 @@ function client(directoryUrl, opts) {
     return _resolve(_Promise, undefined).then(function () {
       opts = _gateOpts(opts, _METHOD_OPTS.download, "downloadCertificate");
       var select = opts.selectChain;
-      if (select !== undefined && typeof select !== "function") throw E("acme/bad-input", "downloadCertificate opts.selectChain must be a function");
+      if (select != null && typeof select !== "function") throw E("acme/bad-input", "downloadCertificate opts.selectChain must be a function");
       var maxAlt = guard.limits.cap(opts.maxAlternates, "maxAlternates", DEFAULT_MAX_ALTERNATES, { E: E, code: "acme/bad-input", min: 0, max: 64 });
       var binding = _bindingSpec(opts);
       var dlUrl = _clientUrl(url);
@@ -2297,7 +2337,10 @@ function client(directoryUrl, opts) {
         function result(cand) {
           _assertCertBinding(cand.certificate, binding);
           return { certificate: cand.certificate, chain: cand.chain, certificates: cand.certificates, alternates: alternates,
-            boundToKey: binding.spki !== undefined, boundToIdentifiers: binding.ids !== undefined };
+            /** @internal Read as "not absent", not as "not undefined": with the binding
+             *  material left out as `null` the record carries a null, and a test against
+             *  `undefined` alone reported the certificate as bound to a key nobody named. */
+            boundToKey: binding.spki != null, boundToIdentifiers: binding.ids != null };
         }
         if (!select) return result(primary);
         return _resolve(_Promise, select(primary)).then(function (primaryMatch) {
@@ -2327,7 +2370,7 @@ function client(directoryUrl, opts) {
       var certKeyMode = o.certKey != null || _isObject(o.certJwk) || o.certAlg != null;
       if (certKeyMode && !(o.certKey != null && _isObject(o.certJwk) && _isString(o.certAlg))) throw E("acme/bad-input", "revokeCert certificate-key mode requires certKey, certJwk, AND certAlg together, or none (RFC 8555 sec. 7.6)");
       var extra = { certificate: o.certificate };
-      if (o.reason !== undefined) extra.reason = o.reason;
+      if (o.reason != null) extra.reason = o.reason;
       return _resource("revokeCert").then(function (url) {
         if (certKeyMode) {
           return _postJws(url, function (nonce) {
@@ -2347,10 +2390,10 @@ function client(directoryUrl, opts) {
   function _updateAccount(o) {
     return _promised(function () {
       o = guard.identifier.optionsObject(o, E, "acme/bad-input", "pki.acme updateAccount options");
-      if (o.status !== undefined) throw E("acme/bad-input", "updateAccount cannot change the account status; use deactivateAccount (RFC 8555 sec. 7.3.6 is the only client-settable status)");
-      if (o.termsOfServiceAgreed !== undefined) throw E("acme/bad-input", "the server MUST ignore a termsOfServiceAgreed update to the account (RFC 8555 sec. 7.3.2); it is set at account creation, and a changed-terms CA answers with a userActionRequired problem (sec. 7.3.3) directing a human to the terms URL");
-      if (o.orders !== undefined) throw E("acme/bad-input", "the account orders URL is server-assigned and cannot be updated (RFC 8555 sec. 7.3.2)");
-      if (o.externalAccountBinding !== undefined) throw E("acme/bad-input", "externalAccountBinding is not updateable by the client (RFC 8555 sec. 7.1.2 / 7.3.4)");
+      if (o.status != null) throw E("acme/bad-input", "updateAccount cannot change the account status; use deactivateAccount (RFC 8555 sec. 7.3.6 is the only client-settable status)");
+      if (o.termsOfServiceAgreed != null) throw E("acme/bad-input", "the server MUST ignore a termsOfServiceAgreed update to the account (RFC 8555 sec. 7.3.2); it is set at account creation, and a changed-terms CA answers with a userActionRequired problem (sec. 7.3.3) directing a human to the terms URL");
+      if (o.orders != null) throw E("acme/bad-input", "the account orders URL is server-assigned and cannot be updated (RFC 8555 sec. 7.3.2)");
+      if (o.externalAccountBinding != null) throw E("acme/bad-input", "externalAccountBinding is not updateable by the client (RFC 8555 sec. 7.1.2 / 7.3.4)");
       guard.identifier.assertKnownKeys(o, _METHOD_OPTS.updateAccount, E, "acme/bad-input", "unknown updateAccount option ");
       var account = _requireKid();
       return _post(account, updateAccount, { contact: o.contact }, "kid").then(function (res) { return validate("account", _json(res)); });
@@ -2435,10 +2478,10 @@ function client(directoryUrl, opts) {
     return _resolve(_Promise, undefined).then(function () {
       o = _gateOpts(o, _METHOD_OPTS.renewalWindow, "renewalWindow");
       if (!guard.bytes.isByteSource(certDer)) throw E("acme/bad-input", "renewalWindow requires a DER certificate BufferSource");
-      if (o.random !== undefined && typeof o.random !== "function") throw E("acme/bad-input", "renewalWindow opts.random must be a function returning a number in [0, 1]");
-      if (o.clock !== undefined && typeof o.clock !== "function") throw E("acme/bad-input", "renewalWindow opts.clock must be a function returning epoch milliseconds");
-      if (o.replaced !== undefined && typeof o.replaced !== "boolean") throw E("acme/bad-input", "renewalWindow opts.replaced must be a boolean");
-      if (o.previous !== undefined && !_isObject(o.previous)) throw E("acme/bad-input", "renewalWindow opts.previous must be a prior renewalWindow result object");
+      if (o.random != null && typeof o.random !== "function") throw E("acme/bad-input", "renewalWindow opts.random must be a function returning a number in [0, 1]");
+      if (o.clock != null && typeof o.clock !== "function") throw E("acme/bad-input", "renewalWindow opts.clock must be a function returning epoch milliseconds");
+      if (o.replaced != null && typeof o.replaced !== "boolean") throw E("acme/bad-input", "renewalWindow opts.replaced must be a boolean");
+      if (o.previous != null && !_isObject(o.previous)) throw E("acme/bad-input", "renewalWindow opts.previous must be a prior renewalWindow result object");
       /** @internal `previous` is READ ONCE, here, before the await below, and the stickiness decision
        *  reads this reading. It was validated as an object here and then read three more times after the
        *  renewalInfo fetch: `o.previous.suggestedWindow` twice in one expression, and
@@ -2446,7 +2489,7 @@ function client(directoryUrl, opts) {
        *  each read separately and the fetch is the window in which to change its answer, so the prior
        *  window this compares against need not be the one the caller validated, and a non-object arriving
        *  after the await reached `.start` and raised a bare TypeError. */
-      var prev = o.previous === undefined ? undefined : _readOnce(o.previous, PREVIOUS_WINDOW_NAMES);
+      var prev = o.previous == null ? undefined : _readOnce(o.previous, PREVIOUS_WINDOW_NAMES);
       var prevWindow = prev && _isObject(prev.suggestedWindow) ? _readOnce(prev.suggestedWindow, WINDOW_BOUND_NAMES) : null;
       var _clk = typeof o.clock === "function" ? o.clock : clock;
       function clk() { var t = _clk(); if (typeof t !== "number" || !isFinite(t)) throw E("acme/bad-input", "the renewalWindow clock returned a non-finite value"); return t; }
@@ -2490,11 +2533,13 @@ function client(directoryUrl, opts) {
     return _resolve(_Promise).then(function () {
       o = _gateOpts(o, _METHOD_OPTS.scheduleRenewal, "scheduleRenewal");
       if (!guard.bytes.isByteSource(certDer)) throw E("acme/bad-input", "scheduleRenewal requires a DER certificate BufferSource");
-      if (o.random !== undefined && typeof o.random !== "function") throw E("acme/bad-input", "scheduleRenewal opts.random must be a function returning a number in [0, 1]");
-      if (o.shouldStop !== undefined && typeof o.shouldStop !== "function") throw E("acme/bad-input", "scheduleRenewal opts.shouldStop must be a function returning a boolean");
-      if (o.renew !== undefined && typeof o.renew !== "function") throw E("acme/bad-input", "scheduleRenewal opts.renew must be an async function (decision) -> newCertDer | void");
+      if (o.random != null && typeof o.random !== "function") throw E("acme/bad-input", "scheduleRenewal opts.random must be a function returning a number in [0, 1]");
+      if (o.shouldStop != null && typeof o.shouldStop !== "function") throw E("acme/bad-input", "scheduleRenewal opts.shouldStop must be a function returning a boolean");
+      if (o.renew != null && typeof o.renew !== "function") throw E("acme/bad-input", "scheduleRenewal opts.renew must be an async function (decision) -> newCertDer | void");
+      /** @internal The value handed in is the caller's own option, so absence keeps both
+       *  of its forms here: a `null` states no count and reads as an omitted one. */
       function optCount(v, name) {
-        if (v === undefined) return null;
+        if (v == null) return null;
         if (typeof v !== "number" || !intrinsic.isFinite(v) || v < 1 || intrinsic.floor(v) !== v) throw E("acme/bad-input", "scheduleRenewal opts." + name + " must be a positive integer");
         return v;
       }

package/lib/attrcert-sign.js

@@ -709,7 +709,7 @@ function _checkTargeting(ac, want) {
     if (ac.extensions[i].name === "targetInformation") ext = ac.extensions[i];
   }
   if (!ext) return guard.verdict.of({ checked: true, ok: true });
-  if (want === undefined) {
+  if (want == null) {
     return guard.verdict.of({ checked: false, ok: false,
       reason: "this attribute certificate is targeted, and no opts.target names this verifier (RFC 5755 sec. 4.3.2)" });
   }
@@ -860,11 +860,12 @@ function _fixVerifyOptions(opts) {
   guard.identifier.assertKnownKeys(o, KNOWN_VERIFY_OPTS, _err, "attrcert/bad-input",
     "pki.attrcert.verify has an unknown option ");
   var at = null;
-  if (o.time !== undefined) {
+  if (o.time != null) {
     guard.time.assertValid(o.time, _err, "attrcert/bad-input", "pki.attrcert.verify opts.time");
     at = guard.time.instantOf(o.time);
   }
   var revocationStatus = null;
+  // allow:caller-option-presence-tested-against-undefined -- absence means no revocation status is applied, so a null must be refused
   if (o.revocationStatus !== undefined) {
     if (typeof o.revocationStatus !== "string" ||
       !_hasOwn(REVOCATION_STATUS, o.revocationStatus)) {
@@ -874,7 +875,7 @@ function _fixVerifyOptions(opts) {
   }
   return {
     at: at, revocationStatus: revocationStatus,
-    target: o.target === undefined ? undefined : _callerTarget(o.target),
+    target: o.target == null ? undefined : _callerTarget(o.target),
   };
 }
 

package/lib/cmp-build.js

@@ -1009,10 +1009,16 @@ function _cmpMessageDer(input) {
   return der;
 }
 
-/** @internal The settings this transfer forwards to its transport. */
-var TLS_SETTINGS = ["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity"];
+/** @internal The settings this transfer forwards to its transport, with the distrust list typed into a
+ *  frozen copy. A setting not on the list is refused. */
+var TLS_SETTINGS = ["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity", "distrustedKeys"];
+var TLS_KNOWN = intrinsic.freeze(guard.identifier.pickSettings(null, TLS_SETTINGS));
 function _tlsForTransfer(opts) {
-  return guard.identifier.pickSettings(opts.tls, TLS_SETTINGS);
+  var tls = opts.tls;
+  guard.identifier.assertKnownKeys(tls, TLS_KNOWN, _err, "cmp/bad-input", "unknown opts.tls setting ");
+  var t = guard.identifier.pickSettings(tls, TLS_SETTINGS);
+  t.distrustedKeys = guard.distrust.keys(t.distrustedKeys, _err, "cmp/bad-input", "opts.tls.distrustedKeys");
+  return t;
 }
 
 /** @internal The media type is read through the captured operations, and on the delimiter CHARACTER
@@ -1076,8 +1082,10 @@ function _transfer(url, message, opts) {
   var parsedUrl;
   try { parsedUrl = new _URL(_stringOf(url)); }
   catch (e) { throw _err("cmp/bad-url", "the CMP URL did not parse: " + guard.text.showValue(url), e); }
+  /** @internal One record answers both the trust-anchor check and the request. */
+  var tls = _tlsForTransfer(opts);
   if (!transport) {
-    var t = opts.tls != null ? opts.tls : intrinsic.create(null);
+    var t = tls;
     var hasAnchors = t.anchors !== undefined && t.anchors !== null && !(Array.isArray(t.anchors) && t.anchors.length === 0);
     if (!hasAnchors && t.useSystemStore !== true) throw _err("cmp/no-trust-anchors", "no explicit trust anchor and tls.useSystemStore not set to true -- refusing an unpinned server (RFC 9811 sec. 5)");
     transport = httpTransport.https({ E: _err, errPrefix: "cmp" });
@@ -1093,7 +1101,6 @@ function _transfer(url, message, opts) {
     if (lk !== "content-length" && lk !== "transfer-encoding" && lk !== "content-type") headers[k] = opts.headers[k];
   });
   headers["content-type"] = PKIXCMP;
-  var tls = _tlsForTransfer(opts);
   return guard.async.invoked(transport, [{ method: "POST", url: parsedUrl.href, headers: headers, body: der, tls: tls, proxy: proxy, timeout: timeout, maxResponseBytes: maxResponseBytes }], _err, "cmp/bad-input", "opts.transport").then(function (res) {
     res = res || intrinsic.create(null);
     var h = guard.header.lowerCased(res.headers);
@@ -1185,8 +1192,11 @@ function wellKnownUrl(base, opts) {
  * @opts
  *   - `transport` -- an injectable `transport(request) -> Promise<{status,headers,body}>` (default
  *     `pki.transport.https`, which fail-closes on a non-https URL and an unpinned server).
- *   - `tls` -- `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }` for the
+ *   - `tls` -- `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity, distrustedKeys }` for the
  *     default transport (mutual-TLS `cert`/`key` is common for CMP in addition to message protection).
+ *     `distrustedKeys` lists SHA-256 SubjectPublicKeyInfo digests (see pki.trust.spkiDigest); a server whose chain
+ *     carries a listed key is refused with `cmp/server-key-distrusted`, and a malformed list is `cmp/bad-input`. A
+ *     setting not named in that list is refused `cmp/bad-input`.
  *   - `headers` -- extra request headers. The `content-type: application/pkixcmp` is always set and not
  *     overridable (any casing), and the request-framing headers (`content-length`, `transfer-encoding`) are
  *     stripped -- the transport computes Content-Length from the exact body, so a caller cannot desync framing.

package/lib/cmp-session.js

@@ -70,7 +70,7 @@ var KNOWN_SESSION_OPTS = Object.assign(Object.create(null), {
   extraCerts: 1, implicitConfirm: 1, maxPolls: 1, maxTotalWait: 1, sleep: 1, time: 1,
   transport: 1, tls: 1, headers: 1, timeout: 1, maxResponseBytes: 1, proxy: 1, pss: 1, digestAlgorithm: 1,
   acceptCert: 1, senderKID: 1, recipKID: 1, expectedSender: 1, acceptCentralKeyGeneration: 1,
-  authorizedBySharedSecret: 1,
+  authorizedBySharedSecret: 1, distrustedKeys: 1,
 });
 
 var TRANSCRIPT_RETAIN_RESPONSES = 2;
@@ -407,6 +407,7 @@ function _certConfHash(certDer) {
  *   - `url` -- REQUIRED: the CMP endpoint URL.
  *   - `key` + `cert` -- signature protection (the enrolling key pair + its cert), XOR `mac: { secret, ... }` for PBMAC1 protection.
  *   - `trustAnchors` -- REQUIRED for the signature flavor (chains + authenticates the CA's response signer cert); OPTIONAL for a MAC session, where it validates the issued certificate's own signature + chain before confirmation (not the response protection). `intermediates` supplies an extra chain pool.
+ *   - `distrustedKeys`: SHA-256 digests of SubjectPublicKeyInfo values (64 hex characters or 32 bytes each), read once at construction. A listed key on the response signer's chain is `cmp/untrusted-signer`, on the issued certificate's chain `cmp/bad-cert-response`, and on the key generation authority's chain `cmp/unauthorized-kga`, which also refuses a listed authority key under `authorizedBySharedSecret`. A `rootCaKeyUpdate` answer whose new root key is listed is `cmp/bad-info-value`. A malformed list, or a list naming a key on a session without `trustAnchors`, is `cmp/bad-input`; an empty list refuses nothing and is accepted.
  *   - `sender` / `recipient` -- header GeneralNames; default the signer cert's subject DN (sender) and a NULL-DN (recipient). A signature-protection certificate with an empty subject (identified only by its subjectAltName) REQUIRES an explicit `sender`, because the empty subject cannot name the requester for a peer that binds the sender to the SAN.
  *   - `senderKID` / `recipKID` -- optional key identifiers emitted on every request header, so a CA selecting among several shared secrets (senderKID) or recipient keys resolves the right credential.
  *   - `expectedSender` -- optional CA signer certificate (DER Buffer / PEM string / already-parsed `pki.schema.x509.parse` object); when set, every signed response's authenticated header sender MUST bind to it under the RFC 5280 sec. 7 subject-or-subjectAltName rule cmp.verify uses, so a re-encoded-but-equivalent DN and an empty-subject CA named only by a directoryName SAN both match. Given as bytes/PEM it also resolves a first response that omits its own extraCerts (a CA that assumes the client already holds its certificate). Absent, the session pins the first signed response's signer certificate and requires every later leg's sender to bind to it, rejecting a switch to a different trusted signer while permitting same-identity certificate/key rotation.
@@ -454,6 +455,10 @@ function session(opts) {
     if (!hasAnchors) throw _err("cmp/bad-input", "signature protection requires opts.trustAnchors to authenticate the CA's response signer (RFC 9483 sec. 3.2)");
   }
   if (isMac && Array.isArray(opts.trustAnchors) && opts.trustAnchors.length === 0) opts.trustAnchors = null;
+  var _distrusted = guard.distrust.keys(opts.distrustedKeys, _err, "cmp/bad-input", "opts.distrustedKeys");
+  if (_distrusted !== null && _distrusted.length > 0 && opts.trustAnchors == null) {
+    throw _err("cmp/bad-input", "opts.distrustedKeys applies to the certificate paths this session validates against opts.trustAnchors, and this shared-secret session supplies none");
+  }
   if (opts.acceptCentralKeyGeneration != null && typeof opts.acceptCentralKeyGeneration !== "boolean") {
     throw _err("cmp/bad-input", "opts.acceptCentralKeyGeneration is a boolean stating that this caller accepts a key pair the authority generated (RFC 9483 sec. 4.1.6)");
   }
@@ -596,7 +601,10 @@ function session(opts) {
   function _verifyOpts(fresh, signerCertOverride, extraIntermediates, responseExtra) {
     var o = Object.assign(Object.create(null), { transactionID: transactionID, expectRecipNonce: fresh });
     if (isMac) o.sharedSecret = opts.mac.secret;
-    else if (opts.trustAnchors != null) o.trustAnchors = opts.trustAnchors;
+    else if (opts.trustAnchors != null) {
+      o.trustAnchors = opts.trustAnchors;
+      if (_distrusted !== null) o.distrustedKeys = _distrusted;
+    }
     var issuers = Array.isArray(responseExtra) ? responseExtra : [];
     var extra = [];
     if (Array.isArray(extraIntermediates)) {
@@ -982,7 +990,9 @@ function session(opts) {
     cachedChain.forEach(function (c) { if (Buffer.isBuffer(c)) _push(added,c); });
     var pool = _boundedPool(caPubsList, added);
     var res;
-    try { res = await _engine.build(leaf, { trustAnchors: _asCertList(opts.trustAnchors), intermediates: pool, validate: true, time: opts.time != null ? opts.time : new Date() }); }
+    var leafOpts = { trustAnchors: _asCertList(opts.trustAnchors), intermediates: pool, validate: true, time: opts.time != null ? opts.time : new Date() };
+    if (_distrusted !== null) leafOpts.distrustedKeys = _distrusted;
+    try { res = await _engine.build(leaf, leafOpts); }
     catch (e) {
       if (e.code === "path/bad-input") throw _err("cmp/bad-input", "invalid trust / validation options for issued-certificate validation: " + guard.text.describeThrown(e), e);
       throw _err("cmp/bad-cert-response", "the issued certificate could not be validated to a supplied trust anchor: " + guard.text.describeThrown(e), e);
@@ -1041,6 +1051,9 @@ function session(opts) {
       open.trustAnchors = _asOpenableCerts(opts.trustAnchors, "opts.trustAnchors", true);
       if (opts.intermediates != null) open.intermediates = _asOpenableCerts(opts.intermediates, "opts.intermediates", false);
     }
+    /** @internal The list goes with either rule: on the chain the verb validates, or, under the
+     *  exemption, on the authority's own key. */
+    if (_distrusted !== null) open.distrustedKeys = _distrusted;
     /** @internal The instant the session validates every other certificate at governs the authority's
      * chain too, so a historical enrollment does not judge one certificate at a stated time and
      * another at the current one. */
@@ -1689,6 +1702,9 @@ function session(opts) {
     var newWithOld = _asCertificate(value.newWithOld, "the rootCaKeyUpdate newWithOld");
     var oldWithNew = value.oldWithNew == null ? null : _asCertificate(value.oldWithNew, "the rootCaKeyUpdate oldWithNew");
     var pNewNew = x509.parse(newWithNew), pNewOld = x509.parse(newWithOld), pOldRoot = x509.parse(oldRootDer);
+    if (guard.distrust.has(_distrusted, pNewNew.subjectPublicKeyInfo.bytes)) {
+      throw _err("cmp/bad-info-value", "the rootCaKeyUpdate new root key is listed in opts.distrustedKeys");
+    }
     _assertCaCapable(pNewNew, "rootCaKeyUpdate newWithNew");
     _assertCaCapable(pNewOld, "rootCaKeyUpdate newWithOld");
     if (!cmpBuild.samePublicKey(pNewOld.subjectPublicKeyInfo.bytes, pNewNew.subjectPublicKeyInfo.bytes)) {

package/lib/cmp-verify.js

@@ -57,7 +57,7 @@ var _certExtDecoders = pkix.certExtensionDecoders(NS).byOid;
 var KNOWN_VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), {
   sharedSecret: 1, signerCert: 1, trustAnchors: 1, intermediates: 1, time: 1,
   transactionID: 1, expectRecipNonce: 1, revocationChecker: 1, maxIterations: 1, kem: 1,
-  messageTimeTolerance: 1,
+  messageTimeTolerance: 1, distrustedKeys: 1,
 });
 var KNOWN_KEM_VERIFY_KEYS = intrinsic.assign(intrinsic.create(null),
   { sharedSecret: 1, transactionID: 1 });
@@ -651,6 +651,7 @@ async function _chainSigner(signer, m, opts, extra) {
   }
   var buildOpts = { trustAnchors: anchors, intermediates: pool, validate: true, time: time };
   if (opts.revocationChecker != null) buildOpts.revocationChecker = opts.revocationChecker;
+  if (opts.distrustedKeys !== null) buildOpts.distrustedKeys = opts.distrustedKeys;
   try {
     var res = await _engine.build(signer.der, buildOpts);
     if (!res || res.valid !== true) return guard.verdict.of({ trusted: false, reason: "the signer certificate did not chain to a supplied trust anchor" });
@@ -826,10 +827,16 @@ function _fixVerifyOptions(opts, made) {
     maxIterations: opts.maxIterations,
     kem: _fixKem(opts.kem, made),
     messageTimeTolerance: _fixTolerance(opts.messageTimeTolerance),
+    distrustedKeys: guard.distrust.keys(opts.distrustedKeys, _err, "cmp/bad-input", "opts.distrustedKeys"),
   };
 
   _assertEchoBytes(f.transactionID, "transactionID");
   _assertEchoBytes(f.expectRecipNonce, "expectRecipNonce");
+  /** @internal Only a list that names a key is refused here: an empty one refuses nothing, so it
+   *  asks for no check that the missing path would leave undone. */
+  if (f.distrustedKeys !== null && f.distrustedKeys.length > 0 && f.trustAnchors == null) {
+    throw _err("cmp/bad-input", "opts.distrustedKeys applies to the signer certificate's path, which is validated only against opts.trustAnchors; MAC and KEM protection validate no path");
+  }
   return f;
 }
 
@@ -874,7 +881,7 @@ async function _verify(message, opts) {
 
 var KNOWN_OPEN_KEY_PACKAGE_OPTS = intrinsic.assign(intrinsic.create(null), {
   key: 1, cert: 1, password: 1, trustAnchors: 1, intermediates: 1, time: 1,
-  authorizedBySharedSecret: 1, allowUnauthenticatedRsa15: 1,
+  authorizedBySharedSecret: 1, allowUnauthenticatedRsa15: 1, distrustedKeys: 1,
 });
 var OID_A_KEY_PACKAGE = oid.byName("aKeyPackage");
 var OID_SIGNED_DATA = oid.byName("signedData");
@@ -950,6 +957,7 @@ function _fixOpenKeyPackageOptions(opts, made) {
     time: _fixTime(opts.time),
     exempt: opts.authorizedBySharedSecret === true,
     allowRsa15: opts.allowUnauthenticatedRsa15 === true,
+    distrustedKeys: guard.distrust.keys(opts.distrustedKeys, _err, "cmp/bad-input", "opts.distrustedKeys"),
   };
   if (opts.authorizedBySharedSecret != null && typeof opts.authorizedBySharedSecret !== "boolean") {
     throw _err("cmp/bad-input", "opts.authorizedBySharedSecret is a boolean stating that this entity protected its request with the shared secret");
@@ -1020,6 +1028,11 @@ async function _openKeyPackage(container, opts) {
   var signerCert = verdict.signers[0] && verdict.signers[0].cert;
   if (!signerCert) throw _keyPackageErr("the SignedData names no signer certificate to authorize as the key generation authority");
   _authorizeKga(verdict, signerCert, opts);
+  /** @internal The shared-secret exemption replaces the authority's chain check, which is where the
+   *  list is otherwise applied, so the authority's own key is checked here. */
+  if (opts.exempt && guard.distrust.has(opts.distrustedKeys, x509.parse(signerCert).subjectPublicKeyInfo.bytes)) {
+    throw _err("cmp/unauthorized-kga", "the key generation authority's key is listed in opts.distrustedKeys");
+  }
   if (verdict.eContent == null) throw _keyPackageErr("the SignedData carries no encapsulated content, so no key package was delivered");
   return guard.verdict.of({ keys: _readKeyPackage(verdict.eContent), kga: _bufferFrom(signerCert), trusted: opts.exempt ? false : true });
 }
@@ -1047,6 +1060,7 @@ function _signedDataVerifyOpts(opts) {
   var v = { trustAnchors: opts.trustAnchors, requiredEku: [OID_CM_KGA] };
   if (opts.intermediates != null) v.certs = opts.intermediates;
   if (opts.time != null) v.time = opts.time;
+  if (opts.distrustedKeys !== null) v.distrustedKeys = opts.distrustedKeys;
   return v;
 }
 
@@ -1152,6 +1166,10 @@ function _coerceKeyPackageBytes(container) {
  *     authority. REQUIRED unless `authorizedBySharedSecret` is set.
  *   - `intermediates` (Buffer|Buffer[]|PEM) -- extra untrusted pool certificates for path building.
  *   - `time` (Date) -- the validity instant for path validation. Defaults to the current time.
+ *   - `distrustedKeys` (Array): SHA-256 digests of SubjectPublicKeyInfo values (64 hex characters
+ *     or 32 bytes each). A listed key on the authority, an intermediate or the anchor is
+ *     `cmp/unauthorized-kga`. Under `authorizedBySharedSecret`, which validates no chain, the list
+ *     is applied to the authority's own key.
  *   - `authorizedBySharedSecret` (boolean) -- authorize the authority by the secret that protected
  *     the request rather than by a chain, which sec. 4.1.6 permits a MAC-protected exchange. Requires
  *     `opts.password` and refuses `opts.trustAnchors`.
@@ -1264,6 +1282,11 @@ function openKeyPackage(container, opts) {
  *   - `transactionID` (Buffer) -- opt-in: require `header.transactionID` to equal it (response-echo defense).
  *   - `expectRecipNonce` (Buffer) -- opt-in: require `header.recipNonce` to echo the sent sender nonce.
  *   - `revocationChecker` -- forwarded to `pki.path.validate` when chaining the signer certificate.
+ *   - `distrustedKeys` (Array): SHA-256 digests of SubjectPublicKeyInfo values (64 hex characters or
+ *     32 bytes each). A listed key on the signer, an intermediate or the anchor makes the verdict
+ *     `trusted: false` with `cmp/untrusted-signer`. A list that names a key requires `trustAnchors`, so
+ *     a MAC- or KEM-protected message refuses one as `cmp/bad-input`, as it does a malformed list; an
+ *     empty list refuses nothing and is accepted.
  *   - `maxIterations` (number) -- downward-only override of the PBKDF2 iteration cap.
  *
  * @example

package/lib/cms-compress.js

@@ -27,12 +27,12 @@ async function compress(content, opts) {
   opts = opts || _create(null);
   var raw = guard.bytes.source(content, CmsError, "cms/bad-input", "content");
   var level = opts.level;
-  if (level !== undefined && (typeof level !== "number" || !isFinite(level) || Math.floor(level) !== level)) throw _err("cms/bad-input", "opts.level must be an integer");
+  if (level != null && (typeof level !== "number" || !isFinite(level) || Math.floor(level) !== level)) throw _err("cms/bad-input", "opts.level must be an integer");
   var ctName = opts.contentType || "data";
   var ctOid = O(ctName);
   if (!ctOid) throw _err("cms/bad-input", "opts.contentType is not a known OID name: " + ctName);
   var stream;
-  try { stream = zlib.deflateSync(raw, level !== undefined ? { level: level } : undefined); }
+  try { stream = zlib.deflateSync(raw, level != null ? { level: level } : undefined); }
   catch (e) { throw _err("cms/bad-input", "the content could not be compressed (check opts.level)", e); }
   var cd = b.sequence([
     b.integer(0),
@@ -46,7 +46,7 @@ async function compress(content, opts) {
 async function decompress(input, opts) {
   opts = opts || _create(null);
   var cap = C.LIMITS.COMPRESS_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("cms/bad-input", "opts.maxOutputBytes must be a positive integer");
     if (mo < cap) cap = mo;