galaxy-game/backend/docs/admin-console.md

Operator console (/_gm)

The operator console is a server-rendered web UI for the platform's admin operations. It is the human-facing counterpart to the JSON admin API under /api/v1/admin/*: both call the same service layer, but the console renders HTML pages an operator drives in a browser, while the JSON API stays internal to the deployment for programmatic and test use.

Design choices

• Server-rendered, no client framework. Pages are rendered with the standard library's html/template. Navigation is by ordinary links and query parameters; every state change is an HTML form POST answered with a Post/Redirect/Get redirect. There is no build step, no JavaScript framework, and no separate asset pipeline — a single embedded stylesheet under /_gm/assets/.
• Reuses the existing admin auth. The console mounts behind the same basicauth.Middleware(admin.Service) verifier that gates /api/v1/admin/*, so there is one credential store (admin_accounts, bcrypt-12) and no second secret to manage.
• Lives in the backend. The backend owns the admin domain and the data, so rendering there lets the console call the service layer directly. The gateway stays a thin proxy.

Request path

Browser ── /_gm/* ──► edge Caddy ──► gateway (public listener)
   gateway: anti-abuse `admin` class (per-IP rate limit, body + method limits)
            └─► reverse proxy ──► backend  /_gm/*
   backend: basicauth.Middleware(admin.Service)
            └─► CSRF guard (state-changing methods)
                └─► console handler ──► admin service layer ──► html/template

The gateway preserves the inbound Host and relays the backend's 401 Basic Auth challenge unchanged, so the browser shows its native credential dialog. The gateway adds only the edge anti-abuse layer; authentication and every state change are enforced by the backend. The gateway answers 502 when the backend is unreachable. See the gateway README "Operator Console Proxy" section for the admin route-class env vars.

Components (package internal/adminconsole)

The package is framework-agnostic (no gin) so it unit-tests in isolation:

• Renderer — parses the embedded layout plus one content page per route and renders a named page wrapped in the shared layout. Rendering goes through an intermediate buffer, so a template failure never emits a partial document.
• CSRF — issues and verifies the stateless anti-CSRF token: HMAC-SHA256 over the authenticated username, keyed by BACKEND_ADMIN_CONSOLE_CSRF_KEY. When the key is unset a per-process random key is used (secure, but forms reset on restart and do not validate across replicas — set a shared key for multi-replica deployments).
• Assets — the embedded stylesheet filesystem served under /_gm/assets/.

The gin glue (route group, Basic Auth, the CSRF guard middleware, the per-page handlers) lives in internal/server/handlers_admin_console.go and internal/server/router.go (registerAdminConsoleRoutes).

CSRF protection

Because the console is sessionless (HTTP Basic Auth, whose credentials the browser replays automatically), state-changing requests are double-guarded:

1. A stateless per-operator token (_csrf form field) that a cross-site page cannot read or forge.
2. A same-origin Origin/Referer check (when the browser sends one), which relies on the gateway preserving the inbound Host.

Safe methods (GET/HEAD/OPTIONS) pass without a token.

Monitoring

The dashboard is the console landing page. It surfaces backend-visible operational state — service health, game-runtime status, and queue depths — read through the existing service and persistence layers. Richer cross-service metrics are out of scope for the console itself: the /metrics Prometheus exporters on backend and gateway are wired and enabled in the dev deployment so a future Prometheus + Grafana stack can scrape them without code changes.

Pages

Path	Method	Purpose
/_gm, /_gm/	GET	Dashboard: health, runtime/mail/notification status, queues.
/_gm/assets/*	GET	Embedded stylesheet.
/_gm/users	GET	Paginated account list.
/_gm/users/{id}	GET	Account detail: profile, entitlement, active sanctions.
/_gm/users/{id}/block	POST	Apply a permanent block (reason required).
/_gm/users/{id}/entitlement	POST	Set the entitlement tier.
/_gm/users/{id}/soft-delete	POST	Soft-delete the account (cascades).
/_gm/games	GET/POST	Paginated game list; POST creates a public game.
/_gm/games/{id}	GET	Game detail with the runtime snapshot.
/_gm/games/{id}/force-start	POST	Force-start the game.
/_gm/games/{id}/force-stop	POST	Force-stop the game.
/_gm/games/{id}/ban-member	POST	Ban a member (user id + reason).
/_gm/games/{id}/runtime/restart	POST	Restart the engine container.
/_gm/games/{id}/runtime/patch	POST	Patch the runtime to a target version.
/_gm/games/{id}/runtime/force-next-turn	POST	Force the next turn now.
/_gm/engine-versions	GET/POST	Version registry; POST registers a version.
/_gm/engine-versions/{ver}/disable	POST	Disable a registered version.
/_gm/operators	GET/POST	Admin-account list; POST creates an operator.
/_gm/operators/{user}/disable	POST	Disable an operator.
/_gm/operators/{user}/enable	POST	Re-enable an operator.
/_gm/operators/{user}/reset-password	POST	Reset an operator's password.
/_gm/mail	GET	Mail deliveries (paginated) + a dead-letter snapshot.
/_gm/mail/deliveries/{id}	GET	Delivery detail with its attempts.
/_gm/mail/deliveries/{id}/resend	POST	Re-enqueue a non-sent delivery.
/_gm/notifications	GET	Notifications, dead-letters, and malformed intents overview.
/_gm/broadcast	GET/POST	Admin multi-game diplomatic broadcast.

Each page reuses the same service layer as the corresponding /api/v1/admin/* JSON endpoint; the console adds no business logic. Collection-mutating POSTs are mounted on the collection path (POST /_gm/games, POST /_gm/engine-versions) so a static action segment never collides with a path parameter in the gin router. Unblocking a user is not yet available because the JSON admin API exposes no remove-sanction endpoint.

Configuration

Variable	Where	Notes
BACKEND_ADMIN_CONSOLE_CSRF_KEY	backend	CSRF token key; unset → per-process random key.
BACKEND_ADMIN_BOOTSTRAP_USER	backend	Bootstrap operator account (shared with the JSON admin API).
BACKEND_ADMIN_BOOTSTRAP_PASSWORD	backend	Bootstrap operator password.
GATEWAY_PUBLIC_HTTP_ANTI_ABUSE_ADMIN_*	gateway	admin route-class rate-limit and body budgets.