@desplega.ai/agent-swarm 2.3.0 → 2.4.1

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;

package/src/http/sessions.ts

@@ -7,18 +7,40 @@ import {
   getTaskById,
   listRecentSessions,
 } from "../be/db";
+import {
+  getSessionRoot,
+  listActiveSessionShares,
+  type SessionAccess,
+  sessionAccessForRoot,
+  setSessionShares,
+  toSessionSharesState,
+} from "../be/session-shares";
 import { getTaskSteeringFieldsForTasks } from "../be/steering";
 import { getTaskCitationsForTasks, TaskCitationSchema } from "../be/task-citations";
 import {
+  findUserById,
   InvalidRuntimeTokenError,
   mintRuntimeToken,
   mintSessionToken,
   revokeSessionToken,
 } from "../be/users";
-import { type AgentTask, AgentTaskSchema, AgentTaskStatusSchema, SteerModeSchema } from "../types";
+import { can } from "../rbac";
+import { sessionAccessTopic } from "../realtime/auth";
+import { realtimeBus } from "../realtime/bus";
+import {
+  type AgentTask,
+  AgentTaskSchema,
+  AgentTaskStatusSchema,
+  SessionAccessSchema,
+  SessionOwnerSchema,
+  SessionSharesSchema,
+  SessionSharesUpdateSchema,
+  SteerModeSchema,
+} from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { isRuntimePoolsEnabled } from "../utils/runtime-pools-flag";
 import { route } from "./route-def";
+import { resolveSessionActor, type SessionActor } from "./session-access";
 import { jsonError } from "./utils";
 
 // ─── Response Schemas ────────────────────────────────────────────────────────
