fix(webapp,sdk): narrow session read tokens by direction and make .in reads secret-key only

Session public tokens can now be narrowed to one stream with
`read:sessions:{id}:out`, and reading a session's `.in` channel now
requires a secret key. The dashboard agent's browser token uses the
narrowed scope.

Mono-RevId: 1214e6dd60256c7f1323e891580c16d500c8fd9a

Author: carderne

.changeset/session-output-scope.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Session public tokens can now be narrowed to one stream: `read: { sessions: "chat_123:out" }` grants read access to that session's `.out` channel only, without access to the session record or its other channels.

.server-changes/session-in-channel-reads-require-secret-key.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: breaking
+---
+
+Reading a session's `.in` channel (`GET /realtime/v1/sessions/{id}/in` and `/in/records`) now requires a secret key. Public tokens, including `read:sessions:{id}`, get a 403; they can still read `.out` and append to `.in`.

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

@@ -174,7 +174,9 @@ const { action } = createActionApiRoute(
     try {
       if (body.externalId && !isSafeSessionExternalId(body.externalId)) {
         return json(
-          { error: `externalId cannot contain "${SESSION_CHANNEL_SCOPE_INFIX}"` },
+          {
+            error: `externalId cannot contain "${SESSION_CHANNEL_SCOPE_INFIX}" or end in ":out" or ":in"`,
+          },
           { status: 422 }
         );
       }

apps/webapp/app/routes/realtime.v1.sessions.$session.$io.records.ts

@@ -2,6 +2,7 @@ import { json } from "@remix-run/server-runtime";
 import { z } from "zod";
 import { $replica } from "~/db.server";
 import { S2RealtimeStreams } from "~/services/realtime/s2realtimeStreams.server";
+import { sessionStreamResources } from "~/services/realtime/sessionChannels.server";
 import {
   canonicalSessionAddressingKey,
   isSessionFriendlyIdForm,
@@ -59,20 +60,32 @@ export const loader = createLoaderApiRoute(
     authorization: {
       action: "read",
       // Multi-key: the channel is addressable by the URL key, the row's
-      // friendlyId, and (if set) externalId. Type-level `read:sessions`
-      // matches any of them; `read:all` / `admin` bypass via the JWT
-      // ability's wildcard branches.
-      resource: ({ row, addressingKey }) => {
+      // friendlyId, and (if set) externalId, each also in its direction-folded
+      // form (`{key}:out`) so a token narrowed to one direction matches. Type-level
+      // `read:sessions` matches any of them; `read:all` / `admin` bypass via the
+      // JWT ability's wildcard branches.
+      resource: ({ row, addressingKey }, params) => {
         const ids = new Set<string>([addressingKey]);
         if (row) {
           ids.add(row.friendlyId);
           if (row.externalId) ids.add(row.externalId);
         }
-        return anyResource([...ids].map((id) => ({ type: "sessions", id })));
+        return anyResource(sessionStreamResources(params.io, ids));
       },
     },
   },
   async ({ params, authentication, resource, searchParams }) => {
+    // `.in` is the client→agent channel: the agent run reads it, clients only append. A
+    // public token is a browser-held credential, and `.in` records can carry data meant
+    // for the agent alone (a server-side proxy may inject per-turn credentials), so
+    // reading `.in` requires the secret key. `.out` is the only public read.
+    if (params.io === "in" && authentication.type !== "PRIVATE") {
+      return json(
+        { ok: false, error: "Reading the in channel requires secret key authentication" },
+        { status: 403 }
+      );
+    }
+
     const realtimeStream = getRealtimeStreamInstance(authentication.environment, "v2", {
       session: resource.row,
       organization: resource.row ? null : authentication.environment.organization,

apps/webapp/app/routes/realtime.v1.sessions.$session.$io.ts

@@ -3,6 +3,7 @@ import { STREAM_START_HEADER } from "@trigger.dev/core/v3";
 import { z } from "zod";
 import { getRequestAbortSignal } from "~/services/httpAsyncStorage.server";
 import { S2RealtimeStreams } from "~/services/realtime/s2realtimeStreams.server";
+import { sessionStreamResources } from "~/services/realtime/sessionChannels.server";
 import {
   canonicalSessionAddressingKey,
   isSessionFriendlyIdForm,
@@ -122,20 +123,31 @@ const loader = createLoaderApiRoute(
     authorization: {
       action: "read",
       // Multi-key: the channel is addressable by the URL key, the row's
-      // friendlyId, and (if set) externalId. Type-level `read:sessions`
-      // matches any of them; `read:all` / `admin` bypass via the JWT
-      // ability's wildcard branches.
-      resource: ({ row, addressingKey }) => {
+      // friendlyId, and (if set) externalId, each also in its direction-folded
+      // form (`{key}:out`) so a token narrowed to one direction matches. Type-level
+      // `read:sessions` matches any of them; `read:all` / `admin` bypass via the
+      // JWT ability's wildcard branches.
+      resource: ({ row, addressingKey }, params) => {
         const ids = new Set<string>([addressingKey]);
         if (row) {
           ids.add(row.friendlyId);
           if (row.externalId) ids.add(row.externalId);
         }
-        return anyResource([...ids].map((id) => ({ type: "sessions", id })));
+        return anyResource(sessionStreamResources(params.io, ids));
       },
     },
   },
   async ({ params, request, authentication, resource }) => {
+    // `.in` is the client→agent channel: the agent run reads it, clients only append. A
+    // public token is a browser-held credential, and `.in` records can carry data meant
+    // for the agent alone (a server-side proxy may inject per-turn credentials), so
+    // reading `.in` requires the secret key. `.out` is the only public read.
+    if (params.io === "in" && authentication.type !== "PRIVATE") {
+      return new Response("Reading the in channel requires secret key authentication", {
+        status: 403,
+      });
+    }
+
     // Same no-row fallback as PUT above.
     const realtimeStream = getRealtimeStreamInstance(authentication.environment, "v2", {
       session: resource.row,

apps/webapp/app/routes/realtime.v1.sessions.$session.channels.$channel.$io.records.ts

@@ -47,7 +47,7 @@ export const loader = createLoaderApiRoute(
           ids.add(row.friendlyId);
           if (row.externalId) ids.add(row.externalId);
         }
-        return anyResource(sessionChannelResources(params.channel, ids));
+        return anyResource(sessionChannelResources(params.channel, ids, params.io));
       },
     },
   },

apps/webapp/app/routes/realtime.v1.sessions.$session.channels.$channel.$io.ts

@@ -104,7 +104,7 @@ const loader = createLoaderApiRoute(
           ids.add(row.friendlyId);
           if (row.externalId) ids.add(row.externalId);
         }
-        return anyResource(sessionChannelResources(params.channel, ids));
+        return anyResource(sessionChannelResources(params.channel, ids, params.io));
       },
     },
   },

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.ts

@@ -199,7 +199,18 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     // Null is not an empty transcript: the chat is deleted or another org's, and a 200 would
     // read as a real, empty chat.
     if (messages === null) return json({ error: "Chat not found" }, { status: 404 });
-    return json({ messages, session });
+    // The stored token is the agent run's own (bare `read:sessions` plus run scopes), kept for
+    // the agent's replay. The browser gets a token minted for it, narrowed like every other
+    // dashboard-agent issuance; a failed mint degrades to a non-streaming transcript.
+    let browserSession: typeof session = null;
+    if (session && isDashboardAgentConfigured()) {
+      try {
+        browserSession = { ...session, publicAccessToken: await mintDashboardAgentToken(chatId) };
+      } catch (error) {
+        logger.error("Dashboard agent chat read could not mint a browser token", { chatId, error });
+      }
+    }
+    return json({ messages, session: browserSession });
   }
 
   const chats = await listChats(dashboardAgentDb, {
@@ -638,7 +649,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
         // run's `basePayload.metadata` verbatim, so without the pick a client could inject
         // any server-owned field into the agent's first turn (a `repoSnapshot.tarballUrl`
         // is fetched and extracted on the worker).
-        const { publicAccessToken } = await startDashboardAgentSession({
+        await startDashboardAgentSession({
           chatId,
           clientData: {
             ...pickAgentClientMetadata(clientData),
@@ -656,14 +667,24 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
             ...dashboardAgentEnvironmentAddress(runtimeEnv),
           },
         });
-        return json({ publicAccessToken });
       } catch (error) {
         logger.error("Failed to start dashboard agent session", { chatId, error });
         return json(
           { error: "The dashboard agent couldn't start. Please try again in a moment." },
           { status: 500 }
         );
       }
+
+      try {
+        return json({ publicAccessToken: await mintDashboardAgentToken(chatId) });
+      } catch (error) {
+        // The session is live and idles out on its own if the client never comes back.
+        logger.error("Dashboard agent chat resumed but its token mint failed", { chatId, error });
+        return json(
+          { error: "The dashboard agent started but couldn't be opened. Try opening it again." },
+          { status: 500 }
+        );
+      }
     }
 
     case "token": {

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

@@ -111,25 +111,30 @@ export function dashboardAgentTriggerConfig(): {
   };
 }
 
+// The SDK's start action also mints a `read:sessions` token; it is discarded here so every
+// browser token comes from `mintDashboardAgentToken`.
 export async function startDashboardAgentSession(params: {
   chatId: string;
   clientData?: Record<string, unknown>;
-}): Promise<{ publicAccessToken: string }> {
+}): Promise<void> {
   const config = dashboardAgentConfig();
   if (!config) throw new Error("DASHBOARD_AGENT_SECRET_KEY is not set");
   const startSession = chat.createStartSessionAction(TASK_ID, {
     apiClient: config,
     triggerConfig: dashboardAgentTriggerConfig(),
   });
-  return startSession({ chatId: params.chatId, clientData: params.clientData });
+  await startSession({ chatId: params.chatId, clientData: params.clientData });
 }
 
+// Read is narrowed to the `.out` stream (`read:sessions:{chatId}:out`): `.in` records carry
+// the delegated user token the `in` proxy injects, and the session row carries the trigger
+// config, so the browser gets neither.
 export async function mintDashboardAgentToken(chatId: string): Promise<string> {
   const config = dashboardAgentConfig();
   if (!config) throw new Error("DASHBOARD_AGENT_SECRET_KEY is not set");
   const client = new TriggerClient(config);
   return client.auth.createPublicToken({
-    scopes: { read: { sessions: chatId }, write: { sessions: chatId } },
+    scopes: { read: { sessions: `${chatId}:out` }, write: { sessions: chatId } },
     expirationTime: "1h",
   });
 }

apps/webapp/app/services/realtime/sessionChannels.server.test.ts

@@ -1,8 +1,10 @@
+import { buildJwtAbility } from "@trigger.dev/plugins";
 import { describe, expect, it } from "vitest";
 import {
   isSafeSessionExternalId,
   SESSION_CHANNEL_SCOPE_INFIX,
   sessionChannelResources,
+  sessionStreamResources,
 } from "./sessionChannels.server";
 
 describe("isSafeSessionExternalId", () => {
@@ -14,22 +16,105 @@ describe("isSafeSessionExternalId", () => {
     expect(isSafeSessionExternalId("a:channels:b:channels:c")).toBe(false);
   });
 
+  it("rejects an externalId that collides with the direction fold", () => {
+    expect(isSafeSessionExternalId("session_abc:out")).toBe(false);
+    expect(isSafeSessionExternalId("session_abc:in")).toBe(false);
+    expect(isSafeSessionExternalId(":out")).toBe(false);
+  });
+
   it("allows normal externalIds, including single colons that are not the fold infix", () => {
     expect(isSafeSessionExternalId("chat-3c3a1756-a49a-4c78-891a-51f78596c984")).toBe(true);
     expect(isSafeSessionExternalId("user:123")).toBe(true);
     expect(isSafeSessionExternalId("org:abc:chat:1")).toBe(true);
     expect(isSafeSessionExternalId("channels")).toBe(true);
     expect(isSafeSessionExternalId("plain")).toBe(true);
+    // Only the exact `:out` / `:in` suffix folds; these merely contain or end with the word.
+    expect(isSafeSessionExternalId("checkout")).toBe(true);
+    expect(isSafeSessionExternalId("login")).toBe(true);
+    expect(isSafeSessionExternalId("chat:out:1")).toBe(true);
   });
 
-  it("keeps a channel-scoped token's folded id from equaling any allowed session's bare key", () => {
-    const channel = "screencast";
-    const foldedIds = sessionChannelResources(channel, ["session_abc"])
+  it("keeps a narrowed token's folded id from equaling any allowed session's bare key", () => {
+    const foldedIds = [
+      ...sessionChannelResources("screencast", ["session_abc"], "out"),
+      ...sessionStreamResources("out", ["session_abc"]),
+      ...sessionStreamResources("in", ["session_abc"]),
+    ]
       .map((r) => r.id)
-      .filter((id) => id.includes(SESSION_CHANNEL_SCOPE_INFIX));
+      .filter((id) => id !== "session_abc");
 
+    expect(foldedIds.length).toBe(4);
     for (const foldedId of foldedIds) {
       expect(isSafeSessionExternalId(foldedId)).toBe(false);
     }
   });
 });
+
+describe("sessionStreamResources", () => {
+  const keys = ["chat_abc", "session_123"];
+
+  it("lets read:sessions:{id}:out read .out but not .in", () => {
+    const ability = buildJwtAbility(["read:sessions:chat_abc:out"]);
+    expect(ability.can("read", sessionStreamResources("out", keys))).toBe(true);
+    expect(ability.can("read", sessionStreamResources("in", keys))).toBe(false);
+  });
+
+  it("keeps read:sessions:{id} matching both streams", () => {
+    const ability = buildJwtAbility(["read:sessions:chat_abc"]);
+    expect(ability.can("read", sessionStreamResources("out", keys))).toBe(true);
+    expect(ability.can("read", sessionStreamResources("in", keys))).toBe(true);
+  });
+
+  it("never authorizes a legacy externalId that equals another session's folded id", () => {
+    // A row created before the direction fold existed may carry externalId `chat_abc:out`.
+    // A token narrowed to session `chat_abc`'s .out stream must not read that other session.
+    const narrowed = buildJwtAbility(["read:sessions:chat_abc:out"]);
+    const legacyKeys = ["chat_abc:out", "session_legacy"];
+    expect(narrowed.can("read", sessionStreamResources("out", legacyKeys))).toBe(false);
+    expect(narrowed.can("read", sessionStreamResources("in", legacyKeys))).toBe(false);
+    expect(narrowed.can("read", sessionChannelResources("tools", legacyKeys, "out"))).toBe(false);
+    // Same for a pre-guard `:channels:` externalId against a channel-narrowed token.
+    const channel = buildJwtAbility(["read:sessions:chat_abc:channels:tools"]);
+    expect(channel.can("read", sessionStreamResources("out", ["chat_abc:channels:tools"]))).toBe(
+      false
+    );
+    // The legacy row stays reachable by friendlyId and by a type-level scope.
+    expect(
+      buildJwtAbility(["read:sessions:session_legacy"]).can(
+        "read",
+        sessionStreamResources("out", legacyKeys)
+      )
+    ).toBe(true);
+    expect(
+      buildJwtAbility(["read:sessions"]).can("read", sessionStreamResources("out", legacyKeys))
+    ).toBe(true);
+    // An unsafe key contributes no resource at all.
+    expect(sessionStreamResources("out", ["chat_abc:out"])).toEqual([]);
+  });
+
+  it("does not let a direction-scoped token match the bare session", () => {
+    const ability = buildJwtAbility(["read:sessions:chat_abc:out"]);
+    expect(ability.can("read", { type: "sessions", id: "chat_abc" })).toBe(false);
+    expect(ability.can("read", { type: "sessions", id: "session_123" })).toBe(false);
+  });
+});
+
+describe("sessionChannelResources", () => {
+  const keys = ["chat_abc"];
+
+  it("lets a channel token read either direction and a channel:out token only .out", () => {
+    const channelWide = buildJwtAbility(["read:sessions:chat_abc:channels:tools"]);
+    expect(channelWide.can("read", sessionChannelResources("tools", keys, "out"))).toBe(true);
+    expect(channelWide.can("read", sessionChannelResources("tools", keys, "in"))).toBe(true);
+
+    const outOnly = buildJwtAbility(["read:sessions:chat_abc:channels:tools:out"]);
+    expect(outOnly.can("read", sessionChannelResources("tools", keys, "out"))).toBe(true);
+    expect(outOnly.can("read", sessionChannelResources("tools", keys, "in"))).toBe(false);
+    expect(outOnly.can("read", sessionChannelResources("other", keys, "out"))).toBe(false);
+  });
+
+  it("does not let a default-stream :out token read a named channel", () => {
+    const ability = buildJwtAbility(["read:sessions:chat_abc:out"]);
+    expect(ability.can("read", sessionChannelResources("tools", keys, "out"))).toBe(false);
+  });
+});