Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

53 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/ecommerce-auth-e-seguranca

Ecommerce - Auth e Segurança

Registrar a arquitetura real de autenticação e proteção da área do cliente.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado15 de abr. de 2026
Seções42
Tags5
guiaecommerceauthsegurançacliente

Objetivo deste guia

Registrar a arquitetura real de autenticação e proteção da área do cliente.

Esta nota complementa:

Visão geral

O projeto hoje tem dois domínios de identidade diferentes:

  • EcommPanel: operação administrativa;
  • Ecommerce / Minha conta: relacionamento com o cliente.

Eles reaproveitam alguns blocos técnicos, mas não compartilham:

  • tabelas de usuário;
  • cookies de sessão;
  • tokens de login;
  • auditoria.

O que é compartilhado entre admin e cliente

As duas camadas compartilham a base conceitual:

  • hashing de senha via scrypt;
  • sessão server-side com cookie + CSRF;
  • validação de origem;
  • rate limit por fingerprint;
  • fingerprint por user-agent;
  • auditoria própria por domínio.

Arquivos que aparecem nos dois lados:

  • src/features/ecommpanel/server/password.ts
  • src/features/ecommpanel/server/crypto.ts
  • src/features/ecommpanel/server/requestMeta.ts
  • src/features/ecommpanel/server/rateLimit.ts

O que é isolado por domínio

Admin

  • cookies: ecommpanel_session, ecommpanel_csrf
  • tabelas: panel_users, panel_sessions, panel_reset_tokens, panel_login_tokens, panel_audit_events

Cliente

  • cookies: ecom_customer_session, ecom_customer_csrf
  • tabelas: customer_accounts, customer_addresses, customer_orders, customer_login_tokens, customer_sessions, customer_audit_events

Isso é importante porque evita mistura entre:

  • privilégio administrativo;
  • identidade do consumidor;
  • auditoria operacional.

Senhas

Algoritmo

Hoje o hash de senha usa scrypt com salt aleatório por senha.

Formato persistido:

txt
scrypt:<salt>:<hash>

Arquivo:

  • src/features/ecommpanel/server/password.ts

Admin

O painel já tem política explícita em src/features/ecommpanel/config/security.ts:

  • mínimo de 12 caracteres;
  • exige maiúscula;
  • exige minúscula;
  • exige número;
  • exige símbolo.

Cliente

A conta do cliente usa o mesmo hash scrypt e agora segue política forte centralizada:

  • mínimo de 12 caracteres;
  • exige maiúscula;
  • exige minúscula;
  • exige número;
  • exige símbolo.

Arquivos centrais:

  • src/features/ecommerce/config/accountSecurity.ts
  • src/features/ecommerce/lib/passwordPolicy.ts
  • src/app/api/ecommerce/account/register/route.ts
  • src/features/ecommerce/components/account/AccountView.tsx

Conclusão importante:

  • o algoritmo está bom;
  • a política de senha do cliente agora está alinhada ao mesmo nível do admin.

Validação do cadastro

O domínio do cliente agora pode exigir confirmação do e-mail antes da ativação da conta.

Quando a política estiver ligada em Configurações do painel > Auth e e-mail:

  1. o cadastro entra como pendente;
  2. o sistema envia um código de 6 dígitos;
  3. a conta só recebe email_verified_at depois da confirmação;
  4. login por senha e login por código passam a exigir conta já verificada.

Tabela usada:

  • customer_pending_registrations

Comportamento relevante:

  • cadastros pendentes expiram automaticamente;
  • o cooldown de reenvio evita spam de criação;
  • a conta do cliente não é ativada enquanto o e-mail não for confirmado.

Sessões

Admin

Configuração atual em src/features/ecommpanel/config/security.ts:

  • sessionTtlMs: 8 horas
  • sessionIdleTtlMs: 30 minutos
  • sessão demo: 30 minutos

Validações:

  • expiração por tempo;
  • expiração por inatividade;
  • usuário ainda ativo;
  • fingerprint por user-agent;
  • CSRF para mutações.

Cliente

Configuração atual em src/features/ecommerce/config/accountSecurity.ts:

  • sessionTtlMs: 30 dias
  • sessionIdleTtlMs: 7 dias

Validações:

  • expiração por tempo;
  • expiração por inatividade;
  • fingerprint por user-agent;
  • CSRF para mutações autenticadas.

Leitura prática:

  • o admin é mais restritivo porque opera áreas sensíveis;
  • a conta do cliente privilegia continuidade de sessão, mas continua com controle de inatividade.

Login principal

Admin

Entrada:

  • POST /api/ecommpanel/auth/login

Fluxo:

  1. valida origem;
  2. aplica rate limit;
  3. busca usuário do painel;
  4. verifica bloqueio temporário;
  5. verifica senha;
  6. registra auditoria;
  7. cria sessão;
  8. devolve cookie + CSRF.

Cliente

Entrada:

  • POST /api/ecommerce/account/login

Fluxo:

  1. valida origem;
  2. aplica rate limit;
  3. aceita identificador por e-mail ou CPF/CNPJ;
  4. busca conta ativa do cliente;
  5. verifica bloqueio temporário;
  6. verifica senha;
  7. exige email_verified_at preenchido;
  8. reseta contador de falhas em sucesso;
  9. cria sessão do cliente;
  10. devolve cookie + CSRF.

Login por código

Os dois domínios também aceitam código por e-mail.

Regras comuns

  • código de 6 dígitos;
  • uso único;
  • expiração de 10 minutos;
  • cooldown de 90 segundos para nova emissão.

Diferença de propósito

  • no admin, é um caminho alternativo forte para operadores;
  • no cliente, é um caminho opcional de recuperação/entrada simplificada para contas já verificadas.

