@blamejs/pki 0.8.54 → 0.8.55

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.8.55 — 2026-10-06
+
+Tell a caller when the path search stopped looking, rather than reporting the chain it had.
+
+### Added
+
+- `pki.path.build` puts `depthLimited: true` on a `{ valid:false }` return when `opts.maxDepth` stopped an expansion that still had candidates waiting. The chain reported alongside it is the best one the search ASSEMBLED, not the best one the pool holds, so a caller treating `valid:false` as a verdict about the certificates should read the field and raise `maxDepth` instead. It is absent from a successful return and from a failing one the search explored to its end, including a chain whose last hop lands exactly on the cap with nothing left to expand: the claim is that the bound truncated the search, not that the search reached it.
+
+### Changed
+
+- `pki.sigstore.verifyBundle` reports `sigstore/chain-incomplete` where it reported `sigstore/chain-invalid`, for a bundle whose Fulcio chain the path search stopped expanding at its depth bound. A rotated CA reissues under one subject name, so a bundle can carry a short branch that assembles and fails beside a long one that reaches an anchor past the bound; the short branch's failure was being published as the verdict on the bundle. The candidate budget already answered this way, and the two bounds now agree. Nothing about a chain that was explored to its end changed: a bundle whose assembled path genuinely fails validation is still `sigstore/chain-invalid`.
+- A reached bound stays a bound rather than becoming a refusal: a bounded depth-first search visits equal-scoring candidates in the order they arrive, so a bundle large enough to exhaust the expansion ceiling can still depend on its own ordering. That is a property of bounding the search at all. Raise `maxDepth` and `maxCandidatesConsidered` for a pool whose shape needs more of the graph walked.
+- `depthLimited` reports a candidate the cap kept the search from expanding, and nothing weaker. A candidate already on the chain is one the cycle check would skip at any depth, so it is not counted: counting it would report a truncated search where the search was exhausted, and turn a chain this toolkit refuses into one it claims it never finished reading. Two cases it does not report, both of which leave the older behavior in place rather than overstating: a chain whose last hop lands on the cap with nothing left to match, and a cap that also suppressed an Authority Information Access fetch for the certificate at that hop. The second needs the fetch's own URL eligibility answered to be certain a fetch was available, so it is left unclaimed rather than guessed at.
+
+### Fixed
+
+- `pki.ct` and `pki.path.build` take their declared options through one shared snapshot instead of two copies of the same loop. Both read every declared name once, before anything derives from one, and both keep an omitted option OMITTED rather than recording it as a name holding `undefined`, which is what lets an absent `transport` still mean "open the connection yourself, under the pinned anchors". Behavior is unchanged at both verbs; what the shared door adds is that the next caller to copy an options bag by hand is caught before it ships.
+
 ## v0.8.54 — 2026-10-06
 
 Refuse the universal tags X.680 assigns to no type, and tell a caller which those are.

package/lib/ct.js

