feat(admin-console): Stage 1 — pipe + skeleton behind the gateway

Add the server-rendered operator console at /_gm, exposed publicly through the gateway behind the existing admin_accounts Basic Auth. Backend: - new internal/adminconsole package (html/template Renderer, stateless HMAC CSRF signer, embedded stylesheet) - /_gm route group reusing basicauth.Middleware(admin.Service) + a CSRF guard (per-operator token + same-origin check); dashboard landing page - BACKEND_ADMIN_CONSOLE_CSRF_KEY config (per-process random fallback) Gateway: - new "admin" public route class (per-IP rate limit, body + GET/HEAD/POST method limits) classifying /_gm traffic - reverse proxy to the backend /_gm surface, preserving Host and relaying the backend 401 Basic Auth challenge; 502 when the backend is unreachable - GATEWAY_PUBLIC_HTTP_ANTI_ABUSE_ADMIN_* config dev-deploy: - Caddy routes /_gm/* to the gateway - bootstrap admin + stable CSRF key; enable Prometheus /metrics exporters on backend and gateway (forward-compat for a future Prometheus/Grafana stack) Docs: ARCHITECTURE 14.1/16, FUNCTIONAL 10.2.1 (+ru mirror), backend and gateway READMEs, new backend/docs/admin-console.md. Tests: renderer + CSRF unit tests; backend router auth/render/asset/CSRF; gateway classifier, proxy forwarding/Host/401/405/413/429/502.
2026-05-31 19:50:15 +02:00
parent 5d2f2bfc26
commit 27916bbe61
28 changed files with 1319 additions and 3 deletions
@@ -0,0 +1,49 @@
+/* Admin console stylesheet. Deliberately small and dependency-free: the
+   console is an internal operator tool, not a public surface. */
+:root {
+  --bg: #11151c;
+  --panel: #1b2230;
+  --panel-hi: #232c3d;
+  --ink: #e6ebf2;
+  --ink-dim: #9aa7ba;
+  --line: #2c3850;
+  --accent: #5aa9ff;
+  --danger: #ff6b6b;
+  --ok: #4ecb8d;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font: 15px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
+  padding: 0.6rem 1.2rem;
+  background: var(--panel);
+  border-bottom: 1px solid var(--line);
+}
+.topbar .brand { font-weight: 700; letter-spacing: 0.04em; }
+.topbar .mainnav { display: flex; gap: 1rem; flex: 1; }
+.topbar .mainnav a.active { color: var(--ink); border-bottom: 2px solid var(--accent); }
+.topbar .who { color: var(--ink-dim); }
+.content { padding: 1.5rem; max-width: 1100px; margin: 0 auto; }
+h1 { font-size: 1.4rem; margin: 0 0 0.4rem; }
+.lede { color: var(--ink-dim); margin-top: 0; }
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 1rem; margin-top: 1.5rem; }
+.card {
+  display: block;
+  padding: 1rem 1.2rem;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  color: var(--ink);
+}
+.card:hover { background: var(--panel-hi); text-decoration: none; }
+.card h2 { font-size: 1.05rem; margin: 0 0 0.3rem; color: var(--accent); }
+.card p { margin: 0; color: var(--ink-dim); font-size: 0.9rem; }
@@ -0,0 +1,54 @@
+package adminconsole
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+)
+
+// CSRF issues and verifies the stateless anti-CSRF token used by the admin
+// console. The token is an HMAC-SHA256 over the authenticated operator's
+// username keyed by a process secret, so a cross-site request cannot forge it
+// without already being able to read an authenticated page. The console is
+// sessionless (HTTP Basic Auth), which makes a stateless, per-operator token
+// the natural fit.
+type CSRF struct {
+	key []byte
+}
+
+// NewCSRF returns a CSRF signer keyed by key. A shared key across backend
+// replicas lets a form rendered by one replica validate on another; callers
+// that pass a per-process random key (see NewRandomCSRF) accept that forms do
+// not survive a restart or span replicas.
+func NewCSRF(key []byte) *CSRF {
+	return &CSRF{key: key}
+}
+
+// NewRandomCSRF returns a CSRF signer keyed by a fresh 32-byte random secret.
+// It is the secure default when no shared key is configured.
+func NewRandomCSRF() (*CSRF, error) {
+	key := make([]byte, 32)
+	if _, err := rand.Read(key); err != nil {
+		return nil, fmt.Errorf("generate admin console CSRF key: %w", err)
+	}
+	return &CSRF{key: key}, nil
+}
+
+// Token returns the anti-CSRF token bound to username.
+func (c *CSRF) Token(username string) string {
+	mac := hmac.New(sha256.New, c.key)
+	mac.Write([]byte(username))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+}
+
+// Verify reports whether token is the valid anti-CSRF token for username. The
+// comparison runs in constant time relative to the token bytes.
+func (c *CSRF) Verify(username, token string) bool {
+	if token == "" {
+		return false
+	}
+	expected := c.Token(username)
+	return hmac.Equal([]byte(token), []byte(expected))
+}
@@ -0,0 +1,42 @@
+package adminconsole
+
+import "testing"
+
+func TestCSRFTokenRoundTrip(t *testing.T) {
+	signer := NewCSRF([]byte("shared-secret"))
+	token := signer.Token("alice")
+
+	if !signer.Verify("alice", token) {
+		t.Fatal("valid token rejected")
+	}
+	if signer.Verify("bob", token) {
+		t.Fatal("token accepted for a different operator")
+	}
+	if signer.Verify("alice", "") {
+		t.Fatal("empty token accepted")
+	}
+	if signer.Verify("alice", token+"x") {
+		t.Fatal("tampered token accepted")
+	}
+}
+
+func TestCSRFKeySeparation(t *testing.T) {
+	a := NewCSRF([]byte("key-a"))
+	b := NewCSRF([]byte("key-b"))
+	if a.Token("operator") == b.Token("operator") {
+		t.Fatal("tokens collide across distinct keys")
+	}
+	if b.Verify("operator", a.Token("operator")) {
+		t.Fatal("token minted under one key verified under another")
+	}
+}
+
+func TestRandomCSRFRoundTrip(t *testing.T) {
+	signer, err := NewRandomCSRF()
+	if err != nil {
+		t.Fatalf("NewRandomCSRF: %v", err)
+	}
+	if !signer.Verify("operator", signer.Token("operator")) {
+		t.Fatal("random-key token failed to round-trip")
+	}
+}
@@ -0,0 +1,18 @@
+// Package adminconsole renders the server-side operator console mounted by the
+// backend under the `/_gm` route group.
+//
+// The console is a multi-page, server-rendered surface built on the standard
+// library's html/template package: navigation is driven by request path and
+// query, state changes are submitted with HTML forms and answered with a
+// Post/Redirect/Get redirect. The package owns three concerns and nothing
+// transport-specific:
+//
+//   - Renderer composes the shared layout with one content page per route.
+//   - CSRF issues and verifies the stateless anti-CSRF token embedded in every
+//     state-changing form.
+//   - Assets exposes the embedded stylesheet served under `/_gm/assets/`.
+//
+// The gin glue (route registration, Basic Auth, the CSRF guard middleware, and
+// the per-page handlers) lives in package server; this package stays free of
+// the web framework so it can be unit-tested in isolation.
+package adminconsole
@@ -0,0 +1,107 @@
+package adminconsole
+
+import (
+	"bytes"
+	"embed"
+	"fmt"
+	"html/template"
+	"io"
+	"io/fs"
+	"path"
+	"strings"
+)
+
+//go:embed templates
+var templatesFS embed.FS
+
+//go:embed assets
+var assetsFS embed.FS
+
+// Renderer holds the parsed admin console templates. It composes one template
+// set per content page, each combining the shared layout (defining the page
+// chrome and the "layout" entry template) with that page's "content" block, so
+// rendering a page is a single ExecuteTemplate call against the "layout" name.
+type Renderer struct {
+	pages map[string]*template.Template
+}
+
+// PageData is the view model passed to every admin console page. Title is the
+// document title; Username is the authenticated operator; CSRFToken is the
+// per-operator token embedded into state-changing forms; ActiveNav marks the
+// highlighted navigation entry; Data carries the page-specific payload.
+type PageData struct {
+	Title     string
+	Username  string
+	CSRFToken string
+	ActiveNav string
+	Data      any
+}
+
+// NewRenderer parses the embedded layout and every content page under
+// templates/pages, returning a Renderer ready to serve them. It fails when a
+// template cannot be parsed.
+func NewRenderer() (*Renderer, error) {
+	base, err := template.New("layout").ParseFS(templatesFS, "templates/layout.gohtml")
+	if err != nil {
+		return nil, fmt.Errorf("parse admin console layout: %w", err)
+	}
+
+	pageFiles, err := fs.Glob(templatesFS, "templates/pages/*.gohtml")
+	if err != nil {
+		return nil, fmt.Errorf("enumerate admin console pages: %w", err)
+	}
+	if len(pageFiles) == 0 {
+		return nil, fmt.Errorf("admin console: no page templates found under templates/pages")
+	}
+
+	pages := make(map[string]*template.Template, len(pageFiles))
+	for _, file := range pageFiles {
+		name := strings.TrimSuffix(path.Base(file), ".gohtml")
+		clone, err := base.Clone()
+		if err != nil {
+			return nil, fmt.Errorf("clone admin console layout for %q: %w", name, err)
+		}
+		if _, err := clone.ParseFS(templatesFS, file); err != nil {
+			return nil, fmt.Errorf("parse admin console page %q: %w", name, err)
+		}
+		pages[name] = clone
+	}
+
+	return &Renderer{pages: pages}, nil
+}
+
+// MustNewRenderer is like NewRenderer but panics on error. The templates are
+// embedded at build time, so a parse failure is a programmer error rather than
+// a runtime condition.
+func MustNewRenderer() *Renderer {
+	renderer, err := NewRenderer()
+	if err != nil {
+		panic(err)
+	}
+	return renderer
+}
+
+// Render writes the named page, wrapped in the shared layout, to w using data.
+// It returns an error when page is unknown or template execution fails; the
+// page is rendered into an intermediate buffer first so a mid-render failure
+// never emits a partial document to w.
+func (r *Renderer) Render(w io.Writer, page string, data PageData) error {
+	tmpl, ok := r.pages[page]
+	if !ok {
+		return fmt.Errorf("admin console: unknown page %q", page)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.ExecuteTemplate(&buf, "layout", data); err != nil {
+		return fmt.Errorf("render admin console page %q: %w", page, err)
+	}
+
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+// Assets returns the embedded static asset tree rooted at the assets directory,
+// suitable for serving under `/_gm/assets/`.
+func Assets() (fs.FS, error) {
+	return fs.Sub(assetsFS, "assets")
+}
@@ -0,0 +1,67 @@
+package adminconsole
+
+import (
+	"bytes"
+	"io/fs"
+	"strings"
+	"testing"
+)
+
+func TestRendererRendersDashboard(t *testing.T) {
+	renderer, err := NewRenderer()
+	if err != nil {
+		t.Fatalf("NewRenderer: %v", err)
+	}
+
+	var buf bytes.Buffer
+	err = renderer.Render(&buf, "dashboard", PageData{
+		Title:     "Dashboard",
+		Username:  "ops-bob",
+		ActiveNav: "dashboard",
+	})
+	if err != nil {
+		t.Fatalf("Render: %v", err)
+	}
+
+	out := buf.String()
+	for _, want := range []string{
+		"<!DOCTYPE html>",
+		"Dashboard",
+		"ops-bob",
+		`href="/_gm/users"`,
+		"/_gm/assets/console.css",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("rendered page missing %q\n--- page ---\n%s", want, out)
+		}
+	}
+}
+
+func TestRendererUnknownPage(t *testing.T) {
+	renderer := MustNewRenderer()
+	if err := renderer.Render(&bytes.Buffer{}, "does-not-exist", PageData{}); err == nil {
+		t.Fatal("expected an error rendering an unknown page")
+	}
+}
+
+func TestRendererEscapesUsername(t *testing.T) {
+	renderer := MustNewRenderer()
+
+	var buf bytes.Buffer
+	if err := renderer.Render(&buf, "dashboard", PageData{Username: "<script>evil</script>"}); err != nil {
+		t.Fatalf("Render: %v", err)
+	}
+	if strings.Contains(buf.String(), "<script>evil</script>") {
+		t.Error("username was not HTML-escaped in the rendered page")
+	}
+}
+
+func TestAssetsContainsStylesheet(t *testing.T) {
+	fsys, err := Assets()
+	if err != nil {
+		t.Fatalf("Assets: %v", err)
+	}
+	if _, err := fs.Stat(fsys, "console.css"); err != nil {
+		t.Fatalf("console.css missing from embedded assets: %v", err)
+	}
+}
@@ -0,0 +1,28 @@
+{{define "layout" -}}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>{{.Title}} · Galaxy GM</title>
+<link rel="stylesheet" href="/_gm/assets/console.css">
+</head>
+<body>
+<header class="topbar">
+  <span class="brand">Galaxy · GM</span>
+  <nav class="mainnav">
+    <a href="/_gm/"{{if eq .ActiveNav "dashboard"}} class="active"{{end}}>Dashboard</a>
+    <a href="/_gm/users"{{if eq .ActiveNav "users"}} class="active"{{end}}>Users</a>
+    <a href="/_gm/games"{{if eq .ActiveNav "games"}} class="active"{{end}}>Games</a>
+    <a href="/_gm/operators"{{if eq .ActiveNav "operators"}} class="active"{{end}}>Operators</a>
+    <a href="/_gm/mail"{{if eq .ActiveNav "mail"}} class="active"{{end}}>Mail</a>
+  </nav>
+  <span class="who">{{.Username}}</span>
+</header>
+<main class="content">
+{{template "content" .}}
+</main>
+</body>
+</html>
+{{- end}}
@@ -0,0 +1,22 @@
+{{define "content" -}}
+<h1>Dashboard</h1>
+<p class="lede">Signed in as <strong>{{.Username}}</strong>.</p>
+<section class="cards">
+  <a class="card" href="/_gm/users">
+    <h2>Users</h2>
+    <p>Accounts, sanctions, entitlements, soft-delete.</p>
+  </a>
+  <a class="card" href="/_gm/games">
+    <h2>Games &amp; runtimes</h2>
+    <p>Lobby state, engine versions, turn control.</p>
+  </a>
+  <a class="card" href="/_gm/operators">
+    <h2>Operators</h2>
+    <p>Admin accounts: create, disable, reset password.</p>
+  </a>
+  <a class="card" href="/_gm/mail">
+    <h2>Mail &amp; notifications</h2>
+    <p>Deliveries, dead-letters, broadcasts.</p>
+  </a>
+</section>
+{{- end}}
@@ -55,6 +55,8 @@ const (
 	envAdminBootstrapUser = "BACKEND_ADMIN_BOOTSTRAP_USER"
 	envAdminBootstrapPassword = "BACKEND_ADMIN_BOOTSTRAP_PASSWORD"

+	envAdminConsoleCSRFKey = "BACKEND_ADMIN_CONSOLE_CSRF_KEY"
+
 	envGeoIPDBPath = "BACKEND_GEOIP_DB_PATH"

 	envOTelTracesExporter = "BACKEND_OTEL_TRACES_EXPORTER"
@@ -208,6 +210,7 @@ type Config struct {
 	Docker DockerConfig
 	Game GameConfig
 	Admin AdminBootstrapConfig
+	AdminConsole AdminConsoleConfig
 	GeoIP GeoIPConfig
 	Telemetry TelemetryConfig
 	Auth AuthConfig
@@ -308,6 +311,15 @@ type AdminBootstrapConfig struct {
 	Password string
 }

+// AdminConsoleConfig configures the server-rendered operator console.
+// CSRFKey is the secret keying the console's stateless anti-CSRF token.
+// When empty the console falls back to a per-process random key, which is
+// secure but means forms do not survive a restart and do not validate across
+// replicas; set a shared key when running more than one backend instance.
+type AdminConsoleConfig struct {
+	CSRFKey string
+}
+
 // GeoIPConfig configures the GeoLite2 country database used by geo lookups.
 type GeoIPConfig struct {
 	DBPath string
@@ -644,6 +656,8 @@ func LoadFromEnv() (Config, error) {
 	cfg.Admin.User = loadString(envAdminBootstrapUser, cfg.Admin.User)
 	cfg.Admin.Password = loadString(envAdminBootstrapPassword, cfg.Admin.Password)

+	cfg.AdminConsole.CSRFKey = loadString(envAdminConsoleCSRFKey, cfg.AdminConsole.CSRFKey)
+
 	cfg.GeoIP.DBPath = loadString(envGeoIPDBPath, cfg.GeoIP.DBPath)

 	cfg.Telemetry.TracesExporter = strings.ToLower(loadString(envOTelTracesExporter, cfg.Telemetry.TracesExporter))
@@ -0,0 +1,154 @@
+package server
+
+import (
+	"bytes"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"galaxy/backend/internal/adminconsole"
+	"galaxy/backend/internal/server/httperr"
+	"galaxy/backend/internal/server/middleware/basicauth"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// AdminConsoleHandlers renders the server-side operator console mounted under
+// the `/_gm` route group. It wraps the framework-agnostic
+// adminconsole.Renderer and CSRF signer with the gin glue: the per-page
+// handlers, the embedded static-asset handler, and the CSRF guard middleware
+// applied to state-changing requests. Authentication is provided by the shared
+// admin Basic Auth middleware mounted on the group, so this type assumes the
+// caller has already been verified.
+type AdminConsoleHandlers struct {
+	renderer *adminconsole.Renderer
+	csrf     *adminconsole.CSRF
+	assets   http.Handler
+	logger   *zap.Logger
+}
+
+// NewAdminConsoleHandlers constructs the console handler set. A nil renderer
+// falls back to the embedded default templates; a nil csrf falls back to a
+// fresh per-process random key; a nil logger falls back to zap.NewNop. It
+// panics only on conditions that are unrecoverable at startup (template parse
+// failure or crypto/rand failure), both of which indicate a broken build or
+// host rather than a runtime input.
+func NewAdminConsoleHandlers(renderer *adminconsole.Renderer, csrf *adminconsole.CSRF, logger *zap.Logger) *AdminConsoleHandlers {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+	if renderer == nil {
+		renderer = adminconsole.MustNewRenderer()
+	}
+	if csrf == nil {
+		generated, err := adminconsole.NewRandomCSRF()
+		if err != nil {
+			panic(err)
+		}
+		csrf = generated
+	}
+
+	assetsFS, err := adminconsole.Assets()
+	if err != nil {
+		panic(err)
+	}
+
+	return &AdminConsoleHandlers{
+		renderer: renderer,
+		csrf:     csrf,
+		assets:   http.StripPrefix("/_gm/assets/", http.FileServer(http.FS(assetsFS))),
+		logger:   logger.Named("http.admin.console"),
+	}
+}
+
+// Dashboard renders the console landing page (GET /_gm and GET /_gm/).
+func (h *AdminConsoleHandlers) Dashboard() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		h.render(c, http.StatusOK, "dashboard", "dashboard", "Dashboard", nil)
+	}
+}
+
+// Asset serves the embedded console static assets under `/_gm/assets/`.
+func (h *AdminConsoleHandlers) Asset() gin.HandlerFunc {
+	return gin.WrapH(h.assets)
+}
+
+// RequireCSRF returns middleware guarding state-changing requests against
+// cross-site request forgery. Safe methods pass through untouched. For unsafe
+// methods it requires both a same-origin Origin/Referer header (when the
+// browser sends one) and a valid per-operator token in the `_csrf` form field;
+// either check failing yields 403.
+func (h *AdminConsoleHandlers) RequireCSRF() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if isSafeHTTPMethod(c.Request.Method) {
+			c.Next()
+			return
+		}
+		if !sameOriginRequest(c.Request) {
+			httperr.Abort(c, http.StatusForbidden, httperr.CodeForbidden, "cross-origin request rejected")
+			return
+		}
+		username, _ := basicauth.UsernameFromContext(c.Request.Context())
+		if !h.csrf.Verify(username, c.PostForm("_csrf")) {
+			httperr.Abort(c, http.StatusForbidden, httperr.CodeForbidden, "invalid or missing CSRF token")
+			return
+		}
+		c.Next()
+	}
+}
+
+// render composes the data common to every console page (operator name, CSRF
+// token, active navigation entry) and writes the named page. It renders into an
+// intermediate buffer so a template failure surfaces as a clean 500 without
+// emitting a partial document.
+func (h *AdminConsoleHandlers) render(c *gin.Context, status int, page, activeNav, title string, data any) {
+	username, _ := basicauth.UsernameFromContext(c.Request.Context())
+
+	var buf bytes.Buffer
+	err := h.renderer.Render(&buf, page, adminconsole.PageData{
+		Title:     title,
+		Username:  username,
+		CSRFToken: h.csrf.Token(username),
+		ActiveNav: activeNav,
+		Data:      data,
+	})
+	if err != nil {
+		h.logger.Error("render admin console page", zap.String("page", page), zap.Error(err))
+		httperr.Abort(c, http.StatusInternalServerError, httperr.CodeInternalError, "failed to render page")
+		return
+	}
+
+	c.Data(status, "text/html; charset=utf-8", buf.Bytes())
+}
+
+// isSafeHTTPMethod reports whether method is a read-only HTTP method that the
+// CSRF guard may let through without a token.
+func isSafeHTTPMethod(method string) bool {
+	switch method {
+	case http.MethodGet, http.MethodHead, http.MethodOptions:
+		return true
+	default:
+		return false
+	}
+}
+
+// sameOriginRequest reports whether the request's Origin (or, failing that,
+// Referer) names the same host as the request itself. A request that carries
+// neither header is treated as same-origin, leaving the CSRF token as the sole
+// guard; a malformed or cross-host value is rejected. This relies on the
+// gateway reverse proxy preserving the inbound Host header.
+func sameOriginRequest(r *http.Request) bool {
+	source := r.Header.Get("Origin")
+	if source == "" {
+		source = r.Header.Get("Referer")
+	}
+	if source == "" {
+		return true
+	}
+	parsed, err := url.Parse(source)
+	if err != nil || parsed.Host == "" {
+		return false
+	}
+	return strings.EqualFold(parsed.Host, r.Host)
+}
@@ -0,0 +1,141 @@
+package server
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"galaxy/backend/internal/adminconsole"
+	"galaxy/backend/internal/server/middleware/basicauth"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func newConsoleTestRouter(t *testing.T) http.Handler {
+	t.Helper()
+	handler, err := NewRouter(RouterDependencies{
+		Logger:        zap.NewNop(),
+		AdminVerifier: basicauth.NewStaticVerifier("secret"),
+		AdminConsole:  NewAdminConsoleHandlers(nil, adminconsole.NewCSRF([]byte("test-key")), nil),
+	})
+	if err != nil {
+		t.Fatalf("NewRouter: %v", err)
+	}
+	return handler
+}
+
+func TestAdminConsoleRequiresAuth(t *testing.T) {
+	router := newConsoleTestRouter(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/_gm/", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d, want 401", rec.Code)
+	}
+	if got := rec.Header().Get("WWW-Authenticate"); !strings.Contains(got, "Basic") {
+		t.Fatalf("WWW-Authenticate = %q, want a Basic challenge", got)
+	}
+}
+
+func TestAdminConsoleDashboardRenders(t *testing.T) {
+	router := newConsoleTestRouter(t)
+
+	for _, path := range []string{"/_gm", "/_gm/"} {
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		req.SetBasicAuth("ops", "secret")
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Fatalf("GET %s status = %d, want 200; body=%s", path, rec.Code, rec.Body.String())
+		}
+		if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/html") {
+			t.Errorf("GET %s content-type = %q, want text/html", path, ct)
+		}
+		body := rec.Body.String()
+		if !strings.Contains(body, "Dashboard") {
+			t.Errorf("GET %s body missing the dashboard heading", path)
+		}
+		if !strings.Contains(body, "ops") {
+			t.Errorf("GET %s body missing the operator name", path)
+		}
+	}
+}
+
+func TestAdminConsoleServesAsset(t *testing.T) {
+	router := newConsoleTestRouter(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/_gm/assets/console.css", nil)
+	req.SetBasicAuth("ops", "secret")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("asset status = %d, want 200", rec.Code)
+	}
+	if ct := rec.Header().Get("Content-Type"); !strings.Contains(ct, "text/css") {
+		t.Errorf("asset content-type = %q, want text/css", ct)
+	}
+}
+
+func TestAdminConsoleRequireCSRF(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	csrf := adminconsole.NewCSRF([]byte("test-key"))
+	console := NewAdminConsoleHandlers(nil, csrf, nil)
+
+	engine := gin.New()
+	engine.Use(func(c *gin.Context) {
+		c.Request = c.Request.WithContext(basicauth.WithUsername(c.Request.Context(), "ops"))
+		c.Next()
+	})
+	engine.Use(console.RequireCSRF())
+	engine.GET("/x", func(c *gin.Context) { c.Status(http.StatusOK) })
+	engine.POST("/x", func(c *gin.Context) { c.Status(http.StatusOK) })
+
+	token := csrf.Token("ops")
+
+	cases := []struct {
+		name   string
+		method string
+		form   string
+		origin string
+		host   string
+		want   int
+	}{
+		{"get is a safe method", http.MethodGet, "", "", "galaxy.lan", http.StatusOK},
+		{"valid token, same origin", http.MethodPost, "_csrf=" + token, "https://galaxy.lan", "galaxy.lan", http.StatusOK},
+		{"valid token, no origin header", http.MethodPost, "_csrf=" + token, "", "galaxy.lan", http.StatusOK},
+		{"missing token", http.MethodPost, "", "https://galaxy.lan", "galaxy.lan", http.StatusForbidden},
+		{"wrong token", http.MethodPost, "_csrf=bogus", "https://galaxy.lan", "galaxy.lan", http.StatusForbidden},
+		{"cross-origin", http.MethodPost, "_csrf=" + token, "https://evil.example", "galaxy.lan", http.StatusForbidden},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var body io.Reader
+			if tc.form != "" {
+				body = strings.NewReader(tc.form)
+			}
+			req := httptest.NewRequest(tc.method, "/x", body)
+			if tc.form != "" {
+				req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+			}
+			if tc.origin != "" {
+				req.Header.Set("Origin", tc.origin)
+			}
+			req.Host = tc.host
+
+			rec := httptest.NewRecorder()
+			engine.ServeHTTP(rec, req)
+
+			if rec.Code != tc.want {
+				t.Fatalf("status = %d, want %d (body=%s)", rec.Code, tc.want, rec.Body.String())
+			}
+		})
+	}
+}
@@ -81,6 +81,13 @@ type RouterDependencies struct {
 	AdminGeo *AdminGeoHandlers
 	InternalSessions *InternalSessionsHandlers
 	InternalUsers *InternalUsersHandlers
+
+	// AdminConsole, when non-nil, mounts the server-rendered operator
+	// console under the `/_gm` route group behind the same admin Basic
+	// Auth verifier as `/api/v1/admin`. A nil value leaves the console
+	// unmounted, which keeps routers built without console wiring (the
+	// contract test, most unit tests) unchanged.
+	AdminConsole *AdminConsoleHandlers
 }

 // NewRouter constructs the backend gin engine wired with the documented