E-mails temporários e descartáveis

O projeto agora aceita política configurável para bloquear domínios de e-mail temporário.

Leitura prática:

  • o bloqueio pode ficar ativo por padrão;
  • o painel pode liberar temporariamente esses domínios para teste;
  • a lista padrão pode ser complementada com domínios extras da operação.

Isso reduz:

  • cadastros falsos;
  • abuso automatizado;
  • base poluída com contas que nunca serão ativadas.

Bloqueio por falha

Admin

  • 5 falhas invalidam temporariamente a conta;
  • bloqueio de 15 minutos.

Cliente

Hoje a conta do cliente já replica a mesma ideia:

  • contador de falhas em customer_accounts.failed_attempts;
  • bloqueio temporário em customer_accounts.lock_until;
  • bloqueio disparado após 5 falhas;
  • janela atual de 15 minutos.

Rate limit

Admin

Configuração atual:

  • login: 10 tentativas por 10 minutos
  • pedir código: 3 por 10 minutos
  • validar código: 10 por 10 minutos
  • forgot password: 5 por 15 minutos
  • reset password: 10 por 15 minutos
  • mutações administrativas: 120 por minuto

Cliente

Configuração atual:

  • login por senha: 12 tentativas por 10 minutos;
  • solicitar código: 4 por 10 minutos;
  • validar código: 10 por 10 minutos;
  • mutação de perfil: 40 por 5 minutos;
  • mutação de endereço: 60 por 5 minutos;
  • exportação LGPD: 6 por 1 hora;
  • solicitação de exclusão: 3 por 1 hora.

LGPD e retenção

O domínio do cliente agora também já diferencia:

  • exportação do dado;
  • solicitação de exclusão;
  • anonimização operacional da conta;
  • retenção mínima do pedido por obrigação operacional ou legal.

Ponto importante:

  • pedido sanitizado e desvinculado da conta não é a mesma coisa que conta ativa;
  • dado reversível não deve ser chamado de anonimizado.

Leitura complementar:

  • cadastro: 8 por 15 minutos
  • login por senha: 12 por 10 minutos
  • pedir código: 4 por 10 minutos
  • validar código: 10 por 10 minutos
  • mutações de perfil: 40 por 5 minutos
  • mutações de endereço: 60 por 5 minutos

CSRF e origem confiável

Os dois domínios protegem escrita com:

  • verificação de Origin;
  • token CSRF em cookie e header x-csrf-token;
  • comparação segura com safeCompare.

Arquivos principais:

  • src/features/ecommpanel/server/auth.ts
  • src/features/ecommerce/server/customerAuth.ts

Fingerprint de sessão

As duas camadas hoje vinculam sessão ao user-agent por hash.

Importante:

  • o hash do IP também é armazenado;
  • mas o IP não é exigido como match rígido;
  • isso evita quebra excessiva por NAT, redes móveis e troca de borda.

Então, na prática:

  • user-agent é barreira forte;
  • IP hoje é mais material de auditoria do que trava dura.

Criptografia de dados sensíveis

Cliente

Dados sensíveis do cliente não ficam em texto puro quando persistidos:

  • data de nascimento;
  • CPF/CNPJ;
  • RG/documento secundário;
  • inscrição estadual.

Implementação:

  • AES-256-GCM
  • chave derivada de segredo por SHA-256
  • helper em src/features/ecommerce/server/customerCrypto.ts

Segredo:

  • APP_CUSTOMER_DATA_SECRET
  • fallback local apenas fora de produção

Admin

No domínio do painel, o foco atual está em:

  • hash de senha;
  • sessões;
  • tokens;
  • auditoria.

O painel não persiste o mesmo volume de PII sensível que a conta do cliente.

Auditoria

Admin

Tabela:

  • panel_audit_events

Registra:

  • sucesso e falha de login;
  • bloqueio;
  • bootstrap;
  • ações administrativas relevantes.

Cliente

Tabela:

  • customer_audit_events

Registra:

  • emissão e falha de código;
  • sucesso e falha de login;
  • eventos da conta do cliente.

O que já está bem resolvido

  • separação entre identidade do admin e do cliente;
  • hash moderno de senha com scrypt;
  • sessão server-side;
  • CSRF;
  • origin check;
  • rate limit;
  • bloqueio por falha;
  • auditoria por domínio;
  • criptografia em repouso para PII do cliente.

O que ainda merece fortalecimento

Prioridade alta

  • elevar a política de senha do cliente para o mesmo padrão do admin;
  • abrir recuperação de senha do cliente;
  • adicionar rotação/estratégia operacional para o segredo de criptografia do cliente;
  • endurecer monitoramento de eventos suspeitos.

Prioridade seguinte

  • 2FA real para operadores críticos do painel;
  • trilha de exportação/anonimização/exclusão LGPD;
  • revogação administrativa de sessões do cliente;
  • proteção mais forte para rotas públicas críticas via edge/proxy.

Publicar isso abertamente é seguro?

Resposta curta:

  • documentar internamente: sim;
  • publicar tudo abertamente na internet: eu não recomendo.

O que é seguro documentar internamente sem omissão:

  • arquitetura;
  • fluxos;
  • tabelas;
  • algoritmos;
  • decisões de segurança;
  • gaps atuais;
  • próximos reforços.

O que eu evitaria em documentação pública aberta:

  • segredos e referências operacionais reais;
  • thresholds exatos de abuso quando isso não for necessário;
  • detalhes de fallback de desenvolvimento;
  • pontos de exceção e tolerâncias específicas de fingerprint.

Minha recomendação prática:

  • manter o mini site completo como documentação interna;
  • se houver documentação pública para terceiros, derivar uma versão sanitizada.

Leitura seguinte