internet_use_control/README.md

# Internet Use Control — Control Service

The **Control Service** is the brain and the single source of truth for the
Internet Use Control project (`SYSTEM_MAP.md`). It holds schedules, blocklists,
per-device state and usage, and serves the web dashboard. Only it publishes
device config.

This repository currently contains **Phase 8 — Overrides** (AGENTS.md §11), on
top of Phases 1–7:

- Go service with its own image (`Dockerfile`) and compose file.
- SQLite schema for the whole data model (§7), applied through versioned
  migrations.
- Configuration from the process environment (`environment.d`); no secrets in
  the repo.
- A separate session login for Sam.
- `GET /health`.
- HTMX + server-rendered dashboard styled with the Family Home Lab design
  system (`tokens.css` copied in).
- **Device registry**: add and edit a device, assign it to a child, choose its
  platform. Persisted in `devices`.
- **Dashboard cards**: name, child, platform, status, current state, time left.
- **Manual lock/unlock** from the dashboard, persisted in `state` and written
  to the append-only `audit` log (FR-15).
- **MQTT**: each device's desired state is published *retained* on
  `restrict/<device>/config`; device status and telemetry are subscribed and
  written to SQLite; presence comes from the broker's Last Will and Testament.
  The broker is transport only — SQLite stays the source of truth.
- **Weekly schedules**: a per-device grid of blocking windows, Monday to Sunday,
  including windows that cross midnight. The Control Service computes the
  *effective* state — manual lock or active window — and republishes it at each
  window boundary, so a schedule turns on and off with nobody touching it.
- **Blocklist / allowlist**: per-device `app` (Android package or Windows
  process) and `site` (hostname) entries. While a device is blocked, the device
  blocks every blocklist value **except** the allowlist values (Spotify at
  night). That allow decision is in the published config.
- **Usage**: telemetry reports are stored per device, day, app and domain and
  rolled up into a daily summary. The dashboard shows a week at a time — the
  daily total plus the top apps and top sites — with dark mode and phone-sized
  touch targets.
- Every edit is written to the append-only audit log (FR-15).
- **Overrides**: a versioned admin HTTP API for the separate Kotlin admin app
  (`lock`, `unlock`, `grant`, query state) guarded by a bearer token, plus the
  shared device keycode (one code, every device) that a kid's client can redeem
  for a short exemption. Both are recorded in `overrides` and `audit`, and a
  state change is published retained before the API responds.

