Chau spam en tu formulario con Cloudflare Turnstile.

Qué es Turnstile

Turnstile es la alternativa de Cloudflare al captcha: la documentación lo define como «Cloudflare's smart CAPTCHA alternative». Se agrega a tu formulario y decide si quien lo manda es una persona o un bot. En vez de pedir que elijas semáforos, en el modo recomendado no pide nada o, como mucho, que tildes una casilla.

No hace falta que tu web esté en Cloudflare: según la documentación, «can be embedded into any website without sending traffic through Cloudflare». Solo necesitás una cuenta de Cloudflare.

Qué incluye el plan gratis

Modos del widget

Cómo funciona

Turnstile tiene dos partes y necesitás las dos:

El widget le da al formulario un token. Tu servidor manda ese token a Cloudflare con la clave secreta y Cloudflare le dice si es válido. Cada token vale 300 segundos y se puede validar una sola vez. La documentación es clara: «The client-side widget alone does not protect your forms».

Pasos

1. Creá el widget. Entrá al panel de Cloudflare con tu cuenta, creá un widget de Turnstile con el dominio de tu web y elegí el modo (Managed es el recomendado). Te da dos claves: la del sitio y la secreta. La secreta no la pongas nunca en el HTML.
2. Cargá el script. En la página del formulario agregá <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>.
3. Poné el widget en el formulario. Dentro del formulario agregá <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div> y reemplazá <YOUR-SITE-KEY> por tu clave del sitio.
4. Validá en el servidor. Cuando tu servidor recibe el formulario, hacé un POST a https://challenges.cloudflare.com/turnstile/v0/siteverify con dos parámetros: secret (tu clave secreta) y response (el token que mandó el formulario). Si Cloudflare dice que no es válido, rechazá el envío.
5. Probá las dos puntas. Mandá el formulario desde el navegador: tiene que pasar. Después mandalo sin token, por ejemplo con curl, como haría un bot: tu servidor tiene que rechazarlo.

Claves de prueba

Cloudflare publica claves oficiales para probar sin cuenta y sin tocar tu sitio publicado.

Para probar la validación del servidor a mano:

curl -X POST https://challenges.cloudflare.com/turnstile/v0/siteverify -d secret=1x0000000000000000000000000000000AA -d response=TOKEN_DE_PRUEBA

Cuando termines de probar, cambiá las claves de prueba por las de tu widget.

Si algo falla

• Los bots siguen mandando mensajes: revisá que tu servidor llame a siteverify en cada envío y rechace los que no validan. Con el widget solo no alcanza.
• Un envío legítimo da error al validar: el token vence a los 300 segundos y se valida una sola vez. Si el formulario quedó abierto mucho tiempo o el servidor valida dos veces el mismo token, falla.
• El widget no aparece: confirmá que el <script> de api.js esté en la página y que el div tenga la clase cf-turnstile y tu clave del sitio en data-sitekey.
• Funciona en un dominio y en otro no: el widget va atado a los hostnames que cargaste al crearlo (hasta 10 por widget). Agregá el que falta.
• No sabés si el problema está en tu código o en las claves: cambiá a las claves de prueba que siempre pasan; si así anda, el problema está en tus claves o en el dominio del widget.
• Te pide tildar una casilla: es normal en modo Managed, que según el riesgo puede pedirla.