left4me/docs/superpowers/specs/2026-05-11-profile-password-change-design.md

Profile page with self-service password change — design

Context

The web app has login/logout (l4d2web/auth.py, l4d2web/routes/auth_routes.py) and admin user management (activate/deactivate/delete), but no way for a logged-in user to change their own password. The header (l4d2web/templates/base.html:27) renders the username as a non-clickable <span class="muted">.

This design adds a /profile page reachable by clicking the username, with "Change password" as its first (and only) section. Future profile fields can slot into the same page as new sections without rework.

Goals

• Logged-in users can change their own password from a self-service page.
• Following an industry-standard session model: a successful password change invalidates every other active session for the user and keeps the current session signed in. No re-login on the current browser.
• Single password policy enforced everywhere a password is set (web flow today, CLI create-user for consistency).

Non-goals (out of scope for v1)

• Admin password reset for other users. A separate feature; no rework needed to add later.
• Password recovery / email reset flow.
• Other profile fields (display name, email, etc.). The page is structured to grow but ships with one section.

Decisions

• URLs. GET /profile for the page, POST /profile/password for the form submission.
• Form fields. current_password, new_password, confirm_new_password. All three required.
• Password policy. Not empty, minimum 8 characters. Same rule applies to the CLI create-user so policy lives in one place.
• Session policy. Invalidate other sessions on success; keep the current session signed in.
• Rate limit. Per-IP, sliding window. Re-uses the same primitive as /login.
• CSRF. Standard hidden-token pattern shared with the rest of the app.

Session-invalidation mechanism

A new password_changed_at: DateTime NOT NULL column on users. Two checkpoints:

1. On login. login_user stashes session["pw_changed_at"] = user.password_changed_at.isoformat().
2. On every request. load_current_user rejects the session — same shape as the existing user.active check — when the marker is missing, malformed, or strictly older than user.password_changed_at.

On successful password change:

• Rotate user.password_digest and bump user.password_changed_at to "now".
• Re-stamp session["pw_changed_at"] to the new value so this browser keeps working.
• Other browsers carry the old marker and get logged out the next time they hit a @require_login route.

This mirrors the established g.user = None if not user.active else user pattern, so the surface area added to the auth path is small and the behavior is easy to reason about.

Validation branches (POST /profile/password)

In order:

1. All three fields present → otherwise error=fields_required.
2. new_password == confirm_new_password → otherwise error=mismatch.
3. validate_new_password(new_password) passes → otherwise error=empty or error=too_short.
4. verify_password(current_password, user.password_digest) succeeds → otherwise error=wrong_current.
5. Rotate, re-stamp, redirect to /profile?success=1.

Errors are surfaced inline on the next render of /profile via a small ?error=<key> → human-readable message map in the route. No flash storage required.

Migration story

Adding password_changed_at to users requires a migration:

• Add the column nullable.
• Backfill existing rows with their created_at so historical data has a sane marker.
• Alter to NOT NULL.

Effect on existing live sessions: any cookie that predates the migration lacks pw_changed_at and is rejected on first request after deploy. Users log in once more. Acceptable for v1 deployment.

Surface area

New files

• l4d2web/alembic/versions/0009_user_password_changed_at.py
• l4d2web/services/rate_limit.py
• l4d2web/routes/profile_routes.py
• l4d2web/templates/profile.html
• l4d2web/tests/test_profile.py

Modified files

• l4d2web/models.py — column.
• l4d2web/auth.py — MIN_PASSWORD_LENGTH, validate_new_password, login_user signature, freshness check in load_current_user.
• l4d2web/routes/auth_routes.py — pass marker to login_user; use the generic rate-limit helper.
• l4d2web/templates/base.html — username <span> → <a href="/profile">.
• l4d2web/app.py — register the new blueprint, reset its rate-limit bucket in TESTING.
• l4d2web/cli.py — apply validate_new_password for parity with the web flow.

Reused utilities

• hash_password, verify_password — l4d2web/auth.py
• require_login — l4d2web/auth.py
• session_scope — l4d2web/db.py
• now_utc — l4d2web/models.py
• CSRF hidden-token pattern — see templates/admin_users.html, routes/auth_routes.py

Open questions resolved during brainstorming

• Should the current session also be invalidated? No — industry consensus (Django update_session_auth_hash, Rails Devise, GitHub/Google behaviour, OWASP / NIST SP 800-63B implications) is to keep the current session and rotate other sessions. Forcing re-login on a session that just proved knowledge of the current password adds friction without security gain.
• Should we add password_changed_at or use a session_version counter? Timestamp is enough; the comparison is unambiguous and avoids an extra integer field with arbitrary meaning.
• Admin reset? Deferred. The current model has no rework debt for adding it later.