@vantageos/mcp-doctor 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,129 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.6.0 — 2026-10-10
+
+Rebased onto 0.5.0 (S-28, PR #53); this release ships as 0.6.0.
+
+Measured on `vantage-mcp-boilerplate` @ `577c6e0b` (`--mode=static`: 14 non-conforming, 3
+could-not-judge under 0.4.0) and against the standard as merged in ElPi-Corp #241 (`572a8835`) +
+fix-forward #242. Every changed reading below has a RED test committed before its fix and a bite
+mutation on foreign material (`scripts/v050-foreign-bite-probe.sh`).
+
+### Fixed (false positives and blind spots)
+- **C15 reads `annotations: TOOL_ANNOTATIONS`.** An `annotations:` value that is not an inline
+  object is resolved to a `const X = { ... }` in the same file (or the only such definition in the
+  tree; `...SPREAD` entries are followed). Unresolvable (imported from a package, a call, a member
+  access) is `could-not-judge` naming the expression, never "missing hint". The same abstention
+  now protects C-8, C-9, C-10, C-11 and C-13, which read the same annotations window.
+- **DServer14 Element 1 recognises the delegated challenge.** A call to `unauthorizedChallenge(` or
+  `verifyMcpAccessToken(` imported from `@vantageos/cloud-identity` (or its `/resource-server`
+  subpath, multi-line and aliased imports included) with the result's `status` and `WWW-Authenticate`
+  header forwarded — in the same module or another — is the 401 challenge. A delegation call whose
+  forwarding is not readable is `could-not-judge`. The kit's verifier also counts as the RS256/JWKS
+  verification (Element 4). A same-named function imported from another package is not a delegation.
+- **DServer14 Element 2 reads a PRM route registered through a constant**
+  (`for (const path of PRM_PATHS) app.get(path, ...)`), a blind spot that Element 1 had been masking.
+- **C19 reads the description forms servers actually write:** a `+` concatenation of literals across
+  lines, a template literal without expressions, and a string holding the other quote character
+  (`"the caller's org"` ended the literal at the apostrophe). A `description:` whose value is not
+  readable (a call, an interpolated template) is `could-not-judge` naming it. A tool's window now
+  stops at the previous tool's call, so a neighbour's description is never claimed.
+- **D10 reads `description_fr:` with the literal on the next line,** a `+` concatenation, or an
+  identifier bound to a same-tree `const X = "..."`. Any other value (`t(locale, ...)`, a call) stays
+  `could-not-judge` and the reason now names the form.
+- **The code mask lexes JSX/TSX.** In `.tsx`/`.jsx` files a `<` at an expression position opens an
+  element; the text between tags is not code, `/>` is not a regex, an apostrophe in JSX text is not a
+  string. `src/ui/entry.tsx` no longer reads "brackets never balance". A file that ends inside an
+  unterminated JSX element, template literal or block comment is now unreadable (fail closed) instead
+  of having its tail swallowed.
+- **D16 recognises the SDK v2 server construction.** `new McpServer({ name, version })` whose
+  `version` is read from `package.json` (directly, or through a `const` bound to a statement that
+  reads `package.json`'s `.version`, in any file) is the observable version: the SDK serves it on
+  `server/discover` and `initialize`. The verdict is `[static read]` and declares the residual
+  (pre-auth reachability of the SDK transport is the dynamic half). A literal version, or an
+  identifier bound to anything else, is not credited.
+
+### Fixed (measured on vantage-peers `mcp-server` @ `2f0e5469`, Sigma's triage)
+- **D2 stateless: a header NAME in a CORS list is not session keying.** Every `mcp-session-id` mention
+  is classified: a keying form (a `sessionIdGenerator` other than `undefined`, the header read or
+  written by call or index, sent as an object key, or a store keyed by a session id) is
+  `non-conforming`; a CORS `allowHeaders` / `exposeHeaders` entry is inert and named in the verdict;
+  anything else is `could-not-judge` naming the site. The old oracle fixture, which was only CORS
+  lists, now carries a real generator.
+- **DServer6 reports every site and resolves literal values.** It returned on its first match; it now
+  lists all sites (Forms A, B, C, D). A name match whose value is proven a literal constant
+  (`HOSTNAME = "0.0.0.0"` reached through `server.hostname`) is not a finding and is named as not
+  counted; an unresolved value is kept and says "identifier-name match, value unresolved". A call is
+  never resolved.
+- **C17 reads the repository-root workflows.** For a package scanned as a subdirectory the check
+  walks from the scan root up to the git root (the nearest `.git`) and reads that
+  `.github/workflows`; it never reads above the git root and never leaves the scanned tree when
+  there is no `.git`.
+- **C25 recognises a build identity on `/health`.** A `/health` handler that serves `version` and a
+  derived `commit` (or any C25 identity key) beside it is the build identity of the tree served; a
+  hand-written literal there is red.
+- **Registration wrappers (`defineTool(...)`).** A function whose body calls `registerTool` / `.tool`
+  (directly or through a local alias) with one of its own parameters as the tool name is a
+  registration wrapper; the parameter index is derived, and the literal at that index of every call
+  is a tool name (a constant bound to a string literal is resolved; anything else is an unresolved
+  site, as before). The tool's annotations are read from its call, its description from the argument
+  the wrapper forwards, and the wrapper's own internal `registerTool(name, ...)` is no longer
+  reported as an unresolved tool. C8-C13, C15, C19 and DServer2 judge those tools instead of
+  abstaining.
+
+### Corrected after review (PR #54)
+- **C17 reads a publish step, nothing else.** Provenance is an actual package-manager `publish`
+  invocation carrying `--provenance` (YAML/shell comments stripped, `\` continuations joined) or
+  `publishConfig.provenance: true`. A comment that names the flag and the `id-token: write`
+  permission (necessary for OIDC, attests nothing) are no longer a claim.
+- **C15: a one-line constant closes on its own line.** `const PING_ANN = { title: "x" };` no longer
+  reads on into the next constant and borrows its hints. A tool whose own `annotations: X` is an
+  expression reads only X; the sibling-attribution fix now has a test that fails without it.
+- **C15 reads spreads in order.** In `annotations: { ...CONST, key: value }` a later member
+  overrides the spread (`key: undefined` un-declares a hint, a boolean keeps it); a spread that
+  cannot be resolved is `could-not-judge` naming it.
+- **C25 resolves a constant.** `commit: GIT_SHA` with `const GIT_SHA = "deadbeef"` is the same
+  hand-written literal and stays red.
+
+### Changed (rule changes from the merged standard)
+- **D7:** conformant when the tree depends on `@modelcontextprotocol/server` >= 2 and no result
+  builder is written by hand (`resultType` / `ttlMs` / `cacheScope` spelled in source, outside the
+  SDK's `cacheHints` option). The protocol-kit requirement applies only to hand-rolled builders:
+  SDK v2 plus a hand-rolled builder and no kit is `non-conforming` at the builder. A dependency range
+  that is a tag (`latest`) is `could-not-judge`. SDK v1 / no SDK keeps the 0.4.0 `absent`.
+- **C-17 non-CI path.** A package published without CI has no npm provenance; the standard accepts the
+  `npm pack` shasum the reviewer reproduced and read back at the registry. **Proposed evidence form —
+  the reviewer rules:** one line `Provenance: <pkg>@<version> npm-pack shasum <40-hex> reproduced by
+  <who>, read back from the registry <date>` in `PROVENANCE`, `PROVENANCE.md`, `CHANGELOG.md` or
+  `README.md`, naming `<pkg>@<version>` equal to `package.json`'s `name@version`. A record for another version or
+  another package, one that names only a version, or one with no 40-hex shasum, is
+  `non-conforming` and says why. Without `--provenance` and without a record it is
+  still `non-conforming`. Whether the shasum equals the registry's `dist.shasum` stays the gate.
+- **C-18 identifies the server manifest by content.** A root `mcp.json` carrying `mcpServers` is the
+  OpenAI plugin config, not the server manifest; the server manifest is the root file (`mcp.json` or
+  `mcp-server.json`) carrying capabilities + transport + version. `non-conforming` when no root file
+  qualifies (the verdict says why `mcp.json` did not count) and when two root files each qualify.
+- **S-5 package rule (DServer14):** `non-conforming` on a shipped dependency (`dependencies`,
+  `peerDependencies`, `optionalDependencies`) on `@vantageos/mcp-auth-kit`, or on
+  `@vantageos/cloud-identity` whose lowest admissible version is below 0.15.0; a range whose floor
+  cannot be read (`latest`) is `could-not-judge`. The import-subpath half of S-5 is not read.
+- **DLocalIdentity: minting is not resolving the caller.** Sites that sign or mint (`new SignJWT`,
+  `jwt.sign`, `importPKCS8`, `createPrivateKey`, `importJWK` of a private key) and the claims written
+  into a signing chain's payload are listed under `MINTING/SIGNING` and never counted. Local signature
+  verification (`jwtVerify`, `createLocalJWKSet`, ...) and raw claim reads that identify the caller
+  stay violations whoever issued the token: there is no issuer carve-out.
+
+### Also
+- **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.
+- **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.5.0 — unreleased
 
 ### Added — S-28, a tool forwards the verified claim of its caller (standard `bacc54a`)

package/README.md

@@ -119,10 +119,10 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D4** CacheableResult | `ttlMs` / `cacheScope` on the list/read result types | present / absent |
 | **D5** server/discover | a `server/discover` handler is registered (absence-based, with a positive control) | present / absent |
 | **D6** mcp-apps ui-key | MCP Apps UI key is the GA nested `_meta.ui.resourceUri` — not flat `ui/resourceUri`, not community `io.modelcontextprotocol/ui` | GA-nested / flat-deprecated / community-nonGA / none |
-| **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 |
+| **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. Conformant too on `@modelcontextprotocol/server` >= 2 with no hand-rolled result builder (the kit is required only where builders are written by hand) |
 | **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 |
+| **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth; an SDK v2 `new McpServer({ name, version })` carrying a `package.json`-derived version counts (pre-auth reach is the dynamic half) | 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. Minting/signing sites (`new SignJWT`, `jwt.sign`, a private-key import) are listed as `MINTING/SIGNING` and not counted; verification and claim reads stay violations whoever issued the token (no issuer carve-out). | 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
@@ -134,6 +134,25 @@ not UTF-8 text, is `could-not-judge`. To adopt the rule on a tree that still hol
 `--local-identity-ceiling=<current count>` as a ratchet; the row then reads `present` and still lists
 every site.
 
+**Reading rules, 0.6.0** (each changed detector; details and rationale in [CHANGELOG.md](./CHANGELOG.md)).
+- **C15 / C8 / C9 / C10 / C11 / C13** resolve `annotations: SOME_CONST` to a same-tree `const` object; an
+  unresolvable value is `could-not-judge`, never "missing".
+- **C19** counts `"a" + "b"`, an expression-free template literal and apostrophe-bearing strings as a
+  declared description; **D10** reads `description_fr:` with the literal on the next line or a const.
+- **DServer14** accepts a 401 challenge delegated to `@vantageos/cloud-identity`
+  (`unauthorizedChallenge` / `verifyMcpAccessToken`, status + header forwarded), a PRM route registered
+  through a path constant, and is red on `@vantageos/mcp-auth-kit` or `cloud-identity` below 0.15.0.
+- **C17** accepts, without CI, a `Provenance: <pkg>@<version> npm-pack shasum <40-hex> ...` record naming the
+  published version (**proposed evidence form, reviewer rules**); **C18** identifies the server manifest by
+  content (`mcpServers` = OpenAI plugin config; the manifest is `mcp-server.json` then) and is red on two.
+- **D2** names `mcp-session-id` in a CORS list as inert and flags only real session keying;
+  **DServer6** reports every site and does not count a name whose value is a literal constant;
+  **C17** reads the repository-root `.github/workflows` for a subpackage; **C25** accepts a derived
+  `commit` served on `/health` beside `version`; a project-local registration wrapper
+  (`defineTool(...)`) is derived from the function that forwards a parameter to `registerTool`, so its
+  tools are judged.
+- **TSX/JSX files** are lexed; a file that ends inside an unterminated JSX element is unreadable, not skipped.
+
 **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
 lives in `src/detectors/index.ts`. No count is written here on purpose: a number typed into a README