Sessions routes: post-RBAC apiBuilder shape + preserve superScopes semantics

The 6 session routes merged via PR #3417 were authored against the
pre-RBAC apiBuilder API: `authorization.resource` returned shapes like
`{ sessions: 'abc' }`, with a parallel `superScopes: [...]` whitelist
for broad-scope bypass. Post-TRI-8719, that shape doesn't typecheck and
`superScopes` is dead code.

Convert each resource callback to the canonical `{ type, id? }` shape.
For the two routes whose resource type is `tasks` but whose old
superScopes included `<action>:sessions` (list and create), use a
multi-key array `[{ type: 'tasks', id }, { type: 'sessions' }]` so a
JWT scoped `<action>:sessions` (no id) still passes — preserving the
exact allow-set the old superScopes mechanism granted. `*:all` and
`admin*` were already handled by the JWT ability's wildcard branches.

Drop the now-dead `superScopes` field from all 9 entries.

Adds e2e coverage in `auth-api.e2e.full.test.ts` (34 new tests, ~9
sub-describes) that locks in: per-task narrowing, `<action>:sessions`
type-only equivalence to the old superScope, `*:all` and `admin*`
bypass, wrong-action / wrong-id rejection. Plus a new
`seedTestApiSession` helper for inserting Session rows via Prisma —
distinct from the existing `seedTestSession` (cookie-session helper
for dashboard tests).

Author: matt-aitken

apps/webapp/app/routes/api.v1.sessions.$session.close.ts

@@ -25,8 +25,7 @@ const { action, loader } = createActionApiRoute(
     corsStrategy: "all",
     authorization: {
       action: "admin",
-      resource: (params) => ({ sessions: params.session }),
-      superScopes: ["admin:sessions", "admin:all", "admin"],
+      resource: (params) => ({ type: "sessions", id: params.session }),
     },
   },
   async ({ authentication, params, body }) => {

apps/webapp/app/routes/api.v1.sessions.$session.end-and-continue.ts

@@ -42,15 +42,18 @@ const { action, loader } = createActionApiRoute(
       resolveSessionByIdOrExternalId($replica, auth.environment.id, params.session),
     authorization: {
       action: "write",
+      // Multi-key: the session is addressable by URL param, friendlyId,
+      // and externalId — a JWT scoped to any of them grants access.
+      // Type-level `write:sessions` (no id) also matches; `write:all` /
+      // `admin` bypass via the JWT ability's wildcard branches.
       resource: (params, _, __, ___, session) => {
         const ids = new Set<string>([params.session]);
         if (session) {
           ids.add(session.friendlyId);
           if (session.externalId) ids.add(session.externalId);
         }
-        return { sessions: [...ids] };
+        return [...ids].map((id) => ({ type: "sessions", id }));
       },
-      superScopes: ["write:sessions", "write:all", "admin"],
     },
   },
   async ({ authentication, params, body, resource: session }) => {

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

@@ -29,8 +29,17 @@ export const loader = createLoaderApiRoute(
     },
     authorization: {
       action: "read",
-      resource: (session) => ({ sessions: [session.friendlyId, session.externalId ?? ""] }),
-      superScopes: ["read:sessions", "read:all", "admin"],
+      // Multi-key: a session is addressable by both friendlyId and (when
+      // set) externalId. A JWT scoped to either id grants access; type-
+      // level `read:sessions` (no id) matches both elements; `read:all`
+      // / `admin` bypass via the JWT ability's wildcard branches.
+      resource: (session) =>
+        session.externalId
+          ? [
+              { type: "sessions", id: session.friendlyId },
+              { type: "sessions", id: session.externalId },
+            ]
+          : { type: "sessions", id: session.friendlyId },
     },
   },
   async ({ resource: session }) => {
@@ -50,8 +59,7 @@ const { action } = createActionApiRoute(
     corsStrategy: "all",
     authorization: {
       action: "admin",
-      resource: (params) => ({ sessions: params.session }),
-      superScopes: ["admin:sessions", "admin:all", "admin"],
+      resource: (params) => ({ type: "sessions", id: params.session }),
     },
   },
   async ({ authentication, params, body }) => {

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

@@ -37,8 +37,21 @@ export const loader = createLoaderApiRoute(
     corsStrategy: "all",
     authorization: {
       action: "read",
-      resource: (_, __, searchParams) => ({ tasks: searchParams["filter[taskIdentifier]"] }),
-      superScopes: ["read:sessions", "read:all", "admin"],
+      // Multi-key resource preserves the pre-RBAC superScope semantics:
+      //   - Per-task scoping via `read:tasks:<id>` matches a task element
+      //   - Type-level `read:sessions` (the old superScope) matches the
+      //     sessions element (collection-level — no id)
+      //   - `read:all` / `admin` bypass via the JWT ability's wildcard branches
+      // The taskIdentifier filter accepts a string or an array; expand to
+      // one resource per task id so any per-task-scoped JWT among them
+      // grants access (the array gets OR semantics).
+      resource: (_, __, searchParams) => {
+        const taskFilter = asArray(searchParams["filter[taskIdentifier]"]) ?? [];
+        return [
+          ...taskFilter.map((id) => ({ type: "tasks" as const, id })),
+          { type: "sessions" as const },
+        ];
+      },
     },
     findResource: async () => 1,
   },
@@ -113,21 +126,19 @@ const { action } = createActionApiRoute(
       // 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"`. Broad
-      // callers (cli-v3 MCP, customer servers wrapping their own auth)
-      // hold the `write:sessions` super-scope and bypass the per-task
-      // check entirely.
+      // can only create sessions whose `taskIdentifier` is `"foo"`.
       //
-      // Note: the auth check is OR across resource types, so listing both
-      // `sessions` and `tasks` here would let a `write:sessions`-scoped
-      // JWT pass for *any* task — defeating the per-task narrowing. Keep
-      // it task-only and let the super-scope path handle session-level
-      // wildcard access.
+      // 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) => ({
-        tasks: body.taskIdentifier,
-      }),
-      superScopes: ["write:sessions", "admin"],
+      resource: (_params, _searchParams, _headers, body) => [
+        { type: "tasks", id: body.taskIdentifier },
+        { type: "sessions" },
+      ],
     },
     corsStrategy: "all",
   },

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

