# ADR-0003: Autenticação e gestão de sessão

## Status
Aceito

## Contexto
O legado usa JWT HS256 com payload mínimo (`sub`, `ver`), expiração fixa de 30 dias, sem refresh token, invalidação via `token_version` incremental (derruba todas as sessões de uma vez, nunca uma só). O Master Prompt (§5.3) pede explicitamente uma evolução: access token curto + refresh token rotativo (ou sessão server-side segura), refresh tokens armazenados em hash, histórico de sessões/dispositivos, "encerrar todas as sessões", MFA/TOTP preparado.

## Decisão
- **Access token**: JWT de vida curta, payload mínimo (`sub`, sessão id), assinado (algoritmo a confirmar em ADR de criptografia geral — HS256 mantém paridade com o legado, RS256 fica em aberto se houver necessidade de verificação por serviço externo). TTL original 15min, revisado para 8h — ver adendo 2026-09-18.
- **Refresh token**: opaco, alta entropia (≥256 bits), **rotativo a cada uso** (um novo é emitido e o antigo invalidado), armazenado só como hash no banco (nunca em claro) — mesma filosofia do token de link público do legado.
- **Tabela `sessions`** (não só um contador `token_version`): permite listar sessões/dispositivos ativos e revogar individualmente **ou** todas de uma vez (superset da capacidade do legado, que só permitia "todas").
- **Vínculo por aplicação**: uma sessão registra explicitamente para qual aplicação (`core`/`reseller`/`subscriber`) foi emitida — nunca inferir pelo papel do usuário (Master Prompt §5.1).
- **MFA/TOTP**: schema preparado desde a Fase 1 (tabela de fator, secret cifrado), ativação opcional para todos, indicada como obrigatória por política para `super_admin`/`admin` assim que a UI existir.
- Senha: Argon2id (ADR-0005 detalha parâmetros/versionamento), não bcrypt.

## Consequências
- Positivo: revogação granular por sessão/dispositivo, alinhado ao pedido explícito do Master Prompt.
- Positivo: access token de vida curta reduz janela de uso de token vazado sem exigir consulta ao banco a cada request (mesma vantagem de performance que o legado tinha com JWT, mas com menor exposição).
- Negativo: mais complexidade que o modelo legado (rotação de refresh token exige lógica de "replay detection" — se um refresh token já usado for reapresentado, é sinal de token roubado; a sessão inteira deve ser revogada nesse caso).
- Migração: nenhuma — é um sistema novo, não há sessões legadas para migrar.

## Adendo — 2026-09-18: TTL do access token revisado de 15min para 8h

O frontend nunca implementou refresh silencioso (`apps/core-web/src/lib/auth/AuthContext.tsx`/`session.ts` documentam isso explicitamente: "No refresh-token rotation in this leva"). Na prática, 15min derrubava o usuário no meio de um cadastro/edição em uso normal do backoffice — usuário pediu explicitamente pelo menos 8h. `ACCESS_TOKEN_TTL_SECONDS` em `apps/api/src/auth/token.service.ts` ajustado para `8 * 60 * 60`.

Isso é uma troca deliberada de exposição por conveniência — o risco que a decisão original mitigava (janela de uso de um token vazado) fica maior. Mitigado por: a arquitetura de `sessions` já permite revogar uma sessão específica ou todas a qualquer momento (login com nova senha após reset já revoga tudo — `password-reset.spec.ts`), então um access token vazado ainda pode ser cortado sem esperar o TTL expirar, só não automaticamente. **Trabalho futuro real, não feito agora**: implementar refresh silencioso no frontend (ex. renovar o access token em background antes de expirar, ou reagir a um 401 chamando `/auth/refresh` e repetindo a requisição) permitiria voltar a um TTL curto sem prejudicar a UX — o TTL de 8h é um paliativo, não a solução definitiva.