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:
@@ -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
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user