message_bus/reports/0008-2026-06-07-unibus-admin-users-wired.md

# Report 0008 — unibus_admin: pestaña Users cableada a la API del plano de control

- **Fecha:** 07/06/2026
- **Autor:** agente (Claude Opus 4.8)
- **Ámbito:** `projects/message_bus/apps/unibus_admin` (gateway Go + SPA Mantine), sub-repo `dataforge/unibus_admin`, rama `master`
- **Estado:** done (código + verificación E2E del código) — con un gap de **despliegue** del bus documentado abajo

## Resumen

La pestaña Users del panel de administración de unibus estaba degradada en cluster
porque el gateway sólo sabía gestionar la allowlist abriendo el `membership.Store`
directo con `--db`, y caía a `users_backend=none` (estado informativo) cuando no había
acceso directo al store. El control plane de unibus ahora expone una API HTTP admin-only
de users, y `pkg/client` la envuelve con `ListUsers/AddUser/RevokeUser` firmados. Este
trabajo cablea el gateway a esos métodos (camino principal: API HTTP firmada, funciona
en cluster), deja la pestaña Users operativa (sin el estado "degradado"), y verifica la
cadena completa list → add → revoke (con idempotencia 409) end-to-end contra un
`membershipd` master real. `--db` queda como fallback single-node explícito.

## Cambios

| Archivo | Cambio |
|---|---|
| `internal/admin/repo.go` | Eliminado `ErrUsersUnavailable` y el camino "none"; comentarios del interface `Repo` y de `MeInfo.UsersBackend` actualizados (`"control-plane"` \| `"sqlite"`). |
| `internal/admin/repo_bus.go` | `ListUsers/AddUser/RevokeUser` usan `r.cli.*` (API firmada) cuando no hay store directo; con `--db` siguen usando el store. `UsersWritable()` → `true` (el gateway conectado siempre puede; el control real es `requireAdmin` en runtime). Backend por defecto `"control-plane"`, `"sqlite"` con `--db`. |
| `internal/admin/server.go` | Handlers `/api/users` simplificados (cualquier error del control plane → 502 con su mensaje, que ya trae el código embebido, p.ej. `(HTTP 409)`); quitado el manejo de `ErrUsersUnavailable` y el import `errors`. |
| `main.go` | `--db` documentado como opcional (fallback single-node); por defecto el backend es `control-plane`. Logs de arranque acordes. |
| `web/src/pages/UsersPage.tsx` | Quitado el `Alert` "Gestión de users no disponible" y el gating `writable` (botón Add deshabilitado / revoke oculto). El badge muestra `backend: <control-plane\|sqlite>`. La tabla (handle/rol/estado/sign_pub/creado), el modal Add (handle + sign-pub hex64 + rol) y revoke con confirmación se mantienen. |
| `web/dist/*` | Bundle SPA recompilado (embebido por el binario). |
| `app.md` | Diagrama, tabla de capacidades, ejemplos de arranque y gaps actualizados al cableado control-plane + el gap de despliegue del bus. |

El gateway **reutiliza** los métodos del cliente del bus (`pkg/client`), no reimplementa
firma ni HTTP. No se tocó el repo `unibus` (sólo se importa por `replace => ../unibus`).

## Verificación

### Mecánica (verde)

```
go vet ./...        → VET_EXIT:0
go build -o unibus_admin .   → BUILD_EXIT:0  (19 MB, embebe la SPA)
cd web && pnpm build         → tsc -b + vite build OK (sin errores de tipo)
```

### Cobertura E2E del código (verde) — contra `membershipd` master real

El cluster de producción aún no expone la ruta `/users` (ver Gaps), así que la cadena
del panel se verificó contra un `membershipd` compilado de master (con la ruta) arrancado
localmente (sqlite, `--bus-auth soft`), con el operador sembrado como admin
(`membershipd user add --role admin`). El gateway firma como el operador; el bus verifica
con `requireAdmin`. Secuencia ejecutada **por la API del panel** (`/api/users`):

| Paso | Comando (gateway en :18481) | Resultado |
|---|---|---|
| list (antes) | `GET /api/users` | `[operator(admin,active)]` |
| add | `POST /api/users {gapcheck_admin_ui, member}` | `201 {"status":"added"}` |
| list | `GET /api/users` | `gapcheck_admin_ui` **active/member** + operator |
| re-alta (idempotencia) | `POST /api/users` (mismo sign_pub) | `409` `user already registered (unchanged); revoke it first` |
| revoke | `POST /api/users/revoke {sign_pub}` | `200 {"status":"revoked"}` |
| list (final) | `GET /api/users` | `gapcheck_admin_ui` **revoked** + `revoked_at`; operator intacto |

