Kordant/tasks/android-production/26-permissions.md

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