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
+5 -1
View File
@@ -145,7 +145,8 @@ RUN cmake --preset release -B build/postgres -DCMAKE_CXX_COMPILER=g++-14 \
-DCMAKE_C_COMPILER=gcc-14 -DEVO_BUILD_NETWORK=ON \
-DEVO_BUILD_QUIC=ON -DEVO_BUILD_POSTGRES=ON \
-DPostgreSQL_ROOT=/source/.cache/postgres/install \
&& cmake --build build/postgres --target evo-server evo-session-probe evo-world-clone evo-grant-broker --parallel "${PG_BUILD_JOBS}"
&& cmake --build build/postgres --target evo-server evo-session-probe evo-world-clone evo-grant-broker \
evo-admin-api --parallel "${PG_BUILD_JOBS}"
FROM postgres-build AS postgres-test-build
ARG PG_BUILD_JOBS=6
@@ -202,6 +203,9 @@ COPY --from=postgres-build /source/build/postgres/evo-server /usr/local/bin/evo-
COPY --from=postgres-build /source/build/postgres/evo-world-clone /usr/local/bin/evo-world-clone
# ADR-0131 grant broker (Keycloak tokens to session grants); its own Deployment.
COPY --from=postgres-build /source/build/postgres/evo-grant-broker /usr/local/bin/evo-grant-broker
# ADR-0182 read-only admin API and the portal's static files; its own Deployment.
COPY --from=postgres-build /source/build/postgres/evo-admin-api /usr/local/bin/evo-admin-api
COPY apps/evo-admin-api/portal/ /usr/local/share/evo-admin-portal/
COPY --from=postgres-build /source/.cache/postgres/install/lib/libpq.so* /opt/postgres/lib/
COPY --from=postgres-build /source/build/postgres/msquic/bin/Release/libmsquic.so* /opt/msquic/lib/
COPY --from=postgres-build /source/.cache/postgres/postgresql-18.6/COPYRIGHT /usr/share/doc/evo-postgres/COPYRIGHT
@@ -0,0 +1,88 @@
# ADR-0182 read-only admin API and portal. One replica; it holds no state but a short view
# cache. The realm's public signing key is pinned below (ADMIN_JWKS, the same key as the grant
# broker's); a Keycloak key rotation needs a Git update in both.
apiVersion: apps/v1
kind: Deployment
metadata:
name: evo-admin-portal
annotations:
argocd.argoproj.io/sync-wave: "2" # After migration (schema v61).
labels:
app.kubernetes.io/name: evo-admin-portal
app.kubernetes.io/component: admin-portal
spec:
replicas: 1
revisionHistoryLimit: 3
progressDeadlineSeconds: 180
selector:
matchLabels:
app.kubernetes.io/name: evo-admin-portal
template:
metadata:
labels:
app.kubernetes.io/name: evo-admin-portal
app.kubernetes.io/component: admin-portal
app.kubernetes.io/part-of: aevolution
spec:
serviceAccountName: aevolution-admin-portal
automountServiceAccountToken: false
terminationGracePeriodSeconds: 10
securityContext:
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
fsGroup: 10001
seccompProfile: {type: RuntimeDefault}
containers:
- name: evo-admin-api
image: aevolution-server
command: ["/bin/bash", "-c"]
args:
- |
set -eu
regions=()
for region in $ADMIN_REGIONS; do regions+=(--region "$region"); done
exec /usr/local/bin/evo-admin-api --listen 0.0.0.0:8080 --world "$ADMIN_WORLD" \
--jwks "$ADMIN_JWKS" --oidc-issuer "$ADMIN_OIDC_ISSUER" \
--audience aevolution-admin --client aevolution-admin-portal \
--role aevolution-admin --assets /usr/local/share/evo-admin-portal \
--pg-service /run/postgres/pg_service.conf --pg-passfile /run/postgres/pgpass \
"${regions[@]}"
env:
- {name: ADMIN_WORLD, value: "100"}
# Space-separated REGION=HOST:PORT: each region's operations address for /admin/view.
- {name: ADMIN_REGIONS, value: "16=evo-region-ops:9100"}
- {name: ADMIN_OIDC_ISSUER, value: "https://auth.aeternalisgames.com/realms/aeternalis"}
# Public RS256 signing key(s) of realm aeternalis, from its JWKS endpoint.
- name: ADMIN_JWKS
value: '{"keys":[{"alg":"RS256","e":"AQAB","kid":"NGQG4QzQuBCIHVEomUPy-OoWOTVQIuyf3RXqeNbP8JI","kty":"RSA","n":"vvOpu1xxdyH_mB8LkJG6cwc6UVmmAj6mwQi1oEwrpJDLerBI2OZr2kpgMAUJ3-hMIkz5tRtSjHieMFteVrpDDQaCViIPCIvJTL3T7ujTGFNReSE6ho7h0DB_kybFeEWVpLqm6SSXWFYls5TKo6_t8Hw4G3njiRW9pX_NxyaBHqLkrCi63EyIGHOkdgUczg2d4pM4JTt-q25bcFSlYz8bhD3WEORQmbp-bU7aPPluCqCEAZRrbzf8Iy7svNemP5daDdlWQ3LaNy-ixC2HRjiPZdqK5BgAE800BigI-l1dkyJ4X172TLIPVPLW1WKlvdm3kHOpBXwACYiy8boSNDW7gQ","use":"sig"}]}'
ports:
- {name: http, containerPort: 8080, protocol: TCP}
readinessProbe:
httpGet: {path: /healthz, port: http}
periodSeconds: 5
timeoutSeconds: 1
livenessProbe:
httpGet: {path: /healthz, port: http}
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3
resources:
requests: {cpu: 10m, memory: 16Mi}
limits: {memory: 128Mi}
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities: {drop: [ALL]}
volumeMounts:
- {name: connection, mountPath: /run/postgres, readOnly: true}
volumes:
- name: connection
secret:
secretName: aevolution-admin-pg
defaultMode: 0440
items:
- {key: pg_service.conf, path: pg_service.conf}
- {key: pgpass, path: pgpass}
- {key: ca.crt, path: ca.crt}
@@ -0,0 +1,15 @@
# ADR-0182 read-only admin API and portal for evolution-dev ONLY: verifies Keycloak access
# tokens (realm aeternalis, realm role aevolution-admin, audience aevolution-admin) and reads
# world 100 through the schema v61 views and region 16's /admin/view.
# Public route, 443 only: https://srs.aeternalisgames.com -> ingress-nginx (TLS; Ingress
# created out of band, since the aevolution-dev Argo project admits none) -> ClusterIP
# Service evo-admin-portal:8080, in-cluster only.
# Out-of-band Secret in evolution-dev: aevolution-admin-pg (pg_service.conf, pgpass, ca.crt
# for a login in the runtime group, as aevolution-grant-broker-pg).
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
- serviceaccount.yaml
- deployment.yaml
- service.yaml
- networkpolicy.yaml
@@ -0,0 +1,58 @@
# Admin portal traffic on top of the namespace default-deny. Admins reach it only at
# https://srs.aeternalisgames.com on 443, where ingress-nginx terminates TLS; port 8080 is
# admitted from the ingress-nginx pods and nothing else. Egress: PostgreSQL on pg-forge-01
# and the region's operations port (9100) for /admin/view.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: evo-admin-portal
annotations:
argocd.argoproj.io/sync-wave: "-1"
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: evo-admin-portal
policyTypes: [Ingress, Egress]
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
podSelector:
matchLabels:
app.kubernetes.io/name: rke2-ingress-nginx
ports:
- {protocol: TCP, port: 8080}
egress:
- to:
- ipBlock:
cidr: 172.10.1.127/32
ports:
- {protocol: TCP, port: 5432}
- to:
- podSelector:
matchLabels:
app.kubernetes.io/name: evo-region
ports:
- {protocol: TCP, port: 9100}
---
# The region's operations port also admits the admin portal (alongside Prometheus,
# evo-region-scrape). Only 9100: never the session port.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: evo-region-admin-view
annotations:
argocd.argoproj.io/sync-wave: "-1"
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: evo-region
policyTypes: [Ingress]
ingress:
- from:
- podSelector:
matchLabels:
app.kubernetes.io/name: evo-admin-portal
ports:
- {protocol: TCP, port: 9100}
@@ -0,0 +1,15 @@
# Cluster-internal; the Ingress for srs.aeternalisgames.com terminates TLS and forwards here.
apiVersion: v1
kind: Service
metadata:
name: evo-admin-portal
annotations:
argocd.argoproj.io/sync-wave: "2"
labels:
app.kubernetes.io/name: evo-admin-portal
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: evo-admin-portal
ports:
- {name: http, port: 8080, targetPort: http, protocol: TCP}
@@ -0,0 +1,10 @@
apiVersion: v1
kind: ServiceAccount
metadata:
name: aevolution-admin-portal
annotations:
argocd.argoproj.io/sync-wave: "-1"
automountServiceAccountToken: false
# Create this pull-only Secret separately in evolution-dev; never commit credentials.
imagePullSecrets:
- name: harbor-pull
@@ -9,6 +9,7 @@ resources:
components:
- ../dev-session-route
- ../../grant-broker-dev
- ../../admin-portal-dev
- ../../worker-only-dev
images:
- name: aevolution-server