sparda-mcp 0.64.0 → 0.66.0

package/README.md

@@ -6,11 +6,12 @@
 
 <br/>
 
-> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
+> 🇫🇷 **Français** — _L'IA écrit. SPARDA prouve._ Un gate déterministe et hors-ligne qui détecte quand une modif d'IA retire une garde, expose une route ou casse un invariant — sans clé API, directement dans la boucle d'édition de l'agent. Pour tout comprendre en 10 minutes (douleur, architecture, vision) : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
 
 ---
 
 <h1 align="center">AI writes. SPARDA proves.</h1>
+<p align="center"><em>L'IA écrit. SPARDA prouve.</em></p>
 
 **The trust layer for AI-written backends.** SPARDA compiles your backend — routes, database queries, state mutations, guards, side-effects — into one deterministic behavior graph, then **statically proves what can and can't break before you ship**: no unguarded mutation, no broken invariant, no non-atomic aggregate write.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sparda-mcp",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
-  "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
+  "description": "AI writes. SPARDA proves. A deterministic, offline gate that catches when an AI edit removes a guard, exposes a route, or breaks an invariant — no API key, right in the agent edit loop.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -46,10 +46,16 @@
     "mcp",
     "model-context-protocol",
     "claude",
-    "ai",
-    "express",
-    "fastapi",
-    "codegen"
+    "claude-code",
+    "ai-code-review",
+    "code-review",
+    "guardrails",
+    "static-analysis",
+    "security",
+    "authorization",
+    "bola",
+    "ai-agents",
+    "trust-layer"
   ],
   "author": "Residual Labs (residual-labs.fr)",
   "license": "BUSL-1.1",

package/src/commands/apocalypse.js

@@ -8,12 +8,38 @@
 //   sparda apocalypse --json            raw findings for tooling
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
-import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+import {
+  checkGraph,
+  diffGraphs,
+  verdictOf,
+  verdictState,
+  buildProofObjects,
+} from '../ubg/apocalypse.js';
 import { surveyBlindspots } from '../ubg/blindspots.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
