harden: validate containment depth, loopback range, and test coverage

Add realpath-safe validate reads, broken-symlink rejection, 127.0.0.0/8
loopback token policy, expanded DML/format tests, and consumer-surface parity.

Author: SutuSebastian

.changeset/read-surface-hardening.md

@@ -2,4 +2,4 @@
 "@stainless-code/codemap": patch
 ---
 
-Harden read surfaces: `codemap query --format …` blocks index mutations via the same read-only guard as `--json`; `codemap serve` requires `--token` when `--host` is not loopback; `codemap validate` (and MCP/HTTP `validate`) can return `rejected` rows with a `reason` when a path escapes the project root or resolves outside via symlink.
+Harden read surfaces: `codemap query --format …` blocks index mutations via the same read-only guard as `--json`; `codemap serve` requires `--token` when `--host` is not loopback (any `127.0.0.0/8` address counts as loopback, so `--token` stays optional on `127.0.0.2` and similar); `codemap validate` (and MCP/HTTP `validate`) can return `rejected` rows with a `reason` when a path escapes the project root, resolves outside via symlink, or is a broken symlink — output `path` keys are always project-relative POSIX paths.

docs/architecture.md

@@ -125,7 +125,7 @@ CI-aggregate flag on `codemap query` and `codemap audit`. Aliases `--format sari
 
 ### `codemap validate`
 
-CLI subcommand comparing on-disk SHA-256 against `files.content_hash`. Statuses: `stale | missing | unindexed | rejected` (`rejected` carries optional `reason` when a path escapes the project root or resolves outside via symlink). Exits `1` on any drift.
+CLI subcommand comparing on-disk SHA-256 against `files.content_hash`. Statuses: `stale | missing | unindexed | rejected` (`rejected` carries optional `reason` when a path escapes the project root, resolves outside via symlink, or has a broken symlink; output `path` keys are always project-relative POSIX paths). Exits `1` on any drift.
 
 ### `module_cycles` (table) / circular imports
 
@@ -565,7 +565,7 @@ Long-running process that subscribes to filesystem changes via [chokidar v5](htt
 
 ### `codemap serve` / HTTP server
 
-Long-running HTTP server exposing the same tool taxonomy as `codemap mcp` over `POST /tool/{name}` for non-MCP consumers (CI scripts, simple `curl`, IDE plugins that don't speak MCP). Default bind **`127.0.0.1:7878`** (loopback only — refuse `0.0.0.0` unless explicitly opted in via `--host 0.0.0.0`); `--token <secret>` is optional on loopback binds and **required** on non-loopback binds — when set, every request needs `Authorization: Bearer <secret>`. HTTP returns each tool's native JSON payload directly (NOT MCP's `{content: [...]}` wrapper); `query` / `query_recipe` match `codemap query --json` row arrays unless `summary` / `group_by` reshape the envelope, or `baseline` returns a diff envelope (incompatible with non-`json` `format` / `group_by`; save/list/drop remain separate tools); parity twins (`query batch`, `trace`, `explore`, `node`, `file`, `schema`, `symbols`, `context`, `ingest-coverage`, `ingest-churn`) always emit JSON on CLI without `--json`; other tools match their CLI `--json` payloads when that flag is set; `format: "sarif"` payloads ship as `application/sarif+json`, `format: "annotations"` / `"mermaid"` / `"diff"` / `"badge"` (markdown) as `text/plain; charset=utf-8`, `format: "diff-json"` / `"codeclimate"` / `"badge"` + `badge_style: "json"` as `application/json; charset=utf-8`. Routes: `POST /tool/{name}` (every MCP tool), `GET /resources/{encoded-uri}` (resource handler for `codemap://recipes`, `codemap://recipes/{id}`, `codemap://schema`, `codemap://skill`, `codemap://rule`, `codemap://mcp-instructions`, `codemap://files/{path}`, and `codemap://symbols/{name}`), `GET /health` (auth-exempt liveness probe — does not start the watcher), `GET /tools` / `GET /resources` (catalogs). With `--watch`, chokidar is refcount-gated per request and stops 5s after the last client (`HTTP_WATCH_RELEASE_GRACE_MS`) — distinct from MCP idle shutdown; the HTTP process keeps listening. Pure transport — same `tool-handlers.ts` / `resource-handlers.ts` MCP uses; no engine duplication. Errors → `{"error": "..."}` with HTTP status 400 / 401 / 403 / 404 / 500. SIGINT / SIGTERM → graceful drain. Every response carries `X-Codemap-Version: <semver>`. **CSRF + DNS-rebinding guard:** every request (including auth-exempt `/health`) is evaluated against `Sec-Fetch-Site` / `Origin` / `Host` when present — modern browsers send `Sec-Fetch-Site` and `Origin` on cross-origin fetches (header presence varies by request type, browser, and privacy settings), so the guard rejects browser-driven cross-origin requests like a malicious local webpage `fetch`-ing `http://127.0.0.1:7878/tool/save_baseline` to mutate `.codemap/index.db`. `Host` mismatch on a loopback bind blocks DNS rebinding (an attacker resolving `evil.com` to `127.0.0.1` post-load). Non-browser clients (curl, fetch from Node, MCP hosts, CI scripts) typically omit these headers and pass through. Implementation: `src/cli/cmd-serve.ts` (CLI shell) + `src/application/http-server.ts` (transport). See [`architecture.md` § HTTP wiring](./architecture.md#cli-usage).
+Long-running HTTP server exposing the same tool taxonomy as `codemap mcp` over `POST /tool/{name}` for non-MCP consumers (CI scripts, simple `curl`, IDE plugins that don't speak MCP). Default bind **`127.0.0.1:7878`** (loopback only — refuse `0.0.0.0` unless explicitly opted in via `--host 0.0.0.0`; any **`127.0.0.0/8`** address counts as loopback for the token rule); `--token <secret>` is optional on loopback binds and **required** on non-loopback binds — when set, every request needs `Authorization: Bearer <secret>`. HTTP returns each tool's native JSON payload directly (NOT MCP's `{content: [...]}` wrapper); `query` / `query_recipe` match `codemap query --json` row arrays unless `summary` / `group_by` reshape the envelope, or `baseline` returns a diff envelope (incompatible with non-`json` `format` / `group_by`; save/list/drop remain separate tools); parity twins (`query batch`, `trace`, `explore`, `node`, `file`, `schema`, `symbols`, `context`, `ingest-coverage`, `ingest-churn`) always emit JSON on CLI without `--json`; other tools match their CLI `--json` payloads when that flag is set; `format: "sarif"` payloads ship as `application/sarif+json`, `format: "annotations"` / `"mermaid"` / `"diff"` / `"badge"` (markdown) as `text/plain; charset=utf-8`, `format: "diff-json"` / `"codeclimate"` / `"badge"` + `badge_style: "json"` as `application/json; charset=utf-8`. Routes: `POST /tool/{name}` (every MCP tool), `GET /resources/{encoded-uri}` (resource handler for `codemap://recipes`, `codemap://recipes/{id}`, `codemap://schema`, `codemap://skill`, `codemap://rule`, `codemap://mcp-instructions`, `codemap://files/{path}`, and `codemap://symbols/{name}`), `GET /health` (auth-exempt liveness probe — does not start the watcher), `GET /tools` / `GET /resources` (catalogs). With `--watch`, chokidar is refcount-gated per request and stops 5s after the last client (`HTTP_WATCH_RELEASE_GRACE_MS`) — distinct from MCP idle shutdown; the HTTP process keeps listening. Pure transport — same `tool-handlers.ts` / `resource-handlers.ts` MCP uses; no engine duplication. Errors → `{"error": "..."}` with HTTP status 400 / 401 / 403 / 404 / 500. SIGINT / SIGTERM → graceful drain. Every response carries `X-Codemap-Version: <semver>`. **CSRF + DNS-rebinding guard:** every request (including auth-exempt `/health`) is evaluated against `Sec-Fetch-Site` / `Origin` / `Host` when present — modern browsers send `Sec-Fetch-Site` and `Origin` on cross-origin fetches (header presence varies by request type, browser, and privacy settings), so the guard rejects browser-driven cross-origin requests like a malicious local webpage `fetch`-ing `http://127.0.0.1:7878/tool/save_baseline` to mutate `.codemap/index.db`. `Host` mismatch on a loopback bind blocks DNS rebinding (an attacker resolving `evil.com` to `127.0.0.1` post-load). Non-browser clients (curl, fetch from Node, MCP hosts, CI scripts) typically omit these headers and pass through. Implementation: `src/cli/cmd-serve.ts` (CLI shell) + `src/application/http-server.ts` (transport). See [`architecture.md` § HTTP wiring](./architecture.md#cli-usage).
 
 ### Code Climate format (`codeclimate`)
 

docs/glossary.md

@@ -31,8 +31,8 @@ codemap serve --host 0.0.0.0
   → parseServeRest: require --token when !isLoopbackHost(host)
 
 codemap validate <paths>
-  → computeValidateRows → rejectValidatePath
-      → pathEscapesProjectRoot | pathTraversesSymlinkOutsideRoot → status rejected
+  → computeValidateRows → rejectUnsafeProjectRelativePath / readUtf8WithinProjectRoot
+      → pathEscapesProjectRoot | pathTraversesSymlinkOutsideRoot | realpath → status rejected
 ```
 
 ---
@@ -46,7 +46,7 @@ codemap validate <paths>
 | 2.1 | `isLoopbackHost` + non-loopback `--token` required         | **done**    | `bun test src/cli/cmd-serve.test.ts`                |
 | 2.2 | Serve tests updated                                        | **done**    | same                                                |
 | 3.1 | `pathTraversesSymlinkOutsideRoot`, `resolvePathWithinRoot` | **done**    | `bun test src/application/path-containment.test.ts` |
-| 3.2 | `validate` `rejected` + `rejectValidatePath`               | **done**    | `bun test src/cli/cmd-validate.test.ts`             |
+| 3.2 | `validate` `rejected` + safe read containment              | **done**    | `bun test src/cli/cmd-validate.test.ts`             |
 | 3.3 | Test `../../../etc/passwd` → `rejected`                    | **done**    | same                                                |
 | 1.x | `docs/architecture.md` lift                                | **done**    | `bun run format:check`                              |
 | 1.s | Commit + PR + CI                                           | **pending** | `bun run check` (committed; PR + CI open)           |

docs/plans/security-hardening-wave1.md

@@ -267,7 +267,7 @@ function registerValidateTool(server: McpServer): void {
     "validate",
     withToolAnnotations("validate", {
       description:
-        "Compare on-disk SHA-256 of indexed files to the indexed `files.content_hash` column. Returns only out-of-sync rows with status `stale` / `missing` / `unindexed` / `rejected` (fresh paths omitted; `rejected` includes optional `reason` when a path escapes the project root or resolves outside via symlink). Empty `paths` validates every indexed file. Useful for 'codemap doctor' agents that diagnose a stale index before issuing structural queries.",
+        "Compare on-disk SHA-256 of indexed files to the indexed `files.content_hash` column. Returns only out-of-sync rows with status `stale` / `missing` / `unindexed` / `rejected` (fresh paths omitted; `rejected` includes optional `reason`: path escapes project root | path escapes via symlink | path resolves outside project root). Output `path` keys are project-relative POSIX paths. Empty `paths` validates every indexed file. Useful for 'codemap doctor' agents that diagnose a stale index before issuing structural queries.",
       inputSchema: validateArgsSchema,
     }),
     (args) => wrapToolResult(handleValidate(args)),

src/application/mcp-server.ts

@@ -3,9 +3,13 @@ import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { canCreateSymlinks } from "../test/symlink-capable";
 import {
+  pathRealpathEscapesProjectRoot,
   pathTraversesSymlinkOutsideRoot,
   projectRelativePathFromResolved,
+  readUtf8WithinProjectRoot,
+  rejectUnsafeProjectRelativePath,
   resolvePathWithinRoot,
 } from "./path-containment";
 
@@ -24,46 +28,131 @@ describe("projectRelativePathFromResolved", () => {
   });
 });
 
+const symlinkCapable = canCreateSymlinks();
+
 describe("pathTraversesSymlinkOutsideRoot", () => {
-  it("returns false for symlinks that stay inside the project root", () => {
-    const root = mkdtempSync(join(tmpdir(), "codemap-symlink-in-"));
-    writeFileSync(join(root, "real.ts"), "export const x = 1;\n");
-    symlinkSync(join(root, "real.ts"), join(root, "link.ts"));
-    expect(pathTraversesSymlinkOutsideRoot(root, join(root, "link.ts"))).toBe(
-      false,
-    );
+  it.skipIf(!symlinkCapable)(
+    "returns false for symlinks that stay inside the project root",
+    () => {
+      const root = mkdtempSync(join(tmpdir(), "codemap-symlink-in-"));
+      writeFileSync(join(root, "real.ts"), "export const x = 1;\n");
+      symlinkSync(join(root, "real.ts"), join(root, "link.ts"));
+      expect(pathTraversesSymlinkOutsideRoot(root, join(root, "link.ts"))).toBe(
+        false,
+      );
+    },
+  );
+
+  it.skipIf(!symlinkCapable)(
+    "returns true when a path component symlinks outside the project root",
+    () => {
+      const base = mkdtempSync(join(tmpdir(), "codemap-symlink-out-"));
+      const root = join(base, "proj");
+      const outside = join(base, "outside");
+      mkdirSync(root, { recursive: true });
+      mkdirSync(outside, { recursive: true });
+      writeFileSync(join(outside, "secret.ts"), "export const s = 1;\n");
+      symlinkSync(join(outside, "secret.ts"), join(root, "escape.ts"));
+      expect(
+        pathTraversesSymlinkOutsideRoot(root, join(root, "escape.ts")),
+      ).toBe(true);
+    },
+  );
+
+  it.skipIf(!symlinkCapable)(
+    "returns true when an intermediate directory symlinks outside the root",
+    () => {
+      const base = mkdtempSync(join(tmpdir(), "codemap-symlink-dir-"));
+      const root = join(base, "proj");
+      const outside = join(base, "outside");
+      mkdirSync(root, { recursive: true });
+      mkdirSync(join(outside, "nested"), { recursive: true });
+      writeFileSync(
+        join(outside, "nested", "secret.ts"),
+        "export const s = 1;\n",
+      );
+      symlinkSync(outside, join(root, "linked-dir"));
+      expect(
+        pathTraversesSymlinkOutsideRoot(
+          root,
+          join(root, "linked-dir", "nested", "secret.ts"),
+        ),
+      ).toBe(true);
+    },
+  );
+
+  it.skipIf(!symlinkCapable)(
+    "returns true for a broken symlink in the path chain",
+    () => {
+      const root = mkdtempSync(join(tmpdir(), "codemap-symlink-broken-"));
+      symlinkSync(join(root, "missing-target.ts"), join(root, "broken.ts"));
+      expect(
+        pathTraversesSymlinkOutsideRoot(root, join(root, "broken.ts")),
+      ).toBe(true);
+    },
+  );
+});
+
+describe("pathRealpathEscapesProjectRoot", () => {
+  it.skipIf(!symlinkCapable)(
+    "returns true when realpath follows a symlink outside the project root",
+    () => {
+      const base = mkdtempSync(join(tmpdir(), "codemap-realpath-out-"));
+      const root = join(base, "proj");
+      const outside = join(base, "outside");
+      mkdirSync(root, { recursive: true });
+      mkdirSync(outside, { recursive: true });
+      writeFileSync(join(outside, "secret.ts"), "export const s = 1;\n");
+      symlinkSync(join(outside, "secret.ts"), join(root, "escape.ts"));
+      expect(
+        pathRealpathEscapesProjectRoot(root, join(root, "escape.ts")),
+      ).toBe(true);
+      expect(rejectUnsafeProjectRelativePath(root, "escape.ts")).toBe(
+        "path escapes via symlink",
+      );
+    },
+  );
+});
+
+describe("readUtf8WithinProjectRoot", () => {
+  it("reads safe files via realpath", () => {
+    const root = mkdtempSync(join(tmpdir(), "codemap-read-safe-"));
+    writeFileSync(join(root, "a.ts"), "export const a = 1;\n");
+    const result = readUtf8WithinProjectRoot(root, "a.ts");
+    expect(result).toEqual({ ok: true, content: "export const a = 1;\n" });
+  });
+
+  it("returns missing for paths that do not exist", () => {
+    const root = mkdtempSync(join(tmpdir(), "codemap-read-missing-"));
+    expect(readUtf8WithinProjectRoot(root, "gone.ts")).toEqual({
+      ok: false,
+      status: "missing",
+    });
   });
 
-  it("returns true when a path component symlinks outside the project root", () => {
-    const base = mkdtempSync(join(tmpdir(), "codemap-symlink-out-"));
+  it.skipIf(!symlinkCapable)("rejects broken symlinks before read", () => {
+    const root = mkdtempSync(join(tmpdir(), "codemap-read-broken-"));
+    symlinkSync(join(root, "missing.ts"), join(root, "broken.ts"));
+    expect(readUtf8WithinProjectRoot(root, "broken.ts")).toEqual({
+      ok: false,
+      status: "rejected",
+      reason: "path escapes via symlink",
+    });
+  });
+
+  it.skipIf(!symlinkCapable)("rejects symlink escapes before read", () => {
+    const base = mkdtempSync(join(tmpdir(), "codemap-read-escape-"));
     const root = join(base, "proj");
     const outside = join(base, "outside");
     mkdirSync(root, { recursive: true });
     mkdirSync(outside, { recursive: true });
     writeFileSync(join(outside, "secret.ts"), "export const s = 1;\n");
     symlinkSync(join(outside, "secret.ts"), join(root, "escape.ts"));
-    expect(pathTraversesSymlinkOutsideRoot(root, join(root, "escape.ts"))).toBe(
-      true,
-    );
-  });
-
-  it("returns true when an intermediate directory symlinks outside the root", () => {
-    const base = mkdtempSync(join(tmpdir(), "codemap-symlink-dir-"));
-    const root = join(base, "proj");
-    const outside = join(base, "outside");
-    mkdirSync(root, { recursive: true });
-    mkdirSync(join(outside, "nested"), { recursive: true });
-    writeFileSync(
-      join(outside, "nested", "secret.ts"),
-      "export const s = 1;\n",
-    );
-    symlinkSync(outside, join(root, "linked-dir"));
-    expect(
-      pathTraversesSymlinkOutsideRoot(
-        root,
-        join(root, "linked-dir", "nested", "secret.ts"),
-      ),
-    ).toBe(true);
+    expect(readUtf8WithinProjectRoot(root, "escape.ts")).toEqual({
+      ok: false,
+      status: "rejected",
+      reason: "path escapes via symlink",
+    });
   });
 });
 
@@ -81,14 +170,17 @@ describe("resolvePathWithinRoot", () => {
     expect(resolvePathWithinRoot(root, "../../../etc/passwd")).toBeNull();
   });
 
-  it("returns null when a symlink target resolves outside the root", () => {
-    const base = mkdtempSync(join(tmpdir(), "codemap-resolve-symlink-"));
-    const root = join(base, "proj");
-    const outside = join(base, "outside");
-    mkdirSync(root, { recursive: true });
-    mkdirSync(outside, { recursive: true });
-    writeFileSync(join(outside, "secret.ts"), "export const s = 1;\n");
-    symlinkSync(join(outside, "secret.ts"), join(root, "escape.ts"));
-    expect(resolvePathWithinRoot(root, "escape.ts")).toBeNull();
-  });
+  it.skipIf(!symlinkCapable)(
+    "returns null when a symlink target resolves outside the root",
+    () => {
+      const base = mkdtempSync(join(tmpdir(), "codemap-resolve-symlink-"));
+      const root = join(base, "proj");
+      const outside = join(base, "outside");
+      mkdirSync(root, { recursive: true });
+      mkdirSync(outside, { recursive: true });
+      writeFileSync(join(outside, "secret.ts"), "export const s = 1;\n");
+      symlinkSync(join(outside, "secret.ts"), join(root, "escape.ts"));
+      expect(resolvePathWithinRoot(root, "escape.ts")).toBeNull();
+    },
+  );
 });