docs: add forgot password implementation plan

2026-07-21 22:27:02 +08:00
parent a4b7761f92
commit 3a5daaa987
1 changed files with 412 additions and 0 deletions
@@ -0,0 +1,412 @@
 # Forgot Password Flow Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Add self-service password reset so users can recover access via email link without admin help.
 **Architecture:** Three UI changes — a link on the login form, a forgot-password page (sends reset email via Supabase), and a reset-password page (sets new password using the recovery session). The existing `/api/auth/callback` route handles the email link's code exchange without modification.
 **Tech Stack:** Next.js 15 App Router, Supabase Auth (`@supabase/ssr`), Tailwind CSS
 ## Global Constraints
 - `basePath: '/ims'` — all internal links use paths without `/ims` prefix; Next.js prepends it automatically
 - `NEXT_PUBLIC_APP_URL` = `http://64.176.82.100/ims` in production (`.env.production`) — no trailing slash
 - Supabase client in client components: `createClient` from `@/lib/supabase/client`
 - Styling must match existing login form: `border border-gray-300 rounded-lg px-3 py-2 text-sm focus:ring-2 focus:ring-blue-500`, error in `bg-red-50 border border-red-200 text-red-700 text-sm rounded px-3 py-2`
 - Password minimum: 8 characters (matches `change-password-form.tsx`)
 - No new API routes — all Supabase calls are client-side
 ---
 ### Task 1: Add "Forgot password?" link to login form
 **Files:**
 - Modify: `components/auth/login-form.tsx`
 **Interfaces:**
 - Produces: link to `/forgot-password` visible below the Sign in button
 - [ ] **Step 1: Add the link**
 In `components/auth/login-form.tsx`, add after the `<button type="submit" ...>` closing tag:
 ```tsx
 <p className="text-center text-sm text-gray-500">
  <a href="/forgot-password" className="text-blue-600 hover:underline">
    Forgot password?
  </a>
 </p>
 ```
 The full return block bottom should look like:
 ```tsx
      <button
        type="submit"
        disabled={loading}
        className="bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 rounded-md disabled:opacity-50 transition-colors"
      >
        {loading ? 'Signing in…' : 'Sign in'}
      </button>
      <p className="text-center text-sm text-gray-500">
        <a href="/forgot-password" className="text-blue-600 hover:underline">
          Forgot password?
        </a>
      </p>
    </form>
 ```
 - [ ] **Step 2: Verify visually**
 Run `npm run dev` and open `http://localhost:3000/ims/login`. Confirm "Forgot password?" link appears below the Sign in button and clicking it navigates to `/forgot-password` (404 is expected — page doesn't exist yet).
 - [ ] **Step 3: Commit**
 ```bash
 git add components/auth/login-form.tsx
 git commit -m "feat(auth): add forgot password link to login form"
 ```
 ---
 ### Task 2: Create forgot-password page
 **Files:**
 - Create: `app/(auth)/forgot-password/page.tsx`
 **Interfaces:**
 - Consumes: `createClient` from `@/lib/supabase/client`, `NEXT_PUBLIC_APP_URL` env var
 - Produces: page at `/forgot-password` that sends a reset email and shows success state
 - [ ] **Step 1: Create the page file**
 Create `app/(auth)/forgot-password/page.tsx`:
 ```tsx
 'use client'
 import { useState } from 'react'
 import Link from 'next/link'
 import { createClient } from '@/lib/supabase/client'
 export default function ForgotPasswordPage() {
  const [email, setEmail] = useState('')
  const [loading, setLoading] = useState(false)
  const [submitted, setSubmitted] = useState(false)
  const [error, setError] = useState<string | null>(null)
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    if (!email) return
    setLoading(true)
    setError(null)
    const supabase = createClient()
    const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? ''
    const redirectTo = `${appUrl}/api/auth/callback?next=/auth/reset-password`
    const { error: resetError } = await supabase.auth.resetPasswordForEmail(email, {
      redirectTo,
    })
    setLoading(false)
    if (resetError) {
      setError('Something went wrong. Please try again.')
      return
    }
    // Always show success — never reveal whether email exists
    setSubmitted(true)
  }
  if (submitted) {
    return (
      <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
        <div className="w-full max-w-sm space-y-4 text-center">
          <h1 className="text-2xl font-bold text-gray-900">Check your email</h1>
          <p className="text-sm text-gray-500">
            If an account exists for <strong>{email}</strong>, a password reset link has been sent.
          </p>
          <Link href="/login" className="text-sm text-blue-600 hover:underline">
            Back to sign in
          </Link>
        </div>
      </div>
    )
  }
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
      <form onSubmit={handleSubmit} className="flex flex-col gap-4 w-full max-w-sm">
        <div className="text-center">
          <h1 className="text-2xl font-bold">Reset password</h1>
          <p className="text-sm text-gray-500 mt-1">
            Enter your email and we'll send a reset link.
          </p>
        </div>
        {error && (
          <p className="bg-red-50 border border-red-200 text-red-700 text-sm rounded px-3 py-2">
            {error}
          </p>
        )}
        <input
          type="email"
          placeholder="Email"
          value={email}
          onChange={e => setEmail(e.target.value)}
          required
          autoComplete="email"
          className="border border-gray-300 rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <button
          type="submit"
          disabled={loading}
          className="bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 rounded-md disabled:opacity-50 transition-colors"
        >
          {loading ? 'Sending…' : 'Send reset link'}
        </button>
        <p className="text-center text-sm text-gray-500">
          <Link href="/login" className="text-blue-600 hover:underline">
            Back to sign in
          </Link>
        </p>
      </form>
    </div>
  )
 }
 ```
 - [ ] **Step 2: Verify page loads**
 With dev server running, open `http://localhost:3000/ims/forgot-password`. Confirm the form renders with email input and "Send reset link" button. Confirm "Back to sign in" navigates to `/ims/login`.
 - [ ] **Step 3: Commit**
 ```bash
 git add app/\(auth\)/forgot-password/page.tsx
 git commit -m "feat(auth): add forgot password page"
 ```
 ---
 ### Task 3: Create reset-password page
 **Files:**
 - Create: `app/(auth)/reset-password/page.tsx`
 **Interfaces:**
 - Consumes: `createClient` from `@/lib/supabase/client`, valid Supabase recovery session in browser cookie
 - Produces: page at `/auth/reset-password` that sets a new password and redirects to `/login`
 Note: The path is `/auth/reset-password` (not `/reset-password`) because the auth callback `next` param is `/auth/reset-password` which resolves to `app/(auth)/reset-password/page.tsx` — the `(auth)` group folder matches the `/auth/` URL segment? No — route groups like `(auth)` do NOT add a URL segment. So `app/(auth)/reset-password/page.tsx` maps to `/reset-password`.
 **Correction:** The callback redirects to `/auth/reset-password` but the page lives at `app/(auth)/reset-password/page.tsx` which maps to `/reset-password`. These must match. Use `/reset-password` as the `next` param in the callback URL (update Task 2's `redirectTo`).
 Update `app/(auth)/forgot-password/page.tsx` line:
 ```tsx
 const redirectTo = `${appUrl}/api/auth/callback?next=/reset-password`
 ```
 - [ ] **Step 1: Fix redirectTo in forgot-password page**
 In `app/(auth)/forgot-password/page.tsx`, change:
 ```tsx
 const redirectTo = `${appUrl}/api/auth/callback?next=/auth/reset-password`
 ```
 to:
 ```tsx
 const redirectTo = `${appUrl}/api/auth/callback?next=/reset-password`
 ```
 - [ ] **Step 2: Create the reset-password page**
 Create `app/(auth)/reset-password/page.tsx`:
 ```tsx
 'use client'
 import { useState } from 'react'
 import { useRouter } from 'next/navigation'
 import Link from 'next/link'
 import { createClient } from '@/lib/supabase/client'
 export default function ResetPasswordPage() {
  const router = useRouter()
  const [password, setPassword] = useState('')
  const [confirm, setConfirm] = useState('')
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState<string | null>(null)
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    setError(null)
    if (password.length < 8) {
      setError('Password must be at least 8 characters.')
      return
    }
    if (password !== confirm) {
      setError('Passwords do not match.')
      return
    }
    setLoading(true)
    const supabase = createClient()
    const { error: updateError } = await supabase.auth.updateUser({ password })
    setLoading(false)
    if (updateError) {
      if (updateError.message.toLowerCase().includes('session') ||
          updateError.message.toLowerCase().includes('expired')) {
        setError('Reset link has expired. Request a new one.')
      } else {
        setError(updateError.message)
      }
      return
    }
    router.push('/login?message=password_reset')
  }
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
      <form onSubmit={handleSubmit} className="flex flex-col gap-4 w-full max-w-sm">
        <div className="text-center">
          <h1 className="text-2xl font-bold">Set new password</h1>
          <p className="text-sm text-gray-500 mt-1">Choose a strong password.</p>
        </div>
        {error && (
          <p className="bg-red-50 border border-red-200 text-red-700 text-sm rounded px-3 py-2">
            {error}{' '}
            {error.includes('expired') && (
              <Link href="/forgot-password" className="underline">
                Request new link
              </Link>
            )}
          </p>
        )}
        <input
          type="password"
          placeholder="New password"
          value={password}
          onChange={e => setPassword(e.target.value)}
          required
          minLength={8}
          autoComplete="new-password"
          className="border border-gray-300 rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <input
          type="password"
          placeholder="Confirm new password"
          value={confirm}
          onChange={e => setConfirm(e.target.value)}
          required
          autoComplete="new-password"
          className="border border-gray-300 rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <button
          type="submit"
          disabled={loading}
          className="bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 rounded-md disabled:opacity-50 transition-colors"
        >
          {loading ? 'Saving…' : 'Set password'}
        </button>
      </form>
    </div>
  )
 }
 ```
 - [ ] **Step 3: Show success message on login page when redirected from reset**
 In `app/(auth)/login/page.tsx` (or wherever the login page renders), check for `?message=password_reset` and show a banner. Check what the login page currently looks like first:
 ```bash
 cat app/\(auth\)/login/page.tsx
 ```
 If it just renders `<LoginForm />`, update it to a server component that reads the search param and passes a success message:
 ```tsx
 import { LoginForm } from '@/components/auth/login-form'
 interface Props {
  searchParams: Promise<{ message?: string }>
 }
 export default async function LoginPage({ searchParams }: Props) {
  const { message } = await searchParams
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
      {message === 'password_reset' && (
        <div className="fixed top-4 left-1/2 -translate-x-1/2 bg-green-50 border border-green-200 text-green-700 text-sm rounded px-4 py-2 shadow">
          Password updated — sign in with your new password.
        </div>
      )}
      <LoginForm />
    </div>
  )
 }
 ```
 If the login page already has a wrapping layout, add the banner inside the existing structure instead.
 - [ ] **Step 4: Verify reset-password page loads**
 Open `http://localhost:3000/ims/reset-password`. Confirm the two password inputs and "Set password" button render. Without a recovery session, the Supabase call will fail — the error message should show.
 - [ ] **Step 5: Commit**
 ```bash
 git add app/\(auth\)/forgot-password/page.tsx app/\(auth\)/reset-password/page.tsx app/\(auth\)/login/page.tsx
 git commit -m "feat(auth): add reset-password page and login success banner"
 ```
 ---
 ### Task 4: Verify Supabase redirect URL and deploy
 **Files:** None — configuration + deploy
 - [ ] **Step 1: Check Supabase redirect URL allowlist**
 Go to [https://supabase.com](https://supabase.com) → project `nkcfjbgappslicotwopl` → Authentication → URL Configuration → Redirect URLs.
 Ensure this URL is listed:
 ```
 http://64.176.82.100/ims/api/auth/callback
 ```
 If missing, click "Add URL" and add it. Without this, Supabase will reject the reset email's redirect as unauthorised.
 - [ ] **Step 2: Deploy to VPS**
 ```bash
 bash deploy.sh
 ```
 Expected output ends with:
 ```
 ==> Done. http://64.176.82.100/ims/
 ```
 - [ ] **Step 3: End-to-end test on production**
 1. Go to `http://64.176.82.100/ims/login` — confirm "Forgot password?" link visible
 2. Click it → confirm redirects to `http://64.176.82.100/ims/forgot-password`
 3. Enter a real user's email → click "Send reset link"
 4. Confirm success screen: "Check your email"
 5. Open email → click the reset link
 6. Confirm landing on `http://64.176.82.100/ims/reset-password`
 7. Enter a new password (≥8 chars) + confirm → click "Set password"
 8. Confirm redirect to `/login` with green success banner
 9. Sign in with the new password — confirm it works