chore(rbac): keep the delegated-token invariant, drop the essay

Author: kathiekiwi

internal-packages/rbac/src/fallback.ts

@@ -22,9 +22,7 @@ import type { PrismaClient } from "@trigger.dev/database";
 import { buildFallbackAbility, buildJwtAbility, permissiveAbility } from "./ability.js";
 import { BearerCredentialResolver } from "./bearerCredentials.js";
 
-// What a user-actor token with no declared cap can do without a plugin. Reads
-// only: writes need a role the fallback can't resolve, and denying everything
-// would break the token's own JWT exchange (gated on `read:apiKeys`).
+// Reads only: a capless token still has to reach its own JWT exchange (gated on `read:apiKeys`).
 const CAPLESS_USER_ACTOR_SCOPES = ["read:all"];
 
 export type FallbackPrismaClients = {
@@ -218,9 +216,7 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
         organizationId: context.organizationId ?? "",
         projectId: context.projectId,
       },
-      // A delegated token is a downgrade of the user, so it never gets the
-      // blanket ability a PAT gets here: its own cap, or read-only when it
-      // declares none (a capless token still has to reach the JWT exchange).
+      // A delegated token is a downgrade of the user: never the blanket ability a PAT gets here.
       ability: buildJwtAbility(claims.cap ?? CAPLESS_USER_ACTOR_SCOPES),
     };
   }

packages/plugins/src/rbac.ts

@@ -88,7 +88,6 @@ export type RbacSubject =
       userId: string;
       client?: string;
       // The environment the token was signed for, when it carries the claim.
-      // Carried on the subject so an authorization path can't lose it.
       environmentId?: string;
       organizationId: string;
       projectId?: string;
@@ -399,10 +398,8 @@ export type UserActorAuthResult =
   | {
       ok: true;
       userId: string;
-      // The verified claims, so the caller gets the token's environment scope
-      // with the identity instead of re-deriving it. Optional only because a
-      // plugin built against an older contract can't return it — a host that
-      // enforces the environment claim must fail closed on its absence.
+      // Optional only for plugins built against an older contract: a host enforcing the
+      // environment claim must fail closed when it is absent.
       claims?: UserActorClaims;
       subject: RbacSubject;
       ability: RbacAbility;
@@ -453,9 +450,8 @@ export interface RoleBaseAccessController {
   // user: floor = the user's role in the target org (rejects non-members,
   // like authenticatePat), cap = the token's optional scope cap.
   //
-  // No plugin installed → the fallback verifies the token and builds the
-  // ability from the token's own cap (read-only when it declares none). A
-  // delegated token never gets the blanket ability the fallback gives a PAT.
+  // No plugin installed → the fallback builds the ability from the token's own cap
+  // (read-only when it declares none), never the blanket ability it gives a PAT.
   authenticateUserActor(
     request: Request,
     context: { organizationId?: string; projectId?: string }