Authentication Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication Flow in Subito is a multi-stage system designed to handle secure user access across customer and partner applications. It leverages mobile number verification via Firebase, JSON Web Tokens (JWT) for session management, and a robust refresh token rotation mechanism to ensure long-lived but secure sessions.
The system encompasses initial login challenges, Firebase token verification, JWT issuance, role-based access control (RBAC), and session management (including logout and device tracking).
Sources: apps/api/src/modules/auth/auth.service.ts, apps/api/src/middleware/auth.ts
Login and Verification Process
The authentication process starts with a mobile number login that initiates a challenge-response mechanism.
Phase 1: Initiation (Login)
When a user submits their mobile number, the system validates the request against rate limits and creates an authentication challenge. This challenge is stored in Redis with a unique challengeId.
Sources: apps/api/src/modules/auth/auth.service.ts:109-138
Phase 2: Verification
The user must provide the challengeId along with a firebaseIdToken obtained via mobile OTP verification. The system verifies the Firebase token, ensures the phone numbers match, and then either creates a new user or retrieves an existing one.
Sources: apps/api/src/modules/auth/auth.service.ts:143-241
Authentication Sequence
The following diagram illustrates the sequence from initial login request to JWT issuance:
JWT and Session Management
Subito uses two types of tokens: Access Tokens (short-lived) and Refresh Tokens (long-lived).
Token Structure and Expiry
- Access Tokens: Contain
userId,role,phone,sessionId,deviceId, andpermissions. Default expiry is 15 minutes. - Refresh Tokens: Used to obtain new access tokens. They are tracked in the database and support "Rotation," where a new refresh token is issued every time one is used.
Sources: apps/api/src/lib/jwt.ts:25-82, apps/api/src/modules/auth/auth.service.ts:348-369
Refresh Token Rotation and Security
To prevent replay attacks, the system marks old refresh tokens as rotated. If a token is reused, the entire session "family" is revoked.
Role-Based Access Control (RBAC)
Permissions are derived from the user's role and embedded directly into the Access Token.
Role Permissions Mapping
| Role | Permissions |
|---|---|
| Customer | read:profile, create:booking, read:booking, read:listing, read:cart |
| Partner | read:profile, read:partner_bookings, update:partner_status, update:partner_location |
| Admin | * (All permissions) |
Sources: apps/api/src/lib/jwt.ts:32-52
Middleware Enforcement
Authorization is enforced through middleware that validates the JWT and checks for specific roles or session validity.
| Middleware | Description |
|---|---|
requireAuth | Mandatory valid Bearer token; checks blacklist and device mismatch. |
optionalAuth | Attempts to identify user but allows request to proceed if token is missing. |
requireRole | Validates that the user has one of the specified roles (customer, partner, admin). |
Sources: apps/api/src/middleware/auth.ts:15-103
Data Models
Authentication state is persisted across several tables in the PostgreSQL database.
Refresh Tokens Table (refresh_tokens)
| Field | Type | Description |
|---|---|---|
id | uuid | Primary Key |
user_id | uuid | Reference to the user |
token | text | SHA256 hash of the plain refresh token |
session_id | uuid | Grouping ID for a specific login session |
device_id | varchar(128) | Unique identifier for the hardware |
expires_at | timestamp | Token expiration date |
Sources: packages/db/drizzle/0000_normal_the_order.sql:22-30
Users Table (users)
Relevant fields for authentication:
firebase_uid: Unique ID from Firebase Auth.role: Enum ofcustomer,partner, oradmin.phone: Primary identifier (mobile number).
Sources: packages/db/drizzle/0000_normal_the_order.sql:42-59
API Endpoints
The authRouter defines the following routes for managing the authentication lifecycle.
| Method | Path | Auth Required | Description |
|---|---|---|---|
POST | /login | No | Initiates OTP challenge for a mobile number. |
POST | /verify | No | Verifies Firebase token and returns JWTs. |
POST | /refresh | No | Rotates access/refresh tokens. |
POST | /logout | Yes | Revokes current session and blacklists token. |
GET | /sessions | Yes | Lists all active sessions for the user. |
DELETE | /sessions/:id | Yes | Revokes a specific session by ID. |
Sources: apps/api/src/modules/auth/auth.routes.ts:58-132
Summary
The Subito Authentication Flow provides a secure, token-based architecture that integrates Firebase for identity verification and custom JWT logic for session management. By implementing refresh token rotation and device-bound session tracking, the system protects against token theft and unauthorized access across its various user roles.
Sources: apps/api/src/modules/auth/auth.service.ts, apps/api/src/middleware/auth.ts