Auth - Backend Documentation

1. Module Scope

Shared AuthModule provides auth primitives used by two HTTP surfaces:

• Admin controller: /api/auth/*
• Mobile customer controller: /api/mobile/auth/*

Core responsibilities:

• email/password auth
• session/token issuance + refresh/logout
• email/phone verification flows
• password reset flows
• customer Google OAuth login/linking/signup

---

2. Composition

2.1 Controllers

• apps/api/src/modules/auth/auth.controller.ts
  • admin/backoffice auth routes
  • no Google OAuth endpoints
• apps/api/src/modules/mobile/auth/auth.controller.ts
  • customer/mobile auth routes
  • owns Google OAuth endpoints (google, google/callback, google/exchange)

2.2 Strategies and guards

• LocalStrategy + LocalAuthGuard for admin email login
• JwtStrategy + JwtAuthGuard for protected routes
• GoogleStrategy + GoogleAuthGuard for customer Google OAuth flow

2.3 Core services

• AuthService
• AuthSessionService
• AuthUserQueryService
• AuthTokenService
• AuthEmailService
• VerificationTokenService
• GoogleOAuthHandoffService

---

3. Google OAuth Execution Path (Customer Only)

1. GET /api/mobile/auth/google?redirect_uri=<frontend_callback> validates allowlist, signs state, and triggers GoogleAuthGuard redirect.
2. Google calls GET /api/mobile/auth/google/callback.
3. GoogleStrategy.validate() returns profile payload (id, email, displayName, photoUrl) and provider tokens.
4. AuthService.handleGoogleOAuth() applies runtime rules:
   • reject missing email
   • reject if email belongs to admin user
   • find existing customer by email
   • upsert/link Google account row
   • auto-mark customer emailVerified=true when needed
   • auto-create customer + Google account when customer does not exist
5. Service issues session + tokens via existing auth issuance path.
6. Backend stores { user, tokens } in Redis under one-time code (single-use, short TTL).
7. Backend redirects browser to frontend callback with ?code=....
8. Frontend calls POST /api/mobile/auth/google/exchange with the one-time code.
9. Mobile controller returns ResponseDto("Google login successful.", { user, tokens }).

---

4. Data Model Effects

Tables touched in Google flow:

• customers
• admin_users (lookup check only)
• account
• customer_sessions

Write behavior:

• Existing linked customer: updates account token columns.
• Existing unlinked customer: creates Google provider link row in account.
• Existing unverified customer: updates customers.email_verified = true.
• New customer: inserts into customers and inserts provider link into account.

---

5. Behavior Clarifications

5.1 New user via Google

Customer is auto-signed-up (customer row created), then logged in immediately.

5.2 Existing customer with pending email verification

Successful Google login on same email upgrades account to verified and logs user in.

5.3 Admin account attempting Google login

Rejected with unauthorized response; admin must use email/password flow.

---

6. Configuration

Google config keys:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_CALLBACK_URL
• GOOGLE_OAUTH_REDIRECT_ALLOWLIST
• GOOGLE_OAUTH_STATE_SECRET
• GOOGLE_OAUTH_STATE_TTL_SECONDS
• GOOGLE_OAUTH_CODE_TTL_SECONDS

Expected callback route:

• http://<host>:<port>/api/mobile/auth/google/callback

---

7. Security and Operational Controls

• DTO validation via global ValidationPipe
• endpoint throttling via IpThrottlerGuard + @IpThrottle
• banned-user protection via user-query checks
• token/session rotation centralized in session service
• signed/expiring state verification for OAuth callback integrity
• one-time exchange codes stored in Redis and atomically consumed once

This keeps Google flow aligned with the same session issuance policy as email login.