t-convex-nextjs-saas/.sisyphus/plans/dashboard-password-reset-flow.md

# Dashboard Password Reset Flow

## TL;DR
> **Summary**: Add an authenticated password-change flow reachable from the dashboard, with the actual form hosted on a protected `/settings` page that follows the repo's existing server-page plus client-component auth pattern.
> **Deliverables**:
> - Dashboard entry affordance to account security settings
> - Protected `/settings` page with localized password-change UI
> - Better Auth `changePassword` integration with explicit success/error handling
> - Agent-executable manual QA evidence for auth protection, validation, and credential rotation
> **Effort**: Medium
> **Parallel**: YES - 2 waves
> **Critical Path**: 1 -> 3 -> 4 -> 5 -> 6

## Context
### Original Request
Implement a user-facing password reset flow from `src/app/dashboard/page.tsx`.

### Interview Summary
- User selected the authenticated in-session flow, not forgot-password by email.
- Dashboard is the entry point, but the actual form should live on `/settings`.
- Manual QA only for now; no test infrastructure setup in this slice.

### Metis Review (gaps addressed)
- Protect `/settings` explicitly instead of assuming auth.
- Keep scope to password/security only; do not expand into general settings architecture.
- Use Better Auth's existing `changePassword` flow instead of inventing custom backend plumbing.
- Define concrete browser QA with fixed credentials and explicit redirect/session assertions.

## Work Objectives
### Core Objective
Provide a secure, authenticated password-change experience that users can reach from the dashboard and complete on a dedicated settings page.

### Deliverables
- Auth-protected `src/app/settings/page.tsx`
- Dashboard entry UI from `src/app/dashboard/page.tsx` to `/settings`
- Localized client password-change component under `src/components/`
- Better Auth client submission flow with `revokeOtherSessions: true`
- Updated translation files for all new strings
- QA evidence captured for happy path and failure cases

### Definition of Done (verifiable conditions with commands)
- `pnpm lint` completes successfully
- `pnpm build` completes successfully
- Visiting `/settings` while unauthenticated redirects to sign-in with a callback back to `/settings`
- A signed-in user can open `/settings`, submit a valid current/new password pair, and subsequently sign in with only the new password
- Wrong current password and mismatched confirmation both fail with clear user feedback

### Must Have
- Protected `/settings` route with explicit redirect behavior
- Dashboard affordance linking to `/settings`
- Fields for `currentPassword`, `newPassword`, and `confirmPassword`
- Client validation for required fields, confirmation match, and rejecting `newPassword === currentPassword`
- Backend-driven password validation through Better Auth's configured policies, including HIBP plugin
- Success/error feedback and loading state consistent with existing auth UI
- New strings added to both `messages/en.json` and `messages/pl.json`

### Must NOT Have (guardrails, AI slop patterns, scope boundaries)
- No forgot-password email flow, token flow, reset page, or mail templates
- No full settings IA, profile editor, preferences, or navigation redesign
- No new test framework, Playwright project, or CI setup in this slice
- No custom Convex mutation/server action for password change unless Better Auth client API proves unusable during execution
- No route-protection behavior left implicit or undocumented

## Verification Strategy
> ZERO HUMAN INTERVENTION - all verification is agent-executed.
- Test decision: none + existing repo has no test framework; use browser-driven QA and build/lint verification
- QA policy: Every task includes agent-executed scenarios with exact credentials, selectors, and expected outcomes
- Evidence: `.sisyphus/evidence/task-{N}-{slug}.{ext}`

## Execution Strategy
### Parallel Execution Waves
> Target: 5-8 tasks per wave. <3 per wave (except final) = under-splitting.
> Extract shared dependencies as Wave-1 tasks for max parallelism.

Wave 1: 1) route protection and settings page scaffold, 2) dashboard entry affordance, 3) settings UI shell + translations
Wave 2: 4) client validation and field UX, 5) Better Auth submission + session behavior, 6) polish and end-to-end manual QA capture

### Dependency Matrix (full, all tasks)
- 1 blocks 4, 5, 6
- 2 is independent after route constants are confirmed; feeds 6 QA coverage
- 3 blocks 4 and 5
- 4 blocks 5 and 6
- 5 blocks 6
- 6 blocks final verification wave

