Kordant/tasks/shieldai-unified-restructure/36-android-auth-onboarding.md

# 36. Android App — Authentication, Onboarding, and Account Setup

meta:
  id: shieldai-unified-restructure-36
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-34, shieldai-unified-restructure-35]
  tags: [android, jetpack-compose, auth, onboarding, mobile]

objective:
- Build the authentication and onboarding flow for the Android app: login, signup, password reset, and a multi-step onboarding experience. Use native Android authentication where possible (Google Sign-In, Credential Manager) and maintain visual consistency with the web app.

deliverables:
- `android/app/src/main/java/com/shieldai/android/ui/screens/auth/` — Auth screens:
  - `AuthScreen.kt` — Auth container with login/signup toggle
  - `LoginScreen.kt` — Email + password login form
  - `SignupScreen.kt` — Account creation form
  - `ForgotPasswordScreen.kt` — Password reset request
  - `ResetPasswordScreen.kt` — Password reset confirmation
- `android/app/src/main/java/com/shieldai/android/ui/screens/onboarding/` — Onboarding:
  - `OnboardingScreen.kt` — Horizontal pager with 4 steps
  - `PlanSelectionStep.kt` — Tier cards (Basic, Plus, Premium)
  - `WatchlistSetupStep.kt` — Add first email/phone
  - `FamilyInviteStep.kt` — Invite family members
  - `CompleteStep.kt` — Success animation and "Get Started"
- `android/app/src/main/java/com/shieldai/android/ui/screens/auth/BiometricAuthScreen.kt` — Biometric prompt:
  - Uses `BiometricPrompt` from `androidx.biometric:biometric`
  - Face/fingerprint authentication
  - Fallback to device credential
- `android/app/src/main/java/com/shieldai/android/viewmodel/AuthViewModel.kt` — Auth logic:
  - `login(email, password)` → calls API (task 37)
  - `signup(name, email, password)` → calls API
  - `resetPassword(email)` → calls API
  - `signInWithGoogle()` → Google Sign-In
  - `enableBiometricAuth()` → stores credential in EncryptedSharedPreferences
  - `logout()` → clears tokens and state
- `android/app/src/main/java/com/shieldai/android/data/repository/AuthRepository.kt` — Data layer:
  - Token storage in `EncryptedSharedPreferences`
  - API calls via repository pattern

steps:
1. Create auth and onboarding screen directories.
2. **AuthScreen**:
   - `Column` with ShieldAI logo and tagline
   - `TabRow` or custom toggle for Login/Signup
   - `ShieldCard` containing the form
3. **LoginScreen**:
   - `ShieldTextField` for email and password
   - "Remember me" `Switch`
   - "Forgot password?" `TextButton`
   - "Sign In" `ShieldButton`
   - Google Sign-In button (Material `Button` with Google icon)
   - On success: store JWT in `EncryptedSharedPreferences`, navigate to main app
4. **SignupScreen**:
   - Additional fields: name, confirm password
   - Password strength indicator using `ShieldProgressBar`
   - Terms `Checkbox` (required)
   - "Create Account" `ShieldButton`
5. **ForgotPasswordScreen**:
   - Email `ShieldTextField` + submit
   - Success state with instructions
6. **OnboardingScreen**:
   - `HorizontalPager` from `androidx.compose.foundation:pager`
   - 4 pages with `PageIndicator` dots at bottom
   - Step 1: Plan cards with feature comparison
   - Step 2: Input for email/phone with "Add" button
   - Step 3: Email inputs for family invites with "Skip" button
   - Step 4: Success animation using `Lottie` or Compose animation
   - "Get Started" button navigates to Dashboard
7. **BiometricAuthScreen**:
   - `BiometricPrompt` setup with `BiometricManager`
   - `setDeviceCredentialAllowed(true)` for fallback
   - On success: store "useBiometric" flag and credential in `EncryptedSharedPreferences`
   - Show prompt on app launch if enabled
8. **AuthViewModel**:
   - `ViewModel` with `StateFlow` for UI state (`Loading`, `Success`, `Error`)
   - `login()`, `signup()`, etc. methods
   - `signInWithGoogle()` using `com.google.android.gms:play-services-auth`
   - Token management: save to `EncryptedSharedPreferences`, include in API calls
9. **AuthRepository**:
   - Interface + implementation
   - `login(email, password)` returns `Result<AuthToken>`
   - `saveToken(token)`, `getToken()`, `clearToken()`
10. Wire auth state to navigation:
    - `MainActivity` observes auth state
    - Unauthenticated → show LoginScreen
    - Authenticated but new → show OnboardingScreen
    - Authenticated → show Dashboard

steps:
- Unit: AuthViewModel emits correct states for login/signup
- Unit: Password strength calculator returns correct level
- Unit: Onboarding pager advances and collects data
- Integration: Google Sign-In button triggers auth flow
- E2E: Complete login → onboarding → main app flow

acceptance_criteria:
- [ ] Login screen accepts email/password and authenticates via API
- [ ] Signup screen validates inputs and creates account via API
- [ ] Password reset flow sends request to API and shows success state
- [ ] Onboarding has 4 steps with pager indicator and swipe navigation
- [ ] Google Sign-In button works and authenticates user
- [ ] Biometric auth (face/fingerprint) can be enabled after first login
- [ ] Tokens are stored securely in EncryptedSharedPreferences
- [ ] Logout clears all auth state and returns to login screen
- [ ] Auth flow matches web app visual style

validation:
- Run app on emulator, complete login with test credentials
- Verify JWT stored in EncryptedSharedPreferences (use Android Studio Database Inspector or log)
- Test Google Sign-In flow (emulator supports mock Google account)
- Complete onboarding and verify data sent to API
- Test biometric prompt on device (emulator can simulate with Extended Controls)
- Run `./gradlew test` for unit tests

notes:
- Credential Manager (`androidx.credentials:credentials`) is the modern replacement for Google Sign-In. Use it if targeting API 34+; otherwise, use `play-services-auth`.
- `EncryptedSharedPreferences` from `androidx.security:security-crypto` is the standard for secure token storage.
- The onboarding data should be collected in a ViewModel state and submitted to the API at the final step.
- For the success animation in onboarding, consider using Lottie (`com.airbnb.android:lottie-compose`) with a checkmark animation.
- The `BiometricPrompt` should be shown as a system dialog, not a custom screen. The `BiometricAuthScreen.kt` is just a wrapper/helper.
- Handle configuration changes (rotation) correctly: ViewModel survives, but UI state should be restored.