- Decision
- ADR-039
- Date
- 2026-08-15
- Status
- AcceptedAccepted
- Part
- Duress Unlock
- Mentions
- ADR-038
- Mentioned by
- ADR-040, ADR-042
1Decision
Accept the Duress Unlock keyguard integration design (docs/superpowers/specs/2026-08-15-duress-keyguard-integration-design.md), resolving all three items ADR-038 left open, and retire two pieces of the already-merged duress-unlock-core module's original scope: its PBKDF2 credential-hash matching, and its consumption as a runtime Binder-called app module.
2Why and evidence
Brainstormed through the three ADR-038 open items in order.
(1) Dispatch order/collision: resolved by always paying the real per-profile Gatekeeper check's cost on every failed real-credential attempt — a registered decoy gets a genuine verifyCredential(credential, decoyUserId) call, an unregistered one gets an equivalent-cost dummy — which closes the timing side-channel a conditional call would create, and naturally avoids the wipe/decoy hooks shadowing each other since a decoy match already returns "matched" before the wipe hook's own finally block runs.
(2) Because the real Gatekeeper check is now always paid and authoritative, duress-unlock-core's own PBKDF2 hash comparison stops mattering for the match decision — keeping it would mean maintaining two independent security-critical comparison paths for no remaining benefit, so it is retired in favor of Gatekeeper's hardware-backed, anti-hammering guarantees.
That, in turn, meant confronting where the routing logic actually runs: duress-unlock-core is a plain JVM/Gradle module built for an app process, but the hook must execute synchronously inside system_server, where an out-of-process Binder dependency on a separate app's liveness would be a reliability regression at the OS's single most security-critical hook — exactly why GrapheneOS's own DuressPasswordHelper is in-tree/in-process rather than a separate app.
Decided to port the routing logic into frameworks/base as new framework-internal Java instead, with duress-unlock-core demoted to validated-reference-implementation status.
(3) Setup UX: a new AegisOS Settings flow (not a reuse of the wipe-only DuressPasswordSetupActivity) that re-authenticates the owner, creates/selects a Private-Space-type profile, and rejects a candidate decoy PIN that collides with the configured wipe-PIN using the wipe feature's own existing DuressCredentials.verify() — real collision prevention without ever storing or comparing plaintext across the two setup flows.
3Consequences
duress-unlock-core's DuressProfileState conceptually shrinks to Off/Registered(profileId) — the credential-hash fields and DuressCredentialMatcher's comparison logic are no longer part of the runtime path; the implementation plan decides their literal fate (deleted vs. left as reference). No code changes landed from this ADR alone — it authorizes the design, not an implementation. The actual frameworks/base patch, new Settings activities, and framework-internal tests remain future implementation-plan work against the real platform source tree, which this repository does not hold.
4Review when
Revisit if the implementation plan finds the framework-internal port cannot cleanly reuse LockSettingsStorage or the DuressCredentials.verify() collision check as assumed here, or if real-hardware timing measurement (still deferred, per the design's own "Testing" section) finds the symmetric-cost dispatch is not actually symmetric in practice.
Read from docs/governance/decision-log.md, entry ADR-039.