Skip to content

email-verification-enhancement-plan.md

Latest commit

 

History

History
299 lines (238 loc) · 10.3 KB

email-verification-enhancement-plan.md

File metadata and controls

299 lines (238 loc) · 10.3 KB

Email Verification Enhancement Plan

Project: IndexNow Studio
Date: September 19, 2025
Status: Planning Phase

Current State Analysis

✅ What's Already Implemented

  1. Dedicated /verify page at app/(public)/auth/verify/page.tsx

    • Shows "Check your email" message with email parameter
    • Redirects back to login page
    • Proper styling matching project design

  2. Registration Flow

    • app/(public)/auth/register/page.tsx redirects to /verify?email=user@email.com on success
    • Uses Supabase Auth for user registration
    • Registration API endpoint at /api/v1/auth/register

  3. Auth Callback System

    • app/auth/callback/route.ts handles Supabase verification tokens
    • Exchanges code for session using exchangeCodeForSession
    • Redirects to dashboard on successful verification

  4. Authentication Context

    • lib/contexts/AuthContext.tsx manages global auth state
    • Tracks emailVerification property based on email_confirmed_at
    • lib/auth/auth.ts includes email verification status in user object

❌ What's Missing

  1. Email Confirmation Check During Login

    • Current login flow (app/login/page.tsx) doesn't check email_confirmed_at status
    • Unconfirmed users can access dashboard directly after login
    • No redirect to /verify for unconfirmed users

  2. Proper Supabase Verification URL Handling

    • Current callback route doesn't distinguish between different verification types
    • Need to handle signup confirmation vs password reset vs magic link flows
    • Missing proper error handling for expired/invalid tokens

  3. Enhanced Verification Page Features

    • No option to resend confirmation email
    • No handling for different verification states (expired, invalid, etc.)
    • No user feedback for verification process

Enhancement Requirements

1. Enhanced Login Flow with Email Verification Check

Objective: Redirect unconfirmed users to /verify instead of dashboard

Implementation Details:

  • Modify app/login/page.tsx to check user's email confirmation status after login
  • If user.emailVerification === false or email_confirmed_at === null, redirect to /verify?email=user@email.com
  • Add proper loading states and error handling
  • Maintain current login functionality for confirmed users

Files to Modify:

  • app/login/page.tsx - Add email confirmation check after successful login
  • lib/auth/auth.ts - Ensure emailVerification property is properly set

2. Enhanced Authentication Callback Route

Objective: Properly handle different types of verification URLs from Supabase

Current Supabase Verification URL Format:

https://indexnow.studio/auth/v1/verify?token=e98ea7ff93b5a8f26694e9706571579f74e005df481e08ab09adecdf&type=signup&redirect_to=http://localhost:3000

Implementation Details:

  • Modify app/auth/callback/route.ts to handle different type parameters:
    • type=signup - Email confirmation for new registration
    • type=recovery - Password reset verification
    • type=magiclink - Magic link authentication
  • Add proper success/error redirects based on verification type
  • Update email_confirmed_at status in database when verification succeeds
  • Add comprehensive error handling for expired/invalid tokens

Files to Modify:

  • app/auth/callback/route.ts - Enhanced callback handling
  • Create new route: app/auth/v1/verify/route.ts - Handle Supabase verification URLs

3. Enhanced Verification Page

Objective: Improve user experience during email verification process

Implementation Details:

  • Add "Resend Email" functionality with rate limiting
  • Show different messages based on verification state (pending, expired, invalid)
  • Add countdown timer for resend functionality
  • Improve error handling and user feedback
  • Add automatic refresh/polling to check verification status

Features to Add:

  • Resend confirmation email button (with 60-second cooldown)
  • Real-time verification status checking
  • Better error messages for common issues
  • Progress indicators
  • Success state handling

Files to Modify:

  • app/(public)/auth/verify/page.tsx - Enhanced verification page
  • Create API route: app/api/v1/auth/resend-verification/route.ts

4. Authentication Context Enhancement

Objective: Improve authentication state management for email verification

Implementation Details:

  • Enhance useAuth hook to provide email verification status
  • Add method to refresh authentication state after verification
  • Improve user object structure to include verification details
  • Add helper methods for verification-related actions

Files to Modify:

  • lib/contexts/AuthContext.tsx - Add email verification helpers
  • lib/auth/auth.ts - Enhance user object with verification data

Technical Implementation Plan

Phase 1: Core Login Enhancement (Priority: High)

  1. Update Login Page

    // In app/login/page.tsx - after successful login
