# 3. Password Management

User Type: **Student**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 3. Password Management

### 3.1 Password Reset
**What it does:** Lets a Student who has forgotten their password recover access to their account. The Student requests a reset from the login screen, receives a single-use, time-limited reset link (or code) at their registered email, and sets a new password. The reset invalidates all existing sessions for the account.

**Sub-features:**
- "Forgot password?" entry point on the login screen
- Reset request: enter registered email, receive a single-use, time-limited reset link
- Reset link validation (single-use, time-limited) with expiry handling
- New password entry with strength validation and confirm field
- All existing sessions invalidated on successful reset
- Rate limiting on reset requests per account and per IP
- Generic response for unknown emails (no account enumeration)
- Reset event logging (requested, link sent, link used, expired, failed)
- Audit logging of the password reset

**Student User Journey:**
1. Student is on the login screen and clicks "Forgot password?".
2. Student enters their registered email and clicks "Send reset link". The screen shows "If an account exists for this email, a reset link has been sent" (generic, to prevent enumeration).
3. Student receives the email and clicks the reset link. The link opens a "Set a new password" screen.
4. Student enters a new password (strength meter shows "Strong") and confirms it, then clicks "Save".
5. The system validates the new password, updates it, invalidates all existing sessions, and shows "Your password has been changed. Log in with your new password."
6. Student returns to the login screen and signs in with the new password successfully.
7. If the reset link had expired, clicking it would show "This link has expired" with a "Request a new link" button.
8. Student opens the profile menu → "Security activity" and confirms the reset event is recorded with timestamp and IP.

**Rules & Edge Cases:**
- The reset link is single-use and time-limited; reusing or expiring it produces a reissue path.
- The response to a reset request is identical whether or not the email is registered (prevents account enumeration).
- Reset requests are rate-limited per account and per IP to prevent abuse.
- A successful reset invalidates all existing sessions for the account.
- The new password must meet the strength policy and cannot be the same as the previous password.
- Reset events (requested, link sent, link used, expired, failed) are logged with timestamp and IP.
- The password reset is audit-logged with the account, the outcome, and the timestamp.

### 3.2 Password Change
**What it does:** Lets a Student who is already logged in change their password. The Student verifies their current password, enters a new password meeting the strength policy, and confirms it. The change is applied immediately and (optionally) other sessions are invalidated.

**Sub-features:**
- "Change password" entry point in Profile → Security
- Current password verification before accepting a new password
- New password entry with strength validation and confirm field
- "Cannot reuse previous password" check
- Immediate application on success
- Optional invalidation of other sessions on change
- Change event logging (success, wrong current password, weak new password)
- Audit logging of the password change

**Student User Journey:**
1. Student opens Profile → "Security" → "Change password".
2. Student enters their current password; the system verifies it.
3. Student enters a new password (strength meter shows "Strong") and confirms it, then clicks "Save".
4. The system validates the new password (meets policy, not a reuse), updates it, and shows "Your password has been changed."
5. Student is asked whether to sign out of other devices; Student chooses "Sign out everywhere" and all other sessions are invalidated.
6. Student opens the profile menu → "Security activity" and confirms the change event is recorded with timestamp.

**Rules & Edge Cases:**
- The current password must be verified before a new password is accepted.
- The new password must meet the strength policy and cannot be the same as the current or recent previous passwords.
- Changing the password does not sign out the current session by default, but can invalidate all other sessions.
- A wrong current password produces a specific "current password incorrect" message (the Student is already authenticated, so enumeration is not a concern).
- Change events (success, wrong current password, weak new password) are logged with timestamp.
- The password change is audit-logged with the account, the outcome, and the timestamp.

### 3.3 Password Policy Enforcement
**What it does:** Enforces the platform's password strength and hygiene rules for Student accounts at creation, reset, and change. The policy defines minimum length, required character classes, blocked patterns (common passwords, personal information), and reuse history. Violations are rejected with specific, actionable feedback.

**Sub-features:**
- Minimum length requirement (e.g., 8 characters)
- Character class requirements (uppercase, lowercase, number, symbol)
- Blocked common passwords list
- Personal information check (password must not contain the Student's name or email)
- Reuse history: the new password cannot match any of the last N passwords
- Real-time strength meter with specific, actionable hints
- Policy applied consistently at registration, reset, and change
- Policy violation logging
- Audit logging of the password policy enforcement

**Student User Journey:**
1. Student is setting a new password (at registration or change) and types "password123"; the strength meter shows "Weak" with the hint "Avoid common passwords".
2. Student types "Thabo1990!"; the meter shows "Strong" and the hint clears.
3. Student tries to reuse a password from 3 months ago; the system rejects it with "You cannot reuse a recent password".
4. Student types a password containing their own name; the system rejects it with "Password must not contain your name".
5. Student enters a compliant password and the field is accepted.
6. Student opens the profile menu → "Security activity" and confirms the policy checks are part of the recorded password event.

**Rules & Edge Cases:**
- The policy is applied consistently at registration, reset, and change; there is no weaker path.
- The strength meter gives specific, actionable hints (length, character class, common password, personal info, reuse).
- The reuse history covers the last N passwords (e.g., 5); a match is rejected.
- A password containing the Student's name or email is rejected.
- Policy violations are logged (which rule failed) without storing the password itself.
- The password policy enforcement is audit-logged with the account, the rule(s) triggered, and the timestamp.