RBAC plugin: Result types on mutation methods + OSS fallback (TRI-8747)

Mutation methods on RoleBaseAccessController now return discriminated
Result unions instead of throwing on expected error paths:

- RoleMutationResult — { ok: true; role: Role } | { ok: false; error }
  for createRole, updateRole.
- RoleAssignmentResult — { ok: true } | { ok: false; error: string }
  for deleteRole, setUserRole, removeUserRole, setTokenRole,
  removeTokenRole.

The cloud webapp surfaces the 'error' strings directly to users
(system role edits, plan-tier gating, validation conflicts), so a
thrown exception now signals only an unexpected failure (DB outage,
bug). Read methods (getUserRole, getTokenRole, allRoles,
allPermissions) are unchanged.

OSS fallback returns { ok: false, error: 'RBAC plugin not installed' }
for every mutation — matches the prior behaviour (createRole/updateRole
already threw with this message; the others were silent no-ops, which
made misuse hard to detect). The LazyController in @internal/rbac
forwards the new return types verbatim. Changeset: patch.

Customer-facing surface: only public type widening of mutation method
return types — no runtime behaviour change for OSS callers (they get
a Result error instead of a thrown error or silent no-op; both indicate
'do not call these without the enterprise plugin').

Author: matt-aitken

.changeset/rbac-mutation-result-types.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/plugins": patch
+---
+
+RBAC plugin: mutation methods on `RoleBaseAccessController` now return discriminated `Result` types instead of throwing on expected error paths. `createRole` and `updateRole` return `RoleMutationResult` (`{ ok: true; role: Role } | { ok: false; error: string }`); `deleteRole`, `setUserRole`, `removeUserRole`, `setTokenRole`, and `removeTokenRole` return `RoleAssignmentResult` (`{ ok: true } | { ok: false; error: string }`). The webapp surfaces the `error` strings directly to users (system role edits, plan-tier gating, validation conflicts) so a thrown exception now signals only an unexpected failure (DB outage, bug). Read methods (`getUserRole`, `getTokenRole`, `allRoles`, `allPermissions`) are unchanged.

internal-packages/rbac/src/fallback.ts

@@ -7,7 +7,9 @@ import type {
   RbacResource,
   BearerAuthResult,
   SessionAuthResult,
+  RoleAssignmentResult,
   RoleBaseAccessController,
+  RoleMutationResult,
 } from "@trigger.dev/plugins";
 import type { PrismaClient } from "@trigger.dev/database";
 import { validateJWT } from "@trigger.dev/core/v3/jwt";
@@ -163,29 +165,41 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
     return [];
   }
 
-  async createRole(): Promise<Role> {
-    throw new Error("RBAC plugin not installed");
+  async createRole(): Promise<RoleMutationResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
   }
 
-  async updateRole(): Promise<Role> {
-    throw new Error("RBAC plugin not installed");
+  async updateRole(): Promise<RoleMutationResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
   }
 
-  async deleteRole(): Promise<void> {}
+  async deleteRole(): Promise<RoleAssignmentResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
+  }
 
   async getUserRole(): Promise<Role | null> {
     return null;
   }
 
-  async setUserRole(): Promise<void> {}
-  async removeUserRole(): Promise<void> {}
+  async setUserRole(): Promise<RoleAssignmentResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
+  }
+
+  async removeUserRole(): Promise<RoleAssignmentResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
+  }
 
   async getTokenRole(): Promise<Role | null> {
     return null;
   }
 
