password_reset_tokens

Tabela auxiliar do fluxo de recuperação de senha. Um row é inserido em POST /auth/forgot-password (apenas se o e-mail existir) e consumido em POST /auth/reset-password. Após uso, o row não é deletado — used_at é setado, preservando o registro pra auditoria.

Igual ao refresh_tokens, guarda apenas sha256(rawToken). O token raw vai apenas no e-mail enviado ao usuário.

Colunas

Funcionalidade dos campos

• id — UUID, PK. Não usado em URLs; apenas referência interna.
• user_id — FK pra users.id com ON DELETE CASCADE. Apagar conta apaga tokens.
• token_hash — sha256 hex do raw token (32 bytes). Lookup direto.
• expires_at — now() + 1 hora no momento do insert. Tokens expirados são rejeitados em /auth/reset-password.
• used_at — NULL enquanto não consumido; now() após reset bem-sucedido. Single-use enforcement: WHERE used_at IS NULL no momento da validação.

Foreign keys

Índices

Esta tabela não tem índices customizados.

Não há índice secundário em token_hash. Como tokens válidos por usuário são poucos (TTL 1h, single-use), full scan é barato.

Constraints

Limpeza

Não há job de limpeza implementado. Tokens expirados/usados ficam até a conta ser deletada (cascade).

Volume baixo: usuário típico chama /forgot-password raramente. Se a tabela crescer (ex: spam de forgot-password), considerar adicionar:

• Cron DELETE FROM password_reset_tokens WHERE expires_at < now() - INTERVAL '7 days'
• Rate limiting em /auth/forgot-password por e-mail

Padrões de uso

• Insert — POST /auth/forgot-password (se user existe)
• Update used_at — POST /auth/reset-password (quando consumido)
• Delete por user_id — apenas via cascade (delete user)

Tabelas relacionadas

• users — pai (cascade)
• refresh_tokens — tabela irmã com semântica parecida