@@ -1353,18 +1353,16 @@ function _clientDoor(opts, keyName) {
 }
 
 /** @internal Every DECLARED option the bag can answer, read once into a record of plain values, before
- *  anything derives from one. `in` is used rather than an enumeration because the door accepts an option
- *  supplied through a caller's defaults object, and an enumeration omits an inherited FUNCTION member,
- *  which silently dropped a `transport` and fell through to opening a real connection. It consults the
- *  prototype chain exactly as the direct reads it replaces did, so it carries no new exposure, and
- *  absence survives: a name the bag cannot answer is left out rather than materialized as `undefined`,
- *  which a guard that tells absent from present-and-undefined depends on. */
+ *  anything derives from one. The presence-preserving snapshot is the one this module needs: absence
+ *  survives, so a name the bag cannot answer is left out rather than materialized as `undefined`,
+ *  which is what lets an absent `transport` still mean "open the connection yourself, under the
+ *  pinned anchors". It consults the prototype chain exactly as the direct reads it replaces did,
+ *  because the door accepts an option supplied through a caller's defaults object and an enumeration
+ *  omits an inherited FUNCTION member, which silently dropped a `transport` and fell through to
+ *  opening a real connection. */
+// @guard-via guard.identifier.snapshotPresentOptions
 function _takeTopLevel(bag, known) {
-  var o = intrinsic.create(null);
-  intrinsic.forEach(intrinsic.keys(known), function (k) {
-    if (k in bag) o[k] = bag[k];
-  });
-  return o;
+  return guard.identifier.snapshotPresentOptions(bag, known);
 }
 
 /** @internal The two values a verdict rests on, made IMMUNE rather than merely taken. Holding a

package/lib/guard-identifier.js

@@ -101,6 +101,28 @@ function snapshotOptions(obj, known) {
   return out;
 }
 
+/** @internal The same one-read capture, for a caller that tells an ABSENT option from one present
+ *  and holding `undefined`. `snapshotOptions` materializes every declared name, which is correct for
+ *  a caller testing `!== undefined` and wrong for one testing presence: an omitted option becomes an
+ *  own key, and a presence-based guard then sees an option the caller never passed. Measured, a bag
+ *  omitting `transport` is ACCEPTED by `assertCallableOption` and REFUSED after `snapshotOptions`,
+ *  because the materialized `undefined` is a transport that is not callable.
+ *
+ *  Presence consults the prototype chain, because a caller supplying options through a defaults
+ *  object is supplying them, and an enumeration omits an inherited FUNCTION member: that is how a
+ *  copy once dropped a `transport` and fell through to opening a real connection where the caller
+ *  had passed a fake one. The VALUE is still read once per name, which is what the snapshot is for.
+ *  The two live side by side rather than behind a flag so a caller chooses between them knowingly. */
+// @enforced-by guard-shape-reinlined
+// @guard-shape if \(\w+ in \w+\) \w+\[\w+\] = \w+\[\w+\];
+function snapshotPresentOptions(obj, known) {
+  var out = _create(null);
+  if (obj === null || obj === undefined) return out;
+  var o = _Object(obj);
+  _forEach(_getOwnPropertyNames(known), function (k) { if (k in o) out[k] = o[k]; });
+  return out;
+}
+
 /** @internal The option names a bag carries, read the way assertKnownKeys read them: every own
  *  string key, whatever its descriptor says. Object.keys reports only the enumerable ones, so an
  *  option written with `enumerable: false` clears the door and then vanishes from the read.
@@ -656,6 +678,7 @@ module.exports = intrinsic.freeze({
   optionsObject: optionsObject,
   refuseAccessorFields: refuseAccessorFields,
   snapshotOptions: snapshotOptions,
+  snapshotPresentOptions: snapshotPresentOptions,
   optionNames: optionNames,
   ownOptions: ownOptions,
   pickSettings: pickSettings,

package/lib/path-validate.js

@@ -3301,7 +3301,7 @@ async function _fetchAiaIssuers(current, aia) {
 
 /**
  * @primitive  pki.path.build
- * @signature  pki.path.build(leaf, opts) -> Promise<{ valid, path, trustAnchor, result, candidatesConsidered, aiaFetches }>
+ * @signature  pki.path.build(leaf, opts) -> Promise<{ valid, path, trustAnchor, result, candidatesConsidered, aiaFetches, depthLimited? }>
  * @since       0.3.7
  * @status      stable
  * @spec        RFC 4158, RFC 5280
@@ -3347,7 +3347,12 @@ async function _fetchAiaIssuers(current, aia) {
  * `validate` consumes (anchor-proximal first, leaf last, the anchor excluded). Fail-closed: bad
  * options throw `path/bad-input`; no chain to any anchor throws `path/no-path`; chains that
  * assemble but none validate return `{ valid:false }` with the best failing `validate` result;
- * the search bound throws `path/build-limit`. By default `build` is OFFLINE (zero network), so supply
+ * the search bound throws `path/build-limit`. A `{ valid:false }` return carries
+ * `depthLimited: true` when the depth cap stopped an expansion that still had candidates waiting,
+ * which means the chain reported is the best one ASSEMBLED rather than the best one that exists: a
+ * caller that treats `valid:false` as a verdict about the certificates should read that field and
+ * raise `opts.maxDepth` instead. It is absent on a successful return and on a failing one the
+ * search explored to its end. By default `build` is OFFLINE (zero network), so supply
  * intermediates in `opts.candidates`. Set `opts.fetchAia: true` to opt in to fetching a MISSING intermediate
  * from a certificate's Authority Information Access `caIssuers` URL (RFC 5280 sec. 4.2.2.1) over
  * `pki.transport`: the fetch triggers only on a pool miss, every fetched certificate is UNTRUSTED pool material
@@ -3511,14 +3516,24 @@ async function build(leaf, opts) {
 
   var BUILD_ONLY_OPT = { candidates: 1, intermediates: 1, trustAnchors: 1, maxDepth: 1, maxCandidatesConsidered: 1, validate: 1,
     fetchAia: 1, transport: 1, tls: 1, maxAiaFetches: 1, maxAiaPerCert: 1, aiaTimeout: 1, maxResponseBytes: 1 };
-  var forwarded = Object.create(null);
+  /** @internal The names this door forwards by VALUE: every validate option that is not consumed by
+   * the builder and not one of the switches typed above. Absence has to survive the copy, so the
+   * presence-preserving snapshot is the one to take: an option the caller omitted stays omitted
+   * rather than arriving at `validate` as a name holding `undefined`.
+   * @guard-via guard.identifier.snapshotPresentOptions */
+  var FORWARD_BY_VALUE = intrinsic.create(null);
   intrinsic.forEach(intrinsic.keys(_VALIDATE_OPTS), function (k) {
-    if (intrinsic.hasOwn(BUILD_ONLY_OPT, k)) return;
-    /** @internal A switch this door typed is forwarded as the value it typed. Reading it off the
-     * options object again would ask a second time, and normalizing an anchor between the two runs
-     * caller accessors, so the value `validate` is handed need not be the one that passed here. */
-    if (intrinsic.hasOwn(forwardedSwitches, k)) { forwarded[k] = forwardedSwitches[k]; return; }
-    if (k in opts) forwarded[k] = opts[k];
+    if (intrinsic.hasOwn(BUILD_ONLY_OPT, k) || intrinsic.hasOwn(forwardedSwitches, k)) return;
+    FORWARD_BY_VALUE[k] = 1;
+  });
+  var forwarded = guard.identifier.snapshotPresentOptions(opts, FORWARD_BY_VALUE);
+  /** @internal A switch this door typed is forwarded as the value it typed, overlaid after the copy.
+   * Reading it off the options object again would ask a second time, and normalizing an anchor
+   * between the two runs caller accessors, so the value `validate` is handed need not be the one that
+   * passed here. All four are validate options and none is build-only, so the overlay adds no name
+   * the loop above would have skipped. */
+  intrinsic.forEach(intrinsic.keys(forwardedSwitches), function (k) {
+    forwarded[k] = forwardedSwitches[k];
   });
   if (buildPermRaw != null) forwarded.initialPermittedSubtrees = buildPermSeeds;
   if (buildExclRaw != null) forwarded.initialExcludedSubtrees = buildExclSeeds;
