@desplega.ai/agent-swarm 1.112.0 → 1.113.0

package/src/be/rbac-audit.ts

@@ -0,0 +1,218 @@
+/**
+ * RBAC permission-audit batched writer + retention GC (DES-445, Phase 6).
+ *
+ * `enqueueAuditRow` is the concrete `AuditSink` wired into `can()` at server
+ * boot (src/http/index.ts, src/stdio.ts). Rows buffer in memory and flush in
+ * a single prepared-statement transaction every FLUSH_INTERVAL_MS (2s) or at
+ * FLUSH_MAX_ROWS (200), whichever comes first. Every path is try/caught — a
+ * failed flush logs a warning and DROPS the batch; auditing must never throw
+ * into the request path. Rows are structured ids/verbs only (no payloads, no
+ * secret-bearing content).
+ *
+ * Kill-switch: `RBAC_AUDIT_DISABLED=true` makes the sink a no-op (checked per
+ * call so tests and live config reloads can toggle it).
+ *
+ * Retention: `startAuditGc` (pattern: startMemoryGc in src/http/memory.ts)
+ * ticks daily and deletes rows older than RBAC_AUDIT_RETENTION_DAYS
+ * (default 30).
+ */
+import type { RbacCheck, RbacDecision } from "../rbac";
+import { getDb } from "./db";
+
+type AuditRow = {
+  principalType: "agent" | "user" | "operator";
+  principalId: string | null;
+  originatorUserId: string | null;
+  verb: string;
+  resourceType: string | null;
+  resourceId: string | null;
+  decision: "allow" | "deny";
+  reason: string | null;
+  source: "mcp" | "http";
+};
+
+const FLUSH_INTERVAL_MS = 2_000;
+const FLUSH_MAX_ROWS = 200;
+const AUDIT_GC_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+const DEFAULT_RETENTION_DAYS = 30;
+
+let buffer: AuditRow[] = [];
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+let auditGcTimer: ReturnType<typeof setInterval> | null = null;
+let thresholdFlushScheduled = false;
+
+function isAuditDisabled(): boolean {
+  return process.env.RBAC_AUDIT_DISABLED === "true";
+}
+
+function principalIdOf(principal: RbacCheck["principal"]): string | null {
+  switch (principal.kind) {
+    case "agent":
+      return principal.agentId;
+    case "user":
+      return principal.userId;
+    case "operator":
+      return null;
+  }
+}
+
+function resourceIdOf(resource: RbacCheck["resource"]): string | null {
+  if (!resource) return null;
+  switch (resource.kind) {
+    case "task":
+      return resource.taskId;
+    case "agent":
+      return resource.agentId;
+    case "kv-namespace":
+      return resource.namespace;
+    case "owned":
+      return resource.ownerAgentId ?? null;
+    case "none":
+      return null;
+  }
+}
+
+function toRow(check: RbacCheck, decision: RbacDecision): AuditRow {
+  return {
+    principalType: check.principal.kind,
+    principalId: principalIdOf(check.principal),
+    // Reserved: slice-1 RbacCheck carries no originating-user field yet.
+    originatorUserId: null,
+    verb: check.verb,
+    resourceType: check.resource?.kind ?? null,
+    resourceId: resourceIdOf(check.resource),
+    decision: decision.allow ? "allow" : "deny",
+    reason: decision.allow ? null : decision.reason,
+    source: check.source,
+  };
+}
+
+/**
+ * The concrete AuditSink for `can()`. Never throws — `can()` already swallows
+ * sink exceptions, but the audit path defends independently.
+ */
+export function enqueueAuditRow(check: RbacCheck, decision: RbacDecision): void {
+  if (isAuditDisabled()) return;
+  try {
+    buffer.push(toRow(check, decision));
+    // The threshold flush is deferred to a zero-delay timeout so the can()
+    // call that happens to be the 200th never pays for the SQLite transaction
+    // itself — audit stays fire-and-forget on the request path.
+    if (buffer.length >= FLUSH_MAX_ROWS && !thresholdFlushScheduled) {
+      thresholdFlushScheduled = true;
+      const t = setTimeout(() => {
+        thresholdFlushScheduled = false;
+        flushAuditBuffer();
+      }, 0);
+      if (typeof t.unref === "function") t.unref();
+    }
+  } catch (err) {
+    console.warn("[rbac-audit] enqueue failed, dropping row:", (err as Error).message);
+  }
+}
+
+/**
+ * Drain the buffer into permission_audit in one transaction. Called by the
+ * flush interval, the 200-row threshold, and shutdown. A failed flush logs a
+ * warning and drops the batch — never throws.
+ */
+export function flushAuditBuffer(): void {
+  if (buffer.length === 0) return;
+  const rows = buffer;
+  buffer = [];
+  try {
+    const db = getDb();
+    const stmt = db.prepare(
+      `INSERT INTO permission_audit
+         (principalType, principalId, originatorUserId, verb, resourceType, resourceId, decision, reason, source)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insertAll = db.transaction((batch: AuditRow[]) => {
+      for (const r of batch) {
+        stmt.run(
+          r.principalType,
+          r.principalId,
+          r.originatorUserId,
+          r.verb,
+          r.resourceType,
+          r.resourceId,
+          r.decision,
+          r.reason,
+          r.source,
+        );
+      }
+    });
+    insertAll(rows);
+  } catch (err) {
+    console.warn(
+      `[rbac-audit] flush failed, dropping ${rows.length} row(s):`,
+      (err as Error).message,
+    );
+  }
+}
+
+/**
+ * Test hook, not a production knob: rbac-lifecycle-e2e.test.ts sets a huge
+ * interval so the SIGTERM-drain assertion can prove rows were persisted by
+ * the shutdown drain rather than a racing timer tick.
+ */
+function flushIntervalMs(): number {
+  const v = Number(process.env.RBAC_AUDIT_FLUSH_MS);
+  return Number.isFinite(v) && v > 0 ? v : FLUSH_INTERVAL_MS;
+}
+
+/** Start the periodic flush (2s tick). Idempotent. */
+export function startAuditWriter(intervalMs = flushIntervalMs()): void {
+  if (flushTimer) return;
+  flushTimer = setInterval(() => flushAuditBuffer(), intervalMs);
+  if (typeof flushTimer?.unref === "function") flushTimer.unref();
+}
+
+/** Stop the periodic flush. Does NOT flush — shutdown calls flushAuditBuffer(). */
+export function stopAuditWriter(): void {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+}
+
+/** Delete audit rows older than the retention window. Returns rows deleted. */
+export function purgeExpiredAuditRows(): number {
+  try {
+    const days = Number(process.env.RBAC_AUDIT_RETENTION_DAYS) || DEFAULT_RETENTION_DAYS;
+    // ts is CURRENT_TIMESTAMP format ("YYYY-MM-DD HH:MM:SS"); compute the
+    // cutoff in SQLite so the string formats always match.
+    const result = getDb()
+      .prepare("DELETE FROM permission_audit WHERE ts < datetime('now', ?)")
+      .run(`-${days} days`);
+    return result.changes;
+  } catch (err) {
+    console.warn("[rbac-audit] retention purge failed:", (err as Error).message);
+    return 0;
+  }
+}
+
+/** Start the retention GC (daily tick, immediate first run). Idempotent. */
+export function startAuditGc(intervalMs = AUDIT_GC_INTERVAL_MS): void {
+  if (auditGcTimer) return;
+
+  const purged = purgeExpiredAuditRows();
+  if (purged > 0) {
+    console.log(`[rbac-audit] Initial retention purge removed ${purged} audit row(s)`);
+  }
+
+  auditGcTimer = setInterval(() => {
+    const n = purgeExpiredAuditRows();
+    if (n > 0) {
+      console.log(`[rbac-audit] Retention purge removed ${n} audit row(s)`);
+    }
+  }, intervalMs);
+  if (typeof auditGcTimer?.unref === "function") auditGcTimer.unref();
+}
+
+export function stopAuditGc(): void {
+  if (auditGcTimer) {
+    clearInterval(auditGcTimer);
+    auditGcTimer = null;
+  }
+}

package/src/http/all-routes.ts

@@ -0,0 +1,58 @@
+/**
+ * Side-effect import of every HTTP handler module so their `route()` calls
+ * populate `routeRegistry`. Single source of truth for "all registered
+ * routes" — consumed by scripts/generate-openapi.ts and
+ * scripts/check-rbac-coverage.ts.
+ *
+ * When you add a new handler file, add its import HERE (keep the existing
+ * order — OpenAPI output and route matching in the generators follow
+ * registration order).
+ */
+import "./active-sessions";
+import "./agents";
+import "./approval-requests";
+import "./budgets";
+import "./codex-oauth-keep-warm";
+import "./config";
+import "./context";
+import "./db-query";
+import "./ecosystem";
+
+import "./api-keys";
+import "./events";
+import "./favorites";
+import "./fs";
+import "./heartbeat";
+import "./inbox-state";
+import "./integrations";
+import "./kv";
+import "./memory";
+import "./metrics";
+import "./oauth-locks";
+import "./page-proxy";
+import "./pages";
+import "./pages-public";
+import "./prompt-templates";
+import "./poll";
+import "./pricing";
+import "./repos";
+import "./schedules";
+import "./script-runs";
+import "./session-data";
+import "./sessions";
+import "./skills";
+import "./scripts";
+import "./mcp-bridge";
+import "./mcp-oauth";
+import "./mcp-servers";
+import "./stats";
+import "./status";
+import "./tasks";
+import "./task-templates";
+import "./trackers/jira";
+import "./trackers/linear";
+import "./users";
+import "./webhooks";
+import "./workflow-events";
+import "./workflows";
+import "./x";

package/src/http/config.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
   deleteSwarmConfig,
+  getAgentById,
   getResolvedConfig,
   getSwarmConfigById,
   getSwarmConfigLookupById,
@@ -14,6 +15,8 @@ import {
   reservedKeyError,
   validateConfigValue,
 } from "../be/swarm-config-guard";
+import { can, type PermissionVerb } from "../rbac";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { registerVolatileSecret } from "../utils/secret-scrubber";
 import { reloadGlobalConfigsAndIntegrations, scheduleIntegrationsReload } from "./core";
 import { route } from "./route-def";
@@ -32,6 +35,54 @@ function stripApiOnlyKeys<T extends { key: string }>(configs: T[]): T[] {
   return configs.filter((config) => !API_ONLY_CONFIG_KEYS.has(config.key));
 }
 
+function singleHeader(req: IncomingMessage, name: string): string | undefined {
+  const raw = req.headers[name];
+  return Array.isArray(raw) ? raw[0] : raw;
+}
+
+/**
+ * Gate a config write/delete over HTTP (DES-445 follow-up).
+ *
+ * Config administration is trusted to the operator (shared swarm key) and to
+ * authenticated users — they short-circuit as allowed, matching the
+ * operator/user-before-agent ordering used by fs.ts (Appendix A row 36). This
+ * preserves every existing HTTP caller (dashboard, codex-oauth token refresh,
+ * devin playbook cache — all operate as operator). Only an agent-context
+ * principal (X-Agent-ID without operator/user request auth) is gated to lead;
+ * the real per-agent enforcement lives on the MCP set-config/delete-config
+ * tools, where the principal is always an agent.
+ *
+ * Returns true when the request may proceed; on denial it writes a 403 and
+ * returns false.
+ */
+function ensureConfigAdmin(
+  req: IncomingMessage,
+  res: ServerResponse,
+  verb: Extract<PermissionVerb, "config.write.any" | "config.delete.any">,
+): boolean {
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "operator" || auth?.kind === "user") return true;
+  const agentId = singleHeader(req, "x-agent-id");
+  const agent = agentId ? getAgentById(agentId) : undefined;
+  const decision = can({
+    principal: { kind: "agent", agentId: agentId ?? "", isLead: agent?.isLead ?? false },
+    verb,
+    resource: { kind: "none" },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(
+      res,
+      verb === "config.write.any"
+        ? "Writing swarm config requires the lead agent"
+        : "Deleting swarm config requires the lead agent",
+      403,
+    );
+    return false;
+  }
+  return true;
+}
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const getResolvedConfigRoute = route({
@@ -119,6 +170,7 @@ const upsertConfig = route({
   summary:
     "Create or update a config entry (reserved env-only keys are rejected). Global-scope writes auto-trigger an integrations reload (debounced ~250ms) so Slack/GitHub/Linear/Jira/AgentMail pick up new credentials without an explicit /api/config/reload call.",
   tags: ["Config"],
+  rbac: { permission: "config.write.any" },
   body: z.object({
     scope: z.enum(["global", "agent", "repo"]),
     scopeId: z.string().nullish(),
@@ -141,6 +193,7 @@ const deleteConfig = route({
   summary:
     "Delete a config entry by ID (including legacy reserved rows for cleanup). Global-scope deletes auto-trigger an integrations reload.",
   tags: ["Config"],
+  rbac: { permission: "config.delete.any" },
   params: z.object({ id: z.string() }),
   responses: {
     200: { description: "Config deleted" },
@@ -251,6 +304,7 @@ export async function handleConfig(
   if (upsertConfig.match(req.method, pathSegments)) {
     const parsed = await upsertConfig.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    if (!ensureConfigAdmin(req, res, "config.write.any")) return true;
     const { scope, scopeId, key, value, isSecret, envPath, description } = parsed.body;
 
     if (scope === "global" && scopeId) {
@@ -303,6 +357,7 @@ export async function handleConfig(
   if (deleteConfig.match(req.method, pathSegments)) {
     const parsed = await deleteConfig.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    if (!ensureConfigAdmin(req, res, "config.delete.any")) return true;
     const existing = getSwarmConfigLookupById(parsed.params.id);
     if (!existing) {
       jsonError(res, "Config not found", 404);

package/src/http/favorites.ts

@@ -28,6 +28,11 @@ const putFavorite = route({
   pattern: ["api", "favorites"],
   summary: "Set favorite state for an item",
   tags: ["Favorites"],
+  // Self-scoped write: the row is keyed to the authenticated user
+  // (resolveHttpAuditUserId), never a body-supplied id, so there is no
+  // cross-principal authorization to gate — a user can only favorite for
+  // themselves.
+  rbac: { ungated: "self-scoped to the authenticated user; no cross-principal access" },
   body: z.object({
     itemType: FavoriteItemTypeSchema,
     itemId: z.string().min(1),

package/src/http/fs.ts

@@ -11,6 +11,7 @@ import {
 import { ensureAgentFsCredentialsForAgent } from "../be/seed/agent-fs-provision";
 import { type FileObject, type FileScope, FilesError, normalizeFilesError } from "../fs/provider";
 import { getFileStorageProvider } from "../fs/registry";
+import { can, type RbacPrincipal, type RbacResource } from "../rbac";
 import type { TaskAttachment } from "../types";
 import { getCurrentRequestAuth, getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
@@ -93,6 +94,7 @@ const uploadTaskFileRoute = route({
     413: { description: "Upload exceeds 50 MiB" },
   },
   auth: { apiKey: true, agentId: true },
+  rbac: { permission: "task.fs.mutate" },
 });
 
 const getTaskFileRoute = route({
@@ -150,6 +152,7 @@ const deleteTaskFileRoute = route({
     404: { description: "Task or attachment not found" },
   },
   auth: { apiKey: true, agentId: true },
+  rbac: { permission: "task.fs.mutate" },
 });
 
 export async function handleFs(
@@ -430,17 +433,34 @@ function findAttachment(
 }
 
 function canMutateTask(
-  task: { agentId: string | null; creatorAgentId?: string },
+  task: { id: string; agentId: string | null; creatorAgentId?: string },
   myAgentId: string | undefined,
   req: IncomingMessage,
 ): boolean {
+  const resource: RbacResource = {
+    kind: "task",
+    taskId: task.id,
+    agentId: task.agentId,
+    creatorAgentId: task.creatorAgentId,
+  };
+  // Decision order preserved (plan Appendix A row 36): operator/user request
+  // auth short-circuits BEFORE agent identity — an operator bearer with a
+  // non-owner X-Agent-ID is still allowed. The agent branches only bind when
+  // the request-auth context is unset.
   const auth = getRequestAuth(req);
-  if (auth?.kind === "operator") return true;
-  if (auth?.kind === "user") return true;
-  if (!myAgentId) return false;
-  const agent = getAgentById(myAgentId);
-  if (agent?.isLead) return true;
-  return task.agentId === myAgentId || task.creatorAgentId === myAgentId;
+  let principal: RbacPrincipal;
+  if (auth?.kind === "operator") {
+    principal = { kind: "operator" };
+  } else if (auth?.kind === "user") {
+    principal = { kind: "user", userId: auth.userId };
+  } else {
+    // A missing caller identity cannot be lead/assignee/creator — same denial
+    // as before (no separate "agent not found" branch).
+    if (!myAgentId) return false;
+    const agent = getAgentById(myAgentId);
+    principal = { kind: "agent", agentId: myAgentId, isLead: agent?.isLead ?? false };
+  }
+  return can({ principal, verb: "task.fs.mutate", resource, source: "http" }).allow;
 }
 
 async function readRawBody(

package/src/http/index.ts

@@ -9,6 +9,14 @@ import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/se
 import { getEnabledCapabilities, hasCapability } from "@/server";
 import { initAgentMail } from "../agentmail";
 import { closeDb, getSwarmConfigs, upsertSwarmConfig } from "../be/db";
+import {
+  enqueueAuditRow,
+  flushAuditBuffer,
+  startAuditGc,
+  startAuditWriter,
+  stopAuditGc,
+  stopAuditWriter,
+} from "../be/rbac-audit";
 import { initGitHub } from "../github";
 import { initGitLab } from "../gitlab";
 import { stopHeartbeat } from "../heartbeat";
@@ -21,6 +29,7 @@ import {
   withRemoteContext,
   withSpanContext,
 } from "../otel";
+import { clearAuditSink, setAuditSink } from "../rbac";
 import { startScriptRunSupervisor, stopScriptRunSupervisor } from "../script-workflows/supervisor";
 import { getServerSessionsProcessed } from "../server-runtime-counters";
 import { startSlackApp, stopSlackApp } from "../slack";
@@ -416,6 +425,12 @@ async function shutdown() {
   // Stop memory expired-row garbage collector
   stopMemoryGc();
 
+  // Stop RBAC audit: retention GC, flush interval, final drain, detach sink
+  stopAuditGc();
+  stopAuditWriter();
+  flushAuditBuffer();
+  clearAuditSink();
+
   if (globalState.__apiGcInterval) {
     clearInterval(globalState.__apiGcInterval);
     delete globalState.__apiGcInterval;
@@ -502,6 +517,15 @@ try {
   console.error("[startup] Failed to seed built-in entities:", err);
 }
 
+// Wire the RBAC permission-audit sink into can() and start the batched writer
+// (2s flush) + retention GC (daily tick) BEFORE the server accepts traffic —
+// installing it inside the listen callback would leave an unaudited startup
+// window (requests can land while telemetry/Slack init awaits are pending).
+// RBAC_AUDIT_DISABLED=true makes the sink a no-op inside enqueueAuditRow.
+setAuditSink(enqueueAuditRow);
+startAuditWriter();
+startAuditGc();
+
 // business-use initialization (no-op if envs not set)
 initialize();
 
@@ -593,6 +617,8 @@ httpServer
     // Start expired-memory garbage collector (1-hour tick, immediate first run)
     startMemoryGc();
 
+    // (RBAC audit sink is wired pre-listen — see above httpServer.listen.)
+
     // Background backfill: re-embed any agent_memory rows with wrong-dimension
     // embeddings (e.g. 1536d instead of 512d). Non-blocking, idempotent, no-op
     // when the DB is clean. See src/be/memory/boot-reembed.ts.

package/src/http/kv.ts

@@ -11,6 +11,7 @@ import {
   listKv,
   upsertKv,
 } from "../be/db";
+import { can } from "../rbac";
 import { agentContextKey, pageContextKey } from "../tasks/context-key";
 import { KvKeySchema, KvNamespaceSchema, KvValueTypeSchema } from "../types";
 import { route } from "./route-def";
@@ -107,6 +108,7 @@ const putKvHeader = route({
   params: z.object({ key: KvKeySchema }),
   body: kvSetBodySchema,
   responses: RESPONSES_PUT,
+  rbac: { permission: "kv.write.any" },
 });
 
 const deleteKvHeader = route({
@@ -122,6 +124,7 @@ const deleteKvHeader = route({
     403: { description: "Caller may not write this namespace" },
     400: { description: "Validation error or unresolvable namespace" },
   },
+  rbac: { permission: "kv.write.any" },
 });
 
 const incrKvHeader = route({
@@ -133,6 +136,7 @@ const incrKvHeader = route({
   params: z.object({ key: KvKeySchema }),
   body: kvIncrBodySchema,
   responses: RESPONSES_PUT,
+  rbac: { permission: "kv.write.any" },
 });
 
 const listKvHeader = route({
@@ -165,6 +169,7 @@ const putKvExplicit = route({
   params: z.object({ namespace: KvNamespaceSchema, key: KvKeySchema }),
   body: kvSetBodySchema,
   responses: RESPONSES_PUT,
+  rbac: { permission: "kv.write.any" },
 });
 
 const deleteKvExplicit = route({
@@ -179,6 +184,7 @@ const deleteKvExplicit = route({
     404: { description: "KV entry not found" },
     403: { description: "Caller may not write this namespace" },
   },
+  rbac: { permission: "kv.write.any" },
 });
 
 const incrKvExplicit = route({
@@ -190,6 +196,7 @@ const incrKvExplicit = route({
   params: z.object({ namespace: KvNamespaceSchema, key: KvKeySchema }),
   body: kvIncrBodySchema,
   responses: RESPONSES_PUT,
+  rbac: { permission: "kv.write.any" },
 });
 
 const listKvExplicit = route({
@@ -324,10 +331,20 @@ function authorizeWrite(
     return null;
   }
   if (namespace.startsWith("task:agent:")) {
-    const target = namespace.slice("task:agent:".length);
-    if (ctx.callerAgentId && target === ctx.callerAgentId) return null;
-    if (ctx.isLead) return null;
-    return { status: 403, message: "writes to another agent's namespace require lead" };
+    // A missing caller identity can never own a namespace nor be lead — same
+    // denial as before (no separate "agent not found" branch).
+    const allowed =
+      ctx.callerAgentId != null &&
+      can({
+        principal: { kind: "agent", agentId: ctx.callerAgentId, isLead: ctx.isLead },
+        verb: "kv.write.any",
+        resource: { kind: "kv-namespace", namespace },
+        source: "http",
+      }).allow;
+    if (!allowed) {
+      return { status: 403, message: "writes to another agent's namespace require lead" };
+    }
+    return null;
   }
   return null;
 }

package/src/http/route-def.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
+import type { PermissionVerb } from "../rbac";
 import { jsonError, matchRoute, parseBody } from "./utils";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -32,6 +33,14 @@ export interface RouteDef<
     apiKey?: boolean; // default true
     agentId?: boolean; // requires X-Agent-ID
   };
+  /**
+   * RBAC posture (DES-445). Required on every non-GET route — enforced by
+   * `bun run check:rbac-coverage` (CI). Either name the `PermissionVerb` the
+   * handler gates via `can()`, or document why no principal gate applies.
+   * Declarative in slice 1: the handler still calls `can()` itself; the role
+   * engine (increment 3) may enforce the declared verb centrally.
+   */
+  rbac?: { permission: PermissionVerb } | { ungated: string };
 }
 
 interface ParsedRequest<TParams, TQuery, TBody> {