testsAndMisc/phone_focus_mode/README.md

Phone Focus Mode

Location-based app restriction for a rooted Android phone using wireless ADB.

When within ~500m of home: only whitelisted productive apps remain usable. When outside that radius: all apps work normally.

Requirements

• Rooted phone with Magisk installed
• Wireless ADB enabled (Settings → Developer options → Wireless debugging)
• adb installed on your PC (sudo apt install adb on Debian/Ubuntu)
• GPS/Location enabled on the phone

Setup (first time)

1. Find your home coordinates

Open Google Maps, right-click your apartment → copy the coordinates shown.

2. Edit config_secrets.sh

HOME_LAT="-48.876667"   # your latitude
HOME_LON="-123.393333"  # your longitude

3. (Optional) Adjust the whitelist in config.sh

To find the exact package name of any app:

./deploy.sh <phone_ip> --find-pkg stronglift
./deploy.sh <phone_ip> --find-pkg anki
./deploy.sh <phone_ip> --find-pkg pomodoro

Then add the correct package name to WHITELIST in config.sh.

4. Deploy

chmod +x deploy.sh
./deploy.sh 192.168.1.42        # replace with your phone's IP

This:

1. Pushes all scripts to /data/local/tmp/focus_mode/ on the device
2. Installs a Magisk service.d script so the daemon auto-starts on boot
3. Starts the daemon immediately

Usage

./deploy.sh <ip> --status    # Current mode, location, distance from home
./deploy.sh <ip> --log       # View recent daemon log
./deploy.sh <ip> --list      # List all apps + whitelist status
./deploy.sh <ip> --enable    # Force focus mode ON (for testing)
./deploy.sh <ip> --disable   # Force focus mode OFF
./deploy.sh <ip> --stop      # Stop daemon entirely (restores all apps)
./deploy.sh <ip> --start     # Start daemon
./deploy.sh <ip> --restart   # Restart daemon (picks up config changes)
./deploy.sh <ip> --pull-log  # Download log file to your PC

How it works

Every 60 seconds:
  get_location()  ─── dumpsys location ──► lat,lon
        │
        ▼
  calc_distance()  ─── Haversine formula ──► meters
        │
        ├── within radius?  ──► enable_focus_mode()
        │                           pm disable-user all non-whitelisted apps
        │                           record which apps were disabled
        │
        └── outside radius? ──► disable_focus_mode()
                                    pm enable each app in the disabled list

Hysteresis: 50m buffer prevents rapid toggling at the boundary. You must travel radius - 50m inward to trigger lock, and radius + 50m outward to unlock.

Fail-safe: If location is unavailable for 5 consecutive checks (~5 minutes), focus mode is automatically disabled so you can't be locked out.

State persistence: The daemon records exactly which apps it disabled (in /data/local/tmp/focus_mode/disabled_by_focus.txt), so it never accidentally re-enables apps that were already disabled by the user before focus mode ran.

On-device control (without PC)

From a root terminal app (e.g. Termux + tsu):

su --mount-master -c 'sh /data/local/tmp/focus_mode/focus_ctl.sh status'
su --mount-master -c 'sh /data/local/tmp/focus_mode/focus_ctl.sh disable'

