-
-
Notifications
You must be signed in to change notification settings - Fork 15
Home Passcode
Protect Home or Settings with a 4- or 6-digit passcode. Optional brute-force protection progressively locks input after repeated failures, and the keypad can be shuffled each time it appears.
Introduced in 0.6.0 ("The Circle Is Complete").
A device passcode can protect either Home or Settings.
- Choose a 4- or 6-digit passcode and a custom auto-lock delay.
- Lock Home immediately from the sidebar.
- Optionally shuffle the keypad each time it appears.
- Optional brute-force protection progressively locks input for 1 minute, 5 minutes, 30 minutes and 1 hour after repeated failures.
- Time spent in Settings does not count as Home inactivity; the timer restarts after returning Home.
When Settings is protected, Home remains freely accessible while opening Settings requires the passcode; leaving the settings area locks it again for the next entry. Existing users continue to protect Home by default, preserving upgrade behavior.
Path: Ava Settings → Device Services → Home Passcode
| Setting | Default | Description |
|---|---|---|
| Enable | Off | Activate passcode protection for the chosen target. |
| Lock target | Home | What the passcode protects: Home or Settings. Mutually exclusive. |
| PIN length | 6 | 4 or 6 digits. Changing length resets the passcode to that length's default (0000 / 000000). |
| Passcode | 000000 |
The current passcode. Stored as a salted SHA-256 hash, never in plain text. |
| Auto-lock delay | 30 seconds | Idle seconds on Home before the passcode overlay returns. Range: 5–3600 seconds. |
| Shuffle keypad | Off | Shuffle digit keys to a new layout each time the pad is shown. |
| Brute-force protection | Off | After 5 consecutive wrong unlock attempts, lock the keypad with escalating wait times. |
New installs and first enable default to 6 digits with the default passcode 000000. Legacy installs without a recorded PIN length keep their existing 4-digit hash and continue to use 0000 as the default.
Change the default passcode immediately after enabling. The default is only meant to let you enable protection and then set a real PIN without knowing the length picker upfront.
The lock target is mutually exclusive — the passcode protects Home or Settings, never both at once.
| Target | Behavior |
|---|---|
| Home (default) | The Home workspace is covered by the passcode overlay after the idle timeout. Settings remains freely accessible. Existing users keep this behavior on upgrade. |
| Settings | Home remains freely accessible. Opening Settings requires the passcode; leaving the settings area locks it again for the next entry. |
When the target is Settings, time spent inside Settings does not count toward Home inactivity — the Home idle timer restarts after returning Home.
The sidebar exposes a Lock Home action that covers Home with the passcode overlay right away, without waiting for the idle timeout. This is useful for wall panels and shared devices where the next user should authenticate before interacting.
When Brute-force protection is enabled, the keypad locks after 5 consecutive wrong unlock attempts. The wait escalates with each lockout:
| Lockout level | Wait |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4+ | 1 hour |
- While locked out, the keypad refuses input and shows the remaining wait time.
- A successful unlock resets
failedAttemptsandlockoutLevelto 0. - Disabling brute-force protection clears
failedAttempts,lockoutLevelandlockoutUntilEpochMs.
The maximum lockout level is capped at 4 (1 hour); further failures keep the wait at 1 hour.
The passcode is never stored in plain text.
-
Storage:
home_lock_settings.json(DataStore). -
Hash: SHA-256 of
SALT + pin, whereSALT = "ava.home.lock.v1|". -
Field:
pinHash(hex string). Empty means the default PIN for the currentpinLengthis in effect. -
Length:
pinLengthrecords 4 or 6. Legacy entries withoutpinLengthresolve to 4 if a hash already exists, otherwise 6.
Ava compares the entered PIN by hashing it with the same salt and comparing the result in constant time. The plain PIN is only held in memory long enough to hash it during a change.
All passcode settings live under HomeLockSettings and are persisted in home_lock_settings.json:
| Field | Type | Default | Purpose |
|---|---|---|---|
enabled |
Boolean | false |
Passcode protection active. |
lockTarget |
String | "home" |
"home" or "settings". |
pinHash |
String | "" |
Salted SHA-256 hex of the PIN. Empty = default PIN. |
idleTimeoutSeconds |
Int | 30 |
Home idle seconds before overlay. Range 5–3600. |
pinLength |
Int | 0 |
4 or 6. 0 = legacy unset (resolved at runtime). |
shuffleKeypad |
Boolean | false |
Shuffle digit keys each time the pad shows. |
antiBruteForce |
Boolean | false |
Progressive lockout after 5 wrong attempts. |
failedAttempts |
Int | 0 |
Current consecutive wrong attempts toward next lockout. |
lockoutLevel |
Int | 0 |
How many lockouts have been applied; next wait = level minutes. |
lockoutUntilEpochMs |
Long | 0 |
Wall-clock millis when keypad lockout ends; 0 = not locked out. |
The passcode is stored only as a salted SHA-256 hash and cannot be recovered from the device. To reset it:
- Disable the passcode from Ava Settings → Device Services → Home Passcode (requires reaching Settings — if Settings is the lock target, you need to authenticate once more or clear app data).
- Re-enable with a new passcode.
If Settings is locked and you cannot authenticate, clearing Ava's app data (Android Settings → Apps → Ava → Storage → Clear data) resets all settings including the passcode.
Wait for the lockout to expire. The remaining wait time is shown on the keypad. A successful unlock resets the lockout state.
Increase Auto-lock delay under Ava Settings → Device Services → Home Passcode. The range is 5–3600 seconds.
This is expected when the lock target is Settings. Switch the lock target to Home if you want Home covered instead.
- Home Launcher — the desktop workspace this passcode protects. The launcher's own desktop lock prevents layout edits; the Home passcode prevents entering Home at all.
- Permissions — Shizuku, Root and Device Admin grants used by other device-level features.
Back to Home