ObliviOS Developer portal Project site

Home / Decisions / ADR-032

Add android.permission.PACKAGE_USAGE_STATS to Guardian's platform-integration permission set, beyond the three permissions ADR-013/the Guardian platform integration…

Superseded, recorded 6 August 2026.

Decision
ADR-032
Date
2026-08-06
Status
SupersededSuperseded by ADR-240. Accepted
Mentions
ADR-013, ADR-240
Mentioned by
ADR-033, ADR-034, ADR-035, ADR-057, ADR-240

1Decision

Add android.permission.PACKAGE_USAGE_STATS to Guardian's platform-integration permission set, beyond the three permissions ADR-013/the Guardian platform integration design originally scoped.

2Why and evidence

During Task 4 of the Guardian platform integration plan (docs/superpowers/plans/2026-08-05-guardian-platform-integration.md), BackgroundLocationWatcher was found to need a UID's live process importance (foreground vs. background) to correctly scope REVOKE_BACKGROUND_LOCATION to genuinely background access — the design's stated purpose.

Verified directly against the real, synced GrapheneOS source (platform-primary, manifest 2026071500): every API that exposes this (ActivityManager.getUidImportance(int), ActivityManager.addOnUidImportanceListener) is @RequiresPermission(Manifest.permission.PACKAGE_USAGE_STATS) with no narrower alternative (getBindingUidImportance does not apply — it only works for UIDs already bound to the caller, not arbitrary apps).

PACKAGE_USAGE_STATS's confirmed protection level, signature\|privileged\|development\|appop\|retailDemo (core/res/AndroidManifest.xml:7851-7853), carries the privileged flag, so it is obtainable through the same privapp-permissions allowlist mechanism already used for WATCH_APPOPS/GET_APP_OPS_STATS — no platform-signature special case.

Full research trail in docs/research/guardian-platform-api-verification.md's "getUidImportance permission requirement" section. Presented to the owner as a plan-conflict decision (the plan's own Global Constraints capped Guardian at three permissions and required this exact escalation before adding a fourth) rather than added unilaterally; approved 2026-08-06.

3Consequences

docs/security/capability-boundaries.md's Guardian sensor row is updated to name this narrowly: live process-importance reads only, explicitly excluding the broader usage-stats history/data-usage query surface that permission also happens to unlock.

guardian/app/AndroidManifest.xml and guardian/app/privapp-permissions-org.aegisos.guardian.xml (in aegisos-platform, branch guardian-platform-integration) both declare it; guardian-platform-integration.md's Global Constraints section is corrected to list every permission Guardian actually holds at this point — the three privapp-permissions.xml-allowlisted permissions plus PACKAGE_USAGE_STATS (also allowlisted), and REVOKE_RUNTIME_PERMISSIONS/GRANT_RUNTIME_PERMISSIONS (granted via platform signing, not the allowlist — GRANT_RUNTIME_PERMISSIONS was added during Task 3 but never reflected in that section's text until now).

4Review when

If a future Guardian feature would use PACKAGE_USAGE_STATS for anything beyond live process-importance reads (e.g. actual usage-stats history), that is new scope requiring its own review against capability-boundaries.md, not an extension of this entry.

Read from docs/governance/decision-log.md, entry ADR-032.