refactor(auth): redesign authentication and identity models

[Harxhit]

Summary

Closes #519

Redesign the authentication system to support multiple authentication providers, secure session management, refresh token rotation, and future authentication methods such as OAuth, email/password, and phone-based login.

This PR introduces a dedicated identity layer, refresh token infrastructure, account verification fields, role management, and OAuth-ready authentication flows.

---

Context

The previous authentication architecture stored provider-specific authentication data directly on the User model. This made it difficult to support multiple authentication methods for a single account and limited future extensibility.

This redesign separates authentication concerns from user profile data by introducing a dedicated identity model and a more robust session management system.

The new design provides a scalable foundation for:

• Google OAuth
• GitHub OAuth
• Email/password authentication
• Phone authentication
• Multi-provider account linking
• Refresh token rotation
• Session auditing and management

---

Authentication Flow

Login

OAuth Provider
      ↓
OAuth Callback
      ↓
Find Identity
      ↓
Identity Exists?
 ├─ Yes → Login Existing User
 └─ No
      ↓
Check Existing User By Email
 ├─ Yes → Link Identity
 └─ No → Create User + Identity
      ↓
Generate Access Token
Generate Refresh Token
      ↓
Create Session Record
      ↓
Authenticate User

---

Session Management

Access and refresh tokens are now handled separately.

Access Token

• Short-lived JWT
• Used for API authentication
• Contains user identity claims
• Intended lifespan: ~15 minutes

Refresh Token

• Long-lived token
• Stored as a SHA-256 hash in the database
• Used to obtain new access tokens
• Supports refresh token rotation

---

Refresh Token Rotation

Refresh Token A
      ↓
Refresh Request
      ↓
Revoke Token A
      ↓
Issue Token B
      ↓
Issue New Access Token

Benefits:

• Prevents token replay attacks
• Enables compromise detection
• Improves session security

---

Schema Changes

Roles

Introduced role-based account support.

SUPERADMIN
ADMIN
USER

Default role:

USER

---

User Identity Layer

Added a dedicated UserIdentity model.

Responsibilities:

• Stores authentication provider information
• Maps providers to users
• Supports multiple authentication methods per account

Constraints:

• Unique (provider, providerId)
• Indexed userId

Benefits:

• Multiple providers per account
• Cleaner authentication architecture
• Easier provider onboarding
• Simplified account linking

---

User Model Improvements

Added:

emailVerified

Tracks whether a user's email has been verified.

phoneNumber

Supports future phone authentication flows.

lastSignInAt

Records the most recent successful login.

isActive

Supports account activation, suspension, and deactivation.

---

Refresh Token Model Improvements

Enhanced refresh token storage for secure session management.

Added:

family

Groups tokens belonging to the same login session.

tokenHash

Stores hashed refresh tokens instead of raw values.

userAgent

Tracks device and browser information.

ipHash

Stores a hashed representation of the client IP address.

Benefits:

• Secure token storage
• Session tracking
• Device auditing
• Refresh token rotation support
• Reduced impact of database leaks

---

Security Improvements

OAuth State Validation

Added CSRF protection through OAuth state verification.

Token Hashing

Refresh tokens are never stored in plaintext.

Session Tracking

Sessions now track:

• Device information
• Token family
• Login activity

Refresh Token Rotation

Refresh tokens are rotated on use and old tokens are revoked.

Account Linking Foundation

Authentication providers can be linked to a single user account through identities.

---

Future Work

• Email/password authentication
• Password reset flow
• Email verification flow
• Phone authentication
• Session management UI
• Device management
• OAuth provider unlinking
• Token reuse detection
• Automated cleanup of revoked refresh tokens

---

Proofs

Screen.Recording.2026-06-11.171421.mp4

[vercel]

@Harxhit is attempting to deploy a commit to the Prashantkumar Khatri's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

CI — All Checks Passed

Backend — PASS

Check	Result
Lint	PASS
Test	PASS
Typecheck	PASS

Mobile — SKIP

Check	Result
Lint	-
Test	-

Web — SKIP

Check	Result
Check	-
Build	-

---

Last updated: Thu, 11 Jun 2026 19:24:04 GMT

[ShantKhatri]

LGTM!

[ShantKhatri]

The checks are failing, needs to fix this before merge.

[Harxhit]

The checks are failing, needs to fix this before merge.

The problem is with the workflow I will make changes.

[Harxhit]

Need to add cron job for the revoked refresh_tokens.