fix(webapp): require session-write and task-trigger access

Session creation requires both session-write and task-trigger
permissions. Cached sessions are checked against their stored task
before refreshing their configuration or starting a run. The API key
scope preview now displays session and tagged-run access.

Mono-RevId: a138ef996f92a325c335c061f1b46e7f67bbca4a

Author: carderne

.server-changes/session-create-permissions.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: breaking
+---
+
+Creating or resuming a session with `POST /api/v1/sessions` now requires both session-write and task-trigger permissions. Scoped keys and public tokens must grant `write:sessions` (or access to the target session) and permission to trigger its task.

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.apikeys/route.tsx

@@ -889,7 +889,16 @@ const API_KEY_EXPIRATIONS = [
   { value: "never", label: "Never" },
 ];
 
-type CapId = "tasks" | "runs" | "batches" | "queues" | "deployments" | "branches" | "envvars";
+type CapId =
+  | "tasks"
+  | "runs"
+  | "batches"
+  | "queues"
+  | "sessions"
+  | "tags"
+  | "deployments"
+  | "branches"
+  | "envvars";
 
 // Capability rows shown in the scope pane, in a fixed order so two presets read
 // as a diff of the same list rather than a reshuffled one.
@@ -898,6 +907,8 @@ const SCOPE_CAPABILITIES: [CapId, string][] = [
   ["runs", "Runs"],
   ["batches", "Batches"],
   ["queues", "Queues"],
+  ["sessions", "Sessions (all tasks)"],
+  ["tags", "Tagged runs"],
   ["deployments", "Deployments"],
   ["branches", "Preview branches"],
   ["envvars", "Environment variables"],
@@ -934,6 +945,9 @@ const SCOPE_CAPABILITY_BY_SCOPE: Record<string, [CapId, number]> = {
   "write:batch": ["batches", 2],
   "read:queues": ["queues", 1],
   "write:queues": ["queues", 2],
+  "read:sessions": ["sessions", 1],
+  "write:sessions": ["sessions", 2],
+  "read:tags": ["tags", 1],
   "read:deployments": ["deployments", 1],
   "write:deployments": ["deployments", 2],
   "write:branches": ["branches", 3],

apps/webapp/app/routes/api.v1.sessions.ts

@@ -7,7 +7,7 @@ import {
   type SessionItem,
   type SessionStatus,
 } from "@trigger.dev/core/v3";
-import type { Session } from "@trigger.dev/database";
+import type { Prisma, Session } from "@trigger.dev/database";
 import { $replica, prisma, type PrismaClient } from "~/db.server";
 import { clickhouseFactory } from "~/services/clickhouse/clickhouseFactoryInstance.server";
 import { logger } from "~/services/logger.server";
@@ -32,7 +32,10 @@ import {
   createLoaderApiRoute,
   everyResource,
 } from "~/services/routeBuilders/apiBuilder.server";
-import { recordSessionCreateAuthorization } from "~/services/sessionAuthorizationTelemetry.server";
+import {
+  recordSessionCreateAuthorization,
+  sessionCreateAuthorizationOutcome,
+} from "~/services/sessionAuthorizationTelemetry.server";
 import { ServiceValidationError } from "~/v3/services/common.server";
 import { runStore } from "~/v3/runStore.server";
 
@@ -148,26 +151,15 @@ const { action } = createActionApiRoute(
     // browser uses thereafter against `.in/append`, `.out` SSE,
     // `end-and-continue`, etc.
     //
-    // JWT is allowed when the caller holds an explicit `write:sessions` /
-    // `admin` super-scope plus a `tasks:<taskIdentifier>` scope — gates
-    // server-side surfaces like the cli-v3 MCP from creating sessions on
-    // behalf of the developer without weakening the browser model.
+    // Creating a session requires session-write AND task-trigger permissions.
     allowJWT: true,
     authorization: {
-      // Per-task scoping via `body.taskIdentifier` (action-route resource
-      // callbacks receive the parsed body as the 4th arg — see
-      // `apiBuilder.server.ts:710`). A JWT scoped only to `write:tasks:foo`
-      // can only create sessions whose `taskIdentifier` is `"foo"`.
-      //
-      // Multi-key resource: pre-RBAC this route had a `superScopes:
-      // ["write:sessions", "admin"]` whitelist; post-RBAC the equivalent
-      // is the `{ type: "sessions" }` element below — a `write:sessions`
-      // JWT (no id) matches it directly, deliberately bypassing the
-      // per-task check exactly as before. `admin` / `write:all` bypass
-      // via the JWT ability's wildcard branches.
-      action: "write",
-      resource: (_params, _searchParams, _headers, body) =>
-        anyResource([{ type: "tasks", id: body.taskIdentifier }, { type: "sessions" }]),
+      // Session-write is checked below after resolving alternate session IDs.
+      action: "trigger",
+      resource: (_params, _searchParams, _headers, body) => ({
+        type: "tasks",
+        id: body.taskIdentifier,
+      }),
     },
     corsStrategy: "all",
   },
@@ -182,8 +174,25 @@ const { action } = createActionApiRoute(
         );
       }
 
-      // Idempotent on (env, externalId): two concurrent POSTs converge to the same row, and
-      // `triggerConfig` is refreshed on the cached path so a redeployed config reaches the next run.
+      const sessionIds = body.externalId ? [body.externalId] : [];
+      if (body.externalId && !ability.can("write", { type: "sessions", id: body.externalId })) {
+        const existing = await prisma.session.findFirst({
+          where: {
+            runtimeEnvironmentId: authentication.environment.id,
+            externalId: body.externalId,
+          },
+          select: { friendlyId: true },
+        });
+        if (existing) sessionIds.push(existing.friendlyId);
+      }
+      if (
+        sessionCreateAuthorizationOutcome(ability, body.taskIdentifier, sessionIds) !==
+        "both_allowed"
+      ) {
+        return json({ error: "Unauthorized" }, { status: 403 });
+      }
+
+      // Defer cached config changes until the stored task has been authorized.
       const { session, isCached } = await findOrCreateSession({
         environment: authentication.environment,
         externalId: body.externalId,
@@ -193,6 +202,7 @@ const { action } = createActionApiRoute(
         tags: body.tags,
         metadata: body.metadata as Record<string, unknown> | undefined,
         expiresAt: body.expiresAt,
+        refreshTriggerConfig: false,
       });
 
       // Reject create on a closed session. The upsert path will return
@@ -220,6 +230,26 @@ const { action } = createActionApiRoute(
       }
 
       recordSessionCreateAuthorization(ability, session, request, authentication.environment);
+      if (
+        sessionCreateAuthorizationOutcome(
+          ability,
+          session.taskIdentifier,
+          [session.friendlyId, session.externalId].filter((id): id is string => !!id)
+        ) !== "both_allowed"
+      ) {
+        return json({ error: "Unauthorized" }, { status: 403 });
+      }
+
+      if (isCached) {
+        Object.assign(
+          session,
+          await prisma.session.update({
+            where: { id: session.id },
+            data: { triggerConfig: body.triggerConfig as unknown as Prisma.InputJsonValue },
+            select: { triggerConfig: true, updatedAt: true },
+          })
+        );
+      }
 
       // Session is task-bound — every session has a live run by
       // construction. `ensureRunForSession` is idempotent: on the

apps/webapp/app/services/sessionAuthorizationTelemetry.server.test.ts

@@ -29,6 +29,22 @@ describe("session creation authorization observation", () => {
     ).toBe(expected);
   });
 
+  it.each(["chat-1", "session_123"])(
+    "requires a matching task even with write access to session %s",
+    (sessionId) => {
+      const ability = withActionAliases(
+        buildJwtAbility([`write:sessions:${sessionId}`, "trigger:tasks:chat"])
+      );
+      expect(sessionCreateAuthorizationOutcome(ability, "chat", [sessionId])).toBe("both_allowed");
+      expect(sessionCreateAuthorizationOutcome(ability, "other", [sessionId])).toBe(
+        "missing_task_trigger"
+      );
+      expect(sessionCreateAuthorizationOutcome(ability, "chat", ["other-session"])).toBe(
+        "missing_session_write"
+      );
+    }
+  );
+
   it("attributes only would-deny events without exporting the credential or task", async () => {
     const exporter = new InMemorySpanExporter();
     const provider = new BasicTracerProvider({

apps/webapp/app/services/sessionAuthorizationTelemetry.server.ts

@@ -13,8 +13,14 @@ const checks = singleton("sessionCreateAuthorizationChecks", () =>
   })
 );
 
-export function sessionCreateAuthorizationOutcome(ability: RbacAbility, taskIdentifier: string) {
-  const sessionWrite = ability.can("write", { type: "sessions" });
+export function sessionCreateAuthorizationOutcome(
+  ability: RbacAbility,
+  taskIdentifier: string,
+  sessionIds: string[] = []
+) {
+  const sessionWrite =
+    ability.can("write", { type: "sessions" }) ||
+    sessionIds.some((id) => ability.can("write", { type: "sessions", id }));
   const taskTrigger = ability.can("trigger", { type: "tasks", id: taskIdentifier });
 
   if (sessionWrite && taskTrigger) return "both_allowed";
@@ -24,7 +30,7 @@ export function sessionCreateAuthorizationOutcome(ability: RbacAbility, taskIden
 
 export function recordSessionCreateAuthorization(
   ability: RbacAbility,
-  session: { taskIdentifier: string },
+  session: { taskIdentifier: string; friendlyId?: string; externalId?: string | null },
   request: Request,
   environment: Pick<AuthenticatedEnvironment, "id" | "organizationId" | "projectId" | "type">
 ) {
@@ -42,7 +48,11 @@ export function recordSessionCreateAuthorization(
         : "unknown";
 
   try {
-    const outcome = sessionCreateAuthorizationOutcome(ability, session.taskIdentifier);
+    const outcome = sessionCreateAuthorizationOutcome(
+      ability,
+      session.taskIdentifier,
+      [session.friendlyId, session.externalId].filter((id): id is string => !!id)
+    );
     checks.add(1, { credential_kind: credentialKind, outcome });
     if (outcome === "both_allowed") return;
 

apps/webapp/test/auth-api.e2e.full.test.ts

@@ -2555,12 +2555,11 @@ describe("API", () => {
 
     // ---- Create session: POST /api/v1/sessions
     //
-    // Resource: [{ type: "tasks", id: body.taskIdentifier }, { type: "sessions" }]
-    // Old superScopes: ["write:sessions", "admin"]
+    // Session-write AND permission to trigger the requested and resolved tasks.
     describe("Create session — POST /api/v1/sessions", () => {
       const path = "/api/v1/sessions";
 
-      const post = async (jwt: string, taskIdentifier: string) =>
+      const post = async (jwt: string, taskIdentifier: string, externalId?: string) =>
         getTestServer().webapp.fetch(path, {
           method: "POST",
           headers: {
@@ -2570,6 +2569,7 @@ describe("API", () => {
           body: JSON.stringify({
             type: "chat.agent",
             taskIdentifier,
+            externalId,
             triggerConfig: { basePayload: {} },
           }),
         });
@@ -2581,15 +2581,11 @@ describe("API", () => {
           expirationTime: "15m",
         });
 
-      it("write:tasks:foo matching body: auth passes", async () => {
+      it("write:tasks:foo without session-write: 403", async () => {
         const seed = await seedTestEnvironment(getTestServer().prisma);
         const jwt = await mintJwt(seed.apiKey, seed.environment.id, ["write:tasks:foo"]);
         const res = await post(jwt, "foo");
-        // Body validation / handler can fail later (404 if task is
-        // missing, 400 for invalid body) — we only care that auth
-        // didn't reject.
-        expect(res.status).not.toBe(401);
-        expect(res.status).not.toBe(403);
+        expect(res.status).toBe(403);
       });
 
       it("write:tasks:bar mismatching body: 403", async () => {
@@ -2599,14 +2595,65 @@ describe("API", () => {
         expect(res.status).toBe(403);
       });
 
-      it("write:sessions: auth passes (was a superScope)", async () => {
+      it("write:sessions without task-trigger: 403", async () => {
         const seed = await seedTestEnvironment(getTestServer().prisma);
         const jwt = await mintJwt(seed.apiKey, seed.environment.id, ["write:sessions"]);
         const res = await post(jwt, "foo");
+        expect(res.status).toBe(403);
+      });
+
+      it("session-write and matching task-trigger: auth passes", async () => {
+        const seed = await seedTestEnvironment(getTestServer().prisma);
+        const jwt = await mintJwt(seed.apiKey, seed.environment.id, [
+          "write:sessions",
+          "trigger:tasks:foo",
+        ]);
+        const res = await post(jwt, "foo");
         expect(res.status).not.toBe(401);
         expect(res.status).not.toBe(403);
       });
 
+      it.each(["foo", "other-task"])(
+        "accepts a cached session's friendly-ID grant only with access to its task %s",
+        async (taskIdentifier) => {
+          const server = getTestServer();
+          const seed = await seedTestEnvironment(server.prisma);
+          const session = await seedTestApiSession(server.prisma, seed.environment, {
+            taskIdentifier,
+          });
+          const jwt = await mintJwt(seed.apiKey, seed.environment.id, [
+            `write:sessions:${session.friendlyId}`,
+            "trigger:tasks:foo",
+          ]);
+          const res = await post(jwt, "foo", session.externalId!);
+          if (taskIdentifier === "foo") {
+            expect(res.status).not.toBe(401);
+            expect(res.status).not.toBe(403);
+          } else {
+            expect(res.status).toBe(403);
+            const unchanged = await server.prisma.session.findFirst({ where: { id: session.id } });
+            expect(unchanged?.triggerConfig).toEqual(session.triggerConfig);
+          }
+        }
+      );
+
+      it("checks the cached task before changing its config or triggering it", async () => {
+        const server = getTestServer();
+        const seed = await seedTestEnvironment(server.prisma);
+        const session = await seedTestApiSession(server.prisma, seed.environment, {
+          taskIdentifier: "other-task",
+        });
+        const jwt = await mintJwt(seed.apiKey, seed.environment.id, [
+          "write:sessions",
+          "trigger:tasks:foo",
+        ]);
+        const res = await post(jwt, "foo", session.externalId!);
+        expect(res.status).toBe(403);
+        const unchanged = await server.prisma.session.findFirst({ where: { id: session.id } });
+        expect(unchanged?.triggerConfig).toEqual(session.triggerConfig);
+        expect(unchanged?.currentRunId).toBe(session.currentRunId);
+      });
+
       it("write:all: auth passes", async () => {
         const seed = await seedTestEnvironment(getTestServer().prisma);
         const jwt = await mintJwt(seed.apiKey, seed.environment.id, ["write:all"]);