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
+152
View File
@@ -1,8 +1,11 @@
// ADR-0131 grant broker: bounded JSON, offline RS256 access-token checks, and real
// PostgreSQL schema v39 identities, serials and logout revocation. Isolated world 9831.
// ADR-0182 admin API: the admin realm role, the portal's files and the schema v61 read views
// over the same world.
#include "evo/persistence/account_control_store.hpp"
#include "evo/persistence/account_identity_store.hpp"
#include "evo/persistence/region_lease_store.hpp"
#include "evo/server/admin/admin_api.hpp"
#include "evo/server/broker/grant_broker.hpp"
#include "evo/server/broker/json.hpp"
@@ -194,6 +197,26 @@ void token_tests(const Realm& realm) {
CHECK(failure(stranger.token(header, claims("user-a")), TokenError::bad_signature));
CHECK(failure("a.b", TokenError::malformed));
CHECK(failure(std::string(max_access_token_bytes + 1, 'a'), TokenError::malformed));
// ADR-0182: a required realm role, and the email returned for display.
auto admin_rules = rules();
admin_rules.realm_role = "aevolution-admin";
const auto admins = TokenVerifier::from_jwks(realm.jwks("sig-1"), admin_rules);
CHECK(admins);
const auto role = [&](std::string_view extra) {
return admins->verify(realm.token(header, claims("u", extra)), now);
};
const auto granted =
role(R"(,"email":"ops@example.test","realm_access":{"roles":["x","aevolution-admin"]})");
CHECK(granted && granted->email == "ops@example.test" && granted->subject == "u");
CHECK(good->email.empty());
for (const std::string_view without :
{"", R"(,"realm_access":{"roles":["x"]})",
R"(,"realm_access":{"roles":"aevolution-admin"})", R"(,"realm_access":{})",
R"(,"roles":["aevolution-admin"])"}) {
const auto refused = role(without);
CHECK(!refused && refused.error() == TokenError::missing_role);
}
}
struct Grant {
@@ -331,6 +354,134 @@ void broker_tests(const Realm& realm) {
// Runtime role cannot read or write identities except through the functions.
CHECK(!region->query("SELECT count(*) FROM evolution.account_identities", {}, 5s));
}
// ADR-0182 admin API over world 9831 as broker_tests left it: alice and bob have identities,
// alice holds session control in region 1, nobody has a life.
void admin_api_tests(const Realm& realm) {
using server::admin::AdminApi;
AccessTokenRules admin_rules{std::string(issuer), "aevolution-admin", "aevolution-admin-portal",
30, "aevolution-admin"};
const auto admin_claims = [](std::string_view subject, std::string_view roles) {
return claims(subject,
R"(,"email":"ops@example.test","realm_access":{"roles":)" +
std::string(roles) + "}",
R"(["account","aevolution-admin"])", "aevolution-admin-portal");
};
const auto admin =
"Bearer " + realm.token(header, admin_claims("ops", R"(["aevolution-admin"])"));
const auto player = "Bearer " + realm.token(header, admin_claims("ops", R"(["player"])"));
const auto game = "Bearer " + realm.token(header, claims("alice-sub"));
int connects = 0;
int fetches = 0;
const auto make = [&](bool online) {
server::admin::AdminConfig config;
config.world = 9831;
config.view_regions = {1, 3};
config.portal_config_json = "{\"world\":9831}\n";
config.content_security_policy = "default-src 'none'";
return AdminApi{config,
*TokenVerifier::from_jwks(realm.jwks("sig-1"), admin_rules),
[&, online]() -> std::unique_ptr<persistence::Postgres> {
++connects;
return online ? connect_as(env("EVO_PG_RUNTIME_USER")) : nullptr;
},
[&](std::uint64_t region) -> std::optional<std::string> {
++fetches;
return region == 1 ? std::optional<std::string>{"{\"region\":1}\n"}
: std::nullopt;
},
{{"/index.html", "text/html; charset=utf-8", "<!doctype html>"},
{"/app.js", "text/javascript; charset=utf-8", "start();"}}};
};
auto api = make(true);
const auto t0 = std::chrono::steady_clock::time_point{} + 1h;
const auto get = [&](std::string_view path, const std::string& authorization = {},
std::chrono::steady_clock::time_point at = {}) {
return api.handle({"GET", path, authorization}, now, at == decltype(at){} ? t0 : at);
};
// Public: health, the portal's files with their policy headers, and its settings.
CHECK(get("/healthz").status == 200);
const auto index = get("/");
CHECK(index.status == 200 && index.body == "<!doctype html>" &&
index.content_type == "text/html; charset=utf-8" &&
index.headers.find("Content-Security-Policy: default-src 'none'\r\n") == 0 &&
index.headers.find("X-Content-Type-Options: nosniff\r\n") != std::string::npos);
CHECK(get("/app.js?v=2").body == "start();");
CHECK(get("/style.css").status == 404 && get("/../etc/passwd").status == 404);
CHECK(get("/config.json").body == "{\"world\":9831}\n");
CHECK(api.handle({"POST", "/api/me", admin}, now, t0).status == 405);
// Every /api route needs an admin's token; nothing reaches the database before that.
CHECK(get("/api/accounts").status == 401);
const auto no_role = get("/api/accounts", player);
CHECK(no_role.status == 403 && no_role.body.find("not_an_admin") != std::string::npos);
const auto foreign = get("/api/accounts", game);
CHECK(foreign.status == 401 &&
foreign.body.find("token_not_for_this_service") != std::string::npos);
CHECK(connects == 0);
const auto me = must(JsonValue::parse(get("/api/me", admin).body));
CHECK(me.member("subject")->string() == "ops" &&
me.member("email")->string() == "ops@example.test" &&
me.member("world")->integer() == 9831);
// Accounts: alice is connected to region 1; neither has a life yet.
const auto listed = get("/api/accounts", admin);
CHECK(listed.status == 200 && listed.content_type == "application/json");
const auto accounts = must(JsonValue::parse(listed.body));
CHECK(accounts.member("world")->integer() == 9831);
const JsonValue* alice = nullptr;
const JsonValue* bob = nullptr;
for (const auto& entry : *accounts.member("accounts")->array()) {
if (entry.member("subject")->string() == "alice-sub")
alice = &entry;
if (entry.member("subject")->string() == "bob-sub")
bob = &entry;
}
CHECK(alice && bob);
CHECK(alice->member("logged_in")->boolean() == true &&
alice->member("control_region")->string() == "1" &&
alice->member("status")->string() == "no_life" &&
alice->member("lives")->integer() == 0 && alice->member("deaths")->integer() == 0 &&
alice->member("resets")->integer() == 0 &&
alice->member("mutation_choices")->integer() == 0 &&
alice->member("issuer")->string() == issuer && alice->member("created_at")->integer());
CHECK(bob->member("logged_in")->boolean() == false &&
bob->member("control_region")->kind() == JsonValue::Kind::null);
const auto alice_id = std::string(must(alice->member("account")->string()));
const auto one = must(JsonValue::parse(get("/api/accounts/" + alice_id, admin).body));
CHECK(one.member("account")->member("subject")->string() == "alice-sub" &&
one.member("lives")->array() && one.member("lives")->array()->empty());
CHECK(get("/api/accounts/00000000-0000-4000-8000-000000000000", admin).status == 404);
CHECK(get("/api/accounts/" + alice_id.substr(1), admin).status == 404);
CHECK(get("/api/accounts/" + std::string(36, 'A'), admin).status == 404);
// Regions: the lease broker_tests took, and which views can be fetched.
const auto regions = must(JsonValue::parse(get("/api/regions", admin).body));
const auto& region = regions.member("regions")->array()->at(0);
CHECK(region.member("region")->string() == "1" && region.member("frame")->string() == "7" &&
region.member("lease_held")->boolean() == true &&
region.member("viewable")->boolean() == true);
// Views are cached briefly; unknown and unreachable regions are refused.
CHECK(get("/api/regions/1/view", admin).body == "{\"region\":1}\n" && fetches == 1);
CHECK(get("/api/regions/1/view", admin, t0 + 500ms).status == 200 && fetches == 1);
CHECK(get("/api/regions/1/view", admin, t0 + 800ms).status == 200 && fetches == 2);
CHECK(get("/api/regions/2/view", admin).status == 404 && fetches == 2);
CHECK(get("/api/regions/3/view", admin).status == 503 && fetches == 3);
CHECK(get("/api/regions/x/view", admin).status == 404 &&
get("/api/other", admin).status == 404);
// An unreachable database is a 503, retried on the next request.
auto offline = make(false);
CHECK(offline.handle({"GET", "/api/accounts", admin}, now, t0).status == 503);
CHECK(offline.handle({"GET", "/api/regions", admin}, now, t0).status == 503);
// The read views are the only way in: the runtime role still cannot read the tables.
auto runtime = connect_as(env("EVO_PG_RUNTIME_USER"));
CHECK(!runtime->query("SELECT count(*) FROM evolution.life_reservations", {}, 5s));
CHECK(server::admin::json_string("a\"b\\c\n\x01") == "\"a\\\"b\\\\c\\u000a\\u0001\"");
}
} // namespace
void run_grant_broker_tests() {
@@ -338,4 +489,5 @@ void run_grant_broker_tests() {
const Realm realm;
token_tests(realm);
broker_tests(realm);
admin_api_tests(realm);
}