@blamejs/pki 0.6.37 → 0.6.38

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.6.38 — 2026-09-05
+
+A trust anchor can name the namespace its root is trusted for, and pki.path.validate enforces it as the initial name-constraint state.
+
+### Added
+
+- A trust anchor passed to pki.path.validate or pki.path.build may carry nameConstraints: { permitted, excluded }, each an array of { tag, base } subtrees. They seed the RFC 5280 section 6.1.1(h)(i) initial permitted and excluded state, so a root a program trusts only for a namespace enforces that namespace even though its certificate states no nameConstraints extension. The anchor's subtrees intersect with an intermediate's own extension and with opts.initialPermittedSubtrees; excluded subtrees are a union.
+- The pki.path.validate verdict reports anchorConstraints.nameConstraintsApplied, so a stored verdict distinguishes an anchor that named a namespace from one that did not, alongside the distrustAfterApplied and purposeTrustApplied it already carries.
+
+### Fixed
+
+- pki.path.validate and pki.path.build copy a directoryName subtree base and snapshot an iPAddress one before validating, and read opts.initialPermittedSubtrees and opts.initialExcludedSubtrees once rather than again for each trust anchor or candidate path tried. A caller mutating its own subtree list, entry or base while the path is still verifying signatures no longer changes the namespace the validation enforces; the subtrees that bind are the ones read at entry.
+- A directoryName subtree base whose rdns is an accessor rather than a data property is refused. Its value was read once to check its shape and again to copy it, so an accessor could answer with a restrictive name the first time and an empty one the second, and an empty directoryName constraint matches every name.
+- A subtree list that is a Proxy, that is sparse, or whose entries are accessors is refused, on a trust anchor and on opts.initialPermittedSubtrees and opts.initialExcludedSubtrees alike. Such a list answers its own length and index reads, so it could hold a restrictive subtree while reporting none and leave the namespace unenforced. A directoryName subtree is built from property descriptors alone, so nothing the caller supplies runs while the namespace is read: an accessor, own or inherited, is refused rather than invoked. It is a relative-name sequence of attribute lists and nothing deeper, so an array nested past that, including one that refers to itself, is a typed refusal, as is a hole, an entry the array does not own, an attribute that is not an object, or one lacking its own type and value. Each of those refusals is a configuration error reported wherever the anchor sits among several, rather than a name mismatch a different anchor could mask.
+- A parsed certificate passed as a trust anchor is refused if it carries nameConstraints, the way one carrying purposes or distrustAfter already is. A certificate anchor cannot hold that metadata, so accepting it would have dropped the namespace and validated a leaf the anchor was meant to exclude.
+- An anchor whose nameConstraints names a field other than permitted or excluded is refused rather than read as unconstrained, and its subtrees are checked while the anchor is normalized, so a malformed one is refused wherever that anchor sits among several rather than only once it is reached.
+
 ## v0.6.37 — 2026-09-05
 
 A natively signed C509 certificate is refused when it writes an extension in the generic OID form that the registry can carry as an identifier.

package/lib/path-validate.js

