Custom Roles

Frontend

API Endpoints

All under /api/roles, require authentication.

Permission Constraints

Ceiling: ADMIN's permissions

private static final Set<Permission> MAX_ALLOWED_PERMISSIONS = Role.ADMIN.getPermissions();

Custom roles CANNOT include PLATFORM permissions or permissions not held by ADMIN.

Floor: Base member permissions (auto-added)

private static final Set<Permission> BASE_MEMBER_PERMISSIONS = Set.of(
    Permission.MEMBER_VIEW_OWN,
    Permission.MEMBER_EDIT_OWN,
    Permission.DONATION_VIEW_OWN,
    Permission.PLEDGE_VIEW_OWN
);

These are always guaranteed regardless of what the admin selects.

Denomination HQ permissions

Only shown and assignable if the current church is a denomination headquarters. Checked via: denominationRepository.findByHeadquartersChurchId(churchId).isPresent()

Privilege escalation guard

CustomRoleService.validatePermissions() throws PrivilegeEscalationException if:

• Any permission has category PLATFORM
• Any permission has category DENOMINATION_HQ and church is not the denomination HQ
• Any permission is not in MAX_ALLOWED_PERMISSIONS

Permission Display Names

All display names live in PERMISSION_DISPLAY_NAMES in interfaces/custom-role.ts.

Naming rules (MUST follow consistently)

• Use the scope qualifier (Fellowship/Own/Public/Assigned) without appending "Only" — the qualifier already implies restriction
• Scoped permissions use pattern: {Verb} {Scope} {Resource} e.g. View Fellowship Attendance
• MANAGE permissions include parenthetical: Manage Households (Create, Edit, Delete)
• ALL-scoped permissions include "All": View All Members

Scope pattern examples

Adding a new permission display name

1. Add to PERMISSION_DISPLAY_NAMES in interfaces/custom-role.ts
2. Ensure getPermissionCategory() handles the permission's prefix
3. Add the permission to Permission.java (backend enum) with Javadoc
4. Add to Role.java (at minimum ADMIN role)
5. Add to frontend permission.enum.ts with exact same name

Permission Categories

Defined in getPermissionCategory() in interfaces/custom-role.ts:

Role Name Normalization

Names are normalized on save: toUpperCase().replace(" ", "_").replace("-", "_")

Custom role names CANNOT conflict with built-in role names (ADMIN, PASTOR, TREASURER, etc.).

Uniqueness is enforced per church: existsByChurch_IdAndNameIgnoreCase(churchId, normalizedName).

Permission Cache

CustomRoleService uses a ConcurrentHashMap<String, Set<Permission>> keyed by "churchId:roleId".

• Cache is populated on first call to getPermissionsForRole()
• Invalidated when: permissions updated, role activated/deactivated, role deleted
• Inactive roles always return Collections.emptySet() (not cached)
• Call customRoleService.clearCache() in tests that modify roles

Delete Behaviour

When a custom role is deleted:

1. All users assigned to it have customRole set to null
2. Their role is set to Role.MEMBER
3. Permission cache is invalidated
4. Users lose all custom permissions immediately

Frontend RoleSummary Interface

Used for dropdowns (user assignment, user creation):

interface RoleSummary {
  id: string;           // "ADMIN" for built-in, "custom:123" for custom
  name: string;         // Normalized name e.g. "WORSHIP_TEAM"
  displayName: string;  // Human-friendly e.g. "Worship Team"
  description?: string;
  isBuiltIn: boolean;
  isEditable: boolean;
  permissionCount: number;
}

Identify custom roles by checking !role.isBuiltIn or role.id.startsWith('custom:').

Common Bugs to Avoid

1. Missing cache invalidation — always call invalidateCache() after any permission or active-status change
2. Assuming base permissions are optional — they are always auto-added; don't show them as user-configurable
3. Exposing PLATFORM permissions in the picker — filter them out via getAvailablePermissions()
4. Allowing duplicate role names — the service validates uniqueness, but frontend should show the field-level error from DuplicateRoleException
5. Treating inactive roles as having permissions — inactive roles return empty set; always check role.isActive in UI
6. Displaying "My" instead of "Assigned" — use consistent qualifier pattern in display names
7. Adding "Only" suffix to scoped display names — the qualifier word already implies restriction