@@ -91,6 +113,9 @@ const mintSessionTokenRoute = route({
   method: "post",
   path: "/api/sessions/tokens",
   pattern: ["api", "sessions", "tokens"],
+  session: {
+    none: "user tokens cannot mint: the handler admits only the operator key or the task's own runtime",
+  },
   summary: "Mint an ephemeral task or runtime token",
   description:
     "Operators can mint task or runtime tokens. Runtime tokens can mint task tokens for their own assigned tasks. Child tokens expire with their parent runtime.",
@@ -175,6 +200,14 @@ const listSessions = route({
     contextKeyPrefix: z.string().min(1).optional(),
     /** `full` restores the legacy shape (full root `AgentTask`); default is slim. */
     fields: z.enum(["full", "slim"]).optional(),
+    /**
+     * `mine`: sessions the caller owns. `shared`: sessions someone else owns
+     * with an active share to the caller or to everyone. Omit for every
+     * session the caller can open. Callers that act for no user (agents, the
+     * operator key with no picked dashboard user) see every session, and
+     * an empty list for either scope.
+     */
+    scope: z.enum(["mine", "shared"]).optional(),
   }),
   responses: {
     200: {
@@ -195,23 +228,78 @@ const getSession = route({
   method: "get",
   path: "/api/sessions/{rootTaskId}",
   pattern: ["api", "sessions", null],
+  session: { taskParam: "rootTaskId" },
   summary: "Get a session — root task + the entire descendant chain",
   tags: ["Sessions"],
   params: z.object({ rootTaskId: z.string() }),
   responses: {
     200: {
-      description: "Root task + chain (ordered by createdAt)",
+      description:
+        "Root task + chain (ordered by createdAt), plus the caller's `access` and the session `owner`",
       schema: z.object({
         root: TaskWithSteeringSchema,
         chain: z.array(TaskWithSteeringSchema),
+        access: SessionAccessSchema,
+        owner: SessionOwnerSchema.nullable(),
       }),
     },
     401: { description: "Unauthorized" },
+    403: { description: "The caller has no access to this session" },
+    404: { description: "Root task not found" },
+  },
+  auth: { apiKey: true },
+});
+
+const getSessionShares = route({
+  method: "get",
+  path: "/api/sessions/{rootTaskId}/shares",
+  pattern: ["api", "sessions", null, "shares"],
+  session: { taskParam: "rootTaskId" },
+  summary: "List a session's active shares",
+  description:
+    "Active shares only. `everyone` is the access every user has; `users` are per-person shares. A session with no shares is private to its owner.",
+  tags: ["Sessions"],
+  params: z.object({ rootTaskId: z.string() }),
+  responses: {
+    200: { description: "Active shares", schema: SessionSharesSchema },
+    401: { description: "Unauthorized" },
+    403: { description: "The caller has no access to this session" },
+    404: { description: "Root task not found" },
+  },
+  auth: { apiKey: true },
+});
+
+const putSessionShares = route({
+  method: "put",
+  path: "/api/sessions/{rootTaskId}/shares",
+  pattern: ["api", "sessions", null, "shares"],
+  session: { taskParam: "rootTaskId" },
+  summary: "Set who can view or edit a session",
+  description:
+    "Owner only. The body is the full desired state: users left out lose access. Changed targets have their active share revoked and a new one inserted in one transaction; shares are never deleted.",
+  tags: ["Sessions"],
+  params: z.object({ rootTaskId: z.string() }),
+  body: SessionSharesUpdateSchema,
+  responses: {
+    200: { description: "Active shares after the change", schema: SessionSharesSchema },
+    400: { description: "Validation error or unknown user" },
+    401: { description: "Unauthorized" },
+    403: { description: "Only the session owner can share it" },
     404: { description: "Root task not found" },
+    409: { description: "The session has no owner, so it is already open to everyone" },
   },
   auth: { apiKey: true },
+  rbac: { permission: "session.share" },
 });
 
+/** The actor's access to the session rooted at `root`; `owner` when the actor bypasses checks. */
+async function accessForRoot(
+  actor: SessionActor,
+  root: { id: string; requestedByUserId: string | null },
+): Promise<SessionAccess> {
+  return actor.kind === "bypass" ? "owner" : sessionAccessForRoot(actor.userId, root);
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleSessions(
@@ -219,6 +307,7 @@ export async function handleSessions(
   res: ServerResponse,
   pathSegments: string[],
   queryParams: URLSearchParams,
+  myAgentId?: string,
 ): Promise<boolean> {
   if (mintSessionTokenRoute.match(req.method, pathSegments)) {
     const auth = getRequestAuth(req);
@@ -312,13 +401,30 @@ export async function handleSessions(
           .map((s) => s.trim())
           .filter(Boolean)
       : undefined;
-    const baseOpts = {
-      limit: parsed.query.limit,
-      offset: parsed.query.offset,
+    const actor = await resolveSessionActor(req, myAgentId);
+    if (actor.kind === "bypass" && parsed.query.scope) {
+      // No user to own or receive a share.
+      listSessions.respond(res, 200, {
+        sessions: [],
+        total: 0,
+        limit: parsed.query.limit ?? 25,
+        offset: parsed.query.offset ?? 0,
+      });
+      return true;
+    }
+    const filterOpts = {
       source: sources,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
       contextKeyPrefix: parsed.query.contextKeyPrefix,
+      ...(actor.kind === "user"
+        ? { viewer: { userId: actor.userId, scope: parsed.query.scope ?? "all" } as const }
+        : {}),
+    };
+    const baseOpts = {
+      ...filterOpts,
+      limit: parsed.query.limit,
+      offset: parsed.query.offset,
     };
     // List responses default to slim (root is a task summary); `?fields=full` restores it.
     const sessions =
@@ -327,12 +433,7 @@ export async function handleSessions(
         : await listRecentSessions({ ...baseOpts, slim: true });
     // Filter-aware total: same WHERE as the list query, so the UI pager
     // reflects the filtered result set.
-    const total = await countSessions({
-      source: sources,
-      q: parsed.query.q,
-      requestedByUserId: parsed.query.requestedByUserId,
-      contextKeyPrefix: parsed.query.contextKeyPrefix,
-    });
+    const total = await countSessions(filterOpts);
     listSessions.respond(res, 200, {
       sessions,
       total,
@@ -350,6 +451,25 @@ export async function handleSessions(
       jsonError(res, "Root task not found", 404);
       return true;
     }
+    // The route accepts any task id; access follows the topmost root.
+    const sessionRoot = (await getSessionRoot(root.id)) ?? {
+      id: root.id,
+      requestedByUserId: root.requestedByUserId ?? null,
+    };
+    const access = await accessForRoot(await resolveSessionActor(req, myAgentId), sessionRoot);
+    if (access === "none") {
+      jsonError(res, "You don't have access to this session. Ask the owner to share it.", 403);
+      return true;
+    }
+    const ownerUser = sessionRoot.requestedByUserId
+      ? await findUserById(sessionRoot.requestedByUserId)
+      : null;
+    const owner = sessionRoot.requestedByUserId
+      ? {
+          id: sessionRoot.requestedByUserId,
+          name: ownerUser?.name ?? sessionRoot.requestedByUserId,
+        }
+      : null;
     const chain = await getRootTaskChain(parsed.params.rootTaskId);
     // Fixed query count regardless of chain length: one agents lookup and one
     // citations lookup for the whole chain (chunked past 500 ids).
@@ -363,7 +483,87 @@ export async function handleSessions(
       ...steering.get(task.id)!,
       citations: citations.get(task.id)!,
     });
-    getSession.respond(res, 200, { root: decorate(root), chain: chain.map(decorate) });
+    getSession.respond(res, 200, {
+      root: decorate(root),
+      chain: chain.map(decorate),
+      access,
+      owner,
+    });
+    return true;
+  }
+
+  if (getSessionShares.match(req.method, pathSegments)) {
+    const parsed = await getSessionShares.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const root = await getSessionRoot(parsed.params.rootTaskId);
+    if (!root) {
+      jsonError(res, "Root task not found", 404);
+      return true;
+    }
+    const access = await accessForRoot(await resolveSessionActor(req, myAgentId), root);
+    if (access === "none") {
+      jsonError(res, "You don't have access to this session. Ask the owner to share it.", 403);
+      return true;
+    }
+    getSessionShares.respond(
+      res,
+      200,
+      toSessionSharesState(await listActiveSessionShares(root.id)),
+    );
+    return true;
+  }
+
+  if (putSessionShares.match(req.method, pathSegments)) {
+    const parsed = await putSessionShares.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const auth = getRequestAuth(req);
+    const actor = await resolveSessionActor(req, myAgentId);
+    // Sharing is a dashboard action: a person, or the operator key itself.
+    const principal =
+      auth?.kind === "user"
+        ? ({ kind: "user", userId: auth.userId } as const)
+        : auth?.kind === "operator" && !myAgentId
+          ? ({ kind: "operator" } as const)
+          : null;
+    if (
+      !principal ||
+      !can({ principal, verb: "session.share", resource: { kind: "none" }, source: "http" }).allow
+    ) {
+      jsonError(res, "Only the session owner can share it", 403);
+      return true;
+    }
+    const root = await getSessionRoot(parsed.params.rootTaskId);
+    if (!root) {
+      jsonError(res, "Root task not found", 404);
+      return true;
+    }
+    if (!root.requestedByUserId) {
+      jsonError(res, "This session has no owner, so it is already open to everyone", 409);
+      return true;
+    }
+    if (actor.kind === "user" && actor.userId !== root.requestedByUserId) {
+      jsonError(res, "Only the session owner can share it", 403);
+      return true;
+    }
+    const userIds = [...new Set(parsed.body.users.map((user) => user.userId))];
+    if (userIds.length !== parsed.body.users.length) {
+      jsonError(res, "Each user may appear only once", 400);
+      return true;
+    }
+    for (const userId of userIds) {
+      if (!(await findUserById(userId))) {
+        jsonError(res, `Unknown user ${userId}`, 400);
+        return true;
+      }
+    }
+    const state = await setSessionShares(
+      root,
+      parsed.body,
+      actor.kind === "user" ? actor.userId : null,
+    );
+    // Committed: presence sockets re-check access, so a revoked viewer leaves.
+    realtimeBus.publish(sessionAccessTopic(root.id), null);
+    putSessionShares.respond(res, 200, state);
     return true;
   }
 

package/src/http/stats.ts

@@ -19,6 +19,7 @@ import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
 import { scheduleSummaryWithFavoriteSchema } from "./schedules";
+import { readableByFor, resolveSessionActor } from "./session-access";
 
 // ─── Response schemas ────────────────────────────────────────────────────────
 
@@ -222,11 +223,12 @@ export async function handleStats(
     if (!parsed) return true;
     const limit = parsed.query.limit ?? 100;
     const agentId = parsed.query.agentId;
+    const readableBy = readableByFor(await resolveSessionActor(req, myAgentId));
     let logs: AgentLog[] = [];
     if (agentId) {
-      logs = (await getLogsByAgentId(agentId)).slice(0, limit);
+      logs = (await getLogsByAgentId(agentId, readableBy)).slice(0, limit);
     } else {
-      logs = await getAllLogs(limit);
+      logs = await getAllLogs(limit, readableBy);
     }
     listLogs.respond(res, 200, { logs });
     return true;
@@ -306,7 +308,9 @@ export async function handleStats(
   }
 
   if (getConcurrentContextRoute.match(req.method, pathSegments)) {
-    const context = await getConcurrentContext();
+    const context = await getConcurrentContext(
+      readableByFor(await resolveSessionActor(req, myAgentId)),
+    );
     getConcurrentContextRoute.respond(res, 200, context);
     return true;
   }