feat(webapp): consolidate auth path + add comprehensive auth tests (#3499)

## Summary

Consolidates the webapp's authentication and authorization into a small
set of route helpers, replacing the ad-hoc `requireUser` /
`requireUserId` / `authenticatedEnvironmentForAuthentication` calls
scattered across routes. Same security model, but the per-request flow
(authenticate → authorize → load) now lives in one place per route
family.

Introduces a plugin seam (`@trigger.dev/plugins`) that lets the cloud
build install a richer RBAC implementation without touching webapp code.
The OSS fallback keeps the pre-RBAC permissive behaviour intact, so
self-hosted deployments work unchanged.

Adds a comprehensive end-to-end auth test suite that didn't exist before
— 193 `it()` blocks (vitest reports ~199 after `it.each` expansion)
covering API key, PAT and JWT auth across the public API surface, plus
dashboard session auth for admin pages.

## Changes

### Plugin contract — `@trigger.dev/plugins`

`RoleBaseAccessController` interface authoritative for both OSS
(fallback) and cloud (enterprise plugin):
- `authenticateBearer(request, { allowJWT? })` — API-key / public-JWT
auth, returns env + ability
- `authenticateSession(request, { userId, organizationId?, projectId?
})` — dashboard auth, caller resolves `userId` from the session cookie
and passes it in (no `helpers.getSessionUserId` callback — decouples the
plugin host from session-cookie code)
- `authenticatePat(request, { organizationId?, projectId? })` — PAT
auth, returns identity + `lastAccessedAt` so the host can throttle the
per-request update
- `authenticateAuthorize*` variants for the auth-and-check-in-one-call
cases
- `isUsingPlugin(): Promise<boolean>` — capability flag for UI /
branching where plugin-present-ness matters; replaces the
sentinel-string coupling that had `personalAccessToken.server` matching
`"RBAC plugin not installed"` literally

### Dashboard auth (started, partial rollout)

Admin and settings pages migrated to a unified `dashboardLoader` /
`dashboardAction` helper that authenticates the session, runs an
authorization check, and exposes the result to the route. Other
dashboard routes still on the old pattern; remaining migration tracked
in TRI-8730.

Migrated routes:
- `admin.*` (14 admin / back-office / feature-flags / LLM-models /
notifications / orgs / concurrency pages)
- `_app.orgs.$organizationSlug.settings.team`
- `_app.orgs.$organizationSlug.settings.roles`

### API / realtime / engine auth (complete for the migrated families)

71 routes migrated to a unified `apiBuilder` that centralizes Bearer /
PAT / Public-JWT authentication and applies the per-route authorization
check before the handler runs. Includes:
- `api.v1.*` and `api.v2.*` and `api.v3.*` — tasks, runs, batches,
queues, prompts, deployments, query, sessions, waitpoints, packets,
workers, idempotency keys
- `realtime.v1.*` — runs, batches, sessions, streams
- `engine.v1.*` — dev / worker-action protocols

29 routes still on the legacy `authenticateApiRequest*` helpers —
tracked as a post-deploy follow-up in TRI-9228.

Multi-resource auth direction is now explicit at the call site via
`anyResource(...)` (OR) and `everyResource(...)` (AND). Bare arrays no
longer typecheck — fixes a class of bug where a JWT scoped to one
resource could implicitly access others under OR semantics.

PAT auth path consolidated: was three DB queries per request (legacy
`authenticateApiRequestWithPersonalAccessToken` findFirst +
`rbac.authenticatePat` join + `lastAccessedAt` update). Now one query in
the steady state — plugin returns `lastAccessedAt`, host smart-skips the
update via JS-side throttle when fresh.

Side effect: action aliases preserved historic JWT scope semantics where
the new model is stricter (e.g. a `write:tasks` JWT now also satisfies
`trigger` / `batchTrigger` / `update` actions on the same resource —
matched at the auth boundary, not in the route handler).

### Backwards-compat fixes

The strict-match model regressed several real-world JWT shapes. Each
preserved via explicit `anyResource(...)` entries in the route's authz
block:

- **Batch retrieve routes** (`api.v1.batches.$batchId`, `api.v2.*`,
`realtime.v1.batches.*`) accept `read:runs` JWTs again (pre-RBAC
literal-match superScope behaviour)
- **Runs list routes** (`api.v1.runs`, `realtime.v1.runs`) accept
type-level `read:tasks` / `read:tags` on unfiltered queries (matched the
legacy `Object.keys` iteration semantic)
- **PAT/OAT auth shape** normalized through `toAuthenticated` so all
auth methods return the same slim `AuthenticatedEnvironment` (was:
API-key returned the slim shape but PAT/OAT returned raw Prisma
`Decimal` / no `orgMember`)
- **Scope `:` preservation** in resource ids — `read:tags:env:staging`
now correctly identifies the tag id as `env:staging`, not `env`

### Slim `AuthenticatedEnvironment`

Extracted to `@trigger.dev/core/v3/auth/environment` — a structural
shape independent of `@trigger.dev/database`. The plugin contract
returns this; webapp consumers import from there; the cloud plugin
(Drizzle) returns the same shape without Prisma's `Decimal` class
leaking into the public surface. Lets internal-packages (run-engine,
etc.) refer to `AuthenticatedEnvironment` without pulling Prisma in.

### Auth test suite (new — `*.e2e.full.test.ts`)

193 e2e tests run against a real spawned webapp + Postgres (no mocks).
Coverage matrix:

- **API key auth** — read / write / trigger / batchTrigger / deploy
actions across runs, batches, deployments, prompts, queues, query,
sessions, input-streams, waitpoints, tasks, idempotency keys; multi-key
resources (a run carries batch / tag / task identifiers — auth must
accept any matching scope)
- **Personal Access Token auth** — comprehensive matrix: scope match,
scope mismatch, missing scope, expired token, malformed token
- **Public JWT auth** — sub-vs-URL environment resolution, expired JWTs,
signature verification, scope checking, otu (one-time-use) token
semantics, branch-environment signing-key fallback
- **Dashboard session auth** — admin-only pages reject non-admins;
per-action gating
- **Cross-cutting edge cases** — revoked API key grace window, JWT
cross-environment isolation, MissingResource branch behaviour

### Hygiene cleanups

- Deleted dead `app/services/authorization.server.ts` (legacy
`checkAuthorization` + types — no live consumers post-migration) and its
orphaned test
- Dropped the never-populated `scopes` field from
`ApiAuthenticationResultSuccess`
- `scheduleEmail` moved out of `email.server.ts` into its own module —
breaks a `commonWorker → marqs/V1` import chain that was poisoning the
auth test graph
- OSS Roles page shows a deployment-aware empty state ("Roles aren't
available in this self-hosted deployment" vs the plan-upsell copy) via
`rbac.isUsingPlugin()`
- Team action handler: explicit per-intent ability gates
(`manage:billing` for purchase-seats, `manage:members` for set-role +
remove-member with self-leave carve-out)

### Cross-repo coordination

All public-package contract changes paired in `triggerdotdev/cloud#763`
(rbac-packages branch) — the enterprise plugin implements the same
`RoleBaseAccessController` interface against Drizzle.

## Test plan

- [x] `pnpm run typecheck --filter webapp` clean
- [x] `pnpm --filter webapp exec vitest run --config
vitest.e2e.full.config.ts` — 193/193 pass (requires Docker for
testcontainers)
- [x] Spot-check an authed API endpoint with a valid + invalid API key
against a local stack
- [x] Spot-check the migrated admin pages render and gate non-admins

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: matt-aitken

.changeset/plugin-auth-path.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/plugins": patch
+---
+
+The public interfaces for a plugin system. Initially consolidated authentication and authorization interfaces.

.github/workflows/e2e-webapp-auth-full.yml

@@ -0,0 +1,120 @@
+name: "🛡️ E2E Tests: Webapp Auth (full)"
+
+# Comprehensive RBAC auth test suite — see TRI-8731. Runs separately from
+# the smoke e2e-webapp.yml because it covers every route family with a
+# pass/fail matrix and would otherwise dominate per-PR CI time.
+#
+# Triggered:
+#   - Manually via workflow_dispatch.
+#   - Nightly via schedule.
+#   - On pull requests touching auth-relevant files only (paths filter).
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * *" # 04:00 UTC daily
+  pull_request:
+    paths:
+      - "apps/webapp/app/services/routeBuilders/**"
+      - "apps/webapp/app/services/rbac.server.ts"
+      - "apps/webapp/app/services/apiAuth.server.ts"
+      - "apps/webapp/app/services/personalAccessToken.server.ts"
+      - "apps/webapp/app/services/sessionStorage.server.ts"
+      - "apps/webapp/app/routes/api.v*.**"
+      - "apps/webapp/app/routes/realtime.v*.**"
+      - "apps/webapp/test/**/*.e2e.full.test.ts"
+      - "apps/webapp/test/setup/global-e2e-full-setup.ts"
+      - "apps/webapp/test/helpers/sharedTestServer.ts"
+      - "apps/webapp/test/helpers/seedTestSession.ts"
+      - "apps/webapp/vitest.e2e.full.config.ts"
+      - "internal-packages/rbac/**"
+      - "packages/plugins/**"
+      - ".github/workflows/e2e-webapp-auth-full.yml"
+
+jobs:
+  e2eAuthFull:
+    name: "🛡️ E2E Auth Tests (full)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+    steps:
+      - name: 🔧 Disable IPv6
+        run: |
+          sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=1
+
+      - name: 🔧 Configure docker address pool
+        run: |
+          CONFIG='{
+            "default-address-pools" : [
+              {
+                "base" : "172.17.0.0/12",
+                "size" : 20
+              },
+              {
+                "base" : "192.168.0.0/16",
+                "size" : 24
+              }
+            ]
+          }'
+          mkdir -p /etc/docker
+          echo "$CONFIG" | sudo tee /etc/docker/daemon.json
+
+      - name: 🔧 Restart docker daemon
+        run: sudo systemctl restart docker
+
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          # Don't leave the GITHUB_TOKEN in .git/config — this job
+          # doesn't need to push and the persisted creds would be
+          # readable from any subsequent step (zizmor/artipacked).
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: 🐳 Skipping DockerHub login (no secrets available)
+        if: ${{ !env.DOCKERHUB_USERNAME }}
+        run: echo "DockerHub login skipped because secrets are not available."
+
+      - name: 🐳 Pre-pull testcontainer images
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        run: |
+          docker pull postgres:14
+          docker pull redis:7.2
+          docker pull testcontainers/ryuk:0.11.0
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🏗️ Build Webapp
+        run: pnpm run build --filter webapp
+
+      - name: 🛡️ Run Webapp Full Auth E2E Tests
+        run: cd apps/webapp && pnpm exec vitest run --config vitest.e2e.full.config.ts --reporter=default
+        env:
+          WEBAPP_TEST_VERBOSE: "1"

.server-changes/plugin-auth-path.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Webapp now supports a plugin system. Initially consolidates authentication and authorization paths.

apps/webapp/app/components/navigation/OrganizationSettingsSideMenu.tsx

@@ -4,6 +4,7 @@ import {
   Cog8ToothIcon,
   CreditCardIcon,
   LockClosedIcon,
+  ShieldCheckIcon,
   UserGroupIcon,
 } from "@heroicons/react/20/solid";
 import { ArrowLeftIcon } from "@heroicons/react/24/solid";
@@ -14,6 +15,7 @@ import { useFeatures } from "~/hooks/useFeatures";
 import { type MatchedOrganization } from "~/hooks/useOrganizations";
 import { cn } from "~/utils/cn";
 import {
+  organizationRolesPath,
   organizationSettingsPath,
   organizationSlackIntegrationPath,
   organizationTeamPath,
@@ -45,9 +47,11 @@ export type BuildInfo = {
 export function OrganizationSettingsSideMenu({
   organization,
   buildInfo,
+  isUsingPlugin,
 }: {
   organization: MatchedOrganization;
   buildInfo: BuildInfo;
+  isUsingPlugin: boolean;
 }) {
   const { isManagedCloud } = useFeatures();
   const featureFlags = useFeatureFlags();
@@ -128,6 +132,16 @@ export function OrganizationSettingsSideMenu({
             to={organizationTeamPath(organization)}
             data-action="team"
           />
+          {isUsingPlugin && (
+            <SideMenuItem
+              name="Roles"
+              icon={ShieldCheckIcon}
+              activeIconColor="text-sky-500"
+              inactiveIconColor="text-sky-500"
+              to={organizationRolesPath(organization)}
+              data-action="roles"
+            />
+          )}
           <SideMenuItem
             name="Settings"
             icon={Cog8ToothIcon}

apps/webapp/app/components/primitives/Select.tsx

@@ -463,7 +463,15 @@ export function SelectItem({
   ...props
 }: SelectItemProps) {
   const combobox = Ariakit.useComboboxContext();
-  const render = combobox ? <Ariakit.ComboboxItem render={props.render} /> : undefined;
+  // In a Combobox context we wrap the caller's render in ComboboxItem
+  // so combobox keyboard nav still works. Outside a Combobox we pass
+  // the render through verbatim — without this, callers like
+  // SelectLinkItem (which uses render to swap in a <Link>) get their
+  // render prop silently dropped, which is why those rows looked
+  // clickable but didn't navigate.
+  const render = combobox
+    ? <Ariakit.ComboboxItem render={props.render} />
+    : props.render;
   const ref = React.useRef<HTMLDivElement>(null);
   const select = Ariakit.useSelectContext();
   const selectValue = select?.useState("value");

apps/webapp/app/env.server.ts

@@ -1542,6 +1542,9 @@ const EnvironmentSchema = z
     // Private connections
     PRIVATE_CONNECTIONS_ENABLED: z.string().optional(),
     PRIVATE_CONNECTIONS_AWS_ACCOUNT_IDS: z.string().optional(),
+
+    // Force RBAC to not use the plugin
+    RBAC_FORCE_FALLBACK: BoolEnv.default(false),
   })
   .and(GithubAppEnvSchema)
   .and(S2EnvSchema)

apps/webapp/app/models/member.server.ts

@@ -1,6 +1,8 @@
 import { type Prisma, prisma } from "~/db.server";
 import { createEnvironment } from "./organization.server";
 import { customAlphabet } from "nanoid";
+import { logger } from "~/services/logger.server";
+import { rbac } from "~/services/rbac.server";
 
 const tokenValueLength = 40;
 const tokenGenerator = customAlphabet("123456789abcdefghijkmnopqrstuvwxyz", tokenValueLength);
@@ -86,10 +88,19 @@ export async function inviteMembers({
   slug,
   emails,
   userId,
+  rbacRoleId,
 }: {
   slug: string;
   emails: string[];
   userId: string;
+  /**
+   * Optional RBAC role to attach to the invite. When set, accepted
+   * invites trigger `rbac.setUserRole(rbacRoleId)` after the OrgMember
+   * is created.
+   *
+   * `OrgMemberInvite.role` is still set if the plugin isn't installed.
+   */
+  rbacRoleId?: string | null;
 }) {
   const org = await prisma.organization.findFirst({
     where: { slug, members: { some: { userId } } },
@@ -107,6 +118,7 @@ export async function inviteMembers({
         organizationId: org.id,
         inviterId: userId,
         role: "MEMBER",
+        rbacRoleId: rbacRoleId ?? null,
       } satisfies Prisma.OrgMemberInviteCreateManyInput)
   );
 
@@ -163,7 +175,7 @@ export async function acceptInvite({
   user: { id: string; email: string };
   inviteId: string;
 }) {
-  return await prisma.$transaction(async (tx) => {
+  const result = await prisma.$transaction(async (tx) => {
     // 1. Delete the invite and get the invite details
     const invite = await tx.orgMemberInvite.delete({
       where: {
@@ -207,8 +219,32 @@ export async function acceptInvite({
       },
     });
 
-    return { remainingInvites, organization: invite.organization };
+    return {
+      remainingInvites,
+      organization: invite.organization,
+      inviteRole: invite.role,
+      rbacRoleId: invite.rbacRoleId,
+    };
   });
+
+  // If the invite carried an explicit RBAC role. Errors are logged, not fatal.
+  if (result.rbacRoleId) {
+    const roleResult = await rbac.setUserRole({
+      userId: user.id,
+      organizationId: result.organization.id,
+      roleId: result.rbacRoleId,
+    });
+    if (!roleResult.ok) {
+      logger.error("acceptInvite: skipped RBAC role assignment", {
+        organizationId: result.organization.id,
+        userId: user.id,
+        rbacRoleId: result.rbacRoleId,
+        reason: roleResult.error,
+      });
+    }
+  }
+
+  return { remainingInvites: result.remainingInvites, organization: result.organization };
 }
 
 export async function declineInvite({

apps/webapp/app/models/project.server.ts

@@ -4,7 +4,7 @@ import { $replica, prisma } from "~/db.server";
 import type { Prisma, Project } from "@trigger.dev/database";
 import { type Organization, createEnvironment } from "./organization.server";
 import { env } from "~/env.server";
-import { projectCreated } from "~/services/platform.v3.server";
+import { projectCreated } from "~/services/projectCreated.server";
 export type { Project } from "@trigger.dev/database";
 
 const externalRefGenerator = customAlphabet("abcdefghijklmnopqrstuvwxyz", 20);