audit-log.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1/**
2 * The MCP servers' tool-call log: an append-only log of every tool call, with the caller, the arguments and the result
3 * (ruling mcp-2026-10-10, rule 12.4).
4 *
5 * A Durable Object with synchronous SQLite, one instance for the Worker. The class has exactly one write, an INSERT,
6 * and no UPDATE, DELETE or read path over HTTP, so nothing that reaches the Worker can rewrite a row. Read it in the
7 * Cloudflare dashboard's Durable Object data view.
8 *
9 * A refused call is one `refused` row and sent nothing on. An allowed call is two rows: `started` is written before the
10 * API is called, and the call is refused if that write fails, so no tool runs unlogged. `finished` carries the result;
11 * if that write fails the call has already happened, so the failure goes to the Worker log.
12 *
13 * A row carries the caller's audit name (a signed-in email or an agent principal, never a credential), the tool, the
14 * arguments and the result. A long string argument is stored as its length and a SHA-256 prefix, enough to prove which
15 * bytes were sent without keeping a second copy of the content.
16 */
17
18const LONG_STRING = 200;
19const RESULT_CHARS = 1000;
20
21/** The Durable Object class a Worker exports (as ToolCallLog) and binds as TOOL_CALL_LOG. */
22export class ToolCallLog {
23  /** @param {DurableObjectState} state */
24  constructor(state) {
25    this.sql = state.storage.sql;
26    this.sql.exec(
27      "CREATE TABLE IF NOT EXISTS calls (" +
28        "seq INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, call_id TEXT NOT NULL, " +
29        "phase TEXT NOT NULL, caller TEXT NOT NULL, tool TEXT NOT NULL, args TEXT NOT NULL, result TEXT)",
30    );
31  }
32
33  /** @param {Request} request */
34  async fetch(request) {
35    if (request.method !== "POST") return new Response("append only", { status: 405 });
36    const row = /** @type {import("./audit-log.d.mts").AuditRow} */ (await request.json());
37    this.sql.exec(
38      "INSERT INTO calls (at, call_id, phase, caller, tool, args, result) VALUES (?, ?, ?, ?, ?, ?, ?)",
39      new Date().toISOString(),
40      String(row.callId),
41      String(row.phase),
42      String(row.caller),
43      String(row.tool),
44      JSON.stringify(row.args ?? {}),
45      row.result === undefined ? null : JSON.stringify(row.result),
46    );
47    return new Response(null, { status: 204 });
48  }
49}
50
51/** @param {string} text */
52async function digest(text) {
53  const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
54  return [...bytes.slice(0, 8)].map((b) => b.toString(16).padStart(2, "0")).join("");
55}
56
57/**
58 * The arguments as the log stores them: long strings become their length and a digest prefix.
59 * @param {Record<string, unknown>} args
60 */
61export async function loggedArgs(args) {
62  /** @type {Record<string, unknown>} */
63  const out = {};
64  for (const [key, value] of Object.entries(args)) {
65    out[key] = typeof value === "string" && value.length > LONG_STRING ? { chars: value.length, sha256: await digest(value) } : value;
66  }
67  return out;
68}
69
70/**
71 * The result as the log stores it: whether it failed, and the start of its text.
72 * @param {{ isError?: boolean, content: Array<{ text: string }> }} output
73 */
74export function loggedResult(output) {
75  const text = output.content.map((c) => c.text).join("\n");
76  return { isError: output.isError === true, text: text.slice(0, RESULT_CHARS) };
77}
78
79/**
80 * Appends one row. Throws when the binding is missing or the write fails, so the caller decides: a failed `started`
81 * refuses the call, a failed `finished` is reported to the Worker log.
82 * @param {Partial<import("./audit-log.d.mts").AuditEnv>} env
83 * @param {import("./audit-log.d.mts").AuditRow} row
84 */
85export async function appendAudit(env, row) {
86  if (!env.TOOL_CALL_LOG) throw new Error("the TOOL_CALL_LOG binding is missing");
87  const stub = env.TOOL_CALL_LOG.get(env.TOOL_CALL_LOG.idFromName("tool-calls"));
88  const response = await stub.fetch("https://tool-call-log.invalid/append", {
89    method: "POST",
90    headers: { "content-type": "application/json" },
91    body: JSON.stringify(row),
92  });
93  if (response.status !== 204) throw new Error(`the tool-call log answered ${response.status}`);
94}