@@ -553,19 +553,61 @@ function isSubtreeBaseValid(tag, base) {
 
 function checkedSubtreeSeeds(list, optName) {
   if (list === undefined || list === null) return [];
-  if (!intrinsic.isArray(list)) throw E("path/bad-input", "validate: opts." + optName + " must be an array of { tag, base } subtree entries");
-  return list.map(function (st) {
-    if (!st || typeof st !== "object" || !Number.isInteger(st.tag) || st.tag < 0 || st.tag > 8) {
-      throw E("path/bad-input", "validate: opts." + optName + " entries must be { tag: <GeneralName tag number 0..8>, base: <that form's constraint value> }");
+  if (!intrinsic.isArray(list) || intrinsic.types.isProxy(list)) throw E("path/bad-input", "validate: opts." + optName + " must be a plain array of { tag, base } subtree entries");
+  for (var li = 0; li < list.length; li++) {
+    var ld = intrinsic.getOwnPropertyDescriptor(list, li);
+    if (ld === undefined) throw E("path/bad-input", "validate: opts." + optName + " must not be a sparse array; index " + li + " is a hole");
+    if (!intrinsic.hasOwn(ld, "value")) throw E("path/bad-input", "validate: opts." + optName + " entry " + li + " must be a data property, not an accessor");
+  }
+  /** @internal Built with a plain loop into a fresh array: Array.prototype.map consults the caller
+   * array's constructor and Symbol.species, which is more caller code running mid-copy. */
+  var seedsOut = [];
+  for (var si = 0; si < list.length; si++) {
+    intrinsic.push(seedsOut, (function (st) {
+    var shapeMsg = "validate: opts." + optName + " entries must be { tag: <GeneralName tag number 0..8>, base: <that form's constraint value> }";
+    if (!st || typeof st !== "object" || intrinsic.types.isProxy(st)) throw E("path/bad-input", shapeMsg);
+    /** @internal Read tag and base once each, from their own data properties: an accessor could
+     * answer with a restrictive value to a check and a permissive one to the copy. */
+    var tagD = intrinsic.getOwnPropertyDescriptor(st, "tag");
+    var baseD = intrinsic.getOwnPropertyDescriptor(st, "base");
+    if (tagD !== undefined && !intrinsic.hasOwn(tagD, "value")) throw E("path/bad-input", "validate: opts." + optName + " entry tag must be a data property, not an accessor");
+    if (baseD !== undefined && !intrinsic.hasOwn(baseD, "value")) throw E("path/bad-input", "validate: opts." + optName + " entry base must be a data property, not an accessor");
+    var tag = tagD === undefined ? undefined : tagD.value;
+    var base = baseD === undefined ? undefined : baseD.value;
+    if (!Number.isInteger(tag) || tag < 0 || tag > 8) throw E("path/bad-input", shapeMsg);
+    if (tag === 7 && guard.bytes.isByteSource(base)) {
+      base = guard.bytes.snapshotSource(base, PathError, "path/bad-input", "an iPAddress subtree base");
     }
-    var base = (st.tag === 7 && guard.bytes.isByteSource(st.base))
-      ? guard.bytes.snapshotSource(st.base, PathError, "path/bad-input", "an iPAddress subtree base")
-      : st.base;
-    if (!isSubtreeBaseValid(st.tag, base)) {
-      throw E("path/bad-input", "validate: opts." + optName + " entries must be { tag: <GeneralName tag number 0..8>, base: <that form's constraint value> }");
+    if (tag === 4 && base !== null && typeof base === "object") {
+      var seedRdns = _capturedRdns(base, "validate: opts." + optName);
+      if (seedRdns !== undefined) {
+        var dnCopy = {};
+        intrinsic.defineProperty(dnCopy, "rdns", { value: seedRdns, enumerable: true, configurable: true, writable: true });
+        base = dnCopy;
+      }
     }
-    return { tag: st.tag, base: base };
-  });
+    if (!isSubtreeBaseValid(tag, base)) throw E("path/bad-input", shapeMsg);
+    return { tag: tag, base: base };
+    })(intrinsic.getOwnPropertyDescriptor(list, si).value));
+  }
+  return seedsOut;
+}
+
+/**
+ * @internal RFC 5280 sec. 6.1.1(h)(i): the anchor's own permitted/excluded subtrees, the way a root
+ * program restricts a root to a namespace its certificate does not state. Validated through the same
+ * entry-point checker the caller's seeds use, so a mis-shaped subtree is refused rather than dropped.
+ */
+function _anchorSubtreeSeeds(anchor) {
+  var nc = anchor.nameConstraints;
+  if (nc === undefined || nc === null) return { permitted: [], excluded: [] };
+  if (typeof nc !== "object" || intrinsic.isArray(nc)) {
+    throw E("path/bad-input", "validate: a trustAnchor nameConstraints must be a { permitted, excluded } object of { tag, base } subtree entries");
+  }
+  return {
+    permitted: checkedSubtreeSeeds(nc.permitted, "trustAnchors[].nameConstraints.permitted"),
+    excluded: checkedSubtreeSeeds(nc.excluded, "trustAnchors[].nameConstraints.excluded"),
+  };
 }
 
 function initialize(certs, params, seeds, anchor) {
@@ -574,7 +616,7 @@ function initialize(certs, params, seeds, anchor) {
     validPolicyTree: rootNode(),
     policyNodeCount: 1,
     maxPolicyNodes: params.maxPolicyNodes !== undefined ? params.maxPolicyNodes : constants.LIMITS.PATH_MAX_POLICY_NODES,
-    permittedGenerations: seeds.permitted.length ? [seeds.permitted] : [],
+    permittedGenerations: intrinsic.filter(seeds.permittedGenerations, function (g) { return g.length > 0; }),
     excludedSubtrees: seeds.excluded,
     explicitPolicy: params.initialExplicitPolicy ? 0 : n + 1,
     inhibitAnyPolicy: params.initialAnyPolicyInhibit ? 0 : n + 1,
@@ -867,10 +909,21 @@ function validateCriticalExtensionStructure(cert) {
  *
  * `anchorConstraints` reports what the anchor's own trust metadata decided:
  * the `checkedPurpose` it was judged under, and whether the `distrustAfter`
- * date and the `purposes` delegator map each applied. That metadata is keyed BY
- * key purpose, so an anchor carrying it while `opts.checkPurpose` is absent is a
- * configuration fault (`path/bad-input`). A silently inert constraint would let
- * a root distrusted years ago quietly validate a current leaf.
+ * date, the `purposes` delegator map and the `nameConstraints` namespace each
+ * applied. The purpose-keyed metadata is keyed BY key purpose, so an anchor
+ * carrying it while `opts.checkPurpose` is absent is a configuration fault
+ * (`path/bad-input`). A silently inert constraint would let a root distrusted
+ * years ago quietly validate a current leaf.
+ *
+ * An anchor may also carry `nameConstraints`, a `{ permitted, excluded }` pair
+ * of `{ tag, base }` subtrees naming the namespace that root is trusted for.
+ * A root program restricts a root this way when the restriction appears in no
+ * `nameConstraints` extension the root certificate carries. The subtrees become
+ * the RFC 5280 sec. 6.1.1(h)(i) initial permitted and excluded state, so an
+ * intermediate's own `nameConstraints` extension intersects with them and a leaf
+ * must satisfy both. They are a separate generation from
+ * `opts.initialPermittedSubtrees`, so those two intersect as well. A mis-shaped
+ * subtree is refused with `path/bad-input` rather than left inert.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -938,17 +991,35 @@ async function validate(path, opts) {
   var certs = path.map(function (c, ci) { return coerceCert(c, "validate: path[" + ci + "]"); });
   var n = certs.length;
   if (n < 1) throw E("path/empty-path", "validate: the certification path is empty");
+  /** @internal Captured before any anchor is normalized: an anchor field may be an accessor, and
+   * that getter runs caller code which could otherwise clear these lists first. */
+  var callerPermitted = checkedSubtreeSeeds(opts.initialPermittedSubtrees, "initialPermittedSubtrees");
+  var callerExcluded = checkedSubtreeSeeds(opts.initialExcludedSubtrees, "initialExcludedSubtrees");
   var rawAnchors = opts.trustAnchors;
   var anchorList = intrinsic.isArray(rawAnchors) ? rawAnchors : [rawAnchors];
   if (rawAnchors == null || anchorList.length === 0) throw E("path/bad-input", "validate: trustAnchors is required (a single anchor or a non-empty array of anchors)");
+  /** @internal Read the caller's list once here, whatever its length, so neither branch below reads
+   * one of its indices twice. */
+  if (intrinsic.isArray(rawAnchors)) anchorList = _ownAnchorEntries(rawAnchors, "validate");
   if (anchorList.length > 1) {
+    var anchorEntries = anchorList;
+    var preNc = _precaptureAnchorNameConstraints(anchorEntries, "validate");
     var tuples = [];
-    for (var ti = 0; ti < anchorList.length; ti++) { tuples[ti] = toAnchor(anchorList[ti], "validate"); }
+    for (var ti = 0; ti < anchorEntries.length; ti++) {
+      tuples[ti] = toAnchor(anchorEntries[ti], "validate");
+      if (preNc[ti] !== undefined) intrinsic.defineProperty(tuples[ti], "nameConstraints", { value: preNc[ti], enumerable: true, configurable: true, writable: true });
+    }
+    /** @internal Each anchor is a separate attempt and the later ones run after an await, so the
+     * caller's own subtree lists are read once here rather than again per attempt. */
+    var permRawOnce = opts.initialPermittedSubtrees;
+    var exclRawOnce = opts.initialExcludedSubtrees;
     var singleOpts = function (a) {
       var keys = intrinsic.ownKeys(opts);
       var o = {};
       for (var ki = 0; ki < keys.length; ki++) { o[keys[ki]] = opts[keys[ki]]; }
       o.trustAnchors = a;
+      if (permRawOnce != null) o.initialPermittedSubtrees = callerPermitted;
+      if (exclRawOnce != null) o.initialExcludedSubtrees = callerExcluded;
       return o;
     };
     var lastMatched = null, anyMatched = false;
@@ -965,10 +1036,12 @@ async function validate(path, opts) {
   guard.time.assertValid(opts.time, E, "path/bad-input", "validate: opts.time (the always-on validity-window check date)");
   guard.limits.cap(opts.maxPolicyNodes, "validate: opts.maxPolicyNodes", undefined, { E: E, code: "path/bad-input", min: 1 });
   _assertUserInitialPolicySet(opts.userInitialPolicySet, "validate");
+  var anchorNc = _anchorSubtreeSeeds(anchor);
   var seeds = {
-    permitted: checkedSubtreeSeeds(opts.initialPermittedSubtrees, "initialPermittedSubtrees"),
-    excluded: checkedSubtreeSeeds(opts.initialExcludedSubtrees, "initialExcludedSubtrees"),
+    permittedGenerations: [callerPermitted, anchorNc.permitted],
+    excluded: intrinsic.concat(callerExcluded, anchorNc.excluded),
   };
+  var anchorNameConstraintsApplied = anchorNc.permitted.length > 0 || anchorNc.excluded.length > 0;
   var purposeOpts = resolvePurposeOpts(opts);
   var requiredEku = purposeOpts.requiredEku;
   var checkPurpose = purposeOpts.checkPurpose;
@@ -1158,6 +1231,7 @@ async function validate(path, opts) {
       checkedPurpose: checkPurpose || null,
       distrustAfterApplied: anchorDistrustApplied,
       purposeTrustApplied: anchorPurposeApplied,
+      nameConstraintsApplied: anchorNameConstraintsApplied,
     },
     path: certs,
     results: state.results,
@@ -1903,6 +1977,198 @@ function _captureOwnData(entry, key) {
   return (d && intrinsic.hasOwn(d, "value")) ? d.value : undefined;
 }
 
+/**
+ * @internal Copy the anchor's subtree lists getter-free, so a caller mutating the entry afterwards
+ * cannot widen the namespace the validation already resolved.
+ */
+/**
+ * @internal Read a directoryName base's `rdns` once, from its own data property. Reading it twice,
+ * to test its shape and then to copy it, lets an accessor answer differently each time and hand the
+ * validation an empty DN, which matches every name.
+ */
+var _ATV_KEYS = ["type", "value", "name"];
+/**
+ * @internal Build the directoryName's own copy from property descriptors alone, so no caller code
+ * runs while the namespace is read: a getter, own or inherited, could clear another part of the
+ * namespace before it is captured. A directoryName is a relative-name sequence of attribute lists
+ * and nothing deeper, so exactly those levels are walked and a self-referencing array is refused
+ * rather than followed.
+ */
+function _copyDnRdns(rdns, who) {
+  _assertPlainDnRdns(rdns, who);
+  var out = [];
+  for (var i = 0; i < rdns.length; i++) {
+    var rd = intrinsic.getOwnPropertyDescriptor(rdns, i);
+    if (rd === undefined) throw E("path/bad-input", who + " index " + i + " is a hole or is inherited; every entry must be its own");
+    var rdn = rd.value;
+    if (!intrinsic.isArray(rdn)) throw E("path/bad-input", who + "[" + i + "] must be an array of attributes");
+    var rdnOut = [];
+    for (var j = 0; j < rdn.length; j++) {
+      var ad = intrinsic.getOwnPropertyDescriptor(rdn, j);
+      if (ad === undefined) throw E("path/bad-input", who + "[" + i + "] index " + j + " is a hole or is inherited; every entry must be its own");
+      var atv = ad.value;
+      if (atv === null || typeof atv !== "object") throw E("path/bad-input", who + "[" + i + "][" + j + "] must be an attribute object carrying a type and a value");
+      var atvOut = {};
+      for (var k = 0; k < _ATV_KEYS.length; k++) {
+        var fd = intrinsic.getOwnPropertyDescriptor(atv, _ATV_KEYS[k]);
+        if (fd === undefined) continue;
+        intrinsic.defineProperty(atvOut, _ATV_KEYS[k], { value: fd.value, enumerable: true, configurable: true, writable: true });
+      }
+      if (!intrinsic.hasOwn(atvOut, "type") || !intrinsic.hasOwn(atvOut, "value")) {
+        throw E("path/bad-input", who + "[" + i + "][" + j + "] must carry its type and value as own data properties");
+      }
+      intrinsic.push(rdnOut, atvOut);
+    }
+    intrinsic.push(out, rdnOut);
+  }
+  return out;
+}
+/**
+ * @internal The shape check the copy above relies on: a Proxy answers its own reads and an accessor
+ * runs caller code, so either one at any level of the directoryName is refused before it is copied.
+ */
+function _assertPlainDnRdns(rdns, who) {
+  if (intrinsic.types.isProxy(rdns)) throw E("path/bad-input", who + " must be a plain array, not a Proxy");
+  for (var i = 0; i < rdns.length; i++) {
+    var rd = intrinsic.getOwnPropertyDescriptor(rdns, i);
+    if (rd === undefined) continue;
+    if (!intrinsic.hasOwn(rd, "value")) throw E("path/bad-input", who + " entry " + i + " must be a data property, not an accessor");
+    var rdn = rd.value;
+    if (!intrinsic.isArray(rdn)) continue;
+    if (intrinsic.types.isProxy(rdn)) throw E("path/bad-input", who + "[" + i + "] must be a plain array, not a Proxy");
+    for (var j = 0; j < rdn.length; j++) {
+      var ad = intrinsic.getOwnPropertyDescriptor(rdn, j);
+      if (ad === undefined) continue;
+      if (!intrinsic.hasOwn(ad, "value")) throw E("path/bad-input", who + "[" + i + "] entry " + j + " must be a data property, not an accessor");
+      var atv = ad.value;
+      if (atv === null || typeof atv !== "object") continue;
+      if (intrinsic.types.isProxy(atv)) throw E("path/bad-input", who + "[" + i + "][" + j + "] must not be a Proxy");
+      if (intrinsic.isArray(atv)) throw E("path/bad-input", who + "[" + i + "][" + j + "] must be an attribute object, not an array");
+      for (var k = 0; k < _ATV_KEYS.length; k++) {
+        var fd = intrinsic.getOwnPropertyDescriptor(atv, _ATV_KEYS[k]);
+        if (fd !== undefined && !intrinsic.hasOwn(fd, "value")) {
+          throw E("path/bad-input", who + "[" + i + "][" + j + "]." + _ATV_KEYS[k] + " must be a data property, not an accessor");
+        }
+      }
+    }
+  }
+}
+function _capturedRdns(base, who) {
+  if (intrinsic.types.isProxy(base)) throw E("path/bad-input", who + ": a trustAnchor nameConstraints directoryName base must not be a Proxy");
+  /** @internal An inherited Proxy answers `in` through its has trap, which is caller code running
+   * inside what is meant to be a getter-free read. */
+  var baseProto = intrinsic.getPrototypeOf(base);
+  while (baseProto !== null) {
+    if (intrinsic.types.isProxy(baseProto)) throw E("path/bad-input", who + ": a trustAnchor nameConstraints directoryName base must not inherit from a Proxy");
+    baseProto = intrinsic.getPrototypeOf(baseProto);
+  }
+  var d = intrinsic.getOwnPropertyDescriptor(base, "rdns");
+  if (d === undefined) {
+    if ("rdns" in base) throw E("path/bad-input", who + ": a trustAnchor nameConstraints directoryName rdns must be an own data property, not inherited");
+    return undefined;
+  }
+  if (!intrinsic.hasOwn(d, "value")) throw E("path/bad-input", who + ": a trustAnchor nameConstraints directoryName rdns must be a data property, not an accessor");
+  if (!intrinsic.isArray(d.value)) return undefined;
+  return _copyDnRdns(d.value, who + ": a trustAnchor nameConstraints directoryName rdns");
+}
+var _NC_SUBTREE_KEYS = ["tag", "base"];
+var _NC_LIST_KEYS = ["permitted", "excluded"];
+function _copyAnchorSubtreeList(list, key, who) {
+  if (list === undefined || list === null) return undefined;
+  if (!intrinsic.isArray(list) || intrinsic.types.isProxy(list)) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " must be a plain array of { tag, base } subtree entries");
+  var copied = [];
+  var len = list.length;
+  for (var i = 0; i < len; i++) {
+    var entryD = intrinsic.getOwnPropertyDescriptor(list, i);
+    if (entryD === undefined) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " must not be a sparse array; index " + i + " is a hole");
+    if (!intrinsic.hasOwn(entryD, "value")) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " entry " + i + " must be a data property, not an accessor");
+    var st = entryD.value;
+    if (st === null || typeof st !== "object" || intrinsic.types.isProxy(st)) {
+      throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " entry must be a plain { tag, base } object");
+    }
+    var out = {};
+    for (var k = 0; k < _NC_SUBTREE_KEYS.length; k++) {
+      var field = _NC_SUBTREE_KEYS[k];
+      var fd = intrinsic.getOwnPropertyDescriptor(st, field);
+      if (fd === undefined) continue;
+      if (!intrinsic.hasOwn(fd, "value")) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " " + field + " must be a data property, not an accessor");
+      var fv = fd.value;
+      if (field === "base" && fv !== null && typeof fv === "object") {
+        var rdnsOwn = _capturedRdns(fv, who);
+        if (rdnsOwn !== undefined) {
+          var dnBase = {};
+          intrinsic.defineProperty(dnBase, "rdns", { value: rdnsOwn, enumerable: true, configurable: true, writable: true });
+          fv = dnBase;
+        } else if (guard.bytes.isByteSource(fv)) {
+          fv = guard.bytes.snapshotSource(fv, PathError, "path/bad-input", who + ": a trustAnchor nameConstraints iPAddress subtree base");
+        }
+      }
+      intrinsic.defineProperty(out, field, { value: fv, enumerable: true, configurable: true, writable: true });
+    }
+    intrinsic.push(copied, out);
+  }
+  return copied;
+}
+/**
+ * @internal Anchors are normalized one at a time, and each may expose fields through getters that
+ * run caller code. Capture every anchor's namespace first, so an earlier anchor's getter cannot
+ * clear a later anchor's restriction before that anchor is reached.
+ */
+/**
+ * @internal Read a caller's anchor list once, from its own indices, into a fresh array. The list is
+ * walked twice, to capture namespaces and then to normalize, and an accessor index could answer
+ * differently each time.
+ */
+function _ownAnchorEntries(list, who) {
+  if (intrinsic.types.isProxy(list)) throw E("path/bad-input", who + ": trustAnchors must be a plain array, not a Proxy");
+  var out = [];
+  for (var i = 0; i < list.length; i++) {
+    var d = intrinsic.getOwnPropertyDescriptor(list, i);
+    if (d === undefined) throw E("path/bad-input", who + ": trustAnchors index " + i + " is a hole or is inherited; every entry must be its own");
+    if (!intrinsic.hasOwn(d, "value")) throw E("path/bad-input", who + ": trustAnchors entry " + i + " must be a data property, not an accessor");
+    intrinsic.push(out, d.value);
+  }
+  return out;
+}
+function _precaptureAnchorNameConstraints(list, who) {
+  var out = [];
+  for (var i = 0; i < list.length; i++) {
+    var entry = list[i];
+    var captured;
+    if (entry && typeof entry === "object" && !intrinsic.isBuffer(entry) && !guard.parsed.isRecorded(entry) && !intrinsic.types.isProxy(entry)) {
+      var raw = _captureConstraintMap(entry, "nameConstraints", E, "path/bad-input", who);
+      captured = raw == null ? undefined : _copyAnchorNameConstraints(raw, who);
+    }
+    intrinsic.push(out, captured);
+  }
+  return out;
+}
+function _copyAnchorNameConstraints(nc, who) {
+  if (nc === null || typeof nc !== "object" || intrinsic.isArray(nc)) {
+    throw E("path/bad-input", who + ": a trustAnchor nameConstraints must be a { permitted, excluded } object of { tag, base } subtree entries");
+  }
+  guard.identifier.assertPlainRecord(nc, E, "path/bad-input", who + ": a trustAnchor nameConstraints");
+  guard.identifier.assertKnownKeys(nc, { permitted: 1, excluded: 1 }, E, "path/bad-input",
+    who + ": a trustAnchor nameConstraints names its subtree lists `permitted` and `excluded`. The unknown key was: ");
+  var out = {};
+  for (var i = 0; i < _NC_LIST_KEYS.length; i++) {
+    var key = _NC_LIST_KEYS[i];
+    var d = intrinsic.getOwnPropertyDescriptor(nc, key);
+    if (d === undefined) {
+      if (key in nc) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " must be an own data property, not inherited");
+      continue;
+    }
+    if (!intrinsic.hasOwn(d, "value")) throw E("path/bad-input", who + ": a trustAnchor nameConstraints." + key + " must be a data property, not an accessor");
+    var copiedList = _copyAnchorSubtreeList(d.value, key, who);
+    if (copiedList === undefined) continue;
+    /** @internal Validated while the anchor is normalized, so a malformed subtree is refused
+     * wherever the anchor sits in the list rather than only once that anchor is reached. */
+    var checkedList = checkedSubtreeSeeds(copiedList, "trustAnchors[].nameConstraints." + key);
+    intrinsic.defineProperty(out, key, { value: checkedList, enumerable: true, configurable: true, writable: true });
+  }
+  return out;
+}
+
 function _copyAtv(atv) {
   var out = {};
   var t = atv.type;
@@ -1939,7 +2205,7 @@ function _copyRdnsDeep(rdns) {
 function toAnchor(entry, verb) {
   var who = verb || "build";
   var isTuple = false, alg = null, pubRaw, nameRaw = null, pk = null, purposesSnap, distrustSnap;
-  var subjectDerRaw, labelRaw, mozRaw;
+  var subjectDerRaw, labelRaw, mozRaw, ncSnap;
   if (intrinsic.types.isProxy(entry)) {
     throw E("path/bad-input", who + ": a trustAnchor must not be a Proxy");
   }
@@ -1956,6 +2222,8 @@ function toAnchor(entry, verb) {
       purposesSnap = _normalizeConstraintField(pRaw, E, "path/bad-input", who);
       var dRaw = _captureConstraintMap(entry, "distrustAfter", E, "path/bad-input", who);
       distrustSnap = _normalizeConstraintField(dRaw, E, "path/bad-input", who);
+      var ncRaw = _captureConstraintMap(entry, "nameConstraints", E, "path/bad-input", who);
+      ncSnap = ncRaw == null ? undefined : _copyAnchorNameConstraints(ncRaw, who);
       subjectDerRaw = _captureOwnData(entry, "subjectDer");
       labelRaw = _captureOwnData(entry, "label");
       mozRaw = _captureOwnData(entry, "mozillaCaPolicy");
@@ -2023,6 +2291,7 @@ function toAnchor(entry, verb) {
     intrinsic.defineProperty(flat, "name", { value: nameOut, enumerable: true, configurable: true, writable: true });
     if (purposesSnap !== undefined) intrinsic.defineProperty(flat, "purposes", { value: purposesSnap, enumerable: true, configurable: true, writable: true });
     if (distrustSnap !== undefined) intrinsic.defineProperty(flat, "distrustAfter", { value: distrustSnap, enumerable: true, configurable: true, writable: true });
+    if (ncSnap !== undefined) intrinsic.defineProperty(flat, "nameConstraints", { value: ncSnap, enumerable: true, configurable: true, writable: true });
     if (subjectDerRaw !== undefined) intrinsic.defineProperty(flat, "subjectDer", { value: subjectDerRaw, enumerable: true, configurable: true, writable: true });
     if (labelRaw !== undefined) intrinsic.defineProperty(flat, "label", { value: labelRaw, enumerable: true, configurable: true, writable: true });
     if (mozRaw !== undefined) intrinsic.defineProperty(flat, "mozillaCaPolicy", { value: mozRaw, enumerable: true, configurable: true, writable: true });
@@ -2031,8 +2300,8 @@ function toAnchor(entry, verb) {
     intrinsic.defineProperty(flat, "parameters", { value: spkiAlg.parameters, enumerable: true, configurable: true, writable: true });
     return flat;
   }
-  if (entry && typeof entry === "object" && (("purposes" in entry) || ("distrustAfter" in entry))) {
-    throw E("path/bad-input", who + ": a trustAnchor certificate must not carry purposes / distrustAfter -- put per-purpose constraints on a { name, publicKey, algorithm, purposes, distrustAfter } tuple (or a pki.trust anchor), not on a parsed certificate");
+  if (entry && typeof entry === "object" && (("purposes" in entry) || ("distrustAfter" in entry) || ("nameConstraints" in entry))) {
+    throw E("path/bad-input", who + ": a trustAnchor certificate must not carry purposes / distrustAfter / nameConstraints -- put anchor constraints on a { name, publicKey, algorithm, purposes, distrustAfter, nameConstraints } tuple (or a pki.trust anchor), not on a parsed certificate");
   }
   var cert;
   try { cert = coerceCert(entry); }
@@ -2349,7 +2618,20 @@ async function build(leaf, opts) {
   for (var pdk = 0; pdk < pool.length; pdk++) intrinsic.setAdd(poolDerKeys, certDerKey(pool[pdk]));
 
   if (!intrinsic.isArray(opts.trustAnchors) || opts.trustAnchors.length === 0) throw E("path/bad-input", "build: opts.trustAnchors must be a non-empty array of anchor tuples or root certificates");
-  var anchors = opts.trustAnchors.map(function (a) { return toAnchor(a, "build"); });
+  /** @internal Captured before any anchor is normalized: an anchor field may be an accessor whose
+   * getter runs caller code, and every candidate is validated in its own pass after an await. */
+  var buildPermRaw = opts.initialPermittedSubtrees;
+  var buildExclRaw = opts.initialExcludedSubtrees;
+  var buildPermSeeds = checkedSubtreeSeeds(buildPermRaw, "initialPermittedSubtrees");
+  var buildExclSeeds = checkedSubtreeSeeds(buildExclRaw, "initialExcludedSubtrees");
+  var buildEntries = _ownAnchorEntries(opts.trustAnchors, "build");
+  var buildPreNc = _precaptureAnchorNameConstraints(buildEntries, "build");
+  var anchors = [];
+  for (var bai = 0; bai < buildEntries.length; bai++) {
+    var bAnchor = toAnchor(buildEntries[bai], "build");
+    if (buildPreNc[bai] !== undefined) intrinsic.defineProperty(bAnchor, "nameConstraints", { value: buildPreNc[bai], enumerable: true, configurable: true, writable: true });
+    intrinsic.push(anchors, bAnchor);
+  }
 
   guard.time.assertValid(opts.time, E, "path/bad-input", "build: opts.time (the validity-window check date, forwarded to validate)");
   var effectiveMaxCerts = guard.limits.cap(opts.maxPathCerts, "build: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
@@ -2396,6 +2678,8 @@ async function build(leaf, opts) {
     if (intrinsic.hasOwn(BUILD_ONLY_OPT, k)) return;
     if (k in opts) forwarded[k] = opts[k];
   });
+  if (buildPermRaw != null) forwarded.initialPermittedSubtrees = buildPermSeeds;
+  if (buildExclRaw != null) forwarded.initialExcludedSubtrees = buildExclSeeds;
   function validateOpts(anchor) {
     var vo = Object.create(null);
     Object.keys(forwarded).forEach(function (f) { vo[f] = forwarded[f]; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.6.37",
+  "version": "0.6.38",
   "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:82faf919-c224-4430-992b-dd3055e65ed3",
+  "serialNumber": "urn:uuid:adf5e979-6804-475f-a0d0-8aef04be0317",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-05T03:43:35.188Z",
+    "timestamp": "2026-09-05T07:57:13.454Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.6.37",
+      "bom-ref": "@blamejs/pki@0.6.38",
       "type": "application",
       "name": "pki",
-      "version": "0.6.37",
+      "version": "0.6.38",
       "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.6.37",
+      "purl": "pkg:npm/%40blamejs/pki@0.6.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.6.37",
+      "ref": "@blamejs/pki@0.6.38",
       "dependsOn": []
     }
   ]