### Agent Dispatch Summary (wave -> task count -> categories)
- Wave 1 -> 3 tasks -> unspecified-high, visual-engineering, visual-engineering
- Wave 2 -> 3 tasks -> quick, unspecified-high, unspecified-high

## TODOs
> Implementation + Test = ONE task. Never separate.
> EVERY task MUST have: Agent Profile + Parallelization + QA Scenarios.

- [ ] 1. Add protected `/settings` page scaffold

  **What to do**: Read the relevant Next.js App Router docs under `node_modules/next/dist/docs/` before coding, then create `src/app/settings/page.tsx` as a server page that checks authentication with the existing server auth helpers from `src/lib/auth-server.ts`. If unauthenticated, redirect to `/sign-in?callbackURL=/settings`. If authenticated, render a dedicated client settings/password component and keep the page focused on security only.
  **Must NOT do**: Do not implement forgot-password here. Do not place the full form directly in `src/app/settings/page.tsx`. Do not create middleware or a broader settings layout in this slice.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` - Reason: auth-aware App Router work with redirect behavior and server/client boundary decisions
  - Skills: `[]` - No special skill required beyond repo pattern matching
  - Omitted: `playwright` - UI automation belongs in QA, not scaffolding

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: 4, 5, 6 | Blocked By: none

  **References** (executor has NO interview context - be exhaustive):
  - Pattern: `src/app/sign-in/page.tsx` - thin server page wrapper pattern already used for auth routes
  - Pattern: `src/app/sign-up/page.tsx` - same page composition pattern for route-level wrappers
  - Auth helper: `src/lib/auth-server.ts` - server-side auth utilities available for checking session/auth state
  - Route contract: `src/lib/routes.ts` - `/settings` already exists as a private route constant
  - Existing target: `src/app/dashboard/page.tsx` - current dashboard stub that will link into this route
  - External: `node_modules/next/dist/docs/` - project instruction requires reading relevant Next.js docs before implementation

  **Acceptance Criteria** (agent-executable only):
  - [ ] `src/app/settings/page.tsx` exists and remains a server page wrapper rather than a client-heavy file
  - [ ] Unauthenticated access to `/settings` redirects to `/sign-in?callbackURL=/settings`
  - [ ] Authenticated access to `/settings` renders the dedicated password settings component
  - [ ] `pnpm lint` passes after the page scaffold is added

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Unauthenticated redirect from settings
    Tool: Playwright
    Steps: Open a fresh browser context; visit http://localhost:3000/settings directly.
    Expected: Browser lands on `/sign-in` and preserves a callback URL containing `/settings`.
    Evidence: .sisyphus/evidence/task-1-settings-redirect.png

  Scenario: Authenticated settings page render
    Tool: Playwright
    Steps: Sign up `changeflow@example.com` with password `OldPass123!`; sign in; visit http://localhost:3000/settings.
    Expected: The page renders a password/security card instead of redirecting away.
    Evidence: .sisyphus/evidence/task-1-settings-render.png
  ```

  **Commit**: YES | Message: `add protected settings page scaffold and dashboard entry` | Files: `src/app/settings/page.tsx`, `src/lib/routes.ts` (only if needed), related imports

