REQ-SEC-05 — reCAPTCHA en formularios
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ón | Entregable |
|---|---|
| CA1 · Los formularios incluyen reCAPTCHA | Login y recuperación de contraseña ejecutan Google reCAPTCHA v3 (invisible) |
| CA2 · El reCAPTCHA está activo y operativo | Verificació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)yRecaptchaGuardglobal). Sin dependencias nuevas: usa elfetchde Node. Los endpoints marcados responden 400 conCAPTCHA_REQUERIDO/CAPTCHA_INVALIDOcuando no pasan. - Frontend:
src/lib/recaptcha.tscarga el script una sola vez y exponeejecutarRecaptcha(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,scorebajo, 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.tscEXIT 0 en API y web;next lintsin errores nuevos.
Nota: la suite web mantiene 3 suites previas en rojo (
sesiones,login-2fa,sesion-aviso, expectativas del token enlocalStorageretirado por TEC-019); son ajenas a este requerimiento.
📚 Documentación
- Manual: reCAPTCHA en Formularios
- Spec: REQ-SEC-05: reCAPTCHA en Formularios
- Relacionado: Protección contra bots, Rate limiting
