# Role Permission Management

## Overview

Role Permission Management enables administrators to grant and revoke individual permission keys directly on the Role model. Each role holds a `permissions` array of strings. Administrators can manage permissions via `grantPermissionToRole` / `revokePermissionFromRole` commands for individual changes, or set them in bulk via `createRole` / `updateRole`.

When permissions change, an executor recomputes effective permissions for all users assigned to the role. Only ACTIVE roles can receive permission grants.

## Business Purpose

Organizations need permission management that is simple, flexible, and auditable:

- **Simplicity**: No intermediate entities — permissions live directly on the Role as a flat array
- **Flexibility**: Any combination of permission keys can be assigned without predefined groups
- **No seed data overhead**: Adding a new module or command automatically makes it available for assignment
- **Auditability**: Permission changes on a role are directly traceable

## Process Flow

```mermaid
flowchart TD
    A[Grant Permission to Role] --> B{Permission key format valid?}
    B -->|No| C[Return Error: INVALID_PERMISSION]
    B -->|Yes| D{Role exists?}
    D -->|No| E[Return Error: ROLE_NOT_FOUND]
    D -->|Yes| F{Role ACTIVE?}
    F -->|No| G[Return Error: ROLE_NOT_ACTIVE]
    F -->|Yes| H{Permission already in array?}
    H -->|Yes| I[Return success - idempotent]
    H -->|No| J[Add permission to role's permissions array]
    J --> K[Executor recomputes effective permissions for affected users]
    K --> L[Grant Complete]
```

```mermaid
flowchart TD
    A[Revoke Permission from Role] --> B{Role exists?}
    B -->|No| C[Return Error: ROLE_NOT_FOUND]
    B -->|Yes| D{Permission in array?}
    D -->|No| E[Return Error: PERMISSION_NOT_FOUND]
    D -->|Yes| F[Remove permission from role's permissions array]
    F --> G[Executor recomputes effective permissions for affected users]
    G --> H[Revocation Complete]
```

## Scenario Patterns

- **Single Permission Grant**: Administrator grants a permission to a role. The executor recomputes effective permissions for users with that role.
- **Multi-Module Permission Setup**: Administrator grants permissions from different modules to a role. Effective permissions are the union of all permission keys across all assigned roles.
- **Permission Revocation**: Administrator revokes a permission from a role. The executor recomputes effective permissions.
- **Idempotent Grant**: Granting the same permission twice does not create duplicates or return an error.
- **Inactive Role Rejection**: Granting a permission to an inactive role returns ROLE_NOT_ACTIVE error.
- **Bulk Permission Setup**: Administrator sets permissions via `createRole` or `updateRole` for initial setup or bulk changes.

## Test Cases

- Granting a valid permission key to an ACTIVE role should succeed
- Granting a permission should add it to the role's permissions array
- Granting an invalid permission key format should fail with INVALID_PERMISSION error
- Granting a permission to a non-existent role should fail with ROLE_NOT_FOUND error
- Granting a permission to an INACTIVE role should fail with ROLE_NOT_ACTIVE error
- Granting the same permission twice should be idempotent (no error, no duplicates)
- Revoking a permission from a role should remove it from the permissions array
- Revoking a permission not in the array should fail with PERMISSION_NOT_FOUND error
- Granting multiple permissions should all be present in the role's permissions array
- Revoking one permission should not affect other permissions on the same role
- Effective user permissions should be the union of all permissions from all assigned roles

## Reference Links

- [NIST RBAC Model](https://csrc.nist.gov/projects/role-based-access-control)
- [AWS IAM Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html)
- [Odoo Access Rights](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html)