Real-World Session Management in React Native with Auth0 and Biometrics

// types/AuthState.ts
export enum UserState {
  // User has never logged in or has been logged out
  UNAUTHENTICATED = 'unauthenticated',

  // User is in the process of logging in
  AUTHENTICATING = 'authenticating',

  // User is fully authenticated with valid tokens
  AUTHENTICATED = 'authenticated',

  // User was authenticated but tokens have expired
  SESSION_EXPIRED = 'session_expired',

  // User exists but requires additional verification (biometric, 2FA)
  REQUIRES_VERIFICATION = 'requires_verification',

  // App is checking stored credentials on startup
  CHECKING_AUTH = 'checking_auth',

  // User is logging out
  LOGGING_OUT = 'logging_out'
}

export interface AuthState {
  userState: UserState;
  user: User | null;
  tokens: {
    accessToken: string | null;
    refreshToken: string | null;
    expiresAt: number | null;
  };
  lastActivity: number;
  biometricEnabled: boolean;
  sessionStartTime: number;
}

// auth/AuthFlow.ts
class AuthFlow {
  async performLogin(email: string, password: string): Promise<AuthResult> {
    // Step 1: Update state to show loading
    this.updateState({ userState: UserState.AUTHENTICATING });

    try {
      // Step 2: Send credentials to Auth0
      const authResponse = await auth0.authenticate({
        username: email,
        password: password,
        scope: 'openid profile email offline_access'
      });

      // Step 3: Extract tokens from response
      const tokens = {
        accessToken: authResponse.accessToken,
        refreshToken: authResponse.refreshToken,
        expiresAt: Date.now() + (authResponse.expiresIn * 1000)
      };

      // Step 4: Store tokens securely
      await this.secureStorage.storeTokens(tokens);

      // Step 5: Get user profile information
      const userProfile = await this.fetchUserProfile(tokens.accessToken);

      // Step 6: Update app state
      this.updateState({
        userState: UserState.AUTHENTICATED,
        user: userProfile,
        tokens,
        sessionStartTime: Date.now(),
        lastActivity: Date.now()
      });

      // Step 7: Set up automatic token refresh
      await this.scheduleTokenRefresh(tokens.expiresAt);

      // Step 8: Configure biometric authentication if available
      if (await this.biometrics.isAvailable()) {
        await this.setupBiometricAuth(tokens);
      }

      return { success: true };

    } catch (error) {
      // Step 9: Handle login failure
      this.updateState({ userState: UserState.UNAUTHENTICATED });
      throw error;
    }
  }
}

// auth/LogoutFlow.ts
class LogoutFlow {
  async performLogout(reason: LogoutReason): Promise<void> {
    // Step 1: Update state to prevent new operations
    this.updateState({ userState: UserState.LOGGING_OUT });

    try {
      // Step 2: Cancel any ongoing background operations
      await this.cancelBackgroundTasks();

      // Step 3: Stop token refresh timers
      this.tokenManager.stopAllRefreshTimers();

      // Step 4: Clear tokens from memory
      this.clearMemoryTokens();

      // Step 5: Remove tokens from secure storage
      await this.secureStorage.clearAllTokens();

      // Step 6: Clear user data cache
      await this.clearUserDataCache();

      // Step 7: Revoke tokens with Auth0 (if user-initiated)
      if (reason === 'user_initiated') {
        try {
          await this.revokeTokensWithAuth0();
        } catch (error) {
          // Don't fail logout if revocation fails
          console.warn('Token revocation failed:', error);
        }
      }

      // Step 8: Clear biometric stored credentials
      await this.biometrics.clearStoredCredentials();

      // Step 9: Unregister from push notifications
      await this.pushNotifications.unregister();

      // Step 10: Clear navigation stack and redirect
      this.navigation.resetToLogin();

      // Step 11: Update final state
      this.updateState({
        userState: UserState.UNAUTHENTICATED,
        user: null,
        tokens: { accessToken: null, refreshToken: null, expiresAt: null },
        lastActivity: 0,
        sessionStartTime: 0
      });

      // Step 12: Log analytics event
      this.analytics.track('user_logged_out', { reason });

    } catch (error) {
      console.error('Logout error:', error);
      // Even if something fails, force the user to unauthenticated state
      this.forceUnauthenticatedState();
    }
  }
}

