docs: app.md reflects control-plane Users wiring and the deploy gap

Update the architecture diagram, capability table, run examples and known
gaps to describe user management via the signed control-plane API instead
of the old store-only/--db path. Record the remaining gap honestly: the
membershipd binaries currently deployed on the cluster predate the /users
route and return 404, so the Users tab becomes functional in production
once the bus is updated to v0.10.0; the gateway already connects and signs
correctly against those nodes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-07 21:10:41 +02:00
parent c7631074cb
commit 1b19f8e60f
+18 -10
View File
@@ -58,9 +58,10 @@ navegador (SPA Mantine)
unibus_admin (gateway Go, identidad ADMIN del operador)
├── pkg/client (unibus) → CreateRoom / Invite / Kick / ListMyRooms (firma + cripto E2E)
├── pkg/client (unibus) → ListUsers / AddUser / RevokeUser (API admin firmada; funciona en cluster)
├── GET firmado → /rooms/{id}/members (CanonicalRequest + SignEd25519, reusa la construcción del bus)
├── GET /healthz (CA-pinned)→ estado + posture de los 3 nodos del cluster
└── membership.Store (opc.) → users (allowlist) cuando hay acceso directo al store
└── membership.Store (opc.) → users (allowlist) como fallback single-node con --db
cluster unibus (magnus + homer + datardos, enforce + ACL + TLS + KV)
```
@@ -77,7 +78,7 @@ no expone. Nunca reimplementa firma ni cripto.
|---|---|---|
| **Cluster** | up/down + posture (enforce/acl/tls/cluster/store) + latencia de cada nodo | `GET /healthz` (auth-exempt) de los nodos en `--nodes`, TLS pin a la CA del bus |
| **Rooms** | listar (rooms del admin), crear (subject + E2E/persist/firmado), ver miembros, invitar, expulsar+rekey | `pkg/client` (mutaciones) + GET firmado (miembros) |
| **Users** | listar/añadir/revocar la allowlist del bus | `membership.Store` directo — sólo con `--db` (single-node) o acceso KV admin |
| **Users** | listar/añadir/revocar la allowlist del bus | `pkg/client` (`ListUsers`/`AddUser`/`RevokeUser`) contra la API admin-only del plano de control, firmando como el operador. Funciona en cluster (los nodos escriben al mismo store que las rooms) sin acceso directo al store. `--db` queda como fallback single-node opcional |
## Cómo arrancar
@@ -85,13 +86,14 @@ no expone. Nunca reimplementa firma ni cripto.
# Mock (iterar la SPA sin bus):
./unibus_admin --mock --port 8480
# Real contra un membershipd local (dev, sqlite, sin TLS):
# Real contra un membershipd local (dev, sin TLS). Users vía la API del plano de
# control; añade --db sólo si quieres gestionar users contra un SQLite local:
./unibus_admin --port 8480 \
--ctrl-url http://127.0.0.1:8470 --nats-url nats://127.0.0.1:4250 \
--db ./local_files/unibus.db \
--identity-pass unibus/operator-identity
# Producción (cluster magnus, enforce + TLS + nkey):
# Producción (cluster magnus, enforce + TLS + nkey). Sin --db: la pestaña Users
# gestiona la allowlist por la API admin firmada del plano de control:
./unibus_admin --port 8480 --bind 127.0.0.1 \
--ctrl-url https://127.0.0.1:8470 --nats-url tls://127.0.0.1:4250 \
--ca /opt/unibus/tls/ca.crt \
@@ -127,11 +129,17 @@ ofuscado (`admin-<hash>.organic-machine.com`). Credenciales en `pass`
## Gaps conocidos
- **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 no abre el KV
todavía, así que la pestaña Users queda degradada (estado informativo). Se habilita
con la vía de alta KV que añade la rama `quick/0011-deploy-gaps` del repo unibus, o
con `--db` en single-node.
- **Users contra el cluster desplegado**: el código del plano de control (unibus
master, v0.10.0) ya expone la API admin-only de users (`GET/POST /users`,
`POST /users/{signpub}/revoke`) y el gateway la consume firmando como el operador.
La cadena completa (list/add/revoke + idempotencia 409) está verificada end-to-end
contra un `membershipd` master local. El gap restante es de **despliegue**: los
binarios `membershipd` que corren hoy en el cluster (magnus/homer/datardos) son
anteriores al merge de esta ruta y devuelven `404` en `/users`, así que la pestaña
Users sólo será funcional en producción cuando el bus se actualice a v0.10.0. El
gateway ya conecta y firma correctamente contra esos nodos (verificado: `/api/me`
responde con el endpoint real del operador y pasa el `enforce` de magnus). Para
gestión single-node sin esperar al cluster, `--db` sigue disponible.
- **meta-leader / tamaño de quórum** del cluster: `/healthz` no los expone; requieren
el endpoint de monitoreo de NATS (varz/jsz). La pestaña Cluster muestra up/posture.
- **Invite a room E2E**: requiere las claves públicas (sign_pub + kex_pub) del