ObliviOS Developer portal Project site

Home / Decisions / ADR-038

Keep GrapheneOS's existing wipe-on-duress-PIN feature.

Accepted, recorded 15 August 2026.

Decision
ADR-038
Date
2026-08-15
Status
AcceptedAccepted
Part
Duress Unlock
Mentioned by
ADR-039, ADR-145

1Decision

Keep GrapheneOS's existing wipe-on-duress-PIN feature (DuressPasswordHelper/DuressWipe) active and unmodified alongside AegisOS's new decoy-profile duress mechanism (docs/superpowers/specs/2026-08-12-duress-unlock-design.md) as two independent, coexisting duress credentials on the same device, rather than replacing wipe with decoy or pausing to redesign.

2Why and evidence

Tracing the keyguard credential call path for the implementation plan (docs/research/duress-unlock-api-verification.md) found that GrapheneOS already ships a complete duress-PIN feature — LockSettingsService.doVerifyCredential's finally block already calls duressPasswordHelper.onVerifyCredentialResult(...) on every failed credential check, and a match triggers DuressWipe.run(): crypto-erasing KeyMint keys and powering off.

Neither the design doc nor the research doc had previously confirmed this mechanism via source, though the design doc's "Why alternatives were rejected" section already discussed the abstract idea of a destructive duress PIN and rejected it as AegisOS's own feature's behavior. That prior rejection was about what AegisOS's new feature should do, not about whether the pre-existing GrapheneOS mechanism should keep running.

Presented to the owner as a genuine fork (coexist / replace wipe with decoy / stop and redesign) rather than assumed, per this project's standing rule to ask rather than pick the convenient interpretation on a security-posture question. The owner chose coexistence.

3Consequences

The design doc is amended with a "Coexistence with upstream GrapheneOS duress password" section naming this ADR. The wipe-PIN path is inherited GrapheneOS hardening and is not touched, weakened, or replaced — consistent with this project's standing rule to never regress a GrapheneOS mitigation even incidentally.

The follow-up implementation plan (not yet written) must specify: how a single failed real-credential attempt is checked against both the wipe-PIN and the decoy-PIN without either check leaking the other's existence via timing or one shadowing the other; how the decoy path's need for a synchronous "matched" response (to actually dismiss the keyguard into the decoy user) coexists with the wipe path's existing asynchronous fire-and-forget hook inside doVerifyCredentialInner without changing either mechanism's guarantees; and a setup UX letting the owner configure two distinct, non-overlapping duress credentials without confusing which does which (the existing DuressPasswordSetupActivity flow is wipe-only and not directly reusable for a second, differently-consequenced credential).

4Review when

Revisit if the implementation plan finds the two mechanisms cannot cleanly coexist inside doVerifyCredentialInner without a timing or collision risk neither alternative in this decision anticipated — at that point the choice between replace-wipe-with-decoy and stop-and-redesign returns to the owner with concrete evidence instead of a hypothetical.

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