// auth/SessionExpiryHandler.ts
class SessionExpiryHandler {
  async handleSessionExpiry(reason: ExpiryReason): Promise<void> {
    switch (reason) {
      case 'access_token_expired':
        await this.handleAccessTokenExpiry();
        break;

      case 'refresh_token_expired':
        await this.handleRefreshTokenExpiry();
        break;

      case 'idle_timeout':
        await this.handleIdleTimeout();
        break;

      case 'absolute_timeout':
        await this.handleAbsoluteTimeout();
        break;

      case 'security_violation':
        await this.handleSecurityViolation();
        break;
    }
  }

  private async handleAccessTokenExpiry(): Promise<void> {
    // This is normal - just refresh the token
    try {
      await this.tokenManager.refreshAccessToken();
      // Continue normally, user doesn't notice
    } catch (error) {
      // Refresh failed, treat as full session expiry
      await this.handleRefreshTokenExpiry();
    }
  }

  private async handleRefreshTokenExpiry(): Promise<void> {
    // This requires user to log in again
    this.showSessionExpiredDialog();
    await this.performLogout('session_expired');
  }

  private async handleIdleTimeout(): Promise<void> {
    // User was inactive too long - require biometric re-auth
    this.updateState({ userState: UserState.REQUIRES_VERIFICATION });

    const biometricResult = await this.biometrics.authenticate();
    if (biometricResult.success) {
      // Reset activity timer
      this.updateLastActivity();
      this.updateState({ userState: UserState.AUTHENTICATED });
    } else {
      // Biometric failed, require full login
      await this.performLogout('idle_timeout');
    }
  }

  private showSessionExpiredDialog(): void {
    Alert.alert(
      'Session Expired',
      'Your session has expired for security reasons. Please log in again.',
      [
        {
          text: 'Log In',
          onPress: () => this.navigation.navigate('Login')
        }
      ],
      { cancelable: false }
    );
  }
}

// auth/AuthService.ts
import Auth0 from 'react-native-auth0';
import * as Keychain from 'react-native-keychain';
import { Alert } from 'react-native';

class AuthService {
  private auth0: Auth0;
  private accessToken: string | null = null;
  private refreshToken: string | null = null;
  private tokenExpiresAt: number | null = null;

  constructor() {
    this.auth0 = new Auth0({
      domain: 'your-tenant.auth0.com',
      clientId: 'your-client-id',
      // Critical: Use proper scopes
      scope: 'openid profile email offline_access'
    });
  }

  async login(): Promise<void> {
    try {
      const credentials = await this.auth0.webAuth.authorize({
        scope: 'openid profile email offline_access',
        // This is crucial for refresh tokens
        audience: 'https://your-api.com',
        prompt: 'login',
        // Custom parameters for better UX
        parameters: {
          device: 'mobile',
          login_hint: await this.getLastUsedEmail()
        }
      });

      await this.handleAuthResponse(credentials);
    } catch (error) {
      console.error('Login failed:', error);
      throw error;
    }
  }

  private async handleAuthResponse(credentials: any): Promise<void> {
    this.accessToken = credentials.accessToken;
    this.refreshToken = credentials.refreshToken;

    // Calculate token expiration
    const expiresIn = credentials.expiresIn || 3600; // Default 1 hour
    this.tokenExpiresAt = Date.now() + (expiresIn * 1000);

    // Store tokens securely
    await this.securelyStoreTokens();
  }
}

// auth/BiometricAuth.ts
import TouchID from 'react-native-touch-id';
import * as Keychain from 'react-native-keychain';
import { Platform } from 'react-native';

interface BiometricAuthResult {
  success: boolean;
  tokens?: { access: string; refresh: string };
  error?: string;
}

class BiometricAuth {
  private static readonly KEYCHAIN_SERVICE = 'com.yourapp.oauth';
  private static readonly BIOMETRIC_THRESHOLD = 5 * 60 * 1000; // 5 minutes

