Requisição 171 — Suporte Nativo ao Cloudflare Turnstile no Core do Conn2Flow

Origem: Análise de infraestrutura, redução de custos de terceiros e conformidade de privacidade (LGPD/GDPR).
Lote Vinculado: BATCH-176.
Status: ready-for-intake.

1. Contexto e Motivação

O Google reCAPTCHA reduziu a cota gratuita global para 10.000 requisições/mês, cobrando US\$ 1,00 a cada 1.000 chamadas excedentes, além de depender de rastreamento comportamental de usuários e apresentar desafios visuais intrusivos (ex.: selecionar semáforos/faixas).

O Cloudflare Turnstile é uma alternativa moderna, 100% gratuita, sem limite de requisições mensais (inclusive para sites não hospedados na Cloudflare), orientada à privacidade (não coleta dados para fins publicitários) e com experiência de usuário transparente (<1s de verificação sem atrito visual para humanos legítimos).

Esta requisição introduz o suporte nativo ao Cloudflare Turnstile no Core do Conn2Flow, permitindo coexistência, migração suave e seleção configurável de provedor (none, google-recaptcha, cloudflare-turnstile), desacoplando e centralizando a validação de captcha no backend.

2. Escopo Arquitetural

2.1 Configuração de Ambiente e Retrocompatibilidade

1. Novas Variáveis de Configuração:

   • CAPTCHA_PROVIDER: Provedor ativo de proteção anti-bot. Valores suportados:

     • none: Desativado (nenhuma validação de captcha exigida).

     • google-recaptcha: Google reCAPTCHA v2 / v3 (legado mantido).

     • cloudflare-turnstile: Cloudflare Turnstile.

   • TURNSTILE_SITE_KEY: Chave pública para renderização do widget no frontend.

   • TURNSTILE_SECRET_KEY: Chave secreta para validação no endpoint da Cloudflare.

   • TURNSTILE_MODE: Modo do widget (managed, non-interactive, invisible), padrão managed.

2. Inferência e Fallback Sem Regressão:

   • Se CAPTCHA_PROVIDER não estiver definido no .env, mas USUARIO_RECAPTCHA_ACTIVE for true, inferir automaticamente google-recaptcha para garantir total paridade com projetos já instalados.

3. Mapeamento no Core:

   • Registrar as novas chaves em gestor/config.php e no template de instalação gestor/autenticacoes.exemplo/dominio/.env com documentação explicativa e indicação das chaves de teste da Cloudflare.

2.2 Camada Centralizada de Abstração Backend

1. Helper de Validação Unificado:

   • Criar helper desacoplado e reutilizável no core (ex.: gestor_captcha_validar(?string $token = null, array $opcoes = []): array|bool em gestor/bibliotecas/seguranca.php ou biblioteca correspondente).

   • Resolução inteligente do token:

     • Se $token for informado, usa o valor explicitado.

     • Caso contrário, busca em $_POST['cf-turnstile-response'], $_POST['g-recaptcha-response'] ou $_POST['token'].

   • Comportamento por provedor:

     • none: Retorna sucesso imediatamente (true).

     • cloudflare-turnstile:

     • Dispara POST para [REDACTED].

     • Payload: secret, response (token) e remoteip (IP do cliente extraído via seguranca_ip_bloco() ou $_SERVER['REMOTE_ADDR']).

     • Timeout seguro de conexão cURL (5 segundos) e tratamento de falha de rede/JSON.

     • Valida se success === true.

     • google-recaptcha:

     • Mantém a rotina existente de validação contra [REDACTED] (v3 e fallback v2).

2. Refatoração dos Consumidores no Core:

   • Substituir as chamadas cURL repetidas de verificação de captcha em:

     • gestor/bibliotecas/formulario.php (formulario_processamento()).

     • gestor/modulos/perfil-usuario/perfil-usuario.php (login/acessar-sistema, cadastro/signup, esqueceu-a-senha/redefinição).

     • Manter o fluxo de proteção contra abuso por IP (acessos), garantindo que falha de validação de captcha conte como abuso (conforme governança da req-169).

2.3 Frontend, Componentes e Injeção de Assets

1. Injeção de Assets:

   • Injetar dinamicamente o script oficial: <script src="[REDACTED] async defer></script>.

2. Renderização do Widget:

   • Suporte a contêiner com renderização automática: <div class="cf-turnstile" data-sitekey="#turnstile-site-key#" data-theme="auto"></div> ou renderização programática via turnstile.render().

   • Integração nas telas de autenticação do perfil-usuario (acessar sistema, cadastro e esqueceu a senha) tanto no tema Fomantic UI quanto no tema Tailwind CSS.

   • Integração no motor de formulários dinâmicos (gestor/assets/interface/formulario.js e formulario.php).

3. Envio via AJAX:

   • Garantir que o valor preenchido pelo Turnstile em input[name="cf-turnstile-response"] seja devidamente serializado e enviado em requisições AJAX (FormData nativo já inclui inputs do formulário; verificar serializers manuais).

   • Suporte a reset do widget (turnstile.reset()) em caso de retorno de erro de validação ou nova tentativa.

2.4 Módulo de Configuração de Ambiente (admin-environment)

1. Interface Administrativa:

   • Adicionar campo seletor do Provedor de Captcha (CAPTCHA_PROVIDER) com opções:

     • Desativado (none)

     • Google reCAPTCHA (google-recaptcha)

     • Cloudflare Turnstile (cloudflare-turnstile)

   • Alternância condicional dos blocos na UI:

     • Ao selecionar Cloudflare Turnstile, exibir os campos TURNSTILE_SITE_KEY e TURNSTILE_SECRET_KEY.

     • Ao selecionar Google reCAPTCHA, exibir os campos de reCAPTCHA v3 e v2 existentes.

2. Ferramenta de Teste de Conexão no Painel:

   • Endpoint AJAX para validação instantânea no painel administrativo (admin_environment_ajax_testar_turnstile), permitindo testar se a chave secreta e o token funcionam com retorno amigável do status.

3. Matriz de Validação e Chaves Oficiais de Teste

A Cloudflare fornece credenciais universais e determinísticas para homologação e testes automatizados que não geram dependência externa de tráfego real:

4. Critérios de Aceitação

1. Paridade e Coexistência: O sistema opera perfeitamente com CAPTCHA_PROVIDER = none, google-recaptcha e cloudflare-turnstile.

2. Retrocompatibilidade 100%: Instalações sem CAPTCHA_PROVIDER no .env continuam respeitando USUARIO_RECAPTCHA_ACTIVE sem quebra.

3. Abstração Centralizada: Nenhuma chamada cURL duplicada de captcha permanece solta em controladores ou páginas; toda validação passa pelo helper centralizado.

4. Fluxos de Autenticação Protegidos: Login, cadastro e recuperação de senha validam com sucesso tokens do Turnstile quando ativo.

5. Formulários Dinâmicos: Submissões via formulário público (forms-submissions-process) validam o Turnstile e exibem mensagens de erro amigáveis se o token for ausente/inválido.

6. Painel Administrativo: A tela de Ambiente (admin-environment) salva as configurações e testa as chaves do Turnstile com retorno visual claro.

7. Bateria de Testes: Suíte do PHPUnit cobrindo os cenários de validação (sucesso, falha, timeout, chave inválida) com mock e chaves de teste oficiais, com 100% dos testes da suíte passando sem regressões.