Cloudflare Turnstile - MVP - Node.js - formularios - seguridad
6 min lectura

Protege la lista de espera de tu MVP: Turnstile debe verificarse en el servidor

Prueba un formulario con Turnstile y Node.js: token válido, ausente y rechazado. Código copiable y límite antes de guardar correos.

Protege la lista de espera de tu MVP: Turnstile debe verificarse en el servidor

Tu landing recibe cien registros y parece que hay interés. Luego descubres direcciones inventadas y bots. Si el formulario de tu MVP tiene un widget de Cloudflare Turnstile, eso por sí solo no protege la lista: el navegador puede enviar cualquier texto al endpoint. La verificación decisiva ocurre en el servidor, antes de guardar el correo o disparar un email.

Esta guía usa una lista de espera como caso, un formulario HTML y un servidor Node.js sin dependencias externas. Es un tutorial para una función disponible, no un lanzamiento nuevo. Probé localmente las respuestas con las claves de prueba oficiales de Cloudflare: un envío sin token devolvió 400, uno con token de prueba válido devolvió 200 y un token rechazado devolvió 403. No probé un widget de producción ni conecté una base de datos.

Por qué el widget visible no basta

Turnstile produce un token en el navegador. Tu backend debe enviarlo a Siteverify y comprobar la respuesta antes de aceptar el registro. Cloudflare llama obligatoria a esta validación. La documentación del endpoint indica que el token caduca a los cinco minutos y está pensado para un solo uso. Si un agente genera una landing y solo añade el recuadro al HTML, el endpoint sigue expuesto.

Diagrama: formulario envía token al servidor, este consulta Siteverify y guarda solo si es válido

La siguiente prueba no almacena correos: retorna una confirmación únicamente después de verificar el token. Conecta tu base de datos o proveedor de email en el punto señalado del servidor, nunca antes. Eso permite verificar la seguridad de la puerta sin fingir que ya existe una lista operativa.

1. Crea el formulario

Guarda este HTML como form.html. El sitekey que aparece es un valor de prueba oficial que siempre genera un token válido en un entorno de test. Para producción, crea tu propio widget en Cloudflare, configura el dominio permitido y sustituye la clave pública. El formulario debe enviar al mismo backend que valida el token.

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<form method="post" action="/signup">
  <label>Correo <input type="email" name="email" required></label>
  <div class="cf-turnstile" data-sitekey="1x00000000000000000000AA"></div>
  <button type="submit">Unirme</button>
</form>

El script y la clase cf-turnstile siguen el método de renderizado implícito de Cloudflare. El widget agrega el campo cf-turnstile-response al envío. Si usas React y el formulario aparece después de cargar la página, revisa el renderizado explícito en esa documentación: copiar el HTML estático puede no inicializarlo en una SPA.

2. Verifica antes de guardar

Guarda este servidor como server.mjs. Requiere Node.js con fetch global. TURNSTILE_SECRET_KEY vive solo en el servidor; EXPECTED_HOSTNAME debe ser el dominio real de tu landing. Además del resultado success, comprobar el hostname impide aceptar un token emitido para otra web. El ejemplo limita el tamaño del cuerpo y rechaza errores de red, pero no reemplaza límites de frecuencia, deduplicación, confirmación de correo ni validación más estricta.

import { createServer } from 'node:http';

const secret = process.env.TURNSTILE_SECRET_KEY;
const expectedHostname = process.env.EXPECTED_HOSTNAME;
if (!secret || !expectedHostname) throw new Error('Set TURNSTILE_SECRET_KEY and EXPECTED_HOSTNAME');

createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/signup') {
    res.writeHead(404).end('Not found');
    return;
  }
  try {
    let raw = '';
    for await (const chunk of req) {
      raw += chunk;
      if (raw.length > 10_000) { res.writeHead(413).end('Too large'); return; }
    }
    const form = new URLSearchParams(raw);
    const token = form.get('cf-turnstile-response');
    const email = form.get('email')?.trim();
    if (!token || !email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      res.writeHead(400).end('Missing or invalid fields');
      return;
    }
    const body = new URLSearchParams({ secret, response: token });
    const reply = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
      method: 'POST', body, signal: AbortSignal.timeout(5000)
    });
    if (!reply.ok) { res.writeHead(503).end('Verification unavailable'); return; }
    const check = await reply.json();
    if (check.success !== true || check.hostname !== expectedHostname) {
      res.writeHead(403).end('Verification failed');
      return;
    }
    // Verification succeeded. Save to your own database or email provider here.
    res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' }).end('Verified; connect your signup storage');
  } catch {
    res.writeHead(503).end('Verification unavailable');
  }
}).listen(Number(process.env.PORT || 3039), '127.0.0.1', () => console.log(`http://127.0.0.1:${process.env.PORT || 3039}`));

3. Ejecuta tres pruebas sin una cuenta de pago

En una terminal de desarrollo, usa el secreto de prueba y el hostname example.com. Cloudflare documenta que sus claves de prueba devuelven ese hostname fijo, aunque el formulario se abra en localhost. Inicia el servidor y prueba los caminos:

TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA EXPECTED_HOSTNAME=example.com node server.mjs
curl -i -X POST http://127.0.0.1:3039/signup -d 'email=a@example.com'
curl -i -X POST http://127.0.0.1:3039/signup -d 'email=a@example.com&cf-turnstile-response=XXXX.DUMMY.TOKEN.XXXX'

El primero debe fallar con 400; el segundo debe pasar con 200. Para probar el rechazo, reinicia el servidor con TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA y envía el mismo token: debe devolver 403. Esas claves de prueba oficiales no demuestran que tu dominio de producción esté configurado correctamente. Cloudflare advierte que las claves reales y de prueba no deben mezclarse.

Antes de abrir la lista al público

Sustituye ambas claves por las de tu widget real, guarda el secreto en variables del servidor y cambia EXPECTED_HOSTNAME a tu dominio. Haz una prueba real desde la página publicada; confirma que un token omitido o repetido se rechaza y que solo un envío validado llega a tu base de datos. Aplica deduplicación por correo, límite de tasa y confirmación por email si el registro tiene consecuencias. Si falla Siteverify, este ejemplo responde 503 y no guarda nada: mejor pedir reintento que aceptar registros sin prueba.

Según los planes oficiales, Turnstile tiene un plan gratuito con hasta 20 widgets, 10 hostnames por widget y desafíos ilimitados; Enterprise agrega otras capacidades. Revisa el plan vigente si tu caso crece. La decisión para un fundador es clara: si tu lista de espera recibe tráfico público, exige verificación del token en el servidor antes de conectarla con tu CRM. Un widget bonito sin esa llamada no reduce el riesgo principal.

Recibe lo nuevo en tu correo

Workshops gratis, herramientas y novedades de IA aplicadas a negocio, sin humo.

🎓 Workshops en vivo🛠️ Herramientas nuevas⚡ Novedades de IA

Sin spam. Te das de baja cuando quieras.

Comentarios

Aún no hay comentarios. Sé el primero.

Deja un comentario