halobestie-clone/requirement/phase3.4.md

# PRD: Self-Managed Authentication

# Overview

**Goal:** Replace Firebase Auth with a self-managed authentication system across all apps, using Fazpass for SMS/WhatsApp OTP delivery and direct verification of Google/Apple ID tokens for social login.

**Success looks like:** Customers, mitras, and control center admins can all authenticate through our own backend without any dependency on Firebase Auth. User identity is anchored in our database, session tokens are issued and revoked by our backend, and Firebase Admin SDK is fully removed from the backend. FCM push notifications continue to work (Firebase Cloud Messaging is kept).

**Affects:** `backend`, `client_app`, `mitra_app`, `control_center`

## Background

Firebase Auth currently handles:
- Phone OTP for customers and mitras
- Google and Apple social login for customers
- Email/password for control center admins
- Anonymous sessions for customers
- JWT issuance and verification

Moving off Firebase gives us direct control over:
- Session management (revocation, multi-device, TTL tuning)
- OTP delivery (Fazpass for WhatsApp + SMS, better Indonesian coverage than Firebase phone auth)
- User data (no user identity locked inside Firebase)
- Cost (Firebase phone auth is expensive at scale)
- Branding (fully native flows, no Firebase-branded fallback screens)

FCM (Firebase Cloud Messaging) is separate from Firebase Auth and **stays** — it handles push notifications and is not affected by this phase.

---

# Functional Requirements

## 1. Anonymous Customer Flow

### Trigger
- App launches for the first time OR local refresh token is missing/expired.

### Behavior
- App calls `POST /api/shared/auth/anonymous` with no body, no auth.
- Backend creates a new `customers` row with no identity (phone, google_sub, apple_sub all null) and a generated `display_name` (e.g., "Teman Anonim #XXXX").
- Backend creates an `auth_sessions` row and returns `{ access_token, refresh_token }`.
- App stores refresh token in secure storage (Keychain / Keystore).
- All subsequent requests use the access token.

### Upgrade to Authenticated
- When the user chooses a real identity (phone / Google / Apple), the existing anonymous `customers` row gets its identity columns populated (phone / google_sub / apple_sub / email).
- Tokens are rotated — a new access + refresh token pair is issued on identity upgrade.
- If the identity is **already linked to another customer**, backend returns **409 CONFLICT** (reject-on-existing). Merging is deferred (see Out of Scope).

---

## 2. Phone OTP Flow (Customer + Mitra)

### Request OTP
- `POST /api/{client|mitra}/auth/otp/request` with body `{ phone: "+628..." }`
- Backend:
  - Validates phone format (E.164)
  - Checks rate limits (see Section 8)
  - Calls Fazpass API to send OTP via configured channel (default: WhatsApp with SMS fallback)
  - Stores the Fazpass request reference (not the OTP code itself — Fazpass holds it) in a new `otp_requests` table
  - Returns `{ otp_request_id, channel_used, expires_at }`

### Verify OTP
- `POST /api/{client|mitra}/auth/otp/verify` with `{ otp_request_id, code }`
- Backend:
  - Looks up `otp_requests` row; validates not expired, not already used, attempts under limit
  - Calls Fazpass verify API
  - If valid:
    - Look up existing `customers` (or `mitras`) by phone
    - If found: issue tokens against that row (for customer, this is the "upgrade anonymous" path if the current session is anonymous — see Section 1)
    - If not found: create a new row keyed by phone
  - Issues `{ access_token, refresh_token }` + user profile

### Resend
- Same endpoint as Request OTP. Rate limiter enforces 60s cooldown (see Section 8).

---

## 3. Google Sign-In (Customer Only)

### Flow
- Flutter app uses the existing `google_sign_in` package (a Google library, not a Firebase library — survives Firebase removal).
- `GoogleSignIn().signIn()` → returns a Google ID token (JWT signed by Google).
- App sends `POST /api/client/auth/google` with `{ id_token }`.
- Backend:
  - Verifies the token against Google's JWKS (`https://www.googleapis.com/oauth2/v3/certs`) using `google-auth-library`
  - Validates audience matches our OAuth client ID (configured per-platform: Android, iOS)
  - Extracts `sub` (Google user ID), `email`, `name`, `email_verified`
  - Look up existing `customers` by `google_sub`:
    - If found: issue tokens against that row
    - If not found and caller has anonymous session: upgrade anonymous row by setting `google_sub` + `email` + `display_name`
    - If not found and no anonymous session: create a new customer row
  - If the Google sub is already linked to a different customer and caller is anonymous: return 409 (reject-on-existing)
- Returns `{ access_token, refresh_token, profile }`

