@frockbot/plugin-audit 0.0.0 → 0.1.1

package/src/testing.ts

@@ -0,0 +1,197 @@
+// A fake `AuditSqlV1`, and a fake outbox storage, for unit tests.
+//
+// The SQL fake is not an SQL engine. It recognises exactly the statements
+// `AuditStoreV1` issues and answers them from JavaScript arrays. That is
+// enough to hold the module's real logic to account — idempotency on
+// `(botId, runId, occurrenceId)`, both eviction bounds and their durable
+// marker, purge, filters and paging — while `audit.workerd.ts` proves the same
+// module against a real table on `ctx.storage.sql`.
+import type { AuditSqlCursorV1, AuditSqlV1, AuditSqlValueV1 } from "./store.js";
+import type { AuditOutboxStorageV1 } from "./bot.js";
+
+interface FakeRow extends Record<string, AuditSqlValueV1> {
+  bot_id: string;
+  run_id: string;
+  occurrence_id: string;
+  turn: number;
+  step: number;
+  ordinal: number;
+  effect_id: string;
+  at: string;
+  kind: string;
+  target: string;
+  tool_name: string;
+  argument_digest: string;
+  preview: string;
+  outcome: string;
+  exit_code: number | null;
+  duration_ms: number | null;
+  bytes_out: number | null;
+}
+
+const COLUMNS = [
+  "bot_id",
+  "run_id",
+  "occurrence_id",
+  "turn",
+  "step",
+  "ordinal",
+  "effect_id",
+  "at",
+  "kind",
+  "target",
+  "tool_name",
+  "argument_digest",
+  "preview",
+  "outcome",
+  "exit_code",
+  "duration_ms",
+  "bytes_out",
+] as const;
+
+function cursor<Row extends Record<string, AuditSqlValueV1>>(
+  rows: Row[],
+): AuditSqlCursorV1<Row> {
+  return { toArray: () => rows };
+}
+
+function order(left: FakeRow, right: FakeRow): number {
+  return (
+    left.at.localeCompare(right.at) ||
+    left.bot_id.localeCompare(right.bot_id) ||
+    left.run_id.localeCompare(right.run_id) ||
+    left.occurrence_id.localeCompare(right.occurrence_id)
+  );
+}
+
+export class FakeAuditSql implements AuditSqlV1 {
+  private rows: FakeRow[] = [];
+  private meta = new Map<string, string>();
+  /** Every statement the module issued, for tests that assert on shape. */
+  readonly statements: string[] = [];
+
+  exec<Row extends Record<string, AuditSqlValueV1>>(
+    query: string,
+    ...bindings: unknown[]
+  ): AuditSqlCursorV1<Row> {
+    this.statements.push(query);
+    const sql = query.replace(/\s+/g, " ").trim();
+    const answer = (rows: unknown[]) => cursor(rows as Row[]);
+
+    if (sql.startsWith("CREATE") || sql.startsWith("DROP")) return answer([]);
+
+    if (sql.startsWith("SELECT value FROM audit_meta")) {
+      const value = this.meta.get(String(bindings[0]));
+      return answer(value === undefined ? [] : [{ value }]);
+    }
+    if (sql.startsWith("INSERT INTO audit_meta")) {
+      this.meta.set(String(bindings[0]), String(bindings[1]));
+      return answer([]);
+    }
+    if (sql.startsWith("DELETE FROM audit_meta")) {
+      this.meta.delete(String(bindings[0]));
+      return answer([]);
+    }
+    if (sql.startsWith("INSERT INTO audit_entries")) {
+      const row = Object.fromEntries(
+        COLUMNS.map((column, index) => [column, bindings[index] ?? null]),
+      ) as FakeRow;
+      this.rows.push(row);
+      return answer([]);
+    }
+    if (sql.startsWith("SELECT count(*) AS n FROM audit_entries")) {
+      return answer([{ n: this.filtered(sql, bindings).length }]);
+    }
+    if (sql.startsWith("SELECT bot_id, run_id, occurrence_id FROM")) {
+      const limit = Number(bindings[0]);
+      return answer(
+        [...this.rows]
+          .sort(order)
+          .slice(0, limit)
+          .map((row) => ({
+            bot_id: row.bot_id,
+            run_id: row.run_id,
+            occurrence_id: row.occurrence_id,
+          })),
+      );
+    }
+    if (sql.startsWith("DELETE FROM audit_entries WHERE at <")) {
+      this.rows = this.rows.filter((row) => row.at >= String(bindings[0]));
+      return answer([]);
+    }
+    if (
+      sql.startsWith(
+        "DELETE FROM audit_entries WHERE bot_id = ? AND run_id = ? AND occurrence_id = ?",
+      )
+    ) {
+      this.rows = this.rows.filter(
+        (row) =>
+          !(
+            row.bot_id === bindings[0] &&
+            row.run_id === bindings[1] &&
+            row.occurrence_id === bindings[2]
+          ),
+      );
+      return answer([]);
+    }
+    if (sql.startsWith("DELETE FROM audit_entries WHERE bot_id = ?")) {
+      this.rows = this.rows.filter((row) => row.bot_id !== bindings[0]);
+      return answer([]);
+    }
+    if (sql === "DELETE FROM audit_entries") {
+      this.rows = [];
+      return answer([]);
+    }
+    if (sql.startsWith("SELECT * FROM audit_entries")) {
+      const descending = [...this.filtered(sql, bindings)].sort(
+        (left, right) => -order(left, right),
+      );
+      if (!sql.includes("LIMIT")) return answer(descending);
+      const limit = Number(bindings[bindings.length - 2]);
+      const offset = Number(bindings[bindings.length - 1]);
+      return answer(descending.slice(offset, offset + limit));
+    }
+    throw new Error(`FakeAuditSql does not recognise: ${sql}`);
+  }
+
+  /** Applies the `WHERE bot_id/kind/target` clauses the store builds. */
+  private filtered(sql: string, bindings: unknown[]): FakeRow[] {
+    const values = [...bindings];
+    const where = /WHERE (.+?)(?: ORDER BY| LIMIT|$)/.exec(sql)?.[1] ?? "";
+    if (where.startsWith("at <")) {
+      return this.rows.filter((row) => row.at < String(values[0]));
+    }
+    const predicates: Array<(row: FakeRow) => boolean> = [];
+    for (const clause of where.split(" AND ").filter(Boolean)) {
+      const column = clause.split(" ")[0] as keyof FakeRow;
+      if (!COLUMNS.includes(column as (typeof COLUMNS)[number])) continue;
+      const expected = String(values.shift());
+      predicates.push((row) => String(row[column]) === expected);
+    }
+    return this.rows.filter((row) =>
+      predicates.every((predicate) => predicate(row)),
+    );
+  }
+}
+
+/** An in-memory `AuditOutboxStorageV1`. */
+export class FakeAuditOutboxStorage implements AuditOutboxStorageV1 {
+  private readonly values = new Map<string, unknown>();
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const value = this.values.get(key);
+    // Durable Object storage round-trips through structured clone, so a test
+    // that shared an object reference would prove less than production does.
+    return value === undefined
+      ? undefined
+      : (JSON.parse(JSON.stringify(value)) as T);
+  }
+
+  async put<T>(key: string, value: T): Promise<void> {
+    this.values.set(key, JSON.parse(JSON.stringify(value)));
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.values.delete(key);
+  }
+}