const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault()
  setIsLoading(true)
  setError("")
  
  try {
    const { user } = await authService.signIn(email, password)
    
    // Check email verification status
    if (!user?.emailVerification) {
      router.push(`/verify?email=${encodeURIComponent(email)}`)
      return
    }
    
    router.push("/dashboard")
  } catch (error: any) {
    setError(error.message || "Login failed")
  } finally {
    setIsLoading(false)
  }
}

  2. Enhance Auth Service

    • Ensure getCurrentUser() properly sets emailVerification field
    • Add helper method isEmailConfirmed()

Phase 2: Verification URL Handling (Priority: High)

  1. Create Supabase Verification Route

    // New file: app/auth/v1/verify/route.ts
export async function GET(request: NextRequest) {
  const { searchParams, origin } = new URL(request.url)
  const token = searchParams.get('token')
  const type = searchParams.get('type')
  const redirectTo = searchParams.get('redirect_to')
  
  // Handle different verification types
  switch (type) {
    case 'signup':
      // Handle email confirmation
      break
    case 'recovery': 
      // Handle password reset
      break
    // etc.
  }
}

  2. Update Existing Callback Route

    • Maintain backward compatibility
    • Add proper error handling
    • Improve redirect logic

Phase 3: Enhanced Verification Page (Priority: Medium)

  1. Add Resend Functionality

    // In app/(public)/auth/verify/page.tsx
const [canResend, setCanResend] = useState(false)
const [countdown, setCountdown] = useState(60)

const handleResendEmail = async () => {
  // Call resend API
  // Start countdown timer
  // Update UI state
}

  2. Create Resend API Route

    // New file: app/api/v1/auth/resend-verification/route.ts
export async function POST(request: NextRequest) {
  // Validate request
  // Check rate limiting
  // Resend verification email via Supabase
  // Return success/error response
}

Phase 4: Testing & Polish (Priority: Low)

  1. User Flow Testing

    • Test registration → verification → login flow
    • Test unconfirmed user login redirect
    • Test resend functionality
    • Test expired token handling

  2. Error Handling

    • Add comprehensive error messages
    • Handle edge cases
    • Improve user feedback

Database Considerations

Current Database Schema

The project uses Supabase Auth's built-in auth.users table with the email_confirmed_at field:

-- Supabase auth.users table (managed by Supabase)
SELECT email_confirmed_at FROM auth.users WHERE id = 'user-id';

Note: Since this project uses Supabase's managed auth system, no custom database changes are required. The email_confirmed_at field is automatically managed by Supabase Auth.

Security Considerations

1. Rate Limiting

  • Implement rate limiting for resend email functionality
  • Prevent spam/abuse of verification system
  • Use server-side validation

2. Token Validation

  • Ensure proper token validation in callback routes
  • Handle expired tokens gracefully
  • Prevent token replay attacks

3. User Privacy

  • Don't expose sensitive user data in URLs
  • Use proper HTTPS redirects
  • Sanitize email parameters

Success Criteria

✅ Functional Requirements

  • Unconfirmed users are redirected to /verify when trying to access dashboard
  • Email verification URLs from Supabase work correctly
  • Users can resend verification emails with rate limiting
  • Verification page shows proper status and feedback
  • Email confirmation updates email_confirmed_at in database

✅ User Experience Requirements

  • Seamless flow from registration → verification → dashboard
  • Clear error messages for common issues
  • Professional UI matching project design system
  • Mobile-responsive verification page
  • Proper loading states throughout the flow

✅ Technical Requirements

  • No breaking changes to existing authentication flow
  • Backward compatibility with existing URLs
  • Proper error handling and logging
  • SEO-friendly page structure
  • Follow project coding standards and patterns

Timeline Estimate

  • Phase 1 (Core Login Enhancement): 2-3 hours
  • Phase 2 (Verification URL Handling): 3-4 hours
  • Phase 3 (Enhanced Verification Page): 2-3 hours
  • Phase 4 (Testing & Polish): 1-2 hours

Total Estimated Time: 8-12 hours

Risk Mitigation

Potential Risks:

  1. Breaking existing auth flow - Mitigate by thorough testing
  2. Supabase URL format changes - Handle gracefully with fallbacks
  3. User confusion during verification - Provide clear instructions
  4. Rate limiting bypass - Implement server-side validation

Testing Strategy:

  1. Test all existing auth flows still work
  2. Test new verification flows thoroughly
  3. Test edge cases (expired tokens, invalid emails, etc.)
  4. Test mobile responsiveness
  5. Test with different email providers

Notes

  • This plan maintains full compatibility with existing authentication system
  • All changes follow project's Next.js + Supabase architecture
  • UI/UX follows established project design system and color scheme
  • Implementation will be done in phases to minimize risk
⚡