@@ -49,15 +49,16 @@ const { action, loader } = createActionApiRoute(
       action: "write",
       // Authorize against the union of the URL form, friendlyId, and
       // externalId so a JWT scoped to any form authorizes any URL.
+      // Type-level `write:sessions` (no id) also matches; `write:all` /
+      // `admin` bypass via the JWT ability's wildcard branches.
       resource: (params, _, __, ___, session) => {
         const ids = new Set<string>([params.session]);
         if (session) {
           ids.add(session.friendlyId);
           if (session.externalId) ids.add(session.externalId);
         }
-        return { sessions: [...ids] };
+        return [...ids].map((id) => ({ type: "sessions", id }));
       },
-      superScopes: ["write:sessions", "write:all", "admin"],
     },
   },
   async ({ request, params, authentication, resource: session }) => {

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

@@ -30,8 +30,7 @@ const { action } = createActionApiRoute(
     corsStrategy: "all",
     authorization: {
       action: "write",
-      resource: (params) => ({ sessions: params.session }),
-      superScopes: ["write:sessions", "write:all", "admin"],
+      resource: (params) => ({ type: "sessions", id: params.session }),
     },
   },
   async ({ params, authentication }) => {
@@ -110,15 +109,18 @@ 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 }) => {
         const ids = new Set<string>([addressingKey]);
         if (row) {
           ids.add(row.friendlyId);
           if (row.externalId) ids.add(row.externalId);
         }
-        return { sessions: [...ids] };
+        return [...ids].map((id) => ({ type: "sessions", id }));
       },
-      superScopes: ["read:sessions", "read:all", "admin"],
     },
   },
   async ({ params, request, authentication, resource }) => {

apps/webapp/app/services/routeBuilders/apiBuilder.server.ts

@@ -88,6 +88,13 @@ type AnyZodSchema = z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, an
 // identifiers (a run is addressable by friendlyId / batch / tags / task) so a
 // JWT scoped to *any* of them grants access to the row.
 //
+// The pre-RBAC apiBuilder had a separate `superScopes: [...]` whitelist for
+// "broader-than-this-resource" access. Post-RBAC, that's expressed in two
+// ways: include a collection-level shape `{ type: "<subject>" }` (no id) in
+// the array so a `<action>:<subject>` JWT matches it, and rely on the JWT
+// ability's wildcard branches for the bypass tier (`*:all` and `admin*` —
+// see `internal-packages/rbac/src/ability.ts`). No code knob is needed.
+//
 // Batch operations are different: each item in the array is a *distinct*
 // resource and authorization must hold for every one of them. Wrapping the
 // array via `everyResource` flips the auth check from `some` to `every`. The