src/admin-client-audit.ts

Functions

Imports

It imports src/log.ts, src/store-guards.ts. Imported by src/index.ts, src/scope.ts, src/server.ts.

Source

1import { auditStatement } from "./store-guards";
2import { logEvent } from "./log";
3
4// job_e1973c5bcb69, DECIDE 2: for 30 days, record which client the admin acts through,
5// so the seat can see whether a Claude Code session ever reaches /mcp as the admin.
6// OBSERVATION ONLY. Nothing here refuses a call because of what the client says: a
7// clientInfo name and a User-Agent are chosen by the client, so a refusal keyed on
8// either would stop only an honest one (capsid/research/design-local-admin-exposure.md).
9//
10// Two kinds of audit_log row, because /mcp is stateless: createMcpHandler builds a new
11// server and transport per HTTP request (agents/mcp, handler.ts), so a tools/call
12// request carries no clientInfo from the earlier initialize.
13//   - "admin-initialize": the clientInfo name and User-Agent of an initialize request.
14//   - "admin-client": one per admin call that is not a plain read, with the tool, the
15//     User-Agent, and the client name only when the request itself has one (null in
16//     production). Join the two on user_agent.
17// The window ends at a fixed instant, so a merge later than 2026-10-04 shortens it.
18export const ADMIN_CLIENT_AUDIT_UNTIL_MS = Date.parse("2026-11-03T00:00:00Z");
19
20const MAX_FIELD = 200;
21const MAX_INITIALIZE_BODY = 16384;
22const clip = (v: string | null | undefined) => (v ? v.slice(0, MAX_FIELD) : null);
23
24interface AdminWriteCall {
25  tool: string;
26  action: string | undefined;
27  namespace: string | undefined;
28}
29
30// Resolves to a refusal message, or null to let the call run. These rows are
31// observation only (D2, ruled by Dustin 2026-10-04), so a row that cannot be written is
32// logged under ADMIN_CLIENT_AUDIT_FAILED and the call proceeds: the observer returns
33// null on every path today. The type keeps the refusal arm because the registrar's
34// contract is shared. Every other audit row keeps its own behavior.
35export type AdminWriteObserver = (call: AdminWriteCall, clientName: string | null) => Promise<string | null>;
36
37function reportFailure(what: string, err: unknown): void {
38  logEvent("error", "ADMIN_CLIENT_AUDIT_FAILED", { message: `ADMIN_CLIENT_AUDIT_FAILED ${what}: ${err instanceof Error ? err.message : String(err)}` });
39}
40
41export function adminWriteObserver(db: D1Database, actor: string, userAgent: string | null, now: () => number = Date.now): AdminWriteObserver {
42  return async (call, clientName) => {
43    if (now() >= ADMIN_CLIENT_AUDIT_UNTIL_MS) return null;
44    try {
45      await auditStatement(db, actor, "admin-client", call.namespace ?? null, null, {
46        tool: call.tool,
47        action: call.action ?? null,
48        user_agent: clip(userAgent),
49        client_name: clip(clientName),
50      }).run();
51      return null;
52    } catch (err) {
53      reportFailure(call.tool, err);
54      return null;
55    }
56  };
57}
58
59// The clientInfo of an initialize request, from the JSON-RPC body (one message or a
60// batch). Null when the body is not one. A body that is not JSON is the MCP handler's
61// to reject, so it is not an error here: there is simply no initialize to record.
62export function initializeClient(body: unknown): { client_name: string | null; protocol_version: string | null } | null {
63  const messages = Array.isArray(body) ? body : [body];
64  for (const m of messages) {
65    if (!m || typeof m !== "object" || (m as { method?: unknown }).method !== "initialize") continue;
66    const params = (m as { params?: { clientInfo?: { name?: unknown }; protocolVersion?: unknown } }).params;
67    const name = params?.clientInfo?.name;
68    const version = params?.protocolVersion;
69    return {
70      client_name: typeof name === "string" ? clip(name) : null,
71      protocol_version: typeof version === "string" ? clip(version) : null,
72    };
73  }
74  return null;
75}
76
77// Reads the request's own body, on a clone, only when it is small enough to be an
78// initialize (they are a few hundred bytes), so a large document write is never read
79// twice. A failed insert is logged and the connect proceeds (observation only).
80export async function recordAdminInitialize(
81  db: D1Database,
82  actor: string,
83  request: Request,
84  now: () => number = Date.now
85): Promise<boolean> {
86  if (now() >= ADMIN_CLIENT_AUDIT_UNTIL_MS || request.method !== "POST") return false;
87  const length = Number(request.headers.get("content-length"));
88  if (!Number.isFinite(length) || length <= 0 || length > MAX_INITIALIZE_BODY) return false;
89  let body: unknown;
90  try {
91    body = JSON.parse(await request.clone().text());
92  } catch {
93    return false;
94  }
95  const client = initializeClient(body);
96  if (!client) return false;
97  try {
98    await auditStatement(db, actor, "admin-initialize", null, null, { ...client, user_agent: clip(request.headers.get("User-Agent")) }).run();
99  } catch (err) {
100    reportFailure("initialize", err);
101    return false;
102  }
103  return true;
104}