restructure tasks

tasks/shieldai-unified-restructure/33-ios-native-features.md

@@ -0,0 +1,114 @@
+# 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").