Saltar a contenido

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_usuarios mezclarí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_HISTORIAL fija 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.