@vantageos/mcp-doctor 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,19 +3,14 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## Unreleased
+## 0.5.0 — unreleased
 
-### Changed
-- **DLocalIdentity exemption marker renamed** `local-identity-exempt:` -> `allow-local-identity:`
-  (standard R-57), reason of 8 characters or more (was 10). The old spelling no longer exempts.
-
-### Added
-- **DLocalIdentity, third REVISE (PR #52):** reported now are `claimedName` (and any
-  `caller*`/`actor*`/`acting*`/`claimed*` property) compared to an agent's `.name`;
-  `switch (row.createdBy) { case caller: }`; `[caller].includes(row.createdBy)` and
-  `new Set([caller]).has(...)`; `a.localeCompare(b) === 0` on names or tenants; a primitive
-  imported or destructured under an alias (`import { createHash as h }`). Implemented as regex
-  matchers, not an AST: `typescript` is a devDependency only and the report contract is line-based.
+### Added — S-28, a tool forwards the verified claim of its caller (standard `bacc54a`)
+- **`S-28 claim-forwarded`** (`src/detectors/s28-claim-forwarded.ts`), the MCP half of the door audit's cause 1: every MCP caller reaches the backend as one service account, so a tool that does not forward the claim it holds leaves the door nothing to confine to. For each `<client>.query|mutation|action("<module>:<fn>", args)` it reads the call's argument text, the helpers it spreads or attaches (resolved in the tree), the refusal that precedes the call in the same handler, and the backend door list. Red: a call to a door that is not an exit and resolves its caller, with no `verifiedOrg` / `verifiedPerson` in it (a `verifiedActor` added by a wrapped client covers only a bearer that resolved an agent), or one forwarded only through an optional helper with no refusal before the call. Green: the claim is forwarded (and refused-without through an optional helper), or the door is service-account-only / `fleet-wide:` (read from the door). Could-not-judge: no backend found, a door the backend does not define, a door named by an expression, a door whose own source shows no caller resolution. Absent: no Convex client imported at all.
+- **New option `--backend=<convex-dir>`** (and `RunDoctorOptions.backend`, `Tree.backendRoot`, `loadTree(root, backendRoot?)`): the backend source whose door list S-28 reads. Default: the nearest `convex/` (holding a `schema.ts`) above the scanned tree.
+- **Pin.** ElPi-Corp `bacc54a53d5f6f9f20e5254908e2b46807902faa` on `main`, `resources/references/mcp-server-standard.md` blob `fe30518`: the merged S-28 text of ElPi-Corp #239. Its merge commit `7d7df89` was left off `main` by the 2026-10-10 history rewrite; `bacc54a` is its rewritten counterpart and carries the same file blob (as do `7d7df89` and the PR head `6f7794e`, the former pin). Later `main` commits amend other rules and leave S-28 unchanged.
+- Tests: `tests/s28-claim-forwarded.test.ts`. Real material: vantage-peers `16f09070ffd49488ad65b12ec2f8026865d4ab5d` (the commit the door audit measured), `tools.ts` + `verifiedActor.ts` and ten `convex/` modules vendored byte-exact in `fixtures/s28-vp-16f0907/`.
+- Version 0.5.0 (0.4.0 shipped DLocalIdentity, PR #52). The registry has one more detector (47); the oracle snapshot gains one `absent` row, no existing row changed.
 
 ## 0.4.0 — 2026-10-09
 
@@ -46,10 +41,20 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   stylesheet, `authorize.ts:373`) is not reported. A keyed `createHmac`, and any digest of a value the
   caller supplied, stay sites.
 - Measured on vantage-peers `mcp-server/src` at `8fb7c12`: 33 sites, exit 1.
+- **DLocalIdentity, third REVISE (PR #52):** reported now are `claimedName` (and any
+  `caller*`/`actor*`/`acting*`/`claimed*` property) compared to an agent's `.name`;
+  `switch (row.createdBy) { case caller: }`; `[caller].includes(row.createdBy)` and
+  `new Set([caller]).has(...)`; `a.localeCompare(b) === 0` on names or tenants; a primitive
+  imported or destructured under an alias (`import { createHash as h }`). Implemented as regex
+  matchers, not an AST: `typescript` is a devDependency only and the report contract is line-based.
 
 ### Changed
 - The registry has one more detector (46). `tests/__oracle__/oracle-complete-server.static.json`
   gains one `present` row; no existing row changed.
