@umituz/react-native-auth 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Ümit UZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,216 @@
+# @umituz/react-native-auth
+
+Firebase Authentication wrapper for React Native apps - Secure, type-safe, and production-ready.
+
+Built with **SOLID**, **DRY**, and **KISS** principles.
+
+## Installation
+
+```bash
+npm install @umituz/react-native-auth
+```
+
+## Peer Dependencies
+
+- `firebase` >= 11.0.0
+- `react` >= 18.2.0
+- `react-native` >= 0.74.0
+
+## Features
+
+- ✅ Domain-Driven Design (DDD) architecture
+- ✅ SOLID principles (Single Responsibility, Open/Closed, etc.)
+- ✅ DRY (Don't Repeat Yourself)
+- ✅ KISS (Keep It Simple, Stupid)
+- ✅ **Security**: Password validation, email validation, error handling
+- ✅ Type-safe operations
+- ✅ Guest mode support
+- ✅ React hooks for easy integration
+- ✅ Works with Expo and React Native CLI
+
+## Important: Security First
+
+**This package prioritizes security:**
+
+- Password strength validation
+- Email format validation
+- Secure error handling (no sensitive data exposure)
+- Firebase Auth best practices
+- Guest mode support for offline-first apps
+
+## Usage
+
+### 1. Initialize Auth Service
+
+Initialize the service early in your app (e.g., in `App.tsx`):
+
+```typescript
+import { initializeAuthService } from '@umituz/react-native-auth';
+import { getFirebaseAuth } from '@umituz/react-native-firebase';
+
+// Initialize Firebase first (using @umituz/react-native-firebase)
+const auth = getFirebaseAuth();
+
+// Initialize auth service
+initializeAuthService(auth, {
+  minPasswordLength: 6,
+  requireUppercase: false,
+  requireLowercase: false,
+  requireNumbers: false,
+  requireSpecialChars: false,
+  onUserCreated: async (user) => {
+    // Optional: Create user profile in your database
+    console.log('User created:', user.uid);
+  },
+  onSignOut: async () => {
+    // Optional: Cleanup on sign out
+    console.log('User signed out');
+  },
+});
+```
+
+### 2. Use Auth Hook in Components
+
+```typescript
+import { useAuth } from '@umituz/react-native-auth';
+
+function LoginScreen() {
+  const { user, isAuthenticated, isGuest, loading, signIn, signUp, signOut, continueAsGuest } = useAuth();
+
+  if (loading) {
+    return <LoadingSpinner />;
+  }
+
+  if (isAuthenticated) {
+    return <HomeScreen user={user} />;
+  }
+
+  if (isGuest) {
+    return <GuestHomeScreen />;
+  }
+
+  return <LoginForm onSignIn={signIn} onSignUp={signUp} onContinueAsGuest={continueAsGuest} />;
+}
+```
+
+### 3. Sign Up
+
+```typescript
+import { getAuthService } from '@umituz/react-native-auth';
+
+const authService = getAuthService();
+
+try {
+  const user = await authService.signUp({
+    email: 'user@example.com',
+    password: 'securepassword123',
+    displayName: 'John Doe',
+  });
+  console.log('User signed up:', user.uid);
+} catch (error) {
+  if (error instanceof AuthEmailAlreadyInUseError) {
+    console.error('Email already in use');
+  } else if (error instanceof AuthWeakPasswordError) {
+    console.error('Password is too weak');
+  } else {
+    console.error('Sign up failed:', error.message);
+  }
+}
+```
+
+### 4. Sign In
+
+```typescript
+try {
+  const user = await authService.signIn({
+    email: 'user@example.com',
+    password: 'securepassword123',
+  });
+  console.log('User signed in:', user.uid);
+} catch (error) {
+  if (error instanceof AuthWrongPasswordError) {
+    console.error('Wrong password');
+  } else if (error instanceof AuthUserNotFoundError) {
+    console.error('User not found');
+  } else {
+    console.error('Sign in failed:', error.message);
+  }
+}
+```
+
+### 5. Sign Out
+
+```typescript
+await authService.signOut();
+```
+
+### 6. Guest Mode
+
+```typescript
+await authService.setGuestMode();
+```
+
+## API
+
+### Functions
+
+- `initializeAuthService(auth, config?)`: Initialize auth service with Firebase Auth instance
+- `getAuthService()`: Get auth service instance (throws if not initialized)
+- `resetAuthService()`: Reset service instance (useful for testing)
+
+### Hook
+
+- `useAuth()`: React hook for authentication state management
+
+### Types
+
+- `AuthConfig`: Configuration interface
+- `SignUpParams`: Sign up parameters
+- `SignInParams`: Sign in parameters
+- `UseAuthResult`: Hook return type
+
+### Errors
+
+- `AuthError`: Base error class
+- `AuthInitializationError`: Initialization errors
+- `AuthConfigurationError`: Configuration errors
+- `AuthValidationError`: Validation errors
+- `AuthNetworkError`: Network errors
+- `AuthUserNotFoundError`: User not found
+- `AuthWrongPasswordError`: Wrong password
+- `AuthEmailAlreadyInUseError`: Email already in use
+- `AuthWeakPasswordError`: Weak password
+- `AuthInvalidEmailError`: Invalid email
+
+## Security Best Practices
+
+1. **Password Validation**: Configure password requirements based on your app's security needs
+2. **Error Handling**: Always handle errors gracefully without exposing sensitive information
+3. **Guest Mode**: Use guest mode for offline-first apps that don't require authentication
+4. **User Callbacks**: Use `onUserCreated` and `onSignOut` callbacks for app-specific logic
+
+## Integration with @umituz/react-native-firebase
+
+This package works seamlessly with `@umituz/react-native-firebase`:
+
+```typescript
+import { initializeFirebase, getFirebaseAuth } from '@umituz/react-native-firebase';
+import { initializeAuthService } from '@umituz/react-native-auth';
+
+// Initialize Firebase
+const config = {
+  apiKey: 'your-api-key',
+  authDomain: 'your-project.firebaseapp.com',
+  projectId: 'your-project-id',
+};
+initializeFirebase(config);
+
+// Initialize Auth Service
+const auth = getFirebaseAuth();
+initializeAuthService(auth);
+```
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@umituz/react-native-auth",
+  "version": "1.0.0",
+  "description": "Firebase Authentication wrapper for React Native apps - Secure, type-safe, and production-ready",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "firebase",
+    "authentication",
+    "auth",
+    "security",
+    "ddd",
+    "domain-driven-design",
+    "type-safe",
+    "solid",
+    "dry",
+    "kiss"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/react-native-auth.git"
+  },
+  "peerDependencies": {
+    "firebase": ">=11.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "firebase": "^11.10.0",
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}
+

