@blamejs/pki 0.9.4 → 0.9.6

package/lib/est.js

@@ -173,6 +173,17 @@ function _knownOpts(opts, known, verb) {
       Object.keys(known).sort().join(", ");
   });
   _assertTransport(settled);
+  /** @internal The two switches these verbs document, typed here because this is the one door every
+   * one of them passes through and it runs before any request goes out. Both are read further down
+   * by truthiness: `allowCrossOriginRedirect: "false"` is truthy, so it ALLOWED the cross-origin
+   * redirect on an unsafe method that the check exists to refuse (sec. 3.2.1), and
+   * `requestedEncryption: "false"` is read as "encryption was requested", which skips the
+   * sec. 4.4.2 check that an encrypted key part was advertised. A verb that does not accept one of
+   * them never sees a value for it. */
+  guard.identifier.booleanOption(settled.allowCrossOriginRedirect, E, "est/bad-input",
+    "pki.est." + verb + " opts.allowCrossOriginRedirect");
+  guard.identifier.booleanOption(settled.requestedEncryption, E, "est/bad-input",
+    "pki.est." + verb + " opts.requestedEncryption");
   return settled;
 }
 
@@ -907,10 +918,23 @@ function _parseUrl(urlStr) {
   return url;
 }
 
-/** @internal The settings this client forwards to its transport. */
-var TLS_SETTINGS = ["anchors", "useSystemStore", "cert", "key", "minVersion", "servername", "checkServerIdentity"];
-function _tlsForRequest(opts) {
-  return guard.identifier.pickSettings(opts.tls, TLS_SETTINGS);
+/** @internal The settings this client forwards to its transport. The distrust list is typed here, once
+ *  per verb, and the frozen copy is the one every hop 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 _tlsForRequest(tls) {
+  guard.identifier.assertKnownKeys(tls, TLS_KNOWN, E, "est/bad-input", "unknown opts.tls setting ");
+  var t = guard.identifier.pickSettings(tls, TLS_SETTINGS);
+  t.distrustedKeys = guard.distrust.keys(t.distrustedKeys, E, "est/bad-input", "opts.tls.distrustedKeys");
+  return t;
+}
+/** @internal The proxy and the tls settings, taken at the synchronous verb door. Every request and
+ *  redirect hop of the verb uses this record. */
+function _doorSnapshot(opts) {
+  var proxy, tls;
+  try { proxy = _snapProxy(opts); tls = opts.tls; }
+  catch (_pe) { throw E("est/bad-input", "the options object could not be read", _pe); }
+  return { proxy: proxy, tls: _tlsForRequest(tls) };
 }
 
 function _redirectTarget(current, location, method, opts) {
@@ -969,7 +993,7 @@ function _authScheme(opts) {
     if (sc !== "basic" && sc !== "digest") throw E("est/bad-input", "opts.auth.scheme must be \"basic\" or \"digest\"");
     return sc;
   }
-  if (opts.username !== undefined || opts.password !== undefined) return "basic";
+  if (opts.username != null || opts.password != null) return "basic";
   return null;
 }
 function _authUser(opts) { return opts.auth && opts.auth.username !== undefined ? opts.auth.username : opts.username; }
@@ -1084,7 +1108,7 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
 /** @internal `checked` is the transport the verb already took at its door. Taking it again here
  * would ask the caller's options a second time, and anything read in between could change the
  * answer, so a verb that holds one passes it and this reads the option only when none was held. */
-function _client(op, method, baseUrl, body, headers, opts, proxySnap, onAttempt, checked) {
+function _client(op, method, baseUrl, body, headers, opts, snap, onAttempt, checked) {
   var base;
   try { base = new _URL(_stringOf(baseUrl)); }
   catch (e) { throw E("est/bad-url", "the EST base URL did not parse: " + guard.text.showValue(baseUrl), e); }
@@ -1092,14 +1116,14 @@ function _client(op, method, baseUrl, body, headers, opts, proxySnap, onAttempt,
   var url = _parseUrl(paths(baseUrl, { label: opts.label })[op]);
   var transport = checked !== undefined ? checked : _assertTransport(opts);
   if (!transport) {
-    var t = opts.tls != null ? opts.tls : intrinsic.create(null);
+    var t = snap.tls;
     var hasAnchors = t.anchors !== undefined && t.anchors !== null && !(Array.isArray(t.anchors) && t.anchors.length === 0);
     if (!hasAnchors && t.useSystemStore !== true) throw E("est/no-trust-anchors", "no explicit trust anchor and tls.useSystemStore not set to true -- refusing an unpinned server (RFC 7030 sec. 3.6)");
     transport = httpTransport.https({ E: E, errPrefix: "est" });
   }
   var budgets = {
-    tls: _tlsForRequest(opts),
-    proxy: proxySnap,
+    tls: snap.tls,
+    proxy: snap.proxy,
     timeout: guard.limits.cap(opts.timeout, "timeout", DEFAULT_TIMEOUT, { E: E, code: "est/bad-input", min: 1, max: MAX_TIMEOUT }),
     maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "est/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
     maxRedirects: guard.limits.cap(opts.maxRedirects, "maxRedirects", 5, { E: E, code: "est/bad-input", min: 0, max: 32 }),
@@ -1230,18 +1254,19 @@ function fullcmc(baseUrl, request, opts) {
      * caller's nested objects, and one of those reads must not be able to change which transport
      * the request goes out on, so the value that was checked is the value carried below. */
     var carriedTransport = opts.transport;
-    var proxySnap;
-    try { proxySnap = _snapProxy(opts); } catch (_pe) { throw E("est/bad-input", "the options object could not be read", _pe); }
+    /** @internal Taken before the own-property copy below, so a tls a defaults bag carries on its
+     *  prototype is the one the request uses. */
+    var snap = _doorSnapshot(opts);
     der = _cmcRequestDer(request);
     wanted = _requestedPublicKeys(der);
     sent = _cmcSent(opts, der);
     /** @internal The copy below keeps own properties only, and a defaults bag holds its options on
      * a prototype, so the transport is put back from the value held at the door. */
     opts = _shallowCopy(opts);
-    if (carriedTransport !== undefined) opts.transport = carriedTransport;
+    if (carriedTransport != null) opts.transport = carriedTransport;
     var body = transferEncode(der);
     return _client("fullcmc", "POST", baseUrl, body,
-      { accept: "application/pkcs7-mime", "content-type": "application/pkcs7-mime; smime-type=CMC-request" }, opts, proxySnap, undefined, carriedTransport)
+      { accept: "application/pkcs7-mime", "content-type": "application/pkcs7-mime; smime-type=CMC-request" }, opts, snap, undefined, carriedTransport)
       .then(function (res) { return _fullcmcResult(res, opts, wanted, sent); });
   } catch (e) {
     return _rej(e);
@@ -1560,7 +1585,7 @@ function _causedBy(e, target) {
 
 var ENROLL_HEADERS = intrinsic.assign(intrinsic.create(null), { accept: "application/pkcs7-mime", "content-type": "application/pkcs10" });
 
-function _enrollBound(op, baseUrl, builder, opts, proxySnap) {
+function _enrollBound(op, baseUrl, builder, opts, snap) {
   /** @internal Held before anything else the caller supplied is read, and carried to the client:
    * the builder runs during the handshake, so a later read could answer with a different value. */
   var checkedTransport = opts.transport;
@@ -1590,7 +1615,7 @@ function _enrollBound(op, baseUrl, builder, opts, proxySnap) {
         .then(null, function (e) { attempt.error = e; attempt.done = true; throw e; });
     };
   }
-  return _client(op, "POST", baseUrl, hopBody, ENROLL_HEADERS, opts, proxySnap, hopBody, checkedTransport)
+  return _client(op, "POST", baseUrl, hopBody, ENROLL_HEADERS, opts, snap, hopBody, checkedTransport)
     .then(function (res) {
       if (current && current.error) throw current.error;
       if (!current || !current.done) {
@@ -1606,13 +1631,13 @@ function _enrollBound(op, baseUrl, builder, opts, proxySnap) {
     });
 }
 
-function _enroll(op, baseUrl, csrInput, opts, proxySnap) {
-  if (typeof csrInput === "function") return _enrollBound(op, baseUrl, csrInput, opts, proxySnap);
+function _enroll(op, baseUrl, csrInput, opts, snap) {
+  if (typeof csrInput === "function") return _enrollBound(op, baseUrl, csrInput, opts, snap);
   var checkedTransport = opts.transport;
   var csrDer = _csrDer(csrInput);
   var spki = csr.parse(csrDer).subjectPublicKeyInfo;
   var body = transferEncode(csrDer);
-  return _client(op, "POST", baseUrl, body, ENROLL_HEADERS, opts, proxySnap, undefined, checkedTransport)
+  return _client(op, "POST", baseUrl, body, ENROLL_HEADERS, opts, snap, undefined, checkedTransport)
     .then(function (res) { return _certsResult(op, res, opts, spki); });
 }
 
@@ -1635,7 +1660,7 @@ function _enroll(op, baseUrl, csrInput, opts, proxySnap) {
  *
  * @opts
  *   - `transport`: an injected `transport(request) -> Promise<{status, headers, body, tls}>`; default pki.transport.https. It must return a promise of the response; anything else is `est/bad-input`.
- *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }.
+ *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity, distrustedKeys }. `distrustedKeys` lists SHA-256 SubjectPublicKeyInfo digests (see pki.trust.spkiDigest); a server whose chain carries a listed key is refused with `est/server-key-distrusted`, on every hop including a cross-origin redirect, and a malformed list is `est/bad-input`. A setting not named in that list is refused `est/bad-input`. The verb reads `tls` when it is called, so a change the caller makes to it afterward does not reach the request.
  *   - `label` -- an OPTIONAL CA label path segment; `timeout` / `maxResponseBytes` / `maxRedirects` -- budgets.
  *   - `proxy` -- reach the CA through a forward HTTP proxy (`{ url, auth?, tls? }`; see pki.transport).
  *   - `now` -- receipt time (epoch ms) to render a 202 Retry-After HTTP-date as seconds.
@@ -1643,6 +1668,8 @@ function _enroll(op, baseUrl, csrInput, opts, proxySnap) {
  *     There is no `"auto"`: the scheme is chosen here, not by whatever a server offers. `username` / `password`
  *     at the top level are the older form and mean Basic. Answered only after the transport authenticated the server.
  *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on an unsafe method.
+ *     A value other than `true`, `false`, `null` or an absent option is refused `est/bad-input`
+ *     before the request goes out.
  * @example
  *   // a live CA uses the default pki.transport.https; here an injected transport returns a canned bag
  *   var r = await pki.est.cacerts("https://ca.example",
@@ -1651,10 +1678,10 @@ function _enroll(op, baseUrl, csrInput, opts, proxySnap) {
  */
 function cacerts(baseUrl, opts) {
   opts = opts || intrinsic.create(null);
-  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
+  var snap; try { snap = _doorSnapshot(opts); } catch (e) { return _rej(e); }
   return _promiseResolve(_Promise, undefined).then(function () {
     opts = _knownOpts(opts, CACERTS_OPTS, "cacerts");
-    return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts, proxySnap, undefined, opts.transport);
+    return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts, snap, undefined, opts.transport);
   }).then(function (res) { return _certsResult("cacerts", res, opts, null); });
 }
 
@@ -1695,7 +1722,9 @@ function cacerts(baseUrl, opts) {
  *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `proxy` / `now`, as in pki.est.cacerts.
  *   - `strict`: reject an enroll response that carries more than the single issued certificate.
  *   - `username` / `password` / `auth` -- HTTP credentials: top-level `username` / `password` mean Basic; `auth` (`{ scheme: "basic" | "digest", username, password, ... }`, as in pki.est.cacerts) selects Basic or Digest. Answered only after server authorization (empty username allowed).
- *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on this POST.
+ *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on this POST. A
+ *     value other than `true`, `false`, `null` or an absent option is refused `est/bad-input`
+ *     before the request goes out.
  * @example
  *   var req = await pki.csr.sign({ subject: "device.example", subjectPublicKey: signerSpki }, { key: signerKeyPkcs8 });
  *   // a 202 means the CA queued the request -- the verb surfaces the delay, never sleeps
@@ -1717,10 +1746,10 @@ function cacerts(baseUrl, opts) {
  */
 function simpleenroll(baseUrl, csrInput, opts) {
   opts = opts || intrinsic.create(null);
-  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
+  var snap; try { snap = _doorSnapshot(opts); } catch (e) { return _rej(e); }
   return _promiseResolve(_Promise, undefined).then(function () {
     opts = _knownOpts(opts, SIMPLEENROLL_OPTS, "simpleenroll");
-    return _enroll("simpleenroll", baseUrl, csrInput, opts, proxySnap);
+    return _enroll("simpleenroll", baseUrl, csrInput, opts, snap);
   });
 }
 
@@ -1757,12 +1786,12 @@ function simpleenroll(baseUrl, csrInput, opts) {
  */
 function simplereenroll(baseUrl, csrInput, opts) {
   opts = opts || intrinsic.create(null);
-  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
+  var snap; try { snap = _doorSnapshot(opts); } catch (e) { return _rej(e); }
   return _promiseResolve(_Promise, undefined).then(function () {
     opts = _knownOpts(opts, SIMPLEREENROLL_OPTS, "simplereenroll");
     if (!opts.oldCert) throw E("est/bad-input", "simplereenroll requires opts.oldCert (the certificate being renewed, RFC 7030 sec. 4.2.2)");
     if (typeof csrInput !== "function") reenrollGuard(opts.oldCert, _csrDer(csrInput));
-    return _enroll("simplereenroll", baseUrl, csrInput, opts, proxySnap);
+    return _enroll("simplereenroll", baseUrl, csrInput, opts, snap);
   });
 }
 
@@ -1919,6 +1948,8 @@ async function _serverkeygenResult(res, opts, derived) {
  * @opts
  *   - `requestedEncryption` / `expectedRecipientKeyId` / `expectedRecipientIssuerSerial` -- OPTIONAL
  *     overrides of the CSR-derived recipient coherence; a value that contradicts the CSR is `est/bad-input`.
+ *     `requestedEncryption` is a boolean: a value other than `true`, `false`, `null` or an absent
+ *     option is refused `est/bad-input`.
  *   - every option of pki.est.simpleenroll (transport, tls, label, budgets, credentials incl. `auth`).
  * @example
  *   var r = await pki.est.serverkeygen("https://ca.example", csrDer,
@@ -1927,13 +1958,18 @@ async function _serverkeygenResult(res, opts, derived) {
  */
 function serverkeygen(baseUrl, csrInput, opts) {
   opts = opts || intrinsic.create(null);
-  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
+  var snap; try { snap = _doorSnapshot(opts); } catch (e) { return _rej(e); }
   return _promiseResolve(_Promise, undefined).then(function () {
     opts = _knownOpts(opts, SERVERKEYGEN_OPTS, "serverkeygen");
     var checkedTransport = opts.transport;
     var csrDer = _csrDer(csrInput);
     var derived = _serverkeygenEncryptionFromCsr(csrDer);
-    if (opts.requestedEncryption !== undefined && !!opts.requestedEncryption !== derived.requestedEncryption) throw E("est/bad-input", "opts.requestedEncryption (" + !!opts.requestedEncryption + ") contradicts the CSR's advertised key-encryption attribute (" + derived.requestedEncryption + ") (RFC 7030 sec. 4.4.1)");
+    /** @internal An override is a value the caller stated, and `null` states nothing: it is the
+     * absent form the switch door accepts, so the CSR's own answer stands. Read as present it
+     * coerced to `false` and contradicted a CSR the caller never disagreed with. The value is a
+     * boolean by the time it reaches here, so it is compared rather than coerced. */
+    if (opts.requestedEncryption != null && opts.requestedEncryption !== derived.requestedEncryption) throw E("est/bad-input", "opts.requestedEncryption (" + opts.requestedEncryption + ") contradicts the CSR's advertised key-encryption attribute (" + derived.requestedEncryption + ") (RFC 7030 sec. 4.4.1)");
+    // allow:caller-option-presence-tested-against-undefined -- absence means the recipient is not checked against the CSR, so a null must be refused
     if (opts.expectedRecipientKeyId !== undefined) {
       if (!Buffer.isBuffer(opts.expectedRecipientKeyId)) throw E("est/bad-input", "opts.expectedRecipientKeyId must be a Buffer");
       if (derived.expectedRecipientKeyId && !opts.expectedRecipientKeyId.equals(derived.expectedRecipientKeyId)) throw E("est/bad-input", "opts.expectedRecipientKeyId contradicts the key identifier the CSR advertised (RFC 7030 sec. 4.4.1)");
@@ -1947,7 +1983,7 @@ function serverkeygen(baseUrl, csrInput, opts) {
     if ((opts.expectedRecipientKeyId !== undefined || opts.expectedRecipientIssuerSerial != null) && !derived.requestedEncryption) {
       throw E("est/bad-input", "a recipient expectation (expectedRecipientKeyId / expectedRecipientIssuerSerial) implies an encrypted key, but the CSR advertised no DecryptKeyIdentifier / AsymmetricDecryptKeyIdentifier attribute (RFC 7030 sec. 4.4.1)");
     }
-    return _client("serverkeygen", "POST", baseUrl, transferEncode(csrDer), { accept: "multipart/mixed", "content-type": "application/pkcs10" }, opts, proxySnap, undefined, checkedTransport)
+    return _client("serverkeygen", "POST", baseUrl, transferEncode(csrDer), { accept: "multipart/mixed", "content-type": "application/pkcs10" }, opts, snap, undefined, checkedTransport)
       .then(function (res) { return _serverkeygenResult(res, opts, derived); });
   });
 }
@@ -1989,10 +2025,10 @@ function _csrattrsResult(res, opts) {
  */
 function csrattrs(baseUrl, opts) {
   opts = opts || intrinsic.create(null);
-  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
+  var snap; try { snap = _doorSnapshot(opts); } catch (e) { return _rej(e); }
   return _promiseResolve(_Promise, undefined).then(function () {
     opts = _knownOpts(opts, CSRATTRS_OPTS, "csrattrs");
-    return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts, proxySnap, undefined, opts.transport);
+    return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts, snap, undefined, opts.transport);
   }).then(function (res) { return _csrattrsResult(res, opts); });
 }
 

package/lib/guard-all.js

@@ -22,6 +22,7 @@ var secret = require("./guard-secret");
 var parsed = require("./guard-parsed");
 var verdict = require("./guard-verdict");
 var async_ = require("./guard-async");
+var distrust = require("./guard-distrust");
 
 module.exports = _freeze({
   bytes:  bytes,
@@ -42,4 +43,5 @@ module.exports = _freeze({
   parsed: parsed,
   verdict: verdict,
   async:  async_,
+  distrust: distrust,
 });

package/lib/guard-distrust.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+// @internal
+
+var util = require("util");
+var intrinsic = require("./guard-intrinsic");
+var constants = require("./constants");
+var gBytes = require("./guard-bytes");
+var gList = require("./guard-list");
+var gCrypto = require("./guard-crypto");
+
+var _freeze = intrinsic.freeze;
+var _isArray = intrinsic.isArray;
+var _create = intrinsic.create;
+var _hasOwn = intrinsic.hasOwn;
+var _getOwnPropertyDescriptor = intrinsic.getOwnPropertyDescriptor;
+var _bufToString = intrinsic.bufToString;
+var _charCodeAt = intrinsic.uncurry(String.prototype.charCodeAt);
+var _fromCharCode = intrinsic.fromCharCode;
+var _isProxy = util.types.isProxy;
+
+var DIGEST_BYTES = 32;
+var DIGEST_HEX = 64;
+
+/** @internal One hexadecimal character, folded to lower case, or -1. The fold is arithmetic on the
+ *  character code, so the normalized digest is not the answer of a `toLowerCase` read off the live
+ *  prototype. */
+function _lowerHexCode(c) {
+  if (c >= 48 && c <= 57) return c;
+  if (c >= 97 && c <= 102) return c;
+  if (c >= 65 && c <= 70) return c + 32;
+  return -1;
+}
+
+function _hexEntry(s, E, code, where) {
+  if (s.length !== DIGEST_HEX) {
+    throw E(code, where + " must be a SHA-256 digest of a SubjectPublicKeyInfo: 64 hexadecimal characters or 32 bytes, got " + s.length + " characters");
+  }
+  var out = "";
+  for (var i = 0; i < DIGEST_HEX; i++) {
+    var c = _lowerHexCode(_charCodeAt(s, i));
+    if (c === -1) throw E(code, where + " must be 64 hexadecimal characters with no separators; character " + i + " is not a hexadecimal digit");
+    out += _fromCharCode(c);
+  }
+  return out;
+}
+
+function _bytesEntry(v, E, code, where) {
+  var copy = gBytes.snapshotSource(v, E, code, where);
+  if (copy.length !== DIGEST_BYTES) {
+    throw E(code, where + " must be a SHA-256 digest of a SubjectPublicKeyInfo: 32 bytes or 64 hexadecimal characters, got " + copy.length + " bytes");
+  }
+  return _bufToString(copy, "hex");
+}
+
+/** The caller's list of distrusted keys, read once and returned as a frozen list of lower-case hex
+ * digests with duplicates removed, or `null` when the option is absent or `null`. Each entry is the
+ * SHA-256 digest of a certificate's DER SubjectPublicKeyInfo, given as 64 hexadecimal characters or
+ * as 32 bytes.
+ *
+ * Every slot is read through its descriptor, so a hole, an accessor and a Proxy are refused rather
+ * than read: a hole is answered by the array prototype and an accessor answers each read separately,
+ * and either one makes the list the check uses differ from the list the caller wrote. The list is a
+ * refusal list, so reading it as shorter than it is lets through a key the caller distrusted.
+ *
+ * @enforced-by behavioral -- the defect is a door that does not call this, which has no rename-proof
+ * code shape; the guard is the RED vector each verb carries, driving a listed key through the
+ * shipped verb and asserting the refusal.
+ */
+function keys(value, E, code, label) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "object" || _isProxy(value) || !_isArray(value)) {
+    throw E(code, label + " must be an array of SHA-256 SubjectPublicKeyInfo digests");
+  }
+  var n = gList.count(value, "keys");
+  if (n > constants.LIMITS.DISTRUSTED_KEYS_MAX) {
+    throw E(code, label + " has " + n + " entries, more than the " + constants.LIMITS.DISTRUSTED_KEYS_MAX + " this toolkit reads");
+  }
+  var seen = _create(null);
+  var out = [];
+  for (var i = 0; i < n; i++) {
+    var where = label + "[" + i + "]";
+    var d = _getOwnPropertyDescriptor(value, i);
+    if (!d) throw E(code, where + " is a hole; every entry must be present");
+    if (d.get || d.set) throw E(code, where + " is an accessor; every entry must be a data property");
+    var v = d.value;
+    var hex;
+    if (typeof v === "string") hex = _hexEntry(v, E, code, where);
+    else if (gBytes.isByteSource(v)) hex = _bytesEntry(v, E, code, where);
+    else throw E(code, where + " must be 64 hexadecimal characters or 32 bytes");
+    if (_hasOwn(seen, hex)) continue;
+    seen[hex] = true;
+    gList.append(out, hex);
+  }
+  return _freeze(out);
+}
+
+/** The lower-case hex SHA-256 of `spkiBytes`, the DER SubjectPublicKeyInfo exactly as a certificate
+ * or an anchor carries it.
+ *
+ * @enforced-by behavioral -- a digest has no rename-proof shape that separates this use from the
+ * others `guard-crypto` serves; the guard is the membership vector, which fails if the bytes hashed
+ * are not the ones listed.
+ */
+function digest(spkiBytes) {
+  return gCrypto.digest("sha256", spkiBytes, { output: "hex" });
+}
+
+/** @internal The codec and the registry, reached through inline requires: both load this module
+ *  through guard-all, so both are loaded by the time a digest is asked for. */
+function _codec() {
+  return {
+    asn1: require("./asn1-der"),   // allow:inline-require -- circular load: asn1-der -> guard-all -> this module
+    oid: require("./oid"),         // allow:inline-require -- circular load: oid -> guard-all -> this module
+  };
+}
+
+/** @internal The SubjectPublicKeyInfo with an identifier that restricts the key's use replaced by the
+ *  key's own: id-ecDH and id-ecMQV (RFC 5480 sec. 2.1.2) become ecPublicKey with the curve kept, and
+ *  RSASSA-PSS and RSAES-OAEP (RFC 4055) become rsaEncryption with NULL. The subjectPublicKey bits are
+ *  the same key in each pair. Any other identifier is returned unchanged. */
+function _unrestricted(spkiBytes, c) {
+  var b = c.asn1.build;
+  var root = c.asn1.decode(spkiBytes);
+  var alg = root.children[0];
+  var name = c.oid.name(c.asn1.read.oid(alg.children[0]));
+  if (name === "ecDH" || name === "ecMQV") {
+    var params = alg.children.length > 1 ? [b.raw(alg.children[1].bytes)] : [];
+    return b.sequence([b.sequence(intrinsic.concatList([b.oid(c.oid.byName("ecPublicKey"))], params)), b.raw(root.children[1].bytes)]);
+  }
+  if (name === "rsassaPss" || name === "rsaesOaep") {
+    return b.sequence([b.sequence([b.oid(c.oid.byName("rsaEncryption")), b.nullValue()]), b.raw(root.children[1].bytes)]);
+  }
+  return spkiBytes;
+}
+
+/** @internal The key in canonical form, or null when node does not read the bytes as a public key.
+ *  An elliptic curve key is written with ecPublicKey, its named curve and an uncompressed point,
+ *  whatever point form or parameter form it was read in. Any other key node writes as a JWK is
+ *  written the way node writes a key it builds from one, which puts an RSA key under rsaEncryption
+ *  with NULL. A key with neither form is re-exported as node read it. */
+function _canonicalSpki(spkiBytes) {
+  try {
+    var c = _codec();
+    var spki = _unrestricted(spkiBytes, c);
+    var key = gCrypto.publicKey({ key: spki, format: "der", type: "spki" });
+    if (gCrypto.keyTypeOf(key) === "ec") {
+      var details = gCrypto.keyDetailsOf(key);
+      var curveOid = details && typeof details.namedCurve === "string" ? c.oid.byName(details.namedCurve) : undefined;
+      if (curveOid !== undefined) {
+        var b = c.asn1.build;
+        var point = c.asn1.read.bitString(c.asn1.decode(spki).children[1]).bytes;
+        var uncompressed = gCrypto.ecConvertPoint(point, details.namedCurve, "uncompressed");
+        return b.sequence([b.sequence([b.oid(c.oid.byName("ecPublicKey")), b.oid(curveOid)]), b.bitString(uncompressed, 0)]);
+      }
+    }
+    var jwk = null;
+    try { jwk = gCrypto.exportKey(key, { format: "jwk" }); }
+    catch (_je) {
+      // allow:swallow-unverified a key type with no JWK form is re-exported as node read it
+      jwk = null;
+    }
+    if (jwk !== null) key = gCrypto.publicKey({ key: jwk, format: "jwk" });
+    return gCrypto.exportKey(key, { type: "spki", format: "der" });
+  } catch (_e) {
+    // allow:swallow-unverified a key node does not read has no second encoding, and the raw digest still decides
+    return null;
+  }
+}
+
+/** The digest a distrust entry names a key by: the lower-case hex SHA-256 of the key's
+ * SubjectPublicKeyInfo in canonical form, an uncompressed EC point with its named curve and an RSA
+ * key with NULL parameters. That is how nearly every certificate encodes a key, so for those it is
+ * the digest of the bytes the certificate carries. A key node does not read is digested as given.
+ *
+ * @enforced-by behavioral -- a digest has no rename-proof shape; the guard is the two-direction
+ * re-encoding vectors in guard-distrust.test.js.
+ */
+function keyDigest(spkiBytes) {
+  var canonical = _canonicalSpki(spkiBytes);
+  return digest(canonical !== null ? canonical : spkiBytes);
+}
+
+/** Whether the key `spkiBytes` names is on `list`, a value `keys` returned. A `null` or empty list
+ * answers `false`. The digest of the bytes as given is compared, and so is `keyDigest`, so an entry
+ * `keyDigest` computed matches the key however a certificate encodes it (a compressed EC point, RSA
+ * parameters without NULL), and an entry computed over raw bytes matches a certificate with the same
+ * bytes.
+ *
+ * @enforced-by behavioral -- membership has no rename-proof code shape; the RED vectors are the
+ * listed-key refusals at each verb, and the re-encodings in guard-distrust.test.js in both directions.
+ */
+function has(list, spkiBytes) {
+  if (list === null || list === undefined || list.length === 0 || spkiBytes === null || spkiBytes === undefined) return false;
+  if (gList.contains(list, digest(spkiBytes))) return true;
+  return gList.contains(list, keyDigest(spkiBytes));
+}
+
+/** Every entry of two lists that `keys` returned, once, as a frozen list; `null` when both are
+ * `null`. A transport default and a per-request list are combined this way, so a request cannot
+ * remove a key the default distrusts by naming a shorter list.
+ *
+ * @enforced-by behavioral -- a union has no rename-proof code shape; the RED vector is a request
+ * list that omits a default entry and the default entry still being refused.
+ */
+function union(a, b) {
+  if ((a === null || a === undefined) && (b === null || b === undefined)) return null;
+  var seen = _create(null);
+  var out = [];
+  var parts = [a || [], b || []];
+  for (var p = 0; p < 2; p++) {
+    var part = parts[p];
+    for (var i = 0, n = gList.count(part, "union"); i < n; i++) {
+      var hex = part[i];
+      if (_hasOwn(seen, hex)) continue;
+      seen[hex] = true;
+      gList.append(out, hex);
+    }
+  }
+  return _freeze(out);
+}
+
+module.exports = _freeze({ keys: keys, digest: digest, keyDigest: keyDigest, has: has, union: union });

package/lib/guard-identifier.js

@@ -743,7 +743,32 @@ function assertCallableOption(opts, key, E, code, label, shape) {
 // @enforced-by behavioral -- guard: each drives the shipped verb with a non-boolean and asserts the
 // @enforced-by behavioral -- typed refusal, and with false and absence to pin the two off forms.
 function booleanOption(value, E, code, label) {
-  if (value === undefined || value === null) return false;
+  return _switchValue(value, false, E, code, label);
+}
+
+/** @internal The same read for a switch whose absent form is ON: an option the caller turns OFF,
+ * where the documented default is the state an omitted option selects. The two differ only in what
+ * absence means, so the type rule is written once and each boundary names the default it documents.
+ * A boundary comparing such an option to `false` answers for every other value as the default
+ * state, which is how `certificates: "false"` embedded the certificate the caller asked to
+ * withhold; once the value has been through here, that comparison reads a boolean.
+ *
+ * @enforced-by behavioral -- the per-verb vectors in coercion-safe-options.test.js drive each
+ * @enforced-by behavioral -- shipped verb with a non-boolean and assert the typed refusal names the
+ * @enforced-by behavioral -- option, and with true, false and absence to pin the three accepted
+ * @enforced-by behavioral -- forms. The comparison this replaces has its own codebase-wide
+ * @enforced-by behavioral -- detector, optout-switch-read-by-coercion.
+ */
+function booleanOptionDefaultOn(value, E, code, label) {
+  return _switchValue(value, true, E, code, label);
+}
+
+/** @internal A switch is the boolean it documents, an absent one is the stated default, and every
+ * other value is refused. The value is rendered from its own type rather than coerced, so a caller
+ * value with a throwing `toString` reports the typed refusal. `null` is read as absence, the same
+ * reading the rest of this module gives it. */
+function _switchValue(value, whenAbsent, E, code, label) {
+  if (value === undefined || value === null) return whenAbsent;
   if (value === true || value === false) return value;
   throw E(code, label + " must be true or false, got " + _showSwitch(value));
 }
@@ -776,6 +801,7 @@ function declaresOwn(obj, name) {
 module.exports = intrinsic.freeze({
   assertCallable: assertCallable,
   booleanOption: booleanOption,
+  booleanOptionDefaultOn: booleanOptionDefaultOn,
   declaresOwn: declaresOwn,
   assertCallableOption: assertCallableOption,
   assertCanonicalOid: assertCanonicalOid,

package/lib/guard-json.js

@@ -24,7 +24,7 @@ var _hexVal = require("./guard-encoding").hexNibble;
 // @enforced-by json-parse-not-via-guard
 function parse(input, ErrorClass, spec) {
   function E(code, message, cause) { return new ErrorClass(code, message, cause); }
-  if (spec.maxBytes === undefined || spec.maxDepth === undefined) {
+  if (spec.maxBytes == null || spec.maxDepth == null) {
     throw new TypeError("guard.json.parse: spec.maxBytes and spec.maxDepth are required");
   }
   var maxBytes = limits.cap(spec.maxBytes, "guard.json.parse spec.maxBytes", undefined);