@blamejs/pki 0.9.5 → 0.9.6

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

@@ -971,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;
@@ -1037,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.5",
+  "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",

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:e1f0a0ad-8621-4fc9-a62a-62df66fe4d21",
+  "serialNumber": "urn:uuid:114691ca-67be-44e1-9f29-b49116312f56",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-10-12T15:58:58.900Z",
+    "timestamp": "2026-10-21T08:20:31.429Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.9.5",
+      "bom-ref": "@blamejs/pki@0.9.6",
       "type": "application",
       "name": "pki",
-      "version": "0.9.5",
+      "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.5",
+      "purl": "pkg:npm/%40blamejs/pki@0.9.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.9.5",
+      "ref": "@blamejs/pki@0.9.6",
       "dependsOn": []
     }
   ]