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

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").