Functional behavior of admin auth, customer mobile auth, Google login/signup/linking, and verification edge cases.

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

Surface	Prefix	Google OAuth	Register
Admin	`/api/auth/*`	No	No
Customer mobile	`/api/mobile/auth/*`	Yes	Yes

3. Google Customer Flow Features

3.1 Supported behavior

Start OAuth: GET /api/mobile/auth/google
Callback: GET /api/mobile/auth/google/callback
Success response returns user + tokens JSON payload.

3.2 Account resolution rules

If Google email belongs to admin account: reject (no Google login for admin).
If matching customer exists and already linked: update provider tokens, login.
If matching customer exists but unlinked: link Google account, login.
If matching customer exists but email unverified: mark verified, login.
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). Google redirect/callback is guard-driven and follows Passport flow.

7. Environment and Callback

Google callback must target mobile surface:

GOOGLE_CALLBACK_URL=http://localhost:<PORT>/api/mobile/auth/google/callback

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 Google success response contract aligned with existing ResponseDto auth payload.

Auth Module Feature Guide