Feature: Authentication
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication feature provides a complete system for user identity management, leveraging Supabase as the backend service. It handles user registration, sign-in, sign-out, session persistence, and profile updates. The system is designed to be secure, abstracting away direct API interactions through a dedicated service layer and providing a clean interface to the UI via a custom hook.
The architecture is built with future enhancements in mind, containing placeholders ("backdoors") for features like social login (Google, Facebook, Apple), magic links, and phone-based authentication. Session data is persisted locally using AsyncStorage to maintain user login state across application restarts.
Sources: TASK_4_SUMMARY.md, src/core/services/api/auth.api.js, README.md
Architecture Overview
The authentication system follows a clean, layered architecture that separates concerns from the UI down to the backend service. The UI components interact with a custom useAuth hook, which in turn communicates with a Zustand-based state store (authStore). This store manages the application's authentication state. All backend operations are delegated to the auth.api.js service, which is the single point of contact with the Supabase authentication backend.
This diagram illustrates the high-level architecture of the authentication module.
State Management
State is managed globally using Zustand, a lightweight state management library. A dedicated authStore holds all authentication-related data, and a custom useAuth hook provides a simple and reactive interface for UI components to access and manipulate this state.
Sources: TASK_4_SUMMARY.md
Auth Store (authStore.js)
The authStore is the single source of truth for the user's authentication status.
This diagram shows the structure of the authStore.
The key properties managed by the store are:
| Property | Type | Description | Source |
|---|---|---|---|
user | Object | The authenticated user object from Supabase. | TASK_4_SUMMARY.md |
session | Object | The user's session object, including access and refresh tokens. | TASK_4_SUMMARY.md |
isAuthenticated | boolean | A flag indicating if the user is currently authenticated. | TASK_4_SUMMARY.md |
isLoading | boolean | A flag to indicate when an authentication operation is in progress. | TASK_4_SUMMARY.md |
error | string | Stores any error messages from failed authentication attempts. | TASK_4_SUMMARY.md |
useAuth Hook
The useAuth hook is a custom hook that simplifies interaction with the authStore and the authentication API. It exposes methods like signIn, signOut, and state variables like user and isAuthenticated directly to components.
// Example usage from documentation
import { useAuth } from './src/core/state/hooks/useAuth';
function MyComponent() {
const { signIn, user, isAuthenticated } = useAuth();
const handleLogin = async () => {
await signIn('email@example.com', 'password');
};
}
Sources: TASK_4_SUMMARY.md
API Service (auth.api.js)
This service acts as a wrapper around the Supabase client, handling all authentication-related API calls. It is responsible for signing users up, in, and out, managing sessions, and updating user profiles.
Key Functions
The service exposes a set of asynchronous functions to interact with the Supabase backend.
| Function | Description | Source |
|---|---|---|
signUp | Registers a new user with an email, password, and optional metadata. | src/core/services/api/auth.api.js:154-205 |
signIn | Authenticates a user with an email and password, returning a session and user object. | src/core/services/api/auth.api.js:207-254 |
signOut | Signs the current user out and clears the session from local storage. | src/core/services/api/auth.api.js:256-271 |
getSession | Retrieves the current session, first from the Supabase client and falling back to AsyncStorage. | src/core/services/api/auth.api.js:273-293 |
getCurrentUser | Fetches the current authenticated user object from Supabase. | src/core/services/api/auth.api.js:295-304 |
updateProfile | Updates the current user's metadata. | src/core/services/api/auth.api.js:306-323 |
resetPassword | Sends a password reset email to the specified user. | src/core/services/api/auth.api.js:325-345 |
onAuthStateChange | Subscribes to Supabase's authentication state changes, allowing the app to react to events like token refresh or sign-out. It also updates AsyncStorage accordingly. | src/core/services/api/auth.api.js:347-367 |
Session Persistence
The service persists the user's session to the device's local storage using AsyncStorage. This ensures the user remains logged in between app sessions. The session is stored under the key @eefashionita:auth.
// src/core/services/api/auth.api.js:22-25
const persistSession = async (session) => {
if (!session) return;
await AsyncStorage.setItem(AUTH_STORAGE_KEY, JSON.stringify(session));
};
Sources: src/core/services/api/auth.api.js:22-25
Supabase Key Format Handling
The service includes logic to handle different Supabase API key formats (isNewSupabaseKeyFormat). If a newer key format is detected, it makes direct fetch requests to the Supabase REST endpoints (/auth/v1/signup, /auth/v1/token) instead of relying solely on the Supabase JS client methods. This ensures forward compatibility.
Sources: src/core/services/api/auth.api.js:10-13, 78-152
Data Flows
Sign-Up Flow
The following diagram shows the sequence of events during user registration.
Sign-In Flow
This diagram illustrates the user sign-in process.
Configuration and Security
Storage Keys
Authentication-related data is stored locally using keys defined in the constants files. The primary key for the session is defined in auth.api.js.
| Key | File | Description |
|---|---|---|
AUTH_STORAGE_KEY | auth.api.js | The key for storing the entire session object in AsyncStorage. |
AUTH_TOKEN | constants.js | Key for the authentication token. |
REFRESH_TOKEN | constants.js | Key for the refresh token. |
USER_DATA | constants.js | Key for storing user profile data. |
Sources: src/core/services/api/auth.api.js:15, src/core/utils/constants.js:256-260
Environment Variables
To enhance security, Supabase API keys are not hardcoded. They are managed through .env files and loaded at runtime. This practice was adopted to fix a critical security issue where keys were previously exposed in the source code. Developers must create a local .env file with their Supabase credentials to use the authentication features.
Sources: SECURITY_AND_CLEANUP_FIXES.md
Future Enhancements (Backdoors)
The authentication system was explicitly designed with future expansion in mind. The source code and project documentation identify several "backdoors" or placeholder functionalities that can be implemented without significant refactoring.
- Social Login: Placeholders exist for Google, Facebook, and Apple sign-in.
- Magic Link: A placeholder for passwordless email login.
- Phone Authentication: A placeholder for SMS-based sign-in.
These are noted in comments within the auth.api.js file and detailed in the project's planning documents.
Sources: src/core/services/api/auth.api.js:369-377, TASK_4_SUMMARY.md