48 lines
4.4 KiB
Markdown
48 lines
4.4 KiB
Markdown
# Parental Controls Dashboard with OPNsense Alias Blocking
|
||
|
||
**Date:** 2026-05-18
|
||
**Project:** ha-parental-controls
|
||
**Status:** resolved
|
||
**Tags:** home-assistant, opnsense, firewall-alias, dhcp, websocket, rest_command, input_text, dashboard
|
||
|
||
## Context
|
||
Jess wanted a Home Assistant panel to block and unblock internet access per child and per device, backed by the OPNsense firewall, with optional scheduled access windows. The first version (2026-05-10) worked in principle but hit a series of problems over the following week: WebSocket timeouts on load, broken HA auth handshake, config too large for a single `input_text`, OPNsense rejecting alias updates, and tablets needing credentials entered on every device.
|
||
|
||
## Key Decisions
|
||
- **OPNsense firewall alias (`parental_blocked`) + one LAN block rule** — HA only adds/removes IPs from the alias; no per-device firewall rules to manage.
|
||
- **Identify devices by MAC, resolve to current IP at block time** — blocks re-apply automatically when a device reconnects with a new IP.
|
||
- **Standalone HTML panel (`panel_iframe`) instead of Lovelace cards** — the UI (users, devices, toggles, schedules) is too interactive for core cards.
|
||
- **Device discovery/status from an OPNsense DHCP lease REST sensor** rather than `device_tracker` entities alone — gives hostnames, addresses and expiry in one place.
|
||
- **Config persisted in HA, chunked across 12 `input_text` entities (12 × 255 = 3060 chars)** — a single `input_text` with max 10000 is invalid (HA caps at 255), and HA storage means config is shared across devices, unlike localStorage.
|
||
- **REST API for initial state load, WebSocket for live updates** — loading all states over WS timed out; WS timeout raised to 60s.
|
||
- **OPNsense `alias_util` calls use a JSON payload** — the API rejects form-encoded bodies.
|
||
- **Auto-detect HA URL from `window.location.origin`** — works over HTTP, HTTPS, LAN IP or domain without configuration.
|
||
- **Optional token in a `CONFIG` block in the HTML** so the panel works on every device without per-device setup. Trade-off: this contradicts the project principle of no hardcoded credentials — the repo copy must stay blank (`CONFIG_HA_TOKEN = ''`), and the token is only filled in on the HA host's copy.
|
||
|
||
## Technical Details
|
||
- Files: `packages/parental_controls.yaml` (rest_commands, scripts, sensors, `input_text` chunks, optional schedule automation), `www/parental_controls.html` (panel), `secrets_example.yaml`.
|
||
- Secrets used: `opnsense_alias_add_url`, `opnsense_alias_del_url`, `opnsense_apply_url` (`/api/firewall/alias/reconfigure`), `opnsense_basic_auth` (base64 of key:secret), `opnsense_leases_url`. Values `<redacted>`.
|
||
- OPNsense API key needs Firewall: Alias read/write.
|
||
- DHCP sensor: `sensor.home_dhcp_leases_lan`, data under `attributes.Leases` (capital L) with `address` / `hostname` / `expires`.
|
||
- HA WS auth: send the auth message with raw `ws.send()` — the helper `send()` waits for a `result`, but HA replies to auth with `auth_ok` / `auth_invalid`.
|
||
- `lastSaveTime` guard prevents the display blanking when the `input_text` state echo arrives right after a save.
|
||
- Panel added via `panel_iframe` at `/local/parental_controls.html`, `require_admin: true`.
|
||
|
||
## Code Changes
|
||
- `packages/parental_controls.yaml` — rest_commands (JSON payload), DHCP lease REST sensor, 12 chunked `input_text` entities, scripts, optional schedule automation.
|
||
- `www/parental_controls.html` — REST initial load + WS updates, WS auth fix, DHCP-based discovery and HA/DHCP status indicators, chunked `parseCfg`/`saveCfg`, save-error handling, `lastSaveTime` guard, URL auto-detect, optional CONFIG token.
|
||
- `secrets_example.yaml`, `README.md` — setup docs.
|
||
|
||
## Open Questions / Next Steps
|
||
- **Schedules only run while the panel is open in a browser.** For reliable enforcement, move schedule logic into an HA automation (the package has an optional one) so it runs server-side.
|
||
- Consider an HA-side way to supply the token (e.g. trusted network auth or a proxy) so the HTML never needs a hardcoded token.
|
||
- Overlaps with `opnsense-device-control`, `ha-device-assignment` and the newer `homenet-guardrails` — decide which is canonical going forward.
|
||
|
||
## Artifacts
|
||
- `bd49964` — Auto-detect URL from page origin
|
||
- `4142d1c` — Fix empty display after save + OPNsense JSON payload fix
|
||
- `8a5fe10` / `cf8d7ee` — Chunked storage (12×255)
|
||
- `4ecdda5` — Redesign on OPNsense DHCP lease sensor
|
||
- `5593d14` — WS auth via `ws.send()`
|
||
- `76b67d3` — REST initial load, 60s WS timeout
|