`sign_pub` de prueba: `1cb658d9d3f23e6bf5791a3865a1eec731f3df30ad4b85f6fca0074b8bdc98a4`
(aleatorio, role member). Limpieza: revocado al final (revoke es la limpieza; no hay hard
delete). El operador admin y la DB de prueba vivían en `/tmp` efímero, ya borrados. **No se
tocó la allowlist del cluster de producción.**

### SPA (verde) — verificada visualmente (browser MCP)

Panel servido en `:18481`, pestaña Users:
- Badge `backend: control-plane` (sin Alert degradado), botón "Añadir user" **activo**.
- Tabla con `gapcheck_admin_ui` MEMBER/REVOKED (sin botón revoke por estar revocado) y
  `operator` ADMIN/ACTIVE (con botón revoke).
- Modal "Añadir user al bus" renderiza Handle + `sign_pub (hex, 64)` + Rol(member) +
  Cancelar/Añadir.

### Conectividad contra el cluster vivo (verde, salvo la ruta ausente)

- Gateway local apuntado a homer (`141.94.69.66:8470`) + datardos (`51.91.100.142:8470`),
  TLS+nkey con la CA del bus, identidad operator desde `pass`: **conecta y firma**
  (`/api/me` devuelve el endpoint real del operador `vI8HXcintzK-…`). `GET /api/users`
  → `404 page not found` desde el control plane (ruta ausente en esos binarios).
- Panel efímero arrancado **en magnus** (puerto 18482, sin tocar el `unibus-admin.service`)
  contra el control plane loopback de magnus (KV, enforce, TLS): `/api/me` OK (pasa el
  `enforce` de magnus firmando como operador), `GET /api/users` → `404`. El binario
  efímero y su log se borraron; el service real quedó `active`.

## Estado del deploy en magnus

**No se re-desplegó el service.** El panel `unibus-admin.service` sigue `active` en magnus
(healthz 200). Build linux/amd64 del binario nuevo: **listo** (probado en magnus en puerto
efímero). El re-deploy queda **bloqueado por una dependencia**: re-desplegar ahora cambiaría
la pestaña Users de un Alert informativo a un error `502 (GET /users → 404)`, porque el
`membershipd` de magnus aún no expone la ruta. Procedimiento para cuando el bus esté en
v0.10.0 (aditivo, sin tocar otros sites del Caddyfile):

```bash
cd web && pnpm install && pnpm build && cd ..
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o unibus_admin .
scp unibus_admin magnus:/opt/unibus_admin/unibus_admin
ssh magnus 'systemctl restart unibus-admin.service'   # el unit ya arranca sin --db (backend control-plane)
ssh magnus 'curl -fsS http://127.0.0.1:8480/healthz'  # + comprobar la pestaña Users vía el subdominio Caddy
```

El `deploy/unibus-admin.service` no necesita cambios para el camino control-plane (no usa
`--db`). Verificar tras el restart que `ExecStart` no incluye `--db` (si lo incluyera,
quitarlo para usar la API del plano de control).

## Gaps / pendientes

1. **Cluster sin la ruta `/users` (despliegue).** Los `membershipd` desplegados
   (magnus/homer/datardos) son anteriores al merge de la API de users y devuelven 404. La
   verificación E2E del panel contra el cluster vivo **de producción** no es posible hasta
   actualizar el bus a v0.10.0. La cadena está verificada contra un `membershipd` master
   real (mismo código que correrá en el cluster), y el gateway ya conecta y firma bien
   contra los nodos reales. Acción fuera de este aislamiento (toca el repo `unibus`/su
   deploy): actualizar los binarios del cluster.
2. **Mapeo de código de estado.** Un `409` (re-alta idempotente) del control plane llega a
   la SPA como `502` con el mensaje del bus (que incluye `(HTTP 409)`). La SPA muestra el
   mensaje íntegro, así que la UX es correcta y accionable; no se parseó el string de error
   para propagar el código exacto (se evitó un parser frágil — KISS). Mejora menor opcional
   si `pkg/client` expone el status estructuradamente.
3. **Replicación `followers 2/2`.** No se inspeccionó la replicación KV cross-node porque la
   ruta `/users` no está viva en el cluster; el panel no expone métricas de JetStream
   (varz/jsz) — gap ya conocido de la pestaña Cluster.