### OAuth Client IDs
- Separate client IDs per platform (Android / iOS) must be configured in Google Cloud Console.
- Configured via env vars on the backend: `GOOGLE_OAUTH_CLIENT_IDS` (comma-separated list, all validated as valid audiences).

---

## 4. Apple Sign-In (Customer Only)

### Prerequisites (External)
- **Apple Developer account** ($99/year) — required.
- Services ID created in Apple Developer portal (e.g., `com.halobestie.client.signin`)
- Private key (`.p8`) generated with Key ID
- Team ID noted

**This setup is a hard blocker for end-to-end testing.** Backend code can be written and dry-verified without it; runtime flow cannot function on iOS until this is done.

### Flow
- Flutter app uses `sign_in_with_apple` package.
- `SignInWithApple.getAppleIDCredential()` → returns Apple's ID token.
- App sends `POST /api/client/auth/apple` with `{ id_token, authorization_code? }`.
- Backend:
  - Verifies token against Apple's JWKS (`https://appleid.apple.com/auth/keys`) using `apple-signin-auth` or manual JWT verification
  - Validates audience matches Services ID
  - Extracts `sub` (Apple user ID), `email` (only on first sign-in; subsequent sign-ins don't include it)
  - Customer lookup/creation/anonymous-upgrade flow identical to Google
- Returns `{ access_token, refresh_token, profile }`

### Email Handling Quirk
- Apple only returns `email` the first time a user signs in with your app. Subsequent sign-ins omit it.
- We must persist `email` on first sign-in; don't rely on getting it again.

### App Store Policy
- Per Apple guidelines, any iOS app offering third-party social login (Google) **must also offer Sign in with Apple**. So Apple is required on iOS since client_app has Google.

---

## 5. Mitra Authentication

- Mitras use **phone OTP only** (Section 2). No Google, no Apple, no anonymous.
- Existing mitra auth flow wraps the same Fazpass integration behind `/api/mitra/auth/otp/request` and `/api/mitra/auth/otp/verify`.

---

## 6. Control Center Email/Password

### Login
- `POST /internal/auth/login` with `{ email, password }`
- Backend:
  - Looks up `control_center_users` by email
  - Compares password against `password_hash` using bcrypt
  - Checks brute-force lockout state (see Section 8)
  - On success: issues `{ access_token, refresh_token, profile }`
  - On failure: increments failure counter; after 5 failures, 15-minute lockout

### First Super-Admin Seeding
- Updated `backend/src/db/seed.js` reads `ADMIN_EMAIL` + `ADMIN_PASSWORD` env vars, bcrypt-hashes the password, inserts a single `control_center_users` row with super-admin role.
- Replaces the existing Firebase `admin.auth().createUser()` call.

### New Admin Provisioning (CC UI)
- Super-admin creates new CC users via existing CC "Users" page.
- Form adds an "Initial Password" field (with a "Generate" button that creates a 16-char random).
- Backend `POST /internal/cc-user` accepts `{ email, display_name, role_id, password }`, hashes password, inserts row.

### Password Change (Self-Service)
- `PATCH /internal/cc-user/me/password` with `{ current_password, new_password }`
- Backend verifies `current_password` against stored hash, then replaces hash with `bcrypt.hash(new_password, 12)`

### Password Change (Admin-Forced)
- `PATCH /internal/cc-user/:id/password` with `{ new_password }`
- Requires super-admin role
- Same bcrypt flow

### Password Complexity Rules
- Minimum 8 characters
- At least 1 digit
- At least 1 uppercase letter
- At least 1 lowercase letter
- Enforced server-side on create + change endpoints

### Password Hashing
- **bcrypt with cost factor 12**
- Salt is embedded in the hash (bcrypt handles automatically; no separate column needed)
- Stored in `control_center_users.password_hash VARCHAR(60)`

---

## 7. Token Strategy

### Access Token (JWT, HS256)
- **TTL: 1 hour**
- **Signed with**: `AUTH_JWT_SECRET` env var (strong random, min 32 bytes)
- **Claims**:
  - `sub` — user ID
  - `user_type` — `customer` | `mitra` | `cc_user`
  - `session_id` — PK of the `auth_sessions` row (used for future Valkey-based revocation; see Section 7.3)
  - `iat`, `exp` — standard JWT fields
- **Verification**: backend validates signature and expiry on every authenticated request — no DB lookup on happy path

### Refresh Token (Opaque)
- **Format**: 32-byte random, base64url encoded
- **TTL: 30 days**
- **Rotation**: every time the refresh token is used, a new refresh token is issued and the old one is invalidated
- **Storage**:
  - Client: secure storage (Keychain / Keystore on mobile, `httpOnly` cookie on CC — see note below)
  - Server: bcrypt-hashed in `auth_sessions.refresh_token_hash` (never raw)

### Control Center Token Storage
- Browser-based, so JWT access token lives in memory (JS variable in AuthContext) — **not** localStorage (XSS risk)
- Refresh token: httpOnly secure cookie on the CC domain. Browser auto-sends; JS can't read.
- Automatic refresh when access token expires (via 401 interceptor)

### Revocation (Now)
- **Logout**: `DELETE FROM auth_sessions WHERE id = :session_id` — refresh token becomes unusable; access token dies within 1 hour
- **Admin ban mitra**: delete all `auth_sessions` rows for that mitra — same 1-hour window for active access tokens
- Accepted tradeoff: **up to 1 hour between revocation and full session death**

### Revocation (Future, Pre-wired)
- `session_id` claim in JWT enables Valkey-based instant revocation without changing token shape
- Future enhancement: add `SISMEMBER revoked_sessions <session_id>` check to the authenticate middleware
- Mentioned in the plan as a deferred enhancement — not implemented in Phase 3.4

### Multi-Device Sessions
- Each login / OTP verify / social verify = new `auth_sessions` row
- Logging in on device B does not invalidate device A
- Logout only affects the calling device

### Refresh Endpoint
- `POST /api/shared/auth/refresh` with `{ refresh_token }`
- Backend: look up session by token hash, verify not expired, rotate refresh token, issue new access token, return both

### Logout Endpoint
- `POST /api/shared/auth/logout` with `{ refresh_token }` (authenticated)
- Backend: delete the matching `auth_sessions` row

---

## 8. Security

### OTP Rate Limits (Configurable via `app_config`)
- `otp_max_per_phone_per_hour` — default **3**
- `otp_max_per_ip_per_hour` — default **10**
- Exceeding returns **429** with `Retry-After` header

### OTP Resend Cooldown
- Same phone cannot request another OTP within **60 seconds** of the last request

### OTP Verification Attempts
- Max **5 wrong code attempts per OTP request** before invalidating the request (new OTP required)

### Control Center Login Brute-Force
- Max **5 failed password attempts per email per 15 minutes**
- 6th failure locks the account for **15 minutes** (tracked in `control_center_users.lockout_until`)
- Failed attempts counter resets on successful login

### Session Fingerprinting
- On every auth_sessions creation, record `user_agent` and `ip` in a `device_info JSONB` column
- Not enforced for security; visible in control center for audit/support

### JWT Secret Rotation
- **Out of scope for this phase**: single `AUTH_JWT_SECRET` env var
- Documentation will note the rotation procedure (dual-secret window) but implementation is deferred

### HTTPS Only
- All auth endpoints enforce HTTPS in production (assumed via existing infra — Cloud Run + Nginx)

---

## 9. Data Model

### New Table: `auth_sessions`
```
id                    UUID PK
user_type             VARCHAR(16) NOT NULL  -- 'customer' | 'mitra' | 'cc_user'
user_id               UUID NOT NULL
refresh_token_hash    VARCHAR(60) NOT NULL  -- bcrypt hash of refresh token
device_info           JSONB                 -- { user_agent, ip, platform? }
created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
last_used_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
expires_at            TIMESTAMPTZ NOT NULL  -- created_at + 30 days
revoked_at            TIMESTAMPTZ           -- null if active
```
Indexes: `(user_type, user_id)`, `(expires_at)` for cleanup.

### New Table: `otp_requests`
```
id                    UUID PK
phone                 VARCHAR(20) NOT NULL
fazpass_reference     VARCHAR(255) NOT NULL  -- Fazpass's OTP session ID
channel               VARCHAR(16)            -- 'whatsapp' | 'sms'
attempts              INT NOT NULL DEFAULT 0
used_at               TIMESTAMPTZ
created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
expires_at            TIMESTAMPTZ NOT NULL
```
Index: `(phone, created_at)` for rate-limit lookups.

### Schema Changes to Existing Tables

**`customers`**
- DROP `firebase_uid`
- ADD `phone VARCHAR(20) UNIQUE` (already exists, keep)
- ADD `email VARCHAR(255)` (nullable, populated from Google/Apple)
- ADD `google_sub VARCHAR(255) UNIQUE` (nullable)
- ADD `apple_sub VARCHAR(255) UNIQUE` (nullable)

**`mitras`**
- DROP `firebase_uid`

**`control_center_users`**
- DROP `firebase_uid`
- ADD `password_hash VARCHAR(60) NOT NULL`
- ADD `failed_login_count INT NOT NULL DEFAULT 0`
- ADD `lockout_until TIMESTAMPTZ` (nullable)

### New `app_config` Keys
- `otp_max_per_phone_per_hour` (default `3`)
- `otp_max_per_ip_per_hour` (default `10`)
- `otp_resend_cooldown_seconds` (default `60`)
- `otp_verify_max_attempts` (default `5`)
- `cc_login_max_attempts` (default `5`)
- `cc_login_lockout_minutes` (default `15`)

---

## 10. Dependencies to Add / Remove

### Backend

**Add**:
- `jsonwebtoken` (JWT signing/verification)
- `bcrypt` (password + refresh token hashing)
- `google-auth-library` (Google ID token verification)
- `apple-signin-auth` or `jsonwebtoken` + JWKS fetch (Apple ID token verification)
- Fazpass SDK (if they ship one) or direct HTTP client (axios/undici)

**Remove**:
- `firebase-admin`

**Keep**:
- Firebase Cloud Messaging via `firebase-admin` — **wait** — if we remove `firebase-admin`, how does FCM work? The same package handles both Auth and Messaging. Two options:
  - (a) Keep `firebase-admin` but only use its `messaging()` API; never touch `auth()` or the ID token verification functions
  - (b) Switch to the lower-level FCM HTTP v1 API directly (no SDK)
  - **Recommendation**: (a) — simpler, still removes the Auth dependency at runtime.

### client_app (Flutter)

**Remove**:
- `firebase_auth`
- `firebase_core` (if no other Firebase features remain — but FCM needs it, so keep)

**Keep**:
- `firebase_core`, `firebase_messaging` (for FCM)
- `google_sign_in` (standalone Google library)
- `sign_in_with_apple` (standalone Apple library)
- `flutter_secure_storage` (add if not present — refresh token storage)

**Remove config**:
- `firebase_options.dart` — only keep if `firebase_core` is still in use for FCM; otherwise remove

### mitra_app (Flutter)

**Remove**:
- `firebase_auth`

**Keep**:
- `firebase_core`, `firebase_messaging` (for FCM)
- `flutter_secure_storage` (refresh token)

### control_center (React)

**Remove**:
- `firebase`

**Add**:
- None — the existing Axios + cookies setup handles auth.

---

## 11. Prerequisites (External, Non-Code)

- [ ] **Apple Developer account** active ($99/year) — required for Sign in with Apple
- [ ] **Apple Services ID + private key + Team ID + Key ID** — required for backend verification
- [ ] **Google OAuth Client IDs** per platform (Android / iOS) — survive Firebase removal, likely already exist
- [ ] **Fazpass API key + webhook setup** (if applicable) — required for OTP delivery
- [ ] **New env vars provisioned** in all environments (dev, staging, prod):
  - `AUTH_JWT_SECRET`
  - `FAZPASS_API_KEY`, `FAZPASS_BASE_URL`
  - `GOOGLE_OAUTH_CLIENT_IDS`
  - `APPLE_SERVICES_ID`, `APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_PRIVATE_KEY` (PEM contents of the `.p8` file)
  - `ADMIN_EMAIL`, `ADMIN_PASSWORD` (for CC seeding)

---

## 12. Out of Scope for Phase 3.4

- **Password reset for control center** — explicitly deferred (admin-forced reset is the only recovery path)
- **Email delivery infrastructure** (SMTP / Sendgrid / SES) — no emails sent in this phase
- **Cross-app data migration** from the other existing production app — handled separately
- **Merge-on-link** for social login (reject-on-existing for now; merge added later)
- **Valkey-based instant revocation** — pre-wired via `session_id` claim, implementation deferred
- **JWT secret rotation procedure** — documented only, not implemented
- **2FA / MFA** for control center admins
- **Phone number change** flow (re-linking phone to an existing account)
- **Account deletion / soft-delete flow** — separate privacy/compliance work

---

## 13. Prerequisites Before Implementing

Before writing a single line of code:
1. **Apple Developer account** must be purchased and Sign in with Apple configured (Services ID + `.p8` key)
2. **Fazpass account** must be provisioned with API credentials
3. Agreement that the existing halobestie-clone dev database can be wiped and users re-registered (no migration within this phase; cross-app user migration is a separate task)

---

# Tech Stack
- **Backend**: Fastify (existing), PostgreSQL (existing), new deps: `jsonwebtoken`, `bcrypt`, `google-auth-library`, `apple-signin-auth`, Fazpass HTTP integration
- **client_app**: Flutter, `google_sign_in`, `sign_in_with_apple`, `flutter_secure_storage`
- **mitra_app**: Flutter, `flutter_secure_storage`
- **control_center**: React + Vite, httpOnly cookies for refresh tokens
- **Kept**: `firebase-admin` (Messaging only), `firebase_core`, `firebase_messaging` for FCM push