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_ENABLED=true
TURNSTILE_SITE_KEY=sua-site-key-aqui
TURNSTILE_SECRET_KEY=sua-secret-key-aqui
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 |