message_bus/reports/0013-2026-06-07-unibus-admin-panel.md

# Report 0013 — unibus_admin: panel web de administración

- **Fecha:** 07/06/2026
- **Autor:** agente (Claude)
- **Ámbito:** app nueva `projects/message_bus/apps/unibus_admin` (sub-repo Gitea `dataforge/unibus_admin`), desplegada en magnus
- **Estado:** done

## Resumen

Panel web de administración del bus `unibus`: un único binario Go que sirve una SPA
Mantine embebida (`embed.FS`) y expone una REST API. El binario tiene la identidad
ADMIN del operador y media cada acción contra el plano de control del bus firmando
las peticiones; el navegador nunca firma, nunca habla NATS ni ve una clave privada.
Tres capacidades: **Cluster** (salud + posture de los 3 nodos), **Rooms** (listar,
crear, ver miembros, invitar, expulsar+rekey) y **Users** (allowlist del bus).
Verificado end-to-end contra el cluster vivo (magnus+homer+datardos, enforce+TLS+KV)
y desplegado en magnus tras Caddy con basic auth en un subdominio ofuscado.

## Arquitectura

```
navegador (SPA Mantine, dark/índigo)
   │  fetch /api/*   — basic auth de Caddy + bind loopback (doble barrera)
   ▼
unibus_admin (gateway Go) — identidad ADMIN del operador
   ├── pkg/client (unibus)      CreateRoom / Invite / Kick / ListMyRooms   (firma + cripto E2E)
   ├── GET firmado a mano        /rooms/{id}/members  (membership.CanonicalRequest + cs.SignEd25519)
   ├── GET /healthz CA-pinned    posture de cada nodo del cluster
   └── membership.Store (opc.)   users (sólo con --db / acceso KV)
   ▼
cluster unibus  (magnus + homer + datardos, --store kv --kv-replicas 3, enforce+ACL+TLS)
```

Decisión clave: el gateway **reutiliza el cliente del bus** para todo lo que lleva
criptografía (sellar la clave de room en create/invite, rotar en rekey) y construye
GETs firmados con la **única fuente de verdad** de la firma del bus
(`membership.CanonicalRequest` + `cs.SignEd25519`, ambos exportados) para las lecturas
que el cliente no expone (lista de miembros). No reimplementa firma ni cripto. La
identidad se carga de `pass unibus/operator-identity` (dev) o de un fichero 0600
(`--identity-file`, producción). El TLS se ancla a la CA del bus (`busauth.LoadCATLSConfig`).

Capa de repositorio (`internal/admin/Repo`): dos implementaciones —`busRepo` (real) y
`mockRepo` (`--mock`)— detrás de los mismos handlers REST, así la SPA tiene un único
camino de código para mock y real.

## Cambios / artefactos creados

| Artefacto | Qué |
|---|---|
| `main.go`, `embed.go` | flags, carga de identidad, wiring, embed de `web/dist` |
| `internal/admin/repo.go` | interface `Repo` + tipos wire (RoomView, MemberView, UserView, NodeHealth, Posture) |
| `internal/admin/repo_bus.go` | impl real: rooms (client), members (GET firmado), cluster (healthz CA-pinned), users (Store) |
| `internal/admin/repo_mock.go` | datos de muestra para iterar la UI |
| `internal/admin/server.go` | REST `/api/*` + servidor de la SPA embebida (fallback SPA) |
| `internal/admin/identity.go` | carga de la identidad del operador desde `pass` o fichero 0600 |
| `web/` | SPA React 19 + Vite 6 + Mantine v9 (dark/índigo): AdminShell + ClusterPage + RoomsPage + UsersPage + api.ts |
| `app.md`, `deploy/unibus-admin.service`, `deploy/README.md` | registro + artefactos de deploy |

