message_bus/reports/0012-2026-06-07-unibus-deploy-gaps-closed.md

Report 0012 — Cierre de los gaps del despliegue del cluster unibus (report 0011)

• Fecha: 07/06/2026
• Autor: agente (Claude)
• Ámbito: projects/message_bus/apps/unibus/ (sub-repo dataforge/unibus) — cierre de los gaps que el despliegue del cluster de 3 nodos (report 0011) dejó abiertos. Rama quick/0011-deploy-gaps (worktree /tmp/unibus_gaps, basada en master).
• Estado: done — GAP A y GAP B cerrados con evidencia ejecutable contra el cluster VIVO (magnus + homer + datardos, R3); GAP C (runbook) corregido. Pendiente menor: rollout del binario nuevo a magnus+homer (documentado, sin urgencia — la capability está probada y desplegada en datardos).

Resumen

El report 0011 dejó tres gaps. Este trabajo los cierra: (A) membershipd user add|list|revoke --store kv añade usuarios al KV replicado con el cluster en marcha vía la conexión interna privilegiada — sin parar-sembrar-rearrancar; (B) cmd/clientcheck es la verificación end-to-end real del plano de datos (cliente autenticado nkey+TLS, room E2E, publish/subscribe, incluido failover con un nodo caído) que el chaos test del 0011 nunca ejecutó; (C) el runbook deploy/cluster/README.md queda corregido (orden de arranque, R1 inservible, nueva vía de alta). Todo verificado contra los 3 VPS reales con la posture enforce+ACL+TLS+R3 intacta. app.md sube 0.8.0 → 0.9.0.

Cambios

Archivo	Qué	Por qué
pkg/client/identity.go	LoadIdentity (load-only) extraída de LoadOrCreateIdentity	La CLI --store kv y el daemon cargan la identidad de servicio persistida; se preserva el guard "archivo corrupto = error, no se regenera".
cmd/membershipd/main.go	flag --internal-id-file	Persiste la identidad interna privilegiada (load-or-create, 0600) en vez de efímera, para que la misma nkey esté disponible fuera de proceso. Vacío = efímero (default dev/single-node sin cambios).
cmd/membershipd/users_kv.go	connectKVStore + reportKVReplication (nuevo)	Conexión privilegiada al NATS del cluster con la identidad interna; abre el store KV y escribe. Rechaza remoto sin --ca. Imprime followers_current tras escribir.
cmd/membershipd/users_cli.go	--store kv en add/list/revoke + idempotencia explícita	Alta/baja contra el KV vivo. Re-alta de la misma clave = ErrUserExists (sin sobrescribir ni elevar rol).
cmd/membershipd/kv_useradd_test.go (nuevo)	tests de integración GAP A	Golden bajo enforce, idempotencia, endpoint muerto, remoto-sin-CA.
cmd/clientcheck/ (nuevo)	comando de verificación E2E reutilizable	GAP B: cliente real, room E2E, golden + loop (failover).
deploy/cluster/README.md	runbook corregido	GAP C: arranque por quórum, R1 SPOF→R3, vía de alta live, topología real.
deploy/cluster/membershipd-cluster.service, deploy-cluster.sh	--internal-id-file ${INTERNAL_ID_FILE} + INTERNAL_ID_FILE en cluster.env	Para que un deploy fresco habilite la vía de alta live en todos los nodos.
app.md	0.8.0 → 0.9.0 + growth log	Nueva capability.

Mecanismo de la conexión privilegiada (GAP A) — diseño y porqué

Bajo enforce la ACL por-subject confina a cada usuario del bus a la JetStream API de SUS rooms; ninguna identidad de usuario normal puede tocar los buckets KV_UNIBUS_*. La única identidad a la que el autenticador concede permisos plenos de JetStream es la identidad de servicio interna de membershipd (la que ya rompe el ciclo bootstrap del nonce/KV). Esa identidad era efímera por proceso, así que ningún proceso externo podía presentarla.

