candor-ts 0.36.1 → 0.36.2

package/README.md

@@ -249,3 +249,26 @@ node scan.mjs <dir | file.ts | tsconfig.json> --out .candor/report   # scan a pr
 The pure cores are factored into importable modules — `query-core.mjs` (the §3.1 queries),
 `policy.mjs` (the §6.2 DSL + literal matchers), and `scan-core.mjs` (the classifier + the SQL/
 command/host extractors) — so they're unit-tested directly; the TS-compiler-driven walk stays in `scan.mjs`.
+
+## Agents: install candor as an MCP server
+
+`candor-ts` ships candor's read-only query surface as an MCP server, so an agent asks *"what is the
+blast radius of changing this?"* or *"what reaches the network?"* and gets a deterministic answer from a
+precomputed report instead of grepping for it.
+
+```bash
+npx -y candor-ts --mcp        # the server, over stdio
+candor mcp install            # or let the umbrella write/merge .mcp.json for you
+```
+
+Registration instructions come from **the package you already installed** — `candor mcp --help` prints
+the `.mcp.json` snippet and the `claude mcp add` line, and `candor mcp install` writes them. There is no
+remote file to fetch, tamper with, or auto-execute, and nothing here tells an agent to run anything it
+did not already choose to install.
+
+Discovery is passive: the manifest is [`server.json`](server.json), published to the official
+[MCP Registry](https://registry.modelcontextprotocol.io) so clients and directories can find candor
+without being handed a script. The registry verifies namespace ownership through the marker below.
+
+mcp-name: io.github.tombaldwin/candor
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.36)",
   "type": "module",
   "dependencies": {

package/scan.mjs

@@ -108,6 +108,27 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
   process.exit(0);
 }
 
+// --mcp: a MODE, in the same place and for the same reason as --version above — it hands the process
+// to the MCP server so the ONE bin the MCP Registry can invoke (`npx -y candor-ts`) is able to serve.
+//
+// WHY A FLAG AND NOT A BARE `mcp` SUBCOMMAND, which is what ebman does. This script takes its scan
+// target POSITIONALLY, so `candor-ts mcp` would be ambiguous with a directory literally named `mcp` —
+// and a registry-invoked server runs in whatever repo the client happens to be in, where that
+// directory may well exist. A flag cannot collide with a path. The ambiguity would be rare and silent,
+// which is the combination worth designing out rather than documenting.
+//
+// spawnSync rather than `await import("./mcp.mjs")`: an import would RUN the server and then fall
+// through into this file's own argument walk when it returned. Handing the child our stdio and
+// exiting on its status keeps the two programs separate, which is what the transport needs anyway.
+if (process.argv.includes("--mcp")) {
+  const { spawnSync } = await import("node:child_process");
+  const { fileURLToPath } = await import("node:url");
+  const server = fileURLToPath(new URL("./mcp.mjs", import.meta.url));
+  const rest = process.argv.slice(2).filter((a) => a !== "--mcp");
+  const r = spawnSync(process.execPath, [server, ...rest], { stdio: "inherit" });
+  process.exit(r.status ?? 0);
+}
+
 // -h / --help: a print-and-exit MODE (like --version), handled before the arg walk so `-h` (a single
 // dash) is never mistaken for the scan target by the positional fallthrough below.
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -7143,8 +7164,27 @@ function visitCalls(node) {
           // a connected socket). `post/put/patch/delete/head/options` cover the axios/got/undici tier whose
           // URL is the call arg (sweep [18]); `dgram.send(buf,port,host)` is added module-aware below (UDP
           // has no connect, so send carries the destination — sweep [12]).
+          // SOUNDNESS R410 — THE RESOLVER FAMILY WAS MISSING, and its absence is a GATE BYPASS, not a
+          // missed disclosure. `dns.resolve` classifies Net (see the κ table below), so a resolver call
+          // carries the effect while contributing NO host; with this list not naming it, nothing marked
+          // the surface incomplete and a benign sibling `fetch("https://api.stripe.com")` certified a
+          // caller-controlled DNS target — `allow Net api.stripe.com` exit 0, measured, with the
+          // sibling-free control correctly caught by AS-EFF-008. Written as the WHOLE family rather than
+          // the spelling in hand (R346): every node `dns` resolver, the `dns/promises` twins (same names)
+          // and the `Resolver` class methods, which share these member names.
+          //
+          // NOTE THE SHAPE PROBLEM THIS DOES NOT FIX. This set is an INCLUSION list, so forgetting a
+          // member UNDER-reports — the opposite of `FS_USE_VERBS`/`EXEC_USE_VERBS` below, where
+          // forgetting over-charges and is safe. That asymmetry is the defect class itself: java's Net
+          // is sound precisely because it uses the general rule (any Net call contributing no visible
+          // host leaves the surface incomplete) rather than a list. The durable repair is to INVERT this
+          // into a use-verb denylist beside the other two; that is a wider change with its own
+          // over-charge bill to price, so it is filed rather than smuggled in here.
           const NET_ESTABLISHING = new Set(["request", "get", "post", "put", "patch", "delete", "head",
-            "options", "connect", "createConnection", "fetch"]);
+            "options", "connect", "createConnection", "fetch",
+            "lookup", "lookupService", "reverse", "resolve", "resolve4", "resolve6", "resolveAny",
+            "resolveCname", "resolveCaa", "resolveMx", "resolveNaptr", "resolveNs", "resolvePtr",
+            "resolveSoa", "resolveSrv", "resolveTxt"]);
           // Fs/Exec USE-verbs whose LOCATOR was fixed earlier, not an arg of THIS call — so a missing literal
           // here is the legitimate split-construct/use shape, never the masking signal (the establishing-
           // allowlist discipline, generalized from Net to all 4 effects; sweep [11]). Fs: the fd/FileHandle