# Usuarios e RBAC

Gerenciamento de usuarios, grupos, permissoes e politicas de seguranca no Monetarie PIX.

## Pre-requisitos

- Acesso ao portal admin com perfil Administrador
- Banco de dados com schema `monetarie_auth` migrado (migracao #5, #13, #17, #21, #24)
- Redis operacional (para rate limiting e token blacklist)
- Compreensao do modelo de RBAC (Role-Based Access Control)

## Modelo de Dados

```mermaid
erDiagram
    users ||--o{ user_groups : "pertence a"
    groups ||--o{ user_groups : "contem"
    groups ||--o{ group_features : "tem"
    users ||--o{ sessions : "tem"
    users ||--o{ mfa_configurations : "configura"
    users ||--o{ mfa_events : "gera"
    users ||--o{ audit_logs : "registra"
    institutions ||--o{ users : "emprega"

    users {
        uuid id PK
        string username
        string email
        string password_hash
        boolean is_active
        boolean is_blocked
        datetime password_expires
        integer failed_login_attempts
        datetime last_login_at
    }

    groups {
        uuid id PK
        string name
        string description
        boolean is_active
    }

    user_groups {
        uuid user_id FK
        uuid group_id FK
        boolean is_primary
        jsonb metadata
    }

    group_features {
        uuid id PK
        uuid group_id FK
        string feature_name
        string permission_level
    }

    institutions {
        uuid id PK
        string name
        string ispb
        string cnpj
        boolean is_active
    }

    mfa_configurations {
        uuid id PK
        uuid user_id FK
        string secret
        string method
        boolean is_active
    }
```

## Gerenciamento de Usuarios

### Criar Usuario

```bash
# Via API
curl -X POST https://pixapi-dev.fluxiq.com.br/api/v1/users \
  -H "Cookie: pix_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "novo.usuario",
    "email": "novo@instituicao.com.br",
    "password": "SenhaForte@2026!",
    "is_active": true,
    "group_ids": ["<uuid-do-grupo>"]
  }'
```

### Editar Usuario

```bash
curl -X PUT https://pixapi-dev.fluxiq.com.br/api/v1/users/<user_id> \
  -H "Cookie: pix_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo.email@instituicao.com.br",
    "is_active": true
  }'
```

### Desativar Usuario

```bash
curl -X PUT https://pixapi-dev.fluxiq.com.br/api/v1/users/<user_id> \
  -H "Cookie: pix_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

## RBAC (Controle de Acesso Baseado em Funcoes)

### Arquitetura

```mermaid
flowchart TB
    REQ["Requisicao HTTP"] --> AUTH["JWTAuth / SsoAuth<br/>(autenticar)"]
    AUTH --> BL["TokenBlacklist<br/>(verificar revogacao)"]
    BL --> RP["RequirePermission<br/>(verificar RBAC)"]

    RP --> ETS["ETS Cache<br/>(group_features)<br/>TTL: 5 min"]

    ETS -->|Cache hit| CHECK["Verificar permissao"]
    ETS -->|Cache miss| DB["PostgreSQL<br/>monetarie_auth.group_features"]
    DB --> ETS

    CHECK -->|Permitido| CTRL["Controller"]
    CHECK -->|Negado| E403["403 Forbidden<br/>(RFC 7807)"]
    CHECK -->|Erro DB| E403B["403 Forbidden<br/>(fail-closed)"]

    style E403 fill:#f44336,stroke:#333,color:#fff
    style E403B fill:#f44336,stroke:#333,color:#fff
```

### RequirePermission Plug

O plug `Shared.Plugs.RequirePermission` protege 35 acoes de controller:

| Caracteristica | Valor |
|----------------|-------|
| Cache | ETS com TTL de 5 minutos |
| Comportamento em erro | **Fail-closed** (nega acesso se DB indisponivel) |
| SSO bypass | Tokens SSO (`iss: "monetarie"`) passam sem verificacao RBAC |
| Resposta de negacao | RFC 7807 com status 403 |
| Acoes protegidas | 35 actions em controllers |

### Exemplo de Uso no Controller

```elixir
# No controller
plug Shared.Plugs.RequirePermission,
  feature: "transactions",
  level: "write"
  when action in [:create, :update, :delete]

plug Shared.Plugs.RequirePermission,
  feature: "transactions",
  level: "read"
  when action in [:index, :show]
```

### Niveis de Permissao

| Nivel | Descricao | Acoes |
|-------|-----------|-------|
| `read` | Somente leitura | Listar, visualizar, exportar |
| `write` | Leitura e escrita | Criar, editar, processar |
| `admin` | Administracao completa | Deletar, configurar, gerenciar usuarios |

### Acoes Protegidas por Feature

| Feature | read | write | admin |
|---------|------|-------|-------|
| `transactions` | Listar, detalhar, historico | Criar, atualizar | Cancelar, exportar |
| `dict_keys` | Listar chaves | Criar, deletar chaves | Gerenciar claims |
| `settlement` | Visualizar ciclos | Executar netting | Configurar parametros |
| `accounting` | Visualizar lancamentos | Criar eventos | Gerenciar plano de contas |
| `users` | Listar usuarios | Criar, editar | Bloquear, deletar |
| `monitoring` | Dashboard | - | Configurar alertas |
| `simulator` | Visualizar cenarios | Executar testes | Configurar simulador |
| `system_config` | Visualizar parametros | Editar parametros | - |
| `audit` | Visualizar logs | Exportar CSV | - |
| `security` | Visualizar politicas | Editar politicas | - |
| `infractions` | Listar infracoes | Analisar, responder | Fechar |

## MFA (Autenticacao Multi-Fator)

### Fluxo de Configuracao

```mermaid
sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant A as API

    U->>F: Acessar configuracoes MFA
    F->>A: POST /api/v1/auth/mfa/setup
    A-->>F: {secret, qr_code_url, backup_codes: [...]}
    F-->>U: Exibir QR Code + backup codes

    U->>U: Escanear QR Code com app TOTP
    U->>F: Inserir codigo TOTP para confirmar
    F->>A: POST /api/v1/auth/mfa/verify-setup {code}
    A-->>F: {mfa_enabled: true}
```

### TOTP (Time-based One-Time Password)

| Parametro | Valor |
|-----------|-------|
| Algoritmo | TOTP (RFC 6238) |
| Periodo | 30 segundos |
| Digitos | 6 |
| Algoritmo hash | SHA-1 |
| Backup codes | 10 codigos unicos |

### Fluxo de Login com MFA

```mermaid
sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant A as API

    U->>F: Login (username + password)
    F->>A: POST /api/v1/auth/login
    A-->>F: {mfa_required: true, mfa_token: "temp-token"}

    U->>F: Inserir codigo TOTP
    F->>A: POST /api/v1/auth/mfa/verify {mfa_token, code}
    A-->>F: Set-Cookie: pix_session (HttpOnly)
    F-->>U: Redirecionar para dashboard
```

## Bloqueio de Conta

### Regras de Bloqueio Automatico

```mermaid
flowchart LR
    L["Tentativa de Login"] --> V["Verificar<br/>failed_login_attempts"]
    V -->|< 10| A["Autenticar"]
    V -->|>= 10| B["Conta Bloqueada<br/>is_blocked = true"]

    A -->|Falha| INC["Incrementar<br/>failed_login_attempts"]
    A -->|Sucesso| RST["Reset<br/>failed_login_attempts = 0"]
    INC --> CHK["attempts >= 10?"]
    CHK -->|Sim| BLK["SET is_blocked = true"]
    CHK -->|Nao| FIM["Retornar erro generico"]

    B --> E401["401 Unauthorized<br/>(mensagem generica)"]

    style B fill:#f44336,stroke:#333,color:#fff
    style BLK fill:#f44336,stroke:#333,color:#fff
```

| Parametro | Valor | Descricao |
|-----------|-------|-----------|
| Limite | 10 tentativas | Maximo de tentativas falhas |
| Bloqueio | Automatico | `is_blocked = true` apos exceder limite |
| Desbloqueio | Manual | Administrador deve desbloquear |
| Mensagem | Generica | "Credenciais invalidas" (previne enumeracao) |

### Desbloquear Usuario

```bash
# Via API
curl -X PUT https://pixapi-dev.fluxiq.com.br/api/v1/users/<user_id> \
  -H "Cookie: pix_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{"is_blocked": false, "failed_login_attempts": 0}'
```

## Politica de Senhas

| Regra | Requisito |
|-------|-----------|
| Comprimento minimo | 8 caracteres |
| Complexidade | Maiuscula + minuscula + numero + especial |
| Expiracao | Campo `password_expires` verificado no login |
| Historico | Nao reutilizar ultimas 5 senhas |
| Bloqueio | 10 falhas consecutivas |

### Verificacao de Expiracao

A cada login, o sistema verifica o campo `password_expires`:

```elixir
# Se password_expires < DateTime.utc_now(), o login e rejeitado
# O usuario deve redefinir a senha antes de continuar
```

## Rate Limiting (Login)

| Parametro | Valor |
|-----------|-------|
| Limite | 10 tentativas por IP |
| Janela | 15 minutos (900 segundos) |
| Endpoints | `/api/v1/auth/login`, `/api/v1/auth/mfa/*` |
| Armazenamento | Redis (token bucket) |
| Bypass | Desabilitado por padrao (`bypass_auth: false`) |

### Resposta ao Exceder Limite

```json
{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Limite de tentativas de login excedido. Tente novamente em 15 minutos."
}
```

## Auditoria de Acoes

Todas as acoes de usuario sao registradas em `monetarie_auth.audit_logs`:

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `id` | UUID | ID do registro |
| `user_id` | UUID | Usuario que realizou a acao |
| `session_id` | UUID | Sessao ativa |
| `action` | String | Tipo de acao (login, create, update, delete) |
| `entity_type` | String | Tipo de entidade afetada |
| `entity_id` | UUID | ID da entidade afetada |
| `details` | JSONB | Detalhes adicionais |
| `ip_address` | String | IP do cliente |
| `created_at` | DateTime | Timestamp da acao |

### Exportar Logs de Auditoria

```bash
# Exportar como CSV
curl -s "https://pixapi-dev.fluxiq.com.br/api/v1/audit-logs/export?format=csv&start_date=2026-02-01&end_date=2026-02-13" \
  -H "Cookie: pix_session=<token>" \
  -o audit_logs.csv
```

## SSO (Single Sign-On)

### Integracao com Backoffice

O Monetarie PIX aceita tokens SSO do Backoffice e do Core Banking:

| Issuer | `target_system` | RBAC |
|--------|-----------------|------|
| `monetarie` (Core) | Nao verificado | Bypass (confiavel) |
| `monetarie-sso` (Backoffice) | Deve conter `"pix"` | Bypass |
| `monetarie-pix` (PIX interno) | N/A | Verificado via RequirePermission |

### Cadeia de Fallback do Segredo SSO

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

## Token Blacklist (Logout)

Ao fazer logout, o token JWT e revogado via Redis:

```mermaid
sequenceDiagram
    participant U as Usuario
    participant A as AuthController
    participant R as Redis

    U->>A: POST /api/v1/auth/logout
    A->>A: Extrair JTI e EXP do token
    A->>R: SET blacklist:{jti} "revoked" EX {ttl_restante}
    A->>A: Limpar cookie pix_session
    A-->>U: 200 OK

    Note over R: Chave expira automaticamente quando token expiraria
```

A verificacao de blacklist e feita em:

- `Shared.Auth.JWTAuth` (Settlement Service)
- `DictServiceWeb.Plugs.Authenticate` (DICT Service)
- `Shared.Auth.SsoAuth` (SSO)

## Resultado Esperado

Apos configurar usuarios e RBAC:

- Usuarios podem ser criados, editados e desativados via portal ou API
- Grupos com permissoes granulares controlam acesso a 35 acoes de controller
- MFA (TOTP) pode ser habilitado por usuario com backup codes
- Contas sao bloqueadas automaticamente apos 10 tentativas falhas
- Rate limiting protege endpoints de login contra forca bruta (10/15min)
- Tokens JWT sao revogados imediatamente no logout via Redis blacklist
- Audit logs registram todas as acoes com IP, sessao e timestamp
- O RBAC e fail-closed: erros de banco de dados resultam em acesso negado (403)