Protocolo Shepherd 1

O framework de segurança da SafeNode: da verificação humana ao login e à sessão. Guia e protege cada etapa como um bom pastor.

O que é o Shepherd 1?

O Protocolo Shepherd 1 é o conjunto de regras, camadas e fluxos que a SafeNode usa para garantir que apenas o titular acesse a conta. O nome vem de shepherd (pastor): o bom pastor protege e guia o rebanho; o protocolo protege a identidade e guia cada etapa do login de forma segura.

Verificação humana (HV)

Antes de processar credenciais, o login exige que a requisição tenha passado pelo desafio de verificação humana. Isso reduz ataques automatizados (bots, scripts e scrapers).

Como funciona

• No carregamento da página de login, o servidor gera um hv_token e o envia no HTML (campo oculto).
• Um script no cliente executa no navegador e preenche um segundo campo (ex.: hv_js) indicando que o ambiente é um browser real.
• No POST do formulário, o servidor valida SafeNodeHumanVerification::validateRequest($_POST, $error). Se o token estiver ausente, expirado ou o indicador JS não tiver sido preenchido, a requisição é rejeitada.

Rate limiting

O número de tentativas de login por IP (e, quando aplicável, por janela de tempo) é limitado para impedir força bruta e abuso.

Configuração

Os limites são configuráveis via configurações SafeNode (ex.: login_max_attempts, login_window). Tentativas falhas podem ser contabilizadas em tabelas como safenode_human_verification_logs (event_type = ‘bot_blocked’) ou equivalentes. Ao exceder o limite, o usuário recebe HTTP 429 ou mensagem amigável e deve aguardar a janela expirar.

Proteção CSRF

Todo formulário de login (e demais ações sensíveis) usa token CSRF. O token é gerado por sessão e validado no POST; requisições sem token válido são rejeitadas.

No Shepherd 1, a ordem de validação no POST é: CSRF → HV → rate limit → email/senha. Assim, ataques cross-site não conseguem enviar credenciais válidas sem passar pelo mesmo contexto de sessão e HV.

Métodos de login

O Shepherd 1 utiliza quatro mecanismos de autenticação, combinados conforme o contexto:

2FA por email (detalhes técnicos)

O segundo fator é implementado exclusivamente por email na SafeNode (sem TOTP nem backup codes no fluxo atual). Código numérico de 6 dígitos, gerado de forma aleatória e enviado por email.

Ciclo de vida do código

• Geração: random_int(0, 999999) com str_pad para 6 dígitos.
• Armazenamento: apenas o hash SHA-256 do código é gravado na tabela safenode_2fa_email_codes (user_id, code_hash, expires_at). O código em claro nunca é persistido.
• Expiração: expires_at é definido no banco com NOW() + INTERVAL 10 MINUTE (MySQL) para evitar divergência de fuso entre PHP e servidor de banco.
• Uso único: após verificação bem-sucedida, o registro do código é removido (DELETE). Não é possível reutilizar o mesmo código.
• Um código por usuário: ao gerar um novo código, códigos antigos do mesmo user_id são removidos (DELETE antes do INSERT). Portanto, apenas o código do email mais recente é válido.

Verificação

O valor digitado é normalizado (remoção de não dígitos, trim), deve ter exatamente 6 caracteres, e então é hasheado com SHA-256. A busca no banco é por user_id, code_hash e expires_at > NOW(). Se houver match, o código é consumido e o login prossegue.

Dispositivo confiável

Para não exigir 2FA em todo login no mesmo aparelho, o Shepherd 1 mantém um token de confiança por dispositivo (por exemplo, vinculado a user_id + fingerprint do dispositivo ou cookie seguro). O período de confiança é configurável (ex.: 7 dias).

• Após login completo (incluindo 2FA quando aplicável), o dispositivo é marcado como confiável e o token é armazenado (ex.: cookie HttpOnly, Secure, SameSite).
• Em logins subsequentes no mesmo dispositivo, se o token for válido e dentro do prazo, o fluxo pula a tela de código por email.
• O token pode ser rotacionado após cada login bem-sucedido para limitar reuso indevido em caso de vazamento.

Login por QR code

Fluxo em dois dispositivos: o desktop exibe um QR que codifica uma URL de confirmação; o usuário escaneia no celular (onde já está logado) e confirma; o desktop recebe a sessão via polling.

