Turnstile no termina al mostrar el widget: valida cada envío protegido en el servidor

Que un widget de Turnstile aparezca en un formulario no demuestra que esté protegido. La documentación de validación en el servidor de Cloudflare exige comprobar el token mediante Siteverify. Si la aplicación acepta el envío sin esa comprobación, una experiencia aparentemente correcta en el navegador no establece una decisión fiable en el servidor.

El objetivo es sencillo: ninguna acción protegida debe continuar solo porque el navegador dice que ha superado la prueba. Construye y verifica primero la decisión del servidor y después conecta el widget y la recuperación para el usuario. Esta guía propone un flujo para implementar y comprobar, no afirma que ClickSyrup haya probado la aplicación de ningún lector.

Sigue el token desde el navegador hasta el servidor

La guía de inicio distingue la sitekey pública de la clave secreta privada. La sitekey pertenece a la integración del cliente; el servidor utiliza el secreto para verificar. No pongas la clave secreta en código del navegador, un repositorio público o una configuración visible al cliente solo para que funcione un prototipo.

Cuando el navegador envía el token con el formulario, remítelo desde el backend al endpoint fijo de Siteverify, con el secreto y el token como entradas obligatorias. Trata la respuesta como datos que hay que validar, no como un permiso implícito por haber completado la petición HTTP. La aplicación necesita el resultado de verificación antes de ejecutar la acción protegida.

Coloca la acción de negocio después de esa decisión. Enviar un correo, crear un registro o aceptar una solicitud y comprobar el token después invierte la protección. Describe expresamente el orden en la tarea de implementación para que los equipos de frontend y backend no supongan que el otro ya lo ha aplicado.

Gestiona de forma deliberada la ausencia de token, su rechazo y la falta de respuesta de verificación. No aceptes silenciosamente la acción en esos casos. Ofrece una vía útil de reintento y conserva los datos no enviados que corresponda, sin incluir información sensible en los registros de diagnóstico. Perder un mensaje largo es un problema de experiencia que debe resolverse, no una razón para omitir la validación.

La caducidad y la reutilización necesitan pruebas propias

Cloudflare documenta una vigencia de 300 segundos y validación de un solo uso. Un token caducado o ya validado puede generar timeout-or-duplicate. En la práctica, un token obtenido al abrir la página puede haber dejado de servir cuando el visitante termina un formulario largo.

Prueba ese caso de cumplimentación lenta, no solo el envío inmediato tras superar el widget. Confirma que la aplicación obtiene un token nuevo y permite reintentar sin repetir inesperadamente la acción de negocio. El visitante no debería necesitar conocimientos sobre tokens para recuperarse de una demora normal.

Separa la reutilización del token de la idempotencia de la operación. Un token válido no garantiza por sí solo que la aplicación nunca cree dos registros iguales tras un reintento de red o un doble clic. Diseña la operación para reconocer sus propias solicitudes repetidas cuando sea necesario y prueba ese comportamiento aparte del widget.

Si el backend reintenta una llamada de verificación, usa los mecanismos documentados de reintento e idempotencia de la API, sin asumir que el mismo token puede validarse indefinidamente. Anota qué capa se repite: envío del navegador, petición Siteverify o transacción de negocio. Confundirlas dificulta explicar los fallos intermitentes.

Comprueba el host y la acción previstos, no solo el éxito

La respuesta de verificación incluye contexto, como hostname y, cuando se configura, action. Contrástalos con los valores esperados definidos por la aplicación. No aceptes como expectativa un host o una acción proporcionados por el propio formulario no confiable: permitirías que la petición definiera la regla que debe cumplir.

La guía de gestión de hostnames explica cómo se autorizan los dominios del widget. También señala que añadir un dominio raíz autoriza sus subdominios. Elige el alcance conscientemente y revísalo al pasar de pruebas a producción. La configuración del widget y la comprobación del servidor deben respaldar el despliegue previsto, no aprobar accidentalmente otros entornos.

Turnstile sigue siendo una capa. La autenticación determina quién es el usuario; la autorización, qué puede hacer; y la aplicación aún necesita validar entradas y controlar adecuadamente las peticiones. Superar un desafío no justifica aceptar cualquier dato ni dejar que un usuario actúe sobre la cuenta de otra persona.

Revisa también cómo se entrega la página. Si hay caché, mantén las respuestas de cuentas y el estado sensible fuera de las cachés compartidas, siguiendo la separación de nuestra guía de caché de Cloudflare. Un desafío que funciona no corrige una regla independiente que expone contenido privado.

Demuestra los casos negativos antes del lanzamiento

Cloudflare ofrece claves y orientaciones de prueba para casos controlados de éxito y fallo. Usa esas credenciales documentadas en el entorno de pruebas correspondiente, no como protección de producción. Sirven para repetir verificaciones sin depender del resultado de un desafío real de visitante.

Crea un registro de aceptación con un envío válido, token ausente, verificación fallida, token caducado, reutilización de uno ya validado y host o acción inesperados. En cada caso, registra tanto la respuesta al usuario como si el backend realizó realmente la operación. Un mensaje tranquilizador no demuestra que el sistema no haya aceptado nada.

Añade una interrupción del servicio de verificación al plan y acuerda antes del lanzamiento qué verá el usuario. Comprueba también la recuperación cuando vuelva el servicio. Integra las pruebas en la rutina de mantenimiento del sitio, especialmente tras cambios en formularios, proxies inversos, secretos o entornos de despliegue.

El criterio de lanzamiento no es una captura del widget. Es un resultado reproducible: las solicitudes permitidas se completan una vez como corresponde, las rechazadas no ejecutan la acción, los secretos quedan en el servidor y los visitantes legítimos pueden recuperarse claramente. Esa es la diferencia entre añadir un componente visible y aplicar una protección.