# Role-Based Access Control

## Overview

Role-Based Access Control (RBAC) implements a permission-to-role-to-user authorization model. Each Role holds a `permissions` array of permission key strings. Administrators manage permissions directly on roles, and assign roles to users. A user's effective permissions are the union of all permissions from all their assigned roles, and are non-empty only while the user is ACTIVE.

## Business Purpose

Organizations need granular access control that scales with team size:

- **Simplified Administration**: Administrators manage permissions directly on roles
- **Consistency**: All users with the same role have identical permissions
- **Auditability**: Clear mapping from user to roles to permissions supports compliance reviews
- **Scalability**: Adding new users requires only role assignment, not permission configuration

## Process Flow

```mermaid
flowchart TD
    A[Admin creates Role] --> B[Admin grants permissions to Role]
    B --> C[Role has permissions]

    D[Admin assigns Role to User] --> E{User INACTIVE?}
    E -->|Yes| F[Return Error: USER_NOT_ACTIVE]
    E -->|No| G[User has Role]
    G --> H[Executor computes effective permissions]

    subgraph Permission Check
    I[Check User Permission] --> J[Get User's Roles]
    J --> K[Collect all permissions from roles]
    K --> L{Has Required Permission?}
    L -->|Yes| M[Access Granted]
    L -->|No| N[Access Denied]
    end
```

## Scenario Patterns

- **Role Configuration**: Administrator creates "Sales Manager" role and grants permissions such as `sales:salesOrder:create` and `sales:customer:read`. The role directly holds these permission keys.
- **User Role Assignment**: New sales hire is assigned "Sales Representative" role. User immediately inherits all permissions from the roles assigned to them.
- **Role Promotion**: Sales rep promoted to manager. Administrator assigns "Sales Manager" role which has broader permissions.
- **Role Revocation**: User transfers to different department. Administrator revokes current role and assigns appropriate role for new position.
- **Idempotent Assignment**: Assigning the same role to a user twice does not create duplicate assignments or return an error.
- **Inactive User Restriction**: Attempt to assign role to an INACTIVE user fails; reactivate first. PENDING users may be assigned roles.
- **Role Rename**: Administrator renames "Sales Rep" role to "Sales Associate". All existing assignments remain intact.

## Test Cases

- Creating a role with valid name should succeed
- Granting a permission to an ACTIVE role should succeed
- Granting the same permission to a role twice should be idempotent (no error)
- Assigning role to ACTIVE user should succeed
- Assigning role to PENDING user should succeed (permissions dormant until activation)
- Assigning role to INACTIVE user should fail with USER_NOT_ACTIVE error
- Assigning same role to user twice should be idempotent (no error)
- Revoking a permission from a role should remove it from the permissions array
- Revoking role from user should remove the user-role association
- Assigning role to non-existent user should fail with USER_NOT_FOUND error
- Assigning non-existent role to user should fail with ROLE_NOT_FOUND error
- Granting an invalid-format permission to a role should fail with INVALID_PERMISSION error

## Reference Links

- [NIST RBAC Model](https://csrc.nist.gov/projects/role-based-access-control)
- [Odoo Access Rights](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html)
- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)