Firebase Authentication Guide

┌─────────────────────────────────────────────────────────────┐
│                   Firebase Auth Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. User clicks "Sign in with Google"                       │
│     ↓                                                       │
│  2. Firebase opens Google OAuth popup                       │
│     ↓                                                       │
│  3. User authenticates with Google                          │
│     ↓                                                       │
│  4. Firebase returns UserCredential                         │
│     ↓                                                       │
│  5. App redirects to /access (Smart Routing Proxy)          │
│     ↓                                                       │
│  6. /access determines:                                     │
│     - First-time user (< 5 min old) → /onboarding           │
│     - Returning user → /dashboard/chat                      │
│     - Custom redirect → specified URL                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

lib/
├── firebase/
│   ├── config.ts                    # Firebase config & initialization
│   └── auth.ts                      # Auth utilities
├── services/
│   ├── firebase-auth.service.ts     # Main auth service (all methods)
│   ├── firebase-user.service.ts     # User profile management
│   └── firebase-project.service.ts  # Project management
contexts/
└── AuthContext.tsx                  # React context for auth state
app/
├── (marketing)/auth/
│   ├── login/page.tsx              # Login page
│   └── register/page.tsx           # Registration page
├── __/auth/handler/page.tsx        # Firebase redirect handler
└── access/page.tsx                 # Smart routing proxy
components/
└── auth/
    └── simple-auth-form.tsx        # Auth form component

// app/access/page.tsx
 
const getSmartDestination = async (user: User): Promise<string> => {
  // 1. Check for external redirect URL
  if (redirectUrl) return redirectUrl
 
  // 2. Check for internal return URL
  if (returnTo) return returnTo
 
  // 3. Determine if first-time or returning user
  const creationTime = user.metadata?.creationTime
  if (creationTime) {
    const minutesSinceCreation = getMinutesSince(creationTime)
 
    // First-time user (< 5 minutes old)
    if (minutesSinceCreation < 5) {
      return '/onboarding'
    }
  }
 
  // 4. Default: returning user
  return '/dashboard/chat'
}

// Basic: Let smart routing decide
router.push('/access')
 
// With return URL (after protected route redirect)
router.push('/access?returnTo=/dashboard/markets')
 
// With external redirect (for cross-domain auth)
router.push('/access?redirectUrl=https://external.com/callback')

// Sign-In Methods
static async signInWithGoogle(): Promise<UserCredential>
static async signInWithEmail(email: string, password: string): Promise<UserCredential>
static async createAccount(email: string, password: string, displayName?: string): Promise<UserCredential>
static async signOut(): Promise<void>
static async handleRedirectResult(): Promise<UserCredential | null>
 
// User Management
static getCurrentUser(): User | null
static toAuthUser(user: User): AuthUser
static isAuthenticated(): boolean
static async getIdToken(forceRefresh = false): Promise<string | null>
static onAuthStateChange(callback: (user: User | null) => void): () => void
 
// Profile Updates
static async resetPassword(email: string): Promise<void>
static async updateUserProfile(updates: { displayName?: string; photoURL?: string }): Promise<void>
static async updateUserEmail(newEmail: string, password: string): Promise<void>
static async updateUserPassword(currentPassword: string, newPassword: string): Promise<void>

'use client'
 
import { useAuth } from '@/contexts/AuthContext'
 
export function UserProfile() {
  const {
    user,              // Firebase User | null
    userProfile,       // Extended profile data
    loading,           // Auth state loading
    signInWithGoogle,  // Sign-in method
    signOut,           // Sign-out method
  } = useAuth()
 
  if (loading) return <LoadingSpinner />
  if (!user) return <LoginPrompt />
 
  return <div>Welcome, {user.displayName}!</div>
}

// app/(dashboard)/dashboard/layout.tsx
'use client'
 
import { useAuth } from '@/contexts/AuthContext'
import { redirect } from 'next/navigation'
import { useEffect } from 'react'
 
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  const { user, loading } = useAuth()
 
  useEffect(() => {
    if (!loading && !user) {
      redirect('/auth/login')
    }
  }, [user, loading])
 
  if (loading) return <LoadingScreen />
  if (!user) return null
 
  return <DashboardLayout>{children}</DashboardLayout>
}

const handleAuthError = (error: any) => {
  switch (error.code) {
    case 'auth/popup-closed-by-user':
      toast.info('Sign-in cancelled. Try again when ready.')
      break
    case 'auth/popup-blocked':
      toast.warning('Popup blocked. Redirecting to Google...')
      break
    case 'auth/user-not-found':
      toast.error('No account found with this email.')
      break
    case 'auth/wrong-password':
      toast.error('Incorrect password.')
      break
    case 'auth/email-already-in-use':
      toast.error('Email already registered. Try signing in.')
      break
    case 'auth/weak-password':
      toast.error('Password too weak. Use at least 8 characters.')
      break
    case 'auth/too-many-requests':
      toast.error('Too many attempts. Try again later.')
      break
    default:
      toast.error(error.message || 'Authentication failed')
  }
}

// ✅ Good: Use popup method
await signInWithPopup(auth, googleProvider)
 
// ❌ Avoid: Causes redirect loops in Next.js 16
await signInWithRedirect(auth, googleProvider)
 
// ✅ Good: Handle popup-blocked gracefully
try {
  await signInWithPopup(auth, googleProvider)
} catch (error: any) {
  if (error.code === 'auth/popup-blocked') {
    await signInWithRedirect(auth, googleProvider)
    toast.info('Popup blocked. Redirecting to Google...')
  }
}
 
// ✅ Good: Always use smart routing
router.push('/access')
 
// ❌ Avoid: Hardcoded destination
router.push('/dashboard/explore')

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User profiles - users can only read/write their own
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
 
    // Leagues - read public, write owner only
    match /leagues/{leagueId} {
      allow read: if true;
      allow write: if request.auth != null &&
                      request.auth.uid == resource.data.ownerUid;
    }
  }
}