feat(roles): prepare custom roles gating (Member identity, self-host grant, atomic role deletion)

Merged
ET
1mo ago
+937-170

Summary

First half of the custom roles split. It prepares everything the CUSTOM_ROLES gate (#28218) needs, but nothing in this PR refuses an assignment.

Entitlement key and self-host grant

  • New BillingEntitlementKey.CUSTOM_ROLES, also added to the generated SDK and front enums.
  • ENTITLEMENT_KEYS_GRANTED_WITHOUT_BILLING = [CUSTOM_ROLES]:
    • With billing off, the entitlements cache returns exactly those keys as true (before: {}).
    • isEntitlementActive takes the key and returns hasValidEnterprisePlan || key in list when billing is off, so workspace.billingEntitlements agrees: self-hosted keeps custom roles without an enterprise key.
    • Cloud and every other key are unchanged.

Member gets a fixed identity

  • MEMBER_ROLE_UNIVERSAL_IDENTIFIER (in twenty-shared/constants, read by front and server), stamped by createMemberRole. WorkspaceManagerService now finds Member by it instead of its label.
  • 2.50 workspace command upgrade:2-50:backfill-member-role-universal-identifier:
    • stamps the custom-app role labelled Member, or creates Member when the workspace has none;
    • creates it as Workspace Member when an installed application already owns a role labelled Member (labels are unique across the workspace, so reusing Member would fail and block the upgrade);
    • supports --dry-run.
  • Member can no longer be deleted (MEMBER_ROLE_CANNOT_BE_DELETED in FlatRoleValidatorService).
  • Settings disables Delete role for Member and for the workspace default role, both refused server-side, and the Danger zone says why. Member stays editable, so isEditable can't carry this. RoleFragment now selects universalIdentifier.

Role deletion runs as one migration

  • deleteManyRoles used to move users, API keys and agents to the default role through separate committed migrations, then validate the deletion.
  • Now it moves every target of the deleted roles to the default role in the same validateBuildAndRunWorkspaceMigration call as the deletion.
  • Any validator refusal aborts everything. That includes an API key or agent that the default role can't take: those used to fail only after members had already been moved.
  • Revoked API keys are skipped, as before.
  • The rebind loops and the two PermissionsException codes only they threw (ROLE_CANNOT_BE_ASSIGNED_TO_API_KEYS / _AGENTS) are removed. The refusal now comes from the role target validator as ROLE_CANNOT_BE_ASSIGNED_TO_ENTITY.

Rollout

  1. Ship this PR in 2.50 and confirm the 2.50 workspace upgrade finished on cloud (admin Upgrade Status).
  2. Attach the CUSTOM_ROLES Stripe feature to the Organization and grandfathered plans, then run billing:sync-entitlements.
  3. Ship #28218, the gate, in the next release.

Evidence

  • Backfill stamps an existing Member, creates one when missing, and falls back to Workspace Member when an application owns Member (2-50-...-backfill-member-role-universal-identifier.integration-spec.ts). Without the fallback, that last case fails role validation.
  • Deleting Member fails and leaves its members in place (failing-delete-member-role.integration-spec.ts).
  • Deleting a role that still has a member and an API key:
    • refused while the key can't move to Member, with nothing moved;
    • succeeds once the key is revoked, and the member ends up on the default role (successful-delete-one-role.integration-spec.ts).
  • The Admin deletion snapshot now shows the validator errors (failing-delete-one-role).
  • With billing off, the cache returns { CUSTOM_ROLES: true } (billing-entitlements-cache).
  • Unit: is-entitlement-active.util.spec.ts.
  • SettingsRoleSettings stories: Delete role is disabled for Member and for the default role, and stays enabled for an ordinary editable role.

Merge Danger

Door: two-way

Blast Radius: role deletion and the Member role. Deleting a role whose API keys or agents can't move to the default role is still refused, now without side effects. Member becomes undeletable.