harden: read-surface PR parity, bind policy, and ship docs

Add changeset and serve-bind-policy with runHttpServer enforcement;
align validate/serve consumer surfaces (CLI help, MCP, glossary, README,
agent-content); extend symlink containment tests.

Author: SutuSebastian

.changeset/read-surface-hardening.md

@@ -0,0 +1,5 @@
+---
+"@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.

README.md

@@ -50,7 +50,7 @@ codemap dead-code --json                                     # outcome alias →
 codemap query --json --recipe fan-out                        # recipe SQL by id (alias: -r)
 codemap query --json "SELECT name, file_path FROM symbols WHERE name = 'foo'"  # ad-hoc SQL
 codemap --files src/a.ts src/b.tsx                           # targeted re-index after edits
-codemap validate --json                                      # detect stale / missing / unindexed files
+codemap validate --json                                      # detect stale / missing / unindexed / rejected files
 codemap context --compact --for "refactor auth"              # JSON envelope + intent-matched recipes
 codemap ingest-coverage coverage/coverage-final.json --json  # Istanbul / LCOV (auto-detected) → coverage table; joins with symbols
 NODE_V8_COVERAGE=.cov bun test && codemap ingest-coverage .cov --runtime --json  # V8 protocol (per-process dumps); local-only
@@ -162,9 +162,9 @@ codemap query --format diff-json 'SELECT "README.md" AS file_path, 1 AS line_sta
 codemap --with-fts --full
 codemap query --recipe text-in-deprecated-functions    # demonstrates FTS5 ⨯ symbols ⨯ coverage JOIN
 # HTTP API — same tool taxonomy as `codemap mcp`, exposed over POST /tool/{name} for
-# non-MCP consumers (CI scripts, curl, IDE plugins). Loopback default; optional --token.
+# non-MCP consumers (CI scripts, curl, IDE plugins). Loopback default; --token required on non-loopback.
 TOKEN=$(openssl rand -hex 32)
-codemap serve --port 7878 --token "$TOKEN" &
+codemap serve --port 7878 --token "$TOKEN" &                 # --token required when --host is not loopback
 curl -s -X POST http://127.0.0.1:7878/tool/query \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $TOKEN" \

docs/glossary.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`. 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 or resolves outside via symlink). 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`); optional `--token <secret>` requires `Authorization: Bearer <secret>` on every request. 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`); `--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/plans/security-hardening-orchestrator.md

@@ -21,11 +21,11 @@
 
 ## PR schedule
 
-| PR    | Plan                                                           | Status                       | Blocks                              |
-| ----- | -------------------------------------------------------------- | ---------------------------- | ----------------------------------- |
-| **1** | [`security-hardening-wave1.md`](./security-hardening-wave1.md) | **implemented, uncommitted** | —                                   |
-| **2** | [`impact-inpath-homonyms.md`](./impact-inpath-homonyms.md)     | **pending**                  | PR **1** merged                     |
-| **3** | [`runtime-test-isolation.md`](./runtime-test-isolation.md)     | **pending**                  | PR **1** merged (PR **2** optional) |
+| PR    | Plan                                                           | Status                    | Blocks                              |
+| ----- | -------------------------------------------------------------- | ------------------------- | ----------------------------------- |
+| **1** | [`security-hardening-wave1.md`](./security-hardening-wave1.md) | **committed, PR pending** | —                                   |
+| **2** | [`impact-inpath-homonyms.md`](./impact-inpath-homonyms.md)     | **pending**               | PR **1** merged                     |
+| **3** | [`runtime-test-isolation.md`](./runtime-test-isolation.md)     | **pending**               | PR **1** merged (PR **2** optional) |
 
 | — | — | **deferred** | golden `schema.test.ts` + path guards |
 | — | — | **skip** | atomic `ensureStateConfig` writes |
