For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /es/docs/web/captcha.md (or send Accept: text/markdown).

Protección antispam

Comprobaciones Turnstile conmutables por entorno en formularios públicos y endpoints de auth.

Preguntar sobre esta guía

Guía paso a paso para principiantes

Requisitos previos: lea las dos guías para principiantes a continuación, finalice la configuración local web y abra este monorepo en la raíz de su editor. La configuración web pertenece a apps/web/.env.local; Next.js no lee la raíz .env. /dashboard en el modo falso predeterminado es una demostración sin base de datos; /auth necesita una base de datos migrada.

Términos breves: un espacio de trabajo son los usuarios, datos y configuraciones separados de un equipo. El servidor es el backend confiable; Mantenga las claves del proveedor fuera del código del navegador y del teléfono. Una migración es un cambio de base de datos versionada que crea o actualiza tablas. Un modelo de IA es el motor que responde; el catálogo de modelos es la lista del servidor de ID de modelos disponibles y precios. Un proveedor es un servicio externo, como inteligencia artificial, correo electrónico o servicio de facturación. Un derecho es una concesión que permite que un espacio de trabajo utilice una función. Un webhook es un mensaje que un servicio envía al URL de otro servicio.

1. Cree un widget de prueba de Turnstile para el nombre de host local/implementado exacto. En apps/web/.env.local, configure CAPTCHA_PROVIDER=turnstile y NEXT_PUBLIC_TURNSTILE_SITE_KEY; coloque TURNSTILE_SECRET_KEY solo en el almacén secreto del servidor.

2. Reinicie y envíe un formulario de contacto de prueba.

3. Espere el desafío y una respuesta exitosa con una ficha válida. Si todas las solicitudes fallan, compare el nombre de host y el par de claves; Nunca expongas la clave secreta.

Para obtener código personalizado, comience con el prompts/README.md proporcionado y copie el mensaje más cercano: prompts/new-app-screen.md para una pantalla de aplicación o prompts/new-landing-page.md para una página pública. Para trabajos de servidor, base de datos o proveedor, asigne a su agente de codificación la tarea de esta guía y pídale que lea AGENTS.md, .ai/PROJECT_CONTEXT.md y los espejos .ai/ correspondientes; inspeccionar los archivos fuente exactos nombrados aquí; enumerar archivos y verificaciones antes de editarlos; preservar la propiedad del espacio de trabajo y los secretos exclusivos del servidor; y mostrarte la diferencia. Dígale el comportamiento que desea, los campos de entrada y salida, los roles permitidos, los éxitos y errores esperados y la cuenta, proveedor o dispositivo de prueba. Utilice valores de muestra; Nunca pegues un verdadero secreto.

Habilita ambas claves

CAPTCHA_PROVIDER=off es el valor predeterminado. Selecciona turnstile, configura el nombre de host correspondiente en tu aplicación Turnstile y proporciona ambas claves. NEXT_PUBLIC_TURNSTILE_SITE_KEY es pública; TURNSTILE_SECRET_KEY solo la usa el verificador del servidor.

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

Conserva las superficies protegidas

La barrera cubre formularios de contacto/boletín y endpoints de credenciales Better Auth para iniciar sesión, registrarse, OTP y restablecer la contraseña. Complementa la validación y los límites de solicitudes; no sustituye las sesiones ni la autorización del espacio de trabajo.

Verifica el rechazo y la recuperación

Prueba un token válido, un token ausente/caducado/no válido, un fallo del verificador y un reintento después de que el widget del cliente se restablezca. Mantén instrucciones útiles para la comprobación humana y acceso por teclado; revisa la cobertura del motor de autenticación elegido antes de cambiar de proveedor.

Configuración y ajustes

CAPTCHA_PROVIDER selecciona el verificador: off (el valor por defecto, para que el desarrollo local no necesite credenciales) o turnstile. Activar turnstile requiere TURNSTILE_SECRET_KEY en el servidor y NEXT_PUBLIC_TURNSTILE_SITE_KEY para el widget de cliente — el esquema de config falla el arranque si falta alguna.

apps/web/src/captcha.ts compone un verificador único por proceso que envía el token al endpoint siteverify de Cloudflare con un timeout de diez segundos y falla cerrado — un token no verificable nunca se toma como prueba de humanidad.

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

Flujo de implementación

CaptchaWidget (src/captcha-widget.tsx) renderiza el widget e inyecta el campo cf-turnstile-response en el formulario padre, mientras que las llamadas del cliente de auth llevan el token en la cabecera x-captcha-response. Las acciones de contacto y newsletter verifican antes de escribir — una comprobación fallida devuelve status=captcha en lugar de crear un lead.

packages/auth monta el plugin captcha de better-auth cuando el provider está activo; CAPTCHA_ENDPOINTS cubre las rutas de entrada de credenciales y emisión de tokens — sign-in, sign-up, envío de OTP, restablecimiento de contraseña. Los endpoints consumidores como check-verification-otp quedan fuera de la lista: allí el propio OTP o token es la prueba.

Verificación y solución de problemas

Envía cada formulario protegido con un token ausente y con uno malformado — ambos deben fallar cerrado. Verifica que un siteverify inalcanzable rechaza en lugar de dejar pasar, que provider=off deja abierto el desarrollo local y que el secreto nunca llega a los bundles del cliente ni a los logs.