Turnstile: la prueba de humanidad sin acertijos

Durante una década el peaje de internet fue el acertijo visual: identifica los semáforos, transcribe el texto borroso, demuestra con el ratón que eres de carne. Ese contrato se rompió por los dos extremos a la vez, porque hoy una máquina resuelve esos acertijos mejor y más barato que tú, mientras el humano legítimo abandona el formulario a la tercera cuadrícula. Turnstile acepta la ruptura y cambia la pregunta: en lugar de exigirte una demostración activa, observa cómo se comporta tu navegador y emite un veredicto. La fricción desaparece del usuario y reaparece donde debía estar desde el principio, en el servidor que decide si creerse el veredicto.

Dos claves y un token

El montaje tiene tres piezas y conviene nombrarlas bien desde el principio. La sitekey es pública y vive en el HTML: identifica tu widget y no protege nada. La clave secreta es privada, vive como secreto cifrado del Worker y es lo único que autoriza a preguntar por un veredicto. Y entre ambas está el token, una cadena efímera que el widget entrega al navegador y que el navegador te manda a ti.

El ciclo completo es este: el widget evalúa el navegador sin molestar al usuario, produce un token, el formulario lo envía junto al resto de los campos, y tu Worker cambia ese token por un veredicto llamando a la API de validación con la clave secreta. El token, por sí solo, no significa nada hasta que lo canjeas.

sequenceDiagram
participant N as navegador
participant T as widget Turnstile
participant W as Worker
participant S as siteverify
N->>T: carga el widget con la sitekey
T-->>N: token efimero
N->>W: envia el formulario con el token
W->>S: token mas clave secreta
S-->>W: veredicto success mas hostname y action
W-->>N: acepta o rechaza

El widget en el cliente

En su forma más simple es un contenedor con la sitekey y el script de la plataforma. El widget se inyecta solo, resuelve su comprobación y deja el token en un campo oculto del formulario llamado cf-turnstile-response, que viaja con el envío sin que tú tengas que tocarlo.

<form method="POST" action="/contacto">
  <input type="email" name="correo" required />
  <textarea name="mensaje" required></textarea>

  <div class="cf-turnstile"
       data-sitekey="0x4AAAAAAA_clave_publica"
       data-action="contacto"
       data-theme="auto"></div>

  <button type="submit">Enviar</button>
</form>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

Hay tres modos y la elección es de producto, no de seguridad. El gestionado deja que la plataforma decida si hace falta una interacción, y es el buen valor por defecto. El no interactivo nunca pide nada al usuario pero sigue mostrando el widget, útil cuando quieres que se vea la señal de que hay una comprobación. El invisible no muestra nada en absoluto, ideal para formularios muy cuidados, a costa de que el usuario no tenga ninguna explicación visual si algo falla.

En una aplicación de una sola página el montaje implícito estorba, porque el widget debe aparecer y renovarse en momentos que decide tu código. Para eso existe el renderizado explícito: cargas la librería, esperas a que esté lista y montas el widget sobre un contenedor cuando toca, recogiendo el token en una función de retorno en lugar de en un campo del formulario. Es más trabajo, y a cambio te devuelve el control sobre el ciclo de vida, que es justo lo que necesitas para poder refrescar un token caducado sin recargar la página.

La verificación en el Worker

Todo lo anterior es decorado hasta este punto. La validación es una petición POST con la clave secreta y el token, y su respuesta es el único juicio que importa.

type Veredicto = {
  success: boolean;
  hostname?: string;
  action?: string;
  challenge_ts?: string;
  "error-codes"?: string[];
};

async function verificar(env: Env, token: string, ip: string): Promise<Veredicto> {
  const cuerpo = new FormData();
  cuerpo.append("secret", env.TURNSTILE_SECRET);
  cuerpo.append("response", token);
  cuerpo.append("remoteip", ip);
  cuerpo.append("idempotency_key", crypto.randomUUID());

  const r = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
    method: "POST",
    body: cuerpo,
  });
  return await r.json<Veredicto>();
}

export default {
  async fetch(request, env): Promise<Response> {
    const form = await request.formData();
    const token = String(form.get("cf-turnstile-response") ?? "");
    const ip = request.headers.get("CF-Connecting-IP") ?? "";

    const v = await verificar(env, token, ip);
    const valido = v.success && v.hostname === "ejemplo.com" && v.action === "contacto";

    if (!valido) {
      return new Response("Verificacion fallida", { status: 403 });
    }
    return new Response("Mensaje recibido", { status: 202 });
  },
} satisfies ExportedHandler<Env>;

Mirar solo success es el error habitual, y es el que anula la protección en la práctica. Un token es válido para el sitio que lo emitió, así que sin comprobar hostname aceptas tokens generados en un dominio ajeno con tu misma sitekey copiada. Sin comprobar action, aceptas en tu endpoint caro un token cosechado del formulario más barato de tu web.

Lo que prueba y lo que no

Conviene ser preciso con el alcance, porque la confusión aquí produce arquitecturas falsamente tranquilas. Turnstile aporta evidencia probabilística de que el envío viene de un navegador real gobernado por una persona, en el momento de emitir el token. Eso es todo, y es mucho.

No dice quién es esa persona, así que no sustituye a la autenticación. No impide que un humano real haga cien envíos manuales, así que no sustituye al límite de tasa. No valida el contenido del formulario, así que no sustituye a la sanitización. Y no resiste a un adversario dispuesto a pagar a personas por resolver comprobaciones, porque contra eso ninguna prueba de humanidad puede nada por definición: hay humanos de verdad al otro lado.