feat(billing): gate custom roles behind the CUSTOM_ROLES entitlement

Merged
ET
1mo ago
+718-100

Summary

Second half of the custom roles split. #28291 (merged, ships in 2.50) prepared the Member identity, the self-host grant and atomic role deletion. Custom roles move behind the CUSTOM_ROLES billing entitlement: without it, a workspace member or an API key can only get Admin or Member. Agents are exempt. Existing assignments are left alone; only new or changed role targets are checked.

 FlatRoleTargetValidatorService (create, and update when the role changes)
   validateFlatRoleTargetAssignationAvailability
+  validateFlatRoleTargetRoleIsEntitled
+    system build                         -> ok
+    agent target                         -> ok
+    role is Admin or Member              -> ok
+    billingEntitlements.CUSTOM_ROLES     -> ok
+    otherwise                            -> CUSTOM_ROLES_NOT_ENTITLED

This covers member role updates, invitations, API key create and reassign, and the default-role rebind on role deletion. Agent targets are exempt (custom agents, workflow AI agent steps, app agents such as Slack and Teams): Admin and Member can't be assigned to agents, so gating them would leave agents with no role and no CRM tools.

Refused before anything is saved

RoleAssignmentValidationService.validateRoleAssignableToUsersOrThrow (renamed from RoleValidationService) applies the same rule and throws PermissionsException CUSTOM_ROLES_NOT_ENTITLED (403). It runs:

  • when sending an invitation;
  • when changing a member's role;
  • when changing the workspace default role (updateWorkspace), so a workspace without the entitlement can't pick a custom default;
  • in resolveRoleIdForNewMember, for the invited role and the workspace default role.

Before, joining with a refused role saved userWorkspace and workspaceMember and then failed on assignment, and a retry returned early, leaving a member without a role.

Plumbing

  • billingEntitlements joins WORKSPACE_MIGRATION_ADDITIONAL_CACHE_DATA_MAPS_KEY and is required, so every from/to caller passes it. That includes the released 2.43 provision-agent-chat-thread-target command and one 2.42 and one 2.43 spec: typing-only edits, hence the ci:allow-previous-version-upgrade-mutation label.
  • ApiKeyResolver gets WorkspaceMigrationGraphqlApiExceptionInterceptor, otherwise a refused API key role surfaced as an internal error.
  • The dev seeder writes CUSTOM_ROLES = true when billing is seeded, since it assigns custom roles (Guest, limited, impersonate-only).

Before shipping

  • Merge after twenty/v2.50.0 is tagged, so this ships in 2.51 and not alongside #28291.
  • #28291 is deployed and its 2.50 workspace upgrade (Member identifier backfill) finished on cloud. Otherwise Member reads as a custom role.
  • The CUSTOM_ROLES Stripe feature is attached to the Organization and grandfathered plans, and billing:sync-entitlements has run.

Evidence

failing-custom-role-assignment-without-entitlement.integration-spec.ts runs with billing off and snapshots the GraphQL refusals: it forces the cached entitlement to false instead of writing billing rows, because integration runs never enable billing. It covers:

  • member role update and API key refused;
  • an agent with a custom role still created;
  • a custom default role, and a default role users can't be assigned, refused on updateWorkspace;
  • a new user joining with a custom invited role or default role refused, with no membership saved (the default-role case fails without the fix);
  • Admin and Member still assignable;
  • a member saved again on their existing custom role keeps it (no entitlement needed for a no-op).

Unit: validate-flat-role-target-role-is-entitled.util.spec.ts, including the agent exemption.

Merge Danger

Door: two-way

Blast Radius: permissions. A missing entitlement row reads as denied: a cloud workspace without CUSTOM_ROLES can no longer give a custom role to a member or an API key. On those plans an API key can only get Admin, since Member can't be assigned to API keys. Such a workspace can't pick a custom default role, and one that already has a custom default (for example after a downgrade) can't add members until that role changes.