@@ -3533,6 +3548,10 @@ async function build(leaf, opts) {
   var considered = 0;
   var anyChainAssembled = false;
   var bestFail = null;
+  /** @internal Whether the depth bound stopped an expansion that had candidates waiting. A reached
+   * bound is "stopped looking", not "the chain is bad", and the two left this verb returning the
+   * same `valid:false`. */
+  var depthStopped = false;
   var success = null;
   _assertUserInitialPolicySet(opts.userInitialPolicySet, "build");
   var uipsDistinct = null, selectByPolicy = false;
@@ -3570,7 +3589,6 @@ async function build(leaf, opts) {
           guard.list.append(accepted, racc);
         } else if (!bestFail) bestFail = { path: rpath, trustAnchor: rframe.anchor, result: rres };
       }
-      if (rframe.hop >= maxDepth) continue;
       var rscored = [];
       for (var rpi = 0; rpi < pool.length; rpi++) {
         if (nameMatchSoft(pool[rpi].subject.rdns, rframe.anchor.name.rdns) &&
@@ -3579,6 +3597,13 @@ async function build(leaf, opts) {
           guard.list.append(rscored, { cand: pool[rpi], score: scoreCandidateReverse(pool[rpi], frontierCert, leafCert, opts.time) });
         }
       }
+      /** @internal The anchor-first search answers the same question the forward one does, for the
+       * same reason: candidates scored before the bound is consulted, so reaching it can say whether
+       * it stopped anything. */
+      if (rframe.hop >= maxDepth) {
+        if (_anyExpandable(rscored, rframe)) depthStopped = true;
+        continue;
+      }
       considered += _pushCandidates(rframe, rscored, rstack, counter, true);
     }
   } else {
@@ -3635,7 +3660,7 @@ async function build(leaf, opts) {
         guard.list.append(accepted, acc);
       } else if (!bestFail) bestFail = { path: frame.chain.slice(), trustAnchor: anchors[ai], result: res };
     }
