@blamejs/pki 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.9.5 — 2026-10-12
+
+Refuse a non-boolean switch option instead of reading it as the state the caller did not ask for.
+
+### Changed
+
+- For every one of these switches, `true` and `false` pass, `null` and an omitted option select the documented default, and any other value is refused with that module's own `domain/reason` code naming the option. For every value that was already valid the emitted bytes are unchanged. A call that passes a non-boolean to one of these options now throws instead of building a message the other way: pass the boolean, or omit the option to take its default.
+- `opts.pem` is unchanged and still takes `true` or a PEM label string where a verb documents one, as do `signingTime` (a time or `false`) and `pki.pkcs12.build`'s `mac` (a descriptor or `false`). These carry a value as well as an off form, and each is held to the type its own value needs.
+
+### Fixed
+
+- `pki.cms.sign` refuses a non-boolean `detached`. The option decided the message shape in one place and whether the content was carried in another, so `detached: "false"` took the attached branch and then omitted the content from it, emitting an attached SignedData with nothing in it.
+- `pki.cms.authenticate` refuses a non-boolean `authenticatedAttributes`. With `false` the MAC covers the content octets directly (RFC 6211 sec. 2), so the two values are structurally different messages and a mistyped one produced the message the caller had declined.
+- `pki.cms.digest` refuses a non-boolean `detached`; `pki.cms.sign` and `pki.cms.countersign` refuse a non-boolean `signedAttributes`; `pki.ocsp.sign` refuses a non-boolean `embedCert` or `extendedRevoke`; `pki.tsp.sign` refuses a non-boolean `ordering`; `pki.pkcs12.build` refuses a non-boolean `integrity.certificates`; `pki.path.crlChecker` and `pki.path.fetchingChecker` refuse a non-boolean `useDeltas`.
+- `pki.est.serverkeygen` reads a `null` `requestedEncryption` as the absent option it documents rather than as a stated `false`. It tested whether the caller had stated an override by presence alone, so a `null` counted as stated and coerced to `false`, and a request against a CSR that does advertise key encryption was refused for contradicting a CSR the caller never disagreed with.
+
+### Security
+
+- `pki.smime.sign` and `pki.smime.encrypt` refuse a non-boolean `protectHeaders`. Read by comparison to `true`, a value of any other type left RFC 9788 header protection off and the message went out unprotected with no error, so a caller that asked for the protection did not get it and was not told.
+- The `pki.est` and `pki.scep` verbs refuse a non-boolean `allowCrossOriginRedirect`. Read by truthiness, `"false"` allowed the cross-origin redirect on an unsafe method that the check exists to refuse (RFC 7030 sec. 3.2.1), which is the opposite of what that value states.
+- `pki.cms.sign` and `pki.cms.countersign` refuse a non-boolean `certificates`, the switch that withholds the signer chain. A value of any other type embedded the certificates the caller asked to leave out.
+- `pki.x509.sign` and `pki.csr.sign` refuse a non-boolean criticality flag (`keyUsageCritical`, `extendedKeyUsageCritical`, `certificatePoliciesCritical`, `policyMappingsCritical`, `qcStatementsCritical`, `tlsFeatureCritical`). A value of any other type could emit an extension critical that the caller asked to be non-critical, and RFC 5280 sec. 6.1 requires a relying party that does not recognize a critical extension to reject the certificate.
+
 ## v0.9.4 — 2026-10-12
 
 Refuse to issue an elliptic curve certificate asserting a key usage its own algorithm forbids.

package/lib/cms-digest.js

