REQ-COM-02 — «Forzar contraseña» envía de verdad la nueva contraseña (Resend)
El login ya tenía el modal «Forzar contraseña» y el API ya hacía casi todo: generaba una
contraseña temporal que cumplía la política vigente (TEC-009), la persistía, cerraba las sesiones
abiertas (TEC-010), dejaba el rastro en la auditoría (TEC-008)… y no enviaba nada. En
usuarios.service.ts el envío era un comentario:
// In a real application, you would send this password via email
// For now, we'll just return a success message
La contraseña en claro se descartaba al hashearla. El usuario nunca la recibía y el sistema, además, respondía «enviada». El flujo estaba roto de punta a punta: había que conectarlo.
🔌 Qué se hizo
REQ-COM-02 añade un módulo de correo transversal src/common/correo/ que envuelve el SDK
oficial de Resend y conserva el patrón de degradación elegante del resto de integraciones
externas del proyecto (reCAPTCHA, Redis, Web Push): sin RESEND_API_KEY no se cae nada, solo queda
una advertencia en el log.
| Pieza | Rol |
|---|---|
common/correo/correo.module.ts | Declara y exporta CorreoService |
common/correo/correo.service.ts | enviarPasswordTemporal() sobre resend.emails.send(); lee RESEND_API_KEY, RESEND_FROM_EMAIL, RESEND_FROM_NAME y CORREO_HABILITADO |
common/correo/plantillas/password-temporal.ts | Plantilla pura (subject/html/text) en español |
common/correo/correo.service.spec.ts | 5 pruebas con el SDK mockeado |
En el dominio de usuarios, UsuariosModule importa CorreoModule y UsuariosService recibe
CorreoService como dependencia @Optional() — el mismo recurso que ya usaba con
SesionesService: no rompe las pruebas que construyen el servicio a mano y evita ciclos de módulos.
const enviado = await this.correo?.enviarPasswordTemporal(
usuario.email,
usuario.nombreCompleto,
newPassword,
);
if (enviado === false) {
throw new ServiceUnavailableException(
'No se pudo enviar el correo de recuperación. Intenta de nuevo.',
);
}
Se persiste antes de enviar (el orden que ya tenía el código): si el envío falla, la contraseña
ya cambió, así que se responde 503 para que el usuario reintente —que genera otra y reenvía— en
lugar de dejarlo a ciegas con un falso «enviado».
🔒 De paso, dos agujeros menos
| Antes | Ahora |
|---|---|
Un correo inexistente devolvía 404 Usuario no encontrado: el endpoint decía qué cuentas existen | Respuesta genérica idéntica exista o no la cuenta (Si el correo está registrado, enviamos una nueva contraseña); el 404 desaparece de Swagger y aparece el 503 |
getForgotPassword devolvía null al fallar, así que el modal mostraba siempre «enviado» en inglés | El error se propaga con extraerMensajeError, el resultado se sigue con estado propio (ok/error) y los mensajes van en español; el icono de éxito solo aparece cuando el correo salió de verdad |
⚙️ Configuración
# ── Correo transaccional con Resend (REQ-COM-02) ─────────────────────────
CORREO_HABILITADO=true
RESEND_API_KEY=
# Debe pertenecer a un dominio verificado en Resend.
RESEND_FROM_EMAIL=noreply@cdsmaya.com.co
RESEND_FROM_NAME=Modulo de Almacen
La API key se crea en resend.com/api-keys y el dominio del remitente tiene que figurar como
verified en resend.com/domains. Si no lo está, Resend rechaza el envío y el endpoint responde
503.
Se mantienen los controles que ya protegían el endpoint:
@RequiereCaptcha('forgot_password')(REQ-SEC-05) y el rate limit de 5 peticiones por minuto (TEC-005).
🧪 Pruebas
| Prueba | Resultado |
|---|---|
npx tsc --noEmit (API) | EXIT 0 |
common/correo/correo.service.spec.ts | 5/5 OK |
usuarios/usuarios.service.passwords.spec.ts | 14/14 OK (envío, anti-enumeración y fallo de envío) |
npx tsc --noEmit (web) | EXIT 0 |
Queda la verificación en el servidor: pedir la recuperación con un usuario real, confirmar el correo desde el dominio verificado, entrar con la contraseña recibida y comprobar que el modal solo celebra cuando el correo salió.
🚫 Fuera de alcance
| Exclusión | Por qué |
|---|---|
| Enlace de restablecimiento con token de un solo uso | Se decidió mantener el flujo actual (contraseña temporal por correo); el token queda como mejora futura |
Unificar el transporte con EmailService (nodemailer, reportes) | Conviven: reportes por SMTP, transaccional por Resend. Unificarlos es una decisión aparte |
📚 Documentación
- Spec: REQ-COM-02: Recuperación de contraseña con envío real por Resend
- Framework:
ccf-almacen-framework/DOMINIOS/USUARIOS.md - Relacionadas: TEC-009: Políticas de contraseñas, TEC-010: Sesiones concurrentes, REQ-SEC-05: reCAPTCHA en formularios
