@frockbot/plugin-audit 0.0.0 → 0.1.0

package/frockbot.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 4,
+  "id": "audit",
+  "displayName": "Audit",
+  "version": "0.0.1",
+  "compatibility": {
+    "frockbot": ">=0.0.1"
+  },
+  "dependencies": {
+    "flock": ">=0.0.1",
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      {
+        "entry": "./user",
+        "host": "user"
+      },
+      {
+        "entry": "./backend",
+        "host": "gateway"
+      }
+    ],
+    "client": {
+      "entry": "./client",
+      "mounts": [
+        {
+          "slot": "frockbot.bot-settings-sections",
+          "order": 20
+        }
+      ],
+      "outlets": []
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,51 @@
 {
   "name": "@frockbot/plugin-audit",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backend": "./src/backend.ts",
+    "./bot": "./src/bot.ts",
+    "./classify": "./src/classify.ts",
+    "./client": "./src/client/index.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./shared": "./src/shared.ts",
+    "./store": "./src/store.ts",
+    "./testing": "./src/testing.ts",
+    "./user": "./src/user.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.1.0",
+    "@frockbot/client-ui": "0.1.0",
+    "@frockbot/kernel-contracts": "0.1.0",
+    "@frockbot/plugin-shell": "0.1.0",
+    "@frockbot/secret-shapes": "0.1.0",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "typescript": "5.9.3",
+    "vite": "8.2.2",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-audit"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/backend.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createAuditBackendContribution,
+  decodeAuditRequestQueryV1,
+  type AuditGatewayHost,
+} from "./backend.ts";
+import type {
+  AuditEntryV1,
+  AuditQueryV1,
+  AuditRebuildReceiptV1,
+  ClientAuditPageV1,
+} from "./shared.ts";
+
+function url(query: string): URL {
+  return new URL(`https://bot.frockbot.com/api/audit?${query}`);
+}
+
+describe("the audit query decoder", () => {
+  test("decodes exactly the parameters the route implements", () => {
+    expect(
+      decodeAuditRequestQueryV1(
+        url("botId=foreman&kind=shell&target=computer&before=p50&limit=20"),
+      ),
+    ).toEqual({
+      schemaVersion: 1,
+      botId: "foreman",
+      kind: "shell",
+      target: "computer",
+      before: "p50",
+      limit: 20,
+    });
+    expect(decodeAuditRequestQueryV1(url(""))).toEqual({ schemaVersion: 1 });
+  });
+
+  test("refuses an unexpected parameter rather than ignoring it", () => {
+    // A client that means something the route does not implement finds out,
+    // instead of being handed a page it will misread as filtered.
+    expect(() => decodeAuditRequestQueryV1(url("userId=someone"))).toThrow(
+      "not allowed",
+    );
+    expect(() => decodeAuditRequestQueryV1(url("q=ls"))).toThrow("not allowed");
+  });
+
+  test("refuses a repeated parameter", () => {
+    expect(() => decodeAuditRequestQueryV1(url("kind=shell&kind=mcp"))).toThrow(
+      "is repeated",
+    );
+  });
+
+  test("refuses a value the schema does not carry", () => {
+    expect(() => decodeAuditRequestQueryV1(url("kind=network"))).toThrow();
+    expect(() => decodeAuditRequestQueryV1(url("target=box"))).toThrow();
+    expect(() => decodeAuditRequestQueryV1(url("limit=0"))).toThrow();
+    expect(() => decodeAuditRequestQueryV1(url("limit=abc"))).toThrow();
+    expect(() =>
+      decodeAuditRequestQueryV1(url(`before=${"p".repeat(200)}`)),
+    ).toThrow();
+  });
+});
+
+const ENTRY: AuditEntryV1 = {
+  schemaVersion: 1,
+  botId: "foreman",
+  runId: "run-1",
+  occurrenceId: "tool:1:1:0",
+  turn: 1,
+  step: 1,
+  ordinal: 0,
+  effectId: "tool:1:1:0",
+  at: "2026-08-31T00:00:00.000Z",
+  kind: "shell",
+  target: "computer",
+  toolName: "computer_exec",
+  argumentDigest: "a".repeat(64),
+  preview: "ls -la",
+  outcome: "ok",
+};
+
+const RECEIPT: AuditRebuildReceiptV1 = {
+  schemaVersion: 1,
+  status: "rebuilt",
+  entries: 1,
+  bots: 1,
+  indexState: "ready",
+  unknownOutcomes: 0,
+  hostJournalDiscrepancies: 0,
+};
+
+function host(
+  overrides: Partial<AuditGatewayHost> = {},
+): AuditGatewayHost & { queries: AuditQueryV1[] } {
+  const queries: AuditQueryV1[] = [];
+  return {
+    queries,
+    readAudit: async (_userId, query) => {
+      queries.push(query);
+      const page: ClientAuditPageV1 = {
+        schemaVersion: 1,
+        entries: [ENTRY],
+        page: { truncated: false },
+        total: 1,
+        indexState: "ready",
+      };
+      return page;
+    },
+    rebuildAuditIndex: async () => RECEIPT,
+    ...overrides,
+  };
+}
+
+function get(path: string): { request: Request; url: URL } {
+  const target = new URL(`https://bot.frockbot.com${path}`);
+  return { request: new Request(target), url: target };
+}
+
+describe("the audit gateway route", () => {
+  const context = { userId: "alice", client: "browser" as const };
+
+  test("answers only its own paths, and only for an authenticated User", async () => {
+    const route = createAuditBackendContribution(host());
+    const other = get("/api/search?q=x");
+    expect(
+      await route.route(other.request, other.url, context),
+    ).toBeUndefined();
+    const mine = get("/api/audit");
+    expect(
+      await route.route(mine.request, mine.url, {
+        client: "browser",
+      }),
+    ).toBeUndefined();
+  });
+
+  test("carries the decoded filters to the User Durable Object", async () => {
+    const gateway = host();
+    const route = createAuditBackendContribution(gateway);
+    const { request, url: target } = get("/api/audit?kind=mcp&botId=foreman");
+    const response = await route.route(request, target, context);
+    expect(response?.status).toBe(200);
+    expect(gateway.queries).toEqual([
+      { schemaVersion: 1, botId: "foreman", kind: "mcp" },
+    ]);
+    expect(await response!.json()).toMatchObject({ total: 1 });
+  });
+
+  test("refuses an invalid query definitively, and a wrong method", async () => {
+    const route = createAuditBackendContribution(host());
+    const bad = get("/api/audit?userId=someone");
+    const refused = await route.route(bad.request, bad.url, context);
+    expect(refused?.status).toBe(400);
+    expect(await refused!.json()).toMatchObject({
+      code: "invalid-request",
+      definitive: true,
+    });
+
+    const posted = new URL("https://bot.frockbot.com/api/audit");
+    const wrong = await route.route(
+      new Request(posted, { method: "POST" }),
+      posted,
+      context,
+    );
+    expect(wrong?.status).toBe(405);
+  });
+
+  test("rebuilds on POST and answers the receipt, discrepancies and all", async () => {
+    const route = createAuditBackendContribution(host());
+    const target = new URL("https://bot.frockbot.com/api/audit/rebuild");
+    const response = await route.route(
+      new Request(target, { method: "POST" }),
+      target,
+      context,
+    );
+    expect(response?.status).toBe(200);
+    expect(await response!.json()).toEqual(RECEIPT);
+
+    // A rebuild is a write; a GET must not perform one.
+    const read = await route.route(new Request(target), target, context);
+    expect(read?.status).toBe(405);
+  });
+
+  test("turns an unexpected failure into a 500, not a leaked stack", async () => {
+    const route = createAuditBackendContribution(
+      host({
+        readAudit: () => Promise.reject(new Error("the User object is away")),
+      }),
+    );
+    const { request, url: target } = get("/api/audit");
+    const response = await route.route(request, target, context);
+    expect(response?.status).toBe(500);
+    expect(await response!.json()).toEqual({
+      error: "the User object is away",
+    });
+  });
+});

package/src/backend.ts

@@ -0,0 +1,148 @@
+// The Audit Package's gateway Contribution.
+//
+// It sits on the same host as Flock's `/api/bots` and the Search Package's
+// `/api/search`, for the same reason: the gateway is where an authenticated
+// `userId` exists, and audit is User-scoped by construction — there is no
+// cross-User table to leak from, and the User Durable Object refuses any RPC
+// naming a User it is not.
+//
+// The route owns no state. It decodes the query string into the exact
+// `AuditQueryV1` every other caller uses, asks the User Durable Object, and
+// answers. An unexpected or repeated parameter is a refusal rather than
+// something quietly ignored: a client that means something the route does not
+// implement finds out, instead of being handed a page it will misread as
+// filtered.
+import type { Plugin } from "cordis";
+import {
+  AUDIT_KINDS_V1,
+  AUDIT_MAX_CURSOR_LENGTH_V1,
+  AUDIT_MAX_RESULTS_V1,
+  AuditDecodeError,
+  decodeAuditQueryV1,
+  type AuditKindV1,
+  type AuditQueryV1,
+  type AuditRebuildReceiptV1,
+  type ClientAuditPageV1,
+} from "./shared.js";
+
+export interface AuditGatewayHost {
+  readAudit(userId: string, query: AuditQueryV1): Promise<ClientAuditPageV1>;
+  rebuildAuditIndex(userId: string): Promise<AuditRebuildReceiptV1>;
+}
+
+export interface AuditBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+const ALLOWED_PARAMS = new Set(["botId", "kind", "target", "before", "limit"]);
+
+/** The query string, decoded into the exact DTO. */
+export function decodeAuditRequestQueryV1(url: URL): AuditQueryV1 {
+  for (const key of url.searchParams.keys()) {
+    if (!ALLOWED_PARAMS.has(key)) {
+      throw new AuditDecodeError(`audit query.${key} is not allowed`);
+    }
+    if (url.searchParams.getAll(key).length > 1) {
+      throw new AuditDecodeError(`audit query.${key} is repeated`);
+    }
+  }
+  const botId = url.searchParams.get("botId");
+  const kind = url.searchParams.get("kind");
+  const target = url.searchParams.get("target");
+  const before = url.searchParams.get("before");
+  const limit = url.searchParams.get("limit");
+  if (kind !== null && !AUDIT_KINDS_V1.includes(kind as AuditKindV1)) {
+    throw new AuditDecodeError("audit query.kind is invalid");
+  }
+  if (before !== null && before.length > AUDIT_MAX_CURSOR_LENGTH_V1) {
+    throw new AuditDecodeError("audit query.before must be a bounded string");
+  }
+  if (limit !== null && !/^[0-9]{1,3}$/.test(limit)) {
+    throw new AuditDecodeError("audit query.limit must be a bounded integer");
+  }
+  return decodeAuditQueryV1({
+    schemaVersion: 1,
+    ...(botId === null ? {} : { botId }),
+    ...(kind === null ? {} : { kind }),
+    ...(target === null ? {} : { target }),
+    ...(before === null ? {} : { before }),
+    ...(limit === null
+      ? {}
+      : { limit: Math.min(Number(limit), AUDIT_MAX_RESULTS_V1) }),
+  });
+}
+
+function errorResponse(error: unknown): Response {
+  if (
+    error instanceof AuditDecodeError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "AuditDecodeError")
+  ) {
+    return Response.json(
+      {
+        error:
+          error instanceof Error ? error.message : "audit request is invalid",
+        code: "invalid-request",
+        definitive: true,
+      },
+      { status: 400 },
+    );
+  }
+  return Response.json(
+    { error: error instanceof Error ? error.message : "audit read failed" },
+    { status: 500 },
+  );
+}
+
+export function createAuditBackendContribution(
+  host: AuditGatewayHost,
+): AuditBackendRouteContribution {
+  return {
+    packageId: "audit",
+    async route(request, url, context) {
+      if (!context.userId) return undefined;
+      const isRead = url.pathname === "/api/audit";
+      const isRebuild = url.pathname === "/api/audit/rebuild";
+      if (!isRead && !isRebuild) return undefined;
+      const userId = context.userId;
+      try {
+        if (isRebuild) {
+          if (request.method !== "POST") {
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          }
+          return Response.json(await host.rebuildAuditIndex(userId));
+        }
+        if (request.method !== "GET") {
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        }
+        return Response.json(
+          await host.readAudit(userId, decodeAuditRequestQueryV1(url)),
+        );
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export namespace createAuditBackendContribution {
+  export function plugin(
+    host: AuditGatewayHost,
+    lifecycle: { mount(value: AuditBackendRouteContribution): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createAuditBackendContribution(host));
+  }
+}

package/src/bot.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AuditOutboxV1,
+  auditEntriesFromStoredRunV1,
+  type AuditProjectableRunV1,
+} from "./bot.ts";
+import { FakeAuditOutboxStorage } from "./testing.ts";
+import { decodeAuditEntryV1, type AuditEntryV1 } from "./shared.ts";
+
+const AT = "2026-08-31T02:00:00.000Z";
+
+function call(
+  occurrenceId: string,
+  name: string,
+  input: unknown,
+): AuditProjectableRunV1["events"][number] {
+  return { type: "tool/call", timestamp: AT, occurrenceId, name, input };
+}
+
+function result(
+  occurrenceId: string,
+  overrides: { content?: string; isError?: boolean; status?: string } = {},
+): AuditProjectableRunV1["events"][number] {
+  return {
+    type: "tool/result",
+    timestamp: AT,
+    occurrenceId,
+    name: "computer_exec",
+    content: "",
+    isError: false,
+    status: "completed",
+    ...overrides,
+  };
+}
+
+function run(
+  events: AuditProjectableRunV1["events"],
+  status = "completed",
+): AuditProjectableRunV1 {
+  return { runId: "run-1", status, events, acceptedAt: AT };
+}
+
+describe("projecting a settled run", () => {
+  test("audits the effects and ignores the rest", async () => {
+    const entries = await auditEntriesFromStoredRunV1(
+      "foreman",
+      run([
+        { type: "run/admitted", timestamp: AT },
+        call("tool:1:1:0", "current_time", {}),
+        result("tool:1:1:0", { content: "02:00" }),
+        call("tool:1:2:0", "computer_exec", { command: "ls -la" }),
+        result("tool:1:2:0", { content: "a\nb" }),
+        call("tool:1:2:1", "mcp__example__echo", { message: "hi" }),
+        result("tool:1:2:1", { content: "hi" }),
+      ]),
+    );
+    expect(entries.map((entry) => entry.toolName)).toEqual([
+      "computer_exec",
+      "mcp__example__echo",
+    ]);
+    expect(entries[0]).toMatchObject({
+      botId: "foreman",
+      runId: "run-1",
+      occurrenceId: "tool:1:2:0",
+      // The occurrence id *is* the effect id: `plugin-shell` writes
+      // `occurrenceId: context.effectId`, so the Computer envelope joins here.
+      effectId: "tool:1:2:0",
+      turn: 1,
+      step: 2,
+      ordinal: 0,
+      kind: "shell",
+      target: "computer",
+      outcome: "ok",
+      preview: "ls -la",
+      bytesOut: 3,
+    });
+    expect(entries[1]).toMatchObject({
+      kind: "mcp",
+      target: "remote:example",
+    });
+    // Everything the table accepts, the decoder accepts.
+    for (const entry of entries) {
+      expect(decodeAuditEntryV1(JSON.parse(JSON.stringify(entry)))).toEqual(
+        entry,
+      );
+    }
+  });
+
+  test("never carries the arguments, only their digest", async () => {
+    const secret = "Bearer abcdefghijklmnopqrstuvwxyz0123";
+    const [entry] = await auditEntriesFromStoredRunV1(
+      "foreman",
+      run([
+        call("tool:1:1:0", "computer_exec", {
+          command: `curl -H '${secret}' https://api.example`,
+          env: { OPENAI_API_KEY: "sk-abcdefghijklmnopqrst" },
+        }),
+        result("tool:1:1:0"),
+      ]),
+    );
+    const wire = JSON.stringify(entry);
+    expect(wire).not.toContain("abcdefghijklmnopqrstuvwxyz0123");
+    expect(wire).not.toContain("OPENAI_API_KEY");
+    expect(wire).not.toContain("env");
+    expect(entry!.preview).toContain("[redacted:bearer-token]");
+    expect(entry!.argumentDigest).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("names each outcome the durable events actually support", async () => {
+    const outcomes = async (
+      overrides: Parameters<typeof result>[1] | undefined,
+    ) => {
+      const events = [call("tool:1:1:0", "computer_exec", { command: "ls" })];
+      if (overrides) events.push(result("tool:1:1:0", overrides));
+      const [entry] = await auditEntriesFromStoredRunV1("foreman", run(events));
+      return entry?.outcome;
+    };
+    expect(await outcomes({ content: "ok" })).toBe("ok");
+    expect(await outcomes({ isError: true, content: "exit 1" })).toBe("error");
+    expect(
+      await outcomes({
+        isError: true,
+        content: "New calls are blocked while the user has taken control.",
+      }),
+    ).toBe("refused");
+    expect(await outcomes({ status: "interrupted", content: "" })).toBe(
+      "interrupted",
+    );
+    // No result at all is `unknown`, never `error`: the durable log does not
+    // know how the effect ended, and inventing an answer is what the
+    // reconciliation rule forbids.
+    expect(await outcomes(undefined)).toBe("unknown");
+  });
+
+  test("projects nothing until the run has settled, and is deterministic", async () => {
+    const events = [
+      call("tool:1:1:0", "computer_exec", { command: "ls" }),
+      result("tool:1:1:0"),
+    ];
+    expect(
+      await auditEntriesFromStoredRunV1("foreman", run(events, "running")),
+    ).toEqual([]);
+    const first = await auditEntriesFromStoredRunV1("foreman", run(events));
+    const second = await auditEntriesFromStoredRunV1("foreman", run(events));
+    expect(JSON.stringify(first)).toBe(JSON.stringify(second));
+  });
+
+  test("skips a call whose occurrence id it cannot place", async () => {
+    expect(
+      await auditEntriesFromStoredRunV1(
+        "foreman",
+        run([
+          {
+            type: "tool/call",
+            timestamp: AT,
+            occurrenceId: "legacy-1",
+            name: "computer_exec",
+            input: { command: "ls" },
+          },
+        ]),
+      ),
+    ).toEqual([]);
+  });
+});
+
+function entries(count: number): AuditEntryV1[] {
+  return Array.from({ length: count }, (_, index) => ({
+    schemaVersion: 1,
+    botId: "foreman",
+    runId: "run-1",
+    occurrenceId: `tool:1:1:${index}`,
+    turn: 1,
+    step: 1,
+    ordinal: index,
+    effectId: `tool:1:1:${index}`,
+    at: AT,
+    kind: "shell",
+    target: "computer",
+    toolName: "computer_exec",
+    argumentDigest: "b".repeat(64),
+    preview: `ls ${index}`,
+    outcome: "ok",
+  }));
+}
+
+describe("the Bot Durable Object's outbox", () => {
+  test("holds entries durably until a sink accepts them", async () => {
+    const outbox = new AuditOutboxV1(new FakeAuditOutboxStorage());
+    await outbox.append(entries(3));
+    expect(await outbox.state()).toEqual({ pending: 3, truncated: false });
+
+    // A sink that throws clears nothing. That is the entire point of a queue.
+    await expect(
+      outbox.drain({
+        indexEntries: () => Promise.reject(new Error("User object is away")),
+      }),
+    ).rejects.toThrow("User object is away");
+    expect(await outbox.state()).toEqual({ pending: 3, truncated: false });
+
+    const delivered: AuditEntryV1[] = [];
+    const drain = await outbox.drain({
+      indexEntries: async (batch) => {
+        delivered.push(...batch);
+      },
+    });
+    expect(drain.delivered).toBe(3);
+    expect(delivered).toHaveLength(3);
+    expect(await outbox.state()).toEqual({ pending: 0, truncated: false });
+    // An empty outbox drains to a no-op rather than an empty delivery.
+    expect(
+      (await outbox.drain({ indexEntries: async () => {} })).delivered,
+    ).toBe(0);
+  });
+
+  test("appends idempotently, so a re-projected run queues nothing twice", async () => {
+    const outbox = new AuditOutboxV1(new FakeAuditOutboxStorage());
+    await outbox.append(entries(2));
+    await outbox.append(entries(2));
+    expect(await outbox.state()).toEqual({ pending: 2, truncated: false });
+  });
+
+  test("drops the oldest past its bound and records that it did", async () => {
+    const outbox = new AuditOutboxV1(new FakeAuditOutboxStorage(), {
+      maximum: 4,
+    });
+    await outbox.append(entries(6));
+    const state = await outbox.state();
+    expect(state).toEqual({ pending: 4, truncated: true });
+
+    const seen: string[] = [];
+    await outbox.drain({
+      indexEntries: async (batch) => {
+        seen.push(...batch.map((entry) => entry.occurrenceId));
+      },
+    });
+    // The newest four survived, and the loss outlives the drain: it describes
+    // what was lost, not what is pending.
+    expect(seen).toEqual([
+      "tool:1:1:2",
+      "tool:1:1:3",
+      "tool:1:1:4",
+      "tool:1:1:5",
+    ]);
+    expect(await outbox.state()).toEqual({ pending: 0, truncated: true });
+
+    // Only a rebuild — which re-reads every run — may say the gap is closed.
+    await outbox.clearTruncation();
+    expect(await outbox.state()).toEqual({ pending: 0, truncated: false });
+  });
+});