Plugin: authenticatePat for cap-and-floor PAT auth (TRI-9087)

Adds RoleBaseAccessController.authenticatePat — PATs identify the user;
the effective ability is min(user's role in target org, max-role cap).
The user's actual membership is the floor (auto-narrows on demotion or
removal); the cap is set at PAT creation as a deliberate ceiling.

OSS-side:
- @trigger.dev/plugins gains the PatAuthResult type + authenticatePat
  on the controller interface.
- Fallback validates the PAT (prefix, hashed lookup, revoked check) and
  returns a permissive ability — preserves the pre-RBAC behaviour where
  PATs were pure user-identity tokens. Self-hosters see no change.
- LazyController delegates with the existing withActionAliases wrapper.

apiBuilder:
- createLoaderPATApiRoute accepts an optional context callback to
  derive { organizationId?, projectId? } and an optional authorization
  block. When either is declared, rbac.authenticatePat runs and the
  ability flows into the handler. Routes that don't opt in stay on the
  legacy permissive path.
- api.v1.projects.$projectRef.runs.ts opts in: context resolves
  projectRef -> organizationId, authorization is read on type runs.

UI:
- account.tokens picker reframed as 'Maximum role' with a hint
  explaining the cap-vs-floor model. Underlying TokenRole storage
  unchanged; semantic flip from 'bound role' to 'max role cap'.

The role chosen at PAT creation now actually constrains the token
(previously TokenRole was written but never read at request time).

Author: matt-aitken

apps/webapp/app/routes/account.tokens/route.tsx

