@blamejs/core 0.14.25 → 0.14.27

package/lib/auth/openid-federation.js

@@ -334,14 +334,23 @@ function _applyOnePolicy(metadata, policy) {
  * @signature b.auth.openidFederation.applyMetadataPolicy(metadata, chain, kind)
  * @since     0.8.62
  *
- * Apply every metadata_policy in the chain (top-down) to the leaf's
+ * Apply the federation's metadata_policy (top-down) to the leaf's
  * declared metadata for the given entity-kind ("openid_relying_party"
  * / "openid_provider" / "federation_entity" / etc.) and return the
  * effective metadata. Throws on any policy violation.
  *
- * The chain is leaf-first; we reverse for top-down application so
- * the trust anchor's policy applies first, then each intermediate's,
- * then the leaf's claimed metadata is the starting object.
+ * Per OpenID Federation 1.0 §6.2, an entity's metadata_policy comes
+ * from the SUPERIOR-SIGNED subordinate statement about that entity
+ * (`chain[i].subordinate.metadata_policy`), NOT from the entity's own
+ * self-published configuration. An entity cannot self-declare the
+ * policy that constrains it — that would let a leaf widen or drop the
+ * trust anchor's value / subset_of / essential constraints. The leaf's
+ * own self-config metadata_policy is therefore ignored.
+ *
+ * The chain is leaf-first; each `chain[i].subordinate` is the statement
+ * signed by the superior directly above entity `i`, so walking high
+ * index → low index applies the anchor's policy first, then each
+ * intermediate's, narrowing down to the leaf (§6.2 narrow-only merge).
  *
  * @example
  *   var effective = b.auth.openidFederation.applyMetadataPolicy(
@@ -361,12 +370,17 @@ function applyMetadataPolicy(metadata, chain, kind) {
       "applyMetadataPolicy: chain must be an array");
   }
   var out = Object.assign({}, metadata);
-  // Walk top-down (anchor last in leaf-first array).
+  // Walk top-down (anchor last in leaf-first array). Read the policy
+  // from each node's SUPERIOR-SIGNED subordinate statement — never from
+  // the entity's own self-config — so the anchor/intermediate
+  // constraints can't be dropped by a self-declared policy. The anchor
+  // node carries no `.subordinate` (it terminates the chain) and is
+  // skipped; the leaf's self-config policy is never read.
   for (var i = chain.length - 1; i >= 0; i--) {
     var stmt = chain[i];
-    if (!stmt || !stmt.claims) continue;
-    if (stmt.claims.metadata_policy && stmt.claims.metadata_policy[kind]) {
-      out = _applyOnePolicy(out, stmt.claims.metadata_policy[kind]);
+    if (!stmt || !stmt.subordinate) continue;
+    if (stmt.subordinate.metadata_policy && stmt.subordinate.metadata_policy[kind]) {
+      out = _applyOnePolicy(out, stmt.subordinate.metadata_policy[kind]);
     }
   }
   return out;
@@ -433,6 +447,18 @@ async function buildTrustChain(opts) {
   };
   var maxDepth = opts.maxDepth || MAX_CHAIN_DEPTH;
 
+  // ---- Phase 1: collect the chain bottom-up (leaf → anchor) ----------
+  // Fetch each entity's self-config + the superior-signed subordinate
+  // statement about it, but DEFER cryptographic chain verification to
+  // Phase 2. The signature on a subordinate statement must be checked
+  // against the keys ATTESTED for the signing authority by ITS superior
+  // — flowing down from the operator-pinned anchor — not against the
+  // authority's own self-published config jwks. Verifying eagerly here
+  // (against self-published keys) is a fetch-time TOCTOU: an attacker
+  // controlling the authority's endpoint can serve attacker jwks to the
+  // statement-verify fetch while serving genuine config elsewhere, and
+  // the only operator-pinned trust (the anchor key) never gates the
+  // subordinate links.
   var chain = [];
   var current = opts.leafEntityId;
   var depth = 0;
@@ -446,6 +472,7 @@ async function buildTrustChain(opts) {
   // hostile-federation probes immediately.
   var visited = Object.create(null);
   visited[current] = true;
+  var reachedAnchor = false;
   while (depth < maxDepth) {
     var entityConfigUrl = current.replace(/\/$/, "") + "/.well-known/openid-federation";
     var entityConfigJwt = await fetcher(entityConfigUrl);
@@ -454,21 +481,22 @@ async function buildTrustChain(opts) {
       throw new AuthError("auth-openid-federation/bad-self-statement",
         "entity configuration for \"" + current + "\" must have iss==sub==entity_id");
     }
-    // Self-signed: verify with its own jwks.
+    // Self-statement integrity: a well-formed entity config is self-signed
+    // over its own jwks. This proves the document isn't truncated/garbled
+    // — it is NOT the trust decision. Trust flows from the anchor through
+    // the subordinate statements verified top-down in Phase 2.
     verifyEntityStatement(entityConfigJwt, parsedEC.claims.jwks || {});
 
     // Is this entity a trust anchor?
     if (Object.prototype.hasOwnProperty.call(opts.trustAnchors, current)) {
       // Verify the anchor's self-statement using the operator-pinned
       // JWKS — defends against a compromised anchor key by trusting
-      // the configured one over what the anchor publishes today.
+      // the configured one over what the anchor publishes today. The
+      // pinned keys become the root of the top-down verification.
       verifyEntityStatement(entityConfigJwt, opts.trustAnchors[current]);
       chain.push({ jwt: entityConfigJwt, claims: parsedEC.claims, role: "trust_anchor" });
-      _emitAudit("chain_built", "success", {
-        leaf: opts.leafEntityId, depth: chain.length, anchor: current,
-      });
-      _emitMetric("chain-built");
-      return chain;
+      reachedAnchor = true;
+      break;
     }
     // Not the anchor — add to chain, ascend via authority_hints.
     chain.push({
@@ -481,16 +509,15 @@ async function buildTrustChain(opts) {
       throw new AuthError("auth-openid-federation/no-authority-hints",
         "entity \"" + current + "\" has no authority_hints; cannot ascend to a trust anchor");
     }
-    // Pick the FIRST authority_hint that resolves to a trust anchor,
-    // OR the first that returns a valid subordinate statement. Real
-    // operators with multiple federations usually have one anchor
-    // active; we walk in order and pick the first success.
-    // Track every per-authority failure reason and surface them on
-    // `no-ascent` rather than masking — silently
-    // swallowing `catch (_e) {}` lets a hostile intermediate that
-    // serves a malformed-then-valid pair shape-walk the verifier.
-    // We continue past 404 / fetch errors but refuse on
-    // signature-verify failure (cryptographic refusal is a hard stop).
+    // Pick the FIRST authority_hint that yields a fetchable subordinate
+    // statement with matching iss/sub. We continue past 404 / fetch /
+    // parse errors (acceptable "try the next hint") and surface every
+    // failure reason on `no-ascent` rather than masking it — silently
+    // swallowing `catch (_e) {}` lets a hostile intermediate that serves
+    // a malformed-then-valid pair shape-walk the verifier. Cryptographic
+    // verification is NOT done here; the selected statement is verified
+    // against the superior-attested keys in Phase 2, so a forged
+    // signature fails the whole chain regardless of which hint picked it.
     var ascended = false;
     var ascentErrors = [];
     for (var ai = 0; ai < parsedEC.claims.authority_hints.length; ai++) {
@@ -502,49 +529,83 @@ async function buildTrustChain(opts) {
           ascentErrors.push({ authority: authority, code: "iss-sub-mismatch" });
           continue;
         }
-        var authorityCfgJwt = await fetcher(authority.replace(/\/$/, "") + "/.well-known/openid-federation");
-        var authorityCfgClaims = parseEntityStatement(authorityCfgJwt).claims;
-        // Cryptographic verification — any throw here is a hard
-        // refusal, NOT a "try next authority" signal. A malformed-
-        // signature subordinate from an authority listed by the
-        // entity means that authority is hostile or compromised;
-        // moving on lets a chain-shaping attacker bypass the gate.
-        verifyEntityStatement(subordinateJwt, authorityCfgClaims.jwks || {});
-        chain[chain.length - 1].claims.jwks = parsedSub.claims.jwks || chain[chain.length - 1].claims.jwks;
-        chain[chain.length - 1].subordinateJwt = subordinateJwt;
-        chain[chain.length - 1].subordinate    = parsedSub.claims;
-        // Refuse revisit. A trust anchor terminates the loop
-        // before re-entry, so a revisit here ALWAYS means a cyclic
+        // Refuse revisit. A trust anchor terminates the loop before
+        // re-entry, so a revisit here ALWAYS means a cyclic
         // authority_hints graph.
         if (visited[authority]) {
           throw new AuthError("auth-openid-federation/chain-cycle",
             "buildTrustChain: authority \"" + authority + "\" already visited — " +
             "cyclic authority_hints graph refused");
         }
+        // Stash the superior-signed subordinate statement on the entity
+        // it is ABOUT. Phase 2 verifies its signature against the
+        // attested keys for `authority` and applies its metadata_policy.
+        chain[chain.length - 1].subordinateJwt = subordinateJwt;
+        chain[chain.length - 1].subordinate    = parsedSub.claims;
         visited[authority] = true;
         current = authority;
         ascended = true;
         break;
       } catch (err) {
+        // A cycle refusal is a hard stop, not a "try next hint" signal.
+        if (err && err.code === "auth-openid-federation/chain-cycle") throw err;
         var errCode = (err && err.code) || "unknown";
-        // Network / 404 / parse errors at the AUTHORITY-fetch step
-        // are acceptable "try the next hint" signals. Verify-side
-        // failures (crypto) are NOT — surface them and abort.
-        if (/^auth-openid-federation\/(?:bad-jwk|alg-kty-mismatch|bad-signature|signature-failed)$/.test(errCode)) {
-          throw err;
-        }
         ascentErrors.push({ authority: authority, code: errCode, message: (err && err.message) || String(err) });
       }
     }
     if (!ascended) {
       throw new AuthError("auth-openid-federation/no-ascent",
-        "entity \"" + current + "\" has authority_hints but none yielded a verifiable subordinate statement: " +
+        "entity \"" + current + "\" has authority_hints but none yielded a fetchable subordinate statement: " +
         JSON.stringify(ascentErrors));
     }
     depth += 1;
   }
-  throw new AuthError("auth-openid-federation/chain-too-deep",
-    "buildTrustChain: max depth " + maxDepth + " exceeded; refused");
+  if (!reachedAnchor) {
+    throw new AuthError("auth-openid-federation/chain-too-deep",
+      "buildTrustChain: max depth " + maxDepth + " exceeded; refused");
+  }
+
+  // ---- Phase 2: verify top-down against attested keys ----------------
+  // Trust flows from the operator-pinned anchor downward. Each
+  // subordinate statement is signed by the superior directly above the
+  // entity it describes, and pins that entity's jwks. We start with the
+  // anchor's pinned keys and, for each step down, verify the subordinate
+  // statement with the keys attested for its SIGNER (never the signer's
+  // self-published config), then adopt the statement's attested jwks as
+  // the trusted keys for the next step. This closes the fetch-time TOCTOU
+  // and makes the anchor key gate every link, not just the anchor's own
+  // self-config.
+  var anchorEntityId = chain[chain.length - 1].claims.iss;
+  var attestedJwks = opts.trustAnchors[anchorEntityId];
+  for (var ci = chain.length - 2; ci >= 0; ci--) {
+    var node = chain[ci];
+    if (!node.subordinate || !node.subordinateJwt) {
+      // Every non-anchor node must carry the superior-signed statement
+      // collected in Phase 1; its absence is an internal invariant break.
+      throw new AuthError("auth-openid-federation/no-subordinate",
+        "buildTrustChain: entity \"" + node.claims.iss + "\" has no superior-signed subordinate statement");
+    }
+    // Verify against the SIGNER's attested keys (flowed down), not the
+    // signer's self-published config jwks.
+    verifyEntityStatement(node.subordinateJwt, attestedJwks || {});
+    // The subordinate statement pins this entity's jwks — adopt the
+    // attested keys for the next link down, and reflect them on the node.
+    if (node.subordinate.jwks && Array.isArray(node.subordinate.jwks.keys)) {
+      node.claims.jwks = node.subordinate.jwks;
+      attestedJwks = node.subordinate.jwks;
+    } else {
+      // A subordinate statement that pins no keys cannot attest the next
+      // link — refuse rather than fall back to self-published keys.
+      throw new AuthError("auth-openid-federation/no-attested-jwks",
+        "subordinate statement for \"" + node.claims.iss + "\" pins no jwks; cannot attest the chain downward");
+    }
+  }
+
+  _emitAudit("chain_built", "success", {
+    leaf: opts.leafEntityId, depth: chain.length, anchor: anchorEntityId,
+  });
+  _emitMetric("chain-built");
+  return chain;
 }
 
 /**

package/lib/auth/sd-jwt-vc.js

@@ -482,9 +482,13 @@ async function verify(presentation, opts) {
       "verify: issuerKeyResolver returned no key");
   }
   // CVE-2026-22817 — when issuerKeyResolver returns a JWK object,
-  // cross-check alg/kty BEFORE handing it to node:crypto.verify.
-  // KeyObject / PEM shapes can't surface kty so the check happens at
-  // JWK resolution only.
+  // cross-check the issuer JWS alg/kty BEFORE handing it to
+  // node:crypto.verify. KeyObject / PEM shapes can't surface kty, so this
+  // guard only fires when the resolver hands back a JWK (the common path).
+  // The holder KB-JWT path applies its OWN _assertAlgKtyMatch against the
+  // cnf.jwk below — note that the holder key is issuer-ATTESTED (it comes
+  // from the cryptographically-verified issuer payload's cnf claim), not
+  // header-resolved, so the two cross-checks defend different trust edges.
   if (typeof issuerKey === "object" &&
       !(issuerKey instanceof nodeCrypto.KeyObject) &&
       !Buffer.isBuffer(issuerKey) &&
@@ -610,6 +614,15 @@ async function verify(presentation, opts) {
       throw new AuthError("auth-sd-jwt-vc/unsupported-alg",
         "verify: KB-JWT alg unsupported");
     }
+    // CVE-2026-22817 — cross-check the KB-JWT header alg against the holder
+    // key type BEFORE importing the key / verifying. The issuer path does
+    // this for issuerKey (above); the holder KB-JWT path must too. The
+    // KB-JWT header alg is attacker-controllable (the holder mints the
+    // KB-JWT), and holderKey is a cnf.jwk with a kty, so an alg/kty
+    // mismatch (e.g. a header claiming EdDSA against an EC cnf key) is
+    // refused with the precise alg-mismatch error rather than handed to
+    // node:crypto.verify.
+    jwtExternal._assertAlgKtyMatch(kbAlg, holderKey);
     var holderKeyObj = nodeCrypto.createPublicKey({ key: holderKey, format: "jwk" });
     var kbParsed = _verifyJwt(maybeKbJwt, holderKeyObj, kbAlg);
     if (opts.audience && kbParsed.payload.aud !== opts.audience) {

package/lib/break-glass.js

@@ -75,6 +75,10 @@ var DEK_BYTES               = C.BYTES.bytes(32);
 var GRANT_ID_BYTES          = C.BYTES.bytes(16);
 
 var DEFAULT_GRANT_TTL_MS    = C.TIME.minutes(15);
+// Replay-step retention. A TOTP code is only valid inside the verifier's
+// drift window (minutes); retaining the highest-accepted step for an hour
+// guarantees any in-window replay attempt arrives after the floor is set.
+var REPLAY_STEP_TTL_MS      = C.TIME.hours(1);
 var DEFAULT_MAX_ROWS        = 1;       // operator-locked: row-by-row auth
 var DEFAULT_REASON_MIN_LEN  = 12;
 var DEFAULT_LOCKED_BEHAVIOR = "throw"; // or "redact"
@@ -817,10 +821,58 @@ function _verifyTotpFactor(factor) {
   if (!factor || typeof factor !== "object") return { ok: false };
   if (typeof factor.secret !== "string" || factor.secret.length === 0) return { ok: false };
   if (typeof factor.code !== "string" || factor.code.length === 0)     return { ok: false };
-  var verified = totp.verify(factor.secret, factor.code);
+  // factor.now threads a deterministic test clock into totp.verify. The
+  // replay floor is NOT applied here: acceptance reserves the matched step
+  // atomically in _reserveTotpStep, so two concurrent grants presenting the
+  // same in-window code cannot both pass (a read-then-commit floor races —
+  // both reads observe the old floor before either commits). totp.verify
+  // returns the step the code matches (a fixed value for a given code within
+  // the drift window) or false; the reserve then floors replays of that step.
+  var vopts = {};
+  if (typeof factor.now === "number") vopts.now = factor.now;
+  var verified = totp.verify(factor.secret, factor.code, vopts);
   return { ok: verified !== false, step: verified };
 }
 
+// Replay-step cache key. Keyed by BOTH the actorId AND a non-reversible
+// fingerprint of the TOTP secret. Keying on actorId alone would falsely
+// reject a legitimate second grant when two distinct credentials accept a
+// code at the same TOTP step (the step number is a wall-clock counter, not
+// per-credential) — the secret fingerprint disambiguates them. The secret
+// never reaches the cache in any reversible form.
+function _replayStepKey(actorId, secret) {
+  return "totp-step:" + actorId + ":" + sha3Hash(secret);
+}
+
+// Atomically reserve the accepted TOTP step for (actorId, secret): advance
+// the stored replay floor to `step` only when `step` is strictly above the
+// current floor, and report whether THIS caller won the reservation. The
+// compare-and-advance is one atomic cache update, so two concurrent grant()
+// calls presenting the same in-window code cannot both pass — the first wins
+// and raises the floor to `step`, the second observes step <= floor and is
+// refused. (A separate read-then-commit sequence let both reads see the old
+// floor before either committed, so both verified — the replay this closes.)
+// The TTL outlives the verify drift window many times over so a replayed code
+// stays floored until it expires.
+//
+// Fails CLOSED (returns false) on a cache fault: a grant cannot proceed
+// without a working factor cache regardless — the lockout check at the top of
+// grant() already gates on the same cache — so refusing here can only reject,
+// never loosen replay protection.
+async function _reserveTotpStep(actorId, secret, step) {
+  _ensureFactorLockout();
+  if (typeof step !== "number") return false;
+  var won = false;
+  try {
+    await _factorLockoutCache.update(_replayStepKey(actorId, secret), function (prior) {
+      if (typeof prior === "number" && step <= prior) { won = false; return { value: prior }; }
+      won = true;
+      return { value: step };
+    }, { ttlMs: REPLAY_STEP_TTL_MS });
+  } catch (_e) { return false; }
+  return won;
+}
+
 // Passkey factor — operator presents a WebAuthn assertion plus the
 // challenge/origin/RPID + the previously-enrolled credential record.
 // Phishing-resistant; the private key lives on the YubiKey, not in
@@ -990,8 +1042,20 @@ async function grant(opts) {
   }
 
   var factorOk = false;
+  var totpSecret = null;
   if (factorType === "totp") {
-    factorOk = _verifyTotpFactor(opts.factor).ok;
+    totpSecret = opts.factor && opts.factor.secret;
+    // Verify the code, then atomically reserve the step it matched as the act
+    // of acceptance. The reserve advances the per-(actor,secret) replay floor
+    // in one compare-and-set, so a code already redeemed inside the drift
+    // window — including by a concurrent grant for the same credential — is
+    // refused. (A read-then-commit floor raced: both grants read the old
+    // floor before either committed, so both passed.)
+    var totpResult = _verifyTotpFactor(opts.factor);
+    if (totpResult.ok && typeof totpResult.step === "number" &&
+        typeof totpSecret === "string" && totpSecret.length > 0) {
+      factorOk = await _reserveTotpStep(actorId, totpSecret, totpResult.step);
+    }
   } else if (factorType === "passkey") {
     factorOk = (await _verifyPasskeyFactor(opts.factor)).ok;
   }
@@ -1086,6 +1150,78 @@ function _reasonForAudit(reason, mode) {
   return out;
 }
 
+// Enforce the grant's IP / session bindings at redemption. policy.set
+// documents pinIp / sessionPin as default-ON, and grant() captures
+// grantRow.ip / grantRow.sessionId at mint time — but without this gate
+// the bindings are stored-and-never-enforced (a grant minted from IP-A
+// would redeem from IP-B). Called BEFORE the SELECT-then-increment so a
+// mismatch does not consume a grant.
+//
+// FAIL-CLOSED: when a pin is requested but the binding was captured null
+// (e.g. an Express-shaped req whose IP requestHelpers.clientIp couldn't
+// read at mint time), the redemption is REFUSED rather than silently
+// skipped — a `grantRow.ip != null` short-circuit would defeat the pin
+// for exactly the requests whose binding capture failed.
+function _enforceGrantPins(policy, grantRow, redeemReq, actorFor) {
+  if (!policy) return;
+  if (policy.pinIp) {
+    if (grantRow.ip == null) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-ip-binding-missing",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-ip-mismatch",
+        "unsealRow: grant " + grantRow._id + " has pinIp on but no IP was " +
+        "captured at mint (fail-closed) — re-mint from a request whose client " +
+        "IP the framework can resolve", true);
+    }
+    var redeemIp = requestHelpers.clientIp(redeemReq, { trustProxy: _trustProxy });
+    if (redeemIp !== grantRow.ip) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-ip-mismatch",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-ip-mismatch",
+        "unsealRow: grant " + grantRow._id + " is pinned to its issuing IP " +
+        "and this redemption arrived from a different address", true);
+    }
+  }
+  if (policy.sessionPin) {
+    if (grantRow.sessionId == null) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-session-binding-missing",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-session-mismatch",
+        "unsealRow: grant " + grantRow._id + " has sessionPin on but no " +
+        "session id was captured at mint (fail-closed) — re-mint from a " +
+        "request carrying req.session.id", true);
+    }
+    var redeemSession = (redeemReq && redeemReq.session && redeemReq.session.id) || null;
+    if (redeemSession !== grantRow.sessionId) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-session-mismatch",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-session-mismatch",
+        "unsealRow: grant " + grantRow._id + " is pinned to its issuing " +
+        "session and this redemption arrived from a different session", true);
+    }
+  }
+}
+
 // ---- Use a grant ----
 
 /**
@@ -1195,6 +1331,13 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       grantRow.maxRowsPerGrant + " allowed rows", true);
   }
 
+  // IP / session pin enforcement — BEFORE the SELECT-then-increment so a
+  // pin mismatch does not consume the grant. Fail-closed when a requested
+  // pin's binding was captured null (see _enforceGrantPins). The policy is
+  // fetched once here and reused for the Model-A/B unseal dispatch below.
+  var policy = await policyGet(table);
+  _enforceGrantPins(policy, grantRow, opts.req, _actorFor);
+
   // SELECT-before-increment — fetch the target row FIRST. If the row
   // doesn't exist (operator typo, race with row-deletion, etc.), the
   // grant should not be consumed. Without this ordering, a single
@@ -1237,7 +1380,8 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       "unsealRow: grant " + grantHandle.id + " was exhausted by a concurrent read", true);
   }
   void updateRes;
-  var policy = await policyGet(table);
+  // policy was fetched above for the pin enforcement; reuse it for the
+  // Model-A vs Model-B (cryptographic) unseal dispatch.
   var unsealedRow;
   if (policy && policy.cryptographic) {
     // Snapshot the raw glass-locked column ciphertexts BEFORE
@@ -1427,6 +1571,12 @@ async function listActive(opts) {
  * distinct `breakglass.grant.bypass` audit row so post-incident review
  * separates operator-initiated reads from scheduled-job reads.
  *
+ * This path is service-to-service: it consumes NO grant row, so the
+ * `pinIp` / `sessionPin` grant bindings enforced by `unsealRow` do not
+ * apply here. A grant that was minted with those pins is not redeemable
+ * through this surface — the bypass is gated solely by the
+ * `serviceAccountBypass` allowlist + required-role check.
+ *
  * @opts
  *   reason: string,   // operator-supplied reason recorded into the audit row
  *