Authentication Flow and Protected Routes

Authentication Architecture Overview

// Auth states:
// 'loading'        -> Show a splash/loading screen
// 'unauthenticated' -> Show auth stack (Sign In, Sign Up)
// 'authenticated'   -> Show app stack (tabs, data screens)

// The navigator reads session from AuthContext:
const { session, isLoading } = useAuth();

if (isLoading) return <SplashScreen />;

return (
  <NavigationContainer>
    {session ? <AppNavigator /> : <AuthNavigator />}
  </NavigationContainer>
);

AuthContext Setup

// src/context/AuthContext.tsx
import React, { createContext, useContext, useEffect, useState } from 'react';
import { Session } from '@supabase/supabase-js';
import { supabase } from '../services/supabase';

interface AuthContextType {
  session: Session | null;
  isLoading: boolean;
  signOut: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType>(null!);

export function AuthProvider({ children }) {
  const [session, setSession] = useState<Session | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    supabase.auth.getSession().then(({ data }) => {
      setSession(data.session);
      setIsLoading(false);
    });

    const { data: listener } = supabase.auth.onAuthStateChange(
      (_event, session) => setSession(session)
    );
    return () => listener.subscription.unsubscribe();
  }, []);

  const signOut = async () => { await supabase.auth.signOut(); };

  return (
    <AuthContext.Provider value={{ session, isLoading, signOut }}>
      {children}
    </AuthContext.Provider>
  );
}

export const useAuth = () => useContext(AuthContext);

Wrapping the App with AuthProvider

// App.tsx (entry point)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthProvider } from './src/context/AuthContext';
import { RootNavigator } from './src/navigation/RootNavigator';

const queryClient = new QueryClient();

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider>
        <RootNavigator />
      </AuthProvider>
    </QueryClientProvider>
  );
}

Sign-Up Screen Implementation

// src/screens/auth/SignUpScreen.tsx
import { useForm, Controller } from 'react-hook-form';
import { supabase } from '../../services/supabase';

export function SignUpScreen({ navigation }) {
  const { control, handleSubmit, formState: { errors } } = useForm();
  const [message, setMessage] = useState('');

  const onSubmit = async ({ email, password }) => {
    const { error } = await supabase.auth.signUp({ email, password });
    if (error) {
      setMessage(error.message);
    } else {
      setMessage('Check your email to confirm your account!');
    }
  };

  return (
    <View>
      <Controller
        control={control}
        name='email'
        rules={{ required: true, pattern: /^[^@]+@[^@]+$/ }}
        render={({ field: { onChange, value } }) => (
          <TextInput
            value={value}
            onChangeText={onChange}
            placeholder='Email'
            keyboardType='email-address'
          />
        )}
      />
      {/* Password field similar pattern */}
      <Button title='Sign Up' onPress={handleSubmit(onSubmit)} />
      {message ? <Text>{message}</Text> : null}
    </View>
  );
}

Sign-In Screen and Session Persistence

// Sign-in logic (simplified)
const signIn = async (email, password) => {
  setLoading(true);
  const { error } = await supabase.auth.signInWithPassword({
    email,
    password,
  });
  setLoading(false);

  if (error) {
    // Show error to user
    Alert.alert('Sign In Error', error.message);
    return;
  }

  // No navigation.navigate() needed!
  // AuthContext.onAuthStateChange fires automatically
  // -> session is set -> root navigator switches to AppNavigator
};

Root Navigator with Auth Guard

// src/navigation/RootNavigator.tsx
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { useAuth } from '../context/AuthContext';
import { AuthNavigator } from './AuthNavigator';
import { AppTabNavigator } from './AppTabNavigator';
import { SplashScreen } from '../screens/SplashScreen';

const Stack = createStackNavigator();

export function RootNavigator() {
  const { session, isLoading } = useAuth();

  if (isLoading) {
    return <SplashScreen />; // Full-screen loading state
  }

  return (
    <NavigationContainer>
      {session ? (
        <AppTabNavigator />  // Authenticated: show app screens
      ) : (
        <AuthNavigator />    // Unauthenticated: show auth screens
      )}
    </NavigationContainer>
  );
}

Protecting Individual Screens

// src/hooks/useRequireAuth.ts
import { useEffect } from 'react';
import { useNavigation } from '@react-navigation/native';
import { useAuth } from '../context/AuthContext';

export function useRequireAuth() {
  const { session, isLoading } = useAuth();
  const navigation = useNavigation();

  useEffect(() => {
    if (!isLoading && !session) {
      navigation.navigate('SignIn' as never);
    }
  }, [session, isLoading, navigation]);

  return { session, isLoading };
}

// Usage in a screen:
export function PremiumFeatureScreen() {
  const { session } = useRequireAuth();
  if (!session) return null; // Navigation already happening
  return <View>...</View>;
}

Handling Token Expiry

// Token expiry handling is automatic with Supabase:
// supabase client config (already set):
// {
//   auth: {
//     autoRefreshToken: true,  <- handles renewal automatically
//     persistSession: true,
//     storage: AsyncStorage,
//   }
// }

// Your AuthContext listener handles SIGNED_OUT:
supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'SIGNED_OUT') {
    // session is null -> navigator shows auth screens
    setSession(null);
  }
  if (event === 'TOKEN_REFRESHED') {
    // New session with fresh tokens
    setSession(session);
  }
});

Password Reset Flow

// Step 1: Send reset email
const resetPassword = async (email) => {
  const { error } = await supabase.auth.resetPasswordForEmail(email, {
    redirectTo: 'habittracker://reset-password',
  });
  if (!error) Alert.alert('Email sent', 'Check your inbox.');
};

// Step 2: Handle deep link in AuthContext
supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'PASSWORD_RECOVERY') {
    // Navigate to update password screen
    navigationRef.current?.navigate('UpdatePassword');
  }
});

// Step 3: Update password screen
const updatePassword = async (newPassword) => {
  const { error } = await supabase.auth.updateUser({
    password: newPassword,
  });
  if (!error) navigation.navigate('Home');
};

Sign Out and Session Cleanup

// Complete sign-out
const signOut = async () => {
  // 1. Sign out from Supabase (clears AsyncStorage session)
  await supabase.auth.signOut();

  // 2. Clear React Query cache
  queryClient.clear();

  // 3. AuthContext detects SIGNED_OUT -> session = null
  // 4. RootNavigator switches to AuthNavigator automatically
  // No navigation.navigate() needed!
};

// In a Settings screen:
<TouchableOpacity onPress={signOut}>
  <Text>Sign Out</Text>
</TouchableOpacity>

Testing the Auth Flow

# Maestro test for sign-in flow
---
appId: com.yourcompany.habittracker
---
- launchApp:
    clearState: true
- assertVisible: 'Sign In'
- tapOn: 'Email'
- inputText: 'test@example.com'
- tapOn: 'Password'
- inputText: 'TestPass123!'
- tapOn: 'Sign In'
- waitForAnimationToEnd
- assertVisible: 'My Habits'  # First app screen
- tapOn: 'Settings'
- tapOn: 'Sign Out'
- waitForAnimationToEnd
- assertVisible: 'Sign In'   # Back to auth screen

Quick Check

Lesson Recap