@vantageos/mcp-doctor 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 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.
+
+## 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.
+
+### Changed
+- The registry has one more detector (46). `tests/__oracle__/oracle-complete-server.static.json`
+  gains one `present` row; no existing row changed.
+
+---
+
 ## 0.3.2 — 2026-10-04
 
 ### Changed — read this if your CI distinguishes exit codes

package/README.md

@@ -51,6 +51,9 @@ usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
   --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)
   --version       print the version and exit
   --help          print this and exit
 
@@ -90,12 +93,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 +120,16 @@ 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 |
+
+**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,13 @@ 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[];
 }
 
 type State = "present" | "absent" | "non-conforming" | "could-not-judge";
@@ -218,6 +238,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 +269,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 +288,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 };