package/src/user.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+import { AuditUserBackendContribution, resolveAuditTargetV1 } from "./user.ts";
+import { FakeAuditSql } from "./testing.ts";
+import type { AuditEntryV1 } from "./shared.ts";
+
+function entry(overrides: Partial<AuditEntryV1> = {}): AuditEntryV1 {
+  const occurrenceId = overrides.occurrenceId ?? "tool:1:1:0";
+  const [, turn, step, ordinal] = /^tool:(\d+):(\d+):(\d+)$/.exec(
+    occurrenceId,
+  )!;
+  return {
+    schemaVersion: 1,
+    botId: "foreman",
+    runId: "run-1",
+    occurrenceId,
+    turn: Number(turn),
+    step: Number(step),
+    ordinal: Number(ordinal),
+    effectId: occurrenceId,
+    at: "2026-08-31T00:00:00.000Z",
+    kind: "shell",
+    target: "computer",
+    toolName: "computer_exec",
+    argumentDigest: "a".repeat(64),
+    preview: "ls -la",
+    outcome: "ok",
+    ...overrides,
+  };
+}
+
+function contribution(
+  options: {
+    entries?: AuditEntryV1[];
+    hosts?: Map<string, string>;
+    journal?: string[];
+  } = {},
+) {
+  return new AuditUserBackendContribution({
+    sql: new FakeAuditSql(),
+    readDirectory: async () => ({ botIds: ["foreman"] }),
+    projectBotEntries: async (botId, cursor) => ({
+      schemaVersion: 1,
+      botId,
+      entries: cursor ? [] : (options.entries ?? []),
+    }),
+    ...(options.hosts ? { readMcpHosts: async () => options.hosts! } : {}),
+    ...(options.journal
+      ? { readHostJournalEffectIds: async () => options.journal! }
+      : {}),
+  });
+}
+
+describe("resolving an MCP target against the Connection registry", () => {
+  test("turns the Connection slug into the server's host", () => {
+    const hosts = new Map([["example", "mcp.example.test"]]);
+    expect(resolveAuditTargetV1("remote:example", hosts)).toBe(
+      "remote:mcp.example.test",
+    );
+    // A slug the registry does not know stays a slug. That is a less specific
+    // row, not a wrong one — better than claiming a host nobody can vouch for.
+    expect(resolveAuditTargetV1("remote:beeper", hosts)).toBe("remote:beeper");
+    // Everything else is complete as the classifier wrote it.
+    expect(resolveAuditTargetV1("computer", hosts)).toBe("computer");
+    expect(resolveAuditTargetV1("machine:mac-1", hosts)).toBe("machine:mac-1");
+  });
+
+  test("is applied on the projection path and the rebuild path alike", async () => {
+    const hosts = new Map([["example", "mcp.example.test"]]);
+    const mcp = entry({
+      occurrenceId: "tool:1:1:1",
+      kind: "mcp",
+      target: "remote:example",
+      toolName: "mcp__example__echo",
+    });
+    const audit = contribution({ entries: [mcp], hosts });
+    await audit.indexAuditEntries([mcp]);
+    expect(audit.query({}).entries.map((row) => row.target)).toEqual([
+      "remote:mcp.example.test",
+    ]);
+    // The rebuild reads the same unresolved rows back out of the Bot and must
+    // land on the identical target, or the table would change under a repair.
+    await audit.rebuildAuditIndex();
+    expect(audit.query({}).entries.map((row) => row.target)).toEqual([
+      "remote:mcp.example.test",
+    ]);
+  });
+});
+
+describe("the User Contribution", () => {
+  test("refuses anything that is not a bounded array of entries", async () => {
+    const audit = contribution();
+    await expect(audit.indexAuditEntries({})).rejects.toThrow("an array");
+    await expect(
+      audit.indexAuditEntries(Array.from({ length: 513 }, () => entry())),
+    ).rejects.toThrow("bound");
+    await expect(
+      audit.indexAuditEntries([{ ...entry(), turn: 7 }]),
+    ).rejects.toThrow("disagree");
+  });
+
+  test("counts host-journal discrepancies without writing them in", async () => {
+    const known = entry();
+    const audit = contribution({
+      entries: [known],
+      // The host claims an effect no session event accounts for. The host is
+      // non-authoritative, so this is a number a person is shown — never a row.
+      journal: [known.effectId, "tool:9:9:9"],
+    });
+    await audit.indexAuditEntries([known]);
+    const receipt = await audit.rebuildAuditIndex();
+    expect(receipt).toMatchObject({
+      status: "rebuilt",
+      entries: 1,
+      hostJournalDiscrepancies: 1,
+      unknownOutcomes: 0,
+    });
+    expect(audit.query({}).entries.map((row) => row.effectId)).toEqual([
+      known.effectId,
+    ]);
+  });
+
+  test("counts outcomes the durable log cannot explain", async () => {
+    const unknown = entry({ occurrenceId: "tool:1:1:2", outcome: "unknown" });
+    const audit = contribution({ entries: [entry(), unknown] });
+    const receipt = await audit.rebuildAuditIndex();
+    expect(receipt.entries).toBe(2);
+    expect(receipt.unknownOutcomes).toBe(1);
+  });
+
+  test("purges one Bot, and answers its own state", async () => {
+    const audit = contribution();
+    await audit.indexAuditEntries([entry(), entry({ botId: "scheduler" })]);
+    expect(audit.state()).toBe("ready");
+    expect(audit.purgeAuditForBot("foreman")).toEqual({ removed: 1 });
+    expect(audit.query({}).entries.map((row) => row.botId)).toEqual([
+      "scheduler",
+    ]);
+  });
+});

