Auth - Feature Guide

1. Feature Overview

Auth is intentionally split by actor surface:

• Admin/superadmin auth on /api/auth/* (email/password only)
• Customer mobile auth on /api/mobile/auth/* (email/password + Google)

Google OAuth is customer-only.

---

2. Surface Matrix

---

3. Google Customer Flow Features

3.1 Supported behavior

• Start OAuth: GET /api/mobile/auth/google?redirect_uri=<frontend_callback>
• Callback: GET /api/mobile/auth/google/callback
• Exchange: POST /api/mobile/auth/google/exchange
• Browser callback returns one-time code; frontend exchanges it once for user + tokens.

3.2 Account resolution rules

1. If Google email belongs to admin account: reject (no Google login for admin).
2. If matching customer exists and already linked: update provider tokens, login.
3. If matching customer exists but unlinked: link Google account, login.
4. If matching customer exists but email unverified: mark verified, login.
5. If no matching customer: auto-create customer + provider link, login.

3.3 Missing-email guard

If Google provider profile does not include an email, flow fails with bad request.

---

4. Email Verification + Google Interaction

Important edge case:

• A customer who registered with email/password but is still verification-pending can complete Google login with the same email.
• Result: account is marked emailVerified=true and session tokens are issued.

This means Google login acts as a trusted identity verification path for email ownership.

---

5. Non-Google Auth Features

Admin and mobile surfaces both support:

• email/password login
• refresh token rotation
• logout
• password reset (forgot + reset)
• email verification resend/confirm

Admin-only extras:

• GET /api/auth/permissions
• phone verification endpoints under /api/auth/phone/verify/*

---

6. Rate-Limit Feature Notes

Throttling is enabled on high-risk routes (login, refresh, password reset, verification) and Google OAuth start/callback/exchange endpoints.

---

7. Environment and Callback

Google callback must target mobile surface:

• GOOGLE_CALLBACK_URL=http://localhost:<PORT>/api/mobile/auth/google/callback
• GOOGLE_OAUTH_REDIRECT_ALLOWLIST=https://app.thangka.navneetverma.com/auth/callback
• GOOGLE_OAUTH_STATE_SECRET=<long-random-secret>
• GOOGLE_OAUTH_STATE_TTL_SECONDS=300
• GOOGLE_OAUTH_CODE_TTL_SECONDS=90

Do not configure callback to /api/auth/google/callback.

---

8. Implementation Guardrails

• Keep admin auth Google-disabled.
• Keep customer Google flow under mobile controller.
• Keep account linking additive (email/password and Google can coexist).
• Keep bearer token issuance on /api/mobile/auth/google/exchange only (never in redirect URL).