# Self-serve forgot-password — gap & recommended design

**Assessment date:** 2026-08-08  
**Verdict:** **Out of scope for a minimal safe reuse.** Document only until a dedicated reset feature is approved.  
**Mail infra:** Existing SMTP/`mail.Send` is enough; **do not** build a new mail stack. Confirm product copy/TTL/rate limits before implementing.

Related: [status-and-gaps.md](status-and-gaps.md), [ux-backlog.md](ux-backlog.md) (P0-10 set-password), [live-auth-security.md](live-auth-security.md), [migration-readiness.md](migration-readiness.md).

---

## What exists today (not forgot-password)

| Piece | Role | Why it cannot serve “I forgot my password” |
|-------|------|--------------------------------------------|
| `must_set_password` + `auth.SetPassword` | First password after migration / bootstrap | Update requires `must_set_password = true`; returns `ErrPasswordAlreadySet` otherwise |
| `ReissueSetPasswordInvite` | Admin re-issue durable invite | Requires `must_set_password` + active membership; ineligible for accounts that already set a password |
| `AcceptInvite` | Invite / first-password accept | Existing users with password must **verify** current password — does not reset |
| HMAC `IssueSetPasswordToken` + `handleCompleteSetPassword` | Token complete for first-set | Calls `SetPassword` → same `must_set_password` gate |
| Admin `POST …/admin/…` set-password email | Operator-only bulk/single send | AuthZ + eligibility same as above; login CTA points here (no public resend) — see P0-10 |
| `mail.SetPasswordMessage` / `MigratedSetPasswordMessage` | Email copy + `/accept-invite` links | Templates/links are first-set oriented; reusable **patterns** only |
| Login UI | `password_not_set` CTA → `/accept-invite` + admin Users | No “Forgot password?” link |

**Operator workarounds today:** platform admin re-issues set-password for `must_set_password` users; local/dev `ForceSetPassword` / migrator `-set-password` for bootstrap. Neither is self-serve recovery for users who already know they had a password.

---

## Why a “small patch” is unsafe

Reusing invite/HMAC set-password for established accounts would require relaxing `must_set_password` (or calling `ForceSetPassword` from a public token path). That collapses first-set and reset semantics, weakens single-use guarantees for HMAC tokens (no DB row until success), and risks account takeover if the public request endpoint is naively bolted on.

Intentional product gap (Wave 8): **no public self-serve resend** for set-password (P0-10).

---

## Recommended design (when approved)

Reuse **mail delivery and rate-limit patterns** from admin set-password; add a **separate** reset purpose. Do not overload `must_set_password` / `AcceptInvite`.

### API (sketch)

1. **`POST /api/auth/forgot-password`** `{ "email": "…" }`  
   - Always return the same opaque success (anti-enumeration).  
   - Rate-limit by IP + normalized email (mirror admin set-password limiters).  
   - If active user with deliverable email: issue **reset** token (prefer durable hashed row, invite-style; HMAC-only only if single-use store is added).  
   - Skip synthetic `@legacy.local` silently.  
   - Send `ForgotPasswordMessage` (new; link to `/reset-password?token=…`, not accept-invite first-set mode).

2. **`POST /api/auth/reset-password`** `{ "token", "password" }`  
   - Validate token; set new argon2id hash for that user **regardless of** `must_set_password` (dedicated `ResetPassword`, not `SetPassword` / not public `ForceSetPassword`).  
   - Invalidate token; optionally revoke other sessions.  
   - Clear `must_set_password` if still set.

### Web

- Login: “Forgot password?” → `/forgot-password`.  
- `/forgot-password`: email form + generic confirmation copy.  
- `/reset-password`: password + confirm; strip `?token=` from URL like accept-invite.

### Security checklist

- Constant-time / uniform responses and timing where practical.  
- Token TTL short (e.g. 1h); one-time consume.  
- CSRF on cookie-authenticated POSTs; public forgot/reset still need CSRF if under same cookie middleware.  
- No token in list APIs or HTML; prefer `#token=` / exchange code later ([live-auth-security.md](live-auth-security.md) residual).  
- Tests: happy path, expired/reuse, unknown email response shape, rate limit, inactive user, synthetic email.

### Explicitly out of this design

- New mail provider, queue, or template engine (extend `internal/mail`).  
- Turning admin set-password into a public endpoint.  
- Logged-in “change password” (optional follow-up; separate from forgot).

---

## Implementation status

| Item | Status |
|------|--------|
| Self-serve forgot / reset | **Implemented** (`041_password_reset_tokens`, `POST /api/auth/forgot-password`, `POST /api/auth/reset-password`, `/forgot-password` + `/reset-password`, i18n) |
| Migration first-set + admin re-issue | Implemented (P0-10) |
| Mail SMTP send path | Implemented; forgot-password reuses `mail.Send` + `EMAIL_DRY_RUN` / `ApplyDryRun` |

**ASSUMPTION:** Opaque `{status:"ok"}` responses; TTL **1h**; IP 10/min + email 3/hour limiters; no session revoke on reset (optional follow-up).