@@ -123,6 +130,7 @@ func NewRouter(deps RouterDependencies) (http.Handler, error) {
 	registerUserRoutes(router, instruments, deps)
 	registerAdminRoutes(router, instruments, deps)
 	registerInternalRoutes(router, instruments, deps)
+	registerAdminConsoleRoutes(router, deps)

 	router.NoMethod(func(c *gin.Context) {
 		if allow := allowedMethodsForPath(c.Request.URL.Path); allow != "" {
@@ -364,6 +372,24 @@ func registerInternalRoutes(router *gin.Engine, instruments *metrics.Instruments
 	users.GET("/:user_id/account-internal", deps.InternalUsers.GetAccountInternal())
 }

+// registerAdminConsoleRoutes mounts the server-rendered operator console under
+// `/_gm` when deps.AdminConsole is wired. The group reuses the same admin Basic
+// Auth verifier as `/api/v1/admin`; the CSRF guard then protects every
+// state-changing request. A nil AdminConsole leaves the surface unmounted.
+func registerAdminConsoleRoutes(router *gin.Engine, deps RouterDependencies) {
+	if deps.AdminConsole == nil {
+		return
+	}
+
+	group := router.Group("/_gm")
+	group.Use(basicauth.Middleware(deps.AdminVerifier, adminBasicAuthRealm))
+	group.Use(deps.AdminConsole.RequireCSRF())
+
+	group.GET("/assets/*filepath", deps.AdminConsole.Asset())
+	group.GET("", deps.AdminConsole.Dashboard())
+	group.GET("/", deps.AdminConsole.Dashboard())
+}
+
 // allowedMethodsForPath returns the comma-separated list of methods
 // the gin router accepts on requestPath. Only the probe paths declare
 // a non-empty list so NoMethod can advertise a useful `Allow` header