package/src/application/ports/IAuthService.ts

@@ -0,0 +1,55 @@
+/**
+ * Auth Service Interface
+ * Port for authentication operations
+ */
+
+import type { User } from "firebase/auth";
+
+export interface SignUpParams {
+  email: string;
+  password: string;
+  displayName?: string;
+}
+
+export interface SignInParams {
+  email: string;
+  password: string;
+}
+
+export interface IAuthService {
+  /**
+   * Sign up a new user
+   */
+  signUp(params: SignUpParams): Promise<User>;
+
+  /**
+   * Sign in an existing user
+   */
+  signIn(params: SignInParams): Promise<User>;
+
+  /**
+   * Sign out current user
+   */
+  signOut(): Promise<void>;
+
+  /**
+   * Set guest mode (no authentication)
+   */
+  setGuestMode(): Promise<void>;
+
+  /**
+   * Get current authenticated user
+   */
+  getCurrentUser(): User | null;
+
+  /**
+   * Subscribe to auth state changes
+   */
+  onAuthStateChange(callback: (user: User | null) => void): () => void;
+
+  /**
+   * Check if auth is initialized
+   */
+  isInitialized(): boolean;
+}
+

package/src/domain/errors/AuthError.ts

@@ -0,0 +1,85 @@
+/**
+ * Auth Error Types
+ * Domain-specific error classes for authentication operations
+ */
+
+export class AuthError extends Error {
+  constructor(message: string, public code?: string) {
+    super(message);
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, AuthError.prototype);
+  }
+}
+
+export class AuthInitializationError extends AuthError {
+  constructor(message: string = "Firebase Auth is not initialized") {
+    super(message, "AUTH_NOT_INITIALIZED");
+    this.name = "AuthInitializationError";
+    Object.setPrototypeOf(this, AuthInitializationError.prototype);
+  }
+}
+
+export class AuthConfigurationError extends AuthError {
+  constructor(message: string = "Invalid auth configuration") {
+    super(message, "AUTH_CONFIG_ERROR");
+    this.name = "AuthConfigurationError";
+    Object.setPrototypeOf(this, AuthConfigurationError.prototype);
+  }
+}
+
+export class AuthValidationError extends AuthError {
+  constructor(message: string, public field?: string) {
+    super(message, "AUTH_VALIDATION_ERROR");
+    this.name = "AuthValidationError";
+    Object.setPrototypeOf(this, AuthValidationError.prototype);
+  }
+}
+
+export class AuthNetworkError extends AuthError {
+  constructor(message: string = "Network error during authentication") {
+    super(message, "AUTH_NETWORK_ERROR");
+    this.name = "AuthNetworkError";
+    Object.setPrototypeOf(this, AuthNetworkError.prototype);
+  }
+}
+
+export class AuthUserNotFoundError extends AuthError {
+  constructor(message: string = "User not found") {
+    super(message, "AUTH_USER_NOT_FOUND");
+    this.name = "AuthUserNotFoundError";
+    Object.setPrototypeOf(this, AuthUserNotFoundError.prototype);
+  }
+}
+
+export class AuthWrongPasswordError extends AuthError {
+  constructor(message: string = "Wrong password") {
+    super(message, "AUTH_WRONG_PASSWORD");
+    this.name = "AuthWrongPasswordError";
+    Object.setPrototypeOf(this, AuthWrongPasswordError.prototype);
+  }
+}
+
+export class AuthEmailAlreadyInUseError extends AuthError {
+  constructor(message: string = "Email already in use") {
+    super(message, "AUTH_EMAIL_ALREADY_IN_USE");
+    this.name = "AuthEmailAlreadyInUseError";
+    Object.setPrototypeOf(this, AuthEmailAlreadyInUseError.prototype);
+  }
+}
+
+export class AuthWeakPasswordError extends AuthError {
+  constructor(message: string = "Password is too weak") {
+    super(message, "AUTH_WEAK_PASSWORD");
+    this.name = "AuthWeakPasswordError";
+    Object.setPrototypeOf(this, AuthWeakPasswordError.prototype);
+  }
+}
+
+export class AuthInvalidEmailError extends AuthError {
+  constructor(message: string = "Invalid email address") {
+    super(message, "AUTH_INVALID_EMAIL");
+    this.name = "AuthInvalidEmailError";
+    Object.setPrototypeOf(this, AuthInvalidEmailError.prototype);
+  }
+}
+

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

