# 33. iOS App — Push Notifications, Biometrics, Voice Enrollment, Camera

meta:
  id: shieldai-unified-restructure-33
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-28, shieldai-unified-restructure-29, shieldai-unified-restructure-30, shieldai-unified-restructure-31, shieldai-unified-restructure-32]
  tags: [ios, swiftui, native-features, push, biometrics, camera, mobile]

objective:
- Implement native iOS features that differentiate the mobile experience: push notifications via APNs, biometric authentication, voice enrollment with audio recording, and camera integration for document scanning or QR codes.

deliverables:
- `iOS/ShieldAI/Services/PushNotificationService.swift` — Push notification handling:
  - Registers for remote notifications with APNs
  - Handles device token registration with backend (task 14)
  - Processes incoming notifications in foreground and background
  - Deep links to relevant screen based on notification payload
  - Rich notification content (images, actions) via Notification Service Extension
- `iOS/ShieldAI/Services/BiometricAuthService.swift` — Biometric authentication:
  - Evaluates Face ID / Touch ID availability
  - Prompts for biometric authentication
  - Stores credential in Keychain for biometric-protected access
  - Fallback to device passcode
- `iOS/ShieldAI/Views/VoicePrint/RecordingView.swift` — Voice recording UI:
  - Real-time waveform visualization using `AVAudioRecorder` + `CAShapeLayer`
  - Record / stop / playback controls
  - Duration timer
  - Quality check (minimum duration, signal level)
  - Submit enrollment to API
- `iOS/ShieldAI/Views/Common/DocumentScannerView.swift` — Document scanning:
  - Uses `VisionKit` `VNDocumentCameraViewController` (iOS 13+)
  - Captures ID documents or property deeds
  - OCR text extraction using `VNRecognizeTextRequest`
  - Review and retake functionality
- `iOS/ShieldAI/Services/CameraService.swift` — Camera access wrapper:
  - Checks and requests camera/microphone permissions
  - Handles permission denied states with guidance to Settings
- `iOS/ShieldAI/ShieldAI.entitlements` — App entitlements:
  - Push notifications (`aps-environment`)
  - Sign in with Apple (`com.apple.developer.applesignin`)
  - Keychain sharing (if needed)

steps:
1. **Push Notifications**:
   - Add `UIApplicationDelegate` methods or `UNUserNotificationCenterDelegate`
   - `registerForRemoteNotifications()` in `ShieldAIApp.swift` on launch
   - `didRegisterForRemoteNotificationsWithDeviceToken` → send token to backend via `api.notification.registerDevice`
   - `didReceiveRemoteNotification` → parse payload, show local notification if in foreground
   - Handle notification tap: extract `screen` and `id` from payload, navigate via `AppRouter`
   - Create Notification Service Extension target for rich notifications (image attachments)
2. **Biometric Auth**:
   - `LAContext.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)`
   - `evaluatePolicy` with localized reason: "Authenticate to access ShieldAI"
   - On success: unlock Keychain item containing refresh token
   - On failure: show password fallback
   - Add toggle in Settings to enable/disable biometric auth
3. **Voice Recording**:
   - Request microphone permission (`AVAudioSession.requestRecordPermission`)
   - Configure `AVAudioSession` for recording
   - `AVAudioRecorder` with `.wav` format, 16kHz, mono
   - Real-time waveform: read `averagePower(forChannel:)` in a timer, update `Path` in `Canvas`
   - Minimum duration: 5 seconds
   - On stop: playback with `AVAudioPlayer`, then submit to `api.voiceprint.createEnrollment`
4. **Document Scanner**:
   - `VNDocumentCameraViewController` for capture
   - `VNRecognizeTextRequest` for OCR on captured image
   - Display recognized text for user review
   - Use for: ID verification, property deed upload, broker opt-out form scanning
5. **Camera Service**:
   - Centralized permission manager for camera and microphone
   - `AVCaptureDevice.authorizationStatus(for: .video/audio)`
   - Show explanatory UI before requesting permission
   - Handle `.denied` and `.restricted` states
6. Update `Info.plist`:
   - `NSMicrophoneUsageDescription`: "ShieldAI needs microphone access to enroll your voice for clone detection."
   - `NSCameraUsageDescription`: "ShieldAI uses the camera to scan documents and verify your identity."
   - `NSFaceIDUsageDescription`: "Use Face ID to securely access your ShieldAI account."
   - `UIBackgroundModes`: `remote-notification`
7. Test on physical device (simulator cannot test push notifications or biometrics accurately).

steps:
- Unit: BiometricAuthService returns correct availability state
- Unit: CameraService returns correct permission status
- Integration: Push token registration sends correct data to backend
- E2E: Receive test push notification and verify deep link navigation
- E2E: Record voice sample and submit enrollment successfully
- E2E: Scan document and verify OCR text extraction

acceptance_criteria:
- [ ] App registers for push notifications and sends device token to backend
- [ ] Incoming push notifications display correctly in foreground and background
- [ ] Tapping a notification deep links to the correct screen
- [ ] Face ID / Touch ID authentication works for app unlock
- [ ] Voice recording captures audio, shows waveform, and submits enrollment
- [ ] Document scanner captures images and extracts text via OCR
- [ ] All permission requests include explanatory descriptions
- [ ] Denied permissions show helpful guidance to Settings app
- [ ] Native features work on both iPhone and iPad

validation:
- Test push notifications using APNs test tool or Firebase Console
- Verify biometric auth on device with Face ID/Touch ID
- Record a 10-second voice sample and verify enrollment created in backend
- Scan a printed document and verify OCR text matches
- Run unit tests via Xcode Cmd+U

notes:
- Push notifications require an Apple Developer account and APNs certificate/key. For development, use the sandbox environment.
- The Notification Service Extension runs in a separate process and has limited memory (~24MB). Keep image processing lightweight.
- Voice recording quality matters for ML model accuracy. Use 16kHz mono WAV — this matches the web app's preprocessing pipeline.
- Document scanning with VisionKit is iOS 13+. For older versions, fall back to `UIImagePickerController`.
- Biometric auth should be optional. Users can always use password login.
- Consider adding a "Quick Actions" 3D Touch / Haptic Touch menu for common actions ("Run DarkWatch scan", "Check number").