@frockbot/plugin-audit 0.0.0 → 0.1.1

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from "./shared.js";
+export { auditKindForToolV1, type AuditClassificationV1 } from "./classify.js";
+export { auditArgumentDigestV1, auditPreviewV1 } from "./redact.js";
+export {
+  AuditOutboxV1,
+  AUDIT_OUTBOX_KEY_V1,
+  auditEntriesFromStoredRunV1,
+  isSettledAuditRunV1,
+  type AuditOutboxStateV1,
+  type AuditOutboxStorageV1,
+  type AuditProjectableRunV1,
+  type AuditSinkV1,
+} from "./bot.js";
+export {
+  AuditStoreV1,
+  AUDIT_REBUILD_PAGE_V1,
+  decodeAuditOffsetV1,
+  type AuditEntrySourceV1,
+  type AuditRebuildOutcomeV1,
+  type AuditSqlCursorV1,
+  type AuditSqlV1,
+  type AuditSqlValueV1,
+} from "./store.js";
+export { default as manifest } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/redact.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { auditArgumentDigestV1, auditPreviewV1 } from "./redact.ts";
+import { AUDIT_MAX_PREVIEW_LENGTH_V1 } from "./shared.ts";
+
+describe("the audit preview", () => {
+  test("redacts a bearer token out of a shell command", () => {
+    const preview = auditPreviewV1("shell", "computer_exec", {
+      command:
+        "curl -H 'Authorization: Bearer abcdefghijklmnopqrstuvwxyz012345' https://api.example",
+    });
+    expect(preview).not.toContain("abcdefghijklmnopqrstuvwxyz012345");
+    expect(preview).toContain("[redacted:bearer-token]");
+    // The rest of the command survives, which is the only reason to keep a
+    // preview at all.
+    expect(preview).toContain("https://api.example");
+  });
+
+  test("redacts a JWT and an sk- key", () => {
+    const jwt =
+      "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U";
+    expect(
+      auditPreviewV1("shell", "computer_exec", { command: `echo ${jwt}` }),
+    ).toBe("echo [redacted:jwt]");
+    expect(
+      auditPreviewV1("shell", "computer_exec", {
+        command: "export OPENAI_API_KEY=sk-abcdefghijklmnopqrst",
+      }),
+    ).toContain("[redacted:");
+  });
+
+  test("never carries env or a credential reference, whatever the input", () => {
+    // Structural, not filtered: the preview is built from a per-kind
+    // allowlist, so `env` is absent because it was never reachable.
+    const preview = auditPreviewV1("shell", "computer_exec", {
+      command: "printenv",
+      env: { OPENAI_API_KEY: "sk-abcdefghijklmnopqrst" },
+      credentialRef: "sprites:user:alice",
+    });
+    expect(preview).toBe("printenv");
+    expect(preview).not.toContain("credentialRef");
+    expect(preview).not.toContain("sprites:user:alice");
+  });
+
+  test("shows a browser action and its url, and an MCP call's shape only", () => {
+    expect(
+      auditPreviewV1("browser", "computer_browser", {
+        action: "navigate",
+        url: "https://example.test/login",
+      }),
+    ).toBe("navigate https://example.test/login");
+    // A remote server's arguments are somebody else's schema; the preview
+    // names the keys and never their values.
+    expect(
+      auditPreviewV1("mcp", "mcp__example__echo", {
+        message: "Bearer abcdefghijklmnopqrstuvwx",
+        chatId: 42,
+      }),
+    ).toBe("mcp__example__echo (chatId, message)");
+  });
+
+  test("is bounded and deterministic", () => {
+    const input = { command: "x".repeat(5_000) };
+    const once = auditPreviewV1("shell", "computer_exec", input);
+    expect(once.length).toBe(AUDIT_MAX_PREVIEW_LENGTH_V1);
+    expect(auditPreviewV1("shell", "computer_exec", input)).toBe(once);
+    // Falls back to the tool name rather than an empty cell.
+    expect(auditPreviewV1("shell", "computer_exec", {})).toBe("computer_exec");
+    expect(auditPreviewV1("file", "memory_write", null)).toBe("memory_write");
+  });
+});
+
+describe("the argument digest", () => {
+  test("is a stable sha-256 of the exact argument JSON", async () => {
+    const digest = await auditArgumentDigestV1({ command: "ls -la" });
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+    expect(await auditArgumentDigestV1({ command: "ls -la" })).toBe(digest);
+    // The same bytes SHA-256 answers for `{"command":"ls -la"}`.
+    expect(digest).toBe(
+      "1df8bccaec747dc615b50678f35bf5b51756a45f9b2b77b247c7a617fde58b3e",
+    );
+  });
+
+  test("distinguishes two different calls, and is total", async () => {
+    const left = await auditArgumentDigestV1({ command: "ls" });
+    const right = await auditArgumentDigestV1({ command: "ls " });
+    expect(left).not.toBe(right);
+    expect(await auditArgumentDigestV1(undefined)).toBe(
+      await auditArgumentDigestV1(null),
+    );
+  });
+});

