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
+12
View File
@@ -1,5 +1,17 @@
# Project status and next steps
## Read-only admin portal - 2026-10-27
[ADR-0182](adr/0182-admin-portal-and-world-tuning.md) records the admin portal direction
(world tuning in SQL adopted per tick, admin commands, data-defined mutations) and delivers
its read-only first step: `evo-admin-api` and the portal at `https://srs.aeternalisgames.com`
behind the Keycloak realm role `aevolution-admin`. It lists accounts (session, status,
lives, deaths, resets, mutation choices), one account's lives, the world's regions, and a
live 2D view of a region's cells, wildlife, pools and bubbles from the region's new
`/admin/view` ops route. Schema 61 adds only read functions. Nothing in the simulation,
wire protocol or checkpoints changed. Not yet deployed: it needs a new server image, the
Keycloak client, an Ingress and a database Secret. See [validation](engineering/VALIDATION.md).
## Reproduction safety trial and resizable cards - 2026-10-27
[ADR-0181](adr/0181-cellular-reproduction-safety.md) declares opt-in safety
+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.
+57
View File
@@ -10414,3 +10414,60 @@ command, and another unique session activation expiring four hours ahead. No
credential values, credential file, remote URL change or credential-store change
are included in the repository; temporary helpers stay in ignored build output.
No deployment or live-reachability claim follows from publication.
## 2026-10-27 - Read-only admin portal (ADR-0182 step 1, schema 61)
Scope: ADR-0182's read-only first step. `evo-admin-api` (Keycloak realm role
`aevolution-admin`, audience `aevolution-admin`, client `aevolution-admin-portal`) serves
the static portal and read-only JSON for world 100; schema 61 adds three bounded
SECURITY DEFINER read functions; the cellular region's ops port gains `/admin/view`.
The token verifier gains an optional realm-role rule and returns the email; the ops
server's response bound becomes configurable (default unchanged). No simulation rule,
checkpoint, manifest, wire protocol, genome or golden changed; `extent_of` reads the
existing phenotype budget.
Also fixed a pre-existing PostgreSQL failure (`region store test line 826`, also seen in
Gitea run 542): since 054e485 the DEV revamp tuning file seeds 100 wildlife, which
`evo-world-clone provision` refuses without an audited `--playtest-wildlife-first-id`
range. The cellular-v10 provisioning test now provisions the Git file's rules with its
DEV opening fixture set to zero; seeded wildlife keeps its own suite. Earlier push builds
skipped the PostgreSQL gate, and the 09:00 nightly (run 539) stopped at the format check,
so the failure had not surfaced.
Executed (WSL Ubuntu, GCC 14.2 Release/NDEBUG, existing build/m97-postgres with network,
QUIC and PostgreSQL):
- Built evo-server, evo-world-clone, evo-grant-broker, evo-admin-api, evo-postgres-tests
and evo-cellular-admin-view-tests with -Werror (two missing-field-initializer errors
from the new aggregate members were fixed with default initializers).
- `cellular-admin-view-contracts` passed: header, totals, every cell row (id strings,
account text, position, extent, connected flag, members), the cell and deposit limits
keeping the lowest ids, empty lists, and an unchanged owner snapshot after rendering.
- `tools/ci/postgres-check.sh --suite-only` passed after the fixes above: token role
checks (required role present, absent, wrong shape; email), the admin API over world
9831 (public files with CSP/nosniff headers, `/config.json`, 405 for POST, 401 without or
with a foreign token, 403 without the role, no database contact before verification,
accounts with session/status/lives/resets, one account, 404s, regions, the view cache,
unviewable and unreachable regions, an offline database as 503, and the runtime role
still refused direct table reads), the migration path to schema 61 with the privilege
audit's new fenced functions, and the updated migration history expectation.
- `tools/ci/postgres-check.sh --full` passed (634 s: suite, migration partitions, life
reservations, backup, DR, upgrade, migration history, permission audit, checksum drift).
Two CI scripts that pin the newest schema were updated: history-domain-check's schema-50
rewind now drops the three schema-61 functions first, and the unknown-future-version
probe moves from 61 to 62.
- clang-tidy 19 with warnings as errors on every new or changed source passed after one
unchecked-optional fix in the view test; clang-format 19.1.5 applied to changed C++.
- Deploy suite (deploy-policy-check 80 objects / 150 rendered in 17 overlays, selftest,
ops-lib-check) passed with the new admin-portal-dev component.
- Local process smoke of the built evo-admin-api with the realm's pinned JWKS and a
placeholder (unreachable) database: `/`, `/app.js`, `/style.css`, `/config.json`,
`/healthz` answered 200 with the expected types and security headers, `/api/accounts`
401 for a malformed token, `/missing` 404; no arguments exit 2 with usage.
- `node --check` on the portal script.
Limits: no Keycloak sign-in, browser session or live region view was exercised (the
Keycloak client, Ingress, Secret and a new server image are not in place yet); account
lives and deaths were checked only on accounts without lives. The MSVC and sanitizer
presets and the image build/smoke were not run locally. Nothing was deployed, pushed or
synced; no World0, stage or live database operation occurred.