feat(roles): gate custom role creation behind the CUSTOM_ROLES entitlement

Merged
ET
21d ago
+320-14

Summary

Follow-up to #28218, which gated assigning a custom role but left creating one open: on staging a Pro V2 workspace could still create custom roles, then hit the paywall only when assigning them.

The gate lives in the role migration validator, next to the assignment gate, so every non-system build goes through it: Settings, the API, the AI role tools and app installs.

 FlatRoleValidatorService.validateFlatRoleCreation
+  validateRoleIsEntitled(role)

 FlatRoleValidatorService.validateFlatRoleUpdate
+  if !doesRoleRequireCustomRolesEntitlement(fromRole)
+    validateRoleIsEntitled(toRole)

+validateRoleIsEntitled(role)
+  system build, or !doesRoleRequireCustomRolesEntitlement(role), or CUSTOM_ROLES  -> []
+  otherwise -> CUSTOM_ROLES_NOT_ENTITLED

+doesRoleRequireCustomRolesEntitlement(role)
+  Admin or Member (NON_CUSTOM_ROLE_UNIVERSAL_IDENTIFIERS)  -> false
+  otherwise -> canBeAssignedToUsers || canBeAssignedToApiKeys
  • Agent-only roles stay open. Agents can't take Admin or Member, and the agent Role tab and workflow AI agent permissions create their role through createOneRole with canBeAssignedToUsers: false and canBeAssignedToApiKeys: false. Same exemption as the assignment gate. In Settings they are created from the agent Role tab, which stays enabled on every plan.
  • Member stays open. Workspace activation and the 2.50 backfill create it through createRole.
  • Updates are only checked when they make an agent-only role assignable to members or API keys, so existing custom roles (for example after a downgrade), and existing app roles on app upgrade, stay editable.
  • App roles are gated too. An app role only needs member or API key assignability when the app ships it for workspace members or API keys, which is a custom role. Every public app already declares its function role with both flags false. App manifests default both flags to true, so the twenty app init template, examples/hello-world and examples/document-generator now declare them false (the roles docs already showed them that way), and the docs note the plan requirement.
  • Admin and Member now come from one NON_CUSTOM_ROLE_UNIVERSAL_IDENTIFIERS constant, shared with validateFlatRoleTargetRoleIsEntitled.
  • Self-host is unaffected: CUSTOM_ROLES is granted without billing.

Settings, roles list footer:

 <TableFooter>
+  {!hasCustomRolesEntitlement && <OrganizationAdornment tooltipContent="Upgrade to Organization to create custom roles" />}
-  <Button>Create Role</Button>
+  <Button disabled={!hasCustomRolesEntitlement}>Create Role</Button>

Evidence

  • failing-custom-role-assignment-without-entitlement.integration-spec.ts (entitlement forced to false):
    • Before: createOneRole({ label }) succeeds.
      After: refused with METADATA_VALIDATION_FAILED / CUSTOM_ROLES_NOT_ENTITLED (snapshot).
    • Before: an agent-only role updated with canBeAssignedToUsers: true succeeds.
      After: refused with the same error (snapshot).
    • An existing custom role is still editable. The existing "agent only role" case now sets canBeAssignedToApiKeys: false (the flag defaults to true), so it also proves an agent-only role is still created without the entitlement.
  • Unit: does-role-require-custom-roles-entitlement.util.spec.ts covers the cases the integration spec doesn't: API-key-only and Member.
  • Stories: SettingsRolesList CreateRoleWithCustomRolesEntitlement (button enabled, no pill) and CreateRoleWithoutCustomRolesEntitlement (button disabled, Organization pill).

Merge Danger

Door: two-way

Blast Radius: role creation, app installs

A cloud workspace without CUSTOM_ROLES (Pro V2, or any workspace missing the entitlement row) can no longer create a member or API key role, or make an agent-only role assignable to members or API keys, from Settings, the API, the AI role tools or an app install. Existing custom roles and existing app roles stay editable. An app whose manifest omits canBeAssignedToUsers / canBeAssignedToApiKeys on a role (both default to true) no longer installs on those workspaces until it sets them false. The create page is still reachable by URL; saving fails with the upgrade message.