Saltar al contenido principal

REQ-SEC-05 — reCAPTCHA en formularios

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Cierra el requerimiento REQ-SEC-05 (reCAPTCHA en formularios), de Seguridad y prioridad Alta. El login y la recuperación de contraseña ya se defendían de forma no interactiva (honeypot y bloqueo por User-Agent/ruta de TEC-018, límite de tasa de TEC-005, 2FA de TEC-006), pero faltaba una comprobación de que el envío era humano.


📋 Alcance​

Criterio de aceptaciónEntregable
CA1 · Los formularios incluyen reCAPTCHALogin y recuperación de contraseña ejecutan Google reCAPTCHA v3 (invisible)
CA2 · El reCAPTCHA está activo y operativoVerificación server-side contra siteverify + badge de Google visible

⚙️ Cómo funciona​

Formulario (login / recuperación)
└─ grecaptcha.execute(siteKey, { action }) ──▶ token
│
▼
POST /api/auths/login · /api/usuarios/forgot-password { ..., recaptchaToken }
│
▼
RecaptchaGuard (APP_GUARD, solo endpoints con @RequiereCaptcha)
└─ RecaptchaService ──▶ https://www.google.com/recaptcha/api/siteverify
(success · action · score ≥ RECAPTCHA_MIN_SCORE)
  • Backend: submódulo common/seguridad/recaptcha/ (config por entorno, servicio de verificación, @RequiereCaptcha(accion) y RecaptchaGuard global). Sin dependencias nuevas: usa el fetch de Node. Los endpoints marcados responden 400 con CAPTCHA_REQUERIDO / CAPTCHA_INVALIDO cuando no pasan.
  • Frontend: src/lib/recaptcha.ts carga el script una sola vez y expone ejecutarRecaptcha(accion). El token se envía junto al formulario.

🎯 Degradación elegante​

Igual que VAPID o webhooks: sin claves el captcha queda apagado y los formularios siguen funcionando. Al configurar NEXT_PUBLIC_RECAPTCHA_SITE_KEY (web) y RECAPTCHA_SECRET_KEY (API) con RECAPTCHA_ENABLED=true, la verificación se activa. Así, desarrollo, pruebas y despliegues sin claves no se bloquean.

La CSP de next.config.js solo se amplía (script-src, frame-src y connect-src a google.com/gstatic.com) cuando hay site key.

🧩 Cambio colateral​

El endpoint POST /api/usuarios/forgot-password pasa a público (@Public()): antes exigía sesión, de modo que el flujo de recuperación era inalcanzable desde el login. Ya tenía rate limit estricto y ahora también captcha. Se reactiva el enlace «¿Forzar contraseña?» del formulario de login.

🧪 Pruebas​

  • ccf-almacen-api/src/common/seguridad/recaptcha/ — 18 casos: config (clave/interruptor/umbral), servicio (success, score bajo, acción distinta, error HTTP y fallo de red) y guard (sin metadato, deshabilitado, sin token, inválido y válido).
  • ccf-almacen-web/src/lib/recaptcha.spec.ts — 3 casos: degradación sin site key, token por acción e inyección única del script.
  • tsc EXIT 0 en API y web; next lint sin errores nuevos.

Nota: la suite web mantiene 3 suites previas en rojo (sesiones, login-2fa, sesion-aviso, expectativas del token en localStorage retirado por TEC-019); son ajenas a este requerimiento.

📚 Documentación​