OTP phone sign-in flow

This document explains how the phone-number + OTP sign-in works end‑to‑end (backend + frontend) and how to extend or debug it,

High-level overview

• Goal: allow a user to sign in using only their phone number and a one‑time code (OTP) sent via Firebase Phone Authentication.
• Where: mobile app. The web SignIn page is email/password only.
• Key constraints:
  • OTP send goes straight to Firebase. We do not ask the backend whether the number is registered first (that 200-vs-404 check was an account-enumeration oracle; see auth brute-force protection).
  • After a correct OTP, the backend still requires a Mongo user (GET /auth/me / handleUserLogin). An unknown Firebase UID is USER_NOT_REGISTERED — that is after the caller proved they have the phone.
  • We still reuse the existing Firebase session cookie mechanism (POST /auth/session-login) for server‑side authentication on web; mobile uses the ID token on API calls.

Firebase is the only provider involved here for OTP delivery (no Twilio). SMS are billed through the Firebase / Google Cloud project associated with this environment.

---

End-to-end flow (diagram)

At a glance:

• Firebase sends and verifies the SMS code. Send-OTP does not tell the client whether the number is already a Tellia user.
• Backend turns a verified Firebase user into an app session only if a Mongo user already exists for that UID.

---

Backend responsibilities

Backend pieces live under src/firebase/* in the NestJS app.

1. No public phone-existence check

POST /auth/check-phone is gone. Do not add it back: a 200 vs 404 (or any other distinguishable response) for "is this number registered?" is an enumeration oracle on a phone-number identity model.

OTP send lives in apps/mobile/auth/phone-auth.ts (signInWithPhoneNumber only).

2. Firebase lookup and user sync

Key services:

• FirebaseService.getUserByPhoneNumber in src/firebase/firebase.service.ts:

  • Thin wrapper around admin.auth().getUserByPhoneNumber with logging.
  • Admin / migrations only — not a public login probe.

• FirebaseUserService.handleUserLogin in src/firebase/firebase-user.service.ts:

  • Called after a successful OTP when the client hits GET /auth/me (mobile) or POST /auth/session-login (web).
  • Fetches the Firebase user by UID.
  • If a Mongo user exists for that UID, updates identities/metadata.
  • If not, does not auto-create (ENG-269). Throws USER_NOT_REGISTERED so the mobile client can delete the orphan Firebase user in production and send the person to web signup.

3. Session cookie issuance: POST /auth/session-login

• Controller: AuthController.sessionLogin in src/firebase/auth.controller.ts.
• Input: { idToken: string } from the Firebase client SDK.
• Web email/password uses this. Mobile OTP uses the ID token on API calls instead.

---

Client responsibilities

OTP UI lives in apps/mobile:

• app/(auth)/phone-login.tsx + auth/phone-auth.ts — send OTP via Firebase only.
• app/(auth)/verify-otp.tsx + auth/auth-context.tsx confirmPhoneOtp — confirm code, then GET /auth/me.

Do not add a backend "is this number registered?" call on the send-OTP path.

---

Infrastructure, configuration & billing

Provider choice

• We use Firebase Phone Authentication for OTP delivery and verification.
• SMS costs are billed through the Firebase / Google Cloud project associated with the running environment.

Firebase configuration

To enable and operate phone sign‑in, make sure the following are set up in the Firebase console:

• In Firebase Console → Auth → Sign‑in method:
  • Enable Phone as a sign‑in provider.
  • Configure any required reCAPTCHA / safety settings for web clients.
• In Firebase Console → Project settings:
  • Ensure the web app credentials (apiKey, authDomain, etc.) match the values used in the frontend .env (VITE_FIREBASE_* variables).

If phone sign‑in is disabled or misconfigured, signInWithPhoneNumber will fail before any backend logic is called.

Billing & quotas

Firebase charges per SMS for phone authentication. For details:

• See Firebase pricing (Authentication & Phone Auth section).
• Monitor usage & errors under Firebase Auth → Usage and in Cloud Logging for the project.
• Per-IP SMS and verification quotas, plus lockout recovery: Auth brute-force protection.

Operationally, if OTP suddenly fails in production, check in order:

1. Firebase Phone Auth is enabled and not rate‑limited or blocked (auth/too-many-requests / auth/quota-exceeded).
2. Project billing is active and has not hit SMS quota / spending limits.
3. The number’s owner has a Mongo user — otherwise OTP succeeds at Firebase and /auth/me returns USER_NOT_REGISTERED.

---

Links & references

Use these as jumping‑off points; the exact URLs may vary by project/environment.

• Firebase console (Auth – Phone sign‑in): https://console.firebase.google.com
• Firebase Auth phone sign-in docs: https://firebase.google.com/docs/auth/web/phone-auth
• Firebase pricing (Authentication / SMS): https://firebase.google.com/pricing
• Brute-force / enumeration control: Auth brute-force protection
• Internal credentials: search in 1Password for “Firebase – Maison Bleue” to find the console login for the relevant project.