Solución elegida (la más simple y segura de las opciones del prompt — "creds del propio servicio" + "ejecución por loopback en un nodo"): el daemon persiste su identidad de servicio en --internal-id-file (cada nodo genera/carga la suya, 0600, junto a las claves TLS del nodo). La CLI user add --store kv, ejecutada por loopback en el nodo (el SAN del cert data-plane cubre 127.0.0.1), carga ese mismo archivo y presenta la nkey que el autenticador del nodo reconoce con permisos plenos → abre OpenJetStream y escribe el bucket KV_UNIBUS_users replicado.

Seguridad (no baja la posture): leer el archivo de identidad exige root en el nodo, lo que ya implica control total de ese nodo (la clave TLS del servidor y el cluster.pass ya están ahí). Co-ubicarlo no añade exposición práctica. La posture publicada en /healthz (enforce+acl+tls+cluster+store=kv) es idéntica con o sin el flag. Cambio respecto a 0011: la identidad interna pasa de efímera a durable (rotable borrando el archivo + reinicio); documentado.

Verificación

Secretos redactados: clave privada del operador, su endpoint derivado, el hex del operador (48bc…) y los de usuarios de prueba se muestran truncados. Nota de build: el worktree vive en /tmp, donde el replace fn-registry => ../../../../ de go.mod no resuelve; se usó un go.work fuera del árbol (GOWORK=/tmp/unibus_gaps.work, NO commiteado) solo para compilar. El checkout canónico bajo ~/fn_registry/.../unibus no lo necesita.

Mecánica — vet + build + test (CGO_ENABLED=0)

$ CGO_ENABLED=0 go vet ./...            -> rc=0
$ CGO_ENABLED=0 go build ./...          -> rc=0
$ CGO_ENABLED=0 go test ./pkg/membership/ ./cmd/...
ok   github.com/enmanuel/unibus/pkg/membership   8.455s
?    github.com/enmanuel/unibus/cmd/chat         [no test files]
?    github.com/enmanuel/unibus/cmd/clientcheck  [no test files]
ok   github.com/enmanuel/unibus/cmd/membershipd  0.413s
?    github.com/enmanuel/unibus/cmd/worker       [no test files]

$ CGO_ENABLED=0 go test ./...   (suite completa)
ok   github.com/enmanuel/unibus/cmd/membershipd  0.370s
ok   github.com/enmanuel/unibus/pkg/blobstore    0.091s
ok   github.com/enmanuel/unibus/pkg/busauth      0.007s
ok   github.com/enmanuel/unibus/pkg/client       6.168s
ok   github.com/enmanuel/unibus/pkg/embeddednats 5.894s
ok   github.com/enmanuel/unibus/pkg/frame        0.002s
ok   github.com/enmanuel/unibus/pkg/membership   8.383s

Tests de integración GAP A (nodo enforce embebido, identidad de archivo):

$ go test ./cmd/membershipd/ -run TestUserAddStoreKV -count=1
ok   github.com/enmanuel/unibus/cmd/membershipd   0.050s
  TestUserAddStoreKV_GoldenAndIdempotent      (escribe bajo enforce + ErrUserExists sin sobrescribir)
  TestUserAddStoreKV_RequiresInternalIdentity (sin id file / id ausente -> error)
  TestUserAddStoreKV_UnreachableKV            (endpoint muerto -> error envuelto)
  TestUserAddStoreKV_RemoteWithoutCARefused   (remoto sin --ca -> rechazado)

GAP A — user add --store kv contra el cluster VIVO

Despliegue de verificación: binario nuevo + --internal-id-file a datardos (nodo no-crítico) con backups reversibles; arranca con identidad persistida, posture intacta, reincorporado a R3:

