Matheus (Handix)
9e629bb394
Usuário pediu explicitamente pelo menos 8h. O TTL curto original era deliberado (ADR-0003, reduzir janela de token vazado), mas o frontend nunca implementou refresh silencioso — na prática o usuário era derrubado no meio do trabalho sem nenhuma renovação automática. 8h é um paliativo real, documentado como tal num adendo na própria ADR-0003 (com a mitigação que já existe — revogação de sessão continua granular — e o que resolveria isso de verdade sem abrir mão de segurança: refresh silencioso no frontend). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
3.7 KiB
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 contadortoken_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/adminassim 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.