IAM - Change password¶

Status: Implemented
Prefix: PWD
Module: iam
Feature: change-password
Related: Sign-in, Register

Purpose¶

A signed-in person replaces their own password. They must know the current password. Success ends every session, including the one on this device, so they sign in again.

Users and permissions¶

Any active signed-in workspace user may change only their own password. A person who is not signed in cannot change a password.

Requirements¶

ID	Priority	Requirement
PWD-01	Must	A signed-in active user who sends the correct current password and a valid new password gets 200, the stored hash is replaced, every session for that user is deleted, and the session cookie is cleared.
PWD-02	Must	A missing or invalid session is rejected with 401 and the password is unchanged.
PWD-03	Must	A wrong current password is rejected and the password and sessions stay as they were.
PWD-04	Must	A new password that fails the registration strength rule is rejected before the hash is replaced.
PWD-05	Must	A new password that matches the current password is rejected.
PWD-06	Must	After sign-in, an admin and a user can open Đổi mật khẩu. Success returns to the sign-in screen with `Đổi mật khẩu thành công. Hãy đăng nhập lại.`
PWD-07	Should	When the two new-password fields differ, the form shows `Mật khẩu mới không khớp.` and does not call the API.
PWD-08	Must	The change-password screen has a Back control that returns to the workspace home without changing the password.

Screens¶

The signed-in workspace, for every role, has a Đổi mật khẩu action beside logout. It opens /change-password.

The form asks for the current password, the new password, and the new password again.
The new password uses the same rule as registration: at least 8 characters, with a letter, a number, and an uppercase letter.
A Back control returns to the workspace home (/) without calling the change-password API.
A 400 or 401 response is shown on the form.
Success leaves the person on the sign-in screen with the confirmation above. They are not still signed in.

Business rules¶

The current password is checked against the stored scrypt hash. Strength is not checked for the current password.
The new password must pass the registration strength rule and must not match the current password.
The API never returns the hash.
Every session for that user is deleted, including sessions on other devices and the current one.
A locked user, or a session that does not resolve to a user, is rejected as not signed in.

Acceptance criteria¶

PWD-01: Given a signed-in active user with more than one session, when they post the correct current password and a different valid new password to /api/auth/change-password, then the response is 200, the new password matches the stored hash, every session for that user is gone, and the session cookie is cleared.
PWD-02: Given no session, when they post a password change, then the response is 401 and the stored password is unchanged.
PWD-03: Given a signed-in user, when the current password is wrong, then the response is 401, the hash is unchanged, and existing sessions remain.
PWD-04: Given a signed-in user, when the new password is shorter than 8 characters or lacks a letter, a number, or an uppercase letter, then the response is 400 and the hash is unchanged.
PWD-05: Given a signed-in user, when the new password is the same as the current password, then the response is 400 and the hash is unchanged.
PWD-06: Given the workspace, when an admin opens Đổi mật khẩu and submits a valid change, then the sign-in screen shows Đổi mật khẩu thành công. Hãy đăng nhập lại. A user can open the same form.
PWD-07: Given the form, when the two new-password fields differ, then the form shows Mật khẩu mới không khớp. and no change-password request is sent.
PWD-08: Given the change-password form, when the person chooses Back, then they return to the workspace home and no change-password request is sent.