  static async authenticateWithBiometrics(): Promise<BiometricAuthResult> {
    try {
      // Check if biometrics are available
      const biometryType = await TouchID.isSupported();

      if (!biometryType) {
        return { success: false, error: 'Biometrics not available' };
      }

      // Configure biometric prompt
      const optionalConfigObject = {
        title: 'Authentication Required',
        imageColor: '#e00606',
        imageErrorColor: '#ff0000',
        sensorDescription: 'Touch sensor',
        sensorErrorDescription: 'Failed',
        cancelText: 'Cancel',
        fallbackLabel: 'Use Passcode',
        unifiedErrors: false,
        passcodeFallback: true
      };

      // Authenticate
      await TouchID.authenticate(
        'Authenticate to access your account',
        optionalConfigObject
      );

      // Retrieve stored tokens
      const credentials = await Keychain.getInternetCredentials(
        this.KEYCHAIN_SERVICE
      );

      if (!credentials) {
        return { success: false, error: 'No stored credentials' };
      }

      // Parse stored tokens
      const tokens = JSON.parse(credentials.password);

      // Check if tokens are still valid
      if (await this.shouldRefreshTokens(tokens)) {
        const newTokens = await AuthService.refreshTokens(tokens.refresh);
        await this.storeTokens(newTokens);
        return { success: true, tokens: newTokens };
      }

      return { success: true, tokens };
    } catch (error) {
      console.error('Biometric auth failed:', error);
      return { success: false, error: error.message };
    }
  }

  private static async shouldRefreshTokens(tokens: any): Promise<boolean> {
    // Check if we're within the threshold of token expiration
    const expiresAt = tokens.expiresAt || 0;
    const now = Date.now();
    return (expiresAt - now) < this.BIOMETRIC_THRESHOLD;
  }
}

// auth/TokenManager.ts
import NetInfo from '@react-native-community/netinfo';
import BackgroundTimer from 'react-native-background-timer';

class TokenManager {
  private refreshTimer: number | null = null;
  private readonly TOKEN_REFRESH_MARGIN = 5 * 60 * 1000; // 5 minutes
  private readonly MAX_RETRY_ATTEMPTS = 3;

  async initializeTokenRefresh(): Promise<void> {
    // Clear any existing timer
    this.stopTokenRefresh();

    // Get current token expiration
    const expiresAt = await this.getTokenExpiration();
    if (!expiresAt) return;

    // Calculate when to refresh (5 minutes before expiration)
    const refreshTime = expiresAt - Date.now() - this.TOKEN_REFRESH_MARGIN;

    if (refreshTime > 0) {
      // Use background timer for reliability
      this.refreshTimer = BackgroundTimer.setTimeout(async () => {
        await this.performTokenRefresh();
      }, refreshTime);
    } else {
      // Token needs immediate refresh
      await this.performTokenRefresh();
    }
  }

  private async performTokenRefresh(): Promise<void> {
    let attempts = 0;

    while (attempts < this.MAX_RETRY_ATTEMPTS) {
      try {
        // Check network connectivity first
        const netInfo = await NetInfo.fetch();
        if (!netInfo.isConnected) {
          // Schedule retry when network is available
          const unsubscribe = NetInfo.addEventListener(state => {
            if (state.isConnected) {
              unsubscribe();
              this.performTokenRefresh();
            }
          });
          return;
        }

        // Get stored refresh token
        const refreshToken = await this.getRefreshToken();
        if (!refreshToken) {
          // No refresh token, user needs to log in again
          await this.handleSessionExpired();
          return;
        }

        // Perform the refresh
        const response = await auth0.oauth.refreshToken({
          refreshToken,
          scope: 'openid profile email offline_access'
        });

        // Store new tokens
        await this.updateTokens({
          accessToken: response.accessToken,
          refreshToken: response.refreshToken || refreshToken,
          expiresIn: response.expiresIn
        });

        // Schedule next refresh
        await this.initializeTokenRefresh();

        break; // Success, exit retry loop

      } catch (error) {
        attempts++;

        if (error.error === 'invalid_grant') {
          // Refresh token is invalid/expired
          await this.handleSessionExpired();
          return;
        }

        if (attempts >= this.MAX_RETRY_ATTEMPTS) {
          console.error('Token refresh failed after max attempts:', error);
          await this.handleSessionExpired();
          return;
        }

        // Exponential backoff
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, attempts) * 1000)
        );
      }
    }
  }

  private async handleSessionExpired(): Promise<void> {
    // Clear all stored tokens
    await this.clearTokens();

    // Notify user
    Alert.alert(
      'Session Expired',
      'Your session has expired. Please log in again.',
      [
        {
          text: 'Log In',
          onPress: () => NavigationService.navigate('Login')
        }
      ]
    );
  }
}

