Cloudflare Turnstile
Airspace usa Cloudflare Turnstile para proteger formulários públicos contra bots e abuso automatizado. Turnstile fornece proteção semelhante a CAPTCHA com mínima fricção para o usuário — a maioria dos visitantes nunca verá um desafio.
Formulários Protegidos
Turnstile está ativo nas seguintes páginas:
- Login — previne ataques de credential-stuffing
- Registro — previne criação em massa de contas
- Onboarding (criação pública de tenant) — previne provisionamento automatizado de tenants
Configuração
1. Obter Chaves do Turnstile
- Faça login no seu painel Cloudflare
- Navegue até Turnstile na barra lateral
- Clique em Add site
- Insira o nome do seu site e domínio(s)
- Escolha o modo do widget (Managed é recomendado)
- Copie a Site Key e Secret Key
2. Configurar Variáveis de Ambiente
Adicione o seguinte ao seu arquivo .env:
TURNSTILE_SITE_KEY=sua-site-key-aqui
TURNSTILE_SECRET_KEY=sua-secret-key-aqui
O Turnstile é ativado automaticamente quando APP_ENV é staging ou production. Em local, testing e qualquer outro ambiente ele permanece desligado por padrão, então os desenvolvedores não precisam de chaves da Cloudflare para trabalhar nos formulários de login/registro/onboarding. Defina TURNSTILE_ENABLED=true apenas se quiser forçá-lo em um ambiente não produtivo (por exemplo, para verificar o comportamento do widget localmente).
3. Implantar
Nenhuma etapa adicional é necessária. O widget Turnstile aparecerá automaticamente nos formulários protegidos.
Desabilitando o Turnstile
Para desabilitar o Turnstile (ex.: para desenvolvimento), defina:
TURNSTILE_ENABLED=false
Quando desabilitado:
- O widget não é renderizado em nenhum formulário
- A validação no servidor é ignorada (sempre passa)
- Nenhuma requisição é feita ao Cloudflare
Solução de Problemas
| Sintoma | Causa | Solução |
|---|---|---|
| Widget não aparece | TURNSTILE_ENABLED é false ou site key ausente | Verifique os valores no .env |
| Erro "verificação CAPTCHA falhou" | Token expirado ou secret key inválida | Verifique se TURNSTILE_SECRET_KEY corresponde ao seu painel Cloudflare |
| Formulários funcionam mas sem widget | JavaScript bloqueado | Certifique-se de que challenges.cloudflare.com não está bloqueado por CSP ou bloqueadores de anúncios |
| Verificação falha após página ociosa por muito tempo | Tokens Turnstile expiram após ~5 minutos | O widget atualiza automaticamente; se os problemas persistirem, recarregue a página |