@@ -0,0 +1,32 @@
+/**
+ * Auth Configuration Value Object
+ * Validates and stores authentication configuration
+ */
+
+export interface AuthConfig {
+  /** Minimum password length (default: 6) */
+  minPasswordLength?: number;
+  /** Require uppercase letters in password */
+  requireUppercase?: boolean;
+  /** Require lowercase letters in password */
+  requireLowercase?: boolean;
+  /** Require numbers in password */
+  requireNumbers?: boolean;
+  /** Require special characters in password */
+  requireSpecialChars?: boolean;
+  /** Callback for user profile creation after signup */
+  onUserCreated?: (user: any) => Promise<void> | void;
+  /** Callback for user profile update */
+  onUserUpdated?: (user: any) => Promise<void> | void;
+  /** Callback for sign out cleanup */
+  onSignOut?: () => Promise<void> | void;
+}
+
+export const DEFAULT_AUTH_CONFIG: Required<Omit<AuthConfig, 'onUserCreated' | 'onUserUpdated' | 'onSignOut'>> = {
+  minPasswordLength: 6,
+  requireUppercase: false,
+  requireLowercase: false,
+  requireNumbers: false,
+  requireSpecialChars: false,
+};
+

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * React Native Auth - Public API
+ *
+ * Domain-Driven Design (DDD) Architecture
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all Auth operations.
+ * ALL imports from the Auth package MUST go through this file.
+ *
+ * Architecture:
+ * - domain: Entities, value objects, errors (business logic)
+ * - application: Ports (interfaces)
+ * - infrastructure: Auth service implementation
+ * - presentation: Hooks (React integration)
+ *
+ * Usage:
+ *   import { initializeAuthService, useAuth } from '@umituz/react-native-auth';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Business Logic
+// =============================================================================
+
+export {
+  AuthError,
+  AuthInitializationError,
+  AuthConfigurationError,
+  AuthValidationError,
+  AuthNetworkError,
+  AuthUserNotFoundError,
+  AuthWrongPasswordError,
+  AuthEmailAlreadyInUseError,
+  AuthWeakPasswordError,
+  AuthInvalidEmailError,
+} from './domain/errors/AuthError';
+
+export type { AuthConfig } from './domain/value-objects/AuthConfig';
+export { DEFAULT_AUTH_CONFIG } from './domain/value-objects/AuthConfig';
+
+// =============================================================================
+// APPLICATION LAYER - Ports
+// =============================================================================
+
+export type { IAuthService, SignUpParams, SignInParams } from './application/ports/IAuthService';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Implementation
+// =============================================================================
+
+export {
+  AuthService,
+  initializeAuthService,
+  getAuthService,
+  resetAuthService,
+} from './infrastructure/services/AuthService';
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export { useAuth } from './presentation/hooks/useAuth';
+export type { UseAuthResult } from './presentation/hooks/useAuth';
+