@@ -64,15 +64,15 @@ Evaluated 2026-06 against [roadmap § Floors](../roadmap.md#floors-v1-product-sh
 
 ## Session log
 
-| Date       | Event      | Notes                                                                         |
-| ---------- | ---------- | ----------------------------------------------------------------------------- |
-| 2026-06-10 | Triage     | ROI on 7 slices; 3-PR program adopted.                                        |
-| 2026-06-10 | PR 1 impl  | PR **1** code complete; **not committed**. Docs: orchestrator + per-PR plans. |
-| —          | PR 1 merge | _PR URL · merge SHA · update plan status → closed_                            |
-| —          | PR 2 start | _from `main`_                                                                 |
-| —          | PR 2 merge | _fill_                                                                        |
-| —          | PR 3 start | _from `main`_                                                                 |
-| —          | PR 3 merge | _fill · close orchestrator_                                                   |
+| Date       | Event      | Notes                                                                        |
+| ---------- | ---------- | ---------------------------------------------------------------------------- |
+| 2026-06-10 | Triage     | ROI on 7 slices; 3-PR program adopted.                                       |
+| 2026-06-10 | PR 1 impl  | PR **1** committed on `fix/security-hardening-wave1`; harden pass in flight. |
+| —          | PR 1 merge | _PR URL · merge SHA · update plan status → closed_                           |
+| —          | PR 2 start | _from `main`_                                                                |
+| —          | PR 2 merge | _fill_                                                                       |
+| —          | PR 3 start | _from `main`_                                                                |
+| —          | PR 3 merge | _fill · close orchestrator_                                                  |
 
 ---
 

docs/plans/security-hardening-wave1.md

@@ -1,6 +1,6 @@
 # PR 1 — query / serve / validate hardening
 
-> **Status:** open (implemented, uncommitted) · **PR:** 1 of 3 · **Effort:** S
+> **Status:** open (committed, PR pending) · **PR:** 1 of 3 · **Effort:** S
 >
 > **Orchestrator:** [`security-hardening-orchestrator.md`](./security-hardening-orchestrator.md)
 >
@@ -49,7 +49,7 @@ codemap validate <paths>
 | 3.2 | `validate` `rejected` + `rejectValidatePath`               | **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`                                     |
+| 1.s | Commit + PR + CI                                           | **pending** | `bun run check` (committed; PR + CI open)           |
 
 ---
 

src/application/http-server.ts

@@ -21,6 +21,10 @@ import type { IndexFreshness } from "./index-freshness";
 import { MCP_TOOL_NAMES } from "./mcp-tool-allowlist";
 import { buildHttpToolCatalogEntry } from "./mcp-tool-annotations";
 import { listResources, readResource } from "./resource-handlers";
+import {
+  assertServeBindRequiresToken,
+  isLoopbackHost,
+} from "./serve-bind-policy";
 import {
   bindWatchClientRelease,
   createManagedWatchSession,
@@ -119,6 +123,7 @@ export interface HttpServerOpts {
  * to JSON `{"error": "..."}` with appropriate status codes.
  */
 export async function runHttpServer(opts: HttpServerOpts): Promise<void> {
+  assertServeBindRequiresToken(opts.host, opts.token);
   await bootstrapForServe(opts);
 
   let managedWatchSession: ManagedWatchSession | undefined;
@@ -692,7 +697,7 @@ function csrfCheck(
     return `cross-origin request rejected (Sec-Fetch-Site: ${String(fetchSite)}). codemap serve does not accept browser-driven cross-origin requests.`;
   }
 
-  if (host === "127.0.0.1" || host === "localhost" || host === "::1") {
+  if (isLoopbackHost(host)) {
     const hostHeader = req.headers.host;
     if (hostHeader !== undefined) {
       const allowed = new Set([

src/application/mcp-server.ts

@@ -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` (fresh paths omitted). 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` 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.",
       inputSchema: validateArgsSchema,
     }),
     (args) => wrapToolResult(handleValidate(args)),

src/application/path-containment.test.ts

@@ -46,6 +46,25 @@ describe("pathTraversesSymlinkOutsideRoot", () => {
       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);
+  });
 });
 
 describe("resolvePathWithinRoot", () => {

src/application/serve-bind-policy.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  assertServeBindRequiresToken,
+  isLoopbackHost,
+  serveBindTokenRequiredMessage,
+} from "./serve-bind-policy";
+
+describe("isLoopbackHost", () => {
+  it.each([
+    ["127.0.0.1", true],
+    ["localhost", true],
+    ["::1", true],
+    ["[::1]", true],
+    ["0.0.0.0", false],
+    ["::", false],
+    ["192.168.1.1", false],
+  ] as const)("host %s → %s", (host, expected) => {
+    expect(isLoopbackHost(host)).toBe(expected);
+  });
+});
+
+describe("serveBindTokenRequiredMessage", () => {
+  it("requires token on non-loopback binds", () => {
+    expect(serveBindTokenRequiredMessage("0.0.0.0", undefined)).toContain(
+      "non-loopback bind requires --token",
+    );
+    expect(serveBindTokenRequiredMessage("::", undefined)).toContain(
+      "non-loopback bind requires --token",
+    );
+  });
+
+  it("allows loopback binds without token", () => {
+    expect(
+      serveBindTokenRequiredMessage("127.0.0.1", undefined),
+    ).toBeUndefined();
+    expect(serveBindTokenRequiredMessage("[::1]", undefined)).toBeUndefined();
+  });
+
+  it("assertServeBindRequiresToken throws with the same message", () => {
+    expect(() => assertServeBindRequiresToken("0.0.0.0", undefined)).toThrow(
+      /non-loopback bind requires --token/,
+    );
+  });
+});

src/application/serve-bind-policy.ts

@@ -0,0 +1,28 @@
+/** Hosts safe to bind without mandatory auth (loopback only). */
+export function isLoopbackHost(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "127.0.0.1" || h === "localhost" || h === "::1" || h === "[::1]";
+}
+
+/** Error message when a non-loopback bind lacks a token; `undefined` when OK. */
+export function serveBindTokenRequiredMessage(
+  host: string,
+  token: string | undefined,
+): string | undefined {
+  if (!isLoopbackHost(host) && (token === undefined || token.length === 0)) {
+    return (
+      "codemap serve: non-loopback bind requires --token (use a long random secret). " +
+      "Example: codemap serve --host 0.0.0.0 --token $(openssl rand -hex 32)"
+    );
+  }
+  return undefined;
+}
+
+/** Fail fast before `listen` when bind policy is violated. */
+export function assertServeBindRequiresToken(
+  host: string,
+  token: string | undefined,
+): void {
+  const message = serveBindTokenRequiredMessage(host, token);
+  if (message !== undefined) throw new Error(message);
+}