@desplega.ai/agent-swarm 2.3.0 → 2.4.0

package/src/http/realtime.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { getCombConfig } from "../comb/config";
+import { findUserById } from "../be/users";
 import { can } from "../rbac";
 import bundle from "../realtime/browser.generated.txt" with { type: "text" };
 import { issueRealtimeTicket } from "../realtime/tickets";
 import { getRequestAuth } from "../utils/request-auth-context";
+import { dashboardUserIdHeader } from "./favorite-owner";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -14,14 +15,16 @@ const realtimeTicketRoute = route({
   pattern: ["api", "realtime", "ticket"],
   summary: "Issue a one-shot dashboard realtime ticket",
   tags: ["Rooms"],
-  rbac: { permission: "comb.presence" },
+  description:
+    "The ticket authorizes one dashboard socket for presence rooms: Comb drives (`comb.presence`) and sessions (`session.presence`). An operator-key tab's picked user (`X-Swarm-User-Id`) rides on the ticket so session presence can check that user's access.",
+  // Comb presence came first; a role granting only `comb.presence` keeps its ticket.
+  rbac: { permission: "session.presence", alsoAdmits: ["comb.presence"] },
   responses: {
     200: {
       description: "One-shot realtime ticket",
       schema: z.object({ ticket: z.string(), expiresAt: z.number().int() }),
     },
-    403: { description: "Comb presence is not allowed" },
-    404: { description: "Comb is not enabled" },
+    403: { description: "Presence is not allowed" },
   },
 });
 
@@ -37,7 +40,7 @@ route({
   },
 });
 
