Metadata-Version: 2.4
Name: locker-cli
Version: 1.0.0
Summary: Set an iPhone Screen Time passcode (or any keypad code) that you yourself don't know
Author: Uncle Yam
License: MIT
Project-URL: Homepage, https://github.com/uncleyam/locker
Project-URL: Issues, https://github.com/uncleyam/locker/issues
Keywords: screen-time,screentime,passcode,self-control,digital-wellbeing,parental-controls,time-lock,iphone,ios
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Locker

Set a numeric code **that you yourself don't know** - built for the
**iPhone Screen Time passcode**, works for any keypad code of 3-12
digits.

Locker feeds you a long stream of instructions - *tap 7 ... tap
DELETE ... tap 2 ...* - for the target keypad. Decoy taps and real
ones look identical, so the code gets set without you ever learning
it.

## Install

Open a terminal and run the command for your platform:

**Windows**

```
winget install UncleYam.Locker
```

**Linux**

```
pipx install locker-cli
```

**Mac**

```
brew install uncleyam/tap/locker
```

Or clone this repo - the whole tool is one Python file (3.8+, no
third-party packages) - and use the launcher ([locker.cmd](locker.cmd)
on Windows, [locker](locker) on macOS/Linux) from anywhere on your
PATH, e.g. `ln -s "$PWD/locker" ~/.local/bin/locker`.

## Usage

```
locker set              # walk through setting a passcode
locker list             # show all saved passcodes
locker reveal [label|path]   # decode a saved passcode (default: newest)
locker delete <label|path>   # remove a saved passcode and its backups
```

Setting a Screen Time passcode:

1. iPhone: **Settings > Screen Time > Lock Screen Time Settings**,
   stop at the keypad screen.
2. `locker set`. Memorize the 4-digit **memory number** it shows - it
   keeps your verbal memory busy so the real digits can't stick. Then
   follow the taps one at a time (Space or Enter advances, `x` if you
   mistyped). The step count is hidden, so you can't tell when the
   real digits are coming.
3. The re-enter screen gets a **different** sequence ending in the
   same code, so watching twice teaches you nothing.
4. Don't skip the Apple ID recovery prompt - it's your fallback.

| Flag         | Default | Meaning                                       |
|--------------|---------|-----------------------------------------------|
| `--taps N`   | 28      | Target taps per round (randomized within ±4)  |
| `--digits N` | 4       | Code length, 3-12                             |
| `--delay T`  | ask     | Compute cost of a future reveal: `90s`, `5m`, `2h` |
| `--label L`  | ask     | Name for the code, e.g. `iphone`, `kids-ipad` |

Other keypads work too - just set `--digits`. If the keypad has an OK
key (iOS submits by itself), press it after the last tap.

## Recovery

Each code is saved as a labeled file in `~/.locker/`, sealed in a
computational time-lock. `locker reveal` asks for confirmation, then
grinds through the lock with a progress bar; cancelling loses all
progress.

When sealing, Locker measures how fast your computer is and sizes a
math puzzle so that solving it takes the unlock time you chose. The
puzzle is strictly sequential - extra cores don't help - and the key
isn't stored anywhere; it only exists after the computation has been
done. **There is no backdoor other than compute.** (The delay is
calibrated to the machine that created the file; a faster machine
could solve it somewhat quicker. Friction, not time travel.)

`set` also offers a backup copy in a synced folder - OneDrive, iCloud
Drive, Dropbox, Nextcloud, Syncthing, or any folder via
`LOCKER_BACKUP_DIR`. Backups are just as time-locked, and
`locker list` finds them automatically if the original is gone.

---

Screen Time is a feature of Apple iOS. This project is independent
and not affiliated with or endorsed by Apple Inc.

Much of the code was written with AI assistance
([Claude Code](https://claude.com/claude-code)); the design decisions
are human.

MIT licensed ([LICENSE](LICENSE)). Tests: `python -m pytest`.