$ ssh dd ... (restart con binario nuevo)
internal service identity: persisted (/opt/unibus/secrets/internal.id)   # 0600 root
healthz: {"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}

Golden (alta nueva, replicada R3):

$ ssh dd 'sudo /opt/unibus/membershipd user add --store kv --handle gapcheck_user --role member --sign-pub a58b…5622'
added user "gapcheck_user" (a58b…5622) role=member
KV_UNIBUS_users: leader=homer followers_current=2/2 msgs=2     <-- replicado a los 2 followers

Lectura replicada (user list --store kv en datardos lee el KV replicado):

HANDLE         ROLE    STATUS  SIGN_PUB     CREATED
gapcheck_user  member  active  a58b…5622    2026-06-07T17:33:00Z
operator       admin   active  48bc…<op>    2026-06-07T16:48:12Z

Edge 1 — idempotencia (re-alta de la misma clave, y misma clave con otro rol):

$ ssh dd 'sudo .../membershipd user add --store kv --handle gapcheck_user --role member --sign-pub a58b…5622'
membershipd user add: user a58b…5622 already registered (unchanged); revoke it first to replace   (exit 1)
$ ssh dd 'sudo .../membershipd user add --store kv --handle impostor --role admin --sign-pub a58b…5622'
membershipd user add: user a58b…5622 already registered (unchanged); revoke it first to replace   (exit 1)
  -> NO se sobrescribe ni se eleva a admin (sin escalado de privilegios vía re-alta).

Edge 2 — alta con un nodo caído (quórum 2/3). Se para homer (líder del stream); el stream re-elige líder a datardos y el alta commitea:

>>> STOP homer (líder de KV_UNIBUS_users) — quedan datardos+magnus = quórum 2/3
homer is-active=inactive
$ ssh dd 'sudo .../membershipd user add --store kv --handle gapcheck_user2 --role member --sign-pub e560…4bf4'
added user "gapcheck_user2" (e560…4bf4) role=member
KV_UNIBUS_users: leader=datardos followers_current=1/2 msgs=3   <-- líder failover homer->datardos; commit con quórum
>>> START homer (rejoin) -> is-active=active ; healthz 3/3 ; user list muestra los 3 usuarios

Error 1 — KV inalcanzable (puerto muerto):

$ ssh dd 'sudo .../membershipd user add --store kv --nats-url nats://127.0.0.1:4999 --handle x --sign-pub a58b…5622'
membershipd user add: --store kv: connect cluster NATS "nats://127.0.0.1:4999": nats: no servers available for connection   (exit 1)

Limpieza (revoke de los 2 usuarios de prueba — revoke es flip de status, no hay hard-delete en KV):

$ ssh dd 'sudo .../membershipd user revoke --store kv a58b…5622'  -> revoked user a58b…5622
$ ssh dd 'sudo .../membershipd user revoke --store kv e560…4bf4'  -> revoked user e560…4bf4
$ user list --store kv:
  gapcheck_user   member  revoked   a58b…5622
  gapcheck_user2  member  revoked   e560…4bf4
  operator        admin   active    48bc…<op>

GAP B — verificación cliente END-TO-END real

Golden E2E (identidad operator de pass, CA por path, nkey+TLS+https a los 3 nodos, room E2E efímera, 5 msgs):

$ clientcheck --ca ca.crt --identity-file <operator.id 0600> \
    --nats-seeds nats://magnus,homer,datardos:4250 --ctrl-seeds https://...:8470 --messages 5
connected: endpoint=<redacted> nats=nats://51.91.100.142:4250
created E2E room: id=01KTHHXA… subject=test.gapcheck.968e58c37a2d3d81 (encrypt=true sign=true persist=false)
published 5 messages; waiting for decrypted echoes...
GOLDEN OK: all 5 messages received and decrypted end-to-end

Edge E2E — failover con cliente conectado. Loop publish/subscribe 1/s mientras se para el nodo atado (datardos):

loop: publishing every 1s for 1m0s — stop a node now to test failover
  t= 7s sent=7  recv=6  up=true node=nats://51.91.100.142:4250 publish=ok    <-- atado a datardos
>>> 19:29:07 STOP datardos (nodo atado)
  t= 8s sent=8  recv=7  up=true node=nats://135.125.201.30:4250 publish=ok   <-- FAILOVER a magnus, sin perder mensaje
  …
>>> 19:29:29 START datardos (rejoin)
  …
loop done: sent=56 received=56                <-- CERO pérdida a través del corte
  attached to nats://135.125.201.30:4250 for 49 ticks
  attached to nats://51.91.100.142:4250 for 7 ticks
FAILOVER OBSERVED: client was attached to 2 distinct nodes across the run
LOOP OK: client kept receiving across the run (received=56)

Cluster sano 3/3 tras el corte (datardos reincorporado a R3).

GAP C — runbook corregido

deploy/cluster/README.md:

• Arranque (corregido): "arrancar magnus solo y verificar healthz" deadlockea — un nodo solo de un cluster de 3 no tiene quórum del meta-group RAFT y JetStream nunca queda current, así que --store kv no crea los buckets y /healthz no devuelve ok hasta que se une un segundo nodo. Se documenta el arranque que forma quórum (los 3 cerca, el orden da igual) o escalonado apoyado en el retry loop de 120s; un nodo solo NUNCA se auto-sirve, así que no se debe condicionar el arranque del siguiente al healthz del anterior. Se nombran los 3 fixes de cold-start del 0011.
• R1 inservible (corregido): a R1 los 6 buckets viven en un solo nodo (SPOF de autenticación); el cold start solo converge con los 3 fixes; ir directo a R3 una vez formado el cluster. R1 es artefacto transitorio, no hito.
• Vía de alta con cluster vivo: nueva sección documentando user add --store kv (mecanismo, idempotencia, HA, sin hard-delete) que sustituye parar-sembrar-rearrancar.
• Topología real: IPs reales, ROUTE_NETWORK=public (no hay mesh WireGuard), magnus = host crítico convivido.

Gaps / pendientes

• Rollout del binario nuevo a magnus + homer: la verificación live de GAP A desplegó el binario 0.9.0 + --internal-id-file solo en datardos (nodo no-crítico). magnus y homer siguen con el binario 0011. La capability de alta está probada y disponible desde datardos; la escritura replica R3 a los otros dos. Estado mixto seguro a nivel de protocolo (cambios aditivos/node-local, posture idéntica). Para uniformidad + redundancia de la capability, rodar el binario a homer y magnus (comandos exactos en el README, con backups y healthz entre nodos). Se dejó como decisión del operador por tocar el host crítico magnus y por haber dos agentes vivos en el sub-repo; no es urgente.
• Sin hard-delete de usuarios en KV: revoke deja la fila en estado revoked (denegada en ambos planos, auditable); el KV no borra filas, igual que el store SQLite. Los dos gapcheck_user* de prueba quedan revocados (inertes; sus claves privadas eran aleatorias y descartadas). No se inventó un delete a medias (regla del prompt).
• Sin borrado de la room de prueba (GAP B): el control plane no expone borrado de rooms (no hay endpoint ni DeleteRoom en el store). Las rooms test.gapcheck.<rand> creadas (efímeras, E2E, solo el operator como miembro, subject aleatorio) quedan como filas en KV_UNIBUS_rooms/members (inocuas, sin tráfico). Documentado; no se inventó un delete.
• kill-2/3 (pérdida de quórum): fuera de scope (esperado fail-closed); el runbook lo deja como paso manual.
• Push a Gitea del 0011: sigue pendiente del operador (gap heredado del 0011, ajeno a este trabajo). Esta rama quick/0011-deploy-gaps se pushea a origin para revisión; NO se mergea a master (lo revisa el operador).

Commits (rama quick/0011-deploy-gaps)

e1a7402 chore: bump unibus to 0.9.0 (live user-add + clientcheck)
ce72131 docs(cluster): correct runbook + wire --internal-id-file into deploy
3aa5a2c feat(clientcheck): end-to-end client verification (E2E room + failover)
02c2004 feat(membershipd): user add/list/revoke --store kv against a live cluster