# Autenticação — Backend

## Visão geral

O backend usa JWT com dois tokens: `accessToken` (curta duração) e `refreshToken` (longa duração). O `AUTH_MODE` no `.env` controla o comportamento:

| `AUTH_MODE` | Comportamento |
|---|---|
| `jwt` | Auth JWT ativa (padrão e recomendado) |
| `none` | Auth desativada — **nunca usar em produção** |

---

## Fluxo completo

```
1. LOGIN
   POST /api/auth/login
   Body: { login, senha }
   ──────────────────────
   Resposta: { accessToken, refreshToken, usuario }

   accessToken  → duração curta (padrão: 15 min)
   refreshToken → duração longa (padrão: 30 dias), salvo na tabela refresh_tokens

2. USO DA API
   Enviar o accessToken no header de cada requisição:
   Authorization: Bearer <accessToken>

   O middleware Validajwt decodifica o token e popula req.user.

3. REFRESH (quando accessToken expirar)
   POST /api/auth/refresh
   Body: { refreshToken }
   ──────────────────────
   Resposta: { accessToken }

   O refreshToken permanece válido até expirar ou ser revogado.

4. LOGOUT
   POST /api/auth/logout
   Body: { refreshToken }
   ──────────────────────
   Revoga o refreshToken no banco. O accessToken expira naturalmente.
```

---

## Níveis de acesso

O campo `nivel` no model `Usuario` define o que cada usuário pode fazer:

O campo `Nivel` aceita os valores `"1"`, `"2"` e `"3"` (enum em `Usuario.Schema.js`).

| Valor | Perfil | Permissões |
|---|---|---|
| `"1"` | Usuário comum | Chat, busca, leitura de documentos, conversas próprias, alterar própria senha |
| `"2"` | Intermediário | Nível existente no enum, sem regra dedicada no código atual (tratado como não-admin) |
| `"3"` | Administrador | Tudo do nível 1 + gerenciar usuários, ingerir documentos, excluir documentos |

> **Observação:** apenas `requireAdmin` (exige `"3"`) e o guard de frontend (que redireciona explicitamente o nível `"1"` de `/usuarios`) tratam níveis de forma diferenciada. O nível `"2"` não tem comportamento próprio hoje.

---

## Middleware de auth

| Middleware | Uso |
|---|---|
| `Validajwt` | Decodifica o token e popula `req.user`. Usado antes de `RequireUser`/`RequireAdmin` |
| `RequireUser` | Exige `req.user` presente (qualquer nível) |
| `RequireAdmin` | Exige `req.user.nivel === "3"` |

**Como aplicar em novas rotas:**

```js
// Rota aberta (sem auth)
router.post("/login", AuthController.Login);

// Rota para qualquer usuário autenticado
router.get("/dados", requireUser, Controller.Listar);

// Rota exclusiva para admins
router.delete("/recurso/:id", requireUser, requireAdmin, Controller.Remover);
```

> `requireAdmin` sempre deve vir **após** `requireUser` na lista de middlewares.

---

## Armazenamento dos tokens

- `accessToken`: nunca persistido no banco — é stateless (validado pela assinatura JWT)
- `refreshToken`: persistido na tabela `refresh_tokens` com `UserId`, `Token` (hash), `ExpiresAt` e `RevokedAt`
- Um job de limpeza (`cleanupTokens.js`) remove tokens expirados periodicamente

---

## Configuração do JWT

Variáveis de ambiente relevantes (ver [setup.md](setup.md) para descrição completa):

```
JWT_SECRET=<chave-secreta>
JWT_ISSUER=oraculo-api
JWT_ACCESS_TTL_SECONDS=900       # 15 minutos
JWT_REFRESH_TTL_SECONDS=2592000  # 30 dias
```