-    if (success || frame.hop >= maxDepth) continue;
+    if (success) continue;
 
     var childAki = childAkiKeyId(current);
     var scored = [];
@@ -3645,6 +3670,16 @@ async function build(leaf, opts) {
           ineligible: _forwardPathLenIneligible(pool[pi], frame.chain) });
       }
     }
+    /** @internal The candidates are scored BEFORE the depth bound is consulted, so reaching the
+     * bound can say whether it stopped anything. A chain whose last hop lands on the bound with
+     * nothing left to expand was explored to its end, and a chain with candidates waiting was
+     * TRUNCATED: the two produce the same `valid:false` otherwise, and a caller reading that cannot
+     * tell a refused chain from one the search never assembled. Nothing is pushed either way, so the
+     * reorder costs one pool pass on a frame at the bound and changes no outcome. */
+    if (frame.hop >= maxDepth) {
+      if (_anyExpandable(scored, frame)) depthStopped = true;
+      continue;
+    }
     if (aiaCtx && frame.hop < maxDepth && aiaCtx.fetches < aiaCtx.maxFetches) {
       guard.list.append(deferredAia, { chain: frame.chain, hop: frame.hop, keys: frame.keys, poolMark: pool.length, seq: deferSeq, fetched: false });
       deferSeq += 1;
@@ -3666,11 +3701,29 @@ async function build(leaf, opts) {
     return guard.verdict.of({ path: success.path, trustAnchor: success.trustAnchor, candidatesConsidered: considered, aiaFetches: aiaFetches });
   }
   if (anyChainAssembled) {
-    return guard.verdict.of({ valid: false, path: bestFail.path, trustAnchor: bestFail.trustAnchor, result: bestFail.result, candidatesConsidered: considered, aiaFetches: aiaFetches });
+    /** @internal `depthLimited` is carried only on the FAILING return, and only when the bound
+     * stopped an expansion. On a success the bound hid nothing that mattered, and a caller reading
+     * the field on every verdict would have to ask what it meant for a valid path. */
+    var failed = { valid: false, path: bestFail.path, trustAnchor: bestFail.trustAnchor, result: bestFail.result, candidatesConsidered: considered, aiaFetches: aiaFetches };
+    if (depthStopped) failed.depthLimited = true;
+    return guard.verdict.of(failed);
   }
   throw E("path/no-path", "build: no certification path from the leaf to any configured trust anchor could be assembled");
 }
 