- [ ] 2. Add dashboard entry to account security

  **What to do**: Replace the dashboard stub with a minimal, intentional dashboard card or section that exposes a single clear affordance to account security settings. Link to `/settings` via existing route constants. Keep the page intentionally narrow: one CTA, one short description, no full settings UI embedded here.
  **Must NOT do**: Do not turn dashboard into a general settings page. Do not add unrelated profile, billing, or preferences UI.

  **Recommended Agent Profile**:
  - Category: `visual-engineering` - Reason: small UI composition task that must feel deliberate, not boilerplate
  - Skills: `[]` - Existing component library provides all primitives needed
  - Omitted: `playwright` - verification happens via QA scenario, not implementation

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: 6 QA coverage only | Blocked By: none

  **References** (executor has NO interview context - be exhaustive):
  - Target page: `src/app/dashboard/page.tsx` - currently only a stub and should become the entry point
  - Route contract: `src/lib/routes.ts` - use the existing private route constant for settings
  - UI pattern: `src/components/ui/card.tsx` - use existing card primitives for a compact dashboard section
  - UI pattern: `src/components/ui/button.tsx` - use existing button variants for the CTA

  **Acceptance Criteria** (agent-executable only):
  - [ ] `/dashboard` contains a visible CTA linking to `/settings`
  - [ ] The CTA uses route constants rather than a duplicated hard-coded path
  - [ ] The dashboard change stays focused on password/security entry only
  - [ ] `pnpm lint` passes after the dashboard update

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Dashboard exposes security entry
    Tool: Playwright
    Steps: Sign in as `changeflow@example.com` with `OldPass123!`; open http://localhost:3000/dashboard; inspect the visible security/settings CTA.
    Expected: Clicking the CTA navigates to `/settings`.
    Evidence: .sisyphus/evidence/task-2-dashboard-entry.png

  Scenario: Dashboard does not embed the password form
    Tool: Playwright
    Steps: Load http://localhost:3000/dashboard while signed in.
    Expected: No `currentPassword`, `newPassword`, or `confirmPassword` input fields are present on the dashboard page itself.
    Evidence: .sisyphus/evidence/task-2-dashboard-no-form.png
  ```

  **Commit**: YES | Message: `add protected settings page scaffold and dashboard entry` | Files: `src/app/dashboard/page.tsx`

- [ ] 3. Create the localized password settings component shell

  **What to do**: Create a dedicated client component for password change under `src/components/settings/` and wire it into `src/app/settings/page.tsx`. Use the same card, field, button, spinner, and password input-group patterns already used in `src/components/auth/AuthForm.tsx`. Add all new translation keys to both locale files up front so no hard-coded strings remain.
  **Must NOT do**: Do not reuse `AuthForm` directly for password change. Do not leave untranslated labels, helper text, button copy, or toast messages.

  **Recommended Agent Profile**:
  - Category: `visual-engineering` - Reason: new client UI should blend with existing auth UI while staying scoped
  - Skills: `[]` - Existing component system is sufficient
  - Omitted: `writing` - copy additions are straightforward translation entries, not long-form docs

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: 4, 5, 6 | Blocked By: 1

  **References** (executor has NO interview context - be exhaustive):
  - Pattern: `src/components/auth/AuthForm.tsx` - existing client auth form conventions for card layout, field composition, spinner, toast, and password visibility controls
  - UI primitives: `src/components/ui/field.tsx`, `src/components/ui/input-group.tsx`, `src/components/ui/button.tsx`, `src/components/ui/spinner.tsx`
  - Translation files: `messages/en.json`, `messages/pl.json` - extend with a dedicated settings/security namespace or equivalent flat keys
  - Existing i18n usage: `src/components/auth/AuthForm.tsx` - `useTranslations(...)` pattern

  **Acceptance Criteria** (agent-executable only):
  - [ ] A dedicated client component exists under `src/components/settings/`
  - [ ] `/settings` renders a single password/security card with localized heading, description, and button text
  - [ ] Both `messages/en.json` and `messages/pl.json` contain all strings needed for the new UI
  - [ ] No new hard-coded user-facing strings remain in the component

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Password settings shell renders expected fields
    Tool: Playwright
    Steps: Sign in; visit http://localhost:3000/settings; inspect the form.
    Expected: Inputs named `currentPassword`, `newPassword`, and `confirmPassword` are visible, plus a submit button.
    Evidence: .sisyphus/evidence/task-3-settings-shell.png

  Scenario: Localized shell does not regress rendering
    Tool: Playwright
    Steps: Load the page in the default locale; inspect heading, field labels, and submit button.
    Expected: All visible strings are rendered from translation data with no raw key names or empty labels.
    Evidence: .sisyphus/evidence/task-3-settings-i18n.png
  ```

  **Commit**: YES | Message: `add password change form UI and localization` | Files: `src/components/settings/PasswordChangeCard.tsx`, `src/app/settings/page.tsx`, `messages/en.json`, `messages/pl.json`

