@desplega.ai/agent-swarm 1.112.0 → 1.114.0

package/src/tests/rbac-audit.test.ts

@@ -0,0 +1,345 @@
+/**
+ * RBAC permission-audit writer tests (DES-445, Phase 6).
+ *
+ * Covers the batched writer in src/be/rbac-audit.ts end-to-end against a real
+ * migrated DB: buffer + flush persistence (allow AND deny, all columns),
+ * the 200-row threshold, the interval flush, the RBAC_AUDIT_DISABLED
+ * kill-switch, flush resilience to a throwing DB, retention purge, the
+ * shutdown drain, and one migrated MCP gate (inject-learning) exercised
+ * through its real handler.
+ *
+ * Timer hygiene (plan Review Errata): bun test leaks module state
+ * process-wide, so EVERY interval started here is stopped in afterEach —
+ * dangling timers poison unrelated suites.
+ */
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, getDb, initDb } from "../be/db";
+import {
+  enqueueAuditRow,
+  flushAuditBuffer,
+  purgeExpiredAuditRows,
+  startAuditGc,
+  startAuditWriter,
+  stopAuditGc,
+  stopAuditWriter,
+} from "../be/rbac-audit";
+import { can, clearAuditSink, setAuditSink } from "../rbac";
+import { registerInjectLearningTool } from "../tools/inject-learning";
+
+const TEST_DB_PATH = "./test-rbac-audit.sqlite";
+
+const LEAD_ID = "aaaa6000-0000-4000-8000-000000000001";
+const WORKER_ID = "bbbb6000-0000-4000-8000-000000000002";
+
+type AuditRowSelect = {
+  principalType: string;
+  principalId: string | null;
+  originatorUserId: string | null;
+  verb: string;
+  resourceType: string | null;
+  resourceId: string | null;
+  decision: string;
+  reason: string | null;
+  source: string;
+};
+
+function selectAuditRows(): AuditRowSelect[] {
+  return getDb()
+    .prepare(
+      `SELECT principalType, principalId, originatorUserId, verb, resourceType, resourceId,
+              decision, reason, source
+       FROM permission_audit ORDER BY ts, id`,
+    )
+    .all() as AuditRowSelect[];
+}
+
+function countAuditRows(): number {
+  const row = getDb().prepare("SELECT count(*) AS n FROM permission_audit").get() as { n: number };
+  return row.n;
+}
+
+async function removeDbFiles() {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {
+      // File doesn't exist
+    }
+  }
+}
+
+let savedEnv: NodeJS.ProcessEnv;
+
+beforeAll(async () => {
+  savedEnv = { ...process.env };
+  delete process.env.RBAC_AUDIT_DISABLED;
+  delete process.env.RBAC_AUDIT_RETENTION_DAYS;
+
+  closeDb();
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+
+  createAgent({ id: LEAD_ID, name: "Audit Lead", isLead: true, status: "idle" });
+  createAgent({ id: WORKER_ID, name: "Audit Worker", isLead: false, status: "idle" });
+});
+
+afterAll(async () => {
+  stopAuditWriter();
+  stopAuditGc();
+  clearAuditSink();
+  closeDb();
+  await removeDbFiles();
+
+  for (const key of Object.keys(process.env)) {
+    if (!(key in savedEnv)) delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+beforeEach(() => {
+  // Drain any leftover buffered rows, then start each test from a clean table.
+  flushAuditBuffer();
+  getDb().run("DELETE FROM permission_audit");
+  delete process.env.RBAC_AUDIT_DISABLED;
+  delete process.env.RBAC_AUDIT_RETENTION_DAYS;
+});
+
+afterEach(() => {
+  // CRITICAL: never leak intervals across test files (bun test module-state
+  // leakage) — stop both timers and detach the sink after every test.
+  stopAuditWriter();
+  stopAuditGc();
+  clearAuditSink();
+});
+
+describe("buffer + flush persistence", () => {
+  test("persists allow AND deny rows from can() with correct columns", () => {
+    setAuditSink(enqueueAuditRow);
+
+    const allow = can({
+      principal: { kind: "agent", agentId: LEAD_ID, isLead: true },
+      verb: "memory.learning.inject",
+      resource: { kind: "agent", agentId: WORKER_ID },
+      source: "mcp",
+    });
+    const deny = can({
+      principal: { kind: "agent", agentId: WORKER_ID, isLead: false },
+      verb: "memory.learning.inject",
+      resource: { kind: "agent", agentId: LEAD_ID },
+      source: "http",
+    });
+    expect(allow.allow).toBe(true);
+    expect(deny.allow).toBe(false);
+
+    // Buffered, not yet written.
+    expect(countAuditRows()).toBe(0);
+
+    flushAuditBuffer();
+
+    const rows = selectAuditRows();
+    expect(rows.length).toBe(2);
+
+    const allowRow = rows.find((r) => r.decision === "allow");
+    expect(allowRow).toMatchObject({
+      principalType: "agent",
+      principalId: LEAD_ID,
+      originatorUserId: null,
+      verb: "memory.learning.inject",
+      resourceType: "agent",
+      resourceId: WORKER_ID,
+      decision: "allow",
+      reason: null,
+      source: "mcp",
+    });
+
+    const denyRow = rows.find((r) => r.decision === "deny");
+    expect(denyRow).toMatchObject({
+      principalType: "agent",
+      principalId: WORKER_ID,
+      verb: "memory.learning.inject",
+      resourceType: "agent",
+      resourceId: LEAD_ID,
+      decision: "deny",
+      source: "http",
+    });
+    expect(denyRow?.reason).toBeTruthy();
+  });
+
+  test("auto-flushes at the 200-row threshold without the interval writer", async () => {
+    for (let i = 0; i < 200; i++) {
+      enqueueAuditRow(
+        { principal: { kind: "operator" }, verb: "user.manage", source: "http" },
+        { allow: true },
+      );
+    }
+    // The threshold flush is deferred off the enqueue path (zero-delay
+    // timeout) so the 200th can() call never blocks on the transaction —
+    // nothing is persisted synchronously, everything lands a tick later.
+    expect(countAuditRows()).toBe(0);
+    await Bun.sleep(10);
+    expect(countAuditRows()).toBe(200);
+  });
+
+  test("interval flush drains the buffer", async () => {
+    startAuditWriter(25);
+    enqueueAuditRow(
+      { principal: { kind: "user", userId: "user-1" }, verb: "user.manage", source: "http" },
+      { allow: true },
+    );
+    expect(countAuditRows()).toBe(0);
+
+    await Bun.sleep(120);
+    expect(countAuditRows()).toBe(1);
+    const row = selectAuditRows()[0];
+    expect(row).toMatchObject({ principalType: "user", principalId: "user-1" });
+  });
+});
+
+describe("kill-switch", () => {
+  test("RBAC_AUDIT_DISABLED=true writes nothing", () => {
+    process.env.RBAC_AUDIT_DISABLED = "true";
+    setAuditSink(enqueueAuditRow);
+
+    can({
+      principal: { kind: "agent", agentId: WORKER_ID, isLead: false },
+      verb: "memory.learning.inject",
+      source: "mcp",
+    });
+    enqueueAuditRow(
+      { principal: { kind: "operator" }, verb: "user.manage", source: "http" },
+      { allow: true },
+    );
+    flushAuditBuffer();
+
+    expect(countAuditRows()).toBe(0);
+  });
+});
+
+describe("flush resilience", () => {
+  test("throwing DB during flush does not propagate (batch dropped)", () => {
+    enqueueAuditRow(
+      { principal: { kind: "operator" }, verb: "user.manage", source: "http" },
+      { allow: true },
+    );
+
+    getDb().run("ALTER TABLE permission_audit RENAME TO permission_audit_broken");
+    try {
+      expect(() => flushAuditBuffer()).not.toThrow();
+    } finally {
+      getDb().run("ALTER TABLE permission_audit_broken RENAME TO permission_audit");
+    }
+
+    // Batch was dropped, not retried.
+    expect(countAuditRows()).toBe(0);
+    flushAuditBuffer();
+    expect(countAuditRows()).toBe(0);
+  });
+});
+
+describe("retention purge", () => {
+  test("deletes only rows older than the cutoff (default 30 days)", () => {
+    const insert = getDb().prepare(
+      `INSERT INTO permission_audit (ts, principalType, verb, decision, source)
+       VALUES (datetime('now', ?), 'agent', 'user.manage', 'deny', 'mcp')`,
+    );
+    insert.run("-40 days");
+    insert.run("-29 days");
+    insert.run("-0 seconds");
+    expect(countAuditRows()).toBe(3);
+
+    const purged = purgeExpiredAuditRows();
+    expect(purged).toBe(1);
+    expect(countAuditRows()).toBe(2);
+  });
+
+  test("respects RBAC_AUDIT_RETENTION_DAYS override and runs via startAuditGc", () => {
+    process.env.RBAC_AUDIT_RETENTION_DAYS = "7";
+    const insert = getDb().prepare(
+      `INSERT INTO permission_audit (ts, principalType, verb, decision, source)
+       VALUES (datetime('now', ?), 'agent', 'user.manage', 'deny', 'mcp')`,
+    );
+    insert.run("-10 days");
+    insert.run("-1 days");
+
+    // startAuditGc purges immediately on start (pattern: startMemoryGc).
+    startAuditGc();
+    expect(countAuditRows()).toBe(1);
+    stopAuditGc();
+  });
+});
+
+describe("shutdown flush", () => {
+  test("final flushAuditBuffer() drains everything below the thresholds", () => {
+    enqueueAuditRow(
+      {
+        principal: { kind: "agent", agentId: WORKER_ID, isLead: false },
+        verb: "user.manage",
+        source: "mcp",
+      },
+      { allow: false, reason: "requires lead agent", missing: "user.manage" },
+    );
+    enqueueAuditRow(
+      { principal: { kind: "operator" }, verb: "user.manage", source: "http" },
+      { allow: true },
+    );
+    expect(countAuditRows()).toBe(0);
+
+    // Shutdown path: stop the timer first, then drain.
+    stopAuditWriter();
+    flushAuditBuffer();
+    expect(countAuditRows()).toBe(2);
+
+    // Buffer is empty afterwards — a second drain writes nothing.
+    flushAuditBuffer();
+    expect(countAuditRows()).toBe(2);
+  });
+});
+
+describe("migrated gate end-to-end (inject-learning)", () => {
+  type ToolResult = {
+    content: Array<{ type: string; text: string }>;
+    structuredContent: { success: boolean; message: string };
+  };
+
+  test("worker call → soft denial → flush → deny audit row with expected verb", async () => {
+    setAuditSink(enqueueAuditRow);
+
+    const server = new McpServer({ name: "test-rbac-audit", version: "1.0.0" });
+    registerInjectLearningTool(server);
+    const tools = (
+      server as unknown as {
+        // biome-ignore lint/complexity/noBannedTypes: internal MCP SDK type, test-only
+        _registeredTools: Record<string, { handler: Function }>;
+      }
+    )._registeredTools;
+    const handler = tools["inject-learning"]?.handler;
+    expect(handler).toBeDefined();
+
+    const result = (await handler?.(
+      { agentId: LEAD_ID, learning: "audit e2e learning", category: "best-practice" },
+      {
+        sessionId: "test-session",
+        requestInfo: { headers: { "x-agent-id": WORKER_ID } },
+      },
+    )) as ToolResult;
+    expect(result.structuredContent.success).toBe(false);
+
+    flushAuditBuffer();
+
+    const rows = selectAuditRows();
+    expect(rows.length).toBe(1);
+    expect(rows[0]).toMatchObject({
+      principalType: "agent",
+      principalId: WORKER_ID,
+      verb: "memory.learning.inject",
+      decision: "deny",
+      source: "mcp",
+    });
+    expect(rows[0]?.reason).toBeTruthy();
+  });
+});

package/src/tests/rbac-charact-http.test.ts

@@ -0,0 +1,272 @@
+// RBAC slice-1 characterization — HTTP-surface gates (Phase 2 of
+// thoughts/taras/plans/2026-07-07-des-445-rbac-slice1-can-audit.md).
+//
+// Pins TODAY's behavior of `canMutateTask` (src/http/fs.ts:432-444, appendix
+// row 36). Decision order matters and is part of the characterization:
+//
+//   1. request auth kind "operator" (swarm key)  → allow — BEFORE any agent check,
+//      so an operator bearer with a non-owner X-Agent-ID is still allowed.
+//   2. request auth kind "user" (aswt_ token)    → allow.
+//   3. otherwise (auth context unset): lead OR task-assignee OR task-creator
+//      → allow; anything else → 403 {"error":"Caller cannot mutate this task's files"}.
+//
+// Branch 3 is only reachable when `getRequestAuth(req)` is null. Through the
+// production pipeline `handleCore` 401s such requests first (every accepted
+// bearer is operator or user), so we characterize it by invoking `handleFs`
+// WITHOUT `handleCore` — the exact auth-null condition under which those
+// branches decide. Phase 5 must preserve this full decision table in can().
+// These tests must pass unchanged before AND after the Phase-5 migration.
+//
+// Other HTTP gates from the Phase-1 inventory:
+// - kv `authorizeWrite` (src/http/kv.ts:329, appendix row 35): characterized
+//   by the pre-existing kv-http.test.ts:269-311 — not duplicated here.
+// - http/agents.ts: NO hard gates (all isLead hits are NON-AUTHZ —
+//   registration schema / pass-through / telemetry), so no tests needed.
+// - http/scripts.ts global write/delete: intentionally NOT characterized here;
+//   the permissive behavior flips in Phase 5 (scripts-http.test.ts:319-345).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { rm, unlink } from "node:fs/promises";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  createUser,
+  getTaskAttachments,
+  initDb,
+} from "../be/db";
+import { type IdentityActor, mintToken } from "../be/users";
+import { resetFileStorageProviderForTests } from "../fs/registry";
+import { handleCore } from "../http/core";
+import { handleFs } from "../http/fs";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+
+const TEST_DB_PATH = "./test-rbac-charact-http.sqlite";
+const TEST_FS_DIR = "./test-rbac-charact-http-data";
+const API_KEY = "test-rbac-http-key";
+const ACTOR: IdentityActor = { kind: "operator", id: "test" };
+
+async function removeDbFiles(path: string): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(path + suffix);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+async function listen(server: Server): Promise<number> {
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const addr = server.address();
+  if (!addr || typeof addr === "string") throw new Error("no port");
+  return addr.port;
+}
+
+// Full production pipeline: auth via handleCore, then handleFs
+// (pattern: kv-http.test.ts:39-52).
+function createPipelineServer(apiKey: string): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const handled = await handleCore(req, res, myAgentId, apiKey);
+    if (handled) return;
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    const ok = await handleFs(req, res, pathSegments, queryParams, myAgentId);
+    if (!ok) {
+      res.writeHead(404);
+      res.end("Not Found");
+    }
+  });
+}
+
+// handleFs WITHOUT handleCore: `getRequestAuth(req)` stays null, which is the
+// only condition under which canMutateTask's agent-identity branches
+// (lead / assignee / creator / deny) decide. See header comment.
+function createNoAuthContextServer(): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    const ok = await handleFs(req, res, pathSegments, queryParams, myAgentId);
+    if (!ok) {
+      res.writeHead(404);
+      res.end("Not Found");
+    }
+  });
+}
+
+let pipelineServer: Server;
+let pipelinePort: number;
+let bareServer: Server;
+let barePort: number;
+let assigneeId: string;
+let creatorId: string;
+let outsiderId: string;
+let leadId: string;
+let userToken: string;
+let taskId: string;
+
+beforeAll(async () => {
+  await removeDbFiles(TEST_DB_PATH);
+  await rm(TEST_FS_DIR, { recursive: true, force: true });
+  process.env.AGENT_FS_LOCAL_DIR = TEST_FS_DIR;
+  delete process.env.AGENT_FS_API_URL;
+  delete process.env.API_AGENT_FS_API_KEY;
+  delete process.env.AGENT_FS_API_KEY;
+  resetFileStorageProviderForTests();
+
+  initDb(TEST_DB_PATH);
+  pipelineServer = createPipelineServer(API_KEY);
+  pipelinePort = await listen(pipelineServer);
+  bareServer = createNoAuthContextServer();
+  barePort = await listen(bareServer);
+
+  assigneeId = createAgent({ name: "rbac-fs-assignee", isLead: false, status: "idle" }).id;
+  creatorId = createAgent({ name: "rbac-fs-creator", isLead: false, status: "idle" }).id;
+  outsiderId = createAgent({ name: "rbac-fs-outsider", isLead: false, status: "idle" }).id;
+  leadId = createAgent({ name: "rbac-fs-lead", isLead: true, status: "idle" }).id;
+
+  const user = createUser({ name: "RBAC FS User" });
+  userToken = mintToken(user.id, "rbac-charact", ACTOR).plaintext;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => pipelineServer.close(() => resolve()));
+  await new Promise<void>((resolve) => bareServer.close(() => resolve()));
+  closeDb();
+  await removeDbFiles(TEST_DB_PATH);
+  await rm(TEST_FS_DIR, { recursive: true, force: true });
+  delete process.env.AGENT_FS_LOCAL_DIR;
+  resetFileStorageProviderForTests();
+});
+
+beforeEach(async () => {
+  await rm(TEST_FS_DIR, { recursive: true, force: true });
+  resetFileStorageProviderForTests();
+  taskId = createTaskExtended("rbac fs charact task", {
+    agentId: assigneeId,
+    creatorAgentId: creatorId,
+    source: "mcp",
+  }).id;
+});
+
+const DENY_BODY = { error: "Caller cannot mutate this task's files" };
+
+function uploadPath(): string {
+  return `/api/fs/tasks/${taskId}/files?name=charact.txt`;
+}
+
+function pipelineUpload(opts: { bearer?: string; agentId?: string }): Promise<Response> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.bearer ?? API_KEY}`,
+    "Content-Type": "text/plain",
+  };
+  if (opts.agentId !== undefined) headers["X-Agent-ID"] = opts.agentId;
+  return fetch(`http://localhost:${pipelinePort}${uploadPath()}`, {
+    method: "POST",
+    body: Buffer.from("rbac characterization"),
+    headers,
+  });
+}
+
+function bareFetch(path: string, init: RequestInit & { agentId?: string } = {}): Promise<Response> {
+  const headers: Record<string, string> = {
+    ...((init.headers as Record<string, string>) ?? {}),
+  };
+  if (init.agentId !== undefined) headers["X-Agent-ID"] = init.agentId;
+  return fetch(`http://localhost:${barePort}${path}`, { ...init, headers });
+}
+
+function bareUpload(opts: { agentId?: string }): Promise<Response> {
+  return bareFetch(uploadPath(), {
+    method: "POST",
+    body: Buffer.from("rbac characterization"),
+    headers: { "Content-Type": "text/plain" },
+    ...opts,
+  });
+}
+
+describe("canMutateTask — real pipeline (handleCore auth → handleFs)", () => {
+  test("operator (swarm key, no X-Agent-ID) is allowed", async () => {
+    const res = await pipelineUpload({});
+    expect(res.status).toBe(201);
+  });
+
+  test("operator bearer short-circuits BEFORE agent identity: non-owner X-Agent-ID is still allowed", async () => {
+    const res = await pipelineUpload({ agentId: outsiderId });
+    expect(res.status).toBe(201);
+  });
+
+  test("authenticated user (aswt_ token, no X-Agent-ID) is allowed", async () => {
+    const res = await pipelineUpload({ bearer: userToken });
+    expect(res.status).toBe(201);
+  });
+
+  test("authenticated user with a non-owner X-Agent-ID is still allowed", async () => {
+    const res = await pipelineUpload({ bearer: userToken, agentId: outsiderId });
+    expect(res.status).toBe(201);
+  });
+});
+
+describe("canMutateTask — agent-identity branches (auth context unset)", () => {
+  test("lead agent is allowed", async () => {
+    const res = await bareUpload({ agentId: leadId });
+    expect(res.status).toBe(201);
+  });
+
+  test("assignee agent (task.agentId) is allowed", async () => {
+    const res = await bareUpload({ agentId: assigneeId });
+    expect(res.status).toBe(201);
+  });
+
+  test("creator agent (task.creatorAgentId, not assignee) is allowed", async () => {
+    const res = await bareUpload({ agentId: creatorId });
+    expect(res.status).toBe(201);
+  });
+
+  test("non-owner worker is denied with 403 and the exact body; DB untouched", async () => {
+    const res = await bareUpload({ agentId: outsiderId });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual(DENY_BODY);
+    expect(getTaskAttachments(taskId)).toEqual([]);
+  });
+
+  test("missing X-Agent-ID (no auth, no agent) is denied with 403", async () => {
+    const res = await bareUpload({});
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual(DENY_BODY);
+  });
+
+  test("DELETE: non-owner worker is denied before attachment lookup; row survives", async () => {
+    const seeded = await bareUpload({ agentId: assigneeId });
+    expect(seeded.status).toBe(201);
+    const attachment = (await seeded.json()) as { id: string };
+
+    const res = await bareFetch(`/api/fs/tasks/${taskId}/files/${attachment.id}`, {
+      method: "DELETE",
+      agentId: outsiderId,
+    });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual(DENY_BODY);
+    expect(getTaskAttachments(taskId)).toHaveLength(1);
+  });
+
+  test("DELETE: assignee agent can delete", async () => {
+    const seeded = await bareUpload({ agentId: assigneeId });
+    const attachment = (await seeded.json()) as { id: string };
+
+    const res = await bareFetch(`/api/fs/tasks/${taskId}/files/${attachment.id}`, {
+      method: "DELETE",
+      agentId: assigneeId,
+    });
+    expect(res.status).toBe(204);
+    expect(getTaskAttachments(taskId)).toEqual([]);
+  });
+});