package/src/redact.ts

@@ -0,0 +1,110 @@
+// What an audit entry is allowed to carry out of a tool call.
+//
+// The constitution is explicit and this module is where it is enforced:
+// "No secret lives on the Workspace except the User's browser profile … Code
+// running on the Computer receives every other credential only as an opaque,
+// expiring lease" (`AGENTS.md` § Computer and Workspace), and "client bundles
+// and protocols contain no secrets" (§ Architecture checks). An audit table is
+// durable state a person reads, so it gets the digest and a redacted preview,
+// never the arguments.
+//
+// Three refusals, in order of how badly they would fail:
+//
+//  1. `env` is never projected. The Computer host's exec op carries an `env`
+//     map (`computer-host-protocol/src/protocol.ts`), which is exactly where a
+//     leased credential would be; the preview is built from a per-kind
+//     allowlist of fields, so `env` is absent because it was never reachable,
+//     not because a filter removed it.
+//  2. `credentialRef` is never projected, for the same reason and by the same
+//     mechanism.
+//  3. Whatever survives runs through the shared credential-shape table
+//     (`@frockbot/secret-shapes`), matched substrings replaced with
+//     `[redacted:<id>]`.
+//
+// HONEST BOUND, stated as `plugin-memory/src/secrets.ts` states it: step 3 is
+// a shape matcher, not a secret scanner, and a determined encoding gets
+// through it. Steps 1 and 2 are not — they are structural, and they are what
+// the rule actually rests on.
+import { redactSecretShapesV1 } from "@frockbot/secret-shapes";
+import { AUDIT_MAX_PREVIEW_LENGTH_V1, type AuditKindV1 } from "./shared.js";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The fields each kind may show, in the order they read best.
+ *
+ * An allowlist rather than a denylist: a Package that adds an argument gets no
+ * preview for it until somebody names it here, which is the failure direction
+ * worth having.
+ */
+const PREVIEW_FIELDS: Record<AuditKindV1, readonly string[]> = {
+  shell: ["command", "machineId"],
+  browser: ["action", "url", "role", "name", "label", "key"],
+  process: ["action", "command", "processId", "machineId"],
+  file: ["path", "root", "project", "packageId", "skill", "text"],
+  mcp: [],
+};
+
+function render(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return undefined;
+}
+
+/**
+ * The bounded, redacted, human-readable half of an audit entry.
+ *
+ * Deterministic: same call, same preview, for ever — which is what lets a
+ * rebuild reproduce a row written months earlier.
+ */
+export function auditPreviewV1(
+  kind: AuditKindV1,
+  toolName: string,
+  input: unknown,
+): string {
+  const parts: string[] = [];
+  if (kind === "mcp") {
+    // A remote server's arguments are somebody else's schema; there is no
+    // allowlist that could be right for all of them, so the preview names the
+    // tool and the *shape* of what it was given and stops there.
+    parts.push(toolName);
+    if (isObject(input)) {
+      const keys = Object.keys(input).slice(0, 12).sort();
+      if (keys.length > 0) parts.push(`(${keys.join(", ")})`);
+    }
+  } else {
+    for (const field of PREVIEW_FIELDS[kind]) {
+      if (!isObject(input)) break;
+      const rendered = render(input[field]);
+      if (rendered === undefined || rendered.length === 0) continue;
+      parts.push(rendered);
+    }
+    if (parts.length === 0) parts.push(toolName);
+  }
+  const joined = parts.join(" ").replace(/\s+/g, " ").trim();
+  return redactSecretShapesV1(joined).slice(0, AUDIT_MAX_PREVIEW_LENGTH_V1);
+}
+
+/**
+ * Lowercase hex sha-256 of the exact argument JSON.
+ *
+ * "Exact" means the value the durable `tool/call` event holds, serialized
+ * once: two Turns that issued the same call share a digest, and a person
+ * checking whether a command recurred can do so without the table ever having
+ * held the command. `undefined` arguments hash as `null` so the digest is
+ * total.
+ */
+export async function auditArgumentDigestV1(input: unknown): Promise<string> {
+  const canonical = JSON.stringify(input ?? null) ?? "null";
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(canonical),
+  );
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}