RBAC Endpoint-Role Management

Overview

The RBAC Endpoint-Role Management provides API endpoints for dynamically managing role-based access control permissions. These endpoints enable the Corebanq Configurator UI to:

1. Discover endpoints that need role assignments
2. Assign roles to endpoints without editing YAML files
3. Remove role assignments
4. Export current permissions back to seed files

YAML seed format and $DATA_DIR/rbac/ layout: seed_authoring.md. Module index: README.md.

Key Features

• Real-time Permission Management: Change endpoint access without restarting the server
• Audit Trail: All permission changes are tracked by the blame package
• Security Controls:
  • Protected endpoints can only be accessed by Administrator role
  • Cannot assign non-Administrator roles to RBAC management endpoints
  • Cannot remove Administrator role from any endpoint
  • Automatic cache invalidation on permission changes
• YAML Export: Generate seed files from current database state

Security Notes

Protected Endpoints

The following endpoint patterns are protected and can ONLY be assigned the Administrator role:

• /v1/rbac/endpoint-role/* - Endpoint-role management operations
• /v1/user-roles* - User-role assignment operations
• /v1/roles* - Role management operations

Why? These endpoints control the permission system itself. Allowing non-Administrator roles to access them would enable privilege escalation attacks.

Error Response when attempting to assign non-admin roles to protected endpoints:

{
  "error": "Cannot assign non-Administrator roles to protected endpoint /v1/rbac/endpoint-role/assign. This endpoint controls the permission system and must remain Administrator-only.",
  "code": "403"
}

Audit Logging

Permission changes are tracked by the blame package with:

• Actor identity (user ID and username)
• Endpoint details (ID, path, method)
• Action type
• Affected role
• Request ID for correlation
• Timestamp

Cache Invalidation

When permissions are modified:

1. All affected users' permission caches are automatically cleared
2. Users get fresh permissions on their next API request
3. No server restart required

API Endpoints

Get Unassigned Endpoints

GET /v1/rbac/endpoint-role/unassigned

Returns all API endpoints that currently only have Administrator role access. These endpoints are candidates for role assignment.

Response Example:

[
  {
    "endpoint": "/v1/new-feature",
    "method": "GET",
    "roles": ["Administrator"],
    "is_unassigned": true
  },
  {
    "endpoint": "/v1/beta-endpoint",
    "method": "POST",
    "roles": ["Administrator"],
    "is_unassigned": true
  }
]

Use Case: After deploying new features, scan for endpoints that need role configuration.

Get All Endpoint Permissions

GET /v1/rbac/endpoint-role/endpoints

Returns all API endpoints with their currently assigned roles.

Response Example:

[
  {
    "endpoint": "/v1/customers",
    "method": "GET",
    "roles": ["Administrator", "User", "StandardUser"],
    "is_unassigned": false
  },
  {
    "endpoint": "/v1/accounts",
    "method": "POST",
    "roles": ["Administrator", "User"],
    "is_unassigned": false
  }
]

Use Case: View complete RBAC configuration across all modules.

Assign Roles to Endpoint

POST /v1/rbac/endpoint-role/assign

Assigns one or more roles to a specific endpoint. This is additive - existing role assignments are preserved.

⚠️ Important: This operation is atomic - if ANY role fails to assign (e.g., role not found), the ENTIRE operation is rejected and NO roles are assigned. This prevents partial/inconsistent permission states.

Request Body:

{
  "endpoint": "/v1/customers",
  "method": "GET",
  "roles": ["User", "StandardUser"]
}

Success Response (200):

{
  "message": "Roles assigned successfully",
  "endpoint": "/v1/customers",
  "method": "GET",
  "roles": ["User", "StandardUser"]
}

Error Response - Invalid Roles (400):

{
  "error": "Failed to assign roles to endpoint: InvalidRole, NonExistentRole (assigned 0/3)",
  "code": "400",
  "params": {
    "failed_roles": "InvalidRole, NonExistentRole",
    "success_count": 0,
    "total_count": 3
  }
}

Use Case: Grant access to new user roles for an endpoint. All specified roles must be valid or the operation fails.

Remove Role from Endpoint

POST /v1/rbac/endpoint-role/remove

Removes a specific role's access from an endpoint. Administrator role cannot be removed (safety protection).

Request Body:

{
  "endpoint": "/v1/customers",
  "method": "GET",
  "role": "StandardUser"
}

Response:

{
  "message": "Role removed successfully",
  "endpoint": "/v1/customers",
  "method": "GET",
  "role": "StandardUser"
}

Error Response (trying to remove admin):

{
  "error": "Cannot remove Administrator role from endpoints",
  "code": 403
}

Use Case: Revoke access when a role should no longer have permission to an endpoint.

Export Endpoint to Seed YAML

GET /v1/rbac/endpoint-role/export/{method}/{endpoint}

Generates a YAML seed snippet for the current permissions of a specific endpoint. Useful for updating seed files after UI changes.

Parameters:

• method (path): HTTP method (GET, POST, PUT, PATCH, DELETE)
• endpoint (path): Endpoint path (URL-encoded)

Example Request:

GET /v1/rbac/endpoint-role/export/GET/%2Fv1%2Fcustomers

Response (text/yaml):

  - endpoint: /v1/customers
    method: GET
    roles:
      - User
      - StandardUser
    description: "GET /v1/customers"

Use Case: Export permissions after UI configuration to commit to version control.

Sync Endpoints

POST /v1/rbac/endpoint-role/sync

Returns count of currently registered endpoints. Full endpoint sync requires server restart (routes are registered on startup).

Response:

{
  "message": "Endpoints synced successfully",
  "count": 245
}

Use Case: Verify endpoint count after deployments.

Available Roles

Note: Administrator role is automatically granted to all endpoints and cannot be removed.

Workflow Example

Scenario: New Feature Deployment

1. Deploy new API module with endpoints

   • Server automatically registers endpoints with admin-only access

2. Scan for unassigned endpoints

   GET /v1/rbac/endpoint-role/unassigned

   Returns: /v1/new-feature (GET, POST)

3. Assign roles via UI

   POST /v1/rbac/endpoint-role/assign
   {
     "endpoint": "/v1/new-feature",
     "method": "GET",
     "roles": ["User", "StandardUser"]
   }

4. Export to seed file (optional)

   GET /v1/rbac/endpoint-role/export/GET/%2Fv1%2Fnew-feature

Copy YAML output to .runtime/data/rbac/new_module.rbac.yaml

5. Verify access by testing with different role accounts

Security

Authorization

All configurator endpoints require Administrator role. Non-admin users receive 403 Forbidden.

Audit Logging

Permission changes are tracked by the blame package. All modifications include:

• request_id - For traceability
• actor_id - Who made the change
• endpoint and method - What was changed
• roles - Which roles were affected

Example Log:

INFO: Assigned 2 roles to GET /v1/customers 
  request_id=abc-123 actor_id=uuid-456 roles=[User, StandardUser]

Safety Mechanisms

• ✅ Administrator role cannot be removed from any endpoint
• ✅ Protected endpoints (RBAC management, user-roles, roles) can ONLY be assigned Administrator role
• ✅ Cache automatically invalidated when permissions change
• ✅ Atomic role assignment - if ANY role fails, the entire operation is rejected (no partial success)
• ✅ Detailed error responses include which roles failed and success/total counts
• ✅ Missing endpoints return 404 errors
• ✅ All database operations use parameterized queries (SQL injection safe)

Integration with Seed Files

The configurator works alongside $DATA_DIR/rbac/{module}.rbac.yaml seeds (see seed_authoring.md):

RBAC seeds do not use *.diff.yaml — edit the full module file or export from Configurator.

Error Codes

Performance

• Permission Changes: Instant (no server restart required)
• Cache Behavior: Permissions cached per-user, refreshed on next request
• Database Impact: Minimal - single UPDATE/INSERT per role assignment
• Scalability: Configurator endpoints are admin-only (low traffic)

Best Practices

DO:

✅ Use configurator for quick permission adjustments
✅ Export changes to seed files for version control
✅ Test with different role accounts after changes
✅ Review unassigned endpoints after deployments
✅ Use seed files for bulk/initial permissions

DON'T:

❌ Remove Administrator role (it's auto-granted anyway)
❌ Make production changes without testing in staging
❌ Forget to export important changes to seed files
❌ Assign roles to endpoints that don't exist yet

Related Documentation

• Seed authoring: seed_authoring.md
• Core RBAC API: rbac.mdx
• OpenAPI: rbac_configurator.openapi.json, rbac.openapi.json