Add native host management and role-based operator authentication

Introduce an outbound Python host agent, Debian installer, durable remote
operations, immutable game-file libraries, host-aware deployments and ports,
and occupancy-safe campaigns and draining. Native hosts do not require Komodo.

Add administrator, operator and viewer accounts, protected management routes,
secure sessions, password recovery, audit history and separate telemetry tokens.
Document first-admin setup, reporter migration and live-host acceptance checks.

Validation: 1,343 TypeScript tests and 39 agent tests passed, along with type
checking, the production build, compiled SSR/API smoke tests and administrator
recovery. Real Debian/Docker T5/T6 acceptance remains unrun.

docs/beta-test-plans.md

@@ -6,7 +6,18 @@ beta on that server.
 
 ## Game reporter protocol
 
-Send JSON to `POST /api/telemetry` with `Content-Type: application/json`.
+Set `EC_TELEMETRY_TOKEN` on the Electric Cherry controller to a dedicated random
+secret of at least 32 characters (for example, generate 64 hexadecimal characters
+with `openssl rand -hex 32`). Configure the same secret in each game reporter or
+its trusted local relay. Use a production HTTPS URL or a reverse proxy that
+terminates TLS; browser login cookies do not authorize game telemetry.
+
+Send JSON to `POST /api/telemetry` with `Content-Type: application/json` and either
+`Authorization: Bearer <EC_TELEMETRY_TOKEN>` or
+`X-EC-Telemetry-Token: <EC_TELEMETRY_TOKEN>`. If both headers are present, they must
+contain the same secret. Keep the secret out of URLs, payloads and browser code,
+and use a different secret from host-agent credentials or account passwords.
+The JSON event format is unchanged.
 There are four events. Send them whether or not a beta is active.
 
 | Event | Fields |
@@ -74,8 +85,10 @@ Send the final round and each player's final stats when the game ends.
 
 Success returns HTTP 200 with `{ "ok": true, "telemetry": { ... } }`.
 The returned telemetry contains the event and an Electric Cherry `receivedAt`
-timestamp. Invalid JSON or fields return 400, an unknown/destroyed server 404,
-and a non-JSON content type 415.
+timestamp. A missing/invalid machine token returns 401; an unset or invalid
+controller `EC_TELEMETRY_TOKEN` returns 503. Authentication happens before payload
+validation. Authenticated invalid JSON or fields return 400, an unknown/destroyed
+server 404, and a non-JSON content type 415.
 
 The script sends each event once, in gameplay order, directly to Electric Cherry.
 There is no discovery request, beta token, boot/session ID, sequence number,
@@ -93,7 +106,12 @@ of beta activity. That page documents cumulative stat accounting, round credit,
 and the limits of identifying matches from this protocol.
 
 The game scripts are uploaded artifacts, not source maintained in this
-repository. Their reporter should emit the four payloads above.
+repository. Their reporter should emit the four payloads above and add the
+authentication header. Existing anonymous reporters must be updated before
+telemetry is accepted; if a reporter cannot set HTTP headers, configure a trusted
+host-local relay to add the header. This repository does not bundle that relay or
+assume a particular GSC HTTP implementation. Rotating the shared secret requires
+updating the controller environment and all reporters/relays together.
 
 ### Telemetry diagnostics
 
@@ -102,7 +120,9 @@ Open a server's **Diagnostics → Telemetry API requests** to inspect incoming
 name. Each entry includes the Electric Cherry receipt time, HTTP result, error
 reason, event, map, round, player count, content type, and submitted JSON. Rejected
 reports are included, even when the content type is wrong but the body is readable
-JSON. Processing failures return 500 and record the internal error when diagnostic
+JSON after authentication. Unauthorized requests are rejected before their bodies
+are read and are not retained in per-server diagnostics. Authentication headers
+and their secrets are never stored. Processing failures return 500 and record the internal error when diagnostic
 storage is available; failed database transactions do not update the scoreboard.
 
 The panel refreshes every five seconds while visible and has a manual refresh
@@ -118,6 +138,8 @@ newest first, with caching disabled.
   Check the reporter's destination and server field. Calls that never reach
   Electric Cherry, malformed JSON, and bodies without a usable server name
   cannot appear in this server's log. Earlier requests are not backfilled.
+  Missing/invalid telemetry credentials also produce no retained request; inspect
+  the reporter's HTTP result for 401 or an unconfigured-controller 503.
 - **400 / 415:** inspect the error and payload. One invalid player's stats or a
   duplicate GUID rejects the entire report. These requests do not update the
   scoreboard.