ObliviOS Developer portal Project site

Home / Decisions / ADR-083

Root-cause and fix a real crash found during physical lynx re-validation of the seven-patch avatar-color/switcher batch.

Accepted, recorded 7 September 2026.

Decision
ADR-083
Date
2026-09-07
Status
AcceptedAccepted, build-verified across all three; hardware re-validation of the combined fix in progress, not yet confirmed
Part
Duress Unlock
Mentions
ADR-073, ADR-078
Mentioned by
ADR-084, ADR-096

1Decision

Root-cause and fix a real crash found during physical lynx re-validation of the seven-patch avatar-color/switcher batch: the decoy's own emulated storage volume was permanently unmountable whenever the owner's real credential had never been entered this boot. Three stacked patches: frameworks/base 0038, 0039, 0040.

2Why and evidence

Entering the registered decoy's PIN directly on a freshly-booted device (owner's own credential never entered this boot) crashed Settings ▸ Storage with IllegalArgumentException: Volume external_primary not found, confirmed via dumpsys dropbox. adb shell sm list-volumes showed the decoy's own volume as permanently unmountable despite the decoy itself being RUNNING_UNLOCKED — not a display artifact, the actual underlying VolumeInfo.state.

A control test (a freshly created, entirely ordinary USER_TYPE_FULL_SECONDARY user, no decoy registration) reproduced the identical state while the owner's session was locked and resolved the moment the owner unlocked for the first time — confirming this is not decoy-specific and not caused by any of 0033-0037. Full record with the complete evidence trail: docs/devices/lynx-duress-decoy-storage-unmount-incident.md.

Root cause resolved to three stacked instances of the same underlying pattern already found once before in this project (ADR-073's UserBackupManagerService bug) — a system service silently assuming user 0 always unlocks before any other user's own lifecycle matters, true on stock Android (you must unlock the primary user to even reach the multi-user switcher) but false by design under Duress Unlock, whose entire point is that the real profile stays genuinely locked through a decoy switch.

(1) StorageManagerService.getVolumeList(int userId, ...) hardcoded isSystemUnlocked(UserHandle.USER_SYSTEM) despite already having the correct target userId in scope, used a few lines later for the sibling check isCeStorageUnlocked(userId); git blame confirmed the hardcoded line dates to an unrelated 2019 refactor (157dd1dc40c5a, "Move legacy obb data migration to a handler thread"), not a deliberate, still-valid decision.

Fixed (0038, real branch SHA 94c6a5e888ed) by checking userId instead — a real, standalone fix on its own merits, but re-testing after this alone still reproduced the identical crash, confirmed via a fresh dumpsys dropbox entry matching the original stack trace and an independent services.jar checksum match ruling out a stale-build repeat of ADR-078's own incident.

(2) adb logcat during a fresh repro (not visible in dumpsys dropbox alone) showed the actual proximate cause: StorageSessionController#onUnlockUser(int userId) only called initExternalStorageServiceComponent() — a one-time, global initialization resolving MediaProvider's ExternalStorageService component, identical for every user — when userId == 0.

If user 0 never unlocks, the component name stays permanently null and no user's storage session, including the decoy's own, can ever bind to it (StorageUserConnection.connectIfNeeded() throws "Not ready to bind").

Fixed (0039, real branch SHA ec3b888a36a5) by guarding on mExternalStorageServiceComponent == null instead of which user triggered the check — same one-time-init outcome for every existing Android flow, correct for the decoy-first case too; mExternalStorageServiceComponent is volatile, and a benign double-init race under concurrent unlocks is possible but harmless (same value resolved either way).

This was a real improvement — adb logcat confirmed onUnlockUser(10) genuinely attempted initialization for the first time — but the attempt itself then failed one layer deeper: initExternalStorageServiceComponent() still hardcoded resolveExternalStorageServiceAsUser(UserHandle.USER_SYSTEM) internally, a third independent instance of the identical pattern.

Confirmed directly on hardware: the identical lookup failed with "No valid ExternalStorageService component found" when resolved as user 0 (never unlocked) and succeeded when resolved as the already-unlocked decoy instead.

Fixed (0040, real branch SHA 4067c29a100d) by threading the actually-unlocking userId through initExternalStorageServiceComponent(int userId) (previously took no parameter) in place of the hardcoded constant; only one call site exists (onUnlockUser, already updated by 0039), so this was a clean, mechanical signature change.

All three authored under AGENTS.md's local-first discipline in the same disposable worktree already used for 0034-0037, landed on the real branch with git am (each applied cleanly, confirmed no build in flight beforehand each time), regenerated fresh via git format-patch as a combined 3-patch series from the real post-git am branch history, and independently verified byte-for-byte reproducible against both touched files in one combined apply-and-diff check.

Each was individually built (m -j6 services, OFFICIAL_BUILD=true reconfirmed each time) and repackaged into a fresh system.img (m -j6 systemimage), with the resulting system.img timestamp checked against the freshly-built services.jar each round to rule out a repeat of ADR-078's out-lynx staleness incident; system_ext.img and the other 10 partitions were confirmed byte-identical to the 0037-era candidate across all three rounds and reused as-is.

Each candidate was signed with the alpha key (SHA256_RSA4096, rollback index 1783209600, --padding_size 65536, matching every prior duress-unlock candidate), 13/13 independently verified on two machines each round, and flashed by the owner.

3Consequences

Two of the three fix attempts (0038 alone, and 0038+0039 together) looked plausible and were built, signed, flashed, and re-tested in good faith as complete fixes, and both were disproven only by direct hardware re-testing against the exact original trigger, not by further static analysis.

The combined 0038+0039+0040 candidate is the currently-flashed state as of this entry; hardware re-validation of the exact original trigger is in progress and genuinely not yet confirmed — this entry must not be read as closing the incident.

Do not trust either symptom check alone when it is eventually re-tested: confirm via sm list-volumes showing mounted, a clean repeat of the Settings ▸ Storage screen with no crash, a clean dumpsys dropbox (no new entry), and no new ExternalStorageServiceException in logcat together, not visual "it didn't visibly crash" by itself — that check alone already disagreed with the device's own evidence once earlier in this same investigation.

4Review when

If a future AOSP/GrapheneOS source sync or manifest bump touches StorageManagerService.getVolumeList() or anywhere in StorageSessionController.java from onUnlockUser() down to initExternalStorageServiceComponent(), re-check these exact lines survived the merge.

Any future audit of this feature's remaining attack surface should grep the wider AOSP tree for UserHandle.USER_SYSTEM/UserHandle.USER_OWNER comparisons and userId == 0-style literal checks inside per-user lifecycle callbacks and their own internal call chains (not just the first method reached from a lifecycle callback), since this exact shape of bug has now been found four times across this project by accident — three of them stacked directly underneath each other in this single incident — rather than by systematic search of a whole call chain up front.

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