Sam Rolfe
3cf353d933
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>
122 lines
5.3 KiB
Plaintext
122 lines
5.3 KiB
Plaintext
# Control Service configuration — template.
|
|
#
|
|
# Copy to control-service.env and fill in real values. The real file is
|
|
# gitignored and must never be committed. docker compose loads it with env_file.
|
|
#
|
|
# Secrets in this lab also live in ~/.config/environment.d/10-secrets.conf; the
|
|
# same variable names can be exported there instead. The service reads only the
|
|
# process environment, so either source works.
|
|
|
|
# Listen address inside the container.
|
|
CONTROL_ADDR=:8791
|
|
|
|
# SQLite database on the persistent volume.
|
|
CONTROL_DB_PATH=/data/control.db
|
|
|
|
CONTROL_APP_ENV=production
|
|
CONTROL_LOG_LEVEL=info
|
|
|
|
# Timezone weekly schedule windows are evaluated in. Windows are wall-clock, so
|
|
# this must be the family's zone, not the container's default of UTC.
|
|
CONTROL_TIMEZONE=Australia/Sydney
|
|
|
|
# Signs the session cookie. Set to a long random string (>= 16 chars).
|
|
# Generate: openssl rand -hex 32
|
|
CONTROL_SESSION_SECRET=change-me-to-a-long-random-string
|
|
|
|
# Session lifetime (Go duration).
|
|
CONTROL_SESSION_TTL=12h
|
|
|
|
# Secure cookie flag. Keep true behind Caddy/HTTPS. Set false only for
|
|
# plain-HTTP local testing.
|
|
CONTROL_COOKIE_SECURE=true
|
|
|
|
# The single dashboard login (Sam).
|
|
CONTROL_ADMIN_USERNAME=sam
|
|
|
|
# Option A (simple): plaintext password. Constant-time compared at login.
|
|
CONTROL_ADMIN_PASSWORD=change-me
|
|
|
|
# Option B (preferred): a bcrypt hash; leave CONTROL_ADMIN_PASSWORD empty.
|
|
# Generate: docker run --rm --entrypoint /app/control webrestrict/control:0.7.0-phase9 hash-password 'your-password'
|
|
# CONTROL_ADMIN_PASSWORD_HASH=$2a$10$...
|
|
|
|
# --- Admin API (Phase 8) ---------------------------------------------------
|
|
# The versioned HTTP API the separate Kotlin admin app (kotlin_phone_app_admin)
|
|
# calls directly. Its bearer token is SEPARATE from the dashboard session login.
|
|
# Generate a long random value: openssl rand -hex 32
|
|
# When empty the API answers 503 "admin API is not configured" and nothing else
|
|
# changes, so an older deployment keeps working.
|
|
CONTROL_ADMIN_API_TOKEN=change-me-to-a-long-random-token
|
|
|
|
# The shared device keycode (one code, every device — AGENTS.md §10 rule 3).
|
|
# Give a bcrypt hash, never the code itself. Generate one with:
|
|
# docker run --rm --entrypoint /app/control webrestrict/control:0.7.0-phase9 \
|
|
# hash-password 'the-code'
|
|
# The hash is seeded into SQLite at start-up and can be changed later with
|
|
# `docker exec webrestrict-control /app/control keycode`.
|
|
# CONTROL_DEVICE_KEYCODE_HASH=$2a$10$...
|
|
|
|
# --- MQTT (Phase 3) --------------------------------------------------------
|
|
# The broker is transport only. SQLite stays the source of truth, and only the
|
|
# Control Service publishes config (AGENTS.md §10 rules 5-6).
|
|
|
|
# Turn the broker link on or off. With it off the dashboard still works and the
|
|
# config stays in SQLite, unpublished.
|
|
CONTROL_MQTT_ENABLED=true
|
|
|
|
# The shared Mosquitto on `.13`, seen from inside this container. The compose
|
|
# file maps host.docker.internal to the host gateway. The TLS listener on 8883
|
|
# has been live since 2026-10-13 (deploy/mosquitto/README.md).
|
|
CONTROL_MQTT_BROKER=tls://host.docker.internal:8883
|
|
|
|
# The Control Service identity. The broker ACL gives it write access to every
|
|
# config topic and read access to every status and telemetry topic, nothing else.
|
|
# Generate the account with deploy/mosquitto/provision-clients.sh, which writes
|
|
# the values into deploy/mosquitto/clients.env (gitignored).
|
|
CONTROL_MQTT_CLIENT_ID=control-service
|
|
CONTROL_MQTT_USERNAME=control-service
|
|
CONTROL_MQTT_PASSWORD=change-me
|
|
|
|
# PEM bundle used to verify the broker certificate. Required for a tls:// broker.
|
|
# docker-compose.yml mounts deploy/mosquitto/tls/ here read-only.
|
|
CONTROL_MQTT_CA_FILE=/etc/webrestrict/tls/ca.crt
|
|
|
|
# Escape hatch for a broker that has no TLS listener: it allows a plaintext,
|
|
# credential-less link. The service refuses to start without credentials or TLS
|
|
# unless this is true, and it logs a warning when it is. Leave it false against
|
|
# the shared Mosquitto (AGENTS.md §10 rule 6).
|
|
CONTROL_MQTT_INSECURE=false
|
|
|
|
# --- Hub API (Phase 9) -----------------------------------------------------
|
|
# The project side of central_ai_llm_master/docs/ask-contract.md. The Hub sends
|
|
# this bearer token; /capabilities and /ask refuse an unsigned request. When it
|
|
# is empty the three endpoints answer 503 and nothing else changes.
|
|
# Generate: openssl rand -hex 32
|
|
CONTROL_HUB_TOKEN=change-me-to-a-long-random-token
|
|
|
|
# --- Alerts (Phase 9) ------------------------------------------------------
|
|
# Apprise: the house notification gateway on `.35` (AGENTS.md §8). Alerts and
|
|
# accepted notifications are delivered through it (FR-13).
|
|
CONTROL_APPRISE_URL=http://192.168.20.35:8210
|
|
|
|
# Option A: a stored Apprise configuration key.
|
|
# CONTROL_APPRISE_KEY=sam_email
|
|
|
|
# Option B (lab default): the stateless destination list. This is the same
|
|
# shared value as APPRISE_URLS in ~/.config/environment.d/10-secrets.conf.
|
|
# CONTROL_APPRISE_URLS='mailto://user:app-password@gmail.com'
|
|
|
|
# Optional bearer token if the Apprise API is protected. Empty in this lab.
|
|
# CONTROL_APPRISE_TOKEN=
|
|
|
|
# Turn the limit/offline alert engine on. MQTT-style: with it off the service
|
|
# still answers /ask and /notify.
|
|
CONTROL_ALERTS_ENABLED=true
|
|
|
|
# How long a device may be unreachable before Sam is told. Go duration.
|
|
CONTROL_ALERT_OFFLINE_AFTER=30m
|
|
|
|
# How often the alert engine re-evaluates device state. Go duration.
|
|
CONTROL_ALERT_INTERVAL=30s
|