@vantageos/mcp-doctor 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.5.0 — unreleased
+
+### 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
+
+### Added
+- **`DLocalIdentity no-local-identity` — a local identity primitive in an MCP server is a violation.**
+  Operator order 2026-10-09: no application, MCP server or starter defines its own primitive for
+  resolving a caller to a tenant, asserting membership of an organisation, filtering rows by a
+  caller's scope, or validating a master credential; identity lives only in
+  `@vantageos/cloud-identity`. The detector reports every site as `file:line` with its category and
+  enclosing declaration: local JWT verification (`jwtVerify`, `createRemoteJWKSet`, `jwt.verify`),
+  raw claim reads (`payload.org_id`), a populated `fromAllowList` attached locally, role comparisons,
+  name allow-lists (`fromAllowList.includes`, `roster.includes`, `isInAllowList`, iteration over a
+  roster), tenant row filters (`row.orgId === caller.orgSlug`), and local credential checks
+  (`timingSafeEqual`, `createHash("sha256")`, `createHmac`, `subtle.digest("SHA-256")`). A call
+  whose callee is bound from `@vantageos/cloud-identity` is not a site.
+- **EXEMPT, reported:** the `@vantageos/cloud-identity` package itself, and a site justified by
+  `// allow-local-identity: <reason ≥ 8 chars>`. **COULD-NOT-JUDGE:** a file that is not UTF-8
+  text or whose brackets never balance.
+- **`--local-identity-ceiling=N`** (default 0). One site over the ceiling is `non-conforming`
+  (exit 1); at or under it the row reads `present` and still lists every site.
+- Name and tenant compares are caught in every spelling: `===`, `!==`, `==`, `!=`, `Object.is`,
+  bracket reads, and case-folded or normalised operands (`toLowerCase()`, `normalize()`). Acting-name
+  fields (`createdBy`, `assignedTo`, `from`, `recipient`, `callerOrchestrator`, `orchestrator`, ...) are
+  compared to each other or to a caller name; an operand that is `undefined`, `null`, a boolean or a
+  number is a presence test and is not a site.
+- A digest over static content is not a credential digest: `subtle.digest` / `createHash().update`
+  over a string literal or a module-level constant made of literals (the CSP hash of a static
+  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.
+
+---
+
 ## 0.3.2 — 2026-10-04
 
 ### Changed — read this if your CI distinguishes exit codes

package/README.md

@@ -46,11 +46,16 @@ 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
   --mode=both     both, dynamic findings taking precedence
+  --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
 
@@ -90,12 +95,18 @@ green on 0.2.0 was green because nothing ran. Expect findings on the first run o
 ## Programmatic use
 
 ```ts
-import { runDoctor, renderTable } from "@vantageos/mcp-doctor";
+import { runDoctorReport, renderTable } from "@vantageos/mcp-doctor";
 
-const results = runDoctor("./mcp-server");
-console.log(renderTable("./mcp-server", results));
+const { results, skipped } = runDoctorReport("./mcp-server");
+console.log(renderTable("./mcp-server", results, skipped));
 ```
 
+`skipped` is the list of directories the run actually walked past (`node_modules`, `dist`, test
+material...), recorded by the walks as they skip them. `renderTable` prints it as the
+"skipped directories" section, so a report never reads as full coverage of a narrowed scope. Pass it
+through; called with two arguments, `renderTable` prints a "NOT REPORTED" line in its place.
+`runDoctor(target)` still returns the results alone.
+
 ## What it checks (MCP 2026-07-28)
 
 Each detector maps one standard item and is proven **bipolar** on real material: a genuine defect
@@ -111,6 +122,17 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D7** protocol-kit | `@vantageos/mcp-protocol-kit` listed in `package.json` **and actually called** (builder invoked, not merely declared) | listed+called / listed-not-called / hand-rolled |
 | **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
+carrying `// allow-local-identity: <reason of 8 characters or more>` on the line, in the comment
+block directly above it, or above its enclosing top-level declaration. A marker with a shorter reason,
+or the retired `local-identity-exempt:` spelling, is not a justification and the site stays a violation. A file whose brackets never balance, or that is
+not UTF-8 text, is `could-not-judge`. To adopt the rule on a tree that still holds sites, pass
+`--local-identity-ceiling=<current count>` as a ratchet; the row then reads `present` and still lists
+every site.
 
 **This table is a sample, not the inventory.** Every registered detector runs on every invocation,
 so the authoritative list is simply the output of a run — one row per detector. The registered set

package/dist/doctor.d.ts

@@ -10,6 +10,19 @@ interface SourceFile {
     rel: string;
     lines: SourceLine[];
 }
+/** A directory a walk declined to descend into, recorded AS the walk skipped it. */
+interface SkippedDir {
+    /** Path relative to the walk root, `/`-separated. */
+    path: string;
+    /** Why the canonical list excludes this directory name. */
+    reason: string;
+    /**
+     * Set only by a walk that probed the skipped directory for its own candidate
+     * inputs (C-26: a deploy-config file). Names the first candidate found there,
+     * relative to the walk root. Unset means "not probed", never "nothing there".
+     */
+    candidate?: string;
+}
 interface Tree {
     root: string;
     files: SourceFile[];
@@ -23,6 +36,20 @@ interface Tree {
         json: Record<string, unknown>;
         unreadable?: string;
     } | null;
+    /**
+     * Directories skipped on THIS run, recorded by the walks as they skip them
+     * (deduplicated by path). Mutable on purpose: a detector that walks the tree
+     * itself records into it through `recordSkip`. Never derived from the
+     * 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";
@@ -197,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.
@@ -218,6 +247,15 @@ interface RunDoctorOptions {
  * `detectorList` is injectable for tests; production uses the full registry.
  */
 declare function runDoctor(target: string, detectorList?: Detector[], opts?: RunDoctorOptions): DetectorResult[];
+/**
+ * `runDoctor` plus the directories the run ACTUALLY skipped, read from the tree
+ * AFTER the detectors ran (a detector that walks the tree records its own skips
+ * into it). This is what the report's skipped-directories section prints.
+ */
+declare function runDoctorReport(target: string, detectorList?: Detector[], opts?: RunDoctorOptions): {
+    results: DetectorResult[];
+    skipped: SkippedDir[];
+};
 /**
  * Async runner — the ADDITIVE extension for *dynamique* rules that must CALL a
  * running server. It is a superset of the sync `runDoctor` static path, never a
@@ -240,7 +278,13 @@ declare function runDoctorAsync(target: string, opts?: {
     session?: Session;
     detectorList?: (Detector | LiveDetector)[];
 }): Promise<DetectorResult[]>;
-declare function renderTable(surface: string, results: DetectorResult[]): string;
+/**
+ * The skipped-directories section. A skipped directory narrows the scope of the
+ * run, and a report that does not say so reads as full coverage. Always
+ * rendered: an empty list says "none", it is never omitted.
+ */
+declare function renderSkipped(skipped: SkippedDir[]): string;
+declare function renderTable(surface: string, results: DetectorResult[], skipped?: SkippedDir[]): string;
 /**
  * The process exit code a run's results carry, three-way with precedence:
  *   1 — a VIOLATION: at least one detector is `non-conforming` (something IS
@@ -253,4 +297,4 @@ declare function renderTable(surface: string, results: DetectorResult[]): string
  */
 declare function computeExitCode(results: DetectorResult[]): number;
 
-export { type LiveDetector, type RunDoctorOptions, type RunMode, type Session, computeExitCode, isLiveDetector, renderTable, runDoctor, runDoctorAsync };
+export { type LiveDetector, type RunDoctorOptions, type RunMode, type Session, computeExitCode, isLiveDetector, renderSkipped, renderTable, runDoctor, runDoctorAsync, runDoctorReport };