# 26. Permissions Justification & Declarations

meta:
  id: android-production-26
  feature: android-production
  priority: P1
  depends_on: []
  tags: [compliance, play-store, permissions, production]

objective:
- Justify all permissions used by the app and handle permission declarations for Play Store compliance

deliverables:
- Permissions audit report
- In-app permission rationale dialogs
- Play Console permission declarations
- Permission usage documentation

steps:
1. Audit all permissions:
   - Review AndroidManifest.xml
   - Review all uses-permission declarations
   - List each permission and why it's needed:
     - INTERNET: API communication
     - CAMERA: Document scanning, VoicePrint enrollment
     - RECORD_AUDIO: VoicePrint enrollment
     - READ_PHONE_STATE: Call screening (if needed)
     - READ_CALL_LOG: SpamShield (if needed)
     - POST_NOTIFICATIONS: Android 13+ notifications
     - USE_BIOMETRIC: Fingerprint/Face unlock
     - FOREGROUND_SERVICE: Background sync
     - RECEIVE_BOOT_COMPLETED: Schedule background sync
2. Remove unnecessary permissions:
   - Remove any permissions not actually used
   - Remove transitive permissions from old dependencies
   - Use tools-manifest-merger to control merged permissions
3. Add in-app rationales:
   - Show custom dialog before requesting each permission
   - Explain why permission is needed
   - Show feature benefit
   - Add "Don't Allow" and "Allow" buttons
4. Handle permission denials:
   - Degrade functionality gracefully
   - Show guidance to Settings if permission denied
   - Don't crash if permission unavailable
   - Respect user's choice
5. Document in Play Console:
   - Declare sensitive permissions
   - Provide justification for each
   - Explain why alternatives weren't used
6. Test permission flows:
   - First request → rationale → system dialog
   - Deny → feature degraded → Settings guidance
   - Allow → feature fully functional
   - Revoke in Settings → app handles gracefully

tests:
- Unit: Test permission state handling
- Integration: Test rationale dialog flow
- Device: Test all permissions on physical device

acceptance_criteria:
- All permissions justified with clear use cases
- No unnecessary permissions in manifest
- In-app rationale dialogs for all sensitive permissions
- Graceful degradation when permissions denied
- Settings guidance for denied permissions
- Play Console permission declarations complete
- Permission usage documented internally
- No crashes from missing permissions
- All permission flows tested on physical device
- App Review will approve permission usage

validation:
- Check manifest → only necessary permissions present
- Test camera permission → rationale dialog → system dialog
- Deny permission → app shows Settings guidance
- Check Play Console → permission declarations complete
- Review justifications → all accurate and reasonable

notes:
- Google Play requires justification for sensitive permissions
- READ_CALL_LOG and READ_SMS are especially scrutinized
- Call screening may not need READ_CALL_LOG if using CallScreeningService
- Be prepared to appeal if Play Store questions permissions