Overview
O OTP é um mecanismo genérico de verificação que gera um código numérico de 6 dígitos, mantém apenas sua versão protegida e entrega o código ao usuário. Cada OTP está vinculado a um contexto que determina qual operação será autorizada após a verificação, como recuperação de senha, troca de telefone ou troca de email.
How It Works
A verificação ocorre dentro do fluxo que consome o OTP (ex.: reset-password), usando o otpId devolvido na solicitação junto com o code.
Registro
| Campo | Tipo | Descrição |
|---|
otpId | UUID | Identificador único (devolvido ao cliente na solicitação) |
userId | UUID | Referência ao User |
code | String | Credencial protegida do código (nunca armazenado em texto puro) |
context | OtpContext | Contexto que determina a finalidade do OTP |
recipient | String | Destinatário da entrega |
expiresAt | DateTime | Data/hora de expiração (2 minutos após a criação) |
usedAt | DateTime? | Data/hora de uso (null se não utilizado) |
createdBy | UUID? | Usuário que criou o registro, quando aplicável |
createdAt | DateTime | Data/hora de criação |
updatedBy | UUID? | Usuário que fez a última atualização, quando aplicável |
updatedAt | DateTime | Data/hora de última atualização |
Supported Contexts
| Context | Descrição | Ação pós-verificação |
|---|
RESET_PASSWORD | Recuperação de senha | Define a nova senha do usuário e marca o OTP como usado |
RESET_PHONE | Troca ou validação de telefone | Autoriza a atualização do telefone e marca o OTP como usado |
RESET_EMAIL | Troca ou validação de email | Autoriza a atualização do email e marca o OTP como usado |
Novos contextos podem ser adicionados conforme necessário (ex.: two-factor auth). O mecanismo de geração, entrega e verificação permanece o mesmo — apenas a ação pós-verificação muda.
Business Rules
| Regra | Descrição |
|---|
| Validade | O código expira 2 minutos após a criação. |
| Credencial protegida em repouso | Apenas a versão protegida do código é mantida; o valor em texto puro só existe na entrega. |
| Uso único | Após verificação bem-sucedida, usedAt é preenchido e o código não pode ser reutilizado. |
| Proteção contra enumeração | Se o usuário não existir (ou não tiver telefone), a solicitação devolve um otpId aleatório sem criar nenhum OTP, evitando revelar quais contas existem. |
O código OTP não é um token de autenticação. É um código de verificação de curta duração que, após validado, dispara a ação correspondente ao seu contexto.
