@blamejs/pki 0.9.4 → 0.9.6

package/lib/webauthn-mds.js

@@ -122,7 +122,7 @@ var CERT_SCOPED_STATUS = intrinsic.freeze(intrinsic.assign(intrinsic.create(null
 
 var _BLOB_OPTS = intrinsic.assign(intrinsic.create(null), {
   rootCertificates: 1, time: 1, previousNo: 1, requireRollbackCheck: 1, allowStale: 1,
-  statusPolicy: 1, rejectUnknownStatus: 1,
+  statusPolicy: 1, rejectUnknownStatus: 1, distrustedKeys: 1,
 });
 
 function _isPlainObject(v) { return !!v && typeof v === "object" && !intrinsic.isArray(v); }
@@ -218,8 +218,9 @@ function _verifyMetadataBlob(blob, opts) {
   if (!intrinsic.isArray(roots) || roots.length === 0) {
     throw _err("webauthn/metadata-no-root", "verifying a metadata BLOB requires opts.rootCertificates -- the FIDO root(s) to anchor it to; this library bundles none");
   }
-  if (o.time !== undefined) guard.time.assertValid(o.time, _err, "webauthn/bad-input", "opts.time");
-  var at = o.time === undefined ? new intrinsic.Date() : o.time;
+  if (o.time != null) guard.time.assertValid(o.time, _err, "webauthn/bad-input", "opts.time");
+  var at = o.time == null ? new intrinsic.Date() : o.time;
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (o.previousNo !== undefined && (!intrinsic.isSafeInteger(o.previousNo) || o.previousNo < 0)) {
     throw _err("webauthn/bad-input", "opts.previousNo must be a non-negative safe integer");
   }
@@ -228,13 +229,18 @@ function _verifyMetadataBlob(blob, opts) {
       throw _err("webauthn/bad-input", "opts." + k + " must be a boolean");
     }
   });
+  // allow:caller-option-presence-tested-against-undefined -- absence means any status is accepted, so a null must be refused rather than widen the policy
   if (o.statusPolicy !== undefined && typeof o.statusPolicy !== "function" &&
       o.statusPolicy !== "any" && o.statusPolicy !== "latest-by-date") {
     throw _err("webauthn/bad-input", "opts.statusPolicy must be \"any\", \"latest-by-date\", or a function");
   }
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (o.requireRollbackCheck === true && o.previousNo === undefined) {
     throw _err("webauthn/metadata-no-baseline", "opts.requireRollbackCheck was set without opts.previousNo, so there is no baseline to compare against");
   }
+  /** @internal Typed here, before the chain walk, because the walk turns a validation rejection into
+   *  an untrusted verdict, and a malformed list must be reported as the caller's input fault. */
+  var distrusted = guard.distrust.keys(o.distrustedKeys, _err, "webauthn/bad-input", "opts.distrustedKeys");
   opts = o;
   var anchors = intrinsic.mapList(roots, function (r, i) { return _asCert(r, "opts.rootCertificates[" + i + "]"); });
 
@@ -351,14 +357,17 @@ function _verifyMetadataBlob(blob, opts) {
   }, function (e) { throw _err("webauthn/unsupported-algorithm", "the metadata BLOB x5c leaf key could not be imported for " + header.alg, e); });
   var anchored = intrinsic.chain(verified, function (ok) {
     if (!ok) throw _err("webauthn/verify-failed", "the metadata BLOB signature does not verify under its x5c leaf key");
-    return _chainToAnchor(chain, anchors, at);
+    return _chainToAnchor(chain, anchors, at, undefined, undefined, distrusted);
   });
   return intrinsic.chain(anchored, function () {
     return _parsePayload(segs[1], at, opts);
   });
 }
 
