From dbe627dee44c2ac322d7e2f59ad07504c40432bb Mon Sep 17 00:00:00 2001
From: malice <matt@echo6.co>
Date: Mon, 18 May 2026 14:26:09 -0600
Subject: [PATCH] docs: add v0.3.0 changelog entry and network bindings
 reference (#29)

CHANGELOG.md:
- v0.3.0 Phase 1b entry covering operator console, events feed,
  wizard, session auth, and infrastructure changes

docs/environment.md:
- New "Network and Service Bindings" section documenting:
  - central-gui binds 0.0.0.0 by design (network gating is ops)
  - NATS listener ports table (4222/8080/8222/1883)

Co-authored-by: Matt Johnson <mj@k7zvx.com>
---
 CHANGELOG.md        | 58 +++++++++++++++++++++++++++++++++++++++++++++
 docs/environment.md | 26 ++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d6b237..9b5711a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,63 @@
 # Changelog
 
+## v0.3.0 — Phase 1b (2026-05-18)
+
+Operator console. FastAPI + Jinja2 + Pico + HTMX. Self-hosted,
+Tailscale-gated by default, no application-level auth beyond
+the operator session.
+
+### Added
+- Operator console (`central-gui` systemd service on port 8000)
+- Login + session auth (argon2id, 90-day DB-backed sessions)
+- Dashboard: events 24h by adapter, stream sizes,
+  last-poll-time per adapter
+- Adapters list and edit page (cadence + per-adapter settings),
+  with Leaflet region picker and click-to-draw rectangles
+- Streams view with retention chips (1d / 7d / 14d / 30d /
+  365d / custom)
+- API keys management (list / add / rotate / delete,
+  encrypted at rest via `crypto.encrypt`, plaintext never
+  logged or stored)
+- First-run wizard (5 steps: operator, system, keys, adapters,
+  finish) with deferred-commit pattern — no DB writes until
+  Finish runs as a single transaction
+- Events feed page (`/events`) — paginated, filterable by
+  adapter / category / time range / map viewport, with
+  color-coded geometry overlay, click-to-popup, and
+  expandable row details showing full event payload
+- Paginated events JSON API (`/events.json`) — cursor-based
+  pagination, same filter surface as the HTML feed
+
+### Changed
+- CSRF tokens are now session-bound (synchronizer token
+  pattern), replacing the previous fastapi-csrf-protect
+  library. Eliminates a rotation race that broke first-load
+  submissions
+- First-run wizard is a single atomic transaction at Finish,
+  not per-step DB writes. Back navigation works; abandoned
+  wizards leave no orphan rows
+
+### Fixed
+- Adapter editor's JSONB double-encoding bug (write path
+  called `json.dumps` before asyncpg's codec, corrupting
+  the settings column)
+- Dashboard polls card was reading from the wrong NATS
+  subject and using a durable consumer instead of
+  `get_last_msg`, leaking zombie consumers
+- Browser-noise paths (/favicon.ico, /apple-touch-icon.png,
+  /robots.txt) return 204 directly, preventing parallel
+  requests from racing the CSRF cookie on first page load
+- SubResource Integrity hashes for leaflet-draw assets
+  corrected (previous values were fabricated and silently
+  blocked by browsers)
+
+### Infrastructure
+- New `config.sessions` column: `csrf_token` (per-session
+  synchronizer)
+- Composite index on `public.events (time DESC, id DESC)`
+  for cursor pagination
+- `central-gui` systemd service
+
 ## v0.2.0 — Phase 1a (2026-05-16)
 
 Three live data sources, configurable infrastructure, hot-reload
diff --git a/docs/environment.md b/docs/environment.md
index 9659443..f2afce4 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -28,6 +28,32 @@ The Windows workstation (matt-desktop) has no Central repository clones.
 The directory `C:\Users\mtthw\central_work\` is scratch space only and
 should not be used for commits.
 
+
+## Network and Service Bindings
+
+### Bind Address
+
+`central-gui` binds to `0.0.0.0` by design. Network gating is the
+operator's responsibility (firewall, Tailscale, etc.), not the app's.
+Do not switch to `127.0.0.1` or to a specific interface — operators
+choose their bind via whatever network they want to expose the service on.
+
+### NATS Listener Ports
+
+The default `nats-server.conf` listens on more than just :4222:
+
+| Port | Protocol | Used by Central? |
+|------|----------|------------------|
+| 4222 | NATS client | Yes (all) |
+| 8080 | WebSocket | No (Phase 0 leftover) |
+| 8222 | HTTP monitoring | No (manual ops only) |
+| 1883 | MQTT | No (Phase 0 leftover) |
+
+None of the unused ports cause active harm — they listen but no consumer
+connects. Operators can remove them from `nats-server.conf` if they want
+a tighter footprint. Documenting so future contributors don't grep for
+"MQTT integration" and come up confused.
+
 ## Repository
 
 | Property | Value |