0035. Cambio de la contraseña propia (CU-04)¶
Estado: Aceptado Fecha: 2026-10-01 Autor: Duval Alcivar Módulo(s) afectado(s): app/core/security.py, app/domains/usuarios/, alembic/versions/, tests/unit/, docs/adr/
Contexto¶
Al crear un usuario, mae_usuarios.password_temp nace en true (ADR 0027) y el
paso 1 del login lo bloquea: un usuario con contraseña temporal falla de entrada
con PasswordTemporalError y nunca ve sus empresas ni recibe un pre-token
(ADR 0030). El CU-04 pedía que el usuario pudiera reemplazar esa contraseña
temporal por una propia, pero no existía ningún endpoint para hacerlo: el
usuario quedaba encerrado, con una contraseña que el sistema le había asignado y
sin forma de cambiarla.
La restricción es el orden mismo del login: como el paso 1 bloquea antes de emitir cualquier token, el usuario con contraseña temporal no tiene un access token con el que autenticarse. La única credencial disponible para identificarlo es, justamente, la contraseña actual que ya conoce.
Además, cambiar la contraseña no debe ser un simple UPDATE: hay que exigir un
mínimo de fortaleza, impedir que se reutilicen contraseñas recientes y dejar
rastro del cambio, sin que un fallo a mitad de camino deje el usuario con una
contraseña actualizada y un historial inconsistente.
Decisión¶
Endpoint público con la contraseña actual¶
Se agrega POST /api/v1/auth/cambiar-password, público, con el contrato
CambiarPasswordRequest: username, password_old, password_new y
password_new_confirm. Responde 204. La identificación es por
username + password_old, no por token: el paso 1 bloquea al usuario con
contraseña temporal, así que no hay access token posible y la contraseña actual
es la única credencial que el usuario tiene.
Validaciones de fortaleza¶
app/core/security.py expone validar_fortaleza_password(password) que devuelve
la lista de criterios incumplidos (vacía si la contraseña es fuerte). Los
criterios son: mínimo 8 caracteres, al menos una mayúscula, al menos un
número y al menos un carácter especial (no alfanumérico). La función es
reutilizable: la usa este endpoint y, a futuro, el alta de usuarios. El service
lanza PasswordDebilError con los criterios incumplidos (400).
Reutilización¶
La contraseña nueva no puede coincidir con la actual ni con las últimas
3 contraseñas dejadas por el usuario. El historial vive en la tabla nueva
trx_password_changes y guarda el hash de la contraseña anterior en cada
cambio; la vigente sigue viviendo en mae_usuarios.password. Se verifica con
verify_password contra la actual y contra los últimos PASSWORD_HISTORIAL = 3
registros, y un reuso lanza PasswordReutilizadaError (409).
Tabla de historial¶
trx_password_changes es insert-only, como log_sesiones (ADR 0021
transversal): no se actualiza ni se borra lógicamente, sólo se inserta. Por eso
no hereda AuditMixin: lleva id UUID (de IdMixin), usuario_id (FK a
mae_usuarios, NOT NULL), password_hash (String(255), NOT NULL) y created_at
con server_default now(). Guardar el hash anterior —no la contraseña en claro
ni la nueva— es lo único que el chequeo de reutilización necesita, y deja el
historial como la bitácora de las contraseñas dejadas.
Atomicidad¶
El cambio es una sola transacción. El orden es: insertar el hash anterior en
el historial, actualizar el usuario (password = hash_password(password_new) y
password_temp = False) y registrar el log de sesión con
accion="cambio_password". El repository abre las dos primeras operaciones con
flush (sin commit) y cierra la transacción el registrar_log_sesion final, que
hace el único commit. Si algo falla antes, nada queda a medias: ni el historial,
ni la contraseña, ni el log. Al cambiar, password_temp pasa a false, así que
el usuario queda habilitado para el login normal.
Alternativas descartadas¶
- Identificar por token (Authorization: Bearer) — imposible para el caso que motiva el cambio: el usuario con contraseña temporal no puede obtener un access token porque el paso 1 lo bloquea. Exigir token dejaría el CU-04 sin resolver justo para quien lo necesita.
- Cambiar la contraseña sin historial — no permite cumplir la regla de no
reutilizar contraseñas recientes; guardar el historial en una columna JSON de
mae_usuariosmezclaría estado y bitácora en la misma fila. - Guardar la contraseña nueva en el historial — el historial debe ser las
contraseñas dejadas; la vigente ya vive en
mae_usuarios.password. Guardar la nueva duplicaría el estado y confundiría qué se está validando. - Exigir solo longitud mínima — insuficiente para una plataforma bancaria; mayúscula, número y carácter especial son el mínimo que ya se venía manejando en el alta.
Consecuencias¶
- El CU-04 queda cerrado: el usuario con contraseña temporal puede cambiarla y habilitarse para operar.
- La fortaleza queda en una función reutilizable, no incrustada en el service; el alta de usuarios puede adoptarla después sin duplicar reglas.
- El commit de la transacción lo hace
registrar_log_sesion, que es la última operación del flujo. Cualquier cambio futuro que inserte algo después del log rompería la atomicidad: el log debe seguir siendo el cierre. PASSWORD_HISTORIALfija la ventana de reutilización en 3. Ampliarla o reducirlas es cambiar la constante, no la tabla: el historial se acumula.- La tabla crece insert-only con cada cambio y no tiene purga todavía; si el volumen lo exige, se resolverá como el resto de las bitácoras.
Qué no cubre¶
- La recuperación de contraseña olvidada (por correo o similar) es otro flujo: acá el usuario debe conocer su contraseña actual.
- La política de expiración (forzar el cambio cada N días) no se implementa; sólo se registra el historial que la habilitaría a futuro.