@@ -78,7 +78,8 @@ function _digestName(opts) {
  * @opts
  *   - `digestAlgorithm` (string) -- `sha256` (default), `sha384` or `sha512`.
  *   - `contentType` (string) -- the encapsulated content type by OID name, default `data`.
- *   - `detached` (boolean) -- omit the content, leaving the digest to travel alone.
+ *   - `detached` (boolean) -- omit the content, leaving the digest to travel alone. A value other
+ *     than `true`, `false`, `null` or an absent option is refused `cms/bad-input`.
  *   - `pem` (boolean) -- return a PEM `CMS` block instead of DER.
  * @example
  *   var der = await pki.cms.digest(Buffer.from("hello"));
@@ -94,6 +95,10 @@ async function _digest(content, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "cms/bad-input", "pki.cms.digest options");
   guard.identifier.assertKnownKeys(opts, _DIGEST_OPTS, _err, "cms/bad-input",
     "pki.cms.digest has an unknown option ");
+  /** @internal Whether the content rides in the message is decided below by comparing this option
+   *  to `true`, so a value of any other type attached a content the caller asked to leave out. */
+  var detached = guard.identifier.booleanOption(opts.detached, _err, "cms/bad-input",
+    "pki.cms.digest opts.detached");
   var raw = guard.bytes.source(content, CmsError, "cms/bad-input", "content");
   var alg = _digestName(opts);
   var ctName = opts.contentType === undefined ? "data" : opts.contentType;
@@ -101,7 +106,7 @@ async function _digest(content, opts) {
   if (!ctOid) throw _err("cms/bad-input", "opts.contentType is not a known OID name: " + guard.text.showValue(ctName));
 
   var value = guard.crypto.digest(NODE_DIGEST[alg], raw);
-  var eciChildren = opts.detached === true
+  var eciChildren = detached
     ? [b.oid(ctOid)]
     : [b.oid(ctOid), b.explicit(0, b.octetString(raw))];
   var dd = b.sequence([

package/lib/cms-encrypt.js

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

package/lib/cms-sign.js

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

package/lib/cms-verify.js

@@ -1275,16 +1275,20 @@ function _addCert(out, der) {
  * the same content as the buffered form.
  *
  * @opts  detached          Omit the encapsulated content (a detached signature; the verifier
- *                          supplies the content). Default false.
+ *                          supplies the content). Default false. A value other than `true`,
+ *                          `false`, `null` or an absent option is refused `cms/bad-input`.
  * @opts  eContentType      The encapsulated content type (an OID name). Default `data`.
  * @opts  signedAttributes  Include signed attributes (content-type, message-digest, signing-time);
- *                          false signs the content directly. Default true.
+ *                          false signs the content directly. Default true. A value other than
+ *                          `true`, `false`, `null` or an absent option is refused `cms/bad-input`.
  * @opts  additionalSignedAttributes  Extra signed attributes to add to every SignerInfo, each
  *                          `{ type, values }` (`type` an OID name or dotted string, `values` an
  *                          array of DER value `Buffer`s). Covered by the signature.
  * @opts  signingTime       A `Date` for the signing-time attribute, or false to omit it.
  * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
- * @opts  certificates      Embed the signer certificates in the output. Default true.
+ * @opts  certificates      Embed the signer certificates in the output. Default true. A value other
+ *                          than `true`, `false`, `null` or an absent option is refused
+ *                          `cms/bad-input`.
  * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
  * @opts  unsignedAttributes  Unsigned attributes for every SignerInfo, each `{ type, values }`
  *                          (`type` an OID name or dotted string, `values` an array of DER value
@@ -1341,12 +1345,15 @@ var sign = cmsSign.sign;
  *                              instead of the primary signature (a nested countersignature).
  * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; never a
  *                              content-type). Default true; false signs the target signature octets
- *                              directly.
+ *                              directly. A value other than `true`, `false`, `null` or an absent
+ *                              option is refused `cms/bad-input`.
  * @opts  signingTime           A `Date` for the countersignature's signing-time, or false to omit it.
  * @opts  additionalSignedAttributes  Extra signed attributes on the countersignature (a content-type
  *                              is rejected, RFC 5652 sec. 11.4).
  * @opts  sid                   `"issuerAndSerial"` (default) or `"ski"`.
- * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default true.
+ * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default
+ *                              true. A value other than `true`, `false`, `null` or an absent option
+ *                              is refused `cms/bad-input`.
  * @opts  algorithmProtection   Emit the RFC 6211 `CMSAlgorithmProtection` attribute on the
  *                              countersignature, copying ITS own digest and signature algorithm
  *                              identifiers rather than the countersigned signature's. Off by
@@ -1440,7 +1447,8 @@ var encrypt = cmsEncrypt.encrypt;
  * @opts digestAlgorithm The authenticated-attributes message-digest hash (defaults to the MAC hash).
  * @opts authenticatedAttributes Include the content-type + message-digest authenticated attributes
  *                          (the default, and required for a non-`data` content type); false MACs the
- *                          content directly.
+ *                          content directly. A value other than `true`, `false`, `null` or an absent
+ *                          option is refused `cms/bad-input`.
  * @opts authAttrs Extra authenticated attributes appended to the content-type + message-digest pair.
  * @opts contentType The encapsulated content type (an OID name). Default `data`.
  * @opts keyIdentifier `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.

package/lib/csr-sign.js

@@ -172,7 +172,11 @@ function _relatedCertRequest(spec) {
  * subject-owned set `pki.x509.sign` takes, or an array of pre-encoded Extension DER) and
  * `challengePassword`. An extension the issuing CA assigns (authorityKeyIdentifier, the
  * certificate-transparency pair, the CA version and previous-certificate hash, ocspNoCheck) is not a
- * request and is refused by name. `key` (or
+ * request and is refused by name. The per-extension criticality flags `pki.x509.sign` takes
+ * (`keyUsageCritical`, default true, and `extendedKeyUsageCritical`,
+ * `certificatePoliciesCritical`, `policyMappingsCritical`, `qcStatementsCritical`,
+ * `tlsFeatureCritical`, each default false) apply here too; each is a boolean, and a value other
+ * than `true`, `false`, `null` or an absent flag is refused `csr/bad-input`. `key` (or
  * `{ key }`) is the subject's own PKCS#8 private key, WebCrypto CryptoKey, or signer
  * `{ algorithm, publicKey, sign }`, so the request is self-signed
  * to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the

package/lib/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;
 }
 
@@ -1643,6 +1654,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",
@@ -1695,7 +1708,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
@@ -1919,6 +1934,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,
@@ -1933,7 +1950,11 @@ function serverkeygen(baseUrl, csrInput, opts) {
     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)");
     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)");

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/ocsp.js

@@ -316,6 +316,8 @@ function _normCertDer(cert, what) {
  *   extendedRevoke  emit the id-pkix-ocsp-extended-revoke extension (RFC 6960 sec. 4.4.8); implied
  *                   by a non-issued response, where `false` is refused.
  *   embedCert       `false` to omit certs [0] (a direct-CA response the client already trusts).
+ *                   For both switches, a value other than `true`, `false`, `null` or an absent
+ *                   option is refused `ocsp/bad-input`.
  *   pem             emit a PEM `OCSP RESPONSE` string instead of DER.
  * @example
  *   var ca = await pki.key.generate("Ed25519");
@@ -350,6 +352,12 @@ function _sign(responseData, responder, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "ocsp/bad-input", "pki.ocsp.sign options");
   guard.identifier.assertKnownKeys(opts, _SIGN_OPTS, _err, "ocsp/bad-input",
     "pki.ocsp.sign has an unknown option (the nonce to echo back is `nonce`): ");
+  /** @internal Both switches are read below against one boolean each, which answered for a value
+   *  of any other type as the opposite of what the caller asked: `embedCert: "false"` carried the
+   *  responder certificate a direct-CA response leaves out, and `extendedRevoke: "false"` placed
+   *  the extension while escaping the sec. 2.2 refusal that reads the same option. */
+  guard.identifier.booleanOptionDefaultOn(opts.embedCert, _err, "ocsp/bad-input", "pki.ocsp.sign opts.embedCert");
+  guard.identifier.booleanOption(opts.extendedRevoke, _err, "ocsp/bad-input", "pki.ocsp.sign opts.extendedRevoke");
   responseData = responseData || _ocspIntrinsic.create(null);
   if (typeof responseData !== "object") throw _err("ocsp/bad-input", "the responseData must be an object { responderID, responses, producedAt? }");
   guard.identifier.assertKnownKeys(responseData, _RESPONSE_DATA_KEYS, _err, "ocsp/bad-input", "unknown responseData field (accepted: responderID, responses, producedAt): ");

package/lib/path-validate.js

@@ -2147,7 +2147,9 @@ function selectDelta(candidates) {
  * revocationDate.
  *
  * @opts
- *   useDeltas  boolean  merge delta CRLs onto their base (RFC 5280 sec. 6.3.1(b)).
+ *   useDeltas  boolean  merge delta CRLs onto their base (RFC 5280 sec. 6.3.1(b)). Default `true`;
+ *              a value other than `true`, `false`, `null` or an absent option is refused
+ *              `path/bad-input`.
  *                       Default true. When false a delta is never merged; it is
  *                       still consulted for revocation.
  *
@@ -2171,7 +2173,10 @@ function crlChecker(crls, opts) {
     return guard.parsed.acceptDerived(c, "crl", crl.parse, E, "path/bad-input",
       "crlChecker: crls[" + ci + "]");
   });
-  var useDeltas = !(opts && opts.useDeltas === false);
+  /** @internal The sec. 6.3.1(b) merge, read as the boolean it documents: the comparison this
+   * replaces answered for a value of any other type by merging deltas the caller turned off. */
+  var useDeltas = guard.identifier.booleanOptionDefaultOn(opts && opts.useDeltas, E,
+    "path/bad-input", "crlChecker: opts.useDeltas");
   return {
     check: async function (cert, issuer, ctx) {
       var time = ctx.time;

package/lib/pkcs12-build.js

@@ -532,7 +532,7 @@ function _normalizeSpec(spec, opts, form) {
  * @opts
  *   - `password` -- the shared privacy + integrity password (string / Buffer / Uint8Array).
  *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations?, password? }`. `password` overrides the shared integrity password for the MAC. `keyLength` is a `pbmac1` field: the classic Appendix B derivation produces a key at the hash's own output length, and naming one under `hmac` is refused.
- *   - `integrity` -- `{ mode: 'public-key', signer: { cert, key, digestAlgorithm?, pss? } | signers: [ ... ], sid?, signingTime?, certificates? }` for public-key integrity (a CMS SignedData authSafe over any `pki.cms.sign` signer algorithm, no MacData). Combining it with a truthy `mac` is rejected.
+ *   - `integrity` -- `{ mode: 'public-key', signer: { cert, key, digestAlgorithm?, pss? } | signers: [ ... ], sid?, signingTime?, certificates? }` for public-key integrity (a CMS SignedData authSafe over any `pki.cms.sign` signer algorithm, no MacData). Combining it with a truthy `mac` is rejected. `certificates` embeds the signer certificates in the authSafe, default true; a value other than `true`, `false`, `null` or an absent option is refused `pkcs12/bad-input`.
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
  * @example
@@ -572,6 +572,11 @@ async function _build(spec, opts) {
   if (opts.integrity != null) {
     if (typeof opts.integrity !== "object" || Array.isArray(opts.integrity)) throw _err("pkcs12/bad-input", "opts.integrity must be an object { mode, signer|signers, ... }");
     guard.identifier.assertKnownKeys(opts.integrity, _INTEGRITY_OPTS, _err, "pkcs12/bad-input", "opts.integrity has an unknown option ");
+    /** @internal Forwarded to `pki.cms.sign` below by comparing it to `false`, which answered for a
+     *  value of any other type by embedding the signer certificates the caller asked to leave out
+     *  of the authSafe. */
+    guard.identifier.booleanOptionDefaultOn(opts.integrity.certificates, _err, "pkcs12/bad-input",
+      "opts.integrity.certificates");
     if (opts.integrity.mode !== "public-key") {
       throw _err("pkcs12/bad-integrity-mode", "opts.integrity.mode must be \"public-key\" (the only mode it selects); omit opts.integrity for password integrity, got " + guard.text.showValue(opts.integrity.mode));
     }

package/lib/pki-build.js

@@ -648,6 +648,36 @@ function makeBuilder(ctx) {
     if (bc.pathLen != null) pathLen(bc.pathLen);
     guard.identifier.assertKnownKeys(bc, BC_KEYS, E, "bad-input", "unknown basicConstraints field ");
   }
+
+  /** @internal The criticality a caller states for an extension, read as the boolean each flag
+   * documents and resolved to the default an omitted flag selects. RFC 5280 sec. 4.2 fixes
+   * keyUsage critical and leaves the other five non-critical, which is why the defaults differ.
+   * `basicConstraints` carries its own flag inside the value and is typed by `validateBcSpec`.
+   *
+   * The flags are RETURNED, so the emitters below read criticality from this record rather than
+   * from the caller's spec a second time. A flag read off the spec at the point of emission is a
+   * read of a value that was never typed: measured, `extendedKeyUsageCritical: "false"` emitted
+   * that extension critical, and an extension a relying party does not recognize as critical is
+   * one RFC 5280 sec. 6.1 requires it to reject. */
+  var CRITICALITY_FLAGS = [
+    ["keyUsageCritical", true],
+    ["extendedKeyUsageCritical", false],
+    ["certificatePoliciesCritical", false],
+    ["policyMappingsCritical", false],
+    ["qcStatementsCritical", false],
+    ["tlsFeatureCritical", false],
+  ];
+  function criticality(extSpec, label) {
+    var out = intrinsic.create(null);
+    var where = label || "extensions";
+    for (var i = 0; i < CRITICALITY_FLAGS.length; i++) {
+      var k = CRITICALITY_FLAGS[i][0];
+      out[k] = CRITICALITY_FLAGS[i][1]
+        ? guard.identifier.booleanOptionDefaultOn(extSpec[k], E, "bad-input", where + "." + k)
+        : guard.identifier.booleanOption(extSpec[k], E, "bad-input", where + "." + k);
+    }
+    return out;
+  }
   function extBasicConstraints(spec) {
     var children = [];
     if (spec.cA === true) _push(children,b.boolean(true));
@@ -1368,16 +1398,17 @@ function makeBuilder(ctx) {
     guard.identifier.assertKnownKeys(extSpec, REQ_EXT_KEYS, E, "bad-input", function (k) {
       return "unknown requested extension " + JSON.stringify(k) + "; pass a pre-encoded Extension DER via the array form for a custom extension";
     });
+    var crit = criticality(extSpec, "requested extensions");
     var out = [];
     if (extSpec.subjectKeyIdentifier != null) {
       if (extSpec.subjectKeyIdentifier === true && spki == null) throw E("bad-input", "subjectKeyIdentifier auto-derive (true) requires the public key -- supply a Buffer key id, or include the public key");
       _push(out,ext(O("subjectKeyIdentifier"), false, extSki(skiKeyId(extSpec.subjectKeyIdentifier, spki))));
     }
-    if (extSpec.keyUsage != null) _push(out,ext(O("keyUsage"), extSpec.keyUsageCritical !== false, extKeyUsage(extSpec.keyUsage)));
-    if (extSpec.extendedKeyUsage != null) _push(out,ext(O("extKeyUsage"), !!extSpec.extendedKeyUsageCritical, extExtKeyUsage(extSpec.extendedKeyUsage)));
+    if (extSpec.keyUsage != null) _push(out,ext(O("keyUsage"), crit.keyUsageCritical, extKeyUsage(extSpec.keyUsage)));
+    if (extSpec.extendedKeyUsage != null) _push(out,ext(O("extKeyUsage"), crit.extendedKeyUsageCritical, extExtKeyUsage(extSpec.extendedKeyUsage)));
     if (extSpec.basicConstraints != null) { validateBcSpec(extSpec.basicConstraints); _push(out,ext(O("basicConstraints"), extSpec.basicConstraints.critical !== false, extBasicConstraints(extSpec.basicConstraints))); }
     if (extSpec.subjectAltName != null) _push(out,ext(O("subjectAltName"), false, extSan(extSpec.subjectAltName)));
-    if (extSpec.certificatePolicies != null) _push(out,ext(O("certificatePolicies"), !!extSpec.certificatePoliciesCritical, extCertPolicies(extSpec.certificatePolicies)));
+    if (extSpec.certificatePolicies != null) _push(out,ext(O("certificatePolicies"), crit.certificatePoliciesCritical, extCertPolicies(extSpec.certificatePolicies)));
     /** @internal RFC 5280 sec. 4.2.1.10 fixes this extension critical, in a request as in the certificate. */
     if (extSpec.nameConstraints != null) guard.list.append(out, ext(O("nameConstraints"), true, extNameConstraints(extSpec.nameConstraints)));
     if (extSpec.authorityInfoAccess != null) guard.list.append(out, ext(O("authorityInfoAccess"), false, extAuthorityInfoAccess(extSpec.authorityInfoAccess)));
@@ -1385,14 +1416,14 @@ function makeBuilder(ctx) {
     if (extSpec.freshestCRL != null) guard.list.append(out, ext(O("freshestCRL"), false, extCrlDistributionPoints(extSpec.freshestCRL, "freshestCRL")));
     if (extSpec.policyConstraints != null) guard.list.append(out, ext(O("policyConstraints"), true, extPolicyConstraints(extSpec.policyConstraints)));
     if (extSpec.inhibitAnyPolicy != null) guard.list.append(out, ext(O("inhibitAnyPolicy"), true, extInhibitAnyPolicy(extSpec.inhibitAnyPolicy)));
-    if (extSpec.policyMappings != null) guard.list.append(out, ext(O("policyMappings"), !!extSpec.policyMappingsCritical, extPolicyMappings(extSpec.policyMappings)));
+    if (extSpec.policyMappings != null) guard.list.append(out, ext(O("policyMappings"), crit.policyMappingsCritical, extPolicyMappings(extSpec.policyMappings)));
     if (extSpec.issuerAltName != null) guard.list.append(out, ext(O("issuerAltName"), false, encodeGeneralNames(reqDenseArray(extSpec.issuerAltName, "issuerAltName"))));
-    if (extSpec.qcStatements != null) guard.list.append(out, ext(O("qcStatements"), !!extSpec.qcStatementsCritical, extQcStatements(extSpec.qcStatements)));
+    if (extSpec.qcStatements != null) guard.list.append(out, ext(O("qcStatements"), crit.qcStatementsCritical, extQcStatements(extSpec.qcStatements)));
     /** @internal RFC 7633 sec. 4.2.1 lets a request state the features the server supports, and
      *  sec. 4.3.2 asks a server to generate it, so a feature declaration is the requester's wish and
      *  belongs in this table. The criticality knob is here too, because a request carries the
      *  Extension shape whole and the CA decides what it issues. */
-    if (extSpec.tlsFeature != null) guard.list.append(out, ext(O("tlsFeature"), !!extSpec.tlsFeatureCritical, extTlsFeature(extSpec.tlsFeature)));
+    if (extSpec.tlsFeature != null) guard.list.append(out, ext(O("tlsFeature"), crit.tlsFeatureCritical, extTlsFeature(extSpec.tlsFeature)));
     if (extSpec.msCertificateTemplate != null) guard.list.append(out, ext(O("msCertificateTemplate"), false, extMsCertificateTemplate(extSpec.msCertificateTemplate)));
     if (extSpec.msEnrollCertType != null) guard.list.append(out, ext(O("msEnrollCertType"), false, extMsEnrollCertType(extSpec.msEnrollCertType)));
     if (extSpec.msApplicationPolicies != null) guard.list.append(out, ext(O("msApplicationPolicies"), false, extCertPolicies(extSpec.msApplicationPolicies)));
@@ -1457,6 +1488,7 @@ function makeBuilder(ctx) {
     encodeGeneralNames: encodeGeneralNames, serialInteger: serialInteger, timeDer: timeDer,
     requestedExtensions: requestedExtensions,
     extKeyUsage: extKeyUsage, extExtKeyUsage: extExtKeyUsage, validateBcSpec: validateBcSpec,
+    criticality: criticality,
     extBasicConstraints: extBasicConstraints, pathLen: pathLen, extSki: extSki, extAki: extAki, AKI_KEYS: AKI_KEYS,
     extSan: extSan, extCertPolicies: extCertPolicies, ext: ext,
     extSubjectInfoAccess: extSubjectInfoAccess, extSubjectDirectoryAttributes: extSubjectDirectoryAttributes,

package/lib/revocation-fetch.js

@@ -670,7 +670,9 @@ function _deltaUrlsFor(parsedCrl, state) {
  *                          of the same shape. A transport that does not declare that it blocks
  *                          private addresses is refused a hostname.
  * @opts  allowPlaintextHttp  Whether an `http` URL is fetched. Default `true`.
- * @opts  useDeltas         Whether a freshestCRL delta is fetched and merged. Default `true`.
+ * @opts  useDeltas         Whether a freshestCRL delta is fetched and merged. Default `true`. A
+ *                         value other than `true`, `false`, `null` or an absent option is refused
+ *                         `path/bad-input`.
  * @opts  nonce             Whether an OCSP request carries a 32-octet nonce. `true` or `false`,
  *                          and anything else is `path/bad-input` rather than the default, since a
  *                          control read as off is one an operator asked for and did not get.
@@ -709,7 +711,11 @@ function fetchingChecker(opts) {
      * door is the value the rule is applied on. */
     net: intrinsic.freeze({ allowHttp: allowPlaintextHttp, guardsAddresses: _declaresAddressGuard(transport) }),
     allowPlaintextHttp: allowPlaintextHttp,
-    useDeltas: !(opts.useDeltas === false),
+    /** @internal Read the way `nonce` on the next line has been read since it was written: the
+     * comparison this replaces answered for a value of any other type by fetching the deltas the
+     * caller declined. */
+    useDeltas: guard.identifier.booleanOptionDefaultOn(opts.useDeltas, E, "path/bad-input",
+      "fetchingChecker: opts.useDeltas"),
     nonce: _booleanOption(opts.nonce, "fetchingChecker: opts.nonce"),
     tls: opts.tls,
     maxFetches: guard.limits.cap(opts.maxFetches, "fetchingChecker: opts.maxFetches", LIMITS.REVOCATION_MAX_FETCHES,

package/lib/scep.js

@@ -28,6 +28,12 @@
  *   the message layer, transport-agnostic; a live SCEP CA is driven over
  *   pki.transport separately.
  *
+ *   Every verb that reaches a CA accepts the same transport bounds, listed on
+ *   each of them. One of those bounds is a switch: `allowCrossOriginRedirect`
+ *   opts in to following a cross-origin redirect on an unsafe method. It is a
+ *   boolean, and a value other than `true`, `false`, `null` or an absent option
+ *   is refused `scep/bad-input` before the first request goes out.
+ *
  * @card
  *   Build and read SCEP (RFC 8894) messages: a PKCSReq, RenewalReq, CertPoll,
  *   GetCert, or GetCRL request, or a CA-side CertRep response, wrapped in the
@@ -731,7 +737,11 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
   var redirects = 0, curMethod = method, curBody = body, initialOrigin = _urlOrigin(url);
   var proxySnap = _snapshotProxy(opts.proxy);
   var tlsBase = _tlsForRequest(opts);
-  var allowCrossOrigin = !!opts.allowCrossOriginRedirect;
+  /** @internal Read as the boolean it documents, on the one path every network verb here takes and
+   * before the first request. Taken by truthiness, `allowCrossOriginRedirect: "false"` ALLOWED the
+   * cross-origin redirect on an unsafe method that the check below exists to refuse. */
+  var allowCrossOrigin = guard.identifier.booleanOption(opts.allowCrossOriginRedirect, _err,
+    "scep/bad-input", "opts.allowCrossOriginRedirect");
   function _hopTls(current) {
     var t = tlsBase;
     if (_urlOrigin(current) !== initialOrigin) {

package/lib/smime.js

@@ -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) {
@@ -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"`.
@@ -875,7 +886,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"`.

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) +

package/lib/x509-sign.js

@@ -228,6 +228,10 @@ function _buildExtensions(extSpec, ctx) {
     return "unknown extension " + JSON.stringify(k) + " in the extensions spec; pass a pre-encoded Extension DER via the array form for a custom extension";
   });
 
+  /** @internal The criticality flags, typed at this door and read from the record below: the
+   *  emitters took them off the caller's spec, where a value that was never a boolean selected a
+   *  criticality nobody asked for. */
+  var crit = _b.criticality(extSpec);
   var bc = extSpec.basicConstraints;
   if (bc != null) _validateBcSpec(bc);
   var caTrue = !!(bc && bc.cA === true);
@@ -257,14 +261,14 @@ function _buildExtensions(extSpec, ctx) {
     var akiF = _akiFields(akiVal, ctx);
     _push(out,_ext(O("authorityKeyIdentifier"), false, _extAki(akiF[0], akiF[1], akiF[2])));
   }
-  if (ku != null) _push(out,_ext(O("keyUsage"), extSpec.keyUsageCritical !== false, _extKeyUsage(ku)));
-  if (extSpec.extendedKeyUsage != null) _push(out,_ext(O("extKeyUsage"), !!extSpec.extendedKeyUsageCritical, _extExtKeyUsage(extSpec.extendedKeyUsage)));
+  if (ku != null) _push(out,_ext(O("keyUsage"), crit.keyUsageCritical, _extKeyUsage(ku)));
+  if (extSpec.extendedKeyUsage != null) _push(out,_ext(O("extKeyUsage"), crit.extendedKeyUsageCritical, _extExtKeyUsage(extSpec.extendedKeyUsage)));
   if (bc != null) {
     if (bc.cA === true && bc.critical === false) throw _err("x509/bad-input", "a CA certificate's basicConstraints MUST be critical (RFC 5280 sec. 4.2.1.9)");
     _push(out,_ext(O("basicConstraints"), bc.critical !== false, _extBasicConstraints(bc)));
   }
   if (extSpec.subjectAltName != null) _push(out,_ext(O("subjectAltName"), ctx.subjectEmpty, _extSan(extSpec.subjectAltName)));
-  if (extSpec.certificatePolicies != null) _push(out,_ext(O("certificatePolicies"), !!extSpec.certificatePoliciesCritical, _extCertPolicies(extSpec.certificatePolicies)));
+  if (extSpec.certificatePolicies != null) _push(out,_ext(O("certificatePolicies"), crit.certificatePoliciesCritical, _extCertPolicies(extSpec.certificatePolicies)));
   /** @internal Sections 4.2.2.1 and 4.2.1.15 fix these non-critical; sec. 4.2.1.13 states a SHOULD
    *  and the toolkit issues the conforming form. */
   if (extSpec.authorityInfoAccess != null) guard.list.append(out, _ext(O("authorityInfoAccess"), false, _extAia(extSpec.authorityInfoAccess)));
@@ -279,15 +283,15 @@ function _buildExtensions(extSpec, ctx) {
    *  does not process the extension, so a critical one is a certificate this toolkit's own validator
    *  must reject and pki.lint.certificate grades `unknown-critical-extension`. The default is the
    *  usable form and the knob reaches the SHOULD-conforming one, as certificatePolicies does. */
-  if (extSpec.policyMappings != null) guard.list.append(out, _ext(O("policyMappings"), !!extSpec.policyMappingsCritical, _extPolicyMappings(extSpec.policyMappings)));
+  if (extSpec.policyMappings != null) guard.list.append(out, _ext(O("policyMappings"), crit.policyMappingsCritical, _extPolicyMappings(extSpec.policyMappings)));
   if (extSpec.issuerAltName != null) guard.list.append(out, _ext(O("issuerAltName"), false, _encodeGeneralNames(_reqDenseArray(extSpec.issuerAltName, "issuerAltName"))));
   /** @internal pki.path.validate does not process qcStatements, so a critical one is rejected as an
    *  unrecognized critical extension; the default is the form that validates and the knob reaches
    *  the other, as policyMappings and certificatePolicies do. */
-  if (extSpec.qcStatements != null) guard.list.append(out, _ext(O("qcStatements"), !!extSpec.qcStatementsCritical, _extQcStatements(extSpec.qcStatements)));
+  if (extSpec.qcStatements != null) guard.list.append(out, _ext(O("qcStatements"), crit.qcStatementsCritical, _extQcStatements(extSpec.qcStatements)));
   /** @internal RFC 7633 sec. 4: SHOULD NOT be critical, and the clause names the case where critical
    *  is the desired behavior, so the knob exists and the default is the compatible form. */
-  if (extSpec.tlsFeature != null) guard.list.append(out, _ext(O("tlsFeature"), !!extSpec.tlsFeatureCritical, _b.extTlsFeature(extSpec.tlsFeature)));
+  if (extSpec.tlsFeature != null) guard.list.append(out, _ext(O("tlsFeature"), crit.tlsFeatureCritical, _b.extTlsFeature(extSpec.tlsFeature)));
   if (extSpec.nameConstraints != null) {
     if (!caTrue) throw _err("x509/bad-input", "nameConstraints appears only in a CA certificate, so it requires basicConstraints cA=TRUE (RFC 5280 sec. 4.2.1.10)");
     guard.list.append(out, _ext(O("nameConstraints"), true, _extNameConstraints(extSpec.nameConstraints)));
@@ -565,6 +569,14 @@ function _hasCriticalSan(extSpec) {
  * (positive, <= 20 octets), the validity UTCTime/GeneralizedTime cutover, the DER DEFAULT omissions
  * (v1 tag, `critical=FALSE`, `cA=FALSE`), and the CA cross-field rules (keyCertSign and
  * pathLenConstraint require cA=TRUE) are all enforced; a violation throws a typed `CertificateError`.
+ *
+ * Criticality is stated per extension: `keyUsageCritical` (default true), and
+ * `extendedKeyUsageCritical`, `certificatePoliciesCritical`, `policyMappingsCritical`,
+ * `qcStatementsCritical` and `tlsFeatureCritical` (each default false). `basicConstraints` carries
+ * its own `critical` inside the value. Each is a boolean: a value other than `true`, `false`,
+ * `null` or an absent flag is refused `x509/bad-input`. The extensions RFC 5280 fixes one way
+ * (`nameConstraints` critical, `authorityInfoAccess` and `cRLDistributionPoints` non-critical) take
+ * no flag.
  * Where the spec carries raw DER (a `Name` Buffer, a pre-encoded `Extension`, an issuer `publicKey`
  * SPKI), a structural fault throws `CertificateError`, while a malformed leaf inside those bytes
  * throws `Asn1Error`, the same two-error contract the parsers present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -87,6 +87,6 @@
   "devDependencies": {
     "c8": "12.0.0",
     "esbuild": "0.28.2",
-    "eslint": "10.11.0"
+    "eslint": "10.12.0"
   }
 }

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:9f1767af-18a9-4a06-85fd-6273c947d9b9",
+  "serialNumber": "urn:uuid:e1f0a0ad-8621-4fc9-a62a-62df66fe4d21",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-10-12T04:46:50.282Z",
+    "timestamp": "2026-10-12T15:58:58.900Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.9.4",
+      "bom-ref": "@blamejs/pki@0.9.5",
       "type": "application",
       "name": "pki",
-      "version": "0.9.4",
+      "version": "0.9.5",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.9.4",
+      "purl": "pkg:npm/%40blamejs/pki@0.9.5",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.9.4",
+      "ref": "@blamejs/pki@0.9.5",
       "dependsOn": []
     }
   ]