- [ ] 4. Implement client-side validation and field UX

  **What to do**: Define a dedicated Zod schema for the password-change form that requires `currentPassword`, reuses `defaultPasswordValidator()` for `newPassword`, enforces `confirmPassword === newPassword`, and rejects `newPassword === currentPassword`. Provide inline field errors and disable duplicate submissions with a loading state. Keep password visibility UX consistent with the existing auth form pattern.
  **Must NOT do**: Do not add uppercase/number/special-character composition rules back into the client. Do not rely only on toasts for validation errors that belong inline.

  **Recommended Agent Profile**:
  - Category: `quick` - Reason: bounded form-schema and field-state work inside one component
  - Skills: `[]` - Existing validation patterns are enough
  - Omitted: `ultrabrain` - no deep algorithmic work needed

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: 5, 6 | Blocked By: 1, 3

  **References** (executor has NO interview context - be exhaustive):
  - Validation helper: `src/constants.ts` - current shared minimum-length validator to reuse for `newPassword`
  - Pattern: `src/components/auth/AuthForm.tsx` - React Hook Form + Zod resolver usage and inline `FieldError` handling
  - UI primitives: `src/components/ui/field.tsx`, `src/components/ui/input-group.tsx`, `src/components/ui/spinner.tsx`

  **Acceptance Criteria** (agent-executable only):
  - [ ] Submitting mismatched `newPassword` and `confirmPassword` surfaces an inline error on the confirmation field
  - [ ] Submitting the same value for current and new password surfaces an inline error before any network request
  - [ ] Submitting an empty required field surfaces inline validation without a success toast
  - [ ] Submit button disables while the request is pending

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Mismatched confirmation is blocked locally
    Tool: Playwright
    Steps: Sign in; open `/settings`; fill `currentPassword=OldPass123!`, `newPassword=NewPass123!`, `confirmPassword=Mismatch123!`; submit.
    Expected: Inline error appears for `confirmPassword`; no network-driven success state is shown.
    Evidence: .sisyphus/evidence/task-4-confirm-mismatch.png

  Scenario: Reusing the same password is blocked locally
    Tool: Playwright
    Steps: Fill `currentPassword=OldPass123!`, `newPassword=OldPass123!`, `confirmPassword=OldPass123!`; submit.
    Expected: Inline error indicates the new password must differ from the current password.
    Evidence: .sisyphus/evidence/task-4-same-password.png
  ```

  **Commit**: YES | Message: `add password change form UI and localization` | Files: `src/components/settings/PasswordChangeCard.tsx`, related validation helpers only if needed

- [ ] 5. Wire Better Auth password change submission

  **What to do**: Connect the settings form to Better Auth's client password-change API using the authenticated session. Submit `currentPassword`, `newPassword`, and `revokeOtherSessions: true`. On success, stay on `/settings`, clear sensitive fields, and show a localized success toast. On failure, surface the returned error cleanly without clearing the current user session.
  **Must NOT do**: Do not create a custom Convex mutation for password change unless the Better Auth client call is proven unusable. Do not redirect away from settings after success. Do not silently swallow backend errors.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` - Reason: auth-sensitive submission flow with session behavior and backend error handling
  - Skills: `[]` - Existing Better Auth client is already configured in repo
  - Omitted: `writing` - this is behavior wiring, not docs work

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: 6 | Blocked By: 1, 3, 4

  **References** (executor has NO interview context - be exhaustive):
  - Client auth entry: `src/lib/auth-client.ts` - Better Auth client already configured with Convex plugin
  - Existing auth pattern: `src/components/auth/AuthForm.tsx` - request pending state, toast handling, Better Auth client invocation patterns
  - Backend policy: `convex/auth.ts` - Better Auth email/password configuration with HIBP plugin and min/max length
  - Settings component: `src/components/settings/PasswordChangeCard.tsx` - task 3/4 output

  **Acceptance Criteria** (agent-executable only):
  - [ ] Valid submission calls Better Auth password-change API and succeeds for the signed-in user
  - [ ] Wrong current password yields a visible error state without logging the user out of the current session
  - [ ] Successful submission clears all password inputs and leaves the user on `/settings`
  - [ ] `pnpm build` passes after the integration is complete

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Wrong current password is rejected
    Tool: Playwright
    Steps: Sign in; open `/settings`; fill `currentPassword=WrongPass123!`, `newPassword=NewPass123!`, `confirmPassword=NewPass123!`; submit.
    Expected: Error feedback appears; the current session remains usable; revisiting `/dashboard` still works in the same tab.
    Evidence: .sisyphus/evidence/task-5-wrong-current-password.png

  Scenario: Valid password change succeeds
    Tool: Playwright
    Steps: Fill `currentPassword=OldPass123!`, `newPassword=NewPass123!`, `confirmPassword=NewPass123!`; submit.
    Expected: Success toast/message appears; fields clear; page remains on `/settings`.
    Evidence: .sisyphus/evidence/task-5-successful-change.png
  ```

  **Commit**: YES | Message: `wire password change flow and verify session behavior` | Files: `src/components/settings/PasswordChangeCard.tsx`, any minimal auth client touch-ups only if required

- [ ] 6. Finalize credential-rotation behavior and capture manual QA evidence

  **What to do**: Validate the full user journey end to end: dashboard -> settings -> change password -> sign out -> sign back in with the new credential. Because `revokeOtherSessions: true` is the default for this slice, also verify in a second browser context that another active session becomes unauthorized after the password change. Capture screenshots/logs into the evidence paths referenced below.
  **Must NOT do**: Do not add automated test infrastructure or CI in order to satisfy this task. Do not leave QA as a vague manual checklist.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` - Reason: auth/stateful browser verification across two sessions
  - Skills: [`playwright`] - Use browser automation to validate auth and session transitions precisely
  - Omitted: `frontend-ui-ux` - this task is verification-focused, not design-focused

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: Final verification wave | Blocked By: 1, 2, 3, 4, 5

  **References** (executor has NO interview context - be exhaustive):
  - Entry page: `src/app/dashboard/page.tsx`
  - Protected page: `src/app/settings/page.tsx`
  - Form component: `src/components/settings/PasswordChangeCard.tsx`
  - Auth UI precedent: `src/components/auth/AuthForm.tsx`
  - Command surface: `package.json` - use existing `pnpm dev`, `pnpm lint`, and `pnpm build`

  **Acceptance Criteria** (agent-executable only):
  - [ ] After password change, signing in with `OldPass123!` fails and signing in with `NewPass123!` succeeds
  - [ ] A second active browser context is no longer authorized after the password change
  - [ ] Evidence files exist for redirect, validation failure, success state, old-password rejection, and second-session invalidation
  - [ ] `pnpm lint` and `pnpm build` both pass on the final implementation

  **QA Scenarios** (MANDATORY - task incomplete without these):
  ```
  Scenario: Old password fails and new password succeeds
    Tool: Playwright
    Steps: Complete the password change; sign out; attempt sign-in with `OldPass123!`; then attempt sign-in with `NewPass123!`.
    Expected: Old password sign-in fails; new password sign-in succeeds and returns to an authenticated page.
    Evidence: .sisyphus/evidence/task-6-old-vs-new-credential.png

  Scenario: Other sessions are revoked
    Tool: Playwright
    Steps: Open session A and session B signed in as the same user; change the password in session A; in session B navigate to `/dashboard` or refresh.
    Expected: Session B is redirected to sign-in or otherwise loses authenticated access.
    Evidence: .sisyphus/evidence/task-6-revoke-other-sessions.png
  ```

  **Commit**: YES | Message: `wire password change flow and verify session behavior` | Files: no net-new feature files expected beyond minimal polish; evidence output only

## Final Verification Wave (MANDATORY - after ALL implementation tasks)
> 4 review agents run in PARALLEL. ALL must APPROVE. Present consolidated results to user and get explicit "okay" before completing.
> **Do NOT auto-proceed after verification. Wait for user's explicit approval before marking work complete.**
> **Never mark F1-F4 as checked before getting user's okay.** Rejection or user feedback -> fix -> re-run -> present again -> wait for okay.
- [ ] F1. Plan Compliance Audit - oracle
- [ ] F2. Code Quality Review - unspecified-high
- [ ] F3. Real Manual QA - unspecified-high (+ playwright if UI)
- [ ] F4. Scope Fidelity Check - deep

## Commit Strategy
- Commit 1: `add protected settings page scaffold and dashboard entry`
- Commit 2: `add password change form UI and localization`
- Commit 3: `wire password change flow and verify session behavior`

## Success Criteria
- The feature remains scoped to authenticated password change only
- `/dashboard` clearly leads users into account security settings
- `/settings` is inaccessible without authentication
- Password change succeeds only with the correct current password and valid new password
- QA evidence proves redirect, validation failure, success path, and new-credential sign-in behavior