Pular para o conteúdo principal

Feature - OTP (Geração e Validação)

Introdução ao documento​

Este documento descreve o ciclo de geração e validação de OTP utilizado para autenticação de telefone. Evidência: src/routes/otp.ts:9 Evidência: src/routes/otp.ts:27

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Persistência com model Sequelize Otp.
  • Envio de OTP por template WhatsApp. Evidência: src/models/otp.ts:18 Evidência: src/features/api/whatsapp/sendOtpCode.ts:2

Visão geral​

A feature cria OTP de 6 dígitos, com validade de 15 minutos, e valida posteriormente o par phone + code contra expiração. Evidência: src/routes/otp.ts:11 Evidência: src/routes/otp.ts:12 Evidência: src/routes/otp.ts:31 Evidência: src/routes/otp.ts:37

Atores​

  • Serviço interno consumidor da API (com token de serviço).
  • Usuário final que recebe o OTP via WhatsApp. Evidência: src/routes/otp.ts:9 Evidência: src/features/api/whatsapp/sendOtpCode.ts:12

Pré-condições​

  • Header Authorization válido para middleware verifyServiceToken.
  • SERVICE_TOKEN configurado no ambiente.
  • WHATSAPP_API_TOKEN e WHATSAPP_PHONE_ID para envio do template. Evidência: src/routes/otp.ts:9 Evidência: src/auth/serviceToken.ts:7 Evidência: src/features/api/whatsapp/sendOtpCode.ts:4 Evidência: src/features/api/whatsapp/sendOtpCode.ts:6

Fluxo principal​

  1. POST /otp recebe phone.
  2. Gera código aleatório de 6 dígitos.
  3. Define validUntil (+15 minutos).
  4. Persiste OTP.
  5. Envia template WhatsApp.
  6. POST /otp/confirmation valida código e prazo. Evidência: src/routes/otp.ts:10 Evidência: src/routes/otp.ts:11 Evidência: src/routes/otp.ts:12 Evidência: src/routes/otp.ts:17 Evidência: src/routes/otp.ts:18 Evidência: src/routes/otp.ts:27

Fluxos alternativos​

  • 401: token inválido.
  • 403: ausência de header Authorization.
  • 400: OTP inválido ou expirado na confirmação.
  • 500: falha de persistência/envio/consulta. Evidência: src/auth/serviceToken.ts:22 Evidência: src/auth/serviceToken.ts:30 Evidência: src/routes/otp.ts:34 Evidência: src/routes/otp.ts:38 Evidência: src/routes/otp.ts:22

Regras de negócio​

  • OTP sempre numérico e com 6 dígitos.
  • Janela de validade fixa em 15 minutos.
  • Só valida quando phone e code coincidem com registro existente.
  • Expirado é rejeitado mesmo com código correto. Evidência: src/routes/otp.ts:11 Evidência: src/routes/otp.ts:12 Evidência: src/routes/otp.ts:31 Evidência: src/routes/otp.ts:37

Estados possíveis (quando houver)​

  • OTP gerado (201).
  • OTP válido (200).
  • OTP inválido (400).
  • OTP expirado (400). Evidência: src/routes/otp.ts:20 Evidência: src/routes/otp.ts:41 Evidência: src/routes/otp.ts:34 Evidência: src/routes/otp.ts:38

Endpoints envolvidos​

Dados impactados​

  • Tabela/model Otp (criação e leitura).
  • Referência de dados locais: ../data/model.md. Evidência: src/routes/otp.ts:17 Evidência: src/routes/otp.ts:31 Evidência: src/models/otp.ts:33

Pendências​

  • Definir política de limpeza de OTP expirado (não há rotina dedicada no repositório). Evidência: src/routes/otp.ts:37 Evidência: src/workers/groupLinkDispatchWorker.ts:171