Why --mount-master: MagiskSU puts each su -c session in an isolated mount namespace by default, so bind mounts made by the hosts enforcer would be invisible (and /data/adb/focus_mode/* checks would fail due to SELinux interactions). --mount-master joins the global namespace where the daemons (started from Magisk service.d at boot) actually live. The boot autostart script doesn't need this flag because post-fs-data already runs there.

File layout

File	Purpose
config.sh	Coordinates, radius, whitelist, constants
focus_daemon.sh	Main daemon — runs on device, loops every 60s
focus_ctl.sh	Control utility — runs on device
curfew_enforcer.sh	Night-curfew enforcer — grayscale + DND + optional net
hosts_enforcer.sh	Bind-mounts hosts.canonical over /system/etc/hosts
magisk_service.sh	Magisk boot hook → auto-starts both daemons
deploy.sh	PC-side ADB deployment and control script

Hosts hardening

A second daemon, hosts_enforcer.sh, locks the phone's /system/etc/hosts to the same blocklist installed by linux_configuration/hosts/install.sh on the PC. Three layers:

1. Canonical copy at /data/adb/focus_mode/hosts.canonical is chattr +i.
2. It is bind-mounted read-only over /system/etc/hosts at boot.
3. A watchdog verifies a sha256 every 15 seconds and restores on mismatch.

This blocks the common echo > /etc/hosts one-liner from a terminal app. It is NOT a guarantee against a determined root user on the device itself — a real "impossible without USB" gate would require removing su access, which would break the rest of this system. The watchdog at least ensures tampering is logged and reverted within ~15s.

Status and logs:

./deploy.sh <ip> --hosts-status
./deploy.sh <ip> --hosts-log

Periodic rescan / Play Store

The focus daemon now re-scans every tick (not just on first entry). If you re-enable an app via Play Store or pm enable, it gets re-disabled within CHECK_INTERVAL_FOCUS seconds. com.android.vending (Play Store), com.*.packageinstaller, and popular terminal apps are also uninstalled --user 0 in focus mode to close the usual bypass paths. Google Play Services (com.google.android.gms) is left alone so banking apps work.

Night curfew (after 23:00 at home)

On top of the location-based focus mode, a time-gated curfew makes the phone boring and largely unusable late at night so you go to sleep instead of doom- scrolling. It activates only when focus mode is already ON (i.e. you are at home) and the local clock is inside the curfew window (default 23:00–05:00). Out of that window, or away from home, nothing changes.

While the curfew is active it applies three allow-list layers — block everything except a short essential list:

1. Apps. The daemon swaps the permissive WHITELIST for the strict NIGHT_WHITELIST (banking, maps, calendar, clock, authenticators, gov ID, workout/diet). Everything else — browsers, social, messaging, email, media, manga, stores — is pm disable-user'd and re-enabled automatically at 05:00. Same proven mechanism as location focus; no new disable path.
2. Display + notifications. curfew_enforcer.sh forces the screen to grayscale and DND to alarms-only, re-applying every 5s so toggling them off in Settings snaps back. (Snap-back is the realistic lock; truly blocking Settings risks system instability, so it is deliberately avoided.)
3. Internet (optional, default OFF). A per-UID iptables allow-list that gives network only to the NIGHT_WHITELIST apps (plus root/system/shell + DNS) and cuts off every other app. Enable CURFEW_NET_ENABLED=1 in config.sh only after validating it on-device (see test hook below).

Configuration (config.sh)

NIGHT_CURFEW_ENABLED=1       # master switch
NIGHT_CURFEW_START="2300"    # local HHMM; window wraps past midnight
NIGHT_CURFEW_END="0500"
CURFEW_GRAYSCALE_ENABLED=1   # force monochrome
CURFEW_DND_ENABLED=1         # force DND alarms-only
CURFEW_NET_ENABLED=0         # per-UID internet allow-list (prove first!)

Edit NIGHT_WHITELIST (right below WHITELIST) to choose what stays usable at night. Allow-list by design: when in doubt, leave it out. The active keyboard and the core dialer/SMS/home apps are always protected automatically (a 1am reboot can never strand you without a keyboard), and the default browser is intentionally not protected at night so it can be disabled.

Control

# On-device (root shell):
focus_ctl.sh curfew-status     # window, enforcer state, what's applied
focus_ctl.sh curfew-test-on    # FORCE curfew now (daytime validation)
focus_ctl.sh curfew-test-off   # clear the force
focus_ctl.sh curfew-off        # escape hatch: suspend curfew now
focus_ctl.sh curfew-on         # re-arm (clear the override)
focus_ctl.sh curfew-log        # enforcer log

Opting out at 2am (no PC)

The companion status notification grows a "Suspend curfew till morning" action while the curfew is active. Tapping it drops the override file (curfew off until you re-arm); the label flips to "Re-arm curfew". The action is hidden during the day so it is not a casual temptation. Without the PC this is the only on-device opt-out — by design. From the PC you can always ./deploy.sh <ip> --restart or run focus_ctl.sh curfew-off over ADB.

Validating before you trust it overnight

Because a misconfigured curfew can lock apps at 2am, validate it during the day with the force hook, not by waiting for 23:00:

focus_ctl.sh curfew-test-on    # mBank + keyboard work, Firefox gone, gray, DND
focus_ctl.sh curfew-test-off   # blocked apps come BACK (the reconcile path)

The clock parser fails open (treated as daytime) on a malformed time, so a broken date can never trap you behind the strict list.

Hotspot / tethering block (closes the "second phone" bypass)

Every other network layer only filters this phone's own traffic: /system/etc/hosts is consulted by the phone's system resolver, and both dns_enforcer and the curfew net layer only touch the OUTPUT chain. When the phone shares its mobile data as a WiFi hotspot, a tethered second phone's packets are FORWARDed + NAT'd through this phone on a path none of that covers — so the second phone browses freely and defeats focus mode.

tether_enforcer.sh closes that hole. It is always-on but only acts while focus mode is ON (i.e. you are at home, current_mode.txt == focus), and converges three levers every TETHER_CHECK_INTERVAL seconds:

1. Disable tether offload — sets settings global tether_offload_disabled 1 so forwarded traffic is actually seen by netfilter instead of being shunted around it by the hardware/BPF fast path. Snapshotted on entry, restored on exit.
2. FORWARD blanket REJECT — an iptables/ip6tables chain (FOCUS_TETHER_BLOCK) pinned at position 1 of FORWARD, rejecting all forwarded packets. This is the version-independent catch-all and covers WiFi, USB and Bluetooth tethering. The phone's own traffic uses OUTPUT/INPUT, never FORWARD, so normal connectivity is untouched. Rebuilt only when tampered (chain-intact gate), so it does not fork an iptables -L every second (that pegged netd and overheated the phone during curfew-net tuning).
3. Stop the softAP (best-effort, WiFi only, Android 11+) — cmd wifi stop-softap each tick so the hotspot toggle visibly flips back off.

On the transition away from home it restores the offload snapshot and tears the FORWARD chain down, leaving tethering usable.

Configuration (config.sh)

TETHER_ENFORCER_ENABLED=1     # master switch
TETHER_CHECK_INTERVAL=5       # re-assert cadence (seconds)
TETHER_STOP_SOFTAP_ENABLED=1  # also actively kill a running softAP

Control

focus_ctl.sh tether-status     # enforcer state, offload flag, FORWARD chain
focus_ctl.sh tether-test-on    # FORCE the block now (daytime validation)
focus_ctl.sh tether-test-off   # clear the force
focus_ctl.sh tether-stop       # escape hatch: stop it, restore tethering
focus_ctl.sh tether-start      # (re)start the enforcer
focus_ctl.sh tether-log        # enforcer log

The escape hatch is tether-stop over ADB (or a fresh deploy.sh), consistent with dns_enforcer/launcher_enforcer — there is no companion-app button. tether_override (created manually) suspends the block without stopping the daemon.

Validating before you trust it

Because Android's tether offload can silently skip the FORWARD rule on some ROMs, validate on-device with a real second phone — do not trust rule counts:

focus_ctl.sh tether-test-on    # hotspot on + second phone browsing → it loses
                               # internet within one interval; this phone stays
                               # online. Watch: focus_ctl.sh tether-log
focus_ctl.sh tether-test-off   # forwarding restored, second phone browses again

If the second phone keeps browsing with the block applied, offload is being bypassed: confirm the exact global key with adb shell su -c 'settings list global | grep -i offload' and update TETHER_OFFLOAD_KEY in config.sh.

Updating

After editing config.sh (e.g. changing whitelist):

./deploy.sh <ip>             # re-pushes all files
# or just the config:
adb push config.sh /data/local/tmp/focus_mode/config.sh
./deploy.sh <ip> --restart

Troubleshooting

Location always unavailable:

• Enable GPS and network location on the phone
• Open Google Maps once to warm up the GPS provider
• The daemon logs every attempt; check with --log

App won't disable:

• Some system apps can't be disabled even as root; they're silently skipped
• Check log for "Failed to disable" warnings

Daemon not starting on boot:

• Verify Magisk is installed and service.d is supported
• Check /data/adb/service.d/99-focus-mode.sh exists and is executable
• Some Magisk versions use /data/adb/post-fs-data.d/ instead; try both

Wrong package name in whitelist:

• Use ./deploy.sh <ip> --find-pkg <keyword> to find the exact package name
• Package names are case-sensitive