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. OAuth Customer Flow Features

3.1 Supported behavior

Per provider, with {provider} being google or facebook:

• Start: GET /api/mobile/auth/{provider}?redirect_uri=<frontend_callback>
• Callback: GET /api/mobile/auth/{provider}/callback
• Exchange: POST /api/mobile/auth/{provider}/exchange
• Link (authenticated): POST / DELETE /api/mobile/auth/facebook/link

The browser callback returns a single-use code; the storefront exchanges it once for user + tokens. Tokens are never placed in a redirect URL.

3.2 Account resolution rules

Resolution is by the provider's subject id, not by email. The email is a display attribute.

1. Profile has no email → reject.
2. A link already exists for this subject id → that account is the identity; log in. The stored subject id is never rewritten.
3. Email belongs to an admin → reject. OAuth is customer-only.
4. Email belongs to a live customer → depends on the provider, see 3.3.
5. Email belongs to an account being deleted → point at recovery, or refuse if already deleted.
6. Nobody holds the email → create the customer and the link.

3.3 Why Google and Facebook differ at step 4

Google's OIDC response can assert that an address is verified. Facebook's profile carries no verification signal at all.

• Google, when the profile carries that claim: adopts the existing account and marks the email verified. Without the claim it behaves like Facebook.
• Facebook: never adopts. The user is told to sign in with their existing method and link Facebook from account settings.

The distinction is not stylistic. Allowing a provider that cannot prove an address to claim an account on an email match means anyone who can set a profile email to victim@example.com can take that account over.

3.4 Linking an existing account

POST /api/mobile/auth/facebook/link returns a provider authorization URL. Linking needs a provider-verified subject id, which only a real consent round-trip produces, so the client never supplies one — the authenticated customer id is sealed into the signed state instead.

DELETE refuses when the link is the only remaining way to sign in. A customer created through OAuth has no password, so removing their only provider would lock them out with no recovery path.

3.5 Missing-email guard

If the provider profile has no email, the flow fails with a bad request. For Facebook this is the common case when a user declines the email permission; the guard re-requests it on the next attempt.

---

4. Email Verification + OAuth Interaction

• A customer who registered by email/password and is still verification-pending can complete a verified Google login on the same address. The account is marked verified and tokens issued, so Google acts as a trusted proof of email ownership.
• A Facebook sign-in on that same address is refused instead, and the user links from settings.
• A customer created by Facebook starts with emailVerified = false, because nothing has proved the address. The normal email-verification flow works for them unchanged.
• When a verifying provider proves an address that had never been proved, any link from a non-verifying provider on that account is revoked. The owner re-links deliberately. This stops an attacker who seeded the account from keeping access once the real owner arrives.

---

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
• account deletion request, recovery (via email OTP), and cancellation

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.word.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).

---

9. Duplicate Registration Handling

Attempting to register with an email that already belongs to an existing account behaves differently depending on that account's verification state:

• Account not yet verified: the user is told the account already exists but is unverified, and is directed to resend the verification email rather than register again.
• Account already verified: the user is told to log in instead of registering again.
• Account scheduled for deletion: unchanged — the user is directed to the account-recovery flow first (existing behavior, not new).

Registration itself never resends the verification email automatically on a duplicate attempt — resend is always a separate, explicit user action.