package/src/user.ts

@@ -0,0 +1,215 @@
+// The User backend Contribution: the one place a User's audit table lives.
+//
+// It is mounted into the User Durable Object's Cordis root beside Settings,
+// Credentials, Flock and the transcript index, and it owns exactly one thing —
+// an `AuditStoreV1` over that object's own SQL storage.
+//
+// Three seams it does not own, and takes as host functions instead:
+//
+//  * the Bot directory, because Flock is the authority for which Bots exist;
+//  * the entry source, because entries are projections of runs the *Bot*
+//    Durable Object holds, and a rebuild must read them from that authority;
+//  * the MCP host map, because Connections are User-scoped state this object
+//    holds elsewhere — and resolving `remote:<slug>` to `remote:<host>` here,
+//    on the one path both projection and rebuild take, is what stops the two
+//    disagreeing about what a row says.
+import type { Plugin } from "cordis";
+import {
+  AUDIT_MAX_ENTRY_PAGE_V1,
+  AuditDecodeError,
+  AUDIT_TARGET_REMOTE_PREFIX_V1,
+  decodeAuditEntryPageV1,
+  decodeAuditEntryV1,
+  type AuditEntryV1,
+  type AuditIndexStateV1,
+  type AuditRebuildReceiptV1,
+} from "./shared.js";
+import {
+  AuditStoreV1,
+  type AuditEntrySourceV1,
+  type AuditSqlV1,
+} from "./store.js";
+
+export interface AuditUserBackendHost {
+  /** The User Durable Object's own SQL storage. */
+  sql: AuditSqlV1;
+  /** Every Bot this User has. */
+  readDirectory(): Promise<{ botIds: readonly string[] }>;
+  /**
+   * One page of a Bot's projected entries, read from that Bot's Durable
+   * Object. The answer is decoded here: it is inbound from another runtime.
+   */
+  projectBotEntries(botId: string, cursor?: string): Promise<unknown>;
+  /**
+   * `<mcp server slug> → <host>`, from this User's Connection registry.
+   *
+   * Absent or incomplete is not a failure: an unresolved slug stays
+   * `remote:<slug>`, which is still a true statement about where the call
+   * went, rather than a row that claims a host nobody can vouch for.
+   */
+  readMcpHosts?(): Promise<ReadonlyMap<string, string>>;
+  /**
+   * The Computer host's own per-effect journal, when the deployment exposes
+   * one. It is non-authoritative (`AGENTS.md` § Computer and Workspace), so it
+   * is only ever *compared* against the table — never inserted into it.
+   */
+  readHostJournalEffectIds?(): Promise<readonly string[]>;
+  /** Overridable so a test can drive eviction. */
+  maxRows?: number;
+  /** Overridable so a test can drive age eviction. */
+  maxAgeMs?: number;
+  now?: () => number;
+}
+
+/**
+ * `remote:<slug>` resolved against the Connection registry.
+ *
+ * Every other target passes through untouched: `computer` and `machine:<id>`
+ * are complete as the classifier wrote them.
+ */
+export function resolveAuditTargetV1(
+  target: string,
+  hosts: ReadonlyMap<string, string>,
+): string {
+  if (!target.startsWith(AUDIT_TARGET_REMOTE_PREFIX_V1)) return target;
+  const slug = target.slice(AUDIT_TARGET_REMOTE_PREFIX_V1.length);
+  const host = hosts.get(slug);
+  return host ? `${AUDIT_TARGET_REMOTE_PREFIX_V1}${host}` : target;
+}
+
+export class AuditUserBackendContribution {
+  readonly packageId = "audit";
+  private readonly store: AuditStoreV1;
+
+  constructor(private readonly host: AuditUserBackendHost) {
+    this.store = new AuditStoreV1({
+      sql: host.sql,
+      ...(host.maxRows === undefined ? {} : { maxRows: host.maxRows }),
+      ...(host.maxAgeMs === undefined ? {} : { maxAgeMs: host.maxAgeMs }),
+      ...(host.now === undefined ? {} : { now: host.now }),
+    });
+  }
+
+  private async hosts(): Promise<ReadonlyMap<string, string>> {
+    if (!this.host.readMcpHosts) return new Map();
+    try {
+      return await this.host.readMcpHosts();
+    } catch {
+      // A registry this object could not read leaves slugs unresolved, which
+      // is a less specific row and not a wrong one.
+      return new Map();
+    }
+  }
+
+  private resolve(
+    entries: readonly AuditEntryV1[],
+    hosts: ReadonlyMap<string, string>,
+  ): AuditEntryV1[] {
+    return entries.map((entry) => ({
+      ...entry,
+      target: resolveAuditTargetV1(entry.target, hosts),
+    }));
+  }
+
+  /**
+   * Idempotent on `(botId, runId, occurrenceId)`; a redelivered outbox page
+   * inserts nothing the second time.
+   */
+  async indexAuditEntries(input: unknown): Promise<{ indexed: number }> {
+    if (!Array.isArray(input)) {
+      throw new AuditDecodeError("audit entries must be an array");
+    }
+    if (input.length > AUDIT_MAX_ENTRY_PAGE_V1) {
+      throw new AuditDecodeError("audit entries exceed their bound");
+    }
+    const entries = input.map(decodeAuditEntryV1);
+    return {
+      indexed: this.store.insert(this.resolve(entries, await this.hosts())),
+    };
+  }
+
+  /** Every entry of one Bot leaves the table. The archive saga calls this. */
+  purgeAuditForBot(botId: string): { removed: number } {
+    return { removed: this.store.purge(botId) };
+  }
+
+  state(): AuditIndexStateV1 {
+    return this.store.state();
+  }
+
+  query(request: {
+    botId?: string;
+    kind?: string;
+    target?: string;
+    before?: string;
+    limit?: number;
+  }): { entries: AuditEntryV1[]; nextCursor?: string; total: number } {
+    return this.store.query(request);
+  }
+
+  /**
+   * Reconstructs the whole table from the Bots' own stored runs.
+   *
+   * This is what makes the table disposable rather than authoritative. The
+   * receipt names how many entries it wrote and how many effects the Computer
+   * host's journal reported that no durable event accounts for — an `unknown`
+   * the User is told about rather than a row invented to cover it.
+   */
+  async rebuildAuditIndex(): Promise<AuditRebuildReceiptV1> {
+    const directory = await this.host.readDirectory();
+    const hosts = await this.hosts();
+    const sources: AuditEntrySourceV1[] = directory.botIds.map((botId) => ({
+      botId,
+      page: async (cursor) => {
+        const page = decodeAuditEntryPageV1(
+          await this.host.projectBotEntries(botId, cursor),
+        );
+        return {
+          entries: this.resolve(page.entries, hosts),
+          ...(page.nextCursor === undefined
+            ? {}
+            : { nextCursor: page.nextCursor }),
+        };
+      },
+    }));
+    const outcome = await this.store.rebuild(sources);
+    return {
+      schemaVersion: 1,
+      status: "rebuilt",
+      entries: outcome.entries,
+      bots: outcome.bots,
+      indexState: outcome.indexState,
+      unknownOutcomes: this.store
+        .all()
+        .filter((entry) => entry.outcome === "unknown").length,
+      hostJournalDiscrepancies: await this.countHostJournalDiscrepancies(),
+    };
+  }
+
+  /**
+   * Effects the host journal claims that the durable events do not.
+   *
+   * Counted, never written. The host is non-authoritative, so an effect it
+   * reports with no matching session event is a discrepancy for a person to
+   * look at — not evidence a Turn did something.
+   */
+  private async countHostJournalDiscrepancies(): Promise<number> {
+    if (!this.host.readHostJournalEffectIds) return 0;
+    let journal: readonly string[];
+    try {
+      journal = await this.host.readHostJournalEffectIds();
+    } catch {
+      return 0;
+    }
+    if (journal.length === 0) return 0;
+    const known = new Set(this.store.all().map((entry) => entry.effectId));
+    return journal.filter((effectId) => !known.has(effectId)).length;
+  }
+}
+
+export function createAuditUserBackendPlugin(
+  host: AuditUserBackendHost,
+  lifecycle: { mount(value: AuditUserBackendContribution): () => void },
+): Plugin {
+  return () => lifecycle.mount(new AuditUserBackendContribution(host));
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["bun", "vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-audit
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.