+- **DLocalIdentity exemption marker renamed** `local-identity-exempt:` -> `allow-local-identity:`
+  (standard R-57), reason of 8 characters or more (was 10). The old spelling no longer exempts.
+- Fix-forward (0.5.0): the third-REVISE items above and the marker rename were first logged under
+  `Unreleased`, but shipped in 0.4.0 (npm `@vantageos/mcp-doctor@0.4.0`, gitHead `16a7531`); moved here.
 
 ---
 

package/README.md

@@ -46,7 +46,7 @@ The path is the root of the MCP server sources (the folder holding `server.ts` /
 The binary's own `--help` is the authority; this is what it prints:
 
 ```
-usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
+usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both] [--backend=<convex-dir>]
 
   --mode=static   read the tree only (default)
   --mode=dynamic  launch the server and judge what it serves
@@ -54,6 +54,8 @@ usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
   --local-identity-ceiling=N
                   local identity primitives tolerated before DLocalIdentity
                   fails (default 0)
+  --backend=DIR   the backend source (a convex/ dir) whose door list S-28 reads;
+                  default: the nearest convex/ above the tree
   --version       print the version and exit
   --help          print this and exit
 
@@ -121,6 +123,7 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D15** cache-coherence | Server Rule 15 — every tool-set mutation (RegisteredTool `.enable/.disable/.update/.remove`, `unregisterTool`) is correlated with a `notifications/tools/list_changed` emission | present / absent / non-conforming / could-not-judge |
 | **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth | present / absent / non-conforming / could-not-judge |
 | **DLocalIdentity** no-local-identity | No MCP server defines its own identity primitive: resolving a caller to a tenant or agent (local JWT verify, a populated allow-list attached to a bearer), asserting org membership or role, filtering rows by caller scope (`fromAllowList`, a name allow-list, a row's `orgId` or acting-name field such as `createdBy` / `assignedTo` compared to the caller's, by `===`, `==`, `Object.is` or after `toLowerCase()`), or validating a credential (local `timingSafeEqual`, a digest of a presented value, HMAC; a hash over a static literal is not a site). A call to a binding imported from `@vantageos/cloud-identity` is not a site. | present (0, or EXEMPT) / non-conforming (count > ceiling, default 0) / could-not-judge |
+| **S-28** claim-forwarded | Server complement S-28 (standard `bacc54a`) — a tool forwards the verified claim of its caller (`verifiedOrg` / `verifiedPerson`) to every backend door it calls and refuses when it holds none. Reads each `<client>.query\|mutation\|action` call, the helpers it spreads, the refusal before it, and the backend source's door list (`--backend=<convex-dir>`, else the nearest `convex/` above the tree). A door that is service-account-only or declared `fleet-wide:` needs no claim; no backend found, an unknown door, a computed door name are could-not-judge. | present / non-conforming / could-not-judge / absent (no Convex client imported) |
 
 **DLocalIdentity exemptions.** Two, both reported as `EXEMPT` rather than hidden: the
 `@vantageos/cloud-identity` package itself (read from the target's `package.json` name), and a site

package/dist/doctor.d.ts

@@ -43,6 +43,13 @@ interface Tree {
      * configured list: the report states what was walked past, not what could be.
      */
     skippedDirs: SkippedDir[];
+    /**
+     * The backend source root (a `convex/` directory) a detector may read the
+     * backend's door list from. Set by the caller (`--backend=<dir>`); when unset a
+     * detector that needs it looks for the nearest `convex/` above `root` and says
+     * so when it finds none. Unset means "not supplied", never "no backend".
+     */
+    backendRoot?: string;
 }
 
 type State = "present" | "absent" | "non-conforming" | "could-not-judge";
@@ -217,6 +224,8 @@ declare function isLiveDetector(d: Detector | LiveDetector): d is LiveDetector;
 type RunMode = "static" | "dynamic" | "both";
 interface RunDoctorOptions {
     mode?: RunMode;
+    /** The backend source root (`convex/`) a detector reads the backend's door list from (S-28). */
+    backend?: string;
 }
 /**
  * Run every detector against the target.

package/dist/doctor.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/doctor.ts
-import { readFileSync as readFileSync12, realpathSync } from "fs";
-import { dirname as dirname11, join as join19, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync13, realpathSync } from "fs";
+import { dirname as dirname12, join as join20, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/scan.ts
@@ -114,11 +114,12 @@ function findPackageJson(startDir) {
   }
   return null;
 }
-function loadTree(root) {
+function loadTree(root, backendRoot) {
   const st = statSync(root);
   const baseDir = st.isDirectory() ? root : dirname(root);
   const filePaths = [];
   const tree = { root, files: [], packageJson: null, skippedDirs: [] };
+  if (backendRoot !== void 0) tree.backendRoot = backendRoot;
   if (st.isDirectory()) walk(root, filePaths, (d) => recordSkip(tree, d, root));
   else if (root.endsWith(".ts") || root.endsWith(".tsx")) filePaths.push(root);
   tree.files = filePaths.map((p) => loadFile(p, baseDir));
@@ -7215,6 +7216,436 @@ var dServer14 = {
   }
 };
 
+// src/detectors/s28-claim-forwarded.ts
+import { existsSync as existsSync15, readFileSync as readFileSync11, readdirSync as readdirSync7, statSync as statSync8 } from "fs";
+import { dirname as dirname10, join as join18, relative as relative4 } from "path";
+var PIN11 = "bacc54a53d5f6f9f20e5254908e2b46807902faa";
+var CLAIM_TOKEN = /\bverified(?:Org|Person)\b/;
+var ANY_CLAIM = /\bverified(?:Actor|Org|Person)\b/g;
+var CALL_RE = /\b([A-Za-z_$][\w$]*)\s*\.\s*(query|mutation|action)\s*\(/g;
+var GUARD_RE = /\b(?:unresolved\w*Denial|requireVerified\w+|requireClaim\w*)\s*\(|verified-org-unresolved/;
+var FLEET_WIDE = /fleet-wide:\s*\S[^\n]{7,}/;
+var SCOPE_MARKERS = /\bwithOrgScope\b|\brequireAuthenticatedCaller\b|\bresolveInboxReader\b|\bresolveVerified\w*\b|\brequireScope\b|\bgetUserIdentity\b|\bisMaster\b|\bscope\b/;
+var ACTOR_SET_RE = /\bconst\s+(VERIFIED_\w*DOORS)\b[^=]*=\s*new\s+Set\s*(?:<[^>]*>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/;
+function masked(file) {
+  const out = [];
+  for (const line of file.lines) {
+    let row = "";
+    for (let c = 0; c < line.raw.length; c++) {
+      const ch = line.raw[c];
+      row += ch === " " || ch === "	" || ch === "\r" || isCodeAt(file, line.n, c) ? ch : " ";
+    }
+    out.push(row);
+  }
+  return out.join("\n");
+}
+function rawText(file) {
+  return file.lines.map((l) => l.raw).join("\n");
+}
+function lineAt(text, offset) {
+  let n = 1;
+  for (let i = 0; i < offset && i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+var OPEN = { "(": ")", "[": "]", "{": "}" };
+function matchClose(m, open) {
+  const stack = [];
+  for (let i = open; i < m.length; i++) {
+    const ch = m[i];
+    if (OPEN[ch] !== void 0) stack.push(OPEN[ch]);
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      if (stack.pop() !== ch) return -1;
+      if (stack.length === 0) return i;
+    }
+  }
+  return -1;
+}
+function splitTop(m, from, to) {
+  const parts = [];
+  let depth = 0;
+  let start = from;
+  for (let i = from; i < to; i++) {
+    const ch = m[i];
+    if (OPEN[ch] !== void 0) depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+    else if (ch === "," && depth === 0) {
+      parts.push([start, i]);
+      start = i + 1;
+    }
+  }
+  if (start < to && m.slice(start, to).trim() !== "") parts.push([start, to]);
+  return parts;
+}
+function listTs(dir, out = []) {
+  let names;
+  try {
+    names = readdirSync7(dir);
+  } catch {
+    return out;
+  }
+  for (const n of names) {
+    if (n === "node_modules" || n === "_generated" || n === "__tests__") continue;
+    const p = join18(dir, n);
+    let st;
+    try {
+      st = statSync8(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) listTs(p, out);
+    else if (n.endsWith(".ts") && !n.endsWith(".test.ts") && !n.endsWith(".d.ts")) out.push(p);
+  }
+  return out;
+}
+function discoverBackend(root) {
+  let dir = root;
+  try {
+    if (!statSync8(root).isDirectory()) dir = dirname10(root);
+  } catch {
+    return void 0;
+  }
+  for (let up = 0; up < 5; up++) {
+    const cand = join18(dir, "convex");
+    if (existsSync15(join18(cand, "schema.ts"))) return cand;
+    const parent = dirname10(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return void 0;
+}
+function readDoors(backendRoot) {
+  const doors = /* @__PURE__ */ new Map();
+  for (const path of listTs(backendRoot)) {
+    let text;
+    try {
+      text = readFileSync11(path, "utf8");
+    } catch {
+      continue;
+    }
+    const file = {
+      path,
+      rel: relative4(backendRoot, path),
+      lines: text.split("\n").map((raw, i) => ({ n: i + 1, raw, comment: false }))
+    };
+    const m = masked(file);
+    const module = relative4(backendRoot, path).replace(/\.ts$/, "").split("\\").join("/");
+    const re = /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:query|mutation|action)\s*\(/g;
+    for (let hit = re.exec(m); hit; hit = re.exec(m)) {
+      const open = hit.index + hit[0].length - 1;
+      const close = matchClose(m, open);
+      if (close < 0) continue;
+      let start = hit.index;
+      const lines = text.slice(0, start).split("\n");
+      let k = lines.length - 2;
+      while (k >= 0 && (lines[k].trim() === "" || /^\s*(\/\/|\/\*|\*)/.test(lines[k])) && lines.length - 2 - k < 60)
+        k--;
+      start = lines.slice(0, k + 1).join("\n").length;
+      const region = text.slice(start, close + 1);
+      const mRegion = m.slice(hit.index, close + 1);
+      const claims = [];
+      const am = /\bargs\s*:\s*/.exec(mRegion);
+      if (am) {
+        const at = hit.index + am.index + am[0].length;
+        let argsText = "";
+        if (m[at] === "{") argsText = text.slice(at, matchClose(m, at) + 1);
+        else {
+          const id = /^[A-Za-z_$][\w$]*/.exec(m.slice(at));
+          if (id) {
+            const dm = new RegExp(`\\bconst\\s+${id[0]}\\b[^=]*=\\s*`).exec(m);
+            if (dm) {
+              let p = dm.index + dm[0].length;
+              if (m.slice(p).startsWith("v.object(")) p += "v.object(".length;
+              if (m[p] === "{") argsText = text.slice(p, matchClose(m, p) + 1);
+            }
+          }
+        }
+        for (const c of argsText.match(ANY_CLAIM) ?? []) if (!claims.includes(c)) claims.push(c);
+      }
+      let exit;
+      if (/\brequireServiceAccount\b/.test(mRegion))
+        exit = "service-account-only (requireServiceAccount)";
+      else if (/\brequireResolvedCaller\s*\([^)]*masterOnly[^)]*mcpBoundOnly|\brequireResolvedCaller\s*\([^)]*mcpBoundOnly[^)]*masterOnly/s.test(
+        mRegion
+      ))
+        exit = "service-account-only (requireResolvedCaller masterOnly+mcpBoundOnly)";
+      else {
+        const fw = FLEET_WIDE.exec(region);
+        if (fw) exit = `fleet-wide declaration (${fw[0].slice(11).trim().slice(0, 80)})`;
+      }
+      doors.set(`${module}:${hit[1]}`, {
+        claims,
+        exit,
+        resolvesCaller: SCOPE_MARKERS.test(mRegion)
+      });
+    }
+  }
+  return doors;
+}
+function definitionOf(name, files) {
+  const esc = name.replace(/\$/g, "\\$");
+  const re = new RegExp(`(?:\\b(?:const|let|var)\\s+${esc}\\b|\\bfunction\\s+${esc}\\b)`);
+  for (const f of files) {
+    const hit = re.exec(f.m);
+    if (!hit) continue;
+    let depth = 0;
+    for (let i = hit.index + hit[0].length; i < f.m.length; i++) {
+      const ch = f.m[i];
+      if (OPEN[ch] !== void 0) {
+        depth++;
+      } else if (ch === ")" || ch === "]" || ch === "}") {
+        depth--;
+        if (depth === 0 && ch === "}" && /\bfunction\b/.test(hit[0]))
+          return { mask: f.m.slice(hit.index, i + 1) };
+      } else if (ch === ";" && depth === 0 && !/\bfunction\b/.test(hit[0])) {
+        return { mask: f.m.slice(hit.index, i + 1) };
+      }
+      if (depth < 0) break;
+    }
+    return { mask: f.m.slice(hit.index, Math.min(f.m.length, hit.index + 1500)) };
+  }
+  return void 0;
+}
+function readHelper(name, files, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (seen.has(name) || depth > 3) return { forwards: false, optional: false };
+  seen.add(name);
+  const def = definitionOf(name, files);
+  if (!def) return { forwards: false, optional: false };
+  let forwards = CLAIM_TOKEN.test(def.mask);
+  const optional = /:\s*\{\s*\}|return\s*\{\s*\}|\?\?\s*\{\s*\}/.test(def.mask);
+  if (!forwards) {
+    for (const c of def.mask.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+      const sub = readHelper(c[1], files, seen, depth + 1);
+      if (sub.forwards) {
+        forwards = true;
+        break;
+      }
+    }
+  }
+  return { forwards, optional };
+}
+function toolNameBefore(text, offset) {
+  const head = text.slice(0, offset);
+  const open = Math.max(head.lastIndexOf("defineTool("), head.lastIndexOf("registerTool("));
+  if (open >= 0) {
+    const m = /^\s*"([a-z][a-z0-9_]*)",?\s*$/m.exec(head.slice(open));
+    if (m) return { name: m[1], start: open };
+    const r = /registerTool\(\s*"([a-z][a-z0-9_]*)"/.exec(head.slice(open));
+    if (r) return { name: r[1], start: open };
+    return { name: void 0, start: open };
+  }
+  const lines = head.split("\n");
+  const back = Math.max(0, lines.length - 120);
+  return { name: void 0, start: lines.slice(0, back).join("\n").length };
+}
+function scanS28(tree) {
+  const scan = { violate: [], conform: [], cnj: [], calls: 0, backend: void 0 };
+  const backendRoot = tree.backendRoot ?? discoverBackend(tree.root);
+  scan.backend = backendRoot;
+  const doors = backendRoot ? readDoors(backendRoot) : void 0;
+  const files = tree.files.map((f) => ({ f, text: rawText(f), m: masked(f) }));
+  const actorDoors = /* @__PURE__ */ new Set();
+  for (const { text } of files) {
+    const hit = ACTOR_SET_RE.exec(text);
+    if (hit) for (const s of hit[2].matchAll(/["'`]([\w/]+:[\w]+)["'`]/g)) actorDoors.add(s[1]);
+  }
+  for (const { f, text, m } of files) {
+    for (let hit = CALL_RE.exec(m); hit; hit = CALL_RE.exec(m)) {
+      const recv = hit[1];
+      if (!/convex|client/i.test(recv)) continue;
+      const open = hit.index + hit[0].length - 1;
+      const close = matchClose(m, open);
+      if (close < 0) continue;
+      scan.calls++;
+      const line = lineAt(text, hit.index);
+      const tool = toolNameBefore(text, hit.index);
+      const parts = splitTop(m, open + 1, close);
+      let door;
+      if (parts[0]) {
+        const rawFirst = text.slice(parts[0][0], parts[0][1]);
+        const lit = /^\s*(?:\/\/[^\n]*\n\s*)*["'`]([\w/]+:[\w]+)["'`]/.exec(rawFirst);
+        const ref = /^\s*(?:api|internal)\.([\w]+)\.([\w]+)/.exec(rawFirst);
+        if (lit) door = lit[1];
+        else if (ref) door = `${ref[1]}:${ref[2]}`;
+      }
+      const site = (note) => ({
+        file: f.rel,
+        line,
+        door: door ?? "?",
+        tool: tool.name,
+        note
+      });
+      if (door === void 0) {
+        scan.cnj.push(
+          site(
+            "the door is named by an expression the scan cannot resolve (not statically resolvable)"
+          )
+        );
+        continue;
+      }
+      const argText = parts[1] ? m.slice(parts[1][0], parts[1][1]) : "";
+      const region = m.slice(tool.start, hit.index);
+      const regionRaw = text.slice(tool.start, hit.index);
+      const guard = GUARD_RE.test(region) || GUARD_RE.test(regionRaw);
+      let direct = CLAIM_TOKEN.test(argText);
+      let viaHelper;
+      let virtual = argText;
+      const bare = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(argText);
+      if (bare && !direct) {
+        const v = bare[1].replace(/\$/g, "\\$");
+        const pieces = [];
+        for (const a of region.matchAll(new RegExp(`Object\\.assign\\s*\\(\\s*${v}\\s*,`, "g"))) {
+          const o = a.index + a[0].length - 1;
+          const c = matchClose(region, region.lastIndexOf("(", o));
+          pieces.push(region.slice(o, c < 0 ? o + 400 : c));
+        }
+        for (const a of region.matchAll(
+          new RegExp(`\\b${v}\\.verified(?:Org|Person|Actor)\\b`, "g")
+        ))
+          pieces.push(a[0]);
+        const decl = new RegExp(`\\b(?:const|let)\\s+${v}\\b[^=]*=\\s*\\{`).exec(region);
+        if (decl) {
+          const o = decl.index + decl[0].length - 1;
+          const c = matchClose(region, o);
+          pieces.push(region.slice(o, c < 0 ? o + 600 : c + 1));
+        }
+        virtual = pieces.join("\n");
+        direct = CLAIM_TOKEN.test(virtual);
+      }
+      if (!direct) {
+        for (const sp of virtual.matchAll(/\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+          const h = readHelper(sp[1], files);
+          if (h.forwards) {
+            viaHelper = h;
+            break;
+          }
+        }
+        if (!viaHelper) {
+          for (const sp of virtual.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(\s*\)/g)) {
+            const h = readHelper(sp[1], files);
+            if (h.forwards) {
+              viaHelper = h;
+              break;
+            }
+          }
+        }
+      }
+      if (direct) {
+        scan.conform.push(site("forwards the verified claim in the call"));
+        continue;
+      }
+      if (viaHelper) {
+        if (viaHelper.optional && !guard) {
+          scan.violate.push(
+            site(
+              "forwards its claim through an optional helper (it returns {} when the bearer holds none) and no refusal precedes the call in the handler: a bearer with no resolvable organisation is sent claimless"
+            )
+          );
+        } else {
+          scan.conform.push(
+            site(
+              viaHelper.optional ? "forwards the verified claim through a helper and refuses before the call when it holds none" : "forwards the verified claim through a helper"
+            )
+          );
+        }
+        continue;
+      }
+      if (!doors) {
+        scan.cnj.push(
+          site(
+            "forwards no verified claim and no backend source was found above the scanned tree (no convex/ with a schema.ts, and no backend root given): whether the door is an exit cannot be read"
+          )
+        );
+        continue;
+      }
+      const info = doors.get(door);
+      if (!info) {
+        scan.cnj.push(
+          site(
+            `forwards no verified claim and the door ${door} is not defined in the supplied backend (${backendRoot})`
+          )
+        );
+        continue;
+      }
+      if (info.exit) {
+        scan.conform.push(site(`needs no claim: the door is ${info.exit}`));
+        continue;
+      }
+      if (!info.resolvesCaller) {
+        scan.cnj.push(
+          site(
+            `forwards no verified claim and the door ${door} shows no caller resolution in its own source (its scope comes from a helper or a run call that this scan does not follow)`
+          )
+        );
+        continue;
+      }
+      const accepts = info.claims.length > 0 ? `the door accepts ${info.claims.join(", ")} and the tool omits it` : "the door accepts no claim argument, so R-54 must add one before the tool can forward it";
+      const actorNote = actorDoors.has(door) ? "; verifiedActor is added by the wrapped client only for a bearer that resolved an agent, and a bearer that resolved no agent (a seat or person token, an org-level token) is sent claimless" : "";
+      scan.violate.push(site(`forwards no verified claim \u2014 ${accepts}${actorNote}`));
+    }
+  }
+  return scan;
+}
+function fmt(s) {
+  return `${s.file}:${s.line} ${s.door} ${s.tool ? `[${s.tool}] ` : ""}(${s.note})`;
+}
+var S28_ID = "S-28 claim-forwarded";
+var s28ClaimForwarded = {
+  id: S28_ID,
+  rule: "S-28",
+  pin: PIN11,
+  run(tree) {
+    const s = scanS28(tree);
+    const breakdown = `[conform=${s.conform.length} non-conforming=${s.violate.length} could-not-judge=${s.cnj.length}]`;
+    const list = (xs) => xs.slice(0, 5).map(fmt).join("; ");
+    if (s.violate.length > 0) {
+      const first = s.violate[0];
+      return {
+        id: S28_ID,
+        anchor: `${first.file}:${first.line}`,
+        state: "non-conforming",
+        verdict: `S-28: ${s.violate.length} backend call(s) VIOLATE (a tool forwards the verified claim of its caller to every backend door it calls, and refuses when it has none). ${breakdown} Violations: ${list(s.violate)}${s.violate.length > 5 ? `; +${s.violate.length - 5} more` : ""}.${s.cnj.length ? ` could-not-judge calls (a verdict is owed): ${list(s.cnj)}.` : ""}`
+      };
+    }
+    if (s.cnj.length > 0) {
+      const reason2 = `S-28: ${s.cnj.length} backend call(s) could not be judged \u2014 ${list(s.cnj)}. This is NOT a clean bill. ${breakdown}`;
+      return {
+        id: S28_ID,
+        anchor: `${s.cnj[0].file}:${s.cnj[0].line}`,
+        state: "could-not-judge",
+        verdict: reason2,
+        reason: reason2
+      };
+    }
+    if (s.conform.length > 0) {
+      return {
+        id: S28_ID,
+        anchor: `${s.conform[0].file}:${s.conform[0].line}`,
+        state: "present",
+        verdict: `S-28: ${s.conform.length} backend call(s) forward the verified claim or call a door that needs none; 0 violations. ${breakdown} Conform: ${list(s.conform)}.`
+      };
+    }
+    const usesBackend = tree.files.some(
+      (f) => f.lines.some((l) => !l.comment && /\bConvexHttpClient\b|from\s+["']convex\//.test(l.raw))
+    );
+    if (!usesBackend) {
+      return {
+        id: S28_ID,
+        anchor: "source:no-backend-client",
+        state: "absent",
+        verdict: `S-28: no Convex client is imported anywhere in the ${tree.files.length} file(s) read; no backend door is called, so there is no claim to forward (rule out of subject).`
+      };
+    }
+    const reason = `S-28: no applicable site \u2014 a Convex client is imported but none of the ${s.calls} <client>.query|mutation|action call(s) read names a door statically. NOT a clean bill.`;
+    return {
+      id: S28_ID,
+      anchor: "source:no-applicable-site",
+      state: "could-not-judge",
+      verdict: reason,
+      reason
+    };
+  }
+};
+
 // src/detectors/index.ts
 var detectors = [
   d2,
@@ -7248,6 +7679,7 @@ var detectors = [
   c22TestRatioGate,
   c25BuildIdentity,
   c26SubpackageLockfile,
+  s28ClaimForwarded,
   dServer2,
   dServer6,
   dDebugOptIn,
@@ -7267,18 +7699,18 @@ var detectors = [
 
 // src/runtime/launch.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync15, readFileSync as readFileSync11, statSync as statSync8 } from "fs";
-import { dirname as dirname10, isAbsolute, join as join18, resolve } from "path";
+import { existsSync as existsSync16, readFileSync as readFileSync12, statSync as statSync9 } from "fs";
+import { dirname as dirname11, isAbsolute, join as join19, resolve } from "path";
 function findPackageDir(target) {
   let dir;
   try {
-    dir = statSync8(target).isDirectory() ? target : dirname10(target);
+    dir = statSync9(target).isDirectory() ? target : dirname11(target);
   } catch {
     return null;
   }
   for (let depth = 0; depth < 8; depth++) {
-    if (existsSync15(join18(dir, "package.json"))) return dir;
-    const parent = dirname10(dir);
+    if (existsSync16(join19(dir, "package.json"))) return dir;
+    const parent = dirname11(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -7302,10 +7734,10 @@ function deriveLaunchPlan(target) {
   }
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync11(join18(pkgDir, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync12(join19(pkgDir, "package.json"), "utf8"));
   } catch (err) {
     return {
-      error: `could not parse ${join18(pkgDir, "package.json")}: ${err instanceof Error ? err.message : String(err)}`
+      error: `could not parse ${join19(pkgDir, "package.json")}: ${err instanceof Error ? err.message : String(err)}`
     };
   }
   const bin = firstBinEntry(pkg.bin);
@@ -7383,10 +7815,10 @@ function readEvalCounts(target) {
   if (!pkgDir) return counts;
   let dir = pkgDir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = join18(dir, "evals", "evals.json");
-    if (existsSync15(candidate)) {
+    const candidate = join19(dir, "evals", "evals.json");
+    if (existsSync16(candidate)) {
       try {
-        const parsed = JSON.parse(readFileSync11(candidate, "utf8"));
+        const parsed = JSON.parse(readFileSync12(candidate, "utf8"));
         for (const c of parsed.cases ?? []) {
           if (c && typeof c.tool === "string") counts.set(c.tool, (counts.get(c.tool) ?? 0) + 1);
         }
@@ -7394,7 +7826,7 @@ function readEvalCounts(target) {
       }
       return counts;
     }
-    const parent = dirname10(dir);
+    const parent = dirname11(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -7402,7 +7834,7 @@ function readEvalCounts(target) {
 }
 function statSyncSafe(p) {
   try {
-    return statSync8(p).isDirectory();
+    return statSync9(p).isDirectory();
   } catch {
     return false;
   }
@@ -7525,7 +7957,7 @@ function runDoctor(target, detectorList = detectors, opts = {}) {
 }
 function runDoctorReport(target, detectorList = detectors, opts = {}) {
   const mode = opts.mode ?? "static";
-  const tree = loadTree(target);
+  const tree = loadTree(target, opts.backend);
   const needsRuntime = mode !== "static" && detectorList.some((d) => typeof d.runDynamic === "function");
   const runtime = needsRuntime ? launchAndIntrospect(target) : null;
   const results = [];
@@ -7654,7 +8086,7 @@ function computeExitCode(results) {
   return 0;
 }
 var USAGE = [
-  "usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]",
+  "usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both] [--backend=<convex-dir>]",
   "",
   "  --mode=static   read the tree only (default)",
   "  --mode=dynamic  launch the server and judge what it serves",
@@ -7662,6 +8094,8 @@ var USAGE = [
   "  --local-identity-ceiling=N",
   "                  local identity primitives tolerated before DLocalIdentity",
   "                  fails (default 0)",
+  "  --backend=DIR   the backend source (a convex/ dir) whose door list S-28 reads;",
+  "                  default: the nearest convex/ above the tree",
   "  --version       print the version and exit",
   "  --help          print this and exit",
   "",
@@ -7669,8 +8103,8 @@ var USAGE = [
 ].join("\n");
 function readVersion() {
   try {
-    const here = dirname11(fileURLToPath(import.meta.url));
-    const manifest = JSON.parse(readFileSync12(join19(here, "..", "package.json"), "utf8"));
+    const here = dirname12(fileURLToPath(import.meta.url));
+    const manifest = JSON.parse(readFileSync13(join20(here, "..", "package.json"), "utf8"));
     return manifest.version ?? null;
   } catch {
     return null;
@@ -7692,6 +8126,7 @@ function main() {
     return;
   }
   const modeArg = args.find((a) => a.startsWith("--mode="));
+  const backendArg = args.find((a) => a.startsWith("--backend="));
   const target = args.find((a) => !a.startsWith("--"));
   if (!target) {
     console.error(USAGE);
@@ -7714,7 +8149,11 @@ function main() {
     const ratchet = makeLocalIdentity({ ceiling });
     detectorList = detectors.map((d) => d === localIdentity ? ratchet : d);
   }
-  const { results, skipped } = runDoctorReport(target, detectorList, { mode });
+  const backend = backendArg ? backendArg.slice("--backend=".length) : void 0;
+  const { results, skipped } = runDoctorReport(target, detectorList, {
+    mode,
+    ...backend !== void 0 ? { backend } : {}
+  });
   console.log(renderTable(target, results, skipped));
   process.exitCode = computeExitCode(results);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-doctor",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Static MCP conformance checker: audits an MCP server source tree against the MCP 2026-07-28 standard and emits a conformance-diff table (file:line | present | absent | non-conforming | verdict).",
   "type": "module",
   "main": "./dist/doctor.js",