Authentication Services

Relevant source files

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

• apps/api/src/modules/auth/auth.service.ts
• apps/api/src/modules/auth/auth.routes.ts
• apps/api/src/middleware/auth.ts
• apps/api/src/lib/jwt.ts
• packages/db/drizzle/0000_normal_the_order.sql

The Authentication Services module provides a robust multi-layered security framework for the Subito platform. It manages user identification, session persistence, and authorization across different application types (Customer and Partner) using a combination of Firebase for identity verification and custom JSON Web Tokens (JWT) for session management.

The system is designed with a focus on mobile-first security, incorporating device-specific tracking, OTP challenge flows, and refresh token rotation to mitigate common vulnerabilities such as token reuse or account takeover.

Sources: apps/api/src/modules/auth/auth.service.ts, apps/api/src/lib/jwt.ts

Core Authentication Flow

The authentication process utilizes a two-step challenge-response mechanism. Users initiate a login via their mobile number, which generates a challenge, and subsequently verify their identity using a Firebase ID token.

Login Initiation

The system first normalizes the phone number and checks Redis-backed rate limits to prevent OTP abuse. If allowed, it creates an authentication challenge and records the attempt.

Verification and Session Creation

Upon receiving a Firebase ID token, the service performs several validations:

1. Challenge Validation: Ensures the challenge ID is valid, unconsumed, and hasn't exceeded attempt limits.
2. Identity Verification: Verifies the Firebase token and ensures the phone number matches the login request.
3. User Management: Finds or creates the user record, assigns referral rewards if applicable, and generates session identifiers.
4. Token Generation: Issues a short-lived access token and a long-lived refresh token.

Sources: apps/api/src/modules/auth/auth.service.ts:147-320

Token Management

Subito uses standard JWTs signed with HS256. The system enforces strict separation between access and refresh tokens.

Token Specifications

Token Type	Expiry (Default)	Purpose
Access Token	15 minutes	Stateless authorization for API requests. Contains user role, ID, and permissions.
Refresh Token	30 days	Stateful token used to obtain new access tokens. Hashed and stored in the database.
Phone Change Token	15 minutes	Specialized token for verifying a new number during the account update flow.

Sources: apps/api/src/lib/jwt.ts:20-30, apps/api/src/lib/jwt.ts:133-145

Refresh Token Rotation

The system implements refresh token rotation. When a refresh token is used, it is revoked and a new one is issued. If a revoked token is reused, the entire session family is invalidated to prevent hijacking.

RBAC and Middleware

Authorization is enforced via Hono middleware that validates tokens and checks for required roles or permissions.

Role-Based Access Control (RBAC)

Permissions are derived from the user's role defined in the user_role enum (customer, partner, admin).

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:33-54, packages/db/drizzle/0000_normal_the_order.sql:1

Middleware Components

• requireAuth: Ensures a valid, non-blacklisted Bearer token is present. It also validates the X-Device-ID header against the token's embedded device ID.
• requireRole: Restricts access to specific roles (e.g., requireAdmin, requirePartner).
• optionalAuth: Attempts to authenticate but allows the request to proceed if no token is provided.

Sources: apps/api/src/middleware/auth.ts:14-105

Security Models (Database)

The authentication system relies on several tables to manage state and security metadata.

Data Schema Overview

Conclusion

The Authentication Services in Subito provide a defense-in-depth approach by combining Firebase's identity layer with a custom, stateful session management system. By incorporating device verification, token rotation, and strict role-based middleware, the platform ensures that user sessions are both secure and manageable across various client applications.

Sources: apps/api/src/modules/auth/auth.service.ts, apps/api/src/middleware/auth.ts