+/** @internal Whether raising the depth cap could reach anything through these candidates. A
+ * candidate already on the chain is skipped by `_pushCandidates` on the identity key, so a deeper
+ * search would skip it too: counting it reports a truncated search where the search is exhausted,
+ * which turns a chain this toolkit refuses into one it says it never finished reading. The identity
+ * key and the frame's visited set are the same two the push uses, so the two cannot disagree about
+ * which candidate is reachable. */
+function _anyExpandable(scored, frame) {
+  for (var i = 0; i < scored.length; i++) {
+    if (!intrinsic.setHas(frame.keys, identityKey(scored[i].cand))) return true;
+  }
+  return false;
+}
+
 /** @internal The fetching checker composes the two gates below, so it loads after this module
  * rather than beside it. The require sits in the call so the cycle resolves at first use, which is
  * the documented reason an inline require is permitted. */

package/lib/sigstore.js

@@ -1417,8 +1417,11 @@ async function _verifyChain(leaf, chainDers, roots, timeMs) {
    * reported `chain-invalid`. `build` ranks candidates by the RFC 4158 sec. 3.5 heuristics, the key
    * identifier among them, EXCLUDING none, and bounds the search by total candidate expansions rather
    * than by how many paths it has collected, so a later candidate stays reachable and an exhausted
-   * budget is reported as `path/build-limit` rather than as a verdict about the chain. Every assembled
-   * path still flows through `pki.path.validate`, so this delegates the search and duplicates no check.
+   * budget is reported as `path/build-limit` rather than as a verdict about the chain, and a depth bound
+   * that stopped an expansion as `depthLimited` on the failing return. Both reach the incomplete code
+   * below, because a bound the search reached says nothing about the certificates it never read. Every
+   * assembled path still flows through `pki.path.validate`, so this delegates the search and duplicates
+   * no check.
    * The anchors go into the pool as well as the trust store, because a cross-signed root appears in a
    * chain as an intermediate under another anchor. */
   var anchorTuples = _map(inWindow, function (r) {
@@ -1462,6 +1465,14 @@ async function _verifyChain(leaf, chainDers, roots, timeMs) {
     throw _err("sigstore/chain-invalid", "the Fulcio certificate chain failed validation: " + e.message, e);
   }
   if (!built.valid) {
+    /** @internal The third outcome that means "stopped looking". `build` reports `depthLimited` when
+     * its depth bound stopped an expansion that had candidates waiting, so the chain it hands back
+     * is the best one it ASSEMBLED rather than the best one that exists. Reporting that as invalid
+     * denies a bundle whose path the search never reached, which is the same denial the candidate
+     * bound above avoids, so it answers with the same incomplete code. */
+    if (built.depthLimited) {
+      throw _err("sigstore/chain-incomplete", "no chain to a caller-supplied Fulcio anchor was established before the path search reached its depth bound");
+    }
     throw _err("sigstore/chain-invalid", "the Fulcio certificate chain is not valid as of the log time");
   }
   /** @internal `path` is anchor-proximal first and leaf last with the anchor excluded, so the certificate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.8.54",
+  "version": "0.8.55",
   "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:4fbfd882-9aa0-491d-b309-378e286e0976",
+  "serialNumber": "urn:uuid:f7650379-6444-462e-bd4b-7cfbdc879bc7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-10-06T03:34:15.912Z",
+    "timestamp": "2026-10-06T04:32:24.064Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.8.54",
+      "bom-ref": "@blamejs/pki@0.8.55",
       "type": "application",
       "name": "pki",
-      "version": "0.8.54",
+      "version": "0.8.55",
       "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.8.54",
+      "purl": "pkg:npm/%40blamejs/pki@0.8.55",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.8.54",
+      "ref": "@blamejs/pki@0.8.55",
       "dependsOn": []
     }
   ]