docs: WebUI preview brief, signed-in read-only Console behind the edge proxy

Mos approved the cuts 2026-10-11: forward auth at the edge, a user unit beside the bus, a preview hostname, read-only. No code until Jason answers Q91 (amending lead decision 48). Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-11 16:53:21 -05:00
parent c26341b830
commit 620fb174f6
1 changed files with 106 additions and 0 deletions
@@ -0,0 +1,106 @@
 # WebUI preview behind sign-in (2026-10-11)
 Status: written by Sage, lead. It follows `docs/plans/BRIEF-TEMPLATE.md`.
 One row. No code starts until Jason answers Q91 (amending lead decision
 48 for a signed-in preview reachable beyond localhost). Mos relays the
 answer. If the ruling narrows or changes what follows, this brief is
 amended first.
 ## WebUI preview: a signed-in, read-only Console behind the edge proxy
 ### Problem
 Jason asked for an ETA for the refactor WebUI at mosaic.woltje.com. Today
 the Console can't be reached from anywhere but the host it runs on, by
 design:
 - `startServer` refuses to bind to a non-loopback address
  (`packages/webui/src/serve.mjs:82`) and answers 403 to any request whose
  Host isn't loopback on its own port (`serve.mjs:92`). A reverse proxy
  that forwards the public Host is refused.
 - The Origin check (`serve.mjs:96`) compares against `http://<Host>`, so a
  browser on `https://<public name>` is refused as cross-origin.
 - There is no sign-in. Anything that connects to the port reads what a
  reader capability reads (`packages/webui/README.md`, the paragraph on
  the bus views), and the README forbids a public proxy.
 - Two routes write: POST `/api/seen` and `/api/reply` go to the board.
 - Nothing runs the Console as a service. It is a foreground `serve`.
 Mos approved these cuts for the preview (2026-10-11): sign-in at the edge
 through Pocket ID forward auth, not login code in the Console; a systemd
 user unit beside the bus; a preview hostname, so the old build at
 mosaic.woltje.com stays; read-only; not held for S7 (row 42) or Gate E
 (row 5). ops-01 owns the Pocket ID client, the DNS name, TLS, the proxy
 and the route from the edge to this host. Jason approves that route
 before anything is served.
 ### Owner and reviewer
 Owner: Dewey, who owns the WebUI, after their row 59 review. Reviewers:
 Darkwing and Filbert.
 ### Files owned
 - `packages/webui/src/serve.mjs`, `packages/webui/src/cli.mjs`,
  `packages/webui/README.md` and `packages/webui/tests/`
 - a new `scripts/webui-service.sh` and its unit template, beside
  `scripts/bus-service.sh` and `packages/cli/systemd/mosaic-bus.service.in`
 - the test for that script, in the package that holds the template
 - `docs/TOOLS.md`, the new script's entry only. Row 70 also edits this
  file; whichever lands second rebases on the first.
 - `agents/dewey/work/queue-<row>/`
 ### What ships
 A preview mode, off by default. Without its flags the Console behaves
 exactly as today, and the existing tests show it.
 - `serve --public-host NAME --auth-header HEADER --allow-user ID`, all
  three or none. NAME is a hostname, no port or scheme. The bind stays
  loopback; nothing here listens beyond it.
 - In preview mode a request's Host must be NAME, or loopback on the
  Console's port as today. An Origin, when sent, must be `https://NAME`
  for a NAME request, and the loopback form for a loopback request.
 - A NAME request must carry HEADER with a value equal to ID. Missing or
  different answers 401 with no bus read made. Loopback requests are
  unchanged, so the operator's own browser on the host still works.
 - In preview mode every POST answers 403 `read-only`, whatever the Host.
  `/api/seen` and `/api/reply` don't reach the board.
 - Tests for each refusal: wrong Host, wrong Origin, missing header, wrong
  user, a POST to each write route, and a partial flag set refused at
  start. A test that the loopback path is unchanged in preview mode.
 - `scripts/webui-service.sh render|install|uninstall|status` for a
  `mosaic-webui.service` user unit, on the `bus-service.sh` pattern: a
  template, write to a temp file then rename, `daemon-reload` only, no
  start, no restart. It runs the board's `serve` and the Console's
  `serve` with the preview flags (as one unit or two, the packet says
  which and why), with values from flags or an env file the script names.
  The env file holds no secret: the header name, the user id and the
  hostname aren't secrets.
 - The README replaces "Do not expose either unauthenticated server
  through a public proxy" with what the preview mode requires of the
  proxy: it strips HEADER from every client request and sets it only
  after Pocket ID signs the user in, it preserves Host, it terminates TLS,
  and it is the only thing that reaches the port from off the host. It
  says plainly that any local process can still connect and send HEADER,
  the same exposure the README already describes for the port.
 - The packet runs the Console in preview mode with `curl` against
  loopback, showing each refusal and one allowed read, with no network
  beyond the host.
 ### Out of scope
 - OIDC or login code in the Console; Pocket ID config; DNS, TLS, the
  proxy and the route from the edge (ops-01).
 - Resolving decisions or replying from the browser. REQ-DEC-3 keeps
  resolution in the CLI; changing that is a ruling and its own row.
 - Live-seat conversations (CHAT-07) and any board change.
 - A container image, CI deploy, or changes to the bus unit.
 - Installing or starting the unit on dragon-lin. Sage does that after the
  row lands, only once Jason has ruled on Q91 and approved ops-01's route.
 ### Gate
 Darkwing and Filbert approve on the row's issue naming the candidate
 manifest. The webui, control-board and cli node suites and every
 `scripts/test-*.sh` green on Sage's gate rerun.