-function _chainToAnchor(chain, anchors, at, what, code) {
+/** @internal `distrusted` is a list `guard.distrust.keys` returned, or null. It reaches every
+ *  validation below, and the self-presented anchor, which is trusted without one, is refused here
+ *  when its key is listed. */
+function _chainToAnchor(chain, anchors, at, what, code, distrusted) {
   var subject = what || "metadata BLOB certificate chain";
   var faultCode = code || "webauthn/metadata-untrusted";
   var ordered = _reverse(intrinsic.copyList(chain));
@@ -381,12 +390,19 @@ function _chainToAnchor(chain, anchors, at, what, code) {
       var path = intrinsic.copyList(ordered);
       var strippedAnchor = false;
       if (path.length && _isAnchorItself(path[0], anchor)) { path = intrinsic.copyList(path, 1); strippedAnchor = true; }
-      if (path.length === 0) return strippedAnchor;
+      if (path.length === 0) {
+        if (strippedAnchor && guard.distrust.has(distrusted, anchor.subjectPublicKeyInfo.bytes)) {
+          lastFault = _err(faultCode, "the " + subject + " is a trust anchor whose key is listed in opts.distrustedKeys");
+          return false;
+        }
+        return strippedAnchor;
+      }
       var verdict = pathValidate.validate(path, {
         time: at,
         trustAnchors: { name: anchor.subject, publicKey: anchor.subjectPublicKeyInfo.bytes,
           algorithm: anchor.subjectPublicKeyInfo.algorithm.oid,
           parameters: anchor.subjectPublicKeyInfo.algorithm.parameters },
+        distrustedKeys: distrusted || null,
       });
       return intrinsic.chain(verdict, function (r) { return !!(r && r.valid); },
         function (e) { lastFault = e; return false; });
@@ -443,6 +459,7 @@ function _parsePayload(seg, at, opts) {
   if (!_isPlainObject(payload)) throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must be a JSON object");
   if (typeof payload.legalHeader !== "string") throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must carry a string legalHeader");
   if (!intrinsic.isSafeInteger(payload.no) || payload.no < 0) throw _err("webauthn/bad-metadata-blob", "the metadata BLOB payload must carry a non-negative integer no");
+  // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
   if (opts.previousNo !== undefined && payload.no <= opts.previousNo) {
     throw _err("webauthn/metadata-rollback", "the metadata BLOB no " + payload.no + " does not exceed the previously held " + opts.previousNo);
   }
@@ -525,7 +542,9 @@ function _parsePayload(seg, at, opts) {
   });
   var result = { no: payload.no, legalHeader: payload.legalHeader, nextUpdate: payload.nextUpdate,
     stale: stale, allowStale: opts.allowStale === true,
+    // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
     rollbackChecked: opts.previousNo !== undefined,
+    // allow:caller-option-presence-tested-against-undefined -- absence means no rollback comparison is made, so a null must be refused rather than drop the check
     previousNo: opts.previousNo === undefined ? null : opts.previousNo,
     entries: entries, byAaguid: byAaguid, byKeyIdentifier: byKeyIdentifier,
     statusPolicy: opts.statusPolicy || "any", rejectUnknownStatus: opts.rejectUnknownStatus === true };
@@ -558,7 +577,8 @@ function metadataAnchors(entry, opts) {
   if (typeof opts !== "object" || intrinsic.isArray(opts)) throw _err("webauthn/bad-input", "metadataAnchors opts must be an object");
   guard.identifier.assertKnownKeys(opts, _ANCHOR_OPTS, _err, "webauthn/bad-input", "metadataAnchors opts has an unknown key ");
   opts = guard.identifier.ownOptions(opts);
-  if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+  if (opts.time != null) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+  // allow:caller-option-presence-tested-against-undefined -- a trust input: absence means no metadata anchor is applied, so a null must be refused
   if (opts.metadata !== undefined) {
     if (!isVerifiedResult(opts.metadata)) {
       throw _err("webauthn/bad-input", "metadataAnchors opts.metadata expects a verifyMetadataBlob result -- an object that merely resembles one has not been through the signature and chain checks");
@@ -571,7 +591,8 @@ function metadataAnchors(entry, opts) {
    *  freshness and every status report's effective date are compared against, so a replacement
    *  answering with an earlier one accepts expired metadata and suppresses a report already in
    *  effect. */
-  var at = opts.time === undefined ? new intrinsic.Date() : opts.time;
+  var at = opts.time == null ? new intrinsic.Date() : opts.time;
+  // allow:caller-option-presence-tested-against-undefined -- a trust input: absence means no metadata anchor is applied, so a null must be refused
   if (opts.metadata !== undefined) assertFresh(opts.metadata, at, "metadataAnchors");
   if (statusDenied(entry, opts.metadata, opts.certificate, at)) {
     throw _err("webauthn/metadata-status", "the metadata entry for this authenticator carries a disqualifying status report, so it registers no anchors to trust");

package/lib/webauthn.js

@@ -1,6 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
+// codebase-patterns:allow-file caller-option-presence-tested-against-undefined
+/** @internal The `expected*` and `require*` options are SECURITY EXPECTATIONS, so presence
+ * is asked against `undefined` alone and a `null` is not read as an omission. A caller whose
+ * `expectedChallenge` arrives null, from an expired session or a missing field, must be
+ * refused rather than have the ceremony verified with the challenge comparison skipped:
+ * read as absence the check does not run, the verdict reports `checked.challenge` false, and
+ * the call still succeeds. `expectedTopOrigin: null` is a stated value on top of that, naming
+ * an unframed ceremony (WebAuthn sec. 5.8.1). */
 /**
  * @module pki.webauthn
  * @nav        Validation
@@ -413,7 +421,7 @@ function _aaguidIsSigned(fmt) { return _AAGUID_SIGNED_BY_FMT[fmt] !== false; }
 var _VERIFY_OPTS = intrinsic.assign(intrinsic.create(null), {
   time: 1, metadata: 1, tpmPolicy: 1, safetyNetRoots: 1, verifySafetyNetJws: 1, requireCtsProfileMatch: 1,
   expectedRpId: 1, requireUserPresence: 1, requireUserVerification: 1, allowedAlgorithms: 1,
-  rootCertificates: 1,
+  rootCertificates: 1, distrustedKeys: 1,
   clientDataJSON: 1, expectedChallenge: 1, expectedOrigin: 1, expectedTopOrigin: 1,
 });
 
@@ -484,12 +492,12 @@ function _applyCallerRoots(res, supplied, vopts, onlyPaths) {
     throw _err("webauthn/anchor-not-applicable",
       "opts.rootCertificates was supplied, but this attestation carries no trust path to anchor (format '" + res.fmt + "')");
   }
-  var at = vopts.time !== undefined ? vopts.time : new intrinsic.Date();
+  var at = vopts.time != null ? vopts.time : new intrinsic.Date();
   var anchoredAll = intrinsic.reduce(paths, function (p, info) {
     return intrinsic.chain(p, function () {
-      var pathAt = vopts.time !== undefined ? vopts.time : (info.at || at);
+      var pathAt = vopts.time != null ? vopts.time : (info.at || at);
       return mds.chainToAnchor(_reverse(intrinsic.copyList(info.tp)), roots, pathAt,
-        "attestation trust path (against the roots supplied as opts.rootCertificates)");
+        "attestation trust path (against the roots supplied as opts.rootCertificates)", undefined, vopts.distrustedKeys);
     });
   }, _promiseResolve(_Promise, undefined));
   return intrinsic.chain(anchoredAll, function () {
@@ -559,6 +567,7 @@ function _applyBindings(authData, coseKey, opts) {
       "signature made by this credential would use SHA-1, so it is refused unless opts.allowedAlgorithms " +
       "names -65535 explicitly");
   }
+  // allow:caller-option-presence-tested-against-undefined -- absence means every supported algorithm is accepted, so a null must be refused rather than drop the allowlist
   if (opts.allowedAlgorithms !== undefined) {
     /** @internal The entries are required to be the list's OWN. A hole answers from the prototype at
      *  that index, and the universal test skips it, so a sparse list with a number installed on
@@ -720,7 +729,7 @@ var VERIFIERS = intrinsic.assign(intrinsic.create(null), {
     if (!intrinsic.isArray(roots) || roots.length === 0) {
       throw _err("webauthn/safetynet-no-root", "verifying an android-safetynet attestation requires opts.safetyNetRoots -- the Google root(s) to anchor the x5c chain to; this library bundles none (WebAuthn 8.5)");
     }
-    if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+    if (opts.time != null) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
 
     _requireAttShape(att.attStmt, ["ver", "response"], ["ver", "response"]);
     _attRead(att.attStmt, "ver", cbor.read.textString, "a text string");
@@ -783,10 +792,10 @@ var VERIFIERS = intrinsic.assign(intrinsic.create(null), {
     var jwsTrusted = intrinsic.chain(_verifySig(-257, sigBytes, leaf.subjectPublicKeyInfo.bytes,
       intrinsic.bufferFrom(segs[0] + "." + segs[1], "ascii"), _err), function (ok) {
       if (!ok) throw _err("webauthn/verify-failed", "the android-safetynet JWS signature does not verify under the x5c leaf key");
-      chainAt = opts.time !== undefined ? opts.time
+      chainAt = opts.time != null ? opts.time
         : (typeof payload.timestampMs === "number" && intrinsic.isFinite(payload.timestampMs) && payload.timestampMs > 0
           ? new intrinsic.Date(payload.timestampMs) : undefined);
-      return _safetyNetChainTrusted(chain, roots, chainAt);
+      return _safetyNetChainTrusted(chain, roots, chainAt, opts.distrustedKeys);
     });
     return intrinsic.chain(jwsTrusted, function () {
       var res = guard.verdict.of(_result("android-safetynet", "Basic", chain, att), { safetyNet: signals });
@@ -879,7 +888,7 @@ function _safetyNetHostnameOk(leaf) {
   });
 }
 
-function _safetyNetChainTrusted(chain, roots, time) {
+function _safetyNetChainTrusted(chain, roots, time, distrusted) {
   var anchors;
   try {
     anchors = intrinsic.mapList(roots, function (root, i) {
@@ -892,7 +901,7 @@ function _safetyNetChainTrusted(chain, roots, time) {
     });
   } catch (e) { return _promiseReject(_Promise, e); }
   return mds.chainToAnchor(chain, anchors, time === undefined ? new intrinsic.Date() : time,
-    "android-safetynet x5c certificate chain", "webauthn/safetynet-cert-untrusted");
+    "android-safetynet x5c certificate chain", "webauthn/safetynet-cert-untrusted", distrusted);
 }
 
 function _result(fmt, attestationType, chain, att) {
@@ -1015,6 +1024,9 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   allowedAlgorithms -- the COSE algorithms this relying party accepts
  *   metadata          -- a verifyMetadataBlob result; the model's own roots govern
  *   rootCertificates  -- trust anchors you pin, for the models no catalogue lists
+ *   distrustedKeys    -- SHA-256 digests of SubjectPublicKeyInfo DER (64 hex characters
+ *                        or 32 bytes); a listed key on a trust path refuses that path on
+ *                        the metadata, rootCertificates and safetyNetRoots routes
  *   time              -- the instant certificate validity is judged at
  *   tpmPolicy         -- required TPM key properties; refuses a non-TPM attestation
  *   safetyNetRoots / verifySafetyNetJws / requireCtsProfileMatch -- the
@@ -1045,11 +1057,16 @@ function verify(attestationObject, clientDataHash, opts) {
   /** @internal A caller who passes no options gets a record with NO prototype. Defaulted to `{}` it
    *  inherits, so a property installed on `Object.prototype` reads as an option this call never set. */
   opts = opts || intrinsic.create(null);
+  var distrusted;
   try {
     if (!_isPlainObject(opts)) throw _err("webauthn/bad-input", "opts must be an object");
     guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "webauthn/bad-input", "opts has an unknown key ");
     opts = guard.identifier.ownOptions(opts);
-    if (opts.time !== undefined) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+    if (opts.time != null) guard.time.assertValid(opts.time, _err, "webauthn/bad-input", "opts.time");
+    /** @internal Typed here, before any chain is walked, because the walk turns a validation
+     *  rejection into an untrusted verdict, and a malformed list must be reported as the caller's
+     *  input fault on every route. */
+    distrusted = guard.distrust.keys(opts.distrustedKeys, _err, "webauthn/bad-input", "opts.distrustedKeys");
     /** @internal The walk comes from the capture. Each pass of it is a REFUSAL of a mistyped option,
      *  and a mistyped one that survives is read for truthiness later where the rule wants exactly
      *  `true`, so a walk that visits nothing admits `"true"` as the opt-in. */
@@ -1061,7 +1078,7 @@ function verify(attestationObject, clientDataHash, opts) {
   var attBytes, cdh, clientData = null;
   try {
     attBytes = _bytesArg(attestationObject, "attestationObject");
-    var haveJson = opts.clientDataJSON !== undefined, haveHash = clientDataHash !== undefined;
+    var haveJson = opts.clientDataJSON != null, haveHash = clientDataHash !== undefined;
     if (haveJson === haveHash) {
       throw _err("webauthn/bad-input", "verify takes exactly one of clientDataJSON or the clientDataHash argument");
     }
@@ -1075,6 +1092,9 @@ function verify(attestationObject, clientDataHash, opts) {
       });
       cdh = _sha("sha256", cdjBytes);
     } else {
+      /** @internal `expectedTopOrigin: null` states that the ceremony must be unframed, so
+       *  it is an expectation the caller supplied and counts as supplied here too. */
+      // allow:caller-option-presence-tested-against-undefined
       if (opts.expectedChallenge !== undefined || opts.expectedOrigin !== undefined ||
           opts.expectedTopOrigin !== undefined) {
         throw _err("webauthn/bad-input",
@@ -1093,6 +1113,7 @@ function verify(attestationObject, clientDataHash, opts) {
   }
   var verifier = VERIFIERS[att.fmt];
   if (!verifier) return _promiseReject(_Promise, _err("webauthn/unsupported-format", "attestation statement format '" + att.fmt + "' is not supported"));
+  // allow:caller-option-presence-tested-against-undefined -- absence means no TPM policy is applied, so a null must be refused rather than drop it
   if (opts.tpmPolicy !== undefined && !_formatCarries(att, "tpm")) {
     return _promiseReject(_Promise, _err("webauthn/tpm-policy", "opts.tpmPolicy requires a TPM attestation, but this attestation is format '" + att.fmt + "', which carries no TPM public area"));
   }
@@ -1105,6 +1126,7 @@ function verify(attestationObject, clientDataHash, opts) {
     vopts = guard.identifier.ownOptions(opts);
     vopts.rootCertificates = _snapshotRoots(opts.rootCertificates);
     vopts.safetyNetRoots = _snapshotRoots(opts.safetyNetRoots);
+    vopts.distrustedKeys = distrusted;
   } catch (e) { return _promiseReject(_Promise, e); }
   var ranVerifier = intrinsic.chain(_promiseResolve(_Promise, undefined),
     function () { return verifier(att, clientDataHash, vopts); });
@@ -1112,7 +1134,9 @@ function verify(attestationObject, clientDataHash, opts) {
     return guard.verdict.of(res, { clientData: clientData });
   });
   var anchoredRes = intrinsic.chain(withClientData, function (res) {
+      // allow:caller-option-presence-tested-against-undefined -- a trust input: absence falls back to signature-only verification, so a null must be refused rather than skip anchoring
       if (vopts.metadata === undefined) {
+        // allow:caller-option-presence-tested-against-undefined -- a trust input: absence falls back to signature-only verification, so a null must be refused rather than skip anchoring
         if (vopts.rootCertificates !== undefined) return _applyCallerRoots(res, vopts.rootCertificates, vopts);
         var anchored = guard.verdict.of(res, { anchoredTo: _anchoredRoutes(res, null) });
         var sn = _safetyNetAnchored(anchored);
@@ -1127,6 +1151,7 @@ function verify(attestationObject, clientDataHash, opts) {
         function () { return _applyMetadata(res, att, vopts); });
       return intrinsic.chain(applyMd,
         function (out) { return guard.verdict.of(out, { anchoredTo: _anchoredRoutes(out, "metadata") }); }, function (e) {
+          // allow:caller-option-presence-tested-against-undefined -- a trust input: absence falls back to signature-only verification, so a null must be refused rather than skip anchoring
           if (!e || e.code !== "webauthn/metadata-not-found" || vopts.rootCertificates === undefined) throw e;
           return intrinsic.chain(_promiseResolve(_Promise, _applyCallerRoots(res, vopts.rootCertificates, vopts, e.missedPaths)),
             function (withRoots) {
@@ -1186,7 +1211,7 @@ function _applyMetadata(res, att, opts) {
     guard.list.append(applied, { entry: entry, anchors: anchors, identifier: identifier });
     return { anchors: anchors, identifier: identifier };
   }
-  var at = opts.time !== undefined ? opts.time : new intrinsic.Date();
+  var at = opts.time != null ? opts.time : new intrinsic.Date();
   mds.assertFresh(md, at, "the metadata supplied as opts.metadata");
   var governed = [];
   var missed = null;
@@ -1207,9 +1232,9 @@ function _applyMetadata(res, att, opts) {
   var governedAnchored = intrinsic.reduce(governed, function (p, item) {
     return intrinsic.chain(p, function () {
       var g = item.g, info = item.info;
-      var pathAt = opts.time !== undefined ? opts.time : (info.at || at);
+      var pathAt = opts.time != null ? opts.time : (info.at || at);
       return mds.chainToAnchor(_reverse(intrinsic.copyList(info.tp)), g.anchors, pathAt,
-        "attestation trust path for " + g.identifier + " (against the roots its metadata entry registers)");
+        "attestation trust path for " + g.identifier + " (against the roots its metadata entry registers)", undefined, opts.distrustedKeys);
     });
   }, _promiseResolve(_Promise, undefined));
   return intrinsic.chain(governedAnchored,
@@ -1272,6 +1297,9 @@ void constants;
  * @opts
  *   - `rootCertificates` -- REQUIRED. The trust anchors the BLOB's own signing chain
  *     must reach. A certificate, PEM, or DER bytes.
+ *   - `distrustedKeys` -- SHA-256 digests of SubjectPublicKeyInfo DER (64 hex characters
+ *     or 32 bytes). A listed key anywhere on the BLOB's signing chain, the root
+ *     included, refuses the BLOB as `webauthn/metadata-untrusted`.
  *   - `time` -- the instant freshness is judged at. Defaults to now.
  *   - `previousNo` -- the sequence number of the BLOB you already hold. A BLOB whose
  *     `no` is not greater is refused as a rollback.
@@ -1507,6 +1535,10 @@ function parseClientData(bytes, opts) {
     }
     checked.origin = true;
   }
+  /** @internal `null` is a VALUE here, not absence: it states that the ceremony must be
+   *  unframed, which the branch below checks. So presence is asked the one way that keeps
+   *  it, and an option left out is the only form that skips the check. */
+  // allow:caller-option-presence-tested-against-undefined -- see above
   if (opts.expectedTopOrigin !== undefined) {
     var wantTop = opts.expectedTopOrigin;
     var framed = doc.crossOrigin === true;

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.
@@ -959,14 +971,18 @@ function _extensionRow(name) {
   if (oid.isDottedDecimal(name)) return intrinsic.hasOwn(EXTENSION_BY_OID, name) ? EXTENSION_BY_OID[name] : null;
   throw _err("x509/bad-input", "unknown extension " + guard.text.showValue(name) + "; the names spec.extensions takes are accepted, and any other extension is named by its dotted OID with its extnValue pre-encoded");
 }
+/** @internal `stated` is the caller's option, carried here from the door that typed it,
+ *  so absence has the same two forms there and here: a `null` states no criticality and
+ *  takes the row's default, the way an omitted option does. Read as stated, it was
+ *  returned AS the criticality and reached the emitter as a non-boolean. */
 function _extensionCritical(row, opts) {
   var rule = row.rule, stated = opts.critical;
   if (rule.inValue) {
-    if (stated !== undefined) throw _err("x509/bad-input", row.name + " carries its criticality in the value ({ cA, pathLen, critical }), so opts.critical does not apply");
+    if (stated != null) throw _err("x509/bad-input", row.name + " carries its criticality in the value ({ cA, pathLen, critical }), so opts.critical does not apply");
     return null;
   }
-  if (rule.knob) return stated === undefined ? rule.dflt : stated;
-  if (stated !== undefined && stated !== rule.fixed) {
+  if (rule.knob) return stated == null ? rule.dflt : stated;
+  if (stated != null && stated !== rule.fixed) {
     throw _err("x509/bad-input", row.name + " is emitted " + (rule.fixed ? "critical" : "non-critical") + " (" + rule.cite + "), so opts.critical cannot say otherwise");
   }
   return rule.fixed;
@@ -1025,7 +1041,7 @@ function extension(name, value, opts) {
 function _extension(name, value, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "x509/bad-input", "pki.x509.extension options");
   guard.identifier.assertKnownKeys(opts, KNOWN_EXTENSION_OPTS, _err, "x509/bad-input", "pki.x509.extension has an unknown option ");
-  if (opts.critical !== undefined && typeof opts.critical !== "boolean") throw _err("x509/bad-input", "opts.critical must be a boolean");
+  if (opts.critical != null && typeof opts.critical !== "boolean") throw _err("x509/bad-input", "opts.critical must be a boolean");
   if (value === undefined || value === null) throw _err("x509/bad-input", "the extension value is required");
   var row = _extensionRow(name);
   if (row === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "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:114691ca-67be-44e1-9f29-b49116312f56",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-10-12T04:46:50.282Z",
+    "timestamp": "2026-10-21T08:20:31.429Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.9.4",
+      "bom-ref": "@blamejs/pki@0.9.6",
       "type": "application",
       "name": "pki",
-      "version": "0.9.4",
+      "version": "0.9.6",
       "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.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.9.4",
+      "ref": "@blamejs/pki@0.9.6",
       "dependsOn": []
     }
   ]