package/src/infrastructure/services/AuthService.ts

@@ -0,0 +1,353 @@
+/**
+ * Auth Service Implementation
+ * Secure Firebase Authentication wrapper
+ */
+
+import {
+  createUserWithEmailAndPassword,
+  signInWithEmailAndPassword,
+  signOut as firebaseSignOut,
+  onAuthStateChanged,
+  updateProfile,
+  type User,
+  type Auth,
+} from "firebase/auth";
+import type { IAuthService, SignUpParams, SignInParams } from "../application/ports/IAuthService";
+import {
+  AuthInitializationError,
+  AuthValidationError,
+  AuthWeakPasswordError,
+  AuthInvalidEmailError,
+  AuthEmailAlreadyInUseError,
+  AuthWrongPasswordError,
+  AuthUserNotFoundError,
+  AuthNetworkError,
+} from "../domain/errors/AuthError";
+import type { AuthConfig } from "../domain/value-objects/AuthConfig";
+import { DEFAULT_AUTH_CONFIG } from "../domain/value-objects/AuthConfig";
+
+/**
+ * Validate email format
+ */
+function validateEmail(email: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email.trim());
+}
+
+/**
+ * Validate password strength
+ */
+function validatePassword(
+  password: string,
+  config: Required<Omit<AuthConfig, "onUserCreated" | "onUserUpdated" | "onSignOut">>
+): { valid: boolean; error?: string } {
+  if (password.length < config.minPasswordLength) {
+    return {
+      valid: false,
+      error: `Password must be at least ${config.minPasswordLength} characters long`,
+    };
+  }
+
+  if (config.requireUppercase && !/[A-Z]/.test(password)) {
+    return {
+      valid: false,
+      error: "Password must contain at least one uppercase letter",
+    };
+  }
+
+  if (config.requireLowercase && !/[a-z]/.test(password)) {
+    return {
+      valid: false,
+      error: "Password must contain at least one lowercase letter",
+    };
+  }
+
+  if (config.requireNumbers && !/[0-9]/.test(password)) {
+    return {
+      valid: false,
+      error: "Password must contain at least one number",
+    };
+  }
+
+  if (config.requireSpecialChars && !/[!@#$%^&*(),.?":{}|<>]/.test(password)) {
+    return {
+      valid: false,
+      error: "Password must contain at least one special character",
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Map Firebase Auth errors to domain errors
+ */
+function mapFirebaseAuthError(error: any): Error {
+  const code = error?.code || "";
+  const message = error?.message || "Authentication failed";
+
+  // Firebase Auth error codes
+  if (code === "auth/email-already-in-use") {
+    return new AuthEmailAlreadyInUseError();
+  }
+  if (code === "auth/invalid-email") {
+    return new AuthInvalidEmailError();
+  }
+  if (code === "auth/operation-not-allowed") {
+    return new AuthConfigurationError("Email/password authentication is not enabled");
+  }
+  if (code === "auth/weak-password") {
+    return new AuthWeakPasswordError();
+  }
+  if (code === "auth/user-disabled") {
+    return new AuthError("User account has been disabled", "AUTH_USER_DISABLED");
+  }
+  if (code === "auth/user-not-found") {
+    return new AuthUserNotFoundError();
+  }
+  if (code === "auth/wrong-password") {
+    return new AuthWrongPasswordError();
+  }
+  if (code === "auth/network-request-failed") {
+    return new AuthNetworkError();
+  }
+  if (code === "auth/too-many-requests") {
+    return new AuthError("Too many requests. Please try again later.", "AUTH_TOO_MANY_REQUESTS");
+  }
+
+  return new AuthError(message, code);
+}
+
+export class AuthService implements IAuthService {
+  private auth: Auth | null = null;
+  private config: AuthConfig;
+  private isGuestMode: boolean = false;
+
+  constructor(config: AuthConfig = {}) {
+    this.config = { ...DEFAULT_AUTH_CONFIG, ...config };
+  }
+
+  /**
+   * Initialize auth service with Firebase Auth instance
+   * Must be called before using any auth methods
+   */
+  initialize(auth: Auth): void {
+    if (!auth) {
+      throw new AuthInitializationError("Auth instance is required");
+    }
+    this.auth = auth;
+    this.isGuestMode = false;
+  }
+
+  /**
+   * Check if auth is initialized
+   */
+  isInitialized(): boolean {
+    return this.auth !== null;
+  }
+
+  private getAuth(): Auth {
+    if (!this.auth) {
+      throw new AuthInitializationError();
+    }
+    return this.auth;
+  }
+
+  /**
+   * Sign up a new user
+   */
+  async signUp(params: SignUpParams): Promise<User> {
+    const auth = this.getAuth();
+
+    // Validate email
+    if (!params.email || !validateEmail(params.email)) {
+      throw new AuthInvalidEmailError();
+    }
+
+    // Validate password
+    const passwordValidation = validatePassword(params.password, this.config as any);
+    if (!passwordValidation.valid) {
+      throw new AuthWeakPasswordError(passwordValidation.error);
+    }
+
+    try {
+      // Create user
+      const userCredential = await createUserWithEmailAndPassword(
+        auth,
+        params.email.trim(),
+        params.password
+      );
+
+      // Update display name if provided
+      if (params.displayName && userCredential.user) {
+        try {
+          await updateProfile(userCredential.user, {
+            displayName: params.displayName.trim(),
+          });
+        } catch (updateError) {
+          // Don't fail signup if display name update fails
+          // User can still use the app
+        }
+      }
+
+      // Call user created callback if provided
+      if (this.config.onUserCreated) {
+        try {
+          await this.config.onUserCreated(userCredential.user);
+        } catch (callbackError) {
+          // Don't fail signup if callback fails
+        }
+      }
+
+      return userCredential.user;
+    } catch (error: any) {
+      throw mapFirebaseAuthError(error);
+    }
+  }
+
+  /**
+   * Sign in an existing user
+   */
+  async signIn(params: SignInParams): Promise<User> {
+    const auth = this.getAuth();
+
+    // Validate email
+    if (!params.email || !validateEmail(params.email)) {
+      throw new AuthInvalidEmailError();
+    }
+
+    // Validate password
+    if (!params.password || params.password.length === 0) {
+      throw new AuthValidationError("Password is required", "password");
+    }
+
+    try {
+      const userCredential = await signInWithEmailAndPassword(
+        auth,
+        params.email.trim(),
+        params.password
+      );
+
+      this.isGuestMode = false;
+      return userCredential.user;
+    } catch (error: any) {
+      throw mapFirebaseAuthError(error);
+    }
+  }
+
+  /**
+   * Sign out current user
+   */
+  async signOut(): Promise<void> {
+    const auth = this.getAuth();
+
+    try {
+      await firebaseSignOut(auth);
+      this.isGuestMode = false;
+
+      // Call sign out callback if provided
+      if (this.config.onSignOut) {
+        try {
+          await this.config.onSignOut();
+        } catch (callbackError) {
+          // Don't fail signout if callback fails
+        }
+      }
+    } catch (error: any) {
+      throw mapFirebaseAuthError(error);
+    }
+  }
+
+  /**
+   * Set guest mode (no authentication)
+   */
+  async setGuestMode(): Promise<void> {
+    const auth = this.getAuth();
+
+    // Sign out from Firebase if logged in
+    if (auth.currentUser) {
+      try {
+        await firebaseSignOut(auth);
+      } catch (error) {
+        // Ignore sign out errors when switching to guest mode
+      }
+    }
+
+    this.isGuestMode = true;
+  }
+
+  /**
+   * Get current authenticated user
+   */
+  getCurrentUser(): User | null {
+    if (!this.auth) {
+      return null;
+    }
+    return this.auth.currentUser;
+  }
+
+  /**
+   * Check if user is in guest mode
+   */
+  getIsGuestMode(): boolean {
+    return this.isGuestMode;
+  }
+
+  /**
+   * Subscribe to auth state changes
+   */
+  onAuthStateChange(callback: (user: User | null) => void): () => void {
+    const auth = this.getAuth();
+
+    return onAuthStateChanged(auth, (user) => {
+      // Don't update if in guest mode
+      if (!this.isGuestMode) {
+        callback(user);
+      } else {
+        callback(null);
+      }
+    });
+  }
+}
+
+/**
+ * Singleton instance
+ * Apps should use initializeAuthService() to set up with their Firebase Auth instance
+ */
+let authServiceInstance: AuthService | null = null;
+
+/**
+ * Initialize auth service with Firebase Auth instance
+ * Must be called before using any auth methods
+ */
+export function initializeAuthService(
+  auth: Auth,
+  config?: AuthConfig
+): AuthService {
+  if (!authServiceInstance) {
+    authServiceInstance = new AuthService(config);
+  }
+  authServiceInstance.initialize(auth);
+  return authServiceInstance;
+}
+
+/**
+ * Get auth service instance
+ * @throws {AuthInitializationError} If service is not initialized
+ */
+export function getAuthService(): AuthService {
+  if (!authServiceInstance || !authServiceInstance.isInitialized()) {
+    throw new AuthInitializationError(
+      "Auth service is not initialized. Call initializeAuthService() first."
+    );
+  }
+  return authServiceInstance;
+}
+
+/**
+ * Reset auth service (useful for testing)
+ */
+export function resetAuthService(): void {
+  authServiceInstance = null;
+}
+

package/src/presentation/hooks/useAuth.ts

@@ -0,0 +1,106 @@
+/**
+ * useAuth Hook
+ * React hook for authentication state management
+ */
+
+import { useEffect, useState, useCallback } from "react";
+import type { User } from "firebase/auth";
+import { getAuthService } from "../infrastructure/services/AuthService";
+
+export interface UseAuthResult {
+  /** Current authenticated user */
+  user: User | null;
+  /** Whether auth state is loading */
+  loading: boolean;
+  /** Whether user is in guest mode */
+  isGuest: boolean;
+  /** Whether user is authenticated */
+  isAuthenticated: boolean;
+  /** Sign up function */
+  signUp: (email: string, password: string, displayName?: string) => Promise<void>;
+  /** Sign in function */
+  signIn: (email: string, password: string) => Promise<void>;
+  /** Sign out function */
+  signOut: () => Promise<void>;
+  /** Continue as guest function */
+  continueAsGuest: () => Promise<void>;
+}
+
+/**
+ * Hook for authentication state management
+ * 
+ * @example
+ * ```typescript
+ * const { user, isAuthenticated, signIn, signUp, signOut } = useAuth();
+ * ```
+ */
+export function useAuth(): UseAuthResult {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [isGuest, setIsGuest] = useState(false);
+
+  useEffect(() => {
+    try {
+      const service = getAuthService();
+      const unsubscribe = service.onAuthStateChange((currentUser) => {
+        setUser(currentUser);
+        setIsGuest(service.getIsGuestMode());
+        setLoading(false);
+      });
+
+      // Set initial state
+      const currentUser = service.getCurrentUser();
+      setUser(currentUser);
+      setIsGuest(service.getIsGuestMode());
+      setLoading(false);
+
+      return () => {
+        unsubscribe();
+      };
+    } catch (error) {
+      // Auth service not initialized
+      setUser(null);
+      setIsGuest(false);
+      setLoading(false);
+      return () => {};
+    }
+  }, []);
+
+  const signUp = useCallback(async (email: string, password: string, displayName?: string) => {
+    const service = getAuthService();
+    await service.signUp({ email, password, displayName });
+    // State will be updated via onAuthStateChange
+  }, []);
+
+  const signIn = useCallback(async (email: string, password: string) => {
+    const service = getAuthService();
+    await service.signIn({ email, password });
+    // State will be updated via onAuthStateChange
+  }, []);
+
+  const signOut = useCallback(async () => {
+    const service = getAuthService();
+    await service.signOut();
+    setUser(null);
+    setIsGuest(false);
+  }, []);
+
+  const continueAsGuest = useCallback(async () => {
+    const service = getAuthService();
+    await service.setGuestMode();
+    setUser(null);
+    setIsGuest(true);
+  }, []);
+
+  return {
+    user,
+    loading,
+    isGuest,
+    isAuthenticated: !!user && !isGuest,
+    signUp,
+    signIn,
+    signOut,
+    continueAsGuest,
+  };
+}
+