Authentication Flow

Relevant source files

The following files were used as context for generating this wiki page:

• src/auth/passport.ts
• src/auth/routes.ts
• src/database/migrations/008_create_users_and_sessions.sql
• src/api/server.ts
• frontend/src/services/api.ts
• frontend/src/pages/Login.tsx

Introduction

The authentication system in the WhereIsLifeCheaper project is designed to provide secure access to administrative features, such as triggering scrapers and managing canonical products. It utilizes Google OAuth 2.0 as the primary identity provider, managed on the backend via Passport.js and integrated into an Express.js server.

The flow ensures that users are identified by their Google accounts, with roles (user vs. admin) assigned based on pre-configured administrative email lists. Session management is handled using encrypted cookies and persisted in a PostgreSQL database to maintain user state across the serverless environment.

Sources: README.md:16-25, src/api/server.ts:46-64, src/auth/passport.ts:25-45

Backend Architecture

The backend authentication logic is built on top of Express.js using passport-google-oauth20 for strategy implementation and express-session for session persistence.

Passport Strategy & Initialization

The system initializes a GoogleStrategy only if valid Google Client IDs and Secrets are present in the environment configuration. Upon successful redirection from Google, the system checks if the user exists in the users table. If not, a new user record is created. User roles are dynamically assigned: if the user's email exists in the ADMIN_EMAILS configuration, they are granted the 'admin' role; otherwise, they receive the 'user' role.

Sources: src/auth/passport.ts:10-53, src/auth/routes.ts:10-15

Session Persistence

Sessions are stored in the PostgreSQL database using connect-pg-simple. This allows the application to remain stateless while preserving user logins across multiple requests or server restarts.

The diagram above shows how the server verifies identity using the session storage.
Sources: src/api/server.ts:46-64, src/database/migrations/008_create_users_and_sessions.sql:20-25, src/auth/passport.ts:75-95

Authentication Sequence

The OAuth flow involves the Frontend, Backend, Google's OAuth Servers, and the local Database.

Data Models

User Schema

The users table stores profile information and authorization levels.

Field	Type	Description
id	SERIAL	Primary Key
google_id	VARCHAR	Unique ID from Google OAuth
email	VARCHAR	User's primary email (unique)
role	VARCHAR	'user' or 'admin'
is_active	BOOLEAN	Account status (default true)
last_login	TIMESTAMP	Last successful authentication

Sources: src/database/migrations/008_create_users_and_sessions.sql:5-18

API Endpoints

The following endpoints manage the authentication lifecycle:

Method	Endpoint	Description
GET	/api/auth/google	Initiates the Google OAuth login flow.
GET	/api/auth/google/callback	Google redirect target; handles session creation.
GET	/api/auth/me	Returns current user's profile and role.
GET	/api/auth/status	Returns a boolean auth status and admin flag.
POST	/api/auth/logout	Destroys the session and clears cookies.

Sources: src/auth/routes.ts:10-85, frontend/src/services/api.ts:11-25

Frontend Integration

The frontend uses a React Context (AuthContext) to track the user's authentication state globally. Upon mounting, the application queries /api/auth/me to determine if a valid session exists.

Protected Routes

Administrative views (like the Scraper Dashboard or Canonical Mapping) are wrapped in a ProtectedRoute component. This component checks the role property of the user object. If the user is not authenticated or lacks the 'admin' role, they are redirected to the Login page.

Sources: frontend/src/pages/Login.tsx:10-15, frontend/src/services/api.ts:125-150, README.md:120-130

Logout Procedure

When a user logs out, the frontend calls the POST /api/auth/logout endpoint. The backend performs the following:

1. Calls req.logout() to clear the passport state.
2. Destroys the session in the database.
3. Clears the connect.sid cookie from the browser.

Sources: src/auth/routes.ts:65-80, frontend/src/services/api.ts:22-24

Summary

The Authentication Flow provides a robust, session-based mechanism for securing the application. By leveraging Google OAuth 2.0, the project avoids the complexities of password management while maintaining strict access control through role-based logic (RBAC). The integration of database-backed sessions ensures that the system is compatible with serverless deployment environments like Vercel.