feat(admin): read-only admin portal and API (ADR-0182 step 1, schema 61)

evo-admin-api serves the portal at srs.aeternalisgames.com and read-only JSON
for world 100 behind Keycloak (realm role aevolution-admin, audience
aevolution-admin, client aevolution-admin-portal): accounts with session,
status, lives, deaths, resets and mutation choices; one account's lives; the
world's regions; and a live 2D region view of cells, wildlife, pools and
bubbles. The portal is plain HTML/CSS/JS with PKCE sign-in, a strict CSP and
no third-party code.

- Schema 61: three bounded SECURITY DEFINER read functions, fenced in the
  privilege audit; no table or existing function changes.
- Cellular regions answer GET /admin/view on the ops port (NetworkPolicy:
  Prometheus and the admin portal only); CellularLives::extent_of reads the
  existing phenotype budget. No simulation, checkpoint or wire change.
- TokenVerifier takes an optional realm role and returns the email; the ops
  server's response bound is configurable (16 KiB default unchanged).
- DEV component admin-portal-dev (Deployment, Service, NetworkPolicies); the
  Ingress and the aevolution-admin-pg Secret are created out of band.
- CI scripts pinned to schema 60 now expect 61.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-27 12:39:28 -04:00
co-authored by Claude Opus 5.5
parent 46e5ea6c5d
commit 54beceb823
36 changed files with 2331 additions and 37 deletions
+83
View File
@@ -0,0 +1,83 @@
#pragma once
#include "evo/persistence/postgres.hpp"
#include "evo/server/broker/access_token.hpp"
#include "evo/server/ops_http.hpp"
#include <chrono>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
// ADR-0182 read-only admin API and portal host. One world; every /api route needs a Keycloak
// access token carrying the admin realm role. The portal's static files and its OIDC settings
// are public; they carry no secret.
//
// GET /healthz ok
// GET / and the portal's files the portal (index.html, app.js, style.css)
// GET /config.json issuer, client id and world for the portal's sign-in
// GET /api/me the signed-in admin's subject and email
// GET /api/accounts every account with session, lives, deaths and resets
// GET /api/accounts/<uuid> one account and its life requests
// GET /api/regions the world's regions, leases and heads
// GET /api/regions/<n>/view the region's live view (render_cellular_admin_view)
namespace evo::server::admin {
struct AdminAsset {
std::string path; // "/index.html", ...; "/" serves "/index.html".
std::string content_type, body;
};
struct AdminConfig {
std::uint64_t world{};
std::vector<std::uint64_t> view_regions; // Regions whose live view can be fetched.
std::string portal_config_json; // Served at /config.json.
std::string content_security_policy; // Sent with every portal file.
std::chrono::milliseconds db_timeout{3000};
std::chrono::milliseconds view_cache{750}; // A fetched view answers repeats this long.
};
using AdminConnect = std::function<std::unique_ptr<persistence::Postgres>()>;
// The region's /admin/view body, or nullopt when it cannot be reached or is not ready.
using AdminRegionView = std::function<std::optional<std::string>(std::uint64_t region)>;
class AdminApi {
public:
AdminApi(AdminConfig config, broker::TokenVerifier verifier, AdminConnect connect,
AdminRegionView view, std::vector<AdminAsset> assets);
// `now_seconds` is wall time (token expiry); `now` paces the view cache.
[[nodiscard]] OpsResponse handle(const ApiRequest& request, std::uint64_t now_seconds,
std::chrono::steady_clock::time_point now);
private:
[[nodiscard]] OpsResponse api(std::string_view path, const broker::AccessTokenClaims& admin,
std::chrono::steady_clock::time_point now);
[[nodiscard]] OpsResponse accounts(std::optional<std::string_view> account);
[[nodiscard]] OpsResponse regions();
[[nodiscard]] OpsResponse view(std::uint64_t region, std::chrono::steady_clock::time_point now);
[[nodiscard]] std::optional<persistence::PgRows> query(const std::string& sql,
std::vector<std::string> parameters);
AdminConfig config_;
broker::TokenVerifier verifier_;
AdminConnect connect_;
AdminRegionView view_;
std::vector<AdminAsset> assets_;
std::unique_ptr<persistence::Postgres> db_;
struct CachedView {
std::chrono::steady_clock::time_point at;
std::string body;
};
std::map<std::uint64_t, CachedView> views_;
};
// Bounded blocking HTTP/1.1 GET of `path` from "host:port" (a name is resolved): the body of
// a 200 answer of at most `limit` bytes, or nullopt on any error, other status or timeout.
[[nodiscard]] std::optional<std::string> http_get(std::string_view address, std::string_view path,
std::chrono::milliseconds timeout,
std::size_t limit);
// JSON string literal (quotes included) with control characters escaped.
[[nodiscard]] std::string json_string(std::string_view text);
} // namespace evo::server::admin
+5 -1
View File
@@ -17,10 +17,13 @@ struct AccessTokenRules {
std::string audience; // Must appear in `aud` (string or array).
std::string authorized_party; // `azp`: the game's public client.
std::uint64_t leeway_seconds{30};
// ADR-0182: when set, the role must appear in `realm_access.roles` (the admin portal).
std::string realm_role{};
};
struct AccessTokenClaims {
std::string issuer, subject;
std::uint64_t expires_at{};
std::string email{}; // Empty when absent; shown to the admin, never used as identity.
};
enum class TokenError : std::uint8_t {
malformed,
@@ -34,7 +37,8 @@ enum class TokenError : std::uint8_t {
expired,
not_yet_valid,
unverified_email,
missing_subject
missing_subject,
missing_role
};
inline constexpr std::size_t max_access_token_bytes = 6144;
@@ -0,0 +1,36 @@
#pragma once
#include "evo/server/lifecycle/cellular_lives.hpp"
#include <cstddef>
#include <functional>
#include <string>
// ADR-0182 read-only region view for the admin portal: every cell, pool and bubble of a
// cellular owner as compact JSON. It reads the committed in-memory state and changes nothing;
// it is not a simulation output, a checkpoint or a client protocol.
//
// {"world":W,"region":R,"tick":T,"rules":N,"area":[w,h],
// "spent":[e,c,n,p,o],"cells_total":N,"deposits_total":N,
// "cells":[["life","organism","account",x,y,extent,flags,members,
// reserve_e,reserve_c,reserve_n,reserve_p,reserve_o,body_mass],...],
// "deposits":[[id,kind,x,y,radius,e,c,n,p,o],...]}
//
// Cell positions are the lower-left corner of the square footprint and deposits their centre,
// in micrometres. Life and organism ids are decimal strings (bud ids exceed 2^53); `account`
// is the lowercase UUID, empty for wildlife. Flags: 1 wildlife, 2 the account's session is
// connected, 4 lingering, 8 suspended. Deposit kind: 0 patch, 1 pool, 2 bubble. Energy in
// pJ, matter in fg. Cells and deposits beyond the limits are left out (by ascending life id
// and deposit id); the totals still count them.
namespace evo::server {
struct CellularAdminViewLimits {
std::size_t cells{4096}, deposits{16384};
};
// True when the account's session is connected to this region.
using CellularAdminOnline = std::function<bool(const LifeAccount&)>;
[[nodiscard]] std::string render_cellular_admin_view(const CellularLives& state,
const CellularAdminOnline& online,
CellularAdminViewLimits limits = {});
// Lowercase 8-4-4-4-12 text of a 16-byte account.
[[nodiscard]] std::string cellular_account_text(const LifeAccount& account);
} // namespace evo::server
@@ -328,6 +328,9 @@ class CellularLives {
[[nodiscard]] accounting::Inventory heat() const noexcept;
// Rules 13: burned matter and kill remainders waiting to drip back as bubbles.
[[nodiscard]] accounting::Inventory spent() const noexcept;
// ADR-0182 observers: a life's square footprint side in micrometres, as the step uses it;
// nullopt when its genome cannot be costed. Reads the state; changes nothing.
[[nodiscard]] std::optional<std::uint32_t> extent_of(const CellularOwnedLife& life) const;
[[nodiscard]] accounting::Inventory opening_total() const noexcept;
[[nodiscard]] accounting::Inventory current_total() const noexcept;
[[nodiscard]] const CellularBoundaryLedger& boundary_ledger() const noexcept;
+11 -4
View File
@@ -19,6 +19,7 @@ struct OpsResponse {
int status{200};
std::string body;
std::string content_type{"text/plain; charset=utf-8"};
std::string headers{}; // Extra header lines, each ending in CRLF (ADR-0182 portal).
};
// Receives the request path (no query handling: probes use exact paths).
using OpsHandler = std::function<OpsResponse(std::string_view path)>;
@@ -38,12 +39,16 @@ class OpsServer {
static constexpr std::size_t max_accepts_per_serve = 4;
static constexpr std::size_t max_request_bytes = 4096;
static constexpr std::size_t max_api_request_bytes = 8192; // Room for an access token.
static constexpr std::size_t max_response_bytes = 16384;
static constexpr std::size_t max_response_bytes = 16384; // The default bound.
// ADR-0182: the admin view and portal answer up to this many bytes when asked to.
static constexpr std::size_t max_configurable_response_bytes = std::size_t{4} << 20U;
static constexpr std::chrono::milliseconds connection_deadline{1000};
// Numeric address only ("127.0.0.1:9100" or "[::1]:9100"); port 0 picks one.
// Numeric address only ("127.0.0.1:9100" or "[::1]:9100"); port 0 picks one. A
// response over `response_limit` bytes (at most max_configurable_response_bytes) is
// replaced by a 500.
[[nodiscard]] static std::expected<std::unique_ptr<OpsServer>, OpsError>
listen(std::string_view address);
listen(std::string_view address, std::size_t response_limit = max_response_bytes);
OpsServer(const OpsServer&) = delete;
OpsServer& operator=(const OpsServer&) = delete;
OpsServer(OpsServer&&) = delete;
@@ -72,12 +77,14 @@ class OpsServer {
std::size_t sent{};
std::chrono::steady_clock::time_point deadline{};
};
OpsServer(int fd, std::uint16_t port) : fd_(fd), port_(port) {}
OpsServer(int fd, std::uint16_t port, std::size_t response_limit)
: fd_(fd), port_(port), response_limit_(response_limit) {}
void respond(Connection& c, const OpsHandler& handler);
void respond_api(Connection& c, const ApiHandler& handler);
template <typename Answer> void serve_with(std::size_t request_limit, const Answer& answer);
int fd_;
std::uint16_t port_;
std::size_t response_limit_;
std::vector<Connection> connections_;
std::uint64_t refused_{};
};