RBAC: replace systemRoleIds() with systemRoles() catalogue

The OSS no longer needs to know individual role names. systemRoles(orgId)
returns a plugin-owned, ordered SystemRole[] (id, name, description,
available) — the cloud plugin owns the canonical order, the descriptions,
and the per-org plan-tier 'available' flag. Hidden roles (Member in v1)
are filtered out entirely.

OSS callers iterate the array and use array index for the level ladder;
no role-name strings except for the legacy OrgMember.role enum mapping
shim, which is now isolated to one filter in member.server.ts.

Author: matt-aitken

.changeset/rbac-system-roles.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/plugins": patch
+---
+
+RBAC plugin: replaced `systemRoleIds()` with `systemRoles()`. The new method returns an ordered `SystemRole[]` (highest authority first) where each entry carries `id`, `name`, `description`, and `available`. The OSS no longer needs to know individual role names — it just iterates the canonical order from the plugin. `available: false` lets a plugin advertise a role without exposing it (used by v1 to ship Owner/Admin/Developer while keeping Member's prod-restriction promise unmade until the env-tier route wiring lands).

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

@@ -110,15 +110,23 @@ export async function inviteMembers({
     throw new Error("User does not have access to this organization");
   }
 
-  // The legacy enum is the source of truth without the plugin installed.
-  // Owner/Admin RBAC ids → "ADMIN"; everything else → "MEMBER". Pull
-  // the canonical IDs off the plugin so we don't duplicate them here;
-  // null means no plugin → default to "MEMBER" (legacy two-option flow).
-  const ids = await rbac.systemRoleIds();
-  const legacyRole: "ADMIN" | "MEMBER" =
-    ids && (rbacRoleId === ids.owner || rbacRoleId === ids.admin)
-      ? "ADMIN"
-      : "MEMBER";
+  // The legacy OrgMember.role enum (ADMIN | MEMBER) needs a write so
+  // pre-RBAC code paths still see a sensible role on the invite. Map by
+  // role NAME — "Owner" and "Admin" become "ADMIN", everything else
+  // becomes "MEMBER". This is the one place left where the OSS keys off
+  // role names; the plugin owns the systemRoles catalogue and we just
+  // match on the well-known legacy-equivalent labels here.
+  // null means no plugin installed → default to "MEMBER" (legacy two-
+  // option flow).
+  const sys = await rbac.systemRoles(org.id);
+  const adminEquivalent = new Set(
+    (sys ?? [])
+      .filter((r) => r.name === "Owner" || r.name === "Admin")
+      .map((r) => r.id)
+  );
+  const legacyRole: "ADMIN" | "MEMBER" = adminEquivalent.has(rbacRoleId ?? "")
+    ? "ADMIN"
+    : "MEMBER";
 
   const invites = [...new Set(emails)].map(
     (email) =>

apps/webapp/app/routes/_app.orgs.$organizationSlug.invite/route.tsx

@@ -68,23 +68,23 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
   // Inviter's own role drives the "below their level" filter on the
   // dropdown. Plus assignable role IDs already encode the org's plan
   // tier — the intersection is what we offer.
-  const [inviterRole, assignableRoleIds, systemRoleIds] = await Promise.all([
+  const [inviterRole, assignableRoleIds, systemRoles] = await Promise.all([
     rbac.getUserRole({ userId, organizationId: organization.id }),
     rbac.getAssignableRoleIds(organization.id),
-    rbac.systemRoleIds(),
+    rbac.systemRoles(organization.id),
   ]);
 
   // Build the dropdown's offerable set server-side: roles that are
   // (a) assignable on the current plan AND (b) strictly below the
   // inviter's own level. The client just renders these — it doesn't
-  // need to know about the system-role ID constants or the ladder.
+  // need to know about the system-role catalogue or the ladder.
   const assignableSet = new Set(assignableRoleIds);
-  const offerableRoleIds = systemRoleIds
+  const offerableRoleIds = systemRoles
     ? result.roles
         .filter(
           (r) =>
             assignableSet.has(r.id) &&
-            isStrictlyBelow(systemRoleIds, inviterRole?.id ?? null, r.id)
+            isStrictlyBelow(systemRoles, inviterRole?.id ?? null, r.id)
         )
         .map((r) => r.id)
     : [];
@@ -98,27 +98,27 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
 // dropdown is hidden) or as a defensive default.
 const NO_RBAC_ROLE = "__no_rbac_role__";
 
-// Owner > Admin > Developer > Member. An inviter can only assign a
-// role strictly below their own — Owners can pick any of the four,
-// Admins can pick Developer or Member, Developer/Member can't invite
-// at all. Custom roles are out of scope for this rule (TRI-8747's
-// follow-up will handle them).
-function buildRoleLevel(ids: {
-  owner: string;
-  admin: string;
-  developer: string;
-  member: string;
-}): Record<string, number> {
-  return {
-    [ids.owner]: 4,
-    [ids.admin]: 3,
-    [ids.developer]: 2,
-    [ids.member]: 1,
-  };
+// An inviter can only assign a role strictly below their own. The
+// plugin's systemRoles array is in canonical order (highest authority
+// first), so array index drives the ladder — earlier index = higher
+// rank. Plan-tier filtering happens separately via assignableRoleIds;
+// the ladder is the absolute hierarchy. Custom roles aren't in the
+// table and are refused (TRI-8747's follow-up will handle them).
+type LadderRole = { id: string };
+
+function buildRoleLevel(roles: ReadonlyArray<LadderRole>): Record<string, number> {
+  const level: Record<string, number> = {};
+  roles.forEach((r, i) => {
+    // Top of the array = highest level. Subtract from length so larger
+    // numbers always mean "more authority" — no off-by-one when a role
+    // is added or removed.
+    level[r.id] = roles.length - i;
+  });
+  return level;
 }
 
 function isStrictlyBelow(
-  ids: { owner: string; admin: string; developer: string; member: string },
+  roles: ReadonlyArray<LadderRole>,
   inviterRoleId: string | null,
   invitedRoleId: string
 ): boolean {
@@ -128,7 +128,7 @@ function isStrictlyBelow(
   // would have already failed earlier if the inviter wasn't allowed
   // to invite at all.
   if (!inviterRoleId) return true;
-  const level = buildRoleLevel(ids);
+  const level = buildRoleLevel(roles);
   const inviter = level[inviterRoleId];
   const invited = level[invitedRoleId];
   // Custom roles aren't in the level table — refuse.
@@ -182,12 +182,12 @@ export const action: ActionFunction = async ({ request, params }) => {
     if (!org) {
       return json({ errors: { body: "Organization not found" } }, { status: 404 });
     }
-    const [inviterRole, assignableRoleIds, systemRoleIds] = await Promise.all([
+    const [inviterRole, assignableRoleIds, systemRoles] = await Promise.all([
       rbac.getUserRole({ userId, organizationId: org.id }),
       rbac.getAssignableRoleIds(org.id),
-      rbac.systemRoleIds(),
+      rbac.systemRoles(org.id),
     ]);
-    if (!systemRoleIds) {
+    if (!systemRoles) {
       // No plugin installed but the form somehow submitted a role id —
       // ignore it (fall through to legacy behaviour rather than 400).
       resolvedRbacRoleId = null;
@@ -201,7 +201,7 @@ export const action: ActionFunction = async ({ request, params }) => {
       }
       if (
         !isStrictlyBelow(
-          systemRoleIds,
+          systemRoles,
           inviterRole?.id ?? null,
           submittedRbacRoleId
         )

apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.roles/route.tsx

@@ -62,18 +62,18 @@ export const loader = dashboardLoader(
       throw new Response("Not Found", { status: 404 });
     }
 
-    const [roles, assignableRoleIds, allPermissions, systemRoleIds] = await Promise.all([
+    const [roles, assignableRoleIds, allPermissions, systemRoles] = await Promise.all([
       rbac.allRoles(orgId),
       rbac.getAssignableRoleIds(orgId),
       rbac.allPermissions(orgId),
-      rbac.systemRoleIds(),
+      rbac.systemRoles(orgId),
     ]);
 
     return typedjson({
       roles,
       assignableRoleIds,
       allPermissions,
-      systemRoleIds,
+      systemRoles,
     });
   }
 );
@@ -131,7 +131,7 @@ const GROUP_ORDER = [
 ] as const;
 
 export default function Page() {
-  const { roles, assignableRoleIds, allPermissions, systemRoleIds } =
+  const { roles, assignableRoleIds, allPermissions, systemRoles } =
     useTypedLoaderData<typeof loader>();
   const organization = useOrganization();
   const plan = useCurrentPlan();
@@ -145,18 +145,14 @@ export default function Page() {
   const rolesById = new Map<string, LoaderRole>(roles.map((r) => [r.id, r]));
   const assignable = new Set(assignableRoleIds);
 
-  // Column ordering: Owner / Admin / Developer / Member, then any
-  // custom roles in the order rbac.allRoles returned them. systemRoleIds
-  // is null when no plugin is installed — there are no system roles to
-  // pin; fall through to whatever order rbac.allRoles returns.
-  const systemRoleOrder: ReadonlyArray<{ id: string; name: string }> = systemRoleIds
-    ? [
-        { id: systemRoleIds.owner, name: "Owner" },
-        { id: systemRoleIds.admin, name: "Admin" },
-        { id: systemRoleIds.developer, name: "Developer" },
-        { id: systemRoleIds.member, name: "Member" },
-      ]
-    : [];
+  // Column ordering follows the plugin's canonical systemRoles order
+  // (highest authority first), then any custom roles in the order
+  // rbac.allRoles returned them. systemRoles is null when no plugin is
+  // installed; fall through to whatever order rbac.allRoles returns.
+  // Each entry's `available` flag reflects plan-tier eligibility — we
+  // render unavailable system roles too, but PlanBadge tags them so
+  // customers see the comparison and know what an upgrade unlocks.
+  const systemRoleOrder = systemRoles ?? [];
   const systemRoleIdSet = new Set(systemRoleOrder.map((r) => r.id));
   const systemColumns = systemRoleOrder.flatMap((meta) => {
     const role = rolesById.get(meta.id);
@@ -199,7 +195,7 @@ export default function Page() {
                           <PlanBadge
                             roleId={role.id}
                             assignable={assignable}
-                            systemRoleIds={systemRoleIds}
+                            systemRoleIdSet={systemRoleIdSet}
                           />
                         </div>
                       </TableHeaderCell>
@@ -271,19 +267,21 @@ function EmptyState() {
 function PlanBadge({
   roleId,
   assignable,
-  systemRoleIds,
+  systemRoleIdSet,
 }: {
   roleId: string;
   assignable: ReadonlySet<string>;
-  systemRoleIds: { developer: string; member: string } | null;
+  systemRoleIdSet: ReadonlySet<string>;
 }) {
   // Roles the org's plan doesn't permit get a small upgrade-tier hint
   // in the column header. The cell rendering is identical regardless
   // — the comparison value is still useful even on Free/Hobby.
   if (assignable.has(roleId)) return null;
-  // System role gating: Owner+Admin always available; Member/Developer
-  // only on Pro+; custom roles only on Enterprise.
-  if (systemRoleIds && (roleId === systemRoleIds.member || roleId === systemRoleIds.developer)) {
+  // System roles render as "Pro" (the gating tier where they unlock —
+  // Free/Hobby see Owner+Admin only, Pro adds the rest). Custom roles
+  // render as "Enterprise" — only Enterprise plans can create or assign
+  // them.
+  if (systemRoleIdSet.has(roleId)) {
     return <Badge variant="extra-small">Pro</Badge>;
   }
   return <Badge variant="extra-small">Enterprise</Badge>;

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

@@ -71,7 +71,9 @@ async function loadSystemRolesForUser(userId: string) {
     select: { organizationId: true },
     orderBy: { createdAt: "asc" },
   });
-  if (!orgMember) return { roles: [], userRoleId: null as string | null };
+  if (!orgMember) {
+    return { roles: [], userRoleId: null as string | null, orgId: null as string | null };
+  }
 
   const allRoles = await rbac.allRoles(orgMember.organizationId);
   const systemRoles = allRoles.filter((r) => r.isSystem);
@@ -81,26 +83,32 @@ async function loadSystemRolesForUser(userId: string) {
     organizationId: orgMember.organizationId,
   });
 
-  return { roles: systemRoles, userRoleId: userRole?.id ?? null };
+  return {
+    roles: systemRoles,
+    userRoleId: userRole?.id ?? null,
+    orgId: orgMember.organizationId,
+  };
 }
 
 export const loader = async ({ request }: LoaderFunctionArgs) => {
   const userId = await requireUserId(request);
 
   try {
-    const [personalAccessTokens, { roles, userRoleId }] = await Promise.all([
+    const [personalAccessTokens, { roles, userRoleId, orgId }] = await Promise.all([
       getValidPersonalAccessTokens(userId),
       loadSystemRolesForUser(userId),
     ]);
 
     // Default the role picker to the user's own role in their primary
     // org so a freshly-created PAT isn't more privileged than the
-    // person creating it. Falls back to Member if they don't have one
-    // (new user). When no RBAC plugin is installed, systemRoleIds()
-    // returns null and the picker is hidden anyway, so defaultRoleId
-    // is just a placeholder in that branch.
-    const ids = await rbac.systemRoleIds();
-    const defaultRoleId = userRoleId ?? ids?.member ?? "";
+    // person creating it. Falls back to the most-restrictive role
+    // available on the org's plan if they don't have one. When the
+    // user isn't a member of any org or no RBAC plugin is installed,
+    // the picker is hidden anyway, so defaultRoleId is just a
+    // placeholder.
+    const sys = orgId ? await rbac.systemRoles(orgId) : null;
+    const lowestAvailable = (sys ?? []).filter((r) => r.available).at(-1)?.id ?? "";
+    const defaultRoleId = userRoleId ?? lowestAvailable;
 
     return typedjson({
       personalAccessTokens,

internal-packages/rbac/src/fallback.ts

@@ -157,7 +157,7 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
     return auth;
   }
 
-  async systemRoleIds() {
+  async systemRoles(_organizationId: string) {
     // No plugin installed → no seeded roles. Callers handle null by
     // hiding role-picker UI / skipping role assignment writes.
     return null;

internal-packages/rbac/src/index.ts

@@ -138,8 +138,8 @@ class LazyController implements RoleBaseAccessController {
     return auth;
   }
 
-  async systemRoleIds() {
-    return (await this.c()).systemRoleIds();
+  async systemRoles(...args: Parameters<RoleBaseAccessController["systemRoles"]>) {
+    return (await this.c()).systemRoles(...args);
   }
 
   async allPermissions(

packages/plugins/src/rbac.ts

@@ -1,14 +1,22 @@
 /**
- * Stable IDs for the four built-in system roles. Values are tied to
- * the plugin's seed migration; the same map is returned by both the
- * default fallback and any installed plugin so callers can rely on
- * the IDs without knowing which implementation is loaded.
+ * Plugin-owned metadata for a built-in system role. The plugin returns
+ * these in canonical order (highest authority first) so the dashboard
+ * can render columns / build a level ladder without knowing role names.
+ *
+ * Roles the plugin doesn't expose at all (e.g. seeded but with the
+ * `is_hidden` flag set in the cloud plugin) are not returned by
+ * `systemRoles()` — there's no "advertised but absent" state.
+ *
+ * `available` indicates whether the role is assignable on the *org's
+ * plan*. v1: Free/Hobby plans get Owner+Admin available; Pro+ adds
+ * Developer. Consumers may render unavailable rows with an upgrade
+ * badge, hide them, or otherwise gate UI on the flag.
  */
-export type SystemRoleIds = {
-  owner: string;
-  admin: string;
-  developer: string;
-  member: string;
+export type SystemRole = {
+  id: string;
+  name: string;
+  description: string;
+  available: boolean;
 };
 
 export type Permission = {
@@ -119,11 +127,16 @@ export interface RoleBaseAccessController {
     check: { action: string; resource: RbacResource | RbacResource[] }
   ): Promise<SessionAuthResult>;
 
-  // Stable IDs for the four built-in system roles. Returns null when
-  // no plugin is installed — there are no seeded roles to refer to in
-  // that case (the default fallback's `allRoles` returns []). Plugins
-  // return the constants tied to their seed migration.
-  systemRoleIds(): Promise<SystemRoleIds | null>;
+  // Plugin-owned catalogue of built-in system roles for the given org,
+  // in canonical order (highest authority first). Returns null when no
+  // plugin is installed — there are no seeded roles to refer to in that
+  // case (the default fallback's `allRoles` returns []).
+  //
+  // Hidden roles (e.g. Member in v1) are filtered out entirely. Each
+  // entry's `available` flag reflects whether the org's plan permits
+  // assigning that role; consumers can render unavailable entries with
+  // an upgrade badge or hide them.
+  systemRoles(organizationId: string): Promise<SystemRole[] | null>;
 
   // Role introspection. The fallback returns []; a plugin may return
   // its own role catalogue.