# 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.

## 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.      |