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
+41 -12
View File
@@ -23,7 +23,7 @@ may change a running region except an event recorded at a tick.
### 1. World tuning lives in SQL
- Schema 61 adds append-only `world_tuning_revisions(world, revision, parent_revision,
- Schema 62 adds append-only `world_tuning_revisions(world, revision, parent_revision,
format, canonical_text, digest, author_subject, reason, created_at)`. A revision is the
complete canonical tuning text (`encode_cellular_revamp_tuning`), never a diff, so the
existing parser and validator are the only interpretation.
@@ -51,7 +51,7 @@ may change a running region except an event recorded at a tick.
### 3. Admin commands
- Schema 61 adds `admin_commands(world, region, command_id, kind, payload, author_subject,
- Schema 62 adds `admin_commands(world, region, command_id, kind, payload, author_subject,
reason, created_at, applied_tick, outcome)`. The admin API inserts and the region host
drains them at tick boundaries in id order, publishing each with that tick. This is the
same pattern as the durable mutation queue (schema 59).
@@ -121,24 +121,53 @@ pool holds. For the source, scale multiplies the import.
### 7. Admin API and portal
- `evo-admin-api`: a C++ service built like the grant broker. It verifies Keycloak access
tokens against the realm keys pinned in Git, requires audience `aevolution-admin` and
realm role `aevolution-admin`, and has its own database login limited to the read views
and the admin tables. Configured world allowlist; World0 is refused in code.
tokens against the realm keys pinned in Git, requires audience `aevolution-admin`,
authorized party `aevolution-admin-portal` and realm role `aevolution-admin`, and serves
one configured world. Its component exists only in the evolution-dev overlay; World0 and
stage have no admin portal (World0 has no fixed world id to refuse in code).
- Every write records the token subject and a reason.
- The region view: the region host's internal ops port gains a bounded snapshot route (cell
id, position, radius, wildlife/player and account, bubbles), reachable only from the admin
id, position, extent, wildlife/player and account, bubbles), reachable only from the admin
API by NetworkPolicy. The admin API serves it to the portal at up to 1 Hz.
- The portal is a static browser application at `https://srs.aeternalisgames.com`
(section **Cellular** now, **3D** later) using authorization code with PKCE. Its toolchain is chosen in the implementation change
with dependency evidence (DEPENDENCY_EVALUATION.md).
(section **Cellular** now, **3D** later) using authorization code with PKCE. It is plain
HTML, CSS and JavaScript with no third-party code, so no dependency evaluation is needed.
- Keycloak (maintainer setup): realm role `aevolution-admin`; public client
`aevolution-admin-portal` with PKCE S256; an audience mapper adding `aevolution-admin`;
MFA required for the role.
`aevolution-admin-portal` with standard flow and PKCE S256, redirect URI
`https://srs.aeternalisgames.com/*`, web origin `https://srs.aeternalisgames.com` and
post-logout redirect `https://srs.aeternalisgames.com/`; an audience mapper adding
`aevolution-admin`; MFA required for the role.
### 8. Read-only portal (delivered first, schema 61)
- **Schema 61** adds three bounded, read-only SECURITY DEFINER functions, executable by the
runtime group and listed in the privilege audit: `admin_accounts_v1(world)` (every account
with its identity, session control, lives, deaths, active life and mutation-choice count),
`admin_account_lives_v1(world, account)` (its life requests and endings) and
`admin_regions_v1(world)` (leases and heads). No table or existing function changes. The
runtime group still has no table privilege. DEV's admin API logs in with its own login in
that group, as the grant broker does; a dedicated read role is a later least-privilege step.
- **Derived values.** A life is a published, unrefused reservation; a death is an ended one;
resets are lives after the first; logged in means the session control has not expired.
- **Region view.** `GET /admin/view` on the cellular region's ops port renders the committed
in-memory owner (`render_cellular_admin_view`): every cell (life and organism ids as
strings, account, footprint, extent, wildlife/connected/lingering/suspended flags,
members, reserve, body mass) and every pool and bubble, bounded to 4,096 cells and 16,384
deposits with totals. It reads without changing anything; the ops server's response
bound becomes configurable (4 MiB for this port), default 16 KiB elsewhere.
- **Portal files and headers.** The image ships the portal under
`/usr/local/share/evo-admin-portal`. Files go out with a strict Content-Security-Policy
(`'self'` scripts and styles, connections only to this origin and the realm), `nosniff`,
`no-referrer` and `DENY` framing; every answer is `no-store`. The access token stays in
page memory and the rotating refresh token in the tab's sessionStorage.
- **Not yet available** (they need the schema-62 records): time played, bans, current
mutations and living offspring.
## Delivery order
1. Read-only portal: login, accounts (from existing data), regions, census, region view.
2. Schema 61 and the new owner format: world revisions, adoption records, admin commands,
1. Read-only portal: login, accounts (from existing data), regions, region view (schema 61,
section 8).
2. Schema 62 and the new owner format: world revisions, adoption records, admin commands,
game source, drip settings, the score vector, session intervals and bans. One new
opening on that format.
3. Admin commands and account actions in the portal.
+1 -1
View File
@@ -1,6 +1,6 @@
# Architecture decision records
- [ADR-0182: Admin portal, world tuning in SQL and per-tick amendments](0182-admin-portal-and-world-tuning.md) - accepted direction: world tuning revisions in SQL adopted per tick and recorded in region history, admin commands with a named game source, drip/source settings, data-defined mutations, bans and session intervals, and a Keycloak-gated admin API and portal; migration and new matter types deferred.
- [ADR-0182: Admin portal, world tuning in SQL and per-tick amendments](0182-admin-portal-and-world-tuning.md) - accepted direction: world tuning revisions in SQL adopted per tick and recorded in region history, admin commands with a named game source, drip/source settings, data-defined mutations, bans and session intervals, and a Keycloak-gated admin API and portal; the read-only portal (schema 61 read views and the region view) comes first; migration and new matter types deferred.
- [ADR-0181: Reproduction safety revision 1](0181-cellular-reproduction-safety.md) - opt-in controlled-cell mutation share, retained budding provision, outward mutation launch and a protected growth fuel buffer; historical declarations unchanged.