// services/BackgroundService.ts
import BackgroundFetch from 'react-native-background-fetch';
import PushNotification from 'react-native-push-notification';

class BackgroundService {
  static async configure(): Promise<void> {
    // Configure background fetch
    BackgroundFetch.configure({
      minimumFetchInterval: 15, // minutes
      forceAlarmManager: false,
      stopOnTerminate: false,
      startOnBoot: true,
      enableHeadless: true,
      requiresBatteryNotLow: false,
      requiresCharging: false,
      requiresStorageNotLow: false,
      requiresDeviceIdle: false,
      requiredNetworkType: BackgroundFetch.NETWORK_TYPE_ANY
    }, async (taskId) => {
      // This runs in background
      await this.performBackgroundTask();
      BackgroundFetch.finish(taskId);
    }, (error) => {
      console.error('Background fetch failed:', error);
    });

    // Configure push notifications
    PushNotification.configure({
      onRegister: async (token) => {
        // Store FCM/APNS token
        await this.registerDeviceToken(token.token);
      },

      onNotification: async (notification) => {
        // Handle notification when app is in foreground/background
        const isAuthenticated = await this.checkAuthStatus();

        if (!isAuthenticated && notification.data.requiresAuth) {
          // Store notification for later
          await this.queueNotification(notification);
          return;
        }

        // Process notification
        await this.handleNotification(notification);
      },

      permissions: {
        alert: true,
        badge: true,
        sound: true
      },

      popInitialNotification: true,
      requestPermissions: true
    });
  }

  private static async performBackgroundTask(): Promise<void> {
    try {
      // Check if we have valid tokens
      const tokens = await TokenManager.getTokens();
      if (!tokens || !tokens.accessToken) {
        console.log('No valid session for background task');
        return;
      }

      // Check if token needs refresh
      if (await TokenManager.shouldRefreshToken()) {
        await TokenManager.performTokenRefresh();
      }

      // Perform your background operations
      await this.syncDataInBackground();

    } catch (error) {
      console.error('Background task error:', error);
    }
  }

  private static async checkAuthStatus(): Promise<boolean> {
    const tokens = await TokenManager.getTokens();
    if (!tokens || !tokens.accessToken) return false;

    // Check if token is expired
    const expiresAt = tokens.expiresAt || 0;
    return Date.now() < expiresAt;
  }
}

// config/AuthConfig.ts
export const AuthConfig = {
  // Access token: 15 minutes
  // Why: Balances security with user experience
  // Shorter = more secure but more refresh calls
  // Longer = less secure but better performance
  accessTokenExpiration: 15 * 60, // seconds

  // Refresh token: 30 days for mobile
  // Why: Mobile apps have different usage patterns than web
  // Users expect to stay logged in between app launches
  refreshTokenExpiration: 30 * 24 * 60 * 60, // seconds

  // Idle timeout: 30 minutes
  // After this period of inactivity, require biometric re-auth
  idleTimeout: 30 * 60 * 1000, // milliseconds

  // Absolute timeout: 7 days
  // Force re-authentication regardless of activity
  absoluteTimeout: 7 * 24 * 60 * 60 * 1000, // milliseconds

  // Background refresh threshold: 5 minutes
  // Start refresh process this many minutes before expiration
  refreshThreshold: 5 * 60 * 1000, // milliseconds
};

// hooks/useAppState.ts
import { useEffect, useRef } from 'react';
import { AppState, AppStateStatus } from 'react-native';

export const useAppState = () => {
  const appState = useRef(AppState.currentState);
  const lastActiveTime = useRef(Date.now());

  useEffect(() => {
    const handleAppStateChange = async (nextAppState: AppStateStatus) => {
      if (
        appState.current.match(/inactive|background/) &&
        nextAppState === 'active'
      ) {
        // App came to foreground
        const inactiveTime = Date.now() - lastActiveTime.current;

        if (inactiveTime > AuthConfig.idleTimeout) {
          // Require biometric re-authentication
          const result = await BiometricAuth.authenticateWithBiometrics();
          if (!result.success) {
            // Redirect to login
            NavigationService.navigate('Login');
          }
        } else {
          // Just refresh tokens if needed
          await TokenManager.initializeTokenRefresh();
        }
      } else if (nextAppState.match(/inactive|background/)) {
        // App went to background
        lastActiveTime.current = Date.now();
      }

      appState.current = nextAppState;
    };

    const subscription = AppState.addEventListener('change', handleAppStateChange);
    return () => subscription.remove();
  }, []);
};

