@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.5

package/src/posture/remediation-ledger.js

@@ -0,0 +1,337 @@
+// remediation-ledger.js — M5 deliverable #6 (Blast-Radius: Remediation
+// Command Center, FR-507 + AC-31), Task 2 of the sub-project: the IMPURE
+// half. `../lineage/remediation.js` (Task 1) ships the pure RemediationItem
+// contract — zero imports, no fs, never throws. This module owns every side
+// effect that contract needs to become a real, durable, tamper-evident
+// record: file locking, JSONL append, tolerant read, and the hash chain.
+//
+// This is the SECOND `posture/` → `lineage/` import in the codebase
+// (`auditor-walkthrough.js`'s `graph:` branch was the first, per
+// `posture/CLAUDE.md`'s "First `posture/` → `lineage/` import" section) —
+// noted here so the boundary stays a deliberate, documented exception
+// rather than an accident.
+//
+// ── The append-only contract (PRD line 984) ──────────────────────────────
+//
+// A remediation item's history is never rewritten, only appended to. Every
+// decision — owner assignment, a state change, a manual attestation, an
+// accepted-risk exception — is a permanent event, never an edit of a prior
+// one. `foldRemediationItem`/`foldRemediationLedger` (Task 1) derive an
+// item's CURRENT shape by replaying its events forward; nothing here ever
+// mutates a written line.
+//
+// ── Why the physical shape is a JSONL append, not a whole-file rewrite ────
+//
+// `fix-metrics.js:69`'s `recordFixAttempt` is the precedent this module
+// follows: "One writeSync of one newline-terminated line: a concurrent
+// reader sees whole records or nothing, and a torn tail is dropped on
+// read." `provenance/lifecycle.js:195`'s `updateLifecycle`, by contrast,
+// reads the WHOLE store into memory, folds one scan's worth of changes in,
+// and rewrites the WHOLE file — safe there because a lifecycle update is a
+// single scan touching potentially every finding at once. A remediation
+// ledger is the opposite shape: a human, one item at a time, arbitrarily
+// interleaved with edits to every OTHER item. A partial rewrite of a shared
+// document risks losing every OTHER item's history to a crash or a bug
+// mid-rewrite; an append can only ever add a new, independently-readable
+// line.
+//
+// ── Why a lock is still required, despite the append itself being atomic ──
+//
+// `fs.appendFileSync` of one line is atomic at the OS level, but writing an
+// event is not just "append a line" — it is a READ-MODIFY-WRITE: the
+// proposed event must be validated (`validateTransition`) against the
+// item's CURRENT folded state, which requires reading and folding every
+// prior event first. Two concurrent callers each reading the same "before"
+// state and then both appending could both validate against a state that
+// is stale by the time either write lands — e.g. two racing attempts to
+// open the same item, both seeing "no item yet" and both succeeding, when
+// exactly one must win. The lock serializes the whole
+// read-fold-validate-append sequence into one critical section per event.
+//
+// `withLock` below is a faithful local PORT of
+// `provenance/lifecycle.js:36`'s own `withLock` — NOT an import, because
+// that function is not exported (verified directly against the file: it is
+// a bare, module-private `async function withLock`). `isProcessAlive` is
+// ported alongside it for the same reason.
+//
+// ── The hash chain ─────────────────────────────────────────────────────
+//
+// Byte-identical in behavior to `mcp/audit.js`'s own chain (`_sha`,
+// `GENESIS`, `_readLastEntryHash`, `verifyAuditLog`, verified directly
+// against that file before writing this one): each event carries `prev`,
+// the SHA-256 hex digest of the PREVIOUS line's exact serialized JSON text
+// (including that line's own `prev` field). The first event's `prev` is
+// the literal string `'GENESIS'`. `readLedgerEvents`/`latestEventHash`
+// walk forward from GENESIS; a line that fails to `JSON.parse` (a torn
+// tail) or whose `prev` does not match the expected running hash (tamper)
+// STOPS the walk. Both functions therefore return the longest verifying
+// PREFIX of the file — never the full stream when any of it is
+// unverifiable, and never a thrown error. See `_walkLedger` below, which
+// both exported readers share so they cannot silently disagree on what
+// "the last valid line" means.
+//
+// `appendLedgerEvent` is async and is the SINGLE place `validateTransition`
+// is called in this codebase. No CLI command (Task 3) computes validity
+// for itself — every proposed event is validated at this one write
+// boundary, inside the lock, against the real current folded state. As of
+// final-review fix round 1, this is also the single place THREE more
+// things are enforced, all inside the same lock so none of them can race
+// the write they guard: an `opened` event is additionally checked against
+// `validateOpenPayload` (I4/M11 — previously only the CLI validated an
+// `opened` payload's own shape, so a non-CLI caller could append a
+// malformed one); the ledger's on-disk tail is checked for tearing before
+// anything is appended onto it (I4 — appending onto a torn line would
+// merge them into one unparseable line, silently losing the new event,
+// and everything after it, forever); and an optional
+// `opts.expectedBaseHash` optimistic-concurrency check runs against the
+// real `lastHash` computed inside the lock (I5 — previously the CLI's own
+// `--base-event` guard ran OUTSIDE the lock, a real TOCTOU: another
+// process could append in the window between that check and this
+// function's own lock acquisition).
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { statePath, isSafeStateDir, stateWritesEnabled } from './state-dir.js';
+import { validateTransition, validateOpenPayload, foldRemediationLedger } from '../lineage/remediation.js';
+
+const GENESIS = 'GENESIS';
+
+function _sha(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+export function ledgerPaths(scanRoot) {
+  return {
+    ledgerPath: statePath(scanRoot, 'remediation', 'items.jsonl'),
+    lockPath: statePath(scanRoot, 'remediation', 'items.lock'),
+  };
+}
+
+// Shared walk: reads the ledger file (missing → empty), splits on '\n',
+// drops empty lines, and walks forward maintaining `expectedPrev` (starting
+// at GENESIS) exactly as `mcp/audit.js`'s `verifyAuditLog` does. A parse
+// failure or a `prev` mismatch stops the walk without throwing. Returns
+// `{events, lastHash}` so `readLedgerEvents`/`latestEventHash` cannot drift
+// apart on what "the last valid line" means.
+function _walkLedger(scanRoot) {
+  const { ledgerPath } = ledgerPaths(scanRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return { events: [], lastHash: GENESIS };
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  const events = [];
+  let expectedPrev = GENESIS;
+  let lastHash = GENESIS;
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      break; // torn tail — stop, do not throw
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event) || event.prev !== expectedPrev) {
+      break; // tamper detected — stop, do not throw
+    }
+    events.push(event);
+    lastHash = _sha(line);
+    expectedPrev = lastHash;
+  }
+  return { events, lastHash };
+}
+
+// Returns the longest verifying PREFIX of the ledger — never the full
+// stream when a tail is torn or a middle line is tampered. Never throws.
+export function readLedgerEvents(scanRoot) {
+  return _walkLedger(scanRoot).events;
+}
+
+// GENESIS when the ledger is empty/missing, or when nothing in it verifies.
+export function latestEventHash(scanRoot) {
+  return _walkLedger(scanRoot).lastHash;
+}
+
+// Reports whether the ledger's real content on disk has more raw lines than
+// the longest verifying prefix — i.e. a torn tail OR a tampered middle line
+// broke the hash chain partway through. Never throws. This is a read-only
+// diagnostic; it does not change what readLedgerEvents/latestEventHash
+// return (both still return the longest verifying prefix, unconditionally
+// safe by construction) — it exists so a caller (the CLI's `list` command)
+// can surface a loud warning instead of silently presenting a shorter or
+// stale history as if it were the whole truth. (I7, final-review fix
+// round 1.)
+export function ledgerIntegrity(scanRoot) {
+  const { ledgerPath } = ledgerPaths(scanRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return { ok: true, totalLines: 0, verifiedLines: 0 };
+  }
+  const totalLines = raw.split('\n').filter(Boolean).length;
+  const { events } = _walkLedger(scanRoot);
+  return { ok: events.length === totalLines, totalLines, verifiedLines: events.length };
+}
+
+function isProcessAlive(pid) {
+  // POSIX: process.kill(pid, 0) probes existence without sending a signal.
+  // EPERM also means the process exists; only ESRCH means dead.
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}
+
+// Faithful local port of `provenance/lifecycle.js:36-88`'s `withLock` — not
+// an import, since that function is module-private there. Exclusive `wx`
+// open of the lockfile, write the PID, run `fn` in a `try`, `unlink` in
+// `finally`. On EEXIST, a stale lock (holding PID not alive, or lockfile
+// older than 30s) is reaped, re-reading the lockfile before unlinking so a
+// fresh holder taken by another process in the meantime is never raced.
+// 25ms retry; 5s timeout throwing a named error.
+async function withLock(lockPath, fn) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const start = Date.now();
+  const TIMEOUT_MS = 5000;
+  while (true) {
+    try {
+      const handle = await fsp.open(lockPath, 'wx');
+      await handle.writeFile(String(process.pid));
+      try { await handle.close(); } catch {}
+      try {
+        return await fn();
+      } finally {
+        await fsp.unlink(lockPath).catch(() => {});
+      }
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        try {
+          const [st, pidStr] = await Promise.all([
+            fsp.stat(lockPath),
+            fsp.readFile(lockPath, 'utf8').catch(() => ''),
+          ]);
+          const pid = parseInt(pidStr.trim(), 10);
+          const pidAlive = Number.isFinite(pid) && isProcessAlive(pid);
+          const old = Date.now() - st.mtimeMs > 30000;
+          if (!pidAlive || old) {
+            try {
+              // Only unlink if the lockfile still holds the PID we just
+              // read, so we don't race the unlink against a fresh lock
+              // taken by another process in the meantime.
+              const recheck = (await fsp.readFile(lockPath, 'utf8').catch(() => '')).trim();
+              if (recheck === pidStr.trim()) {
+                await fsp.unlink(lockPath);
+              }
+            } catch {}
+            continue;
+          }
+        } catch {}
+        if (Date.now() - start > TIMEOUT_MS) throw new Error('remediation-ledger: lock timed out');
+        await new Promise((r) => setTimeout(r, 25));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+// Resolves the itemId a proposed event refers to, mirroring
+// `foldRemediationLedger`'s own grouping fallback exactly (Task 1's
+// `../lineage/remediation.js`: `ev.itemId ?? (ev.type === 'opened' ?
+// ev.id : undefined)`) — an `opened` event carries `id` (per
+// `foldRemediationItem`'s own use of `openEvent.id`), every other event
+// type carries `itemId`. Reusing the identical fallback here, rather than
+// reading `eventPayload.itemId` alone, is what makes item resolution agree
+// with how the ledger will actually be folded on read — an opened event
+// for an id that already exists must resolve to that existing item, not
+// silently miss it because the payload only carries `id`.
+function _resolveItemId(eventPayload) {
+  if (!eventPayload || typeof eventPayload !== 'object') return undefined;
+  return eventPayload.itemId ?? (eventPayload.type === 'opened' ? eventPayload.id : undefined);
+}
+
+// This function is the single place `validateTransition` is called. No CLI
+// command computes validity for itself. `opts.expectedBaseHash` (I5) is an
+// optional optimistic-concurrency check, compared against the real
+// `lastHash` computed INSIDE the lock — the authoritative half of the
+// `--base-event` guard; `undefined` (the flag was never passed) performs no
+// check.
+export async function appendLedgerEvent(scanRoot, eventPayload, opts = {}) {
+  const { ledgerPath, lockPath } = ledgerPaths(scanRoot);
+  const dir = path.dirname(ledgerPath);
+
+  // Refused BEFORE the lock is taken, so an unsafe/disabled target never
+  // even gets a lockfile written into it.
+  if (!isSafeStateDir(dir)) {
+    return {
+      valid: false,
+      errors: [{ field: '(scanRoot)', message: 'refusing to write — not a recognized project state directory' }],
+    };
+  }
+  if (!stateWritesEnabled()) {
+    return {
+      valid: false,
+      errors: [{ field: '(state)', message: 'state writes are disabled (AGENTIC_SECURITY_NO_STATE or setStateWritesEnabled(false))' }],
+    };
+  }
+
+  return withLock(lockPath, async () => {
+    // I4 (final-review fix round 1): refuse to append onto a torn tail —
+    // concatenating a new event onto an unterminated final line would
+    // merge them into one unparseable line, silently losing this event
+    // (and everything after it) forever while still reporting success. A
+    // crash/ENOSPC mid-write leaves exactly this shape. Checked first,
+    // inside the lock, before anything else touches the file.
+    try {
+      const raw = fs.readFileSync(ledgerPath, 'utf8');
+      if (raw.length > 0 && !raw.endsWith('\n')) {
+        return {
+          valid: false,
+          errors: [{ field: '(ledger)', message: 'the ledger file has a torn/unterminated final line — refusing to append onto it. Recover the file (restore from backup, or manually truncate to its last complete, newline-terminated line) before retrying.' }],
+        };
+      }
+    } catch { /* missing file — nothing to check */ }
+
+    const { events, lastHash } = _walkLedger(scanRoot);
+
+    // I5 (final-review fix round 1): the authoritative optimistic-
+    // concurrency check, run against the real `lastHash` computed inside
+    // this same critical section — the CLI's own pre-lock check is still
+    // useful as a cheap, early fail, but this is the one that cannot be
+    // raced by a concurrent writer.
+    if (opts.expectedBaseHash !== undefined && opts.expectedBaseHash !== lastHash) {
+      return {
+        valid: false,
+        errors: [{ field: '(base-event)', message: 'the ledger changed since --base-event was computed (a concurrent write) — refusing to append.' }],
+      };
+    }
+
+    const items = foldRemediationLedger(events);
+    const itemId = _resolveItemId(eventPayload);
+    const item = itemId != null ? (items[itemId] ?? null) : null;
+
+    // M11: an `opened` event's own shape is validated here too, not just
+    // by the CLI — mirrors "the single place validity is enforced" for
+    // the one event type `validateTransition` deliberately does not
+    // shape-check (it only checks that no item with this id exists yet).
+    if (eventPayload && eventPayload.type === 'opened') {
+      const openCheck = validateOpenPayload(eventPayload);
+      if (!openCheck.valid) {
+        return { valid: false, errors: openCheck.errors };
+      }
+    }
+
+    const { valid, errors } = validateTransition(item, eventPayload);
+    if (!valid) {
+      return { valid: false, errors };
+    }
+
+    const event = { ...eventPayload, prev: lastHash };
+    const line = JSON.stringify(event);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(ledgerPath, line + '\n', 'utf8');
+    return { valid: true, errors: [], event, hash: _sha(line) };
+  });
+}

package/src/server/CLAUDE.md

@@ -0,0 +1,47 @@
+# scanner/src/server/
+
+The `agentic-security explore` local server — Milestone 3 of the Data
+Flow Explorer PRD ("local server and secure API," PRD §17). Read-only in
+this increment; serves the already-scanned, already-signed
+`DataFlowGraph v1` artifact over a hardened loopback HTTP API.
+
+## What's here
+
+**Sub-project Server, increment 1 (read-only GET endpoints + full
+security posture) — COMPLETE:**
+
+| Module | Responsibility |
+|---|---|
+| `docs/superpowers/plans/2026-09-01-data-flow-explorer-m3-server-scoping.md` + `…-s1-plan.md` | Confirms the entire deliverable was greenfield (no HTTP server code anywhere; the MCP server is JSON-RPC-over-stdio, the LSP server a different stdio protocol — neither has an HTTP surface). Scopes S1 to the five P0 GET endpoints only, deferring `query`/`export` (real design work of their own) to S2/M4. Every §17.4 security bullet is a first-class S1 requirement, not a follow-up pass, since `docs/DATA_FLOW_EXPLORER_THREAT_MODEL.md`'s own T2 (DNS rebinding)/T3 (CSRF)/T4 (path traversal) entries are explicitly gated on "the server does not exist yet." |
+| `graph-loader.js` | `loadSignedGraph(scanRoot)` — reads `.agentic-security/lineage-graph.json` + `.sig`, reusing `posture/integrity.js`'s `verifyLastScan` DIRECTLY (never a second, parallel verification mechanism — that function already uses `crypto.timingSafeEqual` internally). Four distinct, clearly-messaged failure reasons: `missing` (no file), `unsigned` (`.sig` absent), `tampered` (signature mismatch), `malformed` (valid signature, invalid JSON). Loaded once at server startup, held in memory — this is a read-only, single-scan-snapshot server; a change to the graph on disk mid-session is out of scope (the threat model doc's own "P0 is read-only" framing). |
+| `security.js` | `generateSessionToken()` (32 random bytes, hex); `constantTimeEqual(a, b)` (wraps `crypto.timingSafeEqual`, length-guarded the same way `verifyLastScan` guards its own HMAC comparison — never throws on mismatched-length input); `isValidHost(hostHeader, expectedPort)` — the T2 DNS-rebinding defense, accepting only `127.0.0.1`/`localhost`/`::1` (bare or bracketed) at the exact expected port, rejecting everything else including alternate-encoded loopback forms (decimal/octal/hex IP literals) — a hostile page's own Host header carries ITS OWN origin, never `127.0.0.1`, so this check defeats DNS rebinding regardless of browser same-origin-policy quirks; `CSP_HEADER_VALUE = "default-src 'none'; frame-ancestors 'none'"` (maximally restrictive — this server serves JSON only in S1, no HTML/inline script surface at all). |
+| `routes.js` | Six PURE handler functions, each `(graph, ...) -> {status, body}` — `handleScan`, `handleGraph`, `handleNode`, `handleEdge`, `handleFlow`, `handleQuery` — no `req`/`res` access anywhere in this file, independently unit-testable without an HTTP layer. `wrapResponse(data, graph, {canonicalIds})` wraps every body in the exact envelope PRD line 1326 requires ("base graph/snapshot digest, schema/extension versions, scope, coverage, limitations, and contributing canonical IDs"), mapped onto the graph's own real fields (`graphId`→digest, `schemaVersion`, `extensions`, `scope`, `coverage`, `limitations`). `canonicalIds` is `null` for `handleScan`/`handleGraph`/`handleQuery` (all three describe the whole graph or a filtered projection of it — `handleGraph`'s own body already IS the full node/edge/flow arrays, so re-listing every id would be pure duplication with real cost on a large graph), `[id]` for `handleNode`/`handleEdge`, and the flow's own id plus its `source`/`sink`/`edgeIds` for `handleFlow` (a derived record referencing several other entities — naming them is genuinely useful metadata, not duplication). **`handleQuery(graph, filter)`** (Milestone 5, large-graph pagination — the `POST /api/v1/query` endpoint the S1-era header comment above and this file's own "What this does NOT do" section used to defer) shape-validates `filter` via `export-json.js`'s `validateFilterShape` (400 on a malformed filter, never a thrown exception) and, when valid, narrows the graph via that same module's already-shipped, already-tested `_filterGraph` — the identical `{nodeIds, edgeIds}` shape `dataflow export --filter` and the MCP `dataflow_get_graph` tool already use, reused rather than reimplemented. `undefined`/`{}` returns the whole graph, identical to `handleGraph`. |
+| `http-server.js` | `createExploreServer({graph, port, sessionToken, idleTimeoutMs, keepOpen})` — the first `node:http` usage anywhere in `scanner/src/`. Binds explicitly to `127.0.0.1` (never `0.0.0.0`, never an omitted host argument — that is NOT the same as `127.0.0.1` on every platform). Every request: `Host` header validated (T2, 400 on failure) BEFORE the session token (T3, 401 on failure, `constantTimeEqual`) BEFORE a uniform request-size cap (`MAX_REQUEST_BODY_BYTES = 64KB`, 413 on excess — S1's GET endpoints have no meaningful body; Milestone 5's `POST /api/v1/query` is the first real consumer of the body-accumulation this cap now gates) BEFORE routing. `POST /api/v1/query`'s request body is accumulated alongside the pre-existing size-cap check and JSON-parsed only for a matched route with a non-empty body (malformed JSON → 400, never a 500) — every pre-M5 GET route still ignores the handler's 3rd `body` argument entirely, so an empty/missing body for them stays a no-op, unchanged. Every response: `Content-Security-Policy` set, `Cache-Control: no-store` set, `Access-Control-Allow-Origin` NEVER set anywhere in this file (CORS stays disabled by the header's own absence — do not add a permissive default later without re-reading this line). Idle-timeout auto-stop (`DEFAULT_IDLE_TIMEOUT_MS = 30 min`, no PRD-specified number exists, a disclosed reasoned default) resets ONLY on requests that pass BOTH the Host and token checks — an unauthenticated prober (a DNS-rebinding attempt, a stray scan) can never keep the server alive by hammering it; only genuine authenticated activity extends the session. `keepOpen: true` suppresses auto-stop entirely. Logging is metadata-only (method/path/status/duration) — never response bodies, never the session token, even on a failed-auth attempt. A 500 from a route handler returns a generic `{error: 'internal error'}` body, never the underlying exception's message/stack. **Disclosed, non-security gap**: no `SIGINT`/`SIGTERM` handler exists yet, so Ctrl-C relies on Node's default abrupt-exit rather than a graceful `server.close()` — functionally fine (the process does exit) but not maximally graceful; a future increment could add one for a cleaner shutdown message. |
+| `bin/agentic-security.js` (extended, additively) | `case 'explore':` + `cmdExplore(args)` — parses the scan root (`args._[1]`, default cwd), `--port` (validated: digits-only, ≤65535), `--keep-open`. Calls `loadSignedGraph` FIRST; on any failure, prints the specific clear message and exits non-zero WITHOUT ever starting the server (never binds a port, never generates a token, on a missing/tampered/unsigned/malformed graph). On success, generates a fresh session token per invocation and prints it to stdout EXACTLY ONCE — the only place it is ever displayed, never written to a file, never logged again after this one print. Returns a Promise resolving to exit code 0 when the server eventually closes (idle-timeout or an external kill), matching every other `cmdX(args)` function's own "returns a numeric exit code" contract while still supporting a long-running process. `explore` never triggers a scan itself — it requires a pre-existing artifact, matching §17.3's own "P0 is read-only with respect to source" framing exactly. |
+| `test/server/*.test.js` (41 tests) | `security.test.js`/`graph-loader.test.js`/`routes.test.js` — pure-function unit tests (isolated `constantTimeEqual`/`isValidHost` edge cases; all four `loadSignedGraph` failure reasons via a real signed/tampered/unsigned/malformed fixture; all five route handlers' shapes). `http-server.test.js` — REAL end-to-end `node:http.request` calls against a REAL running server (never a mocked/isolated unit test for the security-critical properties): a forged `Host` header rejected live (T2); a missing AND a wrong session token rejected live on every one of the five endpoints (T3); response headers asserted present/absent on BOTH a 200 and a rejected response; a real short-idle-timeout variant proving the server genuinely stops listening and refuses new connections (`ECONNREFUSED`), and a `keepOpen: true` variant proving it doesn't; an oversized-body 413. `cmd-explore.test.js` — the real spawned CLI end to end (missing graph → non-zero exit, no token ever printed, connection refused; a valid signed graph → a real server whose printed URL + token authenticate a real request). Independently re-verified by the coordinator via a THIRD path beyond the implementer's own tests: a real `explore` invocation launched manually, hit with `curl` from outside any test harness, confirming the same 200/401/400 outcomes and headers live. |
+
+**Sub-project Wire (live-API wiring for the frontend) — COMPLETE:**
+
+| Module | Responsibility |
+|---|---|
+| `docs/superpowers/plans/2026-09-01-data-flow-explorer-m3-wire-scoping.md` + `…-plan.md` | The load-bearing correction this increment starts from: §17.4's CORS-disabled-by-default posture means the frontend MUST be served from the SAME origin as the API, or the browser blocks every `fetch()` regardless of what the server returns. Decides the session token travels via a URL FRAGMENT (`#token=...`), never a query string or cookie — a fragment is never sent to the server in any HTTP request. |
+| `static-assets.js` | `FRONTEND_ROOT` (located via the exact `path.dirname(fileURLToPath(import.meta.url))` pattern `mcp/server.js` already established, resolved to the real `frontend/` directory). `resolveStaticAsset(requestPath)` — a PURE function, no fs/http access — resolving a request pathname against an explicit ALLOWLIST (`index.html`; `src/**/*.js`; top-level `styles/*.css` only, no nested subdirs) and returning `{ok:true, relativePath, contentType}` or `{ok:false, reason}`. This is a real allowlist, not merely a `../`-traversal guard: `test/`, `scripts/`, `package.json`, `README.md`, `CLAUDE.md`, `.gitignore` are all real files that exist on disk under `frontend/` and are REJECTED (`reason: 'not-allowlisted'`) even though a naive "stays inside frontend/" check would happily serve them. Traversal defense re-checks AFTER `path.posix.normalize` (never trusts normalization alone) for both literal and percent-encoded (`%2e%2e`) `..`; null bytes are rejected both literally and as a decoded `%00`; absolute-URL-looking input (a scheme, or `//host/...`) is rejected outright. `STATIC_CSP_HEADER_VALUE` is a SEPARATE, same-origin-permitting CSP (`script-src 'self'` etc., no `'unsafe-inline'`) from `security.js`'s `CSP_HEADER_VALUE` (`default-src 'none'`, unchanged, still used on every `/api/v1/*` response). |
+| `http-server.js` (extended) | New static-asset branch, checked for every `GET` request whose path does NOT start with `/api/` — resolved BEFORE the session-token check (the ONE deliberate, disclosed exception to "every request requires a token": the token lives in a URL fragment the browser never sends, so the very first page-load request is structurally incapable of carrying it) but AFTER the Host-header check (T2 applies uniformly, auth or not). A rejected static path is a 404, never a 403 (never confirms a path's existence to a prober). Static responses carry `STATIC_CSP_HEADER_VALUE` + `Cache-Control: no-store` (unchanged) + the resolved Content-Type; `Access-Control-Allow-Origin` is still never set. The idle-auto-stop timer is deliberately NOT reset by an unauthenticated static-asset request — only genuine, authenticated `/api/v1/*` activity extends the session, unchanged from S1's own invariant. |
+| `bin/agentic-security.js`'s `cmdExplore` (extended) | The printed URL changed from `http://127.0.0.1:<port>/api/v1/scan` to `http://127.0.0.1:<port>/#token=<64-hex-token>` — still the ONE place the token is ever displayed, now carried as a URL fragment instead of a separate "Token:" line, with updated wording ("open this URL in a browser" rather than "pass the token as a header manually"). |
+| `frontend/src/lib/api-client.js` (new, in `frontend/`) | `extractTokenFromFragment()` (parses `location.hash` for `#token=<hex>`, tolerant of other hash params shell.js may also be writing) and `fetchGraph({token, baseUrl})` (fetches `/api/v1/graph` with the token header, unwraps the `.data` envelope field). `baseUrl` defaults to `''` (a same-origin relative fetch — the only thing the shipped page itself ever passes) and exists solely so a test can point this at a real running server without a headless browser. |
+| `frontend/src/main.js` (new, in `frontend/`) | Replaces `index.html`'s old inline `<script type="module">` block (which would have needed `'unsafe-inline'` under `STATIC_CSP_HEADER_VALUE`) with an external module: extracts the token, calls `fetchGraph`, calls the EXISTING, UNCHANGED `bootstrap(root, graph)`, and shows a plain visible error in `#app-root` on fetch failure — never a silent blank page. |
+| `test/server/static-assets.test.js` (new) | Pure-function tests — every real allowlisted path resolves with the right content type; several REAL on-disk-but-not-allowlisted files (`test/dom-shim.js`, `package.json`, `README.md`, `CLAUDE.md`, `.gitignore`, the generator script) are rejected; traversal (several encodings, including percent-encoded `..` and multi-segment escapes) and null-byte (literal and `%00`) rejection. |
+| `test/server/http-server.test.js` (extended) | Real, live HTTP requests against a real running server for the new surface: `GET /` with NO token succeeds and serves the real `index.html`; `GET /api/v1/graph` with no token still 401 (the exemption is static-route-only); static responses carry the separate static CSP, never `default-src 'none'`; a forged `Host` header is still rejected on a static route; a live `../`-traversal attempt is rejected 404; the same on-disk-but-unlisted files are rejected 404 over real HTTP, never 403. |
+| `test/server/cmd-explore.test.js` (updated) | Re-asserts the CLI's printed-URL regex against the new fragment-token form and that no separate "Token:" line is ever printed. |
+| `frontend/test/api-client.test.js`, `frontend/test/live-fetch-parity.test.js` (new, in `frontend/`) | `extractTokenFromFragment`/`fetchGraph` unit tests (mocked fetch) plus the AC-16 proof: a REAL `explore` server started over the REAL flagship-graph fixture, fetched through the REAL `api-client.js` over a REAL loopback HTTP connection (no mock), asserted content-identical to the static-import baseline, then rendered through the SAME, UNCHANGED `bootstrap()` and asserted to produce a structurally IDENTICAL DOM tree to the existing static-import baseline's own render. |
+
+## What this does NOT do
+
+`POST /api/v1/export` (the self-contained-export pipeline, §17.5 — Milestone 4 territory per the parent M3 scoping doc). Any Milestone 4/5 decision-intelligence endpoint (`stories/`, `scenarios/`, `snapshots/`, `diffs/`, `obligations/`, `runtime/`, `recipients/`, `impact/`, `remediation/`, `rescan`). Wiring `frontend/` to this server (Sub-project Wire's own job — this server is built and tested standalone, in complete isolation from `frontend/`). File/line evidence path resolution and its own T4 path-traversal confinement test (no such lookup exists in S1's five endpoints — the graph JSON is served verbatim, so T4 correctly has no surface yet, the same honest status the threat model doc itself records). Triggering a scan from `explore` itself. Any language beyond what the graph itself already covers (this server is language-agnostic — it serves whatever graph exists).
+
+## Conventions
+
+- **No new npm dependency, ever, without re-opening this decision first.** `node:http`/`node:crypto`/`node:fs` only — matches this repo's own minimalism convention (`validate.js`'s own "no new npm dependency" precedent) and the MCP/LSP servers' own hand-rolled-protocol precedent. If a future increment genuinely needs a framework, that is a real, separately-justified decision, not a default.
+- **CORS stays disabled by the ABSENCE of `Access-Control-Allow-Origin`.** Never add this header with a permissive value (`*`, or an echoed `Origin`) anywhere in this package without a real, disclosed threat-model reason — its absence is load-bearing security posture, not an oversight.
+- **Every security-relevant string comparison goes through `constantTimeEqual`** (`security.js`), never `===`/`!==` on a token or secret.
+- **A route handler's thrown error must never reach the client verbatim** — `http-server.js`'s own catch-and-genericize behavior around route dispatch is load-bearing; a future endpoint must not bypass it.

package/src/server/graph-loader.js

@@ -0,0 +1,141 @@
+// graph-loader.js — Milestone 3, sub-project Server, increment 1.
+//
+// Reads and VERIFIES the `.agentic-security/lineage-graph.json` artifact
+// before `explore` is allowed to serve a single byte of it. Reuses
+// `posture/integrity.js`'s `verifyLastScan` DIRECTLY (per the plan and the
+// root CLAUDE.md's own instruction) — this module does not implement any
+// signature comparison of its own. `verifyLastScan` already uses
+// `crypto.timingSafeEqual` internally.
+//
+// Loaded ONCE at server startup (see bin/agentic-security.js's cmdExplore)
+// and held in memory for the life of the process — this is a read-only,
+// single-scan-snapshot server; a change to the graph on disk mid-session is
+// out of scope for this increment (threat-model doc's own "P0 is
+// read-only" framing).
+
+import * as fs from 'node:fs';
+import { statePath } from '../posture/state-dir.js';
+import { verifyLastScan } from '../posture/integrity.js';
+
+/**
+ * @param {string} scanRoot
+ * @returns {{ok:true, graph:object} | {ok:false, reason:'missing'|'unsigned'|'tampered'|'malformed', message:string}}
+ *
+ * Four, and only four, distinct failure reasons — each with its own clear
+ * message so an operator knows exactly what to do next:
+ *   - 'missing'  — no lineage-graph.json at all. Run a scan with
+ *                  AGENTIC_SECURITY_LINEAGE_DEEP=1 first.
+ *   - 'unsigned' — the graph exists but its .sig sibling does not
+ *                  (verifyLastScan returns null). Refuse to serve an
+ *                  unverifiable graph.
+ *   - 'tampered' — the graph exists and has a .sig, but the signature does
+ *                  not match the body (verifyLastScan returns false). The
+ *                  file was modified after signing, or signed under a
+ *                  different install key.
+ *   - 'malformed' — the body passed signature verification but is not
+ *                  valid JSON. Should not happen from a normal scan; the
+ *                  file may be corrupted on disk after signing.
+ */
+export function loadSignedGraph(scanRoot) {
+  const graphPath = statePath(scanRoot, 'lineage-graph.json');
+  const sigPath = graphPath + '.sig';
+
+  if (!fs.existsSync(graphPath)) {
+    return {
+      ok: false,
+      reason: 'missing',
+      message: `No lineage graph found at ${graphPath}. Run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first (e.g. \`AGENTIC_SECURITY_LINEAGE_DEEP=1 agentic-security scan\`), then re-run \`agentic-security explore\`.`,
+    };
+  }
+
+  let body;
+  try {
+    body = fs.readFileSync(graphPath, 'utf8');
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'missing',
+      message: `Lineage graph found at ${graphPath} but could not be read: ${e && e.message ? e.message : e}.`,
+    };
+  }
+
+  const verified = verifyLastScan(body, sigPath);
+  if (verified === null) {
+    return {
+      ok: false,
+      reason: 'unsigned',
+      message: `Lineage graph at ${graphPath} has no signature file (${sigPath} is missing). Refusing to serve an unverifiable graph. Re-run the scan (AGENTIC_SECURITY_LINEAGE_DEEP=1) to regenerate both files together.`,
+    };
+  }
+  if (verified === false) {
+    return {
+      ok: false,
+      reason: 'tampered',
+      message: `Lineage graph at ${graphPath} FAILED signature verification — its contents do not match ${sigPath}. The file may have been modified after the scan, or signed under a different install key. Refusing to serve a tampered graph. Re-run the scan to regenerate it.`,
+    };
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(body);
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'malformed',
+      message: `Lineage graph at ${graphPath} passed signature verification but is not valid JSON (${e && e.message ? e.message : e}). This should not happen from a normal scan — the file may be corrupted. Re-run the scan to regenerate it.`,
+    };
+  }
+
+  return { ok: true, graph };
+}
+
+/**
+ * Load .agentic-security/lineage-graph.json ONLY when it is genuinely
+ * fresh for THIS scan — never merely because a file happens to exist on
+ * disk. Shared by every caller that signs or narrates a graph:-derived
+ * compliance claim (M4 sub-project 6c's final whole-branch review found
+ * the identical staleness gap independently reachable from
+ * `attest --obligations` AND `compliance --walkthrough`, and required
+ * this predicate to live in exactly one place rather than being
+ * copy-pasted per caller — a safety check that drifts between two
+ * near-identical inline copies is worse than one shared bug).
+ *
+ * `.agentic-security/lineage-graph.json` is only rewritten when a scan
+ * actually finishes building a graph (`if (scan.lineageGraph)` in
+ * bin/agentic-security.js's persistence code) — an ordinary non-deep
+ * rescan, or a deep scan whose lineage build fails, leaves whatever file
+ * was there from an earlier successful deep scan untouched. Loading that
+ * stale graph and joining it to the CURRENT scan's other data would let a
+ * caller assert a graph-derived fact (e.g. "transit protected") about
+ * code that has since changed.
+ *
+ * `enabled: true` in `scan.scanHealth.lineageAnalysis` does NOT by itself
+ * mean the build succeeded — engine.js sets it the moment
+ * AGENTIC_SECURITY_LINEAGE_DEEP=1 is read, before the build even starts,
+ * and leaves it `true` even when the build later throws (only `failure`
+ * gets set in that case). `requested && enabled` alone therefore still
+ * accepts a stale graph after a failed rebuild — reproduced live via the
+ * scan's own already-shipped fault-injection fixture
+ * (test/lineage-fault-injection.test.js) before this `failure === null`
+ * check was added.
+ *
+ * @param {string} scanRoot
+ * @param {object} scan - the parsed last-scan.json for the CURRENT scan
+ * @returns {{graph:object|null, fresh:boolean, loaded:ReturnType<typeof loadSignedGraph>}}
+ *   `fresh` is true only when a signed graph loaded successfully AND this
+ *   scan's own scanHealth confirms lineage analysis was requested,
+ *   enabled, and did not fail. `graph` is `loaded.graph` when fresh, else
+ *   `null` — never the stale file, even when one exists on disk.
+ *   `loaded` is the raw `loadSignedGraph` result, so a caller can still
+ *   distinguish "no file at all" from "a file exists but isn't fresh" for
+ *   its own disclosure message.
+ */
+export function loadFreshLineageGraph(scanRoot, scan) {
+  const la = scan?.scanHealth?.lineageAnalysis;
+  const requested = la?.requested === true;
+  const enabled = la?.enabled === true;
+  const failure = la?.failure ?? null;
+  const loaded = loadSignedGraph(scanRoot);
+  const fresh = loaded.ok && requested && enabled && failure === null;
+  return { graph: fresh ? loaded.graph : null, fresh, loaded };
+}