Shelf

Shelf is a private-space utility that can appear on the launcher as a habit
tracker, calendar, or calculator. Each decoy is a functional app with its own
name, icon, and colour scheme.

Five taps in the top-right corner open the credential prompt. Settings adds a
second, quieter gesture: a long or double tap on the decoy title, or the PIN
typed straight into the calculator. Access uses a PIN, a password, a 3×3 pattern, or a
knock code on four unmarked quarters. The knock pad shows a blank screen while
it is entered, so a watcher learns neither the length of the code nor how far
through it you are. Optional strong-biometric unlock always opens the real
space, with the credential as fallback. The entry gesture can also put up a
fake app-has-stopped dialog; a long press on its message carries on to the
credential.

Auto hide runs after screen off, immediately when Shelf leaves the foreground,
or never. It closes the private space and puts exposed folders back out of
sight. A timer can also put them back after a set time with the screen on. An optional quiet notification, under the disguise's own name, offers
the same emergency hide on demand.

Folders you add stay on the list whether or not they are hidden, and one control
hides or unhides all of them at once. A hidden folder can be opened without
unhiding it: photos, video, audio, PDFs, and text are decrypted as they are
read, with nothing written back to disk and no gallery picking them up.

An optional second credential opens a private space that looks and behaves like
the real one and contains nothing that matters, the one to give up if you are
ever made to hand one over. Shelf records that it was used and tells you on your
next real unlock, along with any wrong credentials someone else tried.

A separate emergency PIN destroys the encryption keys and journals as soon as it
is entered at any unlock prompt. Turning the phone face down or plugging in a
USB cable can also lock everything at once.

Folders can be hidden in three ways: with root, by clearing permission bits on
the backing filesystem; with optional all-files access, by moving the folder
under random names into a hidden directory; or with no special permission, by
renaming it with a leading dot through the system folder picker. All three
replace file names with opaque identifiers, protect the first 64 KiB of each
file, and keep the originals in a recovery manifest encrypted with your
credential. Folders at the top of internal storage or in Download need
all-files access, since Android grants no picker access there.

Each folder operation is journalled before anything changes. Recovery markers,
"Unhide everything", read-only health checks, and a password-encrypted export
of recovery records cover reinstalls and lost app data.

The theme follows the system or is fixed to light, dark, or AMOLED. Shelf can be
kept out of the recent apps list, and screenshots of the private space are
blocked unless you allow them.

Root is optional. Shelf has no network access, analytics, advertising, or cloud
service.

Shelf does not provide full-file encryption. Data beyond each protected header
remains recoverable with forensic tools, and historical file names may remain in
system or app caches. Shelf is designed to prevent casual browsing, not resist
an attacker with root access. The full threat model is at
https://github.com/melastore/shelf/blob/main/THREAT_MODEL.md

- Fixed a root-hidden folder getting stuck if it was re-hidden while open in the viewer.
- Root hides that could not reach the files no longer need file access to unhide.
- The calculator opens with a sum that adds up to your PIN.
- Emergency wipe also removes recovery markers and folder access grants.
- A damaged PIN file shows an error instead of counting as wrong tries.
- Viewer files open before their thumbnail loads and show their subfolder.