@umituz/react-native-auth 3.6.57 → 3.6.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-auth",
-  "version": "3.6.57",
+  "version": "3.6.59",
   "description": "Authentication service for React Native apps - Secure, type-safe, and production-ready. Provider-agnostic design with dependency injection, configurable validation, and comprehensive error handling.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -31,7 +31,6 @@
     "type": "git",
     "url": "git+https://github.com/umituz/react-native-auth.git"
   },
-  "dependencies": {},
   "peerDependencies": {
     "@react-navigation/native": ">=6.0.0",
     "@react-navigation/stack": ">=6.0.0",
@@ -62,7 +61,8 @@
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
     "@umituz/react-native-design-system": "^2.9.33",
-    "@umituz/react-native-firebase": "^1.13.82",
+    "@umituz/react-native-firebase": "^1.13.114",
+    "@umituz/react-native-localization": "^3.7.24",
     "eslint": "^8.57.0",
     "expo-apple-authentication": "^6.0.0",
     "expo-application": "^7.0.8",
@@ -85,7 +85,9 @@
     "expo-video": "^3.0.15",
     "expo-web-browser": "^12.0.0",
     "firebase": "^11.0.0",
+    "i18next": "^25.8.4",
     "react": "~19.1.0",
+    "react-i18next": "^16.5.4",
     "react-native": "~0.81.5",
     "react-native-gesture-handler": "^2.0.0",
     "react-native-safe-area-context": "^4.0.0",

package/src/domain/value-objects/AuthConfig.ts

@@ -56,3 +56,83 @@ export const DEFAULT_AUTH_CONFIG: AuthConfig = {
   social: DEFAULT_SOCIAL_CONFIG,
 };
 
+/**
+ * Configuration validation error
+ */
+export class AuthConfigValidationError extends Error {
+  constructor(message: string, public readonly field: string) {
+    super(message);
+    this.name = "AuthConfigValidationError";
+  }
+}
+
+/**
+ * Validate authentication configuration
+ * @throws {AuthConfigValidationError} if configuration is invalid
+ */
+export function validateAuthConfig(config: Partial<AuthConfig>): void {
+  // Validate password config
+  if (config.password) {
+    if (typeof config.password.minLength !== "number") {
+      throw new AuthConfigValidationError(
+        "Password minLength must be a number",
+        "password.minLength"
+      );
+    }
+    if (config.password.minLength < 4) {
+      throw new AuthConfigValidationError(
+        "Password minLength must be at least 4 characters",
+        "password.minLength"
+      );
+    }
+    if (config.password.minLength > 128) {
+      throw new AuthConfigValidationError(
+        "Password minLength must not exceed 128 characters",
+        "password.minLength"
+      );
+    }
+  }
+
+  // Validate social auth config
+  if (config.social) {
+    if (config.social.google) {
+      const googleConfig = config.social.google;
+      if (googleConfig.enabled) {
+        // At least one client ID should be provided if enabled
+        if (!googleConfig.webClientId && !googleConfig.iosClientId && !googleConfig.androidClientId) {
+          throw new AuthConfigValidationError(
+            "At least one Google client ID (web, iOS, or Android) must be provided when Google Sign-In is enabled",
+            "social.google"
+          );
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Sanitize and merge auth config with defaults
+ * Ensures valid configuration values
+ */
+export function sanitizeAuthConfig(config: Partial<AuthConfig> = {}): AuthConfig {
+  // Validate first
+  validateAuthConfig(config);
+
+  return {
+    password: {
+      minLength: config.password?.minLength ?? DEFAULT_PASSWORD_CONFIG.minLength,
+    },
+    social: {
+      google: {
+        enabled: config.social?.google?.enabled ?? DEFAULT_SOCIAL_CONFIG.google?.enabled ?? false,
+        webClientId: config.social?.google?.webClientId,
+        iosClientId: config.social?.google?.iosClientId,
+        androidClientId: config.social?.google?.androidClientId,
+      },
+      apple: {
+        enabled: config.social?.apple?.enabled ?? DEFAULT_SOCIAL_CONFIG.apple?.enabled ?? false,
+      },
+    },
+  };
+}
+

package/src/index.ts

@@ -1,9 +1,14 @@
 /**
  * React Native Auth - Public API
  * Single source of truth for all Auth operations.
+ *
+ * @module Auth
  */
 
+// =============================================================================
 // DOMAIN LAYER
+// =============================================================================
+
 export type { AuthUser, AuthProviderType } from './domain/entities/AuthUser';
 export {
   AuthError,
@@ -33,7 +38,14 @@ export {
   DEFAULT_SOCIAL_CONFIG,
 } from './domain/value-objects/AuthConfig';
 
+export type { UserProfile, UpdateProfileParams } from './domain/entities/UserProfile';
+export { migrateUserData, configureMigration } from './domain/utils/migration';
+export type { MigrationConfig } from './domain/utils/migration';
+
+// =============================================================================
 // APPLICATION LAYER
+// =============================================================================
+
 export type { IAuthService, SignUpParams, SignInParams } from './application/ports/IAuthService';
 export type {
   IAuthProvider,
@@ -42,7 +54,10 @@ export type {
   SocialSignInResult,
 } from './application/ports/IAuthProvider';
 
+// =============================================================================
 // INFRASTRUCTURE LAYER
+// =============================================================================
+
 export { FirebaseAuthProvider } from './infrastructure/providers/FirebaseAuthProvider';
 export {
   AuthService,
@@ -50,29 +65,33 @@ export {
   getAuthService,
   resetAuthService,
 } from './infrastructure/services/AuthService';
+export type { IStorageProvider } from './infrastructure/types/Storage.types';
 export {
   createStorageProvider,
   StorageProviderAdapter,
 } from './infrastructure/adapters/StorageProviderAdapter';
-export type { IStorageProvider } from './infrastructure/types/Storage.types';
 export {
   ensureUserDocument,
   markUserDeleted,
   configureUserDocumentService,
 } from './infrastructure/services/UserDocumentService';
+export type {
+  UserDocumentConfig,
+  UserDocumentExtras,
+  UserDocumentUser,
+} from './infrastructure/services/UserDocumentService';
+
 export {
   initializeAuth,
   isAuthInitialized,
   resetAuthInitialization,
 } from './infrastructure/services/initializeAuth';
 export type { InitializeAuthOptions } from './infrastructure/services/initializeAuth';
-export type {
-  UserDocumentConfig,
-  UserDocumentExtras,
-  UserDocumentUser,
-} from './infrastructure/services/UserDocumentService';
 
+// =============================================================================
 // VALIDATION
+// =============================================================================
+
 export {
   validateEmail,
   validatePasswordForLogin,
@@ -84,34 +103,8 @@ export type {
   ValidationResult,
   PasswordStrengthResult,
   PasswordRequirements,
-  ValidationConfig,
 } from './infrastructure/utils/AuthValidation';
-export {
-  validateRequired,
-  validatePattern,
-} from './infrastructure/utils/validation/BaseValidators';
-export {
-  validateMinLength,
-  validateMaxLength,
-  validatePhone,
-} from './infrastructure/utils/validation/StringValidators';
-export {
-  validateNumberRange,
-  validatePositiveNumber,
-  validateAge,
-} from './infrastructure/utils/validation/NumberValidators';
-export {
-  calculateAge,
-  validateDateOfBirth,
-  validateDateRange,
-} from './infrastructure/utils/validation/DateValidators';
-export {
-  validateEnum,
-  validateTags,
-} from './infrastructure/utils/validation/CollectionValidators';
-export {
-  batchValidate,
-} from './infrastructure/utils/validation/FormValidators';
+
 export {
   SECURITY_LIMITS,
   sanitizeWhitespace,
@@ -122,117 +115,98 @@ export {
   containsDangerousChars,
   isWithinLengthLimit,
 } from './infrastructure/utils/validation/sanitization';
-export {
-  DEFAULT_VAL_CONFIG,
-} from './infrastructure/utils/AuthValidation';
+export type { SecurityLimitKey } from './infrastructure/utils/validation/sanitization';
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
 
-// PRESENTATION LAYER
-export { AuthProvider } from './presentation/providers/AuthProvider';
 export { useAuth } from './presentation/hooks/useAuth';
 export type { UseAuthResult } from './presentation/hooks/useAuth';
+
 export { useLoginForm } from './presentation/hooks/useLoginForm';
-export type { LoginFormTranslations as UseLoginFormTranslations, UseLoginFormConfig, UseLoginFormResult } from './presentation/hooks/useLoginForm';
+export type { UseLoginFormConfig, UseLoginFormResult } from './presentation/hooks/useLoginForm';
+
 export { useRegisterForm } from './presentation/hooks/useRegisterForm';
-export type { RegisterFormTranslations as UseRegisterFormTranslations, UseRegisterFormConfig, UseRegisterFormResult } from './presentation/hooks/useRegisterForm';
+export type { UseRegisterFormConfig, UseRegisterFormResult } from './presentation/hooks/useRegisterForm';
+
 export { useAuthRequired } from './presentation/hooks/useAuthRequired';
-export type { UseAuthRequiredResult } from './presentation/hooks/useAuthRequired';
 export { useRequireAuth, useUserId } from './presentation/hooks/useRequireAuth';
+
 export { useUserProfile } from './presentation/hooks/useUserProfile';
 export type { UserProfileData, UseUserProfileParams } from './presentation/hooks/useUserProfile';
+
 export { useAccountManagement } from './presentation/hooks/useAccountManagement';
 export type { UseAccountManagementReturn } from './presentation/hooks/useAccountManagement';
+
 export { useProfileUpdate } from './presentation/hooks/useProfileUpdate';
 export type { UseProfileUpdateReturn } from './presentation/hooks/useProfileUpdate';
+
 export { useProfileEdit } from './presentation/hooks/useProfileEdit';
-export type { UseProfileEditReturn, ProfileEditFormState } from './presentation/hooks/useProfileEdit';
+export type { ProfileEditFormState, UseProfileEditReturn } from './presentation/hooks/useProfileEdit';
+
 export { useSocialLogin } from './presentation/hooks/useSocialLogin';
 export type { UseSocialLoginConfig, UseSocialLoginResult } from './presentation/hooks/useSocialLogin';
+
 export { useGoogleAuth } from './presentation/hooks/useGoogleAuth';
-export type { UseGoogleAuthResult, GoogleAuthConfig as GoogleAuthHookConfig } from './presentation/hooks/useGoogleAuth';
+export type { UseGoogleAuthResult } from './presentation/hooks/useGoogleAuth';
+
 export { useAppleAuth } from './presentation/hooks/useAppleAuth';
 export type { UseAppleAuthResult } from './presentation/hooks/useAppleAuth';
+
 export { useAuthBottomSheet } from './presentation/hooks/useAuthBottomSheet';
 export type { SocialAuthConfiguration } from './presentation/hooks/useAuthBottomSheet';
 
-// DOMAIN ENTITIES & UTILS
-export type { UserProfile, UpdateProfileParams } from './domain/entities/UserProfile';
-export { migrateUserData, configureMigration } from './domain/utils/migration';
-export type { MigrationConfig } from './domain/utils/migration';
+// =============================================================================
+// PRESENTATION LAYER - Components
+// =============================================================================
+
+export { AuthProvider } from './presentation/providers/AuthProvider';
+export type { ErrorFallbackProps } from './presentation/providers/AuthProvider';
 
-// SCREENS & NAVIGATION
 export { LoginScreen } from './presentation/screens/LoginScreen';
-export type { LoginScreenTranslations, LoginScreenProps } from './presentation/screens/LoginScreen';
+export type { LoginScreenProps } from './presentation/screens/LoginScreen';
+
 export { RegisterScreen } from './presentation/screens/RegisterScreen';
-export type { RegisterScreenTranslations, RegisterScreenProps } from './presentation/screens/RegisterScreen';
+export type { RegisterScreenProps } from './presentation/screens/RegisterScreen';
+
 export { AccountScreen } from './presentation/screens/AccountScreen';
-export type { AccountScreenConfig, AccountScreenProps } from './presentation/screens/AccountScreen';
+export type { AccountScreenProps } from './presentation/screens/AccountScreen';
+
 export { EditProfileScreen } from './presentation/screens/EditProfileScreen';
-export type { EditProfileConfig, EditProfileScreenProps } from './presentation/screens/EditProfileScreen';
+export type { EditProfileScreenProps } from './presentation/screens/EditProfileScreen';
+
 export { ChangePasswordScreen } from './presentation/screens/change-password';
-export type { ChangePasswordTranslations, ChangePasswordScreenProps } from './presentation/screens/change-password';
+export type { ChangePasswordScreenProps } from './presentation/screens/change-password';
+
 export { AuthNavigator } from './presentation/navigation/AuthNavigator';
-export type {
-  AuthStackParamList,
-  AuthNavigatorTranslations,
-  AuthNavigatorProps,
-} from './presentation/navigation/AuthNavigator';
-
-// COMPONENTS
-export { AuthHeader } from './presentation/components/AuthHeader';
-export type { AuthHeaderProps } from './presentation/components/AuthHeader';
-export { LoginForm } from './presentation/components/LoginForm';
-export type { LoginFormTranslations, LoginFormProps } from './presentation/components/LoginForm';
-export { RegisterForm } from './presentation/components/RegisterForm';
-export type { RegisterFormTranslations, RegisterFormProps } from './presentation/components/RegisterForm';
-export { AuthLegalLinks } from './presentation/components/AuthLegalLinks';
-export type { AuthLegalLinksTranslations, AuthLegalLinksProps } from './presentation/components/AuthLegalLinks';
-export { PasswordStrengthIndicator } from './presentation/components/PasswordStrengthIndicator';
-export type { PasswordStrengthTranslations, PasswordStrengthIndicatorProps } from './presentation/components/PasswordStrengthIndicator';
-export { PasswordMatchIndicator } from './presentation/components/PasswordMatchIndicator';
-export type { PasswordMatchTranslations, PasswordMatchIndicatorProps } from './presentation/components/PasswordMatchIndicator';
-export { AuthBottomSheet } from './presentation/components/AuthBottomSheet';
-export type { AuthBottomSheetTranslations, AuthBottomSheetProps } from './presentation/components/AuthBottomSheet';
-export { SocialLoginButtons } from './presentation/components/SocialLoginButtons';
-export type { SocialLoginButtonsTranslations, SocialLoginButtonsProps } from './presentation/components/SocialLoginButtons';
-export { ProfileSection } from './presentation/components/ProfileSection';
-export type { ProfileSectionConfig, ProfileSectionProps } from './presentation/components/ProfileSection';
-export { AccountActions } from './presentation/components/AccountActions';
-export type { AccountActionsConfig, AccountActionsProps } from './presentation/components/AccountActions';
+export type { AuthStackParamList } from './presentation/navigation/AuthNavigator';
 
+// =============================================================================
 // STORES
-export { useAuthModalStore } from './presentation/stores/authModalStore';
-export type { AuthModalMode } from './presentation/stores/authModalStore';
+// =============================================================================
+
+export { useAuthStore } from './presentation/stores/authStore';
 export {
-  useAuthStore,
   initializeAuthListener,
   resetAuthListener,
   isAuthListenerInitialized,
-  selectIsAuthenticated,
-  selectUserId,
-  selectIsAnonymous,
-  selectUserType,
-  selectIsAuthReady,
-  selectIsRegisteredUser,
-  getUserId,
-  getUserType,
-  getIsAuthenticated,
-  getIsAnonymous,
-  getIsRegisteredUser,
-} from './presentation/stores/authStore';
-export type { UserType, AuthState, AuthActions } from './presentation/stores/authStore';
+} from './presentation/stores/initializeAuthListener';
+export type { AuthState, AuthActions, UserType } from './types/auth-store.types';
 export type { AuthListenerOptions } from './types/auth-store.types';
 
+// =============================================================================
 // UTILITIES
-export { getAuthErrorLocalizationKey, resolveErrorMessage } from './presentation/utils/getAuthErrorMessage';
+// =============================================================================
 
-// App Service Helper (for configureAppServices)
 export {
-  createAuthService,
-  type IAppAuthServiceHelper,
-} from './infrastructure/services/app-service-helpers';
+  getAuthErrorLocalizationKey,
+  resolveErrorMessage,
+} from './presentation/utils/getAuthErrorMessage';
 
-// Init Module Factory
-export {
-  createAuthInitModule,
-  type AuthInitModuleConfig,
-} from './init';
+// =============================================================================
+// INIT MODULE
+// =============================================================================
+
+export { createAuthInitModule } from './init';
+export type { AuthInitModuleConfig } from './init/createAuthInitModule';

package/src/infrastructure/providers/FirebaseAuthProvider.ts

@@ -32,10 +32,11 @@ export class FirebaseAuthProvider implements IAuthProvider {
     }
   }
 
-  async initialize(): Promise<void> {
+  initialize(): Promise<void> {
     if (!this.auth) {
       throw new Error("Firebase Auth instance must be provided");
     }
+    return Promise.resolve();
   }
 
   setAuth(auth: Auth): void {
@@ -130,9 +131,13 @@ export class FirebaseAuthProvider implements IAuthProvider {
             displayName: credentials.displayName.trim(),
           });
         } catch (error) {
-          if (__DEV__) {
-            console.warn("[FirebaseAuthProvider] Failed to update display name:", error);
-          }
+          // Log the error but don't fail the entire sign-up process
+          // The account was created successfully, only the display name update failed
+          const errorMessage = error instanceof Error ? error.message : "Unknown error";
+          console.warn(
+            `[FirebaseAuthProvider] Account created but display name update failed: ${errorMessage}. ` +
+            "User can update their display name later from profile settings."
+          );
         }
       }
 

package/src/infrastructure/repositories/AuthRepository.ts

@@ -36,6 +36,11 @@ export class AuthRepository implements IAuthRepository {
         const password = sanitizePassword(params.password);
         const displayName = params.displayName ? sanitizeName(params.displayName) : undefined;
 
+        // Log if display name was sanitized
+        if (__DEV__ && params.displayName && displayName && params.displayName !== displayName) {
+            console.warn("[AuthRepository] Display name was sanitized during sign up. Original:", params.displayName, "Sanitized:", displayName);
+        }
+
         // Validate email
         const emailResult = validateEmail(email);
         if (!emailResult.isValid) {

package/src/infrastructure/services/AnonymousModeService.ts

@@ -29,25 +29,30 @@ export class AnonymousModeService {
     }
   }
 
-  private async save(storageProvider: IStorageProvider): Promise<void> {
+  private async save(storageProvider: IStorageProvider): Promise<boolean> {
     try {
       await storageProvider.set(this.storageKey, this.isAnonymousMode.toString());
+      return true;
     } catch (err) {
       if (__DEV__) {
         console.error("[AnonymousModeService] Storage save failed:", err);
       }
+      return false;
     }
   }
 
-  async clear(storageProvider: IStorageProvider): Promise<void> {
+  async clear(storageProvider: IStorageProvider): Promise<boolean> {
     try {
       await storageProvider.remove(this.storageKey);
+      this.isAnonymousMode = false;
+      return true;
     } catch (err) {
       if (__DEV__) {
         console.error("[AnonymousModeService] Storage clear failed:", err);
       }
+      this.isAnonymousMode = false;
+      return false;
     }
-    this.isAnonymousMode = false;
   }
 
   async enable(storageProvider: IStorageProvider, provider?: IAuthProvider): Promise<void> {
@@ -63,7 +68,10 @@ export class AnonymousModeService {
     }
 
     this.isAnonymousMode = true;
-    await this.save(storageProvider);
+    const saved = await this.save(storageProvider);
+    if (!saved && __DEV__) {
+      console.warn("[AnonymousModeService] Anonymous mode enabled but not persisted to storage. Mode will be lost on app restart.");
+    }
     emitAnonymousModeEnabled();
   }
 
@@ -79,12 +87,10 @@ export class AnonymousModeService {
     callback: (user: AuthUser | null) => void
   ): (user: AuthUser | null) => void {
     return (user: AuthUser | null) => {
-      // Don't update if in anonymous mode
-      if (!this.isAnonymousMode) {
-        callback(user);
-      } else {
-        callback(null);
-      }
+      // In anonymous mode, still pass the actual Firebase user
+      // The store will handle setting the isAnonymous flag appropriately
+      // This allows proper anonymous to registered user conversion
+      callback(user);
     };
   }
 }

package/src/infrastructure/services/AuthEventService.ts

@@ -98,10 +98,8 @@ export class AuthEventService {
   }
 }
 
-// Export singleton instance for backward compatibility
 export const authEventService = AuthEventService.getInstance();
 
-// Helper functions
 export function emitUserAuthenticated(userId: string): void {
   authEventService.emitUserAuthenticated(userId);
 }

package/src/infrastructure/services/AuthService.ts

@@ -9,7 +9,7 @@ import type { IAuthProvider } from "../../application/ports/IAuthProvider";
 import { FirebaseAuthProvider } from "../providers/FirebaseAuthProvider";
 import type { AuthUser } from "../../domain/entities/AuthUser";
 import type { AuthConfig } from "../../domain/value-objects/AuthConfig";
-import { DEFAULT_AUTH_CONFIG } from "../../domain/value-objects/AuthConfig";
+import { sanitizeAuthConfig } from "../../domain/value-objects/AuthConfig";
 import { AuthRepository } from "../repositories/AuthRepository";
 import { AnonymousModeService } from "./AnonymousModeService";
 import { authEventService } from "./AuthEventService";
@@ -24,11 +24,8 @@ export class AuthService implements IAuthService {
   private config: AuthConfig;
 
   constructor(config: Partial<AuthConfig> = {}, storageProvider?: IStorageProvider) {
-    this.config = {
-      ...DEFAULT_AUTH_CONFIG,
-      ...config,
-      password: { ...DEFAULT_AUTH_CONFIG.password, ...config.password },
-    };
+    // Validate and sanitize configuration
+    this.config = sanitizeAuthConfig(config);
 
     this.anonymousModeService = new AnonymousModeService();
     this.storageProvider = storageProvider;
@@ -45,7 +42,7 @@ export class AuthService implements IAuthService {
     let provider: IAuthProvider;
 
     if ("currentUser" in providerOrAuth) {
-      const firebaseProvider = new FirebaseAuthProvider(providerOrAuth as Auth);
+      const firebaseProvider = new FirebaseAuthProvider(providerOrAuth);
       await firebaseProvider.initialize();
       provider = firebaseProvider;
     } else {
@@ -120,7 +117,10 @@ export class AuthService implements IAuthService {
 
   getCurrentUser(): AuthUser | null {
     if (!this.initialized) return null;
-    return this.anonymousModeService.getIsAnonymousMode() ? null : this.repositoryInstance.getCurrentUser();
+    // Return the actual Firebase user regardless of anonymous mode
+    // The caller should check the user's isAnonymous property if needed
+    // This ensures proper anonymous to registered user conversion
+    return this.repositoryInstance.getCurrentUser();
   }
 
   getIsAnonymousMode(): boolean {

package/src/infrastructure/utils/AuthErrorMapper.ts

@@ -1,6 +1,10 @@
 /**
  * Auth Error Mapper
  * Single Responsibility: Map Firebase Auth errors to domain errors
+ *
+ * @module AuthErrorMapper
+ * @description Provides type-safe error mapping from Firebase Auth errors to
+ * domain-specific error types. Includes runtime validation and type guards.
  */
 
 import {
@@ -14,18 +18,114 @@ import {
   AuthNetworkError,
 } from "../../domain/errors/AuthError";
 
+/**
+ * Firebase Auth error structure
+ * Based on Firebase Auth SDK error format
+ */
+interface FirebaseAuthError {
+  code: string;
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+/**
+ * Type guard to check if error is a valid Firebase Auth error
+ * @param error - Unknown error to check
+ * @returns True if error matches Firebase Auth error structure
+ */
+function isFirebaseAuthError(error: unknown): error is FirebaseAuthError {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const err = error as Partial<FirebaseAuthError>;
+  return (
+    typeof err.code === 'string' &&
+    typeof err.message === 'string' &&
+    err.code.startsWith('auth/')
+  );
+}
+
+/**
+ * Extract error code from error object
+ * @param error - Unknown error
+ * @returns Error code or empty string
+ */
+function extractErrorCode(error: unknown): string {
+  if (isFirebaseAuthError(error)) {
+    return error.code;
+  }
+
+  // Fallback for non-Firebase errors
+  if (error && typeof error === 'object' && 'code' in error) {
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === 'string') {
+      return code;
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Extract error message from error object
+ * @param error - Unknown error
+ * @returns Error message or default message
+ */
+function extractErrorMessage(error: unknown): string {
+  if (isFirebaseAuthError(error)) {
+    return error.message;
+  }
+
+  // Fallback for Error objects
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  // Fallback for objects with message property
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string') {
+      return message;
+    }
+  }
+
+  return "Authentication failed";
+}
+
 /**
  * Map Firebase Auth errors to domain errors
+ *
+ * @param error - Unknown error from Firebase Auth or other sources
+ * @returns Mapped domain error with appropriate error type and message
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await signInWithEmailAndPassword(auth, email, password);
+ * } catch (error) {
+ *   throw mapFirebaseAuthError(error);
+ * }
+ * ```
+ *
+ * @remarks
+ * This function handles:
+ * - Firebase Auth errors with proper code mapping
+ * - Standard JavaScript Error objects
+ * - Unknown error types with safe fallbacks
+ * - Type-safe error extraction using type guards
  */
 export function mapFirebaseAuthError(error: unknown): Error {
+  // Handle null/undefined
   if (!error || typeof error !== 'object') {
     return new AuthError("Authentication failed", "AUTH_UNKNOWN_ERROR");
   }
 
-  const errorObj = error as { code?: string; message?: string };
-  const code = errorObj.code || "";
-  const message = errorObj.message || "Authentication failed";
+  const code = extractErrorCode(error);
+  const message = extractErrorMessage(error);
 
+  // Map known Firebase Auth error codes to domain errors
   switch (code) {
     case "auth/email-already-in-use":
       return new AuthEmailAlreadyInUseError();
@@ -94,7 +194,32 @@ export function mapFirebaseAuthError(error: unknown): Error {
       );
 
     default:
+      // Log unknown errors in development for debugging
+      if (__DEV__ && code) {
+        console.warn(`[AuthErrorMapper] Unknown Firebase Auth code: ${code}`, error);
+      }
       return new AuthError(message, code || "AUTH_UNKNOWN_ERROR");
   }
 }
 
+/**
+ * Check if error is a network-related error
+ * @param error - Error to check
+ * @returns True if error is network-related
+ */
+export function isNetworkError(error: unknown): boolean {
+  return (
+    error instanceof AuthNetworkError ||
+    (error instanceof AuthError && error.code === "auth/network-request-failed")
+  );
+}
+
+/**
+ * Check if error is a configuration-related error
+ * @param error - Error to check
+ * @returns True if error is configuration-related
+ */
+export function isConfigurationError(error: unknown): boolean {
+  return error instanceof AuthConfigurationError;
+}
+

package/src/infrastructure/utils/validation/sanitization.ts

@@ -1,10 +1,39 @@
 /**
  * Sanitization Utilities
  * Secure input cleaning for user data
+ *
+ * @module Sanitization
+ * @description Provides input sanitization functions to prevent XSS attacks,
+ * injection attacks, and ensure data integrity. All user inputs should be
+ * sanitized before storage or processing.
+ *
+ * Security Limits:
+ * These constants define maximum lengths for various input fields to prevent
+ * DoS attacks and ensure database integrity. They are based on industry standards:
+ *
+ * - EMAIL_MAX_LENGTH: 254 (RFC 5321 - maximum email address length)
+ * - PASSWORD_MAX_LENGTH: 128 (NIST recommendations)
+ * - NAME_MAX_LENGTH: 100 (Reasonable limit for display names)
+ * - GENERAL_TEXT_MAX_LENGTH: 500 (Prevents abuse of text fields)
+ *
+ * @note These limits are currently hardcoded for security. If you need to
+ * customize them for your application, you can:
+ * 1. Create your own sanitization functions with custom limits
+ * 2. Use the helper functions like `isWithinLengthLimit()` for validation
+ * 3. Submit a PR to make these limits configurable via AuthConfig
  */
 
 /**
  * Security constants for input validation
+ *
+ * @constant
+ * @type {readonly [key: string]: number}
+ *
+ * @property {number} EMAIL_MAX_LENGTH - Maximum email length per RFC 5321
+ * @property {number} PASSWORD_MIN_LENGTH - Minimum password length (configurable via AuthConfig)
+ * @property {number} PASSWORD_MAX_LENGTH - Maximum password length to prevent DoS
+ * @property {number} NAME_MAX_LENGTH - Maximum display name length
+ * @property {number} GENERAL_TEXT_MAX_LENGTH - Maximum general text input length
  */
 export const SECURITY_LIMITS = {
   EMAIL_MAX_LENGTH: 254, // RFC 5321
@@ -14,6 +43,24 @@ export const SECURITY_LIMITS = {
   GENERAL_TEXT_MAX_LENGTH: 500,
 } as const;
 
+/**
+ * Type for security limit keys
+ */
+export type SecurityLimitKey = keyof typeof SECURITY_LIMITS;
+
+/**
+ * Get a specific security limit value
+ * @param key - The security limit key
+ * @returns The security limit value
+ * @example
+ * ```ts
+ * const maxEmailLength = getSecurityLimit('EMAIL_MAX_LENGTH'); // 254
+ * ```
+ */
+export function getSecurityLimit(key: SecurityLimitKey): number {
+  return SECURITY_LIMITS[key];
+}
+
 /**
  * Trim and normalize whitespace
  */
@@ -34,13 +81,14 @@ export const sanitizeEmail = (email: string): string => {
 
 /**
  * Sanitize password
- * - Only trim (preserve case and special chars)
+ * - Trim leading/trailing whitespace to prevent login issues
+ * - Preserve case and special chars
  * - Limit length to prevent DoS
  */
 export const sanitizePassword = (password: string): string => {
-  // Don't trim password to preserve intentional spaces
-  // Only limit length
-  return password.substring(0, SECURITY_LIMITS.PASSWORD_MAX_LENGTH);
+  // Trim leading/trailing spaces to prevent authentication issues
+  // Internal spaces are preserved for special use cases
+  return password.trim().substring(0, SECURITY_LIMITS.PASSWORD_MAX_LENGTH);
 };
 
 /**

package/src/presentation/hooks/useAuth.ts

@@ -130,11 +130,16 @@ export function useAuth(): UseAuthResult {
   const signOut = useCallback(async () => {
     try {
       setLoading(true);
+      setError(null);
       await signOutMutation.mutateAsync();
+    } catch (err: unknown) {
+      const errorMessage = err instanceof Error ? err.message : "Sign out failed";
+      setError(errorMessage);
+      throw err;
     } finally {
       setLoading(false);
     }
-  }, [setLoading, signOutMutation]);
+  }, [setLoading, setError, signOutMutation]);
 
   const continueAnonymously = useCallback(async () => {
     try {

package/src/presentation/hooks/useProfileUpdate.ts

@@ -27,8 +27,7 @@ export const useProfileUpdate = (): UseProfileUpdateReturn => {
                 return Promise.reject(new Error("Anonymous users cannot update profile"));
             }
 
-            // Note: App should implement this via Firebase SDK
-            return Promise.reject(new Error("Profile update should be implemented by app"));
+            return Promise.reject(new Error("Profile update not implemented - use Firebase SDK directly"));
         },
         [user],
     );

package/src/presentation/providers/AuthProvider.tsx

@@ -10,23 +10,88 @@
  * ```
  */
 
-import { useEffect, type ReactNode } from "react";
-import { initializeAuthListener } from "../stores/authStore";
+import { useEffect, useState, type ReactNode } from "react";
+import { View, Text } from "react-native";
+import { initializeAuthListener } from "../stores/initializeAuthListener";
 
-interface AuthProviderProps {
+export interface AuthProviderProps {
   children: ReactNode;
+  /**
+   * Custom error component to display when auth initialization fails
+   */
+  ErrorFallback?: React.ComponentType<{ error: Error; retry: () => void }>;
+}
+
+export interface ErrorFallbackProps {
+  error: Error;
+  retry: () => void;
+}
+
+/**
+ * Default error fallback component
+ */
+function DefaultErrorFallback({ error, retry }: { error: Error; retry: () => void }) {
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 20 }}>
+      <Text style={{ fontSize: 18, fontWeight: "bold", marginBottom: 10 }}>
+        Authentication Error
+      </Text>
+      <Text style={{ fontSize: 14, textAlign: "center", marginBottom: 20 }}>
+        {error.message || "Failed to initialize authentication. Please restart the app."}
+      </Text>
+      <Text
+        style={{ fontSize: 14, color: "#007AFF" }}
+        onPress={retry}
+      >
+        Retry
+      </Text>
+    </View>
+  );
 }
 
 /**
  * AuthProvider component
  * Initializes Firebase auth listener on mount
  * Must wrap the app root
+ * Includes error boundary for graceful error handling
  */
-export function AuthProvider({ children }: AuthProviderProps): ReactNode {
+export function AuthProvider({ children, ErrorFallback = DefaultErrorFallback }: AuthProviderProps): ReactNode {
+  const [error, setError] = useState<Error | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+
   useEffect(() => {
-    const unsubscribe = initializeAuthListener();
-    return unsubscribe;
-  }, []);
+    let unsubscribe: (() => void) | undefined;
+
+    try {
+      unsubscribe = initializeAuthListener();
+    } catch (err) {
+      const errorObj = err instanceof Error ? err : new Error("Unknown initialization error");
+      if (__DEV__) {
+        console.error("[AuthProvider] Initialization failed:", errorObj);
+      }
+      setError(errorObj);
+    }
+
+    return () => {
+      if (unsubscribe) {
+        try {
+          unsubscribe();
+        } catch (cleanupError) {
+          if (__DEV__) {
+            console.warn("[AuthProvider] Cleanup failed:", cleanupError);
+          }
+        }
+      }
+    };
+  }, [retryCount]); // Re-run on retry
+
+  // If error occurred, show error fallback
+  if (error) {
+    return <ErrorFallback error={error} retry={() => {
+      setError(null);
+      setRetryCount(prev => prev + 1);
+    }} />;
+  }
 
   return <>{children}</>;
 }

package/src/presentation/stores/authStore.ts

@@ -18,30 +18,9 @@ import {
   selectIsAuthenticated,
   selectIsAnonymous,
   selectUserType,
-  selectIsAuthReady,
   selectIsRegisteredUser,
 } from "./auth.selectors";
 
-// Re-export public selectors (consumed by index.ts)
-export {
-  selectUserId,
-  selectIsAuthenticated,
-  selectIsAnonymous,
-  selectUserType,
-  selectIsAuthReady,
-  selectIsRegisteredUser,
-};
-
-// Re-export public types (consumed by index.ts)
-export type { AuthState, AuthActions, UserType };
-
-// Re-export listener functions (consumed by index.ts)
-export {
-  initializeAuthListener,
-  resetAuthListener,
-  isAuthListenerInitialized,
-} from "./initializeAuthListener";
-
 // =============================================================================
 // STORE
 // =============================================================================
@@ -96,9 +75,10 @@ export const useAuthStore = createStore<AuthState, AuthActions>({
       if (__DEV__) {
         console.log("[AuthStore] setIsAnonymous:", { isAnonymous, hadUser: !!user });
       }
-      // Also update user.isAnonymous when converting from anonymous
-      if (user && !isAnonymous && user.isAnonymous) {
-        set({ isAnonymous, user: { ...user, isAnonymous: false } });
+      // Update user.isAnonymous flag to match the new state
+      // This handles both anonymous → registered and registered → anonymous conversions
+      if (user && user.isAnonymous !== isAnonymous) {
+        set({ isAnonymous, user: { ...user, isAnonymous } });
       } else {
         set({ isAnonymous });
       }

package/src/presentation/stores/initializeAuthListener.ts

@@ -15,11 +15,10 @@ import type { AuthListenerOptions } from "../../types/auth-store.types";
 
 const MAX_ANONYMOUS_RETRIES = 2;
 const ANONYMOUS_RETRY_DELAY_MS = 1000;
+const ANONYMOUS_SIGNIN_TIMEOUT_MS = 10000;
 
 let listenerInitialized = false;
-// Reference counter for multiple subscribers
 let listenerRefCount = 0;
-// Actual unsubscribe function from Firebase
 let firebaseUnsubscribe: (() => void) | null = null;
 
 /**
@@ -75,20 +74,24 @@ export function initializeAuthListener(
     return () => {};
   }
 
+  listenerInitialized = true;
+  listenerRefCount = 1;
+
+  // Initialize listener first, then check anonymous mode
+  // This prevents race conditions where the listener fires before we set up state
   const service = getAuthService();
   if (service) {
     const isAnonymous = service.getIsAnonymousMode();
     if (__DEV__) {
       console.log("[AuthListener] Service isAnonymousMode:", isAnonymous);
     }
+    // Set anonymous mode flag before setting up listener
+    // This ensures consistent state when listener first fires
     if (isAnonymous) {
       store.setIsAnonymous(true);
     }
   }
 
-  listenerInitialized = true;
-  listenerRefCount = 1;
-
   firebaseUnsubscribe = onIdTokenChanged(auth, (user) => {
     if (__DEV__) {
       console.log("[AuthListener] onIdTokenChanged:", {
@@ -106,36 +109,60 @@ export function initializeAuthListener(
       // Set loading state while attempting sign-in
       store.setLoading(true);
 
+      // Start anonymous sign-in process
+      // Don't return early - let the listener continue to handle state changes
       void (async () => {
-        for (let attempt = 0; attempt <= MAX_ANONYMOUS_RETRIES; attempt++) {
-          try {
-            await anonymousAuthService.signInAnonymously(auth);
-            if (__DEV__) {
-              console.log("[AuthListener] Anonymous sign-in successful");
-            }
-            // Success - the listener will fire again with the new user
-            return;
-          } catch (error) {
-            if (__DEV__) {
-              console.warn(`[AuthListener] Anonymous sign-in attempt ${attempt + 1} failed:`, error);
-            }
-
-            // If not last attempt, wait and retry
-            if (attempt < MAX_ANONYMOUS_RETRIES) {
-              await new Promise(resolve => setTimeout(resolve, ANONYMOUS_RETRY_DELAY_MS));
-              continue;
-            }
-
-            // Last attempt failed - set error state
-            if (__DEV__) {
-              console.error("[AuthListener] All anonymous sign-in attempts failed");
-            }
-            store.setFirebaseUser(null);
-            store.setLoading(false);
-            store.setInitialized(true);
+        // Add timeout protection
+        const timeoutPromise = new Promise((_, reject) =>
+          setTimeout(() => reject(new Error("Anonymous sign-in timeout")), ANONYMOUS_SIGNIN_TIMEOUT_MS)
+        );
+
+        try {
+          // Race between sign-in and timeout
+          await Promise.race([
+            (async () => {
+              for (let attempt = 0; attempt < MAX_ANONYMOUS_RETRIES; attempt++) {
+                try {
+                  await anonymousAuthService.signInAnonymously(auth);
+                  if (__DEV__) {
+                    console.log("[AuthListener] Anonymous sign-in successful");
+                  }
+                  // Success - the listener will fire again with the new user
+                  return;
+                } catch (error) {
+                  if (__DEV__) {
+                    console.warn(`[AuthListener] Anonymous sign-in attempt ${attempt + 1} failed:`, error);
+                  }
+
+                  // If not last attempt, wait and retry
+                  if (attempt < MAX_ANONYMOUS_RETRIES - 1) {
+                    await new Promise(resolve => setTimeout(resolve, ANONYMOUS_RETRY_DELAY_MS));
+                    continue;
+                  }
+
+                  // All attempts failed
+                  throw error;
+                }
+              }
+            })(),
+            timeoutPromise,
+          ]);
+        } catch (error) {
+          // All attempts failed or timeout - set error state
+          if (__DEV__) {
+            console.error("[AuthListener] All anonymous sign-in attempts failed:", error);
           }
+          store.setFirebaseUser(null);
+          store.setLoading(false);
+          store.setInitialized(true);
+          store.setError("Failed to sign in anonymously. Please check your connection.");
         }
       })();
+
+      // Continue execution - don't return early
+      // The listener will be triggered again when sign-in succeeds
+      // For now, set null user and let loading state indicate in-progress
+      store.setFirebaseUser(null);
       return;
     }