feat(auth,email-verification): fluxo completo de verificação de e-mail e validação no cadastro

[davidmartins-dev]

Descrição

Este PR introduz o fluxo completo de verificação de e-mail por código numérico de 6 dígitos no backend da aplicação, integrando-o como requisito obrigatório para a criação de novas contas (POST /auth/register).

Além disso, adiciona uma camada de segurança antifraude com validação de registros MX e bloqueio em tempo real de provedores de e-mail temporários/descartáveis (disposable emails), garantindo que apenas usuários com caixas postais autênticas e permanentes concluam o cadastro na plataforma.

---

O que foi implementado

1. Proteção contra E-mails Temporários (DisposableEmailService):

   • Bypass de provedores consagrados: Domínios legítimos conhecidos (gmail.com, outlook.com, yahoo.com, hotmail.com, proton.me, etc.) são liberados imediatamente com 0ms de latência e sem requisições externas.
   • Validação de registros MX via DNS (node:dns/promises): Checa se o domínio realmente existe e possui servidores de e-mail ativos, barrando erros de digitação e domínios inexistentes.
   • Consulta à API da DeBounce (disposable.debounce.io): Detecta em tempo real se o domínio pertence a provedores descartáveis (Temp-Mail, Yopmail, Mailinator, 10MinuteMail, etc.).
   • Cache local em memória: Armazena consultas por 24h para economizar chamadas de rede.
   • Fallback resiliente: Em caso de oscilação ou timeout da API externa, a requisição não falha nem bloqueia usuários legítimos.

2. Templates e Transacionais de E-mail (react-email):

   • Criação de template responsivo com React Email para envio do código de 6 dígitos.
   • Configuração de preview local (email:dev).

3. Módulo de Envio de E-mail (EmailModule):

   • Integração com nodemailer via SMTP com suporte a STARTTLS (porta 587).
   • Fallback para desenvolvimento: caso as credenciais SMTP não estejam preenchidas, o código é exibido diretamente nos logs do console da API.

4. Model e Migração Prisma (EmailVerification):

   • Tabela no PostgreSQL com hash criptográfico (codeHash), controle de tentativas (attempts, maxAttempts), propósito (SIGNUP, PASSWORD_RESET) e timestamps de expiração e consumo.
   • Migração aplicada: 20261014204434_add_email_verification.

5. Módulo de Verificação (EmailVerificationModule):

   • POST /email-verification/send: valida o domínio/descarte, gera e envia o código de 6 dígitos (expiração em 15 min) com rate limiting por IP (@nestjs/throttler).
   • POST /email-verification/verify: valida o código contra o hash criptografado, controla limite de tentativas incorretas (máximo 3) e emite um verificationTicket.

6. Integração com o Fluxo de Autenticação (AuthModule):

   • Atualização do CreateUserDto para exigir o campo obrigatório verificationTicket.
   • Método validateVerificationTicket: valida se o ticket pertence ao e-mail informado, se possui menos de 30 minutos e o remove imediatamente do banco para impedir qualquer tipo de reutilização (replay attack).

7. Documentação e Configuração:

   • Atualização do apps/api/.env.example com os parâmetros recomendados para Gmail SMTP (SMTP_PORT=587, SMTP_SECURE=false).
   • Atualização do README.md com instruções detalhadas sobre a criação de senhas de app no Google.

---

Mecanismos de Segurança Aplicados

• Bloqueio de E-mails Descartáveis: Rejeição ativa de provedores temporários via MX e DeBounce API.
• Hash Criptográfico de Códigos: Códigos de 6 dígitos armazenados com bcrypt (nunca em texto puro).
• Proteção contra Força Bruta: Limite estrito de 3 tentativas por código gerado.
• Rate Limiting: Throttling de 3 requisições por minuto por IP no endpoint de envio.
• One-Time Token: O ticket de verificação é consumido e excluído imediatamente após o registro do usuário.
• Janela de Expiração: 5 minutos para uso do código e 30 minutos de tolerância máxima para o ticket.

---

Como Testar

1. Testes automatizados:

   # Testes unitários (10 arquivos, 40 testes)
   pnpm --filter api test
   
   # Testes end-to-end
   pnpm --filter api test:e2e