Add isolated read-only spectator monitor for public sharing

2026-09-22 19:50:05 -04:00
parent 8e96c7ff47
commit 7e19d82a02
7 changed files with 379 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Spectator monitor
+
+A separate loopback service serves a public, read-only projection of the realm.
+It never forwards viewer paths, methods, cookies, authorization headers or query
+parameters to the administrative application. It uses a fixed local GET to
+`http://127.0.0.1:8787/api/state`, caches the sanitized result for ten seconds, and
+marks delayed observations. Visitors refresh every fifteen seconds.
+
+Published fields: online bot names, class, race, level, faction, zone, guild;
+observed bot parties; guild goals and progress; confirmed social activity.
+Only autonomous bot-to-bot reply transcripts are public. Human conversations,
+whispers, memories, account/character IDs, tokens, configuration and PC telemetry
+are excluded. All text is rendered with textContent, never HTML interpolation.
+The HTTP service allows only explicit static paths and `/api/realm`, `/health`,
+`/robots.txt`. Mutation methods return 405; admin paths return 404.
+
+## Install and publish
+
+Run as the realm owner from the repository:
+
+```sh
+python3 scripts/test-spectator.py
+python3 deploy/playable/install-spectator.py
+```
+
+The user service restarts automatically and listens only on `127.0.0.1:8790`.
+User lingering, already used by runtime recovery, is required for boot startup.
+Keep the existing private Tailscale Serve dashboard on HTTPS 443. Publish only
+the spectator service on a separate HTTPS port:
+
+```sh
+sudo tailscale funnel --bg --https=8443 http://127.0.0.1:8790
+```
+
+If Tailscale presents a Funnel enablement link, the tailnet owner must complete
+that authorization. Verify `tailscale funnel status` lists **only port 8443** as
+public and port 443 remains tailnet-only. Share the printed HTTPS URL including
+`:8443`. Visitors do not need Tailscale. This is a public link, without a password.
+The host PC, Ubuntu VM and Tailscale must remain running.
+
+Do not publish port 8787 or 8788, or change the administrative listener into a
+Funnel. Hiding controls in the browser would not protect their APIs.
+
+To turn public access off without disturbing the private dashboard:
+
+```sh
+sudo tailscale funnel --https=8443 off
+```
+
+To stop the local spectator service:
+
+```sh
+systemctl --user disable --now azerothai-spectator
+```
+
+After changing spectator source or assets, restart its service:
+
+```sh
+systemctl --user restart azerothai-spectator
+```