-/** `POST /api/realtime/ticket`: a one-shot ticket for a dashboard realtime socket (Comb presence). */
+/** `POST /api/realtime/ticket`: a one-shot ticket for a dashboard realtime socket (presence rooms). */
 export async function handleRealtimeTicket(
   req: IncomingMessage,
   res: ServerResponse,
@@ -45,34 +48,36 @@ export async function handleRealtimeTicket(
   queryParams: URLSearchParams,
 ): Promise<boolean> {
   if (!realtimeTicketRoute.match(req.method, pathSegments)) return false;
-  // Comb presence is the only ticket consumer, so the route is off with Comb.
-  if (!getCombConfig().enabled) {
-    jsonError(res, "Comb is not enabled", 404);
-    return true;
-  }
+  // Session presence needs the ticket with Comb off too; each room still
+  // checks its own verb and access when the socket joins it.
   const parsed = await realtimeTicketRoute.parse(req, res, pathSegments, queryParams);
   if (!parsed) return true;
   const auth = getRequestAuth(req);
   if (!auth || auth.kind === "agent" || auth.kind === "guest" || auth.kind === "controller") {
-    jsonError(res, "Comb presence requires dashboard authentication", 403);
+    jsonError(res, "Presence requires dashboard authentication", 403);
     return true;
   }
   const principal =
     auth.kind === "operator"
       ? ({ kind: "operator" } as const)
       : ({ kind: "user", userId: auth.userId } as const);
-  if (
-    !can({
-      principal,
-      verb: "comb.presence",
-      resource: { kind: "none" },
-      source: "http",
-    }).allow
-  ) {
-    jsonError(res, "Comb presence requires the comb.presence permission", 403);
+  const allowed = (verb: "comb.presence" | "session.presence") =>
+    can({ principal, verb, resource: { kind: "none" }, source: "http" }).allow;
+  if (!allowed("comb.presence") && !allowed("session.presence")) {
+    jsonError(res, "Presence requires the comb.presence or session.presence permission", 403);
     return true;
   }
-  realtimeTicketRoute.respond(res, 200, issueRealtimeTicket(auth));
+  let dashboardUserId: string | undefined;
+  if (auth.kind === "operator" && !auth.page) {
+    const picked = dashboardUserIdHeader(req);
+    const user = picked ? await findUserById(picked) : null;
+    if (user?.status === "active") dashboardUserId = user.id;
+  }
+  realtimeTicketRoute.respond(
+    res,
+    200,
+    issueRealtimeTicket(dashboardUserId ? { ...auth, dashboardUserId } : auth),
+  );
   return true;
 }
 

package/src/http/route-def.ts

@@ -76,7 +76,20 @@ export interface RouteDef<
   auth?: {
     apiKey?: boolean; // default true
     agentId?: boolean; // requires X-Agent-ID
+    /**
+     * Why a user token may name an agent in X-Agent-ID here. Everywhere else
+     * `handleCore` refuses that pair. The user still needs `agent.act.any`.
+     */
+    userNamesAgent?: string;
   };
+  /**
+   * Session posture: how a user caller's session access gates this route.
+   * Required on every route keyed by a task, steering message or attachment,
+   * on every write whose body names a task, and on every active-session write
+   * (`session-route-posture.test.ts`).
+   * `handleCore` enforces the path forms; `parse()` enforces `bodyTaskIds`.
+   */
+  session?: SessionPosture;
   /**
    * RBAC posture (DES-445). Required on every non-GET route — enforced by
    * `bun run check:rbac-coverage` (CI). Either name the `PermissionVerb` the
@@ -84,7 +97,56 @@ export interface RouteDef<
    * 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 };
+  rbac?:
+    | { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] }
+    | { ungated: string };
+}
+
+/**
+ * - `taskParam` / `steeringParam`: the path param naming a task, or a steering
+ *   message whose task counts. A GET needs read access, any other method write.
+ * - `activeSessionParam`: the path param naming an active-session row; its task
+ *   counts the same way. A row with no task admits no user.
+ * - `bodyTaskIds`: the task ids a write's body names; each needs write access.
+ * - `agentWide`: why the route changes sessions across a whole agent. It
+ *   refuses every user actor; agents and the operator key keep access.
+ * - `none`: why the session does not gate this route.
+ */
+export type SessionPosture =
+  | { taskParam: string }
+  | { steeringParam: string }
+  | { activeSessionParam: string }
+  | { agentWide: string }
+  | { bodyTaskIds: (body: unknown) => readonly unknown[] }
+  | { none: string };
+
+/** A `bodyTaskIds` posture reading one top-level body key. */
+export function bodyTask(key: string): SessionPosture {
+  return { bodyTaskIds: (body) => [(body as Record<string, unknown> | null | undefined)?.[key]] };
+}
+
+/** A `bodyTaskIds` posture reading `key` off every item of the body's `listKey` array. */
+export function bodyListTask(listKey: string, key: string): SessionPosture {
+  return {
+    bodyTaskIds: (body) => {
+      const items = (body as Record<string, unknown> | null | undefined)?.[listKey];
+      return Array.isArray(items)
+        ? items.map((item) => (item as Record<string, unknown> | null)?.[key])
+        : [];
+    },
+  };
+}
+
+/** The raw `{name}` path params of `def` read off the request's segments. */
+export function routePathParams(def: RouteDef, pathSegments: string[]): Record<string, string> {
+  const params: Record<string, string> = {};
+  const paramNames = def.path.match(/\{(\w+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+  for (let i = 0; i < def.pattern.length; i++) {
+    if (def.pattern[i] === null && paramNames.length > 0) {
+      params[paramNames.shift()!] = pathSegments[i] ?? "";
+    }
+  }
+  return params;
 }
 
 interface ParsedRequest<TParams, TQuery, TBody> {
@@ -367,21 +429,25 @@ export function route<
 
     async parse(req, res, pathSegments, queryParams) {
       try {
-        // Extract path params from dynamic segments
-        const rawParams: Record<string, string> = {};
-        if (def.params) {
-          const paramNames = def.path.match(/\{(\w+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
-          for (let i = 0; i < def.pattern.length; i++) {
-            if (def.pattern[i] === null && paramNames.length > 0) {
-              rawParams[paramNames.shift()!] = pathSegments[i] ?? "";
-            }
+        const rawBody = def.body ? await parseBody(req, def.maxBodyBytes) : undefined;
+        // Session access first, so a malformed body cannot tell a reader
+        // anything about a session they cannot write in.
+        if (def.session && "bodyTaskIds" in def.session) {
+          // Lazy: session-access reaches the DB layer, which imports route files.
+          const { bodySessionDenial } = await import("./session-access");
+          const denial = await bodySessionDenial(req, def.session.bodyTaskIds(rawBody));
+          if (denial) {
+            jsonError(res, denial, 403);
+            return null;
           }
         }
 
         // Parse + validate each part
-        const params = def.params ? def.params.parse(rawParams) : undefined;
+        const params = def.params
+          ? def.params.parse(routePathParams(def, pathSegments))
+          : undefined;
         const query = def.query ? def.query.parse(Object.fromEntries(queryParams)) : undefined;
-        const body = def.body ? def.body.parse(await parseBody(req, def.maxBodyBytes)) : undefined;
+        const body = def.body ? def.body.parse(rawBody) : undefined;
 
         return { params, query, body } as ParsedRequest<
           z.infer<TParams>,

package/src/http/script-runs.ts

@@ -47,7 +47,7 @@ import {
   RawLlmConfigSchema,
   RawLlmOutputSchema,
 } from "../workflows/executors/raw-llm";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
 import { json, jsonError } from "./utils";
 
 const DEFAULT_SCRIPT_RUN_CONCURRENCY_CAP = 10;
@@ -282,6 +282,7 @@ const agentTaskRoute = route({
   method: "post",
   path: "/api/internal/script-runs/{runId}/agent-task",
   pattern: ["api", "internal", "script-runs", null, "agent-task"],
+  session: bodyTask("parentTaskId"),
   operationId: "script_runs_internal_agent_task",
   summary: "Create or wait for a script workflow agent task step",
   tags: ["Script Runs"],

package/src/http/scripts.ts

@@ -225,6 +225,10 @@ const upsertRoute = route({
   method: "post",
   path: "/api/scripts/upsert",
   pattern: ["api", "scripts", "upsert"],
+  auth: {
+    userNamesAgent:
+      "dashboard script playground: a user runs or saves a script in a chosen agent's scope",
+  },
   operationId: "scripts_upsert",
   summary: "Create or update a reusable script",
   description: "Explicit script upserts run a TypeScript typecheck before writing.",
@@ -253,6 +257,10 @@ const runRoute = route({
   method: "post",
   path: "/api/scripts/run",
   pattern: ["api", "scripts", "run"],
+  auth: {
+    userNamesAgent:
+      "dashboard script playground: a user runs or saves a script in a chosen agent's scope",
+  },
   operationId: "scripts_run",
   summary: "Run a reusable or inline script",
   description:

package/src/http/session-access.ts

@@ -0,0 +1,179 @@
+import type { IncomingMessage } from "node:http";
+import { getSteeringMessageById } from "../be/db";
+import { getActiveSessionById } from "../be/db/active-sessions";
+import { getUserGrant } from "../be/rbac-roles";
+import {
+  getSessionRoot,
+  hasSessionAccess,
+  type SessionAccess,
+  sessionAccess,
+  sessionAccessForRoot,
+} from "../be/session-shares";
+import { findUserById } from "../be/users";
+import { isRbacEnabled } from "../rbac";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { dashboardUserIdHeader } from "./favorite-owner";
+import { type RouteDef, routePathParams } from "./route-def";
+
+/**
+ * Who a request acts for when it touches a session.
+ *
+ * - `bypass`: no session check. Agents (an `aseph_` token, or the operator key
+ *   with `X-Agent-ID`) continue chains through `POST /api/tasks` all the time,
+ *   and an operator-key call with no picked dashboard user is a script or the
+ *   CLI. Both keep the access they had before sharing existed.
+ * - `user`: an `aswt_` user token, or an operator-key dashboard tab naming an
+ *   active user in `X-Swarm-User-Id`. On the shared key that identity is
+ *   honor-system, the same trust the dashboard already gives favorites.
+ *   `userId: null` is a guest page session, which has no user at all.
+ */
+export type SessionActor = { kind: "bypass" } | { kind: "user"; userId: string | null };
+
+const BYPASS: SessionActor = { kind: "bypass" };
+
+export async function resolveSessionActor(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+): Promise<SessionActor> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (auth?.kind === "guest") return { kind: "user", userId: null };
+  if (auth?.kind === "operator" && !myAgentId && !auth.page) {
+    const picked = dashboardUserIdHeader(req);
+    if (!picked) return BYPASS;
+    const user = await findUserById(picked);
+    return user?.status === "active" ? { kind: "user", userId: user.id } : BYPASS;
+  }
+  return BYPASS;
+}
+
+/** The actor's access to the session holding `taskId`; `owner` for a bypass actor. */
+export async function sessionAccessFor(
+  actor: SessionActor,
+  taskId: string,
+): Promise<SessionAccess> {
+  return actor.kind === "bypass" ? "owner" : sessionAccess(actor.userId, taskId);
+}
+
+export const SESSION_READ_DENIED =
+  "You don't have access to this session. Ask the owner to share it.";
+
+/** True unless the request acts for a user who lacks read access to the task's session. */
+export async function canReadSession(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+  taskId: string,
+): Promise<boolean> {
+  const access = await sessionAccessFor(await resolveSessionActor(req, myAgentId), taskId);
+  return hasSessionAccess(access, "read");
+}
+
+/** The SQL list filter (`readableSessionCondition`) for an actor; none for a bypass actor. */
+export function readableByFor(actor: SessionActor): { userId: string | null } | undefined {
+  return actor.kind === "user" ? { userId: actor.userId } : undefined;
+}
+
+export const SESSION_WRITE_DENIED =
+  "You can't write in this session. Ask the owner to share it with edit access.";
+
+/**
+ * The denial for an actor lacking `needed` access to the session holding
+ * `taskId`, or null. An unknown task passes, so the handler still answers 404.
+ */
+async function denialFor(
+  actor: SessionActor,
+  taskId: string,
+  needed: "read" | "write",
+): Promise<string | null> {
+  if (actor.kind === "bypass") return null;
+  const root = await getSessionRoot(taskId);
+  if (!root) return null;
+  if (hasSessionAccess(await sessionAccessForRoot(actor.userId, root), needed)) return null;
+  return needed === "read" ? SESSION_READ_DENIED : SESSION_WRITE_DENIED;
+}
+
+export const SESSION_AGENT_WIDE_DENIED =
+  "This changes sessions across a whole agent. Only the agent or the operator can call it.";
+
+/**
+ * Enforces a route's path session posture (`taskParam`, `steeringParam`,
+ * `activeSessionParam`, `agentWide`) before any handler runs: a GET needs read
+ * access, every other method write access.
+ */
+export async function pathSessionDenial(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+  def: RouteDef,
+  pathSegments: string[],
+): Promise<string | null> {
+  const posture = def.session;
+  if (!posture || "bodyTaskIds" in posture || "none" in posture) return null;
+  const actor = await resolveSessionActor(req, myAgentId);
+  if (actor.kind === "bypass") return null;
+  if ("agentWide" in posture) return SESSION_AGENT_WIDE_DENIED;
+  const needed = def.method === "get" ? "read" : "write";
+  const params = routePathParams(def, pathSegments);
+  let taskId: string | undefined;
+  if ("taskParam" in posture) {
+    taskId = params[posture.taskParam];
+  } else if ("steeringParam" in posture) {
+    const message = await getSteeringMessageById(params[posture.steeringParam] ?? "");
+    taskId = message?.taskId;
+  } else {
+    const row = await getActiveSessionById(params[posture.activeSessionParam] ?? "");
+    // An unknown row passes so the handler answers; a row with no task is the agent's own.
+    if (!row) return null;
+    if (!row.taskId) return needed === "read" ? SESSION_READ_DENIED : SESSION_WRITE_DENIED;
+    taskId = row.taskId;
+  }
+  if (!taskId) return null;
+  return denialFor(actor, taskId, needed);
+}
+
+/** Enforces a `bodyTaskIds` posture: every task the body names needs write access. */
+export async function bodySessionDenial(
+  req: IncomingMessage,
+  taskIds: readonly unknown[],
+): Promise<string | null> {
+  const ids = [...new Set(taskIds.filter((id): id is string => typeof id === "string" && !!id))];
+  if (ids.length === 0) return null;
+  const actor = await resolveSessionActor(req, headerAgentId(req));
+  for (const id of ids) {
+    const denial = await denialFor(actor, id, "write");
+    if (denial) return denial;
+  }
+  return null;
+}
+
+function headerAgentId(req: IncomingMessage): string | undefined {
+  const header = req.headers["x-agent-id"];
+  return Array.isArray(header) ? header[0] : header;
+}
+
+export const USER_AGENT_HEADER_DENIED =
+  "A user token cannot act as an agent. Drop X-Agent-ID, or call with the agent's own credential.";
+
+/**
+ * Refuses a user or guest token that claims agent identity: any X-Agent-ID,
+ * and the agent MCP transport at all (`/mcp-user` is the user transport).
+ * Runs once in `handleCore`, before any handler reads or changes state. A
+ * route that sets `auth.userNamesAgent` (the dashboard script playground)
+ * admits the pair for a user holding `agent.act.any`, an authorization of the
+ * user, never of the named agent.
+ */
+export async function userAgentIdentityDenial(
+  req: IncomingMessage,
+  def: RouteDef | undefined,
+  pathSegments: string[],
+): Promise<string | null> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "user" && auth?.kind !== "guest") return null;
+  if (pathSegments.length === 1 && pathSegments[0] === "mcp") return USER_AGENT_HEADER_DENIED;
+  if (req.headers["x-agent-id"] === undefined) return null;
+  if (auth.kind === "user" && def?.auth?.userNamesAgent) {
+    if (!isRbacEnabled()) return null;
+    const grant = await getUserGrant(auth.userId);
+    if (grant.grantsAll || grant.verbs.has("agent.act.any")) return null;
+  }
+  return USER_AGENT_HEADER_DENIED;
+}

package/src/http/session-data.ts

@@ -24,7 +24,8 @@ import {
   SessionCostSchema,
   SessionLogSchema,
 } from "../types";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
+import { canReadSession, SESSION_READ_DENIED } from "./session-access";
 import { recomputeSessionCost } from "./session-cost-recompute";
 import { cachedUsageReport } from "./usage-cache";
 import { jsonError } from "./utils";
@@ -127,6 +128,7 @@ const createSessionLogsRoute = route({
   method: "post",
   path: "/api/session-logs",
   pattern: ["api", "session-logs"],
+  session: bodyTask("taskId"),
   summary: "Store session logs",
   tags: ["Session Data"],
   body: z.object({
@@ -149,6 +151,7 @@ const getSessionLogsByTask = route({
   method: "get",
   path: "/api/tasks/{taskId}/session-logs",
   pattern: ["api", "tasks", null, "session-logs"],
+  session: { taskParam: "taskId" },
   summary: "Get session logs for a task",
   tags: ["Session Data"],
   params: z.object({ taskId: z.string() }),
@@ -172,6 +175,7 @@ const createSessionCostRoute = route({
   method: "post",
   path: "/api/session-costs",
   pattern: ["api", "session-costs"],
+  session: bodyTask("taskId"),
   summary: "Store session cost record",
   tags: ["Session Data"],
   body: z.object({
@@ -310,7 +314,7 @@ export async function handleSessionData(
   res: ServerResponse,
   pathSegments: string[],
   queryParams: URLSearchParams,
-  _myAgentId: string | undefined,
+  myAgentId: string | undefined,
 ): Promise<boolean> {
   if (createSessionLogsRoute.match(req.method, pathSegments)) {
     const parsed = await createSessionLogsRoute.parse(req, res, pathSegments, queryParams);
@@ -353,6 +357,10 @@ export async function handleSessionData(
       jsonError(res, "Task not found", 404);
       return true;
     }
+    if (!(await canReadSession(req, myAgentId, task.id))) {
+      jsonError(res, SESSION_READ_DENIED, 403);
+      return true;
+    }
     const logs = await getSessionLogsByTaskId(parsed.params.taskId, parsed.query?.limit);
     getSessionLogsByTask.respond(res, 200, { logs });
     return true;