Cloudflare Turnstile
Airspace utiliza Cloudflare Turnstile para proteger los formularios públicos de bots y abuso automatizado. Turnstile proporciona protección similar a CAPTCHA con mínima fricción para el usuario — la mayoría de los visitantes nunca verán un desafío.
Formularios Protegidos
Turnstile está activo en las siguientes páginas:
- Inicio de sesión — previene ataques de relleno de credenciales
- Registro — previene la creación masiva de cuentas
- Incorporación (creación pública de tenant) — previene el aprovisionamiento automatizado de tenants
Configuración
1. Obtener Claves de Turnstile
- Inicie sesión en su panel de Cloudflare
- Navegue a Turnstile en la barra lateral
- Haga clic en Add site
- Ingrese el nombre de su sitio y dominio(s)
- Elija el modo del widget (se recomienda Managed)
- Copie la Site Key y la Secret Key
2. Configurar Variables de Entorno
Agregue lo siguiente a su archivo .env:
TURNSTILE_SITE_KEY=su-site-key-aqui
TURNSTILE_SECRET_KEY=su-secret-key-aqui
Turnstile se activa automáticamente cuando APP_ENV es staging o production. En local, testing y cualquier otro entorno permanece desactivado por defecto, por lo que los desarrolladores no necesitan claves de Cloudflare para trabajar con los formularios de login/registro/incorporación. Establezca TURNSTILE_ENABLED=true solo si desea forzar su activación en un entorno no productivo (por ejemplo, para verificar el comportamiento del widget localmente).
3. Desplegar
No se necesitan pasos adicionales. El widget de Turnstile aparecerá automáticamente en los formularios protegidos.
Deshabilitar Turnstile
Para deshabilitar Turnstile (por ejemplo, para desarrollo), establezca:
TURNSTILE_ENABLED=false
Cuando está deshabilitado:
- El widget no se renderiza en ningún formulario
- La validación del lado del servidor se omite (siempre pasa)
- No se realizan solicitudes a Cloudflare
Solución de Problemas
| Síntoma | Causa | Solución |
|---|---|---|
| El widget no aparece | TURNSTILE_ENABLED es false o falta la site key | Verifique los valores en .env |
| Error "La verificación CAPTCHA falló" | Token expirado o secret key inválida | Verifique que TURNSTILE_SECRET_KEY coincida con su panel de Cloudflare |
| Los formularios funcionan pero no hay widget | JavaScript bloqueado | Asegúrese de que challenges.cloudflare.com no esté bloqueado por CSP o bloqueadores de anuncios |
| La verificación falla después de larga inactividad | Los tokens de Turnstile expiran después de ~5 minutos | El widget se auto-actualiza; si los problemas persisten, recargue la página |