// services/NetworkAwareTokenManager.ts
class NetworkAwareTokenManager extends TokenManager {
  private pendingRefresh: Promise<void> | null = null;

  async performTokenRefresh(): Promise<void> {
    // Prevent multiple simultaneous refresh attempts
    if (this.pendingRefresh) {
      return this.pendingRefresh;
    }

    this.pendingRefresh = this.doRefresh();

    try {
      await this.pendingRefresh;
    } finally {
      this.pendingRefresh = null;
    }
  }

  private async doRefresh(): Promise<void> {
    const netInfo = await NetInfo.fetch();

    if (!netInfo.isConnected) {
      // No network, wait for connection
      return new Promise((resolve, reject) => {
        const unsubscribe = NetInfo.addEventListener(state => {
          if (state.isConnected) {
            unsubscribe();
            super.performTokenRefresh().then(resolve).catch(reject);
          }
        });

        // Timeout after 5 minutes
        setTimeout(() => {
          unsubscribe();
          reject(new Error('Network timeout'));
        }, 5 * 60 * 1000);
      });
    }

    return super.performTokenRefresh();
  }
}

// auth/LogoutManager.ts
class LogoutManager {
  static async logout(reason?: 'user_initiated' | 'session_expired' | 'security'): Promise<void> {
    try {
      // 1. Clear tokens from memory
      TokenManager.clearMemoryTokens();

      // 2. Cancel any pending refresh timers
      TokenManager.stopTokenRefresh();

      // 3. Clear secure storage
      await Keychain.resetInternetCredentials(AuthService.KEYCHAIN_SERVICE);

      // 4. Clear any cached user data
      await AsyncStorage.multiRemove([
        '@user_profile',
        '@user_preferences',
        '@last_sync_time'
      ]);

      // 5. Unregister push notifications
      await PushNotification.abandonPermissions();

      // 6. Clear web cookies (important for Auth0)
      if (Platform.OS === 'ios') {
        await CookieManager.clearAll(true);
      } else {
        await CookieManager.clearAll();
      }

      // 7. Notify Auth0 (optional but recommended)
      if (reason === 'user_initiated') {
        try {
          await auth0.webAuth.clearSession();
        } catch (error) {
          // Ignore errors, user is logged out locally anyway
          console.log('Auth0 logout error:', error);
        }
      }

      // 8. Reset navigation
      NavigationService.reset('Auth');

      // 9. Log analytics event
      Analytics.track('user_logged_out', { reason });

    } catch (error) {
      console.error('Logout error:', error);
      // Even if something fails, ensure user can't access protected content
      NavigationService.reset('Auth');
    }
  }
}

// security/SecurityManager.ts
import JailMonkey from 'jail-monkey';
import { Platform } from 'react-native';

class SecurityManager {
  static async checkDeviceSecurity(): Promise<{ secure: boolean; reason?: string }> {
    // Check for jailbreak/root
    if (JailMonkey.isJailBroken()) {
      return { secure: false, reason: 'device_compromised' };
    }

    // Check for debugger
    if (JailMonkey.isDebuggedMode()) {
      return { secure: false, reason: 'debugger_attached' };
    }

    // Check for app integrity (iOS only)
    if (Platform.OS === 'ios' && !JailMonkey.isOnExternalStorage()) {
      return { secure: false, reason: 'app_tampered' };
    }

    return { secure: true };
  }

  static async initializeSecurity(): Promise<void> {
    const { secure, reason } = await this.checkDeviceSecurity();

    if (!secure) {
      Alert.alert(
        'Security Warning',
        'Your device appears to be compromised. Some features may be disabled.',
        [{ text: 'OK' }]
      );

      // Limit functionality for compromised devices
      await this.enableRestrictedMode();
    }
  }
}