Migra desde Cloudflare Turnstile
Caputchin usa el mismo modelo de dos partes que Cloudflare Turnstile, un widget en la página que produce un token, y una comprobación en el servidor que lo confirma, así que migrar es sobre todo un cambio mecánico, no una reescritura. Turnstile es el más cercano de los proveedores comunes a Caputchin, porque ambos devuelven un aprobado/fallo autoritativo en vez de un score de riesgo, así que no hay umbral que reafinar. Esta guía da el antes-y-después de cada pieza.
Si todavía no has creado una cuenta de Caputchin y una clave de sitio, crea tu cuenta primero; necesitarás una clave pública (cpt_pub_...) para la página y un secreto (cpt_sec_...) para tu backend, la misma división que la site key y la secret key de Turnstile.
El modelo mental no cambia
Todo lo que ya construiste alrededor de Turnstile, renderizar un widget, recoger un token, hacer POST a tu servidor, verificarlo antes de fiarte de la petición, se queda. Solo cambian los nombres y los endpoints.
1. Cambia el snippet del cliente
| Turnstile | Caputchin | |
|---|---|---|
| Script | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Elemento | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Campo de token en un formulario | cf-turnstile-response (auto-inyectado) | caputchin-token (auto-inyectado) |
| Leer el token en JS | turnstile.getResponse() | el detail.token del evento pass |
Como Turnstile, el widget de Caputchin auto-inyecta un campo de token oculto en el formulario en el que está, así que si tu formulario ya hacía un POST normal, solo cambias el elemento y el nombre del campo que tu backend lee. Mira añade el widget para la configuración completa del cliente y la elección entre CDN y npm.
2. Cambia la verificación del servidor
Aquí es donde los dos están más cerca, las formas de petición y respuesta se alinean casi campo por campo.
| Turnstile | Caputchin | |
|---|---|---|
| Endpoint | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Campos de petición | secret, response | secret, response (idéntico) |
| Respuesta | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| Regla de confianza | actúa solo si success === true | actúa solo si success === true (idéntico) |
En la mayoría de los stacks el único cambio a tu código de verificación es la URL y el valor del secreto; ambos ya ramifican según success, así que no hay umbral de score que portar. Turnstile también acepta JSON para la llamada de verify, exactamente como Caputchin, así que la forma del cuerpo se traslada sin cambios. La referencia completa de petición/respuesta, incluidos los códigos de error, está en verifica un token en tu backend; los snippets por framework están en ejemplos de backend.
Si tu integración de Turnstile leía action o cdata de la respuesta, nota que Caputchin no tiene un equivalente directo; esas son etiquetas específicas de Turnstile que fijas en el widget. El metadato análogo de Caputchin (qué juego se jugó, su puntuación) vive en el bloque platform de la respuesta y es solo informativo.
Qué se traslada, y qué mejora
- Sigue siendo un aprobado/fallo limpio. Conservas la regla de confianza más simple posible,
if (success), sin probabilidad ni umbral que mantener. - La postura de privacidad por la que elegiste Turnstile, conservada. Caputchin no recoge IP, User-Agent, huella, ni telemetría de comportamiento; el protocolo no tiene dónde poner un identificador de visitante. Mira la filosofía.
- Un juego opcional. En vez de un reto invisible o gestionado, puedes convertir la verificación en un juego corto que tus visitantes de verdad juegan, y es la parte que aguanta frente a los solvers de IA. Mira añade un juego.
- Una CSP estricta se queda estricta. Caputchin corre bajo una Content-Security-Policy apretada; permites unos pocos origins en vez de aflojar tu política. Mira cómo Caputchin pone los juegos en sandbox.
Gotchas
- Dos claves, dos hogares. La clave pública (
cpt_pub_...) va en la página; el secreto (cpt_sec_...) se queda solo en el servidor, exactamente la disciplina de Turnstile. No envíes el secreto al navegador. - El token es de un solo uso. Como Turnstile, un token verifica una vez. No lo caches ni lo repitas.
- Cambia el nombre del campo que tu backend lee. El campo oculto es
caputchin-token, nocf-turnstile-response, un fallo común de una línea. - Sin
action/cdata. Si ramificabas según esos, mueve esa lógica a otro sitio; Caputchin no los lleva.
Véase también
- Añade el widget: la configuración completa del cliente.
- Verifica un token en tu backend: la referencia autoritativa de
siteverify. - Ejemplos de backend: la llamada de verify en cada lenguaje.
- Añade un juego: convierte la verificación en un juego.