Add android/, a normal Gradle/Kotlin project with its own wrapper. It
blocks by interruption: an Accessibility Service watches the foreground
package and a full-screen overlay covers any listed app while the device
is locked (FR-16). No Device Owner, no factory reset, no managed profile.
The client subscribes to the retained restrict/<device>/config topic on
the 8883 TLS plane, keeps the last config on disk so a broker-less device
keeps its rules (FR-14), and reports tampering on its own status topic
(FR-17): a disabled service, a revoked overlay permission, or a
force-stop seen on the next start. The Control Service now parses the
tamper field and raises an Apprise alert, so it reaches Sam.
The block path and the tamper alert are proven on the headless pixel35
emulator on .27; see android/README.md and android/tools/emu-proof.sh.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
The Hub routes by the project name in its human-owned routing.md, which
already names this project `internet_control` (the placeholder row from the
Hub brief). The frozen contract requires the /capabilities name to match that
row, so /capabilities now reports `internet_control` as well.
Found while wiring the live Hub (approved confirmation 60b235f3): the Hub
routed the screen-time question to `internet_control` and returned
`no_client` against a project registered as `internet_use_control`. Aligning
the name, rather than editing the Hub repository or its routing file, makes
the end-to-end round-trip work.
Live proof after the rename and the Hub registration:
POST http://192.168.20.13:8788/ask
{"text":"how long have the kids been on screen today?","asker":"sam","source":"console"}
200 {"status":"ok","answer":"The kids have had 1h 22m of screen time today.",
"route":{"kind":"project","project":"internet_control"}}
Repository, module and service names are unchanged; only the Hub-facing
project string changed.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Build on Phases 1-8. Adds the project side of the frozen Hub contract
(central_ai_llm_master/docs/ask-contract.md) and the alert engine from
AGENTS.md §4 FR-12/FR-13, §8, §11 Phase 9.
- hub: internal/hub implements AskRequest/AskResponse/NotifyRequest and a
deterministic, read-only Answerer. It answers screen time today/yesterday,
what is blocked now, and device presence, scoped to one child or all kids.
Screen time is the foreground-app total per device-day; the domain total is
used only when a device reports no apps, so a report carrying both is never
double-counted.
- apprise: internal/apprise is a small Apprise API client (stored key or
stateless URL mode, optional bearer token, typed notifications).
- alert: internal/alert evaluates device state on an interval and raises one
Apprise alert per transition: a limit hit (a device becomes blocked) or a
device offline longer than the threshold. A never-seen device is never
alerted, and the first observation seeds state without replaying an old
limit. The alert is recorded before delivery, with its delivery outcome.
- store: migration 005 adds `alerts` (delivery outcome, audited) and
`alert_state` (per-device dedup). New usage reads from the telemetry detail
table so the daily answer can be checked independently.
- web: GET /capabilities, POST /ask (read-only) and POST /notify behind the
shared CONTROL_HUB_TOKEN, separate from the session and admin API tokens.
/notify accepts the contract's {from,level,message,person} and delivers it
through Apprise (the future tamper-report path, FR-17).
- cmd/control: start the alert engine (CONTROL_ALERTS_ENABLED,
CONTROL_ALERT_OFFLINE_AFTER, CONTROL_ALERT_INTERVAL) and add `alerts` and
`usage` subcommands for read-only inspection.
- deploy/verify-phase9.sh + `make verify-phase9` prove the definition of done;
version 0.7.0-phase9.
Measured on .13 (2026-10-13):
- GET /capabilities -> internet_use_control topics.
- POST /ask "how long have the kids been on screens today?" -> "The kids have
had 1h 22m of screen time today." (total_seconds=4925); the independent
count from the telemetry detail table is also 4925 (app=4925, domain=4800).
- A manual lock raised a delivered limit alert (id 4); an MQTT offline status
raised a delivered offline alert (id 5); POST /notify delivered (id 6). All
three report delivered=1 in `alerts`.
Tests: gofmt, go vet ./... and go test ./... pass in golang:1.25-alpine.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Build on Phases 1–7. Adds the two override paths from AGENTS.md §4 FR-10/FR-11:
the shared device keycode and the versioned admin HTTP API the separate Kotlin
admin app will call.
- store: migration 004 adds state.grant_until and a settings table. New
overrides.go records every override in `overrides` and verifies the shared
keycode (bcrypt; one code for every device, §10 rule 3). ExpireLocks also
clears an expired grant, and NextScheduleBoundary includes the grant end so a
device re-locks on time.
- effective state: a grant unlocks a device inside a schedule window; a manual
lock clears a grant and a grant clears a manual lock. The retained config
payload gains grant_until (additive, v stays 1).
- web: /api/v1/admin/... (list, state, lock, unlock, grant) guarded by
CONTROL_ADMIN_API_TOKEN, separate from the session login, plus the on-device
keycode endpoint POST /api/v1/device/override with per-address throttling.
A state change is published retained before the API responds.
- cmd/control: `keycode` subcommand and start-up seeding from
CONTROL_DEVICE_KEYCODE_HASH.
- deploy/verify-phase8.sh + `make verify-phase8` prove the definition of done:
an API lock reaches a real broker subscriber in well under a second.
- Version 0.6.0-phase8 (compose, Makefile, docs).
Measured on .13: the lock reached the TLS broker subscriber in 7 ms (handler
1 ms, request to retained publish accepted).
Tests: go vet ./... and go test -count=1 ./... pass in golang:1.25-alpine.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Build on Phases 1–6. Telemetry already arrived on
restrict/<device>/telemetry; this phase stores it in a daily rollup and
shows it.
- store: migration 003 adds telemetry_daily (device, day, app seconds,
site seconds). InsertTelemetry maintains the affected days in the same
transaction; RebuildRollups backfills and repairs it. UsageRange and
TopUsage serve the week grid and top lists. CapAudit enforces the
size-capped append-only audit log from AGENTS.md §7.
- web: GET /devices/{id}/usage — Monday-to-Sunday totals plus the top 10
apps and top 10 sites, using CSP-safe native <progress> bars.
- theme.js: light/dark from the OS preference, with a nav toggle, loaded
as an external script so the strict CSP still holds.
- cmd/control: `rollup` subcommand; rollup rebuild and audit cap at
start-up and every 15 minutes.
- Version 0.5.0-phase7 (compose, Makefile, docs).
Tests: go test ./... and go vet ./... pass in golang:1.25-alpine.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- Weekly schedule editor per device: a Monday-Sunday grid of blocking
windows, including windows that cross midnight.
- Blocklist/allowlist editor per device: app (Android package / Windows
process) and site (hostname) entries, tagged by the device platform.
- Effective desired state: a manual lock, an active schedule window, or
neither. While blocked the allowlist is honoured (Spotify stays while
other apps are blocked). Published retained with reason schedule/manual.
- Boundary-aware republish loop so a window turns on and off on time,
and manual lock expiry is cleared promptly.
- CONTROL_TIMEZONE (default Australia/Sydney) with embedded tzdata, so
wall-clock windows are evaluated in the family zone, not the container.
- Every change is written to the append-only audit log (FR-15).
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Follow-up to the Phase 3 commit (14b304e), after Sam accepted the confirmation
on AUD-80. The operational change itself lives outside this repository; this
commit updates the documentation so it matches reality.
Applied on .13 (backups: mosquitto.conf.bak.aud80-20261013-152648 and
docker-compose.yml.bak.aud80-20261013-152648):
- mosquitto.conf gains per_listener_settings true and
include_dir /mosquitto/config/conf.d; its original 1883 listener and
allow_anonymous true are untouched.
- docker-compose.yml publishes 8883 and mounts the new conf.d and tls
directories (the compose mounts mosquitto.conf as a single file, so the
include_dir fails without them).
- conf.d/webrestrict.{conf,acl,passwd} and tls/{ca.crt,server.crt,server.key}
are installed from deploy/mosquitto/.
- The Control Service now uses tls://host.docker.internal:8883 with the
control-service account and CONTROL_MQTT_INSECURE=false.
Verified live after the restart: the 1883 plane still carries anonymous traffic,
8883 refuses anonymous clients and a wrong password, each device reads only its
own retained config, a device cannot write another device's status or its own
config, and a client killed without DISCONNECT drove the retained will into an
offline transition recorded in SQLite.
Docs: deploy/mosquitto/README.md records the exact host diff, the runbook gap
that caused one restart-loop (the missing bind mounts), the per_listener_settings
deprecation caveat and the rollback. README.md and TRANSPORT_DESIGN.md now
describe the applied state.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- internal/mqtt: publish each device's desired state retained on
restrict/<device>/config; subscribe to restrict/+/status and
restrict/+/telemetry and write reports to SQLite; publish on every state
change, republish on connect and every 15 minutes from SQLite, so the broker
is repaired from the source of truth.
- store: presence (devices.online and last_seen, audited only on transitions),
telemetry upsert per (device, day, app, domain) via migration 002, allow and
block lists read into the config payload, device lookup by topic.
- config: MQTT settings. TLS plus per-device credentials are required; the
pre-TLS shared broker needs an explicit CONTROL_MQTT_INSECURE escape hatch.
- web: republish config after lock, unlock, expiry, create and edit; broker card
on the status partial.
- deploy/mosquitto: TLS listener, topic ACL, credential provisioning and a
verifier that proves the policy on a throwaway broker. Not applied to the
shared Mosquitto on .13 — that change needs Sam's approval.
- cmd/control: mqtt-clients prints the MQTT identity of every device.
- paho.mqtt.golang v1.5.1, which pulls golang.org/x/net and with it the
golang.org/x/crypto bump to v0.42.0.
Verified on .13: retained config delivered to a fresh subscriber; a client
killed without DISCONNECT drove the broker's retained will and the service
flipped the device offline; telemetry landed in SQLite; make mqtt-verify passed
13/13; the service connected over TLS with credentials and a CA.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- Device registry: add/edit name, child and platform, persisted in devices.
- Stable per-device topic derived from name + id, unchanged by renames.
- Desired state persisted in state; timed locks expire and are audited.
- Dashboard cards: name, child, platform, status dot, state and time left.
- Manual lock/unlock forms with CSRF; every change appends to audit (FR-15).
- Append-only activity list on the dashboard. No hard deletes (rule 10).
- Store and handler tests; version bumped to 0.2.0-phase2.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- Go service with its own multi-stage Dockerfile and docker-compose.yml; runs
as container webrestrict-control on port 8791.
- SQLite schema for the full AGENTS.md §7 data model via versioned migrations
(PRAGMA user_version); audit log is append-only.
- Configuration from the process environment; the real env file is gitignored
and a template is committed. No secrets in the repo.
- Separate session login (signed HMAC cookie + CSRF) for Sam.
- GET /health; HTMX + server-rendered dashboard styled with the Family Home Lab
tokens.css (copied) and Inter fonts; dark mode; phone-friendly.
- Caddy vhost for webrestrict.lab.audasmedia.com.au applied on .35 (Let's
Encrypt cert issued); route recorded in deploy/caddy/webrestrict.caddy.
- Unit tests for config, auth and store.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
