Add Role-Based Access Control (RBAC): roles, permissions, RolesGuard, and admin role management

[memplethee-lab]

Summary

What: Implement role-based access control (RBAC) with scopes and permissions for API endpoints and administrative operations.
Why: Enables secure multi-tenant or team-based workflows and reduces risk from over-privileged tokens.
Which part: auth module, guards, controllers, user and role models.

Problem Statement

Current limitation

• The codebase lacks a structured RBAC system; authorization is inconsistent or coarse-grained.

Pain point

• Hard to build secure admin UIs, automation, or team workflows; risk of overly permissive tokens.

Why it matters

• Proper RBAC is essential for production deployments, enterprise use, and secure open-source contributions.

Proposed Solution

How it should work

• Introduce roles and permissions models in the auth/user domain (Role entity, Permission enum/lookup table).
• Create a RolesGuard that checks JWT scopes/claims and route metadata (Roles decorator) to enforce permissions.
• Provide migration scripts to seed default roles (admin, maintainer, contributor, read-only).
• Add endpoints for role management (create/assign/remove role) accessible to admin role only.

Expected behavior

• Endpoints decorated with @roles('admin') are restricted; non-admins receive 403.
• Roles assigned in DB reflect downstream token claims.

Important notes

• Integrate with existing auth/jwt strategy; avoid breaking current tokens by mapping claims to roles.

Implementation Guidance

Files/folders likely affected

• src/auth/*
• src/common/guard/*
• src/user/* or src/auth/entities/*
• migrations/*

Modules/Services involved

• Auth module, user service, guards, DTOs

Dependencies/prerequisites

• Existing JWT auth strategy (must adapt), TypeORM migrations

Suggested steps

1. Add Role and Permission entities or enums.
2. Implement Roles decorator and RolesGuard in src/common/guard.
3. Seed default roles via migration.
4. Add admin-only role-management endpoints.
5. Document RBAC setup and how to map token claims.

Acceptance Criteria

Acceptance Criteria

• Role and permission data model implemented
• RolesGuard enforces permissions based on JWT claims or DB lookup
• Migrations seed default roles
• Admin endpoints for role management exist
• Documentation updated with RBAC usage and migration instructions
• Unit tests added for RolesGuard and admin endpoints
• Feature passes linting and existing CI checks

Technical Notes

API changes

• Adds role management endpoints; ensure tokens map to roles without breaking auth
  Database changes
• Adds roles (and possibly permissions) tables and migrations
  Security
• Ensure role assignment restricted to admins; validate input to avoid privilege escalation
  Performance
• Cache role lookups to avoid DB hits on each request if necessary
  Accessibility
• N/A
  Edge cases
• Backwards compatibility for tokens without role claims: map to default read-only role

Definition of Done

• All acceptance criteria met
• Tests added and passing
• Documentation updated

Labels

• enhancement, backend, security, api

Priority

• Medium

Estimated Difficulty

• Advanced

Estimated Effort

• L