@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

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 };
+}

package/src/server/http-server.js

@@ -0,0 +1,325 @@
+// http-server.js — Milestone 3, sub-project Server, increment 1.
+//
+// The real node:http server for `agentic-security explore`. Binds ONLY to
+// 127.0.0.1 (never 0.0.0.0, never an omitted host arg). Every request is
+// validated (Host header, then session token) before any route handler
+// ever runs. Every response carries CSP + Cache-Control: no-store and
+// NEVER carries Access-Control-Allow-Origin (CORS stays disabled by the
+// absence of that header — see security.js).
+//
+// This is the first node:http usage anywhere in scanner/src/.
+
+import * as http from 'node:http';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isValidHost, constantTimeEqual, CSP_HEADER_VALUE } from './security.js';
+import { handleScan, handleGraph, handleNode, handleEdge, handleFlow, handleQuery } from './routes.js';
+import { resolveStaticAsset, FRONTEND_ROOT, STATIC_CSP_HEADER_VALUE } from './static-assets.js';
+
+// Idle-timeout default. No PRD-specified duration exists (confirmed by the
+// scoping doc's own search) — 30 minutes is a reasoned, disclosed default:
+// long enough that a human actually exploring a graph in a browser tab
+// won't get cut off mid-session, short enough that a forgotten terminal
+// doesn't leave a loopback server (and its session token, printed once to
+// stdout/scrollback) listening indefinitely.
+export const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+
+// Request-size cap, applied uniformly to every request. Milestone 5's own
+// POST /api/v1/query is the first real consumer of a request body — every
+// pre-M5 GET endpoint has no meaningful body of its own, so this mostly
+// protects that one route today, but the cap applies to any future
+// body-bearing route without retrofitting. 64KB is generous for any
+// header/body this server should ever legitimately receive.
+export const MAX_REQUEST_BODY_BYTES = 64 * 1024;
+
+// Session token header. A custom header (never a query param) so the
+// token never ends up in server access logs, browser history, or a
+// Referer header the way a query-string token could.
+export const TOKEN_HEADER = 'x-agentic-security-token';
+
+function _log(method, urlPath, status, durationMs) {
+  // Metadata only — NEVER log request/response bodies, NEVER log the
+  // session token itself, even on a failed-auth attempt (T3/§17.4).
+  console.error(`[explore] ${method} ${urlPath} ${status} ${durationMs}ms`);
+}
+
+function _sendJson(res, status, bodyObj) {
+  const body = JSON.stringify(bodyObj);
+  if (!res.headersSent) {
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Content-Security-Policy': CSP_HEADER_VALUE,
+      'Cache-Control': 'no-store',
+      'Content-Length': Buffer.byteLength(body),
+      // Access-Control-Allow-Origin is intentionally NEVER set anywhere in
+      // this file. CORS stays disabled by the absence of this header.
+    });
+  }
+  res.end(body);
+}
+
+const ROUTES = [
+  { method: 'GET', pattern: /^\/api\/v1\/scan\/?$/, handler: (graph) => handleScan(graph) },
+  { method: 'GET', pattern: /^\/api\/v1\/graph\/?$/, handler: (graph) => handleGraph(graph) },
+  { method: 'GET', pattern: /^\/api\/v1\/nodes\/([^/]+)\/?$/, handler: (graph, m) => handleNode(graph, decodeURIComponent(m[1])) },
+  { method: 'GET', pattern: /^\/api\/v1\/edges\/([^/]+)\/?$/, handler: (graph, m) => handleEdge(graph, decodeURIComponent(m[1])) },
+  { method: 'GET', pattern: /^\/api\/v1\/flows\/([^/]+)\/?$/, handler: (graph, m) => handleFlow(graph, decodeURIComponent(m[1])) },
+  { method: 'POST', pattern: /^\/api\/v1\/query\/?$/, handler: (graph, m, body) => handleQuery(graph, body?.filter) },
+];
+
+/**
+ * Serves one resolved static asset from disk. `resolved` is a real
+ * `{ok:true, relativePath, contentType}` from resolveStaticAsset() —
+ * already vetted against the allowlist, so the only failure mode left here
+ * is the file genuinely missing/unreadable on disk (allowlist/inventory
+ * drift), which degrades to a 404 rather than a 500.
+ *
+ * `relativePath` is built entirely from static-assets.js's own restricted
+ * character class (no backslash, already traversal-checked) before it ever
+ * reaches this function, so joining it onto FRONTEND_ROOT with the platform
+ * path.join is safe.
+ */
+function _serveStaticAsset(res, resolved) {
+  let body;
+  try {
+    body = fs.readFileSync(path.join(FRONTEND_ROOT, resolved.relativePath));
+  } catch {
+    _sendJson(res, 404, { error: 'not found' });
+    return 404;
+  }
+  if (!res.headersSent) {
+    res.writeHead(200, {
+      'Content-Type': resolved.contentType,
+      // The STATIC CSP (same-origin-permitting), NOT the JSON API's
+      // `default-src 'none'` — this response is HTML/JS/CSS, not JSON.
+      'Content-Security-Policy': STATIC_CSP_HEADER_VALUE,
+      'Cache-Control': 'no-store',
+      'Content-Length': body.length,
+      // Access-Control-Allow-Origin is intentionally NEVER set anywhere in
+      // this file, on any response, static or JSON alike.
+    });
+  }
+  res.end(body);
+  return 200;
+}
+
+/**
+ * Creates and starts the `explore` HTTP server. Returns a Promise that
+ * resolves once the server is actually listening, with `{server, port}`
+ * (the REAL bound port, resolved from the OS when `port: 0`/omitted was
+ * requested).
+ *
+ * @param {object} opts
+ * @param {object} opts.graph - the verified, in-memory lineage graph
+ * @param {number} [opts.port=0] - 0 lets the OS choose a random free port
+ * @param {string} opts.sessionToken - required on every request
+ * @param {number} [opts.idleTimeoutMs=DEFAULT_IDLE_TIMEOUT_MS]
+ * @param {boolean} [opts.keepOpen=false] - suppresses idle-timeout auto-stop
+ */
+export function createExploreServer({
+  graph,
+  port = 0,
+  sessionToken,
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  keepOpen = false,
+} = {}) {
+  if (!graph || typeof graph !== 'object') {
+    throw new Error('createExploreServer requires a graph object');
+  }
+  if (typeof sessionToken !== 'string' || sessionToken.length < 32) {
+    throw new Error('createExploreServer requires a real sessionToken (>= 32 chars)');
+  }
+
+  let idleTimer = null;
+
+  function _clearIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  // Reset the idle-auto-stop timer. Only called for requests that pass
+  // BOTH the Host and session-token checks — an unauthenticated request
+  // (a DNS-rebinding probe, a stray scan) must never be able to keep the
+  // server alive indefinitely by hammering it; only genuine, authenticated
+  // activity extends the session.
+  function _resetIdleTimer() {
+    if (keepOpen) return;
+    _clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      try { server.closeAllConnections?.(); } catch { /* best-effort */ }
+      server.close();
+    }, idleTimeoutMs);
+    // Don't let this timer alone keep the Node process alive past a clean
+    // shutdown path.
+    if (typeof idleTimer.unref === 'function') idleTimer.unref();
+  }
+
+  const server = http.createServer((req, res) => {
+    const start = Date.now();
+    const method = req.method || 'GET';
+    let urlPath = '/';
+    try {
+      urlPath = new URL(req.url, 'http://internal').pathname;
+    } catch {
+      urlPath = req.url || '/';
+    }
+
+    const finish = (status) => _log(method, urlPath, status, Date.now() - start);
+
+    // The actual bound port. Cheap (no syscall — Node caches the bound
+    // address on the server object), so it's safe to read per-request
+    // rather than caching it in a closure variable that could theoretically
+    // race the 'listening' event.
+    const boundPort = server.address()?.port;
+
+    // 1. Host header validation (T2 defense) — before anything else.
+    const hostHeader = req.headers.host;
+    if (!isValidHost(hostHeader, boundPort)) {
+      _sendJson(res, 400, { error: 'invalid Host header' });
+      finish(400);
+      req.resume(); // drain and discard any body without processing it
+      return;
+    }
+
+    // 1.5. Static-asset serving (Wire's own new surface) — the ONE
+    // deliberate, disclosed exception to "every request requires a session
+    // token" below. The token travels to the browser via a URL FRAGMENT
+    // (`#token=...`), which is NEVER sent to the server by the browser in
+    // any HTTP request — so the very first page-load request (GET /) is
+    // structurally incapable of carrying it. Every subsequent same-origin
+    // fetch() the page itself makes against /api/v1/* still requires the
+    // token, completely unchanged from S1.
+    //
+    // Namespaced away from /api/v1/* so there is no ambiguity: any GET
+    // request NOT under /api/ is resolved against the static-asset
+    // allowlist and NEVER reaches the token check at all, matching or
+    // rejecting with a 404 (never a 403 — a 403 would confirm to a prober
+    // that a rejected path exists). This still runs strictly AFTER the
+    // Host-header check above (T2 applies uniformly, auth or not — DNS
+    // rebinding does not care whether the resource behind it needs a
+    // token).
+    if (method === 'GET' && !urlPath.startsWith('/api/')) {
+      const staticResult = resolveStaticAsset(urlPath);
+      if (staticResult.ok) {
+        const status = _serveStaticAsset(res, staticResult);
+        finish(status);
+      } else {
+        _sendJson(res, 404, { error: 'not found' });
+        finish(404);
+      }
+      req.resume();
+      return;
+    }
+
+    // 2. Session-token validation (T3 defense) — required on EVERY
+    // request, read or write, per the threat-model doc's own §17.4
+    // checklist. Compared in constant time.
+    const provided = req.headers[TOKEN_HEADER];
+    if (typeof provided !== 'string' || !constantTimeEqual(provided, sessionToken)) {
+      _sendJson(res, 401, { error: 'missing or invalid session token' });
+      finish(401);
+      req.resume();
+      return;
+    }
+
+    // Genuine, authenticated request — extend the idle-auto-stop window.
+    _resetIdleTimer();
+
+    // 3. Request-size cap, applied uniformly (S1's GET endpoints have no
+    // meaningful body; Milestone 5's own POST /api/v1/query is the first
+    // real consumer). Milestone 5 also starts accumulating the actual body
+    // BYTES (not just the size) — no earlier route needed them.
+    let bodySize = 0;
+    let bodyChunks = [];
+    let aborted = false;
+    req.on('data', (chunk) => {
+      if (aborted) return;
+      bodySize += chunk.length;
+      if (bodySize > MAX_REQUEST_BODY_BYTES) {
+        aborted = true;
+        _sendJson(res, 413, { error: 'request body too large' });
+        finish(413);
+        // Stop reading further body bytes only once the 413 response has
+        // actually been flushed to the client — destroying the request
+        // stream immediately can race the response write and cut it off
+        // before the client sees it.
+        res.once('finish', () => { try { req.destroy(); } catch { /* best-effort */ } });
+        return;
+      }
+      bodyChunks.push(chunk);
+    });
+
+    req.on('end', () => {
+      if (aborted) return;
+
+      // 4. Route.
+      let matched = null;
+      let match = null;
+      for (const route of ROUTES) {
+        if (route.method !== method) continue;
+        const m = route.pattern.exec(urlPath);
+        if (m) { matched = route; match = m; break; }
+      }
+      if (!matched) {
+        _sendJson(res, 404, { error: 'not found' });
+        finish(404);
+        return;
+      }
+
+      // Milestone 5: parse the body ONLY for a matched route, and only as
+      // JSON when non-empty — every pre-M5 GET route still ignores this
+      // 3rd argument entirely, so an empty/missing body for them is a
+      // no-op, not an error. Disclosed, real, low-risk behavior change
+      // (final whole-branch review finding): this JSON-parse pass applies
+      // to ANY matched route with a non-empty body, not just the new POST
+      // /api/v1/query — a GET request that (unusually) carries a
+      // non-JSON-parseable body now gets a clean 400 instead of the
+      // pre-M5 behavior (body silently drained, request processed
+      // normally). No real client sends a body on a GET here
+      // (frontend/src/lib/api-client.js's own fetch() calls never do), so
+      // this is not expected to affect any real caller — narrower
+      // per-method gating was judged unnecessary complexity for a case
+      // with no real-world traffic, but is a real, disclosed option if
+      // this ever needs revisiting.
+      let body;
+      if (bodyChunks.length > 0) {
+        try {
+          body = JSON.parse(Buffer.concat(bodyChunks).toString('utf8'));
+        } catch {
+          _sendJson(res, 400, { error: 'malformed JSON request body' });
+          finish(400);
+          return;
+        }
+      }
+
+      try {
+        const result = matched.handler(graph, match, body);
+        _sendJson(res, result.status, result.body);
+        finish(result.status);
+      } catch {
+        _sendJson(res, 500, { error: 'internal error' });
+        finish(500);
+      }
+    });
+
+    req.on('error', () => {
+      // A client that aborts mid-request — nothing to respond to.
+      aborted = true;
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    const onError = (err) => reject(err);
+    server.once('error', onError);
+    // Bind explicitly to 127.0.0.1 — never omit the host argument (that is
+    // NOT the same as 127.0.0.1 on every platform) and never 0.0.0.0.
+    server.listen(port, '127.0.0.1', () => {
+      server.removeListener('error', onError);
+      const actualPort = server.address().port;
+      _resetIdleTimer(); // start the idle clock even before the first request
+      resolve({ server, port: actualPort });
+    });
+  });
+}

package/src/server/routes.js

@@ -0,0 +1,129 @@
+// routes.js — Milestone 3, sub-project Server, increment 1.
+//
+// Five pure GET-endpoint handlers, each `(graph, ...) -> {status, body}`.
+// No req/res access anywhere in this file — that is what makes these
+// handlers unit-testable without an HTTP layer at all. http-server.js is
+// the only module that touches node:http and calls into these.
+//
+// Every response body is wrapped in `wrapResponse`, which adds the exact
+// envelope fields PRD line 1326 names (quoted in the implementation plan):
+// "base graph/snapshot digest, schema/extension versions, scope, coverage,
+// limitations, and contributing canonical IDs."
+
+import { _filterGraph, validateFilterShape } from '../lineage/export-json.js';
+
+/**
+ * Shared response envelope. Maps PRD line 1326's required fields onto the
+ * graph's own real fields:
+ *   - digest              -> graph.graphId (the base graph/snapshot digest)
+ *   - schemaVersion        -> graph.schemaVersion
+ *   - extensions           -> graph.extensions (schema/extension versions —
+ *                             today always `{}`; see schema.js)
+ *   - scope                -> graph.scope
+ *   - coverage              -> graph.coverage
+ *   - limitations           -> graph.limitations
+ *   - canonicalIds          -> see the design note below
+ *
+ * "contributing canonical IDs" design decision (disclosed per the plan):
+ * for `handleScan`/`handleGraph`, which describe the WHOLE graph rather
+ * than one entity, `canonicalIds` is `null` — the response body for
+ * `handleGraph` already IS the full nodes/edges/flows arrays, so echoing
+ * every id again here would be pure duplication with no informational
+ * gain, and for a large graph would materially bloat the response for
+ * zero benefit. For `handleNode`/`handleEdge`, `canonicalIds` is the
+ * single id the response is about. For `handleFlow`, `canonicalIds` is
+ * the flow's own id PLUS the node/edge ids that flow's evidence draws
+ * from (source, sink, edgeIds) — a flow is a derived record referencing
+ * several underlying entities, and naming all of them here is genuinely
+ * useful metadata a client would otherwise have to re-derive from the
+ * flow body itself.
+ */
+export function wrapResponse(data, graph, { canonicalIds = null } = {}) {
+  return {
+    digest: graph?.graphId ?? null,
+    schemaVersion: graph?.schemaVersion ?? null,
+    extensions: graph?.extensions ?? {},
+    scope: graph?.scope ?? null,
+    coverage: graph?.coverage ?? null,
+    limitations: graph?.limitations ?? [],
+    canonicalIds,
+    data,
+  };
+}
+
+function _findById(list, id) {
+  if (!Array.isArray(list)) return null;
+  return list.find((item) => item && item.id === id) ?? null;
+}
+
+/** Scan/graph metadata — NOT the full node/edge arrays. */
+export function handleScan(graph) {
+  const data = {
+    schemaVersion: graph?.schemaVersion ?? null,
+    graphId: graph?.graphId ?? null,
+    generatedAt: graph?.generatedAt ?? null,
+    scope: graph?.scope ?? null,
+    scanHealth: graph?.scanHealth ?? null,
+    coverage: graph?.coverage ?? null,
+  };
+  return { status: 200, body: wrapResponse(data, graph, { canonicalIds: null }) };
+}
+
+/** The full graph document, unfiltered. For a scoped/narrowed projection, use `handleQuery` (`POST /api/v1/query`, Milestone 5) below instead. */
+export function handleGraph(graph) {
+  return { status: 200, body: wrapResponse(graph, graph, { canonicalIds: null }) };
+}
+
+/**
+ * A deterministic typed projection query — Milestone 5's own
+ * `POST /api/v1/query`, the S2 endpoint `handleGraph`'s own header
+ * comment named and deferred. `filter` is the exact `{nodeIds, edgeIds}`
+ * shape `dataflow export --filter`/`exportGraphJSON` already use — reused
+ * via `_filterGraph`, never reimplemented. Final whole-branch review
+ * finding: `undefined` (filter omitted entirely) returns the WHOLE graph,
+ * identical to `handleGraph` — but `{}` (an empty, well-formed filter
+ * object) is NOT the same thing, and does NOT mean "no restriction": both
+ * `nodeIds`/`edgeIds` default to empty Sets inside `_filterGraph`, so `{}`
+ * narrows the graph down to EMPTY node/edge/flow/dataElement arrays. A
+ * caller that wants the whole graph must omit `filter` entirely, never
+ * pass `{}` meaning "everything." A malformed filter is a 400, never a
+ * thrown exception reaching the caller.
+ */
+export function handleQuery(graph, filter) {
+  const check = validateFilterShape(filter);
+  if (!check.valid) {
+    return { status: 400, body: { error: check.error } };
+  }
+  return { status: 200, body: wrapResponse(_filterGraph(graph, filter), graph, { canonicalIds: null }) };
+}
+
+/** Look up one node by id. 404 with a clear body if not found. */
+export function handleNode(graph, id) {
+  const node = _findById(graph?.nodes, id);
+  if (!node) {
+    return { status: 404, body: wrapResponse({ error: `node not found: ${id}` }, graph, { canonicalIds: [] }) };
+  }
+  return { status: 200, body: wrapResponse(node, graph, { canonicalIds: [id] }) };
+}
+
+/** Look up one edge by id. 404 with a clear body if not found. */
+export function handleEdge(graph, id) {
+  const edge = _findById(graph?.edges, id);
+  if (!edge) {
+    return { status: 404, body: wrapResponse({ error: `edge not found: ${id}` }, graph, { canonicalIds: [] }) };
+  }
+  return { status: 200, body: wrapResponse(edge, graph, { canonicalIds: [id] }) };
+}
+
+/** Look up one flow by id. 404 with a clear body if not found. */
+export function handleFlow(graph, id) {
+  const flow = _findById(graph?.flows, id);
+  if (!flow) {
+    return { status: 404, body: wrapResponse({ error: `flow not found: ${id}` }, graph, { canonicalIds: [] }) };
+  }
+  const contributing = new Set([id]);
+  if (flow.source) contributing.add(flow.source);
+  if (flow.sink) contributing.add(flow.sink);
+  for (const eid of (flow.edgeIds || [])) contributing.add(eid);
+  return { status: 200, body: wrapResponse(flow, graph, { canonicalIds: [...contributing] }) };
+}