-  async setTokenRole(): Promise<void> {}
-  async removeTokenRole(): Promise<void> {}
+  async setTokenRole(): Promise<RoleAssignmentResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
+  }
+
+  async removeTokenRole(): Promise<RoleAssignmentResult> {
+    return { ok: false, error: "RBAC plugin not installed" };
+  }
 }
 
 function isPublicJWT(token: string): boolean {

internal-packages/rbac/src/index.ts

@@ -3,8 +3,10 @@ import type {
   RbacAbility,
   Role,
   RbacResource,
+  RoleAssignmentResult,
   RoleBaseAccessController,
   RoleBasedAccessControlPlugin,
+  RoleMutationResult,
 } from "@trigger.dev/plugins";
 import type { PrismaClient } from "@trigger.dev/database";
 import { RoleBaseAccessFallback } from "./fallback.js";
@@ -121,39 +123,53 @@ class LazyController implements RoleBaseAccessController {
     return (await this.c()).allRoles(...args);
   }
 
-  async createRole(...args: Parameters<RoleBaseAccessController["createRole"]>): Promise<Role> {
+  async createRole(
+    ...args: Parameters<RoleBaseAccessController["createRole"]>
+  ): Promise<RoleMutationResult> {
     return (await this.c()).createRole(...args);
   }
 
-  async updateRole(...args: Parameters<RoleBaseAccessController["updateRole"]>): Promise<Role> {
+  async updateRole(
+    ...args: Parameters<RoleBaseAccessController["updateRole"]>
+  ): Promise<RoleMutationResult> {
     return (await this.c()).updateRole(...args);
   }
 
-  async deleteRole(...args: Parameters<RoleBaseAccessController["deleteRole"]>): Promise<void> {
+  async deleteRole(
+    ...args: Parameters<RoleBaseAccessController["deleteRole"]>
+  ): Promise<RoleAssignmentResult> {
     return (await this.c()).deleteRole(...args);
   }
 
   async getUserRole(...args: Parameters<RoleBaseAccessController["getUserRole"]>): Promise<Role | null> {
     return (await this.c()).getUserRole(...args);
   }
 
-  async setUserRole(...args: Parameters<RoleBaseAccessController["setUserRole"]>): Promise<void> {
+  async setUserRole(
+    ...args: Parameters<RoleBaseAccessController["setUserRole"]>
+  ): Promise<RoleAssignmentResult> {
     return (await this.c()).setUserRole(...args);
   }
 
-  async removeUserRole(...args: Parameters<RoleBaseAccessController["removeUserRole"]>): Promise<void> {
+  async removeUserRole(
+    ...args: Parameters<RoleBaseAccessController["removeUserRole"]>
+  ): Promise<RoleAssignmentResult> {
     return (await this.c()).removeUserRole(...args);
   }
 
   async getTokenRole(...args: Parameters<RoleBaseAccessController["getTokenRole"]>): Promise<Role | null> {
     return (await this.c()).getTokenRole(...args);
   }
 
-  async setTokenRole(...args: Parameters<RoleBaseAccessController["setTokenRole"]>): Promise<void> {
+  async setTokenRole(
+    ...args: Parameters<RoleBaseAccessController["setTokenRole"]>
+  ): Promise<RoleAssignmentResult> {
     return (await this.c()).setTokenRole(...args);
   }
 
-  async removeTokenRole(...args: Parameters<RoleBaseAccessController["removeTokenRole"]>): Promise<void> {
+  async removeTokenRole(
+    ...args: Parameters<RoleBaseAccessController["removeTokenRole"]>
+  ): Promise<RoleAssignmentResult> {
     return (await this.c()).removeTokenRole(...args);
   }
 }

packages/plugins/src/index.ts

@@ -1,6 +1,8 @@
 export type {
   RoleBasedAccessControlPlugin,
   RoleBaseAccessController,
+  RoleAssignmentResult,
+  RoleMutationResult,
   Permission,
   Role,
   RbacAbility,

packages/plugins/src/rbac.ts

@@ -98,24 +98,31 @@ export interface RoleBaseAccessController {
   allPermissions(organizationId: string): Promise<Permission[]>;
   allRoles(organizationId: string): Promise<Role[]>;
 
-  // Role management (throws in OSS fallback)
+  // Role management. Mutation methods return a discriminated Result
+  // rather than throwing — the cloud webapp surfaces `error` strings
+  // directly to the user (system role edits, plan-gating, validation
+  // conflicts), so a thrown exception is only ever for unexpected
+  // failures (DB outage, bug). The OSS fallback returns
+  // `{ ok: false, error: "RBAC plugin not installed" }` for these.
   createRole(params: {
     organizationId: string;
     name: string;
     description: string;
     permissions: string[];
-  }): Promise<Role>;
+  }): Promise<RoleMutationResult>;
 
   updateRole(params: {
     roleId: string;
     name?: string;
     description?: string;
     permissions?: string[];
-  }): Promise<Role>;
+  }): Promise<RoleMutationResult>;
 
-  deleteRole(roleId: string): Promise<void>;
+  deleteRole(roleId: string): Promise<RoleAssignmentResult>;
 
-  // Role assignments (no-ops in OSS fallback)
+  // Role assignments. Same Result discipline as the role-management
+  // methods above. The OSS fallback returns
+  // `{ ok: false, error: "RBAC plugin not installed" }`.
   getUserRole(params: {
     userId: string;
     organizationId: string;
@@ -127,19 +134,28 @@ export interface RoleBaseAccessController {
     organizationId: string;
     roleId: string;
     projectId?: string;
-  }): Promise<void>;
+  }): Promise<RoleAssignmentResult>;
 
   removeUserRole(params: {
     userId: string;
     organizationId: string;
     projectId?: string;
-  }): Promise<void>;
+  }): Promise<RoleAssignmentResult>;
 
   getTokenRole(tokenId: string): Promise<Role | null>;
-  setTokenRole(params: { tokenId: string; roleId: string }): Promise<void>;
-  removeTokenRole(tokenId: string): Promise<void>;
+  setTokenRole(params: { tokenId: string; roleId: string }): Promise<RoleAssignmentResult>;
+  removeTokenRole(tokenId: string): Promise<RoleAssignmentResult>;
 }
 
+// Mutation result for role create/update — success carries the new
+// `role`, failure carries a user-facing `error` string.
+export type RoleMutationResult =
+  | { ok: true; role: Role }
+  | { ok: false; error: string };
+
+// Result for assignment / deletion mutations that don't return a value.
+export type RoleAssignmentResult = { ok: true } | { ok: false; error: string };
+
 export interface RoleBasedAccessControlPlugin {
   create(
     helpers: { getSessionUserId: (request: Request) => Promise<string | null> }