Role Management & Authorization APIs

[manjik-rumsan]

Title

Implement Role Management and Project-Scoped Authorization APIs

Description

This issue tracks the implementation of role management and authorization APIs to support project-scoped permissions in the Rahat Platform. The system allows roles to be assigned to users within specific project contexts, enabling fine-grained access control.

Background

• Users can have different roles in different projects (e.g., Project Manager in Project A, Viewer in Project B)
• Roles are reusable templates containing permissions
• Permissions are defined using CASL (action, subject, conditions)
• UserRole assignments can be project-scoped (projectId) or system-wide (projectId: null)

Database Schema

Role: id, name, isSystem, expiry
Permission: id, roleId, action, subject, inverted, conditions, reason
UserRole: id, userId, roleId, projectId, expiry

Tasks

1. Core Role CRUD

• POST /api/roles - Create new role
  • Body: { name, isSystem, description }
  • Response: Created role object
• GET /api/roles - List all roles
  • Query params: ?page=1&limit=10&isSystem=true
  • Response: Paginated list of roles
• GET /api/roles/:roleId - Get role details with permissions
  • Response: Role object with nested permissions array
• PUT /api/roles/:roleId - Update role metadata
  • Body: { name, description, isSystem }
  • Response: Updated role object
• DELETE /api/roles/:roleId - Delete role
  • Should fail if role has active assignments
  • Response: { success: true }

2. Permission Management for Roles

• POST /api/roles/:roleId/permissions - Add permission to role
  • Body: { action, subject, inverted, conditions, reason }
  • Response: Created permission object
• GET /api/roles/:roleId/permissions - List role permissions
  • Response: Array of permission objects
• PUT /api/permissions/:permissionId - Update permission
  • Body: { action, subject, inverted, conditions, reason }
  • Response: Updated permission object
• DELETE /api/permissions/:permissionId - Delete permission
  • Response: { success: true }
• POST /api/roles/:roleId/permissions/bulk - Bulk add permissions
  • Body: { permissions: [{ action, subject, ... }, ...] }
  • Response: Array of created permissions
• DELETE /api/roles/:roleId/permissions/bulk - Bulk delete permissions
  • Body: { permissionIds: [1, 2, 3] }
  • Response: { deleted: 3 }

3. User Role Assignment APIs

Project-Scoped Assignments

• POST /api/projects/:projectId/users/:userId/roles - Assign role to user in project
  • Body: { roleId, expiry? }
  • Response: Created UserRole object
• GET /api/projects/:projectId/users/:userId/roles - Get user's roles in project
  • Response: Array of UserRole objects with role details
• DELETE /api/projects/:projectId/users/:userId/roles/:roleId - Remove role from user in project
  • Response: { success: true }
• PUT /api/projects/:projectId/users/:userId/roles/:roleId - Update role assignment
  • Body: { expiry }
  • Response: Updated UserRole object

4. User Role Query APIs

User-Centric Queries

• GET /api/users/:userId/roles - Get all user's role assignments
  • Query params: ?includeExpired=false&projectId=xyz
  • Response: Array of UserRole objects with project and role details
• GET /api/users/:userId/roles/active - Get only active role assignments
  • Filters out expired roles and assignments
  • Response: Array of active UserRole objects
• GET /api/users/:userId/permissions - Get flattened permissions across all projects
  • Response: { permissions: [...], rolesByProject: {...} }
• GET /api/users/:userId/projects/:projectId/permissions - Get user permissions in specific project
  • Response: Array of permission objects applicable in this project

5. Project-Centric Queries

• GET /api/projects/:projectId/users - List all users with roles in project
  • Query params: ?roleId=5&includeExpired=false
  • Response: Array of users with their role assignments
• GET /api/projects/:projectId/roles - List unique roles assigned in project
  • Response: Array of roles with user count for each
• GET /api/projects/:projectId/roles/:roleId/users - List users with specific role in project
  • Response: Array of users
• GET /api/projects/:projectId/users/:userId/abilities - Get user's computed abilities in project
  • Response: { rules: [...CASL rules...] }
• GET /api/projects/:projectId/team - Get complete team roster
  • Response: Array of users with roles, permissions, and metadata

Technical Requirements

Validation

• Role names must be unique
• Cannot delete roles with active assignments
• Permission action and subject are required
• ProjectId must exist when assigning project-scoped roles
• User must exist when creating assignments

Authorization

• Only admins can create/update/delete roles and permissions
• Project managers can assign roles within their projects
• System-wide role assignments require super admin

Error Handling

• Return appropriate HTTP status codes (400, 403, 404, 500)
• Include meaningful error messages
• Handle database constraint violations gracefully