feat(billing): gate custom roles behind the CUSTOM_ROLES entitlement
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
billingEntitlementsjoinsWORKSPACE_MIGRATION_ADDITIONAL_CACHE_DATA_MAPS_KEYand is required, so every from/to caller passes it. That includes the released 2.43provision-agent-chat-thread-targetcommand and one 2.42 and one 2.43 spec: typing-only edits, hence theci:allow-previous-version-upgrade-mutationlabel.ApiKeyResolvergetsWorkspaceMigrationGraphqlApiExceptionInterceptor, otherwise a refused API key role surfaced as an internal error.- The dev seeder writes
CUSTOM_ROLES = truewhen billing is seeded, since it assigns custom roles (Guest, limited, impersonate-only).
Before shipping
- Merge after
twenty/v2.50.0is 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_ROLESStripe feature is attached to the Organization and grandfathered plans, andbilling:sync-entitlementshas 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.