+// version travels with the proof so an audit knows which prover produced it
+const SPARDA_VERSION = (() => {
+  try {
+    return JSON.parse(
+      fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+    ).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+// a deterministic fingerprint of the canonical graph: same source → same graph → same hash.
+// The proof object binds to it, so a third party proves it audited the SAME artifact.
+function graphHash(canonical) {
+  const h = crypto.createHash('sha256');
+  h.update(JSON.stringify({ nodes: canonical.nodes, edges: canonical.edges }));
+  return 'bh1_' + h.digest('hex').slice(0, 16);
+}
+
 const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
 
 export async function runApocalypse(opts) {
@@ -61,6 +87,21 @@ export async function runApocalypse(opts) {
     );
   }
 
+  if (opts.proof) {
+    const proofPath = path.join(opts.cwd, '.sparda', 'apocalypse.proof.json');
+    fs.mkdirSync(path.dirname(proofPath), { recursive: true });
+    const proof = {
+      sparda_version: SPARDA_VERSION,
+      graph_hash: graphHash(canonical),
+      verdict: verdictState(verdict),
+      discharged: buildProofObjects(canonical),
+    };
+    atomicWrite(proofPath, JSON.stringify(proof, null, 2) + '\n');
+    console.log(
+      `✓ Proof written: .sparda/apocalypse.proof.json (${proof.discharged.length} discharged obligation(s), re-verifiable against ${proof.graph_hash})`,
+    );
+  }
+
   if (opts.json) {
     console.log(
       JSON.stringify({ verdict, obligations, findings, blindspots: blind }, null, 2),

package/src/commands/gate.js

@@ -0,0 +1,114 @@
+// commands/gate.js — the agent edit-loop gate: did THIS edit lose a protection
+// or introduce a risk, relative to the armed baseline? Delta-only by design: an
+// edit gate must never scream about pre-existing state (that noise is fatal to
+// adoption — see docs/TWO-FALSE-POSITIVE-CLASSES-2026-07-19.md), so everything
+// already true at arm time is silent and only the regression speaks.
+//   sparda gate            report the edit's behavior delta vs baseline (exit 1 on critical/high)
+//   sparda gate --arm      freeze the current graph as the accepted baseline
+//   sparda gate --hook     Claude Code PostToolUse contract: silent when clean,
+//                          report on stderr + exit 2 (blocking feedback) on regression;
+//                          arms itself on first run so there is nothing to configure.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, diffGraphs } from '../ubg/apocalypse.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+// severities that block the edit; medium/info regressions are reported, never fatal
+const BLOCKING = new Set(['critical', 'high']);
+const findingKey = (f) => `${f.rule}|${f.entrypoint}`;
+
+// The gate's whole judgment, pure over two canonical graphs (testable without a repo):
+// diff regressions (guard/route/invariant lost, blast radius grown) + static findings
+// the candidate has that the baseline did not — the same composition `review` proved
+// out (ADR-030), pointed at the baseline instead of a git ref.
+export function gateDelta(baseline, candidate) {
+  const diff = diffGraphs(baseline, candidate).findings;
+  const before = new Set(checkGraph(baseline).findings.map(findingKey));
+  const introduced = checkGraph(candidate).findings.filter(
+    (f) => !before.has(findingKey(f)),
+  );
+  const seen = new Set(diff.map(findingKey));
+  const findings = [...diff, ...introduced.filter((f) => !seen.has(findingKey(f)))];
+  return {
+    findings,
+    blocking: findings.filter((f) => BLOCKING.has(f.severity)),
+  };
+}
+
+function locOf(canonical, f) {
+  const loc = canonical.nodes.find((n) => n.id === f.entrypoint)?.loc;
+  return loc ? ` (${loc.file}:${loc.line || 1})` : '';
+}
+
+export async function runGate(opts) {
+  const t0 = process.hrtime.bigint();
+  const hook = opts.hook;
+  // in hook mode stdout belongs to nobody and stderr is what the agent reads
+  const say = hook ? (s) => console.error(s) : (s) => console.log(s);
+
+  const { graph } = compileUBG(opts.cwd, { write: false });
+  const candidate = canonicalizeGraph(graph);
+  const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
+
+  const arm = () => {
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+    atomicWrite(baselinePath, JSON.stringify(candidate, null, 2) + '\n');
+  };
+
+  if (opts.arm || opts.saveBaseline) {
+    arm();
+    say(
+      `✓ GATE ARMED — baseline frozen (.sparda/ubg.baseline.json). Every edit is now proven against it.`,
+    );
+    return { armed: true, findings: [] };
+  }
+
+  if (!fs.existsSync(baselinePath)) {
+    // first run arms instead of failing: a hook must work with zero configuration
+    arm();
+    say(
+      `✓ GATE ARMED (first run) — baseline frozen. Future edits are proven against it; re-arm with \`sparda gate --arm\` after intended changes.`,
+    );
+    return { armed: true, findings: [] };
+  }
+
+  const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  const { findings, blocking } = gateDelta(baseline, candidate);
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        { ok: blocking.length === 0, ms: Math.round(ms), findings },
+        null,
+        2,
+      ),
+    );
+    if (blocking.length) process.exitCode = 1;
+    return { armed: false, findings };
+  }
+
+  if (findings.length === 0) {
+    if (!hook)
+      say(
+        `✓ GATE CLEAN — this edit lost no guard, dropped no route, grew no blast radius (proven vs baseline in ${Math.round(ms)} ms).`,
+      );
+    return { armed: false, findings };
+  }
+
+  say(
+    `✗ SPARDA GATE — this edit changed the app's proven behavior (${Math.round(ms)} ms, deterministic):`,
+  );
+  for (const f of findings)
+    say(`  [${f.severity}] ${f.rule} — ${f.message}${locOf(candidate, f)}`);
+  say(
+    blocking.length
+      ? `  → fix the edit or, if intended, accept it with \`sparda gate --arm\`.`
+      : `  → advisory only (no critical/high regression) — review, then \`sparda gate --arm\` if intended.`,
+  );
+
+  if (blocking.length) process.exitCode = hook ? 2 : 1;
+  return { armed: false, findings };
+}

package/src/index.js

@@ -18,6 +18,7 @@ const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   saveBaseline: flags.has('--save-baseline'),
   sarif: flags.has('--sarif'),
+  proof: flags.has('--proof'),
   verbose: flags.has('--verbose'),
   quiet: flags.has('--quiet'),
   probe: flags.has('--probe'),
@@ -27,6 +28,8 @@ const opts = {
   learn: flags.has('--learn'),
   germinate: flags.has('--germinate'),
   check: flags.has('--check'),
+  hook: flags.has('--hook'),
+  arm: flags.has('--arm'),
   markdown: flags.has('--markdown'),
   port: getOpt('port', null),
   out: getOpt('out', null),
@@ -45,7 +48,8 @@ const opts = {
 // reads opts.cwd, so `--dir <path>` works on all of them; only per-command extras are listed.
 const HELP = {
   prove: `sparda prove [--dir <path>] [--json | --markdown]\n  The whole trust verdict: proof + coverage + a shareable seal.\n  --markdown  emit a sticky-PR-comment body (used by the GitHub Action).`,
-  apocalypse: `sparda apocalypse [--dir <path>] [--sarif] [--save-baseline]\n  Prove the deploy — exit 1 on any critical/high finding.\n  --sarif         also write .sparda/apocalypse.sarif for the Security tab.\n  --save-baseline freeze this graph; later runs diff against it.`,
+  apocalypse: `sparda apocalypse [--dir <path>] [--sarif] [--proof] [--save-baseline]\n  Prove the deploy — exit 1 on any critical/high finding.\n  --sarif         also write .sparda/apocalypse.sarif for the Security tab.\n  --proof         also write .sparda/apocalypse.proof.json — a re-verifiable\n                  discharge trace (deny_path per guarded mutation) a third party\n                  can audit against the graph hash without re-compiling.\n  --save-baseline freeze this graph; later runs diff against it.`,
+  gate: `sparda gate [--dir <path>] [--arm] [--hook] [--json]\n  The agent edit-loop gate: prove THIS edit lost no guard, dropped no route,\n  grew no blast radius — delta vs the armed baseline only (pre-existing state\n  never blocks an edit). Arms itself on first run.\n  --arm   accept the current graph as the new baseline.\n  --hook  Claude Code PostToolUse contract: silent when clean, report on\n          stderr + exit 2 (blocking feedback to the agent) on regression.`,
   ubg: `sparda ubg [--dir <path>] [--json] [--out <file>] [--openapi <spec>]\n  Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json).`,
   stitch: `sparda stitch <dir1> <dir2> [...] [--json]\n  Cross-service proof: join one service's outbound HTTP calls to another's routes,\n  surface cross-service trust boundaries + BOLA no mono-repo tool can see.`,
   badge: `sparda badge [--dir <path>] [--out <file>] [--json]\n  Emit a shareable SVG badge + README snippet (verdict · coverage · routes).`,
@@ -162,6 +166,11 @@ try {
       await runApocalypse(opts);
       break;
     }
+    case 'gate': {
+      const { runGate } = await import('./commands/gate.js');
+      await runGate(opts);
+      break;
+    }
     case 'review': {
       const { runReview } = await import('./commands/review.js');
       await runReview(opts);
@@ -234,6 +243,7 @@ try {
 PROVE — the point
   prove        The whole trust verdict in one gesture: proof + coverage + seal (--json / --markdown / --openapi)
   apocalypse   Prove the deploy: guards, invariants, transactions, aggregates (--save-baseline)
+  gate         The agent edit-loop gate: prove an edit lost no protection (--arm / --hook)
   review       Semantic diff of a PR vs a base ref (--base main / --json / --markdown)
   blindspots   Map SPARDA's own blindness — every unseen route/effect/guard, ranked (--json)
   badge        Emit a shareable SVG badge + README snippet (verdict · coverage · routes)

package/src/ubg/apocalypse.js

@@ -42,6 +42,66 @@ export function indexGraph(graph) {
   return { nodes, cfOut, mutOut, gateTargets, compensators, entrypoints };
 }
 
+// Proof objects (the re-verifiable discharge trace, ADR-corroboration). `apocalypse` emits a
+// VERDICT; a skeptic must re-run SPARDA to believe it. A proof object makes each discharged
+// obligation auditable WITHOUT re-compiling: for every mutating route that passes its guard
+// obligation, the exact `deny_path` — a real chain of node ids in the committed ubg.json — that
+// a third party can trace to confirm the guard gates the write. Deterministic (same graph → same
+// object, testable like a `verify` law), and honest: it reports provenance (verified vs asserted)
+// and corroboration (which independent paths agree), never a bare "trust me, it's PROVEN".
+export function buildProofObjects(graph) {
+  const g = indexGraph(graph);
+  const proofs = [];
+  for (const ep of g.entrypoints) {
+    const reached = [...reachOf(ep.id, g.cfOut)]
+      .sort()
+      .map((id) => g.nodes.get(id))
+      .filter(Boolean);
+    const guards = reached.filter((n) => n.kind === 'guard');
+    const writes = [];
+    for (const n of reached)
+      if (n.kind === 'effect')
+        for (const e of g.mutOut.get(n.id) ?? [])
+          writes.push({ effect: n, stateId: e.to });
+    // a proof object is emitted ONLY for a genuinely DISCHARGED obligation: a mutating route
+    // (O1 applies) that actually reaches a guard. A guardless mutation is a FINDING, not a proof.
+    if (!writes.length || !guards.length) continue;
+    const guardInfo = guards
+      .map((gd) => ({
+        guard: gd.label,
+        node: gd.id,
+        // MUST-analysis honesty: 'verified' only when a deny path was SEEN in the body;
+        // an opaque middleware trusted by name is 'asserted' — the proof says which.
+        provenance: gd.meta?.verified ? 'verified' : 'asserted',
+        via: gd.meta?.verifiedVia ?? 'structural',
+      }))
+      .sort((a, b) => cmp(a.node, b.node));
+    proofs.push({
+      obligation: 'GUARDED_MUTATION',
+      route: ep.label,
+      entrypoint: ep.id,
+      discharged_by: {
+        // the obligation is only as strong as its weakest guard: verified iff ALL are verified
+        provenance: guardInfo.every((x) => x.provenance === 'verified')
+          ? 'verified'
+          : 'asserted',
+        corroboratedBy: [...new Set(guardInfo.map((x) => x.via))].sort(),
+        guards: guardInfo.map(({ guard, node, provenance }) => ({
+          guard,
+          node,
+          provenance,
+        })),
+        // the re-checkable path: every id exists in ubg.json; a gate edge links guard→handler,
+        // and the handler control-flow-reaches each listed mutation. Trace it to confirm.
+        deny_path: [ep.id, ...guardInfo.map((x) => x.node)],
+        mutations: [...new Set(writes.map((w) => w.effect.id))].sort(),
+      },
+    });
+  }
+  proofs.sort((a, b) => cmp(a.entrypoint, b.entrypoint));
+  return proofs;
+}
+
 export function reachOf(epId, cfOut) {
   const seen = new Set();
   const queue = [epId];
@@ -100,15 +160,100 @@ export function checkGraph(graph) {
       // sharpens the worst routes (open AND fed by user input) without adding false
       // alarms. Under-approximated (SOUNDNESS Direction 1): a missed tag hides nothing.
       const tainted = writes.filter((w) => w.effect.meta.tainted);
+      // G2 (guard taxonomy families B–D): a public-by-design route whose body checks a
+      // CREDENTIAL and can refuse — a stored-token lookup (reset/invite/verification), a
+      // signature/token verify call, or a webhook/callback handshake — is not "unguarded"
+      // in the critical sense; it is gated by a mechanism the guard model doesn't carry.
+      // The invariant (non-negotiable): this can only DOWNGRADE critical → advisory, with
+      // the mechanism named. It never proves (identity scope stays unproven), never
+      // silences (the finding remains, visible), so it can never make a false PROVEN on
+      // its own — though fewer hard findings CAN promote a clean app; that is the
+      // taxonomy's sanctioned direction (a stored-token reset flow is not a vuln).
+      // Credential/refusal signals reach the entrypoint two ways: from its own middleware chain
+      // (ep.meta.*, set in translate) OR from a body it REACHES through the call graph (the
+      // owner.meta.body* tags — the imported/DI service where the throw actually lives). The
+      // second path is what closes the first-run and API-key false criticals: their refusal sits
+      // in a service method with no effect of its own, so the signal never rode the direct chain.
+      const reachedDenies = reached.some((n) => n?.meta?.bodyDenies);
+      const reachedVerifies = reached.some((n) => n?.meta?.bodyVerifies);
+      const reachedRedirects = reached.some((n) => n?.meta?.bodyRedirects);
+      const credGates = ep.meta?.credentialGates === true || reachedDenies;
+      const credVerify = ep.meta?.credentialVerify === true || reachedVerifies;
+      const credRedirects = ep.meta?.credentialRedirects === true || reachedRedirects;
+      // family A/B: a stored-credential lookup — reset/invite/OTP/magic tokens AND long-lived API
+      // keys / access tokens / personal-access tokens. Same "read the secret, refuse if it doesn't
+      // match" mechanism; only the secret's lifetime differs.
+      const tokenRead = reached.some(
+        (n) =>
+          n?.kind === 'effect' &&
+          n.meta.effectType === 'db_read' &&
+          /token|verif|invite|otp|magic|api[_-]?key|access[_-]?token|credential|personal[_-]?access/i.test(
+            n.meta.table ?? '',
+          ),
+      );
+      const callbackish = /(^|[:/])(callback|webhook|hook)s?([/:]|$)/i.test(ep.label);
+      // family E (first-run / admin-setup): a bootstrap-shaped route — sign-up-admin, setup,
+      // install, onboard, restore/recover — whose body reads an identity table and refuses. The
+      // "only before an admin exists" / "only an admin may" gate. Bounded to bootstrap-shaped
+      // PATHS so an ordinary route's generic "user not found → throw" can never trip it, AND still
+      // requires a real refusal shape below (credGates) to downgrade.
+      const bootstrapish =
+        /(^|[:/\- ])(setup|install|onboard(ing)?|bootstrap|first[-_ ]?run|initiali[sz]e|admin[-_ ]?sign[-_ ]?up|register[-_ ]?admin|restore|recover)([/:\- ]|$)/i.test(
+          ep.label,
+        );
+      const identityRead = reached.some(
+        (n) =>
+          n?.kind === 'effect' &&
+          n.meta.effectType === 'db_read' &&
+          /user|account|admin|member|identit/i.test(n.meta.table ?? ''),
+      );
+      const family = tokenRead
+        ? 'a stored credential-token lookup'
+        : credVerify
+          ? 'a signature/token verification call'
+          : callbackish
+            ? 'a webhook/callback handshake'
+            : bootstrapish && identityRead
+              ? 'a first-run/admin-setup guard'
+              : null;
+      // refusal shapes per family: token/verify/first-run families must throw or 4xx; the callback
+      // family may also refuse by redirecting away (the browser-facing OAuth deny idiom).
+      const credentialGated =
+        family !== null && (credGates || (callbackish && credRedirects));
+      // Class 1 (public-by-design re-label): a route whose PATH is a curated public signature —
+      // login/register/logout, forgot/reset-password, verify-email, oauth/sso/saml, callback/webhook,
+      // health/metrics/.well-known — is *conventionally* meant to run without a session guard. Unlike
+      // the credential families above this carries NO evidence of a gate; it is triage, not proof. So
+      // it only ever RE-LABELS critical → info (`expectedPublic`), names the convention, and says
+      // "confirm intent" — never hidden, never marked safe, never touches PROVEN. The list is the
+      // HEAD of the distribution (deliberately precise, not `**/auth/**` blanket: change-password /
+      // 2fa / session management are NOT public, and re-labeling those would hide a real hole).
+      const expectedPublic =
+        !credentialGated &&
+        (/(^|[:/\- ])(log-?in|sign-?in|sign-?up|register|log-?out|sign-?out|forgot-?password|reset-?password|forgot|verify-?email|email-?verification|confirm-?email|magic-?link|oauth\d?|openid|sso|saml|health(z|check|-?check)?|livez|readyz|metrics|well-known)([/:\- ]|$)/i.test(
+          ep.label,
+        ) ||
+          /\.well-known/i.test(ep.label) ||
+          callbackish);
+      const softened = credentialGated || expectedPublic;
       findings.push({
         rule: 'UNGUARDED_MUTATION',
-        severity: 'critical',
+        severity: softened ? 'info' : 'critical',
+        ...(credentialGated
+          ? { advisory: true, credentialFamily: family }
+          : expectedPublic
+            ? { advisory: true, expectedPublic: true }
+            : {}),
         entrypoint: ep.id,
-        message: `${ep.label} mutates ${fmtStates(writes)} with no guard anywhere on the path${
-          tainted.length ? ' — and request data flows straight into the write' : ''
-        }`,
+        message: credentialGated
+          ? `${ep.label} mutates ${fmtStates(writes)} with no modeled guard — but the body checks ${family} and can refuse; verify that credential's scope covers the mutation`
+          : expectedPublic
+            ? `${ep.label} mutates ${fmtStates(writes)} with no modeled guard — but its path matches a public-by-design signature (auth / oauth / callback / health / metrics); confirm this endpoint is meant to be unauthenticated`
+            : `${ep.label} mutates ${fmtStates(writes)} with no guard anywhere on the path${
+                tainted.length ? ' — and request data flows straight into the write' : ''
+              }`,
         evidence: writes.map((w) => `${w.effect.id} (${locOf(w.effect)})`),
-        ...(tainted.length ? { tainted: true } : {}),
+        ...(tainted.length && !softened ? { tainted: true } : {}),
       });
     }
 
@@ -244,7 +389,18 @@ export function checkGraph(graph) {
     const adminish =
       /(^|[:/])(admin|internal|system|cron|webhooks?|callback)([/:]|$)/i.test(ep.label) ||
       guards.some((gd) => /admin|internal|system|cron|super/i.test(gd?.label ?? ''));
-    if (idScoped.length && !ownerScopedSeen && guards.length && !adminish) {
+    // G1: a call-site ownership assertion on the route (`getXOrThrow({ workspaceId:
+    // workspace.id })`) scopes the object to the caller even when the proof lives in an
+    // imported helper we don't expand — so it clears the BOLA advisory, same as a visible
+    // `ownerScoped` query. Advisory-only, so this can never mask a hard finding.
+    const ownerAsserted = ep.meta?.ownerAsserted === true;
+    if (
+      idScoped.length &&
+      !ownerScopedSeen &&
+      !ownerAsserted &&
+      guards.length &&
+      !adminish
+    ) {
       const tables = [
         ...new Set(idScoped.map((n) => n.meta.table).filter(Boolean)),
       ].sort();

package/src/ubg/extract.js

@@ -831,6 +831,14 @@ export function scanFunction(fnNode, env = {}) {
     calls: [],
     guardSignals: { deniesWithStatus: false },
     validatesInput: false,
+    // O7/BOLA only (G1): the body asserts caller-ownership at a call site
+    // (`getXOrThrow({ workspaceId: workspace.id })`) — an advisory-only signal.
+    ownerAsserted: false,
+    // G2 (guard-taxonomy families B–F): credential-check signals, SEPARATE from
+    // guardSignals on purpose — they may only DOWNGRADE an UNGUARDED_MUTATION critical to
+    // an advisory (never prove a guard, never silence a finding), so widening them can
+    // never fabricate a gate (E-042) or a false PROVEN.
+    credentialSignals: { verifyCall: false, denies4xxOrThrows: false, redirects: false },
     async: Boolean(fnNode?.async),
   };
   if (!fnNode) return result;
@@ -926,6 +934,64 @@ function whereOwnerScoped(whereNode) {
   return scoped;
 }
 
+// Values that reference the caller's VERIFIED identity — the principal a guard puts on the
+// path: dub's `withWorkspace` → `workspace`, a session → `session.user`, `req.user`. Broader
+// than OWNERSHIP_ROOT because it must catch the framework's identity object by its conventional
+// name (the thing a scoped mutation is measured against).
+const IDENTITY_ROOT =
+  /^(workspace|session|auth|user|me|currentuser|actor|viewer|principal|org|organization|team|project|tenant|account|membership)s?$/i;
+// an identity token anywhere in an access path (`req.session.user`, `workspace.id`)
+const IDENTITY_TOKEN =
+  /^(workspace|session|auth|user|me|currentuser|actor|viewer|principal|org|organization|team|project|tenant|account|member|membership)s?$/i;
+// request INPUT the caller controls — never the verified identity, even if named `workspaceId`
+// (`req.body.workspaceId` is an attacker value; matching it would silence a REAL BOLA).
+const REQ_INPUT = /^(body|query|params|input|payload|args|data)$/i;
+function valueIsIdentity(node) {
+  if (!node) return false;
+  if (node.type === 'Identifier') return IDENTITY_ROOT.test(node.name);
+  if (node.type !== 'MemberExpression') return false;
+  // collect every identifier segment of the access path
+  const parts = [];
+  let cur = node;
+  while (cur?.type === 'MemberExpression') {
+    if (cur.property?.type === 'Identifier') parts.push(cur.property.name);
+    cur = cur.object;
+  }
+  if (cur?.type === 'Identifier') parts.push(cur.name);
+  if (parts.some((p) => REQ_INPUT.test(p))) return false; // caller-controlled → not identity
+  return parts.some((p) => IDENTITY_TOKEN.test(p));
+}
+
+// Does this call assert caller-ownership at the site — an argument object binding an ownership
+// KEY to a VERIFIED-IDENTITY value, `getCustomerOrThrow({ workspaceId: workspace.id, id })`?
+// This is the caller stating, before it mutates, that the object it is about to touch is scoped
+// to its own identity — visible WITHOUT resolving the (imported) helper. It feeds ONLY the O7
+// BOLA advisory, never a hard rule, so it can never create a false PROVEN: at worst it silences
+// an advisory the field test wants silenced (dub's ~60 false BOLA are exactly this pattern).
+// the identity object passed to the helper BY NAME — `getDomainOrThrow({ workspace, domain })`
+// hands the whole verified principal, not a `workspaceId:` key.
+const IDENTITY_KEY =
+  /^(workspace|session|user|team|project|tenant|account|org|organization|member|membership|owner|actor|principal)$/i;
+function callAssertsOwnership(node) {
+  for (const arg of node.arguments ?? []) {
+    if (arg?.type !== 'ObjectExpression') continue;
+    for (const p of arg.properties) {
+      if (p.type !== 'ObjectProperty' || p.key?.type !== 'Identifier') continue;
+      // (1) the verified identity handed in by name: `{ workspace, … }` / `{ session }`
+      if (IDENTITY_KEY.test(p.key.name)) return true;
+      // (2) an ownership key bound to the identity OR to a scope-named local (shorthand):
+      // `{ workspaceId: workspace.id }` / `{ workspaceId }`. Same generosity whereOwnerScoped
+      // already grants a `where` key — and O7 is advisory, so it can only silence an advisory.
+      if (
+        OWNERSHIP_KEY.test(p.key.name) &&
+        (valueIsIdentity(p.value) || p.value?.type === 'Identifier')
+      )
+        return true;
+    }
+  }
+  return false;
+}
+
 // does this `where` target a specific object by a bare `id` key (the BOLA shape)?
 function whereHasIdKey(whereNode) {
   if (whereNode?.type !== 'ObjectExpression') return false;
@@ -1021,6 +1087,11 @@ function visit(node, out, ctx) {
     return;
   }
 
+  // G2 credential signal (advisory-only): the body can refuse — any throw, or any 4xx
+  // response. Deliberately BROADER than guardSignals.deniesWithStatus (401/403) because it
+  // can only ever downgrade a critical to an advisory, never verify a guard.
+  if (node.type === 'ThrowStatement') out.credentialSignals.denies4xxOrThrows = true;
+
   // try/catch — try-effects are compensable by catch-effects (SBIR §2.2)
   if (node.type === 'TryStatement') {
     const tryLine = node.loc?.start.line ?? 0;
@@ -1123,9 +1194,42 @@ function inspectCall(node, out, ctx) {
     if (out.returnShapes.length < MAX_RETURN_SHAPES && jsonShape !== null)
       out.returnShapes.push({ line, shape: jsonShape });
     if (deniedStatusOf(node)) out.guardSignals.deniesWithStatus = true;
+    if (statusIn4xx(node)) out.credentialSignals.denies4xxOrThrows = true;
     return;
   }
   if (deniedStatusOf(node)) out.guardSignals.deniesWithStatus = true;
+  if (statusIn4xx(node)) out.credentialSignals.denies4xxOrThrows = true;
+
+  // G1 (O7/BOLA only): a call that asserts caller-ownership at the site scopes the path —
+  // `getCustomerOrThrow({ workspaceId: workspace.id, id })`. Advisory-only, so it can never
+  // create a false PROVEN; it silences the false BOLA the imported ownership helper would raise.
+  if (callAssertsOwnership(node)) out.ownerAsserted = true;
+
+  // G2 (advisory-only): a call whose NAME says it verifies a credential — `verifyUnsubscribeToken`,
+  // `jwt.verify`, an HMAC/signature check. Family B/D of the guard taxonomy. Never a guard by
+  // itself (E-042: a name fabricates nothing) — it only feeds the UNGUARDED downgrade.
+  const verifyName =
+    callee.type === 'Identifier'
+      ? callee.name
+      : callee.type === 'MemberExpression' && callee.property?.type === 'Identifier'
+        ? callee.property.name
+        : '';
+  if (/verify|signature|hmac/i.test(verifyName)) out.credentialSignals.verifyCall = true;
+  // OAuth/browser callbacks refuse by REDIRECTING away (family F) — no throw, no 4xx.
+  // Only ever consulted for callback-shaped routes, and only to downgrade to advisory.
+  if (verifyName === 'redirect') out.credentialSignals.redirects = true;
+  // A named REFUSAL helper is the dominant Next.js / App-Router idiom — the deny is a call like
+  // `responses.notAuthenticatedResponse()` / `unauthorized()` / `throwForbidden()`, never a literal
+  // `res.status(401)` or a bare `throw`, so statusIn4xx and the ThrowStatement check both miss it.
+  // The refusal is real; only its spelling is a helper. Advisory-only (feeds the UNGUARDED
+  // downgrade, never a guard): a route still needs a matching credential FAMILY to downgrade, so a
+  // plain 404 helper on an ordinary route changes nothing.
+  if (
+    /(not_?authenticated|un_?authenticated|not_?authori[sz]ed|un_?authori[sz]ed|forbidden|access_?denied|bad_?request|too_?many_?requests|rate_?limit(ed|_?exceeded)?|missing_?fields|unprocessable|invalid_?(api_?key|token|credential|secret|request|permission))/i.test(
+      verifyName,
+    )
+  )
+    out.credentialSignals.denies4xxOrThrows = true;
 
   // ---- local calls: bare identifier calls → call-graph edges later
   if (callee.type === 'Identifier') {
@@ -1484,6 +1588,45 @@ function isDenyOptions(arg) {
   return false;
 }
 
+// G2 (advisory-only): ANY 4xx refusal — broader than deniedStatusOf's 401/403 on purpose.
+// A stored-token flow refuses with 400/404/410 as often as 401; since this signal can only
+// downgrade a critical to an advisory (never verify a guard), the width is safe.
+function statusIn4xx(node) {
+  const is4xx = (v) => typeof v === 'number' && v >= 400 && v < 500;
+  const inArgs = (args) =>
+    (args ?? []).some(
+      (a) =>
+        a?.type === 'ObjectExpression' &&
+        a.properties.some(
+          (p) =>
+            p.type === 'ObjectProperty' &&
+            p.key?.name === 'status' &&
+            p.value?.type === 'NumericLiteral' &&
+            is4xx(p.value.value),
+        ),
+    );
+  let cur = node;
+  while (cur) {
+    if (cur.type === 'CallExpression') {
+      const m =
+        cur.callee?.type === 'MemberExpression' ? cur.callee.property?.name : null;
+      if (
+        (m === 'status' || m === 'sendStatus') &&
+        cur.arguments[0]?.type === 'NumericLiteral' &&
+        is4xx(cur.arguments[0].value)
+      )
+        return true;
+      if (m === 'json' && inArgs(cur.arguments)) return true;
+    }
+    cur =
+      cur.callee?.type === 'MemberExpression' &&
+      cur.callee.object?.type === 'CallExpression'
+        ? cur.callee.object
+        : null;
+  }
+  return false;
+}
+
 function deniedStatusOf(node) {
   const isDeny = (v) => v === 401 || v === 403;
   // NextResponse.json(_, { status: 401 }) / res.json(_, { status: 403 }) — the deny is

package/src/ubg/passes/state-minimization.js

@@ -73,6 +73,12 @@ function mergeNodes(graph, aId, bId) {
   if (b.meta.returnShapes) {
     a.meta.returnShapes = [...(a.meta.returnShapes ?? []), ...b.meta.returnShapes];
   }
+  // Carry G1/G2 advisory body signals (a credential refusal or an ownership assertion) from the
+  // absorbed node onto the survivor. A thin delegator whose only job is to call a helper that
+  // throws/refuses would otherwise lose that signal at the merge and read as a false critical.
+  // These flags only ever DOWNGRADE a critical to advisory — never prove.
+  for (const k of ['bodyDenies', 'bodyVerifies', 'bodyRedirects', 'ownerAsserted'])
+    if (b.meta[k]) a.meta[k] = true;
 
   const nextEdges = [];
   for (const e of graph.edges) {

package/src/ubg/resolve.js

@@ -39,6 +39,23 @@ export function mergeScan(into, add) {
   into.validatesInput = into.validatesInput || add.validatesInput;
   into.async = into.async || add.async;
   if (add.guardSignals?.deniesWithStatus) into.guardSignals.deniesWithStatus = true;
+  // G1/G2 (advisory-only): a delegated service method that asserts caller-ownership, or refuses on
+  // a credential check (throw/4xx/verify/redirect), carries that signal UP to the handler it is
+  // reached from. Without this a Nest/DI refusal that lives one class away (`this.service.x()`) is
+  // dropped at the merge and its route reads as a false critical — the first-run / admin-setup and
+  // API-key families. These signals can only DOWNGRADE a critical to advisory, never prove.
+  if (add.ownerAsserted) into.ownerAsserted = true;
+  if (add.credentialSignals) {
+    into.credentialSignals ??= {
+      verifyCall: false,
+      denies4xxOrThrows: false,
+      redirects: false,
+    };
+    if (add.credentialSignals.verifyCall) into.credentialSignals.verifyCall = true;
+    if (add.credentialSignals.denies4xxOrThrows)
+      into.credentialSignals.denies4xxOrThrows = true;
+    if (add.credentialSignals.redirects) into.credentialSignals.redirects = true;
+  }
 }
 
 export const relOf = (cwd, abs) => path.relative(cwd, abs).split(path.sep).join('/');

package/src/ubg/translate.js

@@ -204,6 +204,22 @@ function translateRoute(
   for (const cn of chainNodes) {
     if (cn.scan) attachBody(graph, cn.id, cn.scan, helperByName, scanCache, expanded);
   }
+
+  // G1 (O7/BOLA only): if any step on this route asserts caller-ownership at a call site
+  // (`getXOrThrow({ workspaceId: workspace.id })`), the route scopes its objects to the
+  // caller — even when the assertion lives in an imported helper SPARDA doesn't expand.
+  // Advisory-only signal: it silences the false BOLA, never touches a hard rule.
+  if (chainNodes.some((cn) => cn.scan?.ownerAsserted))
+    graph.nodes.get(epId).meta.ownerAsserted = true;
+
+  // G2 (guard taxonomy): credential-check signals from the route's own bodies. Advisory-only —
+  // they can downgrade an UNGUARDED critical to an advisory, never verify a guard.
+  if (chainNodes.some((cn) => cn.scan?.credentialSignals?.verifyCall))
+    graph.nodes.get(epId).meta.credentialVerify = true;
+  if (chainNodes.some((cn) => cn.scan?.credentialSignals?.denies4xxOrThrows))
+    graph.nodes.get(epId).meta.credentialGates = true;
+  if (chainNodes.some((cn) => cn.scan?.credentialSignals?.redirects))
+    graph.nodes.get(epId).meta.credentialRedirects = true;
 }
 
 // A chain step (middleware or handler) becomes a guard or logic node.
@@ -258,6 +274,19 @@ function attachBody(graph, ownerId, scan, helperByName, scanCache, expanded) {
   expanded.add(ownerId);
   const owner = graph.nodes.get(ownerId);
 
+  // G2 propagation (advisory-only): a body that itself refuses on a credential check — throw/4xx,
+  // a verify call, or an OAuth redirect — carries that refusal AT ITS OWN node. This is why the
+  // first-run and API-key gates read as false criticals: their refusal lives in an imported/DI
+  // service method that has no effect of its own, so the signal never rode the entrypoint's direct
+  // middleware chain. Tagging the reached body lets the prover see the mechanism through the call
+  // graph. Reading this tag can only DOWNGRADE a critical to advisory — never prove, never silence,
+  // never fabricate a guard. Tagged once, on first expansion; the node is route-independent.
+  if (owner) {
+    if (scan.credentialSignals?.denies4xxOrThrows) owner.meta.bodyDenies = true;
+    if (scan.credentialSignals?.verifyCall) owner.meta.bodyVerifies = true;
+    if (scan.credentialSignals?.redirects) owner.meta.bodyRedirects = true;
+  }
+
   let order = 0;
   let ordinal = 0;
   const created = []; // effects of THIS body — compensation pairs live here