Passos

1. Desktop: chama api/qr-login-create.php (POST), recebe token e URL. Exibe o QR com essa URL.
2. Mobile: ao escanear, abre a URL (ex.: auth/qr-login-confirm.php?t=TOKEN). Se não estiver logado, é redirecionado para login com redirect=...qr-login-confirm....
3. Login no mobile (se necessário): ao fazer login com redirect para qr-login-confirm, o Shepherd 1 não exige 2FA — o usuário entra direto e é redirecionado para a tela de confirmação do QR.
4. Confirmação: na tela de confirmação, o usuário clica em “Confirmar e entrar no computador”. O backend associa o token ao user_id e marca status = ‘confirmed’.
5. Desktop: o script no desktop faz polling em api/qr-login-status.php?token=.... Quando status = ‘confirmed’, o backend cria a sessão no desktop (cookies, SessionManager) e retorna redirect. O desktop redireciona para o dashboard — sem passar por 2FA.

O token QR tem validade limitada (ex.: 3 minutos). Após uso ou expiração, um novo QR deve ser gerado.

Camadas de segurança

O protocolo atua em quatro camadas principais:

Princípios do Shepherd 1

• Menor privilégio: até passar por todas as etapas exigidas (senha + 2FA quando aplicável), a conta não é acessada.
• Códigos de uso único: cada código 2FA vale uma vez; após uso ou expiração, é invalidado.
• Confiança por dispositivo: evita 2FA repetido no mesmo aparelho por um período definido, sem enfraquecer a segurança em aparelhos novos.
• QR sem 2FA extra: no fluxo de login por QR, quem confirma no celular já está autenticado; o desktop não é enviado para a tela de 2FA por email.
• Não revelar existência de conta: em falhas de HV ou rate limit, a mensagem não indica se o email existe no sistema.

Fluxo completo (resumo)

Da entrada na página de login até a sessão ativa:

1. Acesso à página de login
2. HV: initChallenge() → token + script no cliente
3. Usuário preenche email, senha; envia hv_token + hv_js
4. POST: CSRF válido? → HV válido? → Rate limit OK? → Email/senha válidos?
5. Se senha OK: 2FA ativo?
   - Não → criar sessão → redirect
   - Redirect = qr-login-confirm? → criar sessão → redirect (sem 2FA)
   - Dispositivo confiável? → criar sessão → redirect
   - Senão → redirect login-2fa → enviar código email → verificar código → criar sessão → redirect
6. Sessão: regenerar ID, gravar user/IP/UA, trust device (se aplicável), SessionManager, redirect

Diagrama detalhado em docs/SHEPHERD-1-FLUXO.md.

Gestão de sessões

Após login bem-sucedido, o Shepherd 1 garante sessão segura e rastreável:

• Regeneração de ID: SessionSecurity::regenerateSessionId() após login completo para evitar fixação de sessão.
• Dados na sessão: user_id, username, email, full_name, role, session_ip, session_user_agent, last_activity.
• Persistência: SessionManager::createSession() grava o registro em safenode_user_sessions (ou equivalente) para listagem de sessões ativas e revogação.
• Cookies de sessão com flags seguras (HttpOnly, Secure em HTTPS, SameSite) conforme configuração do PHP/servidor.

Por que “Shepherd”?

Shepherd significa “pastor” em inglês. A imagem do bom pastor é a de quem guia, protege e não abandona o rebanho. Na SafeNode, o Protocolo Shepherd 1 cumpre esse papel: guia cada usuário pelos fluxos de login corretos, protege identidade e sessões com múltiplas barreiras e garante que apenas o titular — ou quem ele autorizar no próprio dispositivo — acesse a conta.

Segurança eficaz não é só bloquear ataques: é criar um caminho claro e confiável para o acesso legítimo. O Shepherd 1 é esse caminho.

Ameaças mitigadas

FAQ

Referências

• · SHEPHERD-1-FLUXO.md — Fluxo visual (Mermaid)
• · shepherd-1.php — Esta página (referência do protocolo)
• · Documentação de funções — Security Headers, CSRF, HV, Rate limiting
• · Login — Implementação do fluxo de login
• · Login 2FA — Tela de código por email