> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Domínio de autorização: RBAC com role types, claims derivados e resolução por Profile.

O DEVMOB utiliza um modelo de **Role-Based Access Control (RBAC)** para controlar autorização. Cada usuário autenticado possui um conjunto de permissions, montado a partir das roles e de claims derivados. Esse conjunto decide quais ações ele pode executar.

## Conceitos Fundamentais

### Permission

Uma **Permission** é a unidade de autorização. Ela representa uma capacidade específica no formato `action:resource`:

```
create:trip       → pode criar viagens
read:order        → pode visualizar pedidos
update:vehicle    → pode editar veículos
delete:driver     → pode remover motoristas
```

### Role

Uma **Role** é um conjunto nomeado de permissions. O `RoleType` define como ela pode ser usada:

| RoleType       | Uso                                        |
| -------------- | ------------------------------------------ |
| `INTERNAL`     | BackOffice, fora de qualquer organização   |
| `ENVIRONMENT`  | Global, reutilizável por organizações      |
| `ORGANIZATION` | Customizada por uma organização específica |

```
Role "Gerente de Frota" (Company X):
  - create:vehicle
  - update:vehicle
  - delete:vehicle
  - read:vehicle
  - create:driver
  - update:driver
  - read:driver
```

### Membership

O vínculo **Membership** conecta um User a uma Role. Para `ENVIRONMENT` e `ORGANIZATION`, a Membership também carrega a Organization do escopo. Para `INTERNAL`, a Membership não possui organização. Apenas vínculos `ACTIVE` entram no Profile.

### Claim de acesso

Um **claim de acesso** é uma permission derivada do vínculo que habilita o usuário a entrar em uma API surface. Os claims `access:ops`, `access:bko` e `access:driver` liberam o ingresso nas superfícies correspondentes e são avaliados antes das permissions de negócio.

| Claim           | Derivado quando                                                                              |
| --------------- | -------------------------------------------------------------------------------------------- |
| `access:bko`    | O usuário possui Membership `ACTIVE` com Role `INTERNAL`                                     |
| `access:ops`    | O usuário possui Membership `ACTIVE` em organização com Role `ENVIRONMENT` ou `ORGANIZATION` |
| `access:driver` | O usuário possui vínculo ativo como motorista em uma empresa                                 |

## Como Funciona na Prática

O conjunto de permissions do usuário é a **união** de quatro fontes:

```mermaid theme={null}
flowchart LR
    CLAIMS[Claims derivados<br/>access:*] --> SCOPE
    IR[Roles INTERNAL<br/>Membership ACTIVE] --> SCOPE
    ER[Roles ENVIRONMENT<br/>Membership ACTIVE<br/>na organização ativa] --> SCOPE
    OR[Roles ORGANIZATION<br/>Membership ACTIVE<br/>da organização ativa] --> SCOPE
    SCOPE[Permissions efetivas<br/>união sem duplicatas]
```

A checagem em cada requisição segue o fluxo abaixo. A organização ativa vem do perfil autenticado:

```mermaid theme={null}
flowchart TD
    REQ[Requisição autenticada] --> JWT[Access token validado]
    JWT --> PROFILE[Perfil autenticado resolvido]
    PROFILE --> ACTIVE{Profile ativo?}
    ACTIVE -->|Não| PEND[403 — ativação pendente]
    ACTIVE -->|Sim| APICLAIM{access:api exigido?}
    APICLAIM -->|Falta o claim| DENY1[403 Forbidden]
    APICLAIM -->|OK| ACL[Permissions efetivas verificadas]
    ACL -->|Sem a permission| DENY2[403 Forbidden]
    ACL -->|OK| OK[Ação permitida]
```

<Info>
  O mesmo usuário pode ter a role "Administrador" em uma cooperativa e "Operador" em uma empresa afiliada. O Profile resolve **no máximo uma** organização ativa por vez, e as permissions são avaliadas no contexto dessa organização.
</Info>

## Entidades

| Entidade           | Descrição                                                                             |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Role**           | Conjunto nomeado de permissions com tipo `INTERNAL`, `ENVIRONMENT` ou `ORGANIZATION`. |
| **Permission**     | Par `action:resource` que representa uma capacidade específica (catálogo estático).   |
| **RolePermission** | Vínculo entre roles e suas permissions.                                               |
| **Membership**     | Vínculo entre User, Organization e Role.                                              |

<CardGroup cols={1}>
  <Card title="Roles e Permissions em Detalhe" icon="list-check" href="/domain/authorization/roles-and-permissions">
    Catálogo completo de permissions, escopo de roles, claims derivados e atribuição via Membership.
  </Card>
</CardGroup>