Enforcement itself (the kids' clients) and the Hub arrive in later phases.
Nothing here touches the router, Pi-hole, or DNS.

## Quick start (on `.13`)

```bash
cd /home/sam/paseo/projects/internet_use_control

# 1. Create the env file from the template and set real values.
cp environment.d/control-service.env.example environment.d/control-service.env
$EDITOR environment.d/control-service.env

# 2. Build and start. Own image, own container, port 8791.
docker compose up -d --build

# 3. Prove it.
curl -s http://127.0.0.1:8791/health
# {"status":"ok","service":"control-service","version":"0.6.0-phase8",...}
```

Open <http://127.0.0.1:8791/> in a browser. It redirects to `/login`. Sign in
with `CONTROL_ADMIN_USERNAME` and `CONTROL_ADMIN_PASSWORD`.

## Configuration

All configuration is environment variables. Docker Compose loads them from
`environment.d/control-service.env` (gitignored). The variables can also be
exported from `~/.config/environment.d/10-secrets.conf` instead; the service
reads only the process environment.

| Variable | Default | Purpose |
|---|---|---|
| `CONTROL_ADDR` | `:8791` | Listen address |
| `CONTROL_DB_PATH` | `/data/control.db` | SQLite file |
| `CONTROL_SESSION_SECRET` | — (required) | Signs the session cookie, ≥ 16 chars |
| `CONTROL_SESSION_TTL` | `12h` | Session lifetime |
| `CONTROL_COOKIE_SECURE` | `true` | Secure cookie flag; keep true behind HTTPS |
| `CONTROL_ADMIN_USERNAME` | `sam` | Dashboard login |
| `CONTROL_ADMIN_PASSWORD` | — | Plaintext password (option A) |
| `CONTROL_ADMIN_PASSWORD_HASH` | — | bcrypt hash (option B, preferred) |
| `CONTROL_ADMIN_API_TOKEN` | — | Bearer token for the versioned admin API (Phase 8); empty disables it with 503 |
| `CONTROL_DEVICE_KEYCODE_HASH` | — | bcrypt hash of the shared device keycode, seeded into SQLite at start-up |
| `CONTROL_APP_ENV` | `production` | Label shown in the footer |
| `CONTROL_LOG_LEVEL` | `info` | `debug`/`info`/`warn`/`error` |
| `CONTROL_TIMEZONE` | `Australia/Sydney` | IANA zone weekly windows are evaluated in |
| `CONTROL_MQTT_ENABLED` | `true` | Turn the broker link on or off |
| `CONTROL_MQTT_BROKER` | `tcp://host.docker.internal:1883` | Broker URL; `tls://…:8883` once the TLS listener exists |
| `CONTROL_MQTT_CLIENT_ID` | `control-service` | MQTT client id |
| `CONTROL_MQTT_USERNAME` | — | Control Service broker account |
| `CONTROL_MQTT_PASSWORD` | — | its password |
| `CONTROL_MQTT_CA_FILE` | `/etc/webrestrict/tls/ca.crt` | PEM bundle that verifies the broker (TLS only) |
| `CONTROL_MQTT_INSECURE` | `false` | Allow a plaintext, credential-less broker. Only for a broker with no TLS listener |

Generate a bcrypt hash without host Go:

```bash
docker run --rm --entrypoint /app/control webrestrict/control:0.6.0-phase8 \
  hash-password 'your-password'
```

`CONTROL_MQTT_USERNAME`/`CONTROL_MQTT_PASSWORD` are required unless
`CONTROL_MQTT_INSECURE=true`, and a non-TLS broker is refused unless
`CONTROL_MQTT_INSECURE=true` (AGENTS.md §10 rule 6). The escape hatch exists for
a broker that has no TLS listener; the running deployment on `.13` does not use
it. Since 2026-10-13 the shared Mosquitto also serves a TLS listener on 8883
with per-device credentials and a topic ACL
(`tls://host.docker.internal:8883`), so `CONTROL_MQTT_INSECURE=false`.
`deploy/mosquitto/README.md` is the design, the apply runbook and the rollback.

## MQTT (Phase 3)

Broker: the shared **Mosquitto on `.13`**. A second broker is not added
(§10 rule 6).

| Topic | Direction | Retained | Payload |
|---|---|---|---|
| `restrict/<device>/config` | service → device | yes | desired state |
| `restrict/<device>/status` | device → service | yes | presence (`online`) |
| `restrict/<device>/telemetry` | device → service | no | usage totals for a day |

- `<device>` is `restrict/<slug>_<id>` from `devices.topic`, which is stored when
  the device is created and never changes. `<id>` is its MQTT username.
- The service publishes each device's config **retained** on startup, after every
  lock, unlock, expiry, create and edit, and again every 15 minutes so a broker
  that lost its retained store is repaired from SQLite.
- Devices use the **8883 TLS listener** with one account each; the broker's ACL
  lets a device read only its own config and write only its own status and
  telemetry, and the Control Service is the only identity that may publish
  config.
- A device registers the will `{"online": false}` on its status topic, so the
  broker reports the drop the moment the connection dies. That is presence
  (FR-6); no polling.
- Reports are written to SQLite. Telemetry is a rolling daily total per
  (device, day, app, domain), so a repeated report replaces the row rather than
  adding to it (migration 002).

### Config payload (v1)

```json
{"v":1,"device_id":1,"name":"Harry's phone","platform":"android",
 "locked":true,"until":"2026-10-13T21:00:00Z",
 "allow":["com.spotify.music"],"block":["com.youtube.android","roblox.exe"],
 "reason":"schedule","generated_at":"2026-10-13T03:30:27Z"}
```

`allow` and `block` are always arrays, never `null`. `locked` and `until` are the
**effective** state: a `reason` of `schedule` means a weekly window is active,
`manual` means a lock was set from the dashboard or the admin API, and `grant`
means a time-limited exemption is active, in which case `grant_until` (RFC3339)
is set and `locked` is false. While `locked` is true the device blocks every
`block` value **except** the `allow` values (FR-4), so the allowlist is the
exception list. A client must ignore unknown fields, so this shape can grow.

### Status payload (device → service)

```json
{"online":true,"app":"com.spotify.music","at":"2026-10-13T03:30:27Z"}
```

The will the device registers on the same topic is `{"online":false}`. A report
with no `online` field counts as online, because the device just talked to us.

### Telemetry payload (device → service)

```json
{"day":"2026-10-13",
 "apps":[{"name":"com.spotify.music","seconds":600}],
 "domains":[{"name":"youtube.com","seconds":120}]}
```

A flat single-row form (`{"app":"…","seconds":600}`) is also accepted. Seconds
are totals for `day`, in `YYYY-MM-DD`; a missing or malformed day uses today.

List the MQTT identity of every device (tokens, no secrets):

```bash
docker exec webrestrict-control /app/control mqtt-clients
```

## Endpoints (Phase 2–7)

| Method | Path | Notes |
|---|---|---|
| `GET` | `/health` | JSON. `status: ok`, database check. No auth. |
| `GET` | `/login` | Session login form. |
| `POST` | `/login` | Verifies credentials, sets a signed session cookie. |
| `POST` | `/logout` | Clears the session. |
| `GET` | `/` | Dashboard: service status, device cards, recent activity. |
| `GET` | `/partials/status` | HTMX fragment, polled every 10 s. |
| `GET` | `/devices/new` | Add-device form. |
| `POST` | `/devices` | Creates a device. |
| `GET` | `/devices/{id}/edit` | Edit-device form. |
| `POST` | `/devices/{id}` | Updates name, child, platform. |
| `POST` | `/devices/{id}/lock` | Locks now; optional `minutes` (0 = until unlocked). |
| `POST` | `/devices/{id}/unlock` | Unlocks now. |
| `GET` | `/devices/{id}/schedule` | Weekly schedule editor (grid of windows). |
| `POST` | `/devices/{id}/schedule` | Replaces the device's windows; `clear=1` clears them. |
| `GET` | `/devices/{id}/lists` | Blocklist / allowlist editor. |
| `POST` | `/devices/{id}/lists` | Adds one entry (`table=block|allow`, `kind=app|site`, `value`). |
| `POST` | `/devices/{id}/lists/{entryID}/delete` | Removes one entry. |
| `GET` | `/devices/{id}/usage` | Usage for one device: a week of daily totals, top apps and top sites. `?week=YYYY-MM-DD` selects the week (any day in it; default today). |

### Admin API (Phase 8)

All admin endpoints are under `/api/v1`, use JSON, and require
`Authorization: Bearer $CONTROL_ADMIN_API_TOKEN`. This token is **separate** from
the dashboard session login. Responses use one envelope:

```json
{"ok":true,"action":"lock","device":{"id":1,"name":"Harry's phone",
  "child":"Harry","platform":"android","topic":"restrict/harry_s_phone_1/config",
  "online":true,"last_seen":null,"locked":true,"until":"2026-10-13T21:00:00Z",
  "grant_until":null,"reason":"manual","updated_at":"2026-10-13T10:29:59Z"}}
```

| Method | Path | Body | Notes |
|---|---|---|---|
| `GET` | `/api/v1/admin/devices` | — | Every device with its effective state. |
| `GET` | `/api/v1/admin/devices/{id}` | — | One device. `404` if unknown. |
| `POST` | `/api/v1/admin/devices/{id}/lock` | `{"minutes":30}` or `{"until":"2026-10-13T21:00:00+11:00"}` or `{}` | Lock now. `{}` means until unlocked; the two time fields are mutually exclusive. |
| `POST` | `/api/v1/admin/devices/{id}/unlock` | `{}` or empty | Clear the manual lock and any grant. |
| `POST` | `/api/v1/admin/devices/{id}/grant` | `{"minutes":30}` or `{"until":"…"}` | Grant time: unlocked until then, even during a schedule window, then the schedule re-applies. A time is required. |
| `POST` | `/api/v1/device/override` | `{"device_id":1,"keycode":"…","minutes":15}` | The on-device keycode path. **No bearer token.** Wrong codes are throttled and audited. |

`minutes` is capped (grants at 24 h, locks at 7 days). Errors are
`{"ok":false,"error":"…"}` with `400` (bad body), `401` (bad token or
keycode), `404` (unknown device), `429` (keycode throttled) or `503` (admin API
or keycode not configured). A `200` means the state was stored **and** the
retained config was accepted by the broker, so the device changes without a
poll.

Every form POST needs the `csrf` field from the session cookie. State changes
append to the `audit` table and republish the device's retained config. Devices
are never hard-deleted (§10 rule 10).

## Telemetry and usage (Phase 7)

Usage arrives on `restrict/<device>/telemetry` and is stored in `telemetry`:
one row per (device, day, app, domain), where a repeat report for the same key
replaces the earlier total (a rolling daily total, not a delta).

`telemetry_daily` is the **daily rollup** — one row per (device, day) — written
together with the detail row and rebuildable from it with `control rollup`.
Apps and domains are summed into separate columns on purpose: a report may
carry both for the same session, so a single total would double-count the time.
The rollup is derived data, never a second source of truth.

`GET /devices/{id}/usage` shows one Monday-to-Sunday week: the app total and the
site total per day, then the top 10 apps and top 10 sites for the week. The
screen uses the Family Home Lab tokens, follows the OS light/dark preference
(there is a toggle in the nav bar), and works on a phone browser.

Retention:

- The daily rollup is kept long; the detail table is small and kept too.
  Nothing is hard-deleted (AGENTS.md §10 rule 10).
- The append-only `audit` log is **size-capped** at 20 000 rows by the service's
  maintenance loop, oldest first (§7). It is never edited in place.

Rebuild the rollup from the detail table at any time (idempotent, safe while the
service is up; the service also does it at start-up and every 15 minutes):

```bash
# inside the container
docker exec webrestrict-control /app/control rollup
# or against a database file on the host
/app/control rollup --db /data/control.db
```

## Schedules, blocklists and allowlists (Phase 6)

A **schedule** is a set of weekly blocking windows per device: a weekday
(Monday = 0 … Sunday = 6), a local `HH:MM` start and end, and an end earlier than
the start means the window crosses midnight (Monday 20:00–07:00 ends Tuesday
07:00). A window means restrictions are **ON** during that time.

The **effective state** is a manual lock, an active window, or neither. The
Control Service computes it and publishes it retained. A manual lock with no end
time (“until I unlock”) never lifts; otherwise the later of the manual end and
the covering window's end is used. A background loop republishes at the next
window boundary, so a window starts and ends on time without a poll.

A **blocklist** entry is blocked while a window is active or the device is
locked. An **allowlist** entry (each entry is `app` or `site`) is the exception
list: the device blocks every blocklist value *except* the allowlist. For
example, with `com.spotify.music` allowlisted and `com.youtube.android` blocked,
Spotify stays available and YouTube does not. Hostnames are lower-cased; app
values keep their case.

## Overrides (Phase 8)

An **override** is a deliberate change to a device's desired state. There are
two paths (AGENTS.md §4 FR-10):

1. **The admin app**, over the versioned HTTP API above. It is the remote
   lock/unlock/grant surface.
2. **The device keycode**, entered on the kid's device. One code is shared by
   every device (§10 rule 3). A correct code grants a short exemption through
   `POST /api/v1/device/override`; the clients in Phases 4–5 will call it.

Semantics:

- **lock** sets the manual lock (`state.locked`). With no end it never lifts;
  with an end it lifts at that time.
- **unlock** clears the manual lock and any grant, returning the device to its
  schedule.
- **grant** unlocks the device until its end, even inside a schedule window, and
  records `grant_until`. When the grant ends the weekly schedule applies again —
  the Control Service treats the grant end as a republish boundary, so the
  device re-locks on time.

Every override is written to the `overrides` table and to the append-only
`audit` log (FR-15), with the actor: `admin-api`, `device-keycode`, or `sam`
from the dashboard. A lock clears a grant and a grant clears a lock, so the two
cannot contradict each other.

### The shared device keycode

The code is never stored or logged in plaintext. It is a bcrypt hash in SQLite.
`CONTROL_DEVICE_KEYCODE_HASH` seeds the first run; after that the stored code is
authoritative, so a change made with `control keycode` survives a restart:

```bash
# Set a code you choose (read from stdin, so it never reaches the process list).
docker exec -i webrestrict-control /app/control keycode <<< '246810'

# Or generate a random six-digit code and print it once to put on each device.
docker exec webrestrict-control /app/control keycode --generate
```

The keycode endpoint is throttled: five wrong codes from one address freeze that
address for five minutes, and every attempt is audited. It returns `503` when no
keycode is configured.

### Prove a lock reaches a device in under a second

The Phase 8 definition of done. `make verify-phase8` issues a lock through the
API and measures the time until a broker subscriber receives the retained
`restrict/<device>/config` message:

```bash
make verify-phase8
```

It needs the `control-service` broker credentials
(`deploy/mosquitto/clients.env`) and a device that exists. It never restarts or
reconfigures anything shared.

## Development

There is no host Go toolchain on `.13`; use the cached builder image.

```bash
make test          # go test ./... in golang:1.25-alpine
make vet           # go vet ./...
make build         # build the container image
make up            # docker compose up -d --build
make logs          # follow container logs
make mqtt-verify   # prove TLS + credentials + ACLs on a throwaway broker
make verify-phase8 # prove an API lock reaches a device in under a second
```

`make test` and `make vet` run the container as your own user and keep the module
cache in `.gocache/` (gitignored), so nothing in the repository ends up owned by
root. `make mqtt-verify` never touches the shared Mosquitto: it stages a scratch
broker on `127.0.0.1:18883` and removes it afterwards.

## Layout

```
cmd/control/            service entry point (+ hash-password, mqtt-clients, rollup, keycode)
internal/config/        environment configuration
internal/store/         SQLite open, migrations, audit, devices + state
  devices.go            device registry, desired state, lock + grant expiry
  schedules.go          weekly windows and the effective state (incl. grants)
  reports.go            presence, telemetry, the daily rollup, top lists, audit cap
  lists.go              allow/block lists and device lookup by topic
  overrides.go          override history + the shared device keycode
  migrations/001_init.sql … 004_overrides_grant.sql
internal/auth/          signed-cookie session login + CSRF
internal/mqtt/          the broker link: retained config out, reports in
  payload.go            topic and payload contract for the kids' clients
  link.go               paho client, subscriptions, publish, TLS verification
internal/web/           HTTP handlers, templates, static assets
  devices.go            device registry + manual lock/unlock handlers
  admin_api.go          versioned admin API + the device keycode endpoint
  schedules.go          weekly schedule and block/allow editors
  usage.go              usage screen: week grid, top apps, top sites
  templates/            login, dashboard, device form, editors, usage, partials
  static/               tokens.css (Family Home Lab), app.css, theme.js, htmx, fonts
Dockerfile              own image (multi-stage, CGO-free)
docker-compose.yml      own container, port 8791
environment.d/          control-service.env.example (real file gitignored)
deploy/caddy/           Caddy vhost for webrestrict.lab.audasmedia.com.au
deploy/mosquitto/       TLS listener, credentials, topic ACL, verifier
```

## Caddy

`deploy/caddy/webrestrict.caddy` holds the vhost for
`webrestrict.lab.audasmedia.com.au`. The terminating Caddy runs on `.35`
(sam-Ubuntu1); see that file for the two proxy patterns and the apply commands.

## Non-goals (Phase 8)

- No grant button in the dashboard. Grant is on the admin API; the dashboard has
  lock and unlock. Adding the button is a later UI change.
- No per-child or per-device keycode. One code, every device (§10 rule 3).
- No HTTP telemetry ingest and no kids' clients (Phases 4–5). The topic and
  payload contract above is what they implement.
- No Hub contact (Phase 9).