Repo Gitea: `dataforge/unibus_admin` (master, 3 commits). `git init -b master` dentro del
sub-repo se hizo inmediatamente tras el scaffold (apps/* gitignored en el padre).

## REST API del gateway

`GET /api/me` · `GET /api/cluster` · `GET /api/rooms` · `POST /api/rooms` ·
`GET /api/rooms/{id}/members` · `POST /api/rooms/{id}/invite` ·
`POST /api/rooms/{id}/kick` · `GET /api/users` · `POST /api/users` ·
`POST /api/users/revoke` · `GET /healthz`.

## Verificación (evidencia ejecutable)

### Build (verde)

```
$ CGO_ENABLED=0 go build ./...            # exit 0
$ CGO_ENABLED=0 go vet ./...              # exit 0
$ cd web && pnpm build                    # tsc -b && vite build → dist/ (485 KB JS, 222 KB CSS)
$ CGO_ENABLED=0 GOOS=linux go build       # ELF estático 18.9 MB
```

### Golden path — membershipd local, posture auth-off (sqlite)

```
POST /api/rooms {"subject":"ops.deploy","encrypt":true,...} → 201 {"room_id":"01KTHJF18N...","role":"owner"}
GET  /api/rooms          → [ops.deploy epoch 1 owner]            (ListMyRooms vía client)
GET  /api/rooms/{id}/members → [{endpoint:vI8HX..., role:owner, sign_pub, kex_pub}]  (GET firmado)
POST /api/users {ana,...} → 201 added ; GET /api/users → operator+ana active
POST /api/users/revoke {ana} → 200 ; GET /api/users → ana=revoked
GET  /api/cluster        → magnus up, posture store:sqlite
```

### Error path + posture de PRODUCCIÓN — membershipd local enforce + TLS + nkey

```
GET  /api/me      → endpoint del operador derivado de la identidad cargada de pass
GET  /api/cluster → magnus up, posture {enforce:true, acl:true, tls:true}    (healthz https)
GET  /api/rooms   → 200 (ListMyRooms): exige conexión nkey+TLS y petición FIRMADA verificada bajo enforce
GET  /api/rooms/{id}/members → 200 (GET firmado verificado bajo enforce)
POST /api/rooms (E2E) → 201 (firma + clave sellada)
GET  /api/rooms/01XXXXNOEXISTE/members → 403 {"error":"forbidden: not a member of this room"}   ← error path
```

### Contra el CLUSTER VIVO (magnus público, internet)

```
GET /api/cluster → magnus UP posture{enforce,acl,tls,cluster,store:kv} (86 ms)
GET /api/rooms   → 3 rooms reales del operador (test.gapcheck.*)   ← operador allowlisted en el cluster KV
```

### Despliegue en magnus (verificado en el host y por URL pública)

```
ssh magnus systemctl is-active unibus-admin.service        → active
ssh magnus curl 127.0.0.1:8480/api/cluster
  → [magnus UP 3ms, homer UP 39ms, datardos UP 7ms]  los 3 nodos, posture enforce+acl+tls+cluster+kv

# URL pública (subdominio ofuscado + basic auth de Caddy):
curl https://admin-<hash>.organic-machine.com/healthz              → 401 (sin auth)
curl -u admin:*** https://admin-<hash>.../healthz                  → {"status":"ok"}
curl -u admin:*** https://admin-<hash>.../api/cluster              → 3 nodos UP
```

### Visual (browser MCP)

- Local mock: las 3 pestañas renderizan (Cluster 2/3 con datardos DOWN; Rooms 4 salas
  con badges E2E/cleartext, epoch, rol, modal crear + drawer miembros; Users 4 con
  ADMIN/MEMBER/REVOKED y revoke sólo en activos).
- URL pública desplegada: SPA renderiza la pestaña Cluster con **3/3 UP** reales
  (magnus 0ms, homer 12ms, datardos 7ms) y el endpoint del operador, sin badge MOCK.

## Estado del deploy en magnus

- `unibus-admin.service` (systemd system, `Restart=always`), binario en
  `/opt/unibus_admin/unibus_admin`, identidad 0600 en `/opt/unibus_admin/identity.json`.
- Puerto `8480` en loopback. Caddy site aditivo
  `admin-<hash>.organic-machine.com` → basic auth (user `admin`) → `reverse_proxy 127.0.0.1:8480`.
  Caddyfile validado y recargado; bloques existentes (gitea/registry/grafana/metrics/logs)
  intactos; `membershipd-cluster.service` y `caddy` siguen `active`.
- Credenciales y URL en `pass`: `unibus/admin-panel-password`, `unibus/admin-panel-url`.
- Backup del Caddyfile previo a la edición: `/etc/caddy/Caddyfile.bak.unibus_admin.<ts>`.

## Gaps / pendientes

- **Users en el cluster (KV)**: el plano de control no expone endpoint HTTP de users
  (viven sólo en el store). Con el cluster en `--store kv`, el gateway aún no abre el
  KV, así que en producción la pestaña **Users queda degradada** (estado informativo:
  `users_backend=none`). Funciona en single-node con `--db`. Se habilita con la vía de
  alta KV de la rama `quick/0011-deploy-gaps` del repo unibus (otro agente) o con un
  cliente KV admin. No se duplicó ese trabajo.
- **meta-leader / tamaño de quórum**: `/healthz` sólo da status + posture; el líder
  RAFT y el nº de réplicas vivas requieren el endpoint de monitoreo de NATS (varz/jsz),
  no expuesto. La pestaña Cluster muestra up/posture/latencia de cada nodo.
- **Invite a room E2E**: pide sign_pub + kex_pub del invitado en hex (la clave de room
  se sella contra su X25519). No hay directorio de claves públicas; la UI los pide a mano.
- **Login propio de la app**: hoy la auth es la basic auth de Caddy + bind loopback. Un
  login a nivel de app (sesión, roles en la UI) queda como mejora futura.
- **Vida útil (Capa 3 DoD)**: recién desplegado hoy; el criterio de >=7 días de uso real
  sin romper queda por acumular. El service tiene `Restart=always` y healthz para
  observabilidad.