> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# OTP (One-Time Password)

> Mecanismo genérico de verificação por código descartável, utilizado em fluxos sensíveis.

## 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

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as DEVMOB API
    participant N as Notification (email)

    C->>API: Solicita OTP de reset de senha
    Note over API: Usuário identificado e código de 6 dígitos gerado
    API->>N: Emit otp.created (deliver code)
    API->>C: Return otpId
    N->>C: Receive code by email
    C->>API: Redefine senha com otpId, code e newPassword
    Note over API: Contexto, validade, uso único e código conferidos
    API->>C: 204 — password updated
```

<Info>
  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`.
</Info>

## 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    |

<Info>
  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.
</Info>

## 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. |

<Warning>
  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.
</Warning>