@@ -372,7 +372,7 @@ function CreatePersonalAccessToken({
 
             {showRolePicker && (
               <InputGroup>
-                <Label>Role</Label>
+                <Label>Maximum role</Label>
                 <Select<string, SystemRole>
                   value={selectedRoleId}
                   setValue={(v) => setSelectedRoleId(v)}
@@ -395,8 +395,8 @@ function CreatePersonalAccessToken({
                   }
                 </Select>
                 <Hint>
-                  The token's permissions are bound to this role. Defaults to your own role so the
-                  token can't do more than you can.
+                  The token can act with up to this role. Your current role in each org is the
+                  actual ceiling — the token never grants more than you have.
                 </Hint>
               </InputGroup>
             )}

apps/webapp/app/routes/api.v1.projects.$projectRef.runs.ts

@@ -1,5 +1,6 @@
 import { json } from "@remix-run/server-runtime";
 import { z } from "zod";
+import { $replica } from "~/db.server";
 import { findProjectByRef } from "~/models/project.server";
 import {
   ApiRunListPresenter,
@@ -16,6 +17,20 @@ export const loader = createLoaderPATApiRoute(
     params: ParamsSchema,
     searchParams: ApiRunListSearchParams,
     corsStrategy: "all",
+    // Resolve projectRef → org so the PAT plugin can ground its
+    // role-floor calculation. We deliberately don't filter by user
+    // membership here — that's the plugin's job (`authenticatePat`
+    // checks OrgMember in the target org and rejects if the user
+    // isn't a member). Keeps the contract clean: context is "what
+    // org does this URL target?" and auth is "is this user allowed?"
+    context: async (params) => {
+      const project = await $replica.project.findFirst({
+        where: { externalRef: params.projectRef },
+        select: { organizationId: true },
+      });
+      return project ? { organizationId: project.organizationId } : {};
+    },
+    authorization: { action: "read", resource: () => ({ type: "runs" }) },
   },
   async ({ searchParams, params, authentication, apiVersion }) => {
     const project = await findProjectByRef(params.projectRef, authentication.userId);

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

@@ -83,6 +83,15 @@ async function authenticateRequestForApiBuilder(
 
 type AnyZodSchema = z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>;
 
+// Sentinel ability for routes that don't opt into the cap-and-floor PAT
+// model — preserves pre-RBAC behaviour where PATs were pure user-identity
+// tokens. New routes that want gated PAT auth declare a `context` and
+// `authorization` block; the actual ability comes from `rbac.authenticatePat`.
+const PERMISSIVE_ABILITY: RbacAbility = {
+  can: () => true,
+  canSuper: () => false,
+};
+
 // Most route auth checks pass an array of resources to ability.can() with
 // "any-element-passes" semantics — a single record carries multiple
 // identifiers (a run is addressable by friendlyId / batch / tags / task) so a
@@ -365,6 +374,37 @@ type PATRouteBuilderOptions<
   searchParams?: TSearchParamsSchema;
   headers?: THeadersSchema;
   corsStrategy?: "all" | "none";
+  // Resolves the target org/project for the request. Fed to
+  // `rbac.authenticatePat` so the plugin can compute the user's role
+  // floor (their authority in that org) for the cap intersection.
+  // When omitted, the PAT runs in identity-only mode — no role floor,
+  // no per-route ability gating beyond what authorization (if any)
+  // declares against a permissive baseline. Routes added before TRI-9087
+  // run in this mode by default.
+  context?: (
+    params: TParamsSchema extends z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>
+      ? z.infer<TParamsSchema>
+      : undefined,
+    request: Request
+  ) =>
+    | { organizationId?: string; projectId?: string }
+    | Promise<{ organizationId?: string; projectId?: string }>;
+  authorization?: {
+    action: string;
+    resource: (
+      params: TParamsSchema extends z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>
+        ? z.infer<TParamsSchema>
+        : undefined,
+      searchParams: TSearchParamsSchema extends
+        | z.ZodFirstPartySchemaTypes
+        | z.ZodDiscriminatedUnion<any, any>
+        ? z.infer<TSearchParamsSchema>
+        : undefined,
+      headers: THeadersSchema extends z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>
+        ? z.infer<THeadersSchema>
+        : undefined
+    ) => AuthResource;
+  };
 };
 
 type PATHandlerFunction<
@@ -384,6 +424,7 @@ type PATHandlerFunction<
     ? z.infer<THeadersSchema>
     : undefined;
   authentication: PersonalAccessTokenAuthenticationResult;
+  ability: RbacAbility;
   request: Request;
   apiVersion: API_VERSIONS;
 }) => Promise<Response>;
@@ -402,6 +443,8 @@ export function createLoaderPATApiRoute<
       searchParams: searchParamsSchema,
       headers: headersSchema,
       corsStrategy = "none",
+      context: contextFn,
+      authorization,
     } = options;
 
     if (corsStrategy !== "none" && request.method.toUpperCase() === "OPTIONS") {
@@ -471,11 +514,53 @@ export function createLoaderPATApiRoute<
 
       const apiVersion = getApiVersion(request);
 
+      // Resolve ability via the rbac plugin. When neither `context` nor
+      // `authorization` is declared, the legacy permissive ability stands
+      // in — preserves the pre-RBAC PAT behaviour for routes that
+      // haven't opted into the cap-and-floor model yet.
+      let ability: RbacAbility = PERMISSIVE_ABILITY;
+      if (contextFn || authorization) {
+        const ctx = contextFn ? await contextFn(parsedParams, request) : {};
+        const patAuth = await rbac.authenticatePat(request, ctx);
+        if (!patAuth.ok) {
+          return await wrapResponse(
+            request,
+            json({ error: patAuth.error }, { status: patAuth.status }),
+            corsStrategy !== "none"
+          );
+        }
+        ability = patAuth.ability;
+
+        if (authorization) {
+          const $resource = authorization.resource(
+            parsedParams,
+            parsedSearchParams,
+            parsedHeaders
+          );
+          if (!checkAuth(ability, authorization.action, $resource)) {
+            return await wrapResponse(
+              request,
+              json(
+                {
+                  error: "Unauthorized",
+                  code: "unauthorized",
+                  param: "access_token",
+                  type: "authorization",
+                },
+                { status: 403 }
+              ),
+              corsStrategy !== "none"
+            );
+          }
+        }
+      }
+
       const result = await handler({
         params: parsedParams,
         searchParams: parsedSearchParams,
         headers: parsedHeaders,
         authentication: authenticationResult,
+        ability,
         request,
         apiVersion,
       });

internal-packages/rbac/src/fallback.ts

@@ -6,11 +6,13 @@ import type {
   RbacSubject,
   RbacResource,
   BearerAuthResult,
+  PatAuthResult,
   SessionAuthResult,
   RoleAssignmentResult,
   RoleBaseAccessController,
   RoleMutationResult,
 } from "@trigger.dev/plugins";
+import { createHash } from "node:crypto";
 import type { PrismaClient } from "@trigger.dev/database";
 import { validateJWT } from "@trigger.dev/core/v3/jwt";
 import { buildFallbackAbility, buildJwtAbility, permissiveAbility } from "./ability.js";
@@ -157,6 +159,45 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
     return auth;
   }
 
+  async authenticatePat(
+    request: Request,
+    context: { organizationId?: string; projectId?: string }
+  ): Promise<PatAuthResult> {
+    const rawToken = request.headers
+      .get("Authorization")
+      ?.replace(/^Bearer /, "")
+      .trim();
+    if (!rawToken || !rawToken.startsWith("tr_pat_")) {
+      return { ok: false, status: 401, error: "Invalid or Missing PAT" };
+    }
+
+    const hashedToken = createHash("sha256").update(rawToken).digest("hex");
+    const pat = await this.prisma.personalAccessToken.findFirst({
+      where: { hashedToken, revokedAt: null },
+      select: { id: true, userId: true },
+    });
+    if (!pat) {
+      return { ok: false, status: 401, error: "Invalid PAT" };
+    }
+
+    return {
+      ok: true,
+      tokenId: pat.id,
+      userId: pat.userId,
+      subject: {
+        type: "personalAccessToken",
+        tokenId: pat.id,
+        organizationId: context.organizationId ?? "",
+        projectId: context.projectId,
+      },
+      // No plugin → no role lookup. PATs in the OSS world are pure
+      // user-identity tokens; the route's own authorization block (or
+      // the absence of one) decides what they can do, same as it did
+      // before this method existed.
+      ability: permissiveAbility,
+    };
+  }
+
   async systemRoles(_organizationId: string) {
     // No plugin installed → no seeded roles. Callers handle null by
     // hiding role-picker UI / skipping role assignment writes.

internal-packages/rbac/src/index.ts

@@ -149,6 +149,11 @@ class LazyController implements RoleBaseAccessController {
     return auth;
   }
 
+  async authenticatePat(...args: Parameters<RoleBaseAccessController["authenticatePat"]>) {
+    const result = await (await this.c()).authenticatePat(...args);
+    return result.ok ? { ...result, ability: withActionAliases(result.ability) } : result;
+  }
+
   async systemRoles(...args: Parameters<RoleBaseAccessController["systemRoles"]>) {
     return (await this.c()).systemRoles(...args);
   }

packages/plugins/src/index.ts

@@ -12,4 +12,6 @@ export type {
   RbacUser,
   BearerAuthResult,
   SessionAuthResult,
+  PatAuthResult,
+  SystemRole,
 } from "./rbac.js";

packages/plugins/src/rbac.ts

@@ -106,6 +106,20 @@ export type SessionAuthResult =
   | { ok: false; reason: "unauthenticated" | "unauthorized" }
   | { ok: true; user: RbacUser; subject: RbacSubject; ability: RbacAbility };
 
+// PAT auth deliberately omits `environment` — PATs are user identity
+// tokens, not environment tokens. The ability is resolved per-request
+// from the user's role in the target org (passed via `context`),
+// intersected with the PAT's optional max-role cap.
+export type PatAuthResult =
+  | { ok: false; status: 401 | 403; error: string }
+  | {
+      ok: true;
+      tokenId: string;
+      userId: string;
+      subject: RbacSubject;
+      ability: RbacAbility;
+    };
+
 export interface RoleBaseAccessController {
   // API routes (Bearer token): one DB query → identity + pre-built ability
   // options.allowJWT: when true, accepts PUBLIC_JWT tokens in addition to environment API keys
@@ -117,6 +131,21 @@ export interface RoleBaseAccessController {
     context: { organizationId?: string; projectId?: string }
   ): Promise<SessionAuthResult>;
 
+  // PAT-authenticated routes (Authorization: Bearer tr_pat_…). The token
+  // identifies the user; the effective ability is `min(user's current
+  // role in the target org, the PAT's optional max-role cap)`. The user's
+  // actual org membership is the floor — if they've been demoted or
+  // removed, the PAT auto-narrows. The cap is set at PAT creation and
+  // ceilings the token even when the user is more privileged.
+  //
+  // No plugin installed → fallback returns a permissive ability so PAT
+  // routes that don't yet declare an `authorization` block keep working
+  // exactly as they did pre-RBAC.
+  authenticatePat(
+    request: Request,
+    context: { organizationId?: string; projectId?: string }
+  ): Promise<PatAuthResult>;
+
   // Convenience: authenticate + ability.can() check in one call; returns ok:false if check fails.
   // resource accepts the same single-or-array shape as RbacAbility.can — array form means
   // "grant access if any element passes".