feat(infra): auto-commit con 86 cambios
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: agentes-dispositivos-mesh
|
||||
id: 0009
|
||||
status: pending
|
||||
created: 2026-05-23
|
||||
updated: 2026-05-23
|
||||
priority: high
|
||||
risk: high
|
||||
related_issues: [0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143]
|
||||
apps: [agents_dashboard, agents_and_robots, wg_hub, device_agent]
|
||||
projects: [element_agents]
|
||||
vaults: []
|
||||
capability_groups: [wireguard, device-agent, docker-agent]
|
||||
trigger: manual
|
||||
schedule: ""
|
||||
expected_runtime_s: 300
|
||||
tags: [mesh, wireguard, matrix, e2ee, agents, devices, docker, sandboxing]
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Hablar desde Element con dispositivos completos (PCs, moviles, raspberry, IoT) y con
|
||||
contenedores Docker como si fueran agentes Matrix. Cada device/container ejecuta sus
|
||||
capabilities declaradas (shell/fs/camera/docker/sensores) bajo:
|
||||
|
||||
1. **Mesh WireGuard** anclado en `organic-machine.com` — sin abrir puertos en los devices.
|
||||
2. **Matrix E2EE** como bus de control y chat — un room por device/container.
|
||||
3. **Capability manifest firmado** ed25519 — el device rechaza lo que no este firmado.
|
||||
|
||||
## Pre-requisitos
|
||||
|
||||
- VPS `organic-machine.com` con root SSH (alias `vps` en `~/.ssh/config`).
|
||||
- `agents_and_robots` y `agents_dashboard` desplegados (ya OK).
|
||||
- `pass` con clave operador ed25519 (`pass insert operator/ed25519` — crear si falta).
|
||||
- `apt-get install wireguard wireguard-tools` permitido en el VPS.
|
||||
- Devices Linux/WSL: sudo sin password para `wg`, `wg-quick`, `systemctl`.
|
||||
- Devices Android: Termux + WireGuard app + `pkg install golang openssh-client`.
|
||||
|
||||
## Funciones del registry recomendadas
|
||||
|
||||
| Rol | Funcion candidata | Estado |
|
||||
|---|---|---|
|
||||
| WG install (host) | `wg_install_bash_infra` | FALTA: crear |
|
||||
| WG keygen | `wg_keygen_go_infra` | FALTA: crear |
|
||||
| WG hub setup | `wg_hub_setup_bash_infra` | FALTA: crear |
|
||||
| WG peer add (hub) | `wg_peer_add_go_infra` | FALTA: crear |
|
||||
| WG peer remove (hub) | `wg_peer_remove_go_infra` | FALTA: crear |
|
||||
| WG peer revoke (kill switch) | `wg_peer_revoke_go_infra` | FALTA: crear |
|
||||
| WG client config gen | `wg_client_config_go_infra` | FALTA: crear |
|
||||
| WG client install (device) | `wg_client_install_bash_infra` | FALTA: crear |
|
||||
| WG status (parse `wg show`) | `wg_status_bash_infra` | FALTA: crear |
|
||||
| Docker list (host) | `docker_container_list_go_infra` | FALTA: crear |
|
||||
| Docker exec capability | `docker_container_exec_go_infra` | FALTA: crear |
|
||||
| Docker logs tail | `docker_container_logs_go_infra` | FALTA: crear |
|
||||
| Docker container enroll | `docker_container_enroll_go_infra` | FALTA: crear |
|
||||
| Capability sign | `capability_manifest_sign_go_infra` | FALTA: crear |
|
||||
| Capability verify | `capability_manifest_verify_go_infra` | FALTA: crear |
|
||||
| Enrollment token gen | `enrollment_token_create_go_infra` | FALTA: crear |
|
||||
| Enrollment token verify | `enrollment_token_verify_go_infra` | FALTA: crear |
|
||||
| Matrix room per device | `matrix_room_for_device_py_browser` (extender) | OK base, EXTENDER |
|
||||
| Provision hub pipeline | `provision_wg_hub_bash_pipelines` | FALTA: crear |
|
||||
| Enroll device pipeline | `enroll_device_bash_pipelines` | FALTA: crear |
|
||||
| Sink audit log | `device_audit_append_go_infra` | FALTA: crear |
|
||||
| Notify approval | `matrix_send_message_py_browser` (existente) | OK |
|
||||
|
||||
## Apps tocadas
|
||||
|
||||
- `agents_dashboard` (cockpit ImGui) — panel "Mesh" + "Devices" + "Containers" + approval queue.
|
||||
- `agents_and_robots` (hub Matrix VPS) — listener Matrix por device/container.
|
||||
- `wg_hub` (nuevo service Go en VPS) — enrollment endpoint, peer CRUD, SSE stream.
|
||||
- `device_agent` (nuevo binario per-host) — capability dispatcher con sandbox.
|
||||
- `container_agent_sidecar` (opcional, nuevo) — sidecar para containers que necesitan WG-peer propio.
|
||||
|
||||
## Projects relacionados
|
||||
|
||||
- `element_agents` (parent project — agents Matrix).
|
||||
|
||||
## Vaults / storage
|
||||
|
||||
- `apps/wg_hub/operations.db` — tabla `wg_peers`, `wg_enrollment_tokens`, `device_audit`.
|
||||
- `apps/agents_dashboard/local_files/agents_dashboard.db` — cache devices + capabilities.
|
||||
- `pass operator/ed25519` — clave maestra del operador (firma manifests).
|
||||
- `pass wg/preshared/<device_id>` — PSK por peer.
|
||||
|
||||
## Capability groups consultados
|
||||
|
||||
- `wireguard` (nuevo, ver `docs/capabilities/wireguard.md`).
|
||||
- `device-agent` (nuevo, capability dispatcher + sandbox + audit).
|
||||
- `docker-agent` (nuevo, capabilities sobre containers locales).
|
||||
|
||||
## Flow
|
||||
|
||||
### Fase A — registry primero (delegar a fn-constructor en paralelo)
|
||||
|
||||
1. `function: wg_install_bash_infra` (delegada).
|
||||
2. `function: wg_keygen_go_infra` (delegada).
|
||||
3. `function: wg_hub_setup_bash_infra` (delegada).
|
||||
4. `function: wg_peer_add_go_infra` (delegada).
|
||||
5. `function: wg_peer_remove_go_infra` (delegada).
|
||||
6. `function: wg_peer_revoke_go_infra` (delegada).
|
||||
7. `function: wg_client_config_go_infra` (delegada).
|
||||
8. `function: wg_client_install_bash_infra` (delegada).
|
||||
9. `function: wg_status_bash_infra` (delegada).
|
||||
10. `cmd: ./fn index` — registra las 9 nuevas.
|
||||
11. `cmd: fn doctor unused | grep wg_` — confirma que estan listas y no huerfanas (se usan en pasos C).
|
||||
|
||||
### Fase C — POC manual end-to-end
|
||||
|
||||
12. `function: wg_install_bash_infra` (sobre `organic-machine.com` via SSH).
|
||||
13. `function: wg_keygen_go_infra` → key par hub.
|
||||
14. `function: wg_hub_setup_bash_infra` — wg0, 10.42.0.1/24, ufw 51820/udp, persistencia.
|
||||
15. `function: wg_keygen_go_infra` → key par device `home-wsl`.
|
||||
16. `function: wg_peer_add_go_infra` (en hub) → asigna 10.42.0.10.
|
||||
17. `function: wg_client_config_go_infra` → genera client.conf.
|
||||
18. `function: wg_client_install_bash_infra` (en `home-wsl`).
|
||||
19. `cmd: ping -c3 10.42.0.1` desde `home-wsl` — verifica handshake.
|
||||
20. `cmd: curl http://10.42.0.1:8080/healthz` — agents_and_robots accesible por IP privada.
|
||||
21. Repetir 15-19 para `pc-aurgi`.
|
||||
|
||||
### Fase B — spec + capability manifest + bot Matrix
|
||||
|
||||
22. Issue 0134 spec protocol: envelope JSON `{request_id, capability, args, signature, nonce}`,
|
||||
error model, approval flow, audit chain hash.
|
||||
23. `function: capability_manifest_sign_go_infra` (operator firma).
|
||||
24. `function: capability_manifest_verify_go_infra` (device verifica antes de aceptar request).
|
||||
25. `function: enrollment_token_create_go_infra` (token QR firmado, TTL 10min).
|
||||
26. `function: enrollment_token_verify_go_infra` (hub valida en `/enroll`).
|
||||
27. Implementar `apps/device_agent/` (Go cross-compile) — Matrix client + capability dispatcher + sandbox firejail.
|
||||
28. Panel "Devices" en `agents_dashboard` — lista + capability matrix + approval queue + boton revoke.
|
||||
29. Bot Matrix por device: cuando hablas en el room `#dev-aurgi:organic-machine.com`,
|
||||
`agents_and_robots` parsea, valida capability, despacha a device_agent, devuelve resultado al room.
|
||||
|
||||
### Fase D — agentes-contenedores docker
|
||||
|
||||
30. `function: docker_container_list_go_infra` — corre en host con docker socket access.
|
||||
31. `function: docker_container_exec_go_infra` — exec en container con whitelist binarios.
|
||||
32. `function: docker_container_logs_go_infra` — tail logs SSE.
|
||||
33. Modo "light": container expuesto via host's `device_agent` capability `docker.*`.
|
||||
Element room: `#host-aurgi:organic-machine.com` con comando `!docker exec mycontainer ps`.
|
||||
34. Modo "deep": container = peer WG propio. `container_agent_sidecar` corre WG dentro del container
|
||||
(privileged) o sidecar gluetun-wg. Manifest firmado mapea `agent_X` → container_id.
|
||||
35. Sub-bot Matrix por container: `#cont-mycontainer:organic-machine.com` (opcional, modo deep).
|
||||
|
||||
## Acceptance
|
||||
|
||||
- [ ] 9 funciones `wg_*` creadas + indexadas + sin huerfanas.
|
||||
- [ ] Hub WG corriendo en `organic-machine.com`, `wg show` muestra interface wg0.
|
||||
- [ ] `home-wsl` y `pc-aurgi` con IP estable 10.42.0.10/11, `ping` OK.
|
||||
- [ ] `agents_and_robots` accesible solo desde subnet 10.42.0.0/24 (publico = DROP en :8080).
|
||||
- [ ] `agents_dashboard` panel "Mesh" muestra peers vivos via SSE.
|
||||
- [ ] Chat en `#dev-aurgi` ejecuta capability (ej. `!ls /home/lucas`) y devuelve resultado.
|
||||
- [ ] Capability fuera del manifest rechazada con error en room.
|
||||
- [ ] Capability `requires_approval=true` espera confirmacion en `#operator-approvals` antes de ejecutar.
|
||||
- [ ] `docker.container.list` invocado desde Element devuelve containers del host.
|
||||
- [ ] `docker.container.exec` con binario fuera de whitelist rechazado.
|
||||
- [ ] Revoke device desde `agents_dashboard` → device pierde acceso en <5s.
|
||||
- [ ] Audit log append-only inviolable (hash chain) sobrevive reinicio.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Triada obligatoria (ver `.claude/rules/dod_quality.md`). Sin las 3 capas + 0 anti-criterios el flow NO se mueve a `completed/`.
|
||||
|
||||
### Mecanica (pre-requisito)
|
||||
|
||||
- [ ] **Build device_agent**: `cd apps/device_agent && CGO_ENABLED=0 GOOS=linux go build -o device_agent .` exit 0; cross-compile `GOOS=windows` + `GOOS=android GOARCH=arm64` tambien verdes.
|
||||
- [ ] **Build agents_and_robots + agents_dashboard**: `./fn run redeploy_cpp_app_windows agents_dashboard apps/agents_dashboard --build` + Go build de `agents_and_robots` exit 0.
|
||||
- [ ] **Tests unitarios funciones nuevas verdes**: `CGO_ENABLED=1 go test -tags fts5 -count=1 ./functions/infra/...` cubriendo wg_*, capability_*, enrollment_*, device_audit_*. Lista de IDs en `## Notas`.
|
||||
- [ ] **`./fn index`** sin warnings nuevos tras anadir las ~20 funciones.
|
||||
- [ ] **`./fn doctor unused --json | jq '.[]|select(.id|startswith("wg_"))'`** vacio (las wg_* tienen consumidores reales).
|
||||
- [ ] **`./fn doctor uses-functions`** verde para `apps/device_agent/app.md`, `apps/wg_hub/app.md`, `apps/agents_dashboard/app.md`.
|
||||
- [ ] **`./fn doctor services-spec`** verde para `wg_hub.service` y `device_agent.service` con bloque service: completo.
|
||||
|
||||
### Cobertura de comportamiento
|
||||
|
||||
Minimo: golden + 8 edge/error documentados aqui con assert ejecutable. Cada uno deja entry en `e2e_runs` de la app afectada (`apps/device_agent/operations.db`, `apps/wg_hub/operations.db`).
|
||||
|
||||
| Escenario | Tipo | Comando / evidencia | Resultado esperado |
|
||||
|---|---|---|---|
|
||||
| Golden: comando whitelist OK | e2e | Element `!exec ls /home/lucas` en `#dev-home-wsl` | output `ls` en <3s, entry en `device_audit` con hash valido |
|
||||
| Edge: comando NO whitelist rechazado | e2e | Element `!exec rm -rf /` | reply `capability rejected: shell.exec.rm not in manifest`; entry `device_audit` status=`rejected_capability` |
|
||||
| Edge: capability fuera de manifest | e2e | Element `!camera.snapshot` en device sin esa capability | reply `capability not in manifest`; alerta a `#operator-approvals` |
|
||||
| Edge: replay nonce viejo | e2e | reenviar mismo envelope con nonce ya visto (cmd test: `device_agent --replay-test <envelope.json>`) | rechazo + log `nonce_replay`; entry `device_audit` status=`rejected_nonce` |
|
||||
| Edge: ed25519 manifest invalido | e2e | servir manifest firmado por clave que no es operator; `device_agent` lo recibe en enrollment | `device_agent` rechaza + no instala wg_peer; hub log muestra `manifest_invalid_signature` |
|
||||
| Edge: token enrollment expirado | e2e | `enrollment_token_create` con TTL=1s, esperar 5s, `POST /enroll` | hub responde 401 `token_expired`; cmd `curl ...` exit != 0 |
|
||||
| Approval flow honrado | e2e | Element `!fs.write /tmp/x hello` (requires_approval=true); operador hace 👍 en `#operator-approvals` | exec ocurre SOLO tras approval; sin approval no escribe; entry `device_audit` con `approval_msg_id` |
|
||||
| Approval flow no se salta | e2e | Forzar via API directa salto del approval queue (test negativo: cmd `curl --data ...` directo al device) | device rechaza + log; sin approval_msg_id en envelope = rechazo |
|
||||
| Mesh-down handled | e2e | `wg-quick down wg0` en hub mientras device manda comando | device entra en `degraded`, comando encolado o respuesta `mesh_unreachable`; al volver hub: handshake reanuda, cola se vacia |
|
||||
| Dos devices simultaneos sin interferencia | e2e | `home-wsl` y `pc-aurgi` ejecutan capabilities en paralelo (script python con 2 threads) | cada audit chain es independiente, sin cross-contamination; `device_audit` muestra 2 chains separadas, hash chain valido en cada una |
|
||||
| Audit chain valida tras restart | e2e | matar `device_agent` mid-flight (`kill -9`) + relanzar; `cmd: device_audit_verify_chain --device home-wsl` | chain integra, hash anterior coincide, sin huecos |
|
||||
| Revoke device <5s | e2e | desde `agents_dashboard` panel "Mesh" boton "Revoke home-wsl"; medir tiempo hasta `wg show` no liste peer | peer ausente en <5s; siguientes comandos a `#dev-home-wsl` -> `peer_revoked` |
|
||||
|
||||
**Regla**: cada fila genera `e2e_check` en `app.md` correspondiente (issue 0068). `fn-analizador` los corre periodicamente.
|
||||
|
||||
### Vida util validada
|
||||
|
||||
| Metrica | Umbral | Donde se observa | Ventana |
|
||||
|---|---|---|---|
|
||||
| Peers vivos en mesh | `>=2` constantes (home-wsl + pc-aurgi) | `agents_dashboard` panel "Mesh" (last_handshake < 3min) | 7 dias |
|
||||
| Crashes `device_agent` | `0` | `journalctl --user -u device_agent.service` en cada device | 7 dias |
|
||||
| Crashes `wg_hub` | `0` | `ssh vps journalctl -u wg_hub.service` | 7 dias |
|
||||
| Huecos en audit chain | `0` | `cmd: device_audit_verify_chain --all` | continuo |
|
||||
| Rollback de wg config | `0 ocurrencias` | hub: `git -C /etc/wireguard status` debe ser clean; sin restore manual | 7 dias |
|
||||
| Handshake fail rate | `<5%` | `wg show all dump` parseado por `agents_dashboard` | 7 dias |
|
||||
| Approval queue stuck | `0 pendientes >24h` | `agents_dashboard` panel "Approvals" | continuo |
|
||||
| Comandos exec latencia p95 | `<3s` | `call_monitor.function_stats` para `capability.shell.exec` | 7 dias |
|
||||
| Replay attacks bloqueados | `>=1 detectado y bloqueado` (pen-test real) | `device_audit` status=`rejected_nonce` count | 30 dias |
|
||||
|
||||
### User-facing (reforzado)
|
||||
|
||||
- [ ] **User-facing surface**: humano abre Element en movil/web (`element.organic-machine.com`), entra a `#dev-<nombre>` y escribe comandos. Output en el mismo room. NO en una BD, NO en un log.
|
||||
- [ ] **User-facing usage real**: el operador (humano) usa Element con `home-wsl` Y `pc-aurgi` (>=2 maquinas reales), **>=1 sesion/dia durante >=7 dias consecutivos**, **>=20 comandos totales** repartidos entre devices.
|
||||
- [ ] **User-facing variado**: cubre capabilities de **>=4 tipos**: read (`!fs.read`, `!ls`), write (`!fs.write`), exec (`!exec`), approval-required (`!fs.write` en path sensible), docker (`!docker exec`).
|
||||
- [ ] **User-facing onboarding**: parrafo en `## Notas` con pasos numerados: abrir Element -> entrar a room -> `!help` -> ejemplo de comando. Sin leer el flow entero.
|
||||
- [ ] **User-facing latencia**: tras enviar mensaje en Element, output visible en <3s (read/exec) o <5s (con approval) — medido y registrado en `## Notas`.
|
||||
|
||||
### Anti-criterios (invalidan DoD aunque checkboxes verdes)
|
||||
|
||||
- [ ] **Solo-en-home-wsl**: el flow funciona en mi WSL pero falla en `pc-aurgi` u otro device fisico.
|
||||
- [ ] **device_agent muere cada noche**: cualquier crash recurrente del proceso device_agent en los 7 dias de validacion.
|
||||
- [ ] **Approval flow se salta**: alguna entrada en `device_audit` con capability `requires_approval=true` ejecutada sin `approval_msg_id` valido.
|
||||
- [ ] **Audit chain rota**: `device_audit_verify_chain` reporta huecos o hash mismatch en algun device.
|
||||
- [ ] **wg config drift**: cambios manuales en `/etc/wireguard/wg0.conf` del hub sin pasar por `wg_peer_add/remove/revoke`. Git status muestra cambios sin trackear.
|
||||
- [ ] **Dashboard fantasma**: `agents_dashboard` declarado pero el operador no lo abre durante la ventana de 7 dias. Telemetria muerta.
|
||||
- [ ] **Pen-test no ejercitado**: replay attack / capability fuera de manifest / token expirado declarados pero sin entry real en `device_audit` con status `rejected_*` en los 7 dias.
|
||||
- [ ] **Silent-fail**: peer cae >24h y nadie se entera (sin alerta a `#operator-approvals` ni badge rojo en dashboard).
|
||||
- [ ] **Secrets en repo**: cualquier hit de `git grep -E 'PrivateKey|PSK|operator/ed25519' -- ':!*.md'` en cualquier rama.
|
||||
|
||||
### Custom (security-specific, deben tener evidencia en `device_audit`)
|
||||
|
||||
- [ ] _(custom)_ Pen-test capability fuera de manifest: entry `device_audit` status=`rejected_capability` ejercitado intencionalmente >=1 vez.
|
||||
- [ ] _(custom)_ Pen-test replay: entry `device_audit` status=`rejected_nonce` ejercitado >=1 vez con cmd reproducible.
|
||||
- [ ] _(custom)_ Stale device: forzar `home-wsl` offline >24h, verificar badge `stale` en `agents_dashboard` + mensaje en `#operator-approvals`.
|
||||
- [ ] _(custom)_ Operator key rotation: ejecutar rollover de la clave ed25519 maestra + revoke-all + re-enroll, sin perder audit chain historica. Documentado en `## Notas`.
|
||||
|
||||
## Telemetria esperada
|
||||
|
||||
- `call_monitor.calls`: cada `wg_*`, `capability.*`, `docker.*` con duration_ms, success.
|
||||
- `apps/wg_hub/operations.db`: tabla `wg_peers` + `device_audit` (hash-chained append-only).
|
||||
- `apps/agents_and_robots/operations.db`: tabla `matrix_capability_dispatches`.
|
||||
- `apps/agents_dashboard/local_files/agents_dashboard.db`: cache devices + approval queue.
|
||||
- Dashboards visibles: `agents_dashboard` panel "Mesh" (peers vivos + last handshake + bytes rx/tx).
|
||||
- Matrix room `#operator-approvals` recibe cada approval_request.
|
||||
- Element en movil aprueba/rechaza con reacciones (👍/👎) o comando `!approve <id>`.
|
||||
|
||||
## Riesgos / gotchas
|
||||
|
||||
- **VPS UDP/51820**: firewall del proveedor del VPS puede bloquearlo. Verificar con `nc -u -v vps 51820`.
|
||||
- **NAT carrier-grade (4G/5G)**: device tras NAT estricto → `PersistentKeepalive = 25` obligatorio.
|
||||
- **Sleep laptop / android doze**: handshake muere. Auto-reconnect via `systemd-networkd-wait-online` + script.
|
||||
- **Privilegio sudo**: `wg-quick` requiere root. Devices necesitan sudo-NOPASSWD para `wg-quick@wg0`.
|
||||
- **Clock skew**: tokens enrollment + nonces dependen de NTP. Forzar `chrony` en VPS y devices.
|
||||
- **Container privileged**: modo "deep" docker requiere `--cap-add NET_ADMIN`. Riesgo si container compromised.
|
||||
Mitigacion: solo modo "deep" para containers de tu propio control (ej. `agents_and_robots` self-hosted), no third-party.
|
||||
- **Operator key compromise**: si tu ed25519 leaks → cualquiera firma manifests. Plan B: rotacion + revoke-all + re-enroll.
|
||||
- **Matrix homeserver compromise**: chat E2EE protege contenido, pero metadata (quien habla con quien) leak.
|
||||
Aceptable porque homeserver es tuyo en `organic-machine.com`.
|
||||
|
||||
## Notas
|
||||
|
||||
(rellenar tras ejecutar fases A/C/B/D)
|
||||
|
||||
### Para hablar con un device desde Element (onboarding)
|
||||
|
||||
1. Abre Element en movil o web (`element.organic-machine.com`).
|
||||
2. Entra al room `#dev-<nombre>` (un room por device).
|
||||
3. Escribe `!help` → bot del room (`agents_and_robots`) responde con capability matrix del device.
|
||||
4. Escribe comando, ej. `!exec ls /home/lucas` o `!fs.read /var/log/syslog`.
|
||||
5. Si capability requiere approval, te llega notification a `#operator-approvals` → reaccionas 👍 → ejecuta.
|
||||
6. Output aparece en el mismo room del device.
|
||||
|
||||
### Para hablar con un container docker
|
||||
|
||||
1. Si el host del container ya esta en la mesh: room `#dev-<host>` con `!docker exec <container> <cmd>`.
|
||||
2. Modo deep: room dedicado `#cont-<container>` (solo containers enrolled).
|
||||
@@ -12,6 +12,7 @@ Tabla de casos de uso multi-app. Mantenida por `/flow create` y `/flow done`.
|
||||
| [0006](0006-metabase-versioning.md) | metabase-versioning | gitops | auto_metabase, dag_engine | pending | medium | 0% | 2026-05-16 |
|
||||
| [0007](0007-matrix-telemetry-bot.md) | matrix-telemetry-bot | event-driven | data_factory, dag_engine, call_monitor, agents_and_robots | pending | low | 0% | 2026-05-16 |
|
||||
| [0008](0008-kanban-cpp-and-agent-workflows.md) | kanban-cpp-and-agent-workflows | realtime-loop | kanban_cpp, kanban, skill_tree, agent_runner_api | pending | medium | 0% | 2026-05-18 |
|
||||
| [0009](0009-agentes-dispositivos-mesh.md) | agentes-dispositivos-mesh | event-driven | agents_dashboard, agents_and_robots, wg_hub, device_agent | pending | high | 0% | 2026-05-23 |
|
||||
|
||||
## Leyenda
|
||||
|
||||
|
||||
+92
-25
@@ -12,49 +12,116 @@ Un flow describe una secuencia de pasos que atraviesa varias apps (`navegator_da
|
||||
- **Definition of Done OBLIGATORIA** — ver seccion abajo. Sin DoD el flow NO puede crearse.
|
||||
- Cerrados se mueven a `completed/`.
|
||||
|
||||
## Definition of Done (OBLIGATORIA)
|
||||
## Definition of Done (OBLIGATORIA — triada)
|
||||
|
||||
Cada flow al crearse DEBE declarar un bloque `## Definition of Done` distinto de `## Acceptance`. Sin el, `/flow create` rechaza el scaffold y `/flow done` rechaza el cierre.
|
||||
|
||||
**Diferencia:**
|
||||
**Regla absoluta**: DoD no es checkbox que se marca a mano. Cada item lleva **evidencia ejecutable** (comando, e2e_check, dashboard URL con datos frescos, log query, screenshot link). Si no puedes probarlo, no es DoD: es deseo. Ver `.claude/rules/dod_quality.md` para la regla completa.
|
||||
|
||||
**Diferencia con `## Acceptance`:**
|
||||
|
||||
| `## Acceptance` | `## Definition of Done` |
|
||||
|---|---|
|
||||
| Checks task-level del flow (ejecucion concreta) | Contrato global de calidad para considerar el flow CERRADO |
|
||||
| Pueden quedar `[ ]` mientras iteras | TODOS deben estar `[x]` antes de mover a `completed/` |
|
||||
| Verifica que el flow CORRE | Verifica que el flow es REPETIBLE, OBSERVABLE y MANTENIBLE |
|
||||
| Checks task-level del flow (el flow corre una vez) | Contrato global de calidad: el flow sobrevive uso real |
|
||||
| Pueden quedar `[ ]` mientras iteras | TODAS las capas verdes con evidencia antes de mover a `completed/` |
|
||||
| Verifica que el flow CORRE | Verifica que el flow es REPETIBLE, OBSERVABLE, MANTENIBLE y USADO |
|
||||
|
||||
**Plantilla minima de DoD** (anadir/ajustar segun flow):
|
||||
### Las 3 capas obligatorias
|
||||
|
||||
**1. Mecanica** (pre-requisito, NO es DoD por si misma):
|
||||
Build verde, tests verdes, `fn index` limpio, `fn doctor` verde, `uses_functions` sin drift. Hacer compilar la cosa NO es haberla terminado.
|
||||
|
||||
**2. Cobertura de comportamiento**:
|
||||
Tabla `escenario | tipo | comando | resultado esperado`. Minimo 1 golden + 2 edge + 1 error path con assert real, no smoke "no peto". Cuando aplique, las pruebas dejan entry en `e2e_runs` de la app afectada.
|
||||
|
||||
**3. Vida util validada**:
|
||||
Tabla `metrica | umbral | dashboard | ventana`. El flow sobrevive **>=7 dias de uso real** sin romperse silenciosamente. Crashes = 0, huecos en audit chains = 0, error_rate < umbral declarado, dashboard observable abierto periodicamente. **El humano usa la cosa en su PC, en su contexto real, >=N veces variadas, no en sandbox aislado**.
|
||||
|
||||
### Plantilla obligatoria
|
||||
|
||||
Ver `template.md` para el esqueleto completo. Bloques:
|
||||
|
||||
```markdown
|
||||
## Definition of Done
|
||||
|
||||
- [ ] **Repetibilidad**: el flow corre N veces consecutivas (N declarado en el flow, default 3) sin intervencion manual.
|
||||
- [ ] **Observabilidad**: queda trazado en `call_monitor.calls` + `data_factory.runs` + dashboard correspondiente.
|
||||
- [ ] **Error-path**: al menos 1 modo de fallo probado y manejado (no crash silencioso).
|
||||
- [ ] **Idempotencia**: re-ejecutar no duplica datos ni rompe estado (clave en sinks).
|
||||
- [ ] **Secrets**: cero credenciales en disco fuera de `pass`/vaults; cero datos sensibles fuera de `risk` declarado.
|
||||
- [ ] **Docs**: `## Notas` rellenado con hallazgos reales + comandos para reproducir.
|
||||
- [ ] **Registry-first**: todas las piezas reutilizables existen como funciones del registry (no inline en apps).
|
||||
- [ ] **INDEX + status**: `status: done` en frontmatter + fila actualizada en `INDEX.md` + archivo movido a `completed/`.
|
||||
### Mecanica
|
||||
- [ ] Build verde (`cmd: ...`)
|
||||
- [ ] Tests verdes (`cmd: ...`)
|
||||
- [ ] fn index limpio
|
||||
- [ ] fn doctor verde
|
||||
- [ ] uses_functions auditado
|
||||
|
||||
### Cobertura de comportamiento
|
||||
| Escenario | Tipo | Comando | Resultado esperado |
|
||||
|---|---|---|---|
|
||||
| Golden: ... | unit/e2e | `cmd` | output concreto |
|
||||
| Edge 1: ... | unit/e2e | `cmd` | comportamiento concreto |
|
||||
| Error 1: ... | e2e | `cmd que rompe` | fallo manejado, no crash |
|
||||
| Error 2: ... | e2e | `cmd` | degradacion graceful + log |
|
||||
|
||||
### Vida util validada
|
||||
| Metrica | Umbral | Donde se observa | Ventana |
|
||||
|---|---|---|---|
|
||||
| <metrica> | `>=N` | `<dashboard URL>` | 7 dias |
|
||||
| crashes | `0` | `journalctl ...` | 7 dias |
|
||||
|
||||
### User-facing (reforzado)
|
||||
- [ ] User-facing surface (lugar concreto, NO BD ni log).
|
||||
- [ ] User-facing usage real: >=N veces en >=7 dias, en PC real, con inputs reales.
|
||||
- [ ] User-facing variado: >=3 capabilities/casos distintos.
|
||||
- [ ] User-facing onboarding (parrafo en `## Notas`).
|
||||
- [ ] User-facing latencia <X medida.
|
||||
|
||||
### Anti-criterios (invalidan DoD aunque checkboxes verdes)
|
||||
- [ ] solo-en-mi-PC
|
||||
- [ ] solo-en-sandbox-vacio
|
||||
- [ ] camino feliz unico (error paths declarados pero nunca ejercitados)
|
||||
- [ ] dashboard fantasma (no abierto en >30 dias)
|
||||
- [ ] self-test sin asserts
|
||||
- [ ] silent-fail
|
||||
- [ ] approval saltado
|
||||
```
|
||||
|
||||
Cada flow puede anadir DoD especificos al dominio (ej. `bbva-movimientos`: "datos NUNCA cruzan a registry.organic-machine"). El bloque DoD se **versiona con el flow** — un cambio de DoD requiere bump de `updated:` en frontmatter.
|
||||
### Reglas duras para marcar `status: done`
|
||||
|
||||
### User-facing surface (sub-bloque OBLIGATORIO dentro de DoD)
|
||||
`/flow done` rechaza el cierre si:
|
||||
|
||||
"DoD verde" sin valor visible al humano = plumbing limpio sin razon de existir. Cada DoD DEBE incluir, al menos, estos cuatro checks tipo `User-facing`:
|
||||
1. Falta alguna de las 3 capas (mecanica + cobertura + vida).
|
||||
2. En Cobertura: <1 golden, <2 edge, <1 error path con evidencia.
|
||||
3. En Vida util: tabla vacia o sin dashboard observable real.
|
||||
4. User-facing usage real <7 dias o <N usos declarados.
|
||||
5. Cualquier anti-criterio marcado como cierto.
|
||||
6. `## Notas` sin parrafo onboarding.
|
||||
7. Algun item sin comando/URL/log query — solo texto.
|
||||
|
||||
```markdown
|
||||
- [ ] **User-facing**: <accion concreta del humano + lugar exacto donde ve/usa el output>.
|
||||
- [ ] **User-facing repeat**: el humano vuelve manana al mismo lugar y ve datos frescos sin conocer el flow.
|
||||
- [ ] **User-facing onboarding**: parrafo en `## Notas` que explica "para ver/usar esto: hacer X" — sin leer el flow.
|
||||
- [ ] **User-facing latencia**: el humano percibe el cambio en <X segundos|minutos> tras el evento (X declarado por flow).
|
||||
```
|
||||
Cada flow puede anadir DoD especificos al dominio. El bloque DoD se **versiona con el flow** — un cambio de DoD requiere bump de `updated:` en frontmatter.
|
||||
|
||||
Regla: si la respuesta a "donde lo ves" es "en una BD" o "en un log" -> NO vale. Tiene que ser una superficie usada por el humano (UI de una app, sala Matrix, dashboard, Metabase card, repo Gitea, archivo en vault abierto a mano). Si el output solo lo consume otra app/flow, esa app/flow es quien debe declarar su propia user-facing surface.
|
||||
### User-facing surface (regla complementaria)
|
||||
|
||||
`/flow done` rechaza el cierre si falta alguno de los 4 user-facing checks o si `## Notas` no contiene parrafo onboarding.
|
||||
Si la respuesta a "donde lo ves" es "en una BD" o "en un log" -> NO vale. Tiene que ser una superficie usada por el humano (UI de app, sala Matrix, dashboard, Metabase card, repo Gitea, archivo en vault abierto a mano). Si el output solo lo consume otra app/flow, esa app/flow declara su propia user-facing surface.
|
||||
|
||||
### Antipatrones documentados
|
||||
|
||||
| Antipatron | Por que es malo |
|
||||
|---|---|
|
||||
| Marcar `done` porque pasa una vez | Tarea "hecha" se rompe al primer uso real |
|
||||
| Checkbox sin evidencia ejecutable | DoD se convierte en placebo, no en gate |
|
||||
| Test que solo verifica camino feliz | El error path es donde se pierden datos en produccion |
|
||||
| Observabilidad declarada pero dashboard no abierto en 30 dias | Telemetria muerta = ceguera |
|
||||
| "Repetible 3 veces consecutivas" con BD efimera | No prueba comportamiento sobre datos reales acumulados |
|
||||
| Aprobacion saltada en algun camino | Security gate roto pero invisible |
|
||||
| Error path manejado solo "en teoria" | Cuando ocurra en produccion el manejo no existe |
|
||||
|
||||
### Validacion programatica de DoD (TBD)
|
||||
|
||||
`/flow done` ejecuta checks programaticos:
|
||||
- Parsea bloques `### Mecanica`, `### Cobertura`, `### Vida util`, `### User-facing`, `### Anti-criterios`.
|
||||
- Verifica que cada item tiene `cmd:` / URL / log query / e2e_check_id asociado.
|
||||
- Cuenta filas en Cobertura: >=1 golden + >=2 edge + >=1 error.
|
||||
- Cruza con `e2e_runs` y `call_monitor.calls` para confirmar evidencias en BDs reales.
|
||||
- Aborta cierre si falta cobertura o algun anti-criterio esta marcado.
|
||||
|
||||
Hoy parte de esto es manual (revision humana). Ver `audit_dod_schema_go_infra` (issue 0114) + `fn doctor dod`.
|
||||
|
||||
### DoD evidence schema (issue 0114, opcional)
|
||||
|
||||
|
||||
+60
-14
@@ -68,28 +68,74 @@ Pasos numerados. Cada paso puede ser:
|
||||
|
||||
## Acceptance
|
||||
|
||||
Checks task-level del flow — verifican que el flow CORRE una vez. Pueden quedar `[ ]` mientras iteras. NO sustituyen a la DoD.
|
||||
|
||||
- [ ] Criterio 1.
|
||||
- [ ] Criterio 2.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Contrato global de cierre. TODOS marcados antes de mover a `completed/`. Ver README.md seccion "Definition of Done".
|
||||
**Filosofia triada (ver `.claude/rules/dod_quality.md`):** DoD no es checkbox que se marca a mano. Cada item debe llevar **evidencia ejecutable** (comando, e2e_check, screenshot link, dashboard URL con datos frescos, log query). Si no puedes probarlo, no es DoD: es deseo. Las 3 capas son obligatorias.
|
||||
|
||||
- [ ] **Repetibilidad**: corre 3 veces consecutivas sin intervencion manual.
|
||||
- [ ] **Observabilidad**: trazado en `call_monitor.calls` + `data_factory.runs` + dashboard relevante.
|
||||
- [ ] **Error-path**: >=1 modo de fallo probado y manejado.
|
||||
- [ ] **Idempotencia**: re-ejecucion no duplica ni corrompe sinks.
|
||||
- [ ] **Secrets**: cero credenciales fuera de `pass`/vaults; risk declarado coincide con datos reales.
|
||||
- [ ] **Docs**: `## Notas` con hallazgos + comandos reproducibles.
|
||||
- [ ] **Registry-first**: piezas reutilizables viven como funciones del registry.
|
||||
- [ ] **INDEX + status**: `status: done` + `INDEX.md` actualizado + movido a `completed/`.
|
||||
### Mecanica (pre-requisito, NO sustituye al resto)
|
||||
|
||||
### User-facing (obligatorio)
|
||||
Construir verde no es estar hecho. Es la base para empezar a probar.
|
||||
|
||||
- [ ] **User-facing**: <accion concreta del humano + lugar exacto donde ve/usa el output>.
|
||||
- [ ] **User-facing repeat**: humano vuelve manana al mismo lugar, ve datos frescos sin conocer el flow.
|
||||
- [ ] **User-facing onboarding**: parrafo en `## Notas` explica "para ver/usar esto: hacer X" sin leer el flow.
|
||||
- [ ] **User-facing latencia**: humano percibe el cambio en <Xs|Xmin> tras el evento (X declarado).
|
||||
- [ ] **Build verde** (`cmd: <comando build>`).
|
||||
- [ ] **Tests unitarios verdes** (`cmd: <comando test>`, listar IDs/paths).
|
||||
- [ ] **`fn index` limpio** (sin warnings nuevos).
|
||||
- [ ] **`fn doctor` verde** en artefactos tocados (`cmd: ./fn doctor --json | jq ...`).
|
||||
- [ ] **`uses_functions` auditado** (sin drift en `app.md` vs imports reales).
|
||||
|
||||
### Cobertura de comportamiento
|
||||
|
||||
Cada escenario debe tener una prueba ejecutable con assert real (no smoke "no peto"). Anadir tantas filas como casos relevantes — golden path + edge cases + error paths.
|
||||
|
||||
| Escenario | Tipo de prueba | Comando / evidencia | Resultado esperado |
|
||||
|---|---|---|---|
|
||||
| Golden path: <descripcion> | unit / e2e / manual | `<cmd>` | <output concreto, no "ok"> |
|
||||
| Edge case 1: <input limite> | unit / e2e | `<cmd>` | <comportamiento concreto> |
|
||||
| Edge case 2: <estado raro> | unit / e2e | `<cmd>` | <comportamiento concreto> |
|
||||
| Error path 1: <fallo esperado> | e2e | `<cmd que provoca fallo>` | <fallo manejado, no crash> |
|
||||
| Error path 2: <recursos caidos> | e2e | `<cmd>` | <degradacion graceful + log> |
|
||||
|
||||
**Regla**: al menos 1 golden + 2 edge + 1 error path. Tests inscritos en `e2e_runs` de la app correspondiente cuando aplique.
|
||||
|
||||
### Vida util validada
|
||||
|
||||
El flow no esta hecho hasta que sobrevive **uso real** durante >=7 dias sin romperse silenciosamente. Cada metrica tiene umbral medible y dashboard observable.
|
||||
|
||||
| Metrica | Umbral | Donde se observa | Ventana |
|
||||
|---|---|---|---|
|
||||
| <metrica 1, ej. handshakes vivos> | `>=N` | `<dashboard URL / app panel>` | 7 dias |
|
||||
| <metrica 2, ej. error_rate> | `<X%` | `<dashboard URL>` | 7 dias |
|
||||
| <metrica 3, ej. duracion p95> | `<Xms` | `call_monitor.function_stats` | 30 dias |
|
||||
| crashes del proceso | `0` | `journalctl -u <unit>` | 7 dias |
|
||||
| huecos en audit chain | `0` | `cmd: <verify chain>` | continuo |
|
||||
|
||||
**Regla**: las metricas NO se autoreportan en el flow; las lee el operador del dashboard real. Si el dashboard no existe, el item se invalida.
|
||||
|
||||
### User-facing (reforzado)
|
||||
|
||||
"DoD verde" sin uso humano real = plumbing limpio sin razon de existir.
|
||||
|
||||
- [ ] **User-facing surface**: <accion concreta del humano + lugar exacto donde ve/usa el output (NO una BD, NO un log)>.
|
||||
- [ ] **User-facing usage real**: el humano (operador) usa la cosa en **su PC, en su contexto real**, **>=N veces en >=7 dias**, con inputs reales (no demo, no sandbox).
|
||||
- [ ] **User-facing variado**: cubre >=3 capabilities/casos distintos (no solo "abre dashboard y mira").
|
||||
- [ ] **User-facing onboarding**: parrafo en `## Notas` que explica "para ver/usar esto: hacer X" sin leer el flow.
|
||||
- [ ] **User-facing latencia**: percepcion del cambio <Xs|Xmin> tras el evento (X declarado, medido).
|
||||
|
||||
### Anti-criterios (invalidan la DoD aunque los checkboxes esten verdes)
|
||||
|
||||
Marca el flow como **NO done** si cualquiera de estas condiciones es cierta:
|
||||
|
||||
- [ ] **Solo-en-mi-PC**: el flow funciona en `home-wsl` pero falla en `pc-aurgi` u otro PC del operador.
|
||||
- [ ] **Repetible-en-sandbox-vacio**: solo pasa con BD limpia / cuenta limpia / sin datos historicos.
|
||||
- [ ] **Camino feliz unico**: los error paths fueron declarados pero NUNCA se ejercitaron (sin entry en `e2e_runs` o logs reales).
|
||||
- [ ] **Dashboard fantasma**: el dashboard declarado en "Vida util" no se ha abierto en >30 dias.
|
||||
- [ ] **Self-test que no apesta**: el `e2e_check` retorna `pass` sin verificar nada material (no asserts).
|
||||
- [ ] **Silent-fail**: el proceso muere/degrada sin alerta visible al operador.
|
||||
- [ ] **Approval saltado**: alguna capability con `requires_approval=true` fue ejecutada sin el approval flow.
|
||||
|
||||
### Custom (opcional, dominio-especifico)
|
||||
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: "0131"
|
||||
title: "Modulo C++ chat_panel — panel ImGui para chat con agentes"
|
||||
status: pendiente
|
||||
type: app
|
||||
domain:
|
||||
- cpp-stack
|
||||
- agents
|
||||
- dev-ux
|
||||
scope: cross-stack
|
||||
priority: alta
|
||||
depends:
|
||||
- "0113"
|
||||
blocks: []
|
||||
related:
|
||||
- "0130"
|
||||
created: 2026-05-22
|
||||
updated: 2026-05-22
|
||||
tags: [cpp, imgui, agents, chat, module, sse]
|
||||
flow: ""
|
||||
---
|
||||
|
||||
# 0131 — Modulo C++ chat_panel
|
||||
|
||||
**Status:** pendiente
|
||||
|
||||
## Por que
|
||||
|
||||
Tras lanzar un agente desde kanban_cpp (issue 0130), no hay forma de interactuar con el desde la propia app. Hoy el flujo es: lanzar agente, abrir terminal aparte, `tail -f /tmp/wt-.../agent.log`. Queremos un panel C++ reutilizable que cualquier app embebra para chatear con un agente (Claude headless o futuros) y ver su output en streaming.
|
||||
|
||||
## Que entrega
|
||||
|
||||
Modulo `cpp/functions/viz/chat_panel/` (paquete del registry, kind: function, lang: cpp, domain: viz). API:
|
||||
|
||||
```cpp
|
||||
namespace fn_chat {
|
||||
struct ChatPanel {
|
||||
// run_id del agent_runner_api; null = panel vacio "no agent attached"
|
||||
std::string run_id;
|
||||
std::string backend_url = "http://127.0.0.1:8486"; // agent_runner_api
|
||||
bool auto_scroll = true;
|
||||
};
|
||||
void render(ChatPanel& panel);
|
||||
}
|
||||
```
|
||||
|
||||
Comportamiento:
|
||||
- Conecta SSE `/api/runs/<run_id>/sse` en background thread (reusa `sse_client_cpp_core`).
|
||||
- Parsea eventos `state`, `log`, `evidence`, `finish` y los renderiza:
|
||||
- `log` → linea cruda en buffer scrollable.
|
||||
- `state` → badge superior con status (`pending/running/done/aborted/failed`).
|
||||
- `evidence` → chip lateral con kind + payload_url.
|
||||
- `finish` → marca run terminada, deja conexion para ver historico.
|
||||
- Input box inferior (multiline) + boton "Send". POST a `/api/runs/<run_id>/message` (endpoint A IMPLEMENTAR en agent_runner_api — extension paralela; si no existe, boton se deshabilita).
|
||||
- Toolbar: `Abort run`, `Clear buffer`, `Show evidence panel`.
|
||||
|
||||
## Estructura
|
||||
|
||||
```
|
||||
cpp/functions/viz/chat_panel/
|
||||
chat_panel.h
|
||||
chat_panel.cpp
|
||||
chat_panel.md
|
||||
chat_panel_test.cpp
|
||||
```
|
||||
|
||||
## Reusa del registry
|
||||
|
||||
- `sse_client_cpp_core` — SSE async.
|
||||
- `http_request_cpp_core` — POST mensajes / abort.
|
||||
- `selectable_text_cpp_viz` — copy log lines.
|
||||
- `data_table_cpp_viz` — opcional para tabla de evidencias.
|
||||
|
||||
## DoD
|
||||
|
||||
- Modulo compila en Linux + Windows.
|
||||
- Demo en `primitives_gallery` o app dedicada `agent_chat_demo` con run_id fijo + mock SSE feeder.
|
||||
- Integracion en kanban_cpp v2: nuevo panel "Chat" que se abre al hacer click en card con agent_active, run_id se pasa automatico.
|
||||
- `e2e_checks`: smoke con mock SSE; assertion: tras emitir 3 eventos de log, panel los muestra en orden.
|
||||
|
||||
## Anti-scope (v1)
|
||||
|
||||
- No persiste history local (refresh = perdemos buffer; agent.log es la fuente).
|
||||
- No syntax highlight markdown / codigo.
|
||||
- Sin multi-run (un panel = un run).
|
||||
- Sin file diff inline (kind:evidence con kind:diff queda como link a `git show`).
|
||||
|
||||
## Notas
|
||||
|
||||
Si el endpoint POST `/api/runs/:id/message` no existe en agent_runner_api, abrir issue paralelo `0131b` para anadirlo (claude headless aceptara mensajes via stdin del subprocess — el runner debe forwardearlos). Para v1 se acepta panel read-only.
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: "0132"
|
||||
title: "Modulo C++ terminal_panel — emulador TTY ImGui embebible"
|
||||
status: pendiente
|
||||
type: app
|
||||
domain:
|
||||
- cpp-stack
|
||||
- dev-ux
|
||||
- apps-infra
|
||||
scope: cross-stack
|
||||
priority: alta
|
||||
depends: []
|
||||
blocks: []
|
||||
related:
|
||||
- "0130"
|
||||
- "0131"
|
||||
created: 2026-05-22
|
||||
updated: 2026-05-22
|
||||
tags: [cpp, imgui, terminal, pty, module]
|
||||
flow: ""
|
||||
---
|
||||
|
||||
# 0132 — Modulo C++ terminal_panel
|
||||
|
||||
**Status:** pendiente
|
||||
|
||||
## Por que
|
||||
|
||||
Apps del ecosistema (kanban_cpp, services_monitor, agents_dashboard) necesitan ver output crudo de comandos shell sin abrir un terminal externo. Tipico: tail de un log, watch de un curl, ejecutar `git status` rapido. Solucion estandar: modulo `terminal_panel` reusable que arranca un shell hijo via PTY y lo renderiza en ImGui.
|
||||
|
||||
## Que entrega
|
||||
|
||||
Modulo `cpp/functions/viz/terminal_panel/`:
|
||||
|
||||
```cpp
|
||||
namespace fn_term {
|
||||
struct TerminalPanel {
|
||||
std::string shell; // "/bin/bash" linux, "powershell.exe" windows; default auto
|
||||
std::string cwd; // working dir; default = current
|
||||
std::vector<std::string> env; // KEY=VAL extras
|
||||
int scrollback_lines = 5000;
|
||||
bool readonly = false; // true = no input forwarding (tail-only)
|
||||
};
|
||||
void open(TerminalPanel& panel); // crea proceso hijo + PTY
|
||||
void render(TerminalPanel& panel);
|
||||
void send(TerminalPanel& panel, const std::string& text); // stdin
|
||||
void close(TerminalPanel& panel);
|
||||
}
|
||||
```
|
||||
|
||||
Implementacion:
|
||||
- Linux: `forkpty` + `read/write` non-blocking en background thread.
|
||||
- Windows: ConPTY (CreatePseudoConsole) + ReadFile en thread.
|
||||
- Buffer circular `scrollback_lines` filas; render con `ImGui::TextUnformatted` por chunk para minimizar costo.
|
||||
- Soporte minimo de ANSI: cursor pos, color FG/BG basico (16 colores), clear screen. NO soporte completo (no Vim, no top, no curses pesado).
|
||||
- Toolbar: clear, copy selection, reset shell, scroll-to-bottom.
|
||||
|
||||
## Estructura
|
||||
|
||||
```
|
||||
cpp/functions/viz/terminal_panel/
|
||||
terminal_panel.h
|
||||
terminal_panel.cpp
|
||||
terminal_panel.md
|
||||
terminal_panel_linux.cpp // forkpty path
|
||||
terminal_panel_windows.cpp // ConPTY path
|
||||
terminal_panel_test.cpp
|
||||
```
|
||||
|
||||
## Reusa del registry
|
||||
|
||||
- `logger_cpp_core` (fn_log) — log errores spawn/io.
|
||||
- `ansi_parser_cpp_core` — si existe, parsear secuencias ANSI. Si no, delegar a `fn-constructor` para crearlo dentro de este issue (sub-deliverable).
|
||||
|
||||
## DoD
|
||||
|
||||
- Compila Linux + Windows.
|
||||
- Demo: `primitives_gallery` muestra terminal corriendo `bash -i` (linux) / `cmd.exe` (windows).
|
||||
- Smoke test: spawn `echo hello && exit 0` → buffer contiene "hello".
|
||||
- Integracion en kanban_cpp v2: panel "Logs" que toma `run_id` de issue activa y arranca `tail -f /tmp/wt-<slug>-<runid>/agent.log` (readonly=true).
|
||||
- FPS sin caida bajo carga de `yes "x"` (saturado): 60fps target con scrollback truncado.
|
||||
|
||||
## Anti-scope (v1)
|
||||
|
||||
- Sin soporte completo ANSI (no italics, no 256 colores, no Unicode wide).
|
||||
- Sin Vim / programas curses-pesados (cursor visible solo).
|
||||
- Sin SSH remoto (solo shell local).
|
||||
- Sin tabs multiples en un panel (un panel = un proceso).
|
||||
|
||||
## Notas
|
||||
|
||||
ConPTY requiere Windows 10 v1809+. Si target inferior, fallback a CreatePipe sin PTY (sin redimensionado).
|
||||
@@ -0,0 +1,979 @@
|
||||
---
|
||||
id: "0134"
|
||||
title: "Mesh protocol spec: capability manifests, ed25519 envelopes, enrollment, audit chain"
|
||||
status: pending
|
||||
type: spec
|
||||
domain:
|
||||
- infra
|
||||
- cybersecurity
|
||||
- protocols
|
||||
scope: cross-app
|
||||
priority: high
|
||||
depends: []
|
||||
blocks:
|
||||
- "0135"
|
||||
- "0136"
|
||||
- "0137"
|
||||
- "0138"
|
||||
- "0139"
|
||||
- "0140"
|
||||
- "0141"
|
||||
- "0142"
|
||||
- "0143"
|
||||
related:
|
||||
- "0069"
|
||||
related_flows:
|
||||
- "0009"
|
||||
created: 2026-05-24
|
||||
updated: 2026-05-24
|
||||
tags: [mesh, wireguard, matrix, e2ee, ed25519, manifest, audit-chain, security, spec, agents, devices]
|
||||
flow: "0009"
|
||||
dependencies: []
|
||||
---
|
||||
|
||||
# 0134 — Mesh protocol spec
|
||||
|
||||
**Status:** pending
|
||||
|
||||
## Por que
|
||||
|
||||
Flow 0009 (`agentes-dispositivos-mesh`) introduce un bus de control multi-device sobre WireGuard + Matrix donde cada dispositivo (PC, movil, raspberry, container Docker) ejecuta capabilities firmadas por el operador. Sin un protocolo formal compartido, cada implementacion (device_agent en Go, bot dispatcher en agents_and_robots, panel Mesh en agents_dashboard, hub en wg_hub) va a derivar.
|
||||
|
||||
Este issue cierra Fase B del flow: define el contrato exacto que **toda** implementacion debe respetar — wire format, firmas, replay protection, approval flow, audit chain, error model, threat model. Las issues 0135-0143 implementan lo que aqui se define.
|
||||
|
||||
Una vez aceptado este spec, ningun cambio en el wire format se acepta sin un nuevo issue + bump de `protocol_version`.
|
||||
|
||||
## Anti-scope
|
||||
|
||||
- NO define como provision el WG hub (ver 0136).
|
||||
- NO define UI del panel Mesh (ver 0138).
|
||||
- NO define implementacion concreta del bot Matrix (ver 0142).
|
||||
- NO entra en como se persiste `pass operator/ed25519` mas alla de su uso.
|
||||
- NO define schema de la `operations.db` de cada app — solo el subset estrictamente compartido (`audit_log`, `room_devices`, `seen_nonces`).
|
||||
|
||||
## Conventions
|
||||
|
||||
- `protocol_version` (string): **"mesh/1"** — incluido en todo envelope.
|
||||
- Todo timestamp es Unix epoch **segundos** (`int64`).
|
||||
- Todo `*_id` es `[a-z0-9_-]+` lowercase, 4-64 chars.
|
||||
- Todo nonce es 16 bytes random (`crypto/rand`), serializado como **base64url sin padding**.
|
||||
- Todo hash es SHA-256, serializado como **hex lowercase** (64 chars).
|
||||
- Toda firma ed25519 es 64 bytes, serializada como **base64url sin padding** (86 chars).
|
||||
- Toda clave publica ed25519 es 32 bytes, serializada como **base64url sin padding** (43 chars).
|
||||
- Fingerprint de clave publica = primeros 16 bytes hex de `SHA-256(pubkey_raw_32_bytes)`.
|
||||
- JSON canonical: claves ordenadas alfabeticamente, sin espacios, UTF-8, sin BOM. Para firmas siempre usar la forma canonica.
|
||||
|
||||
---
|
||||
|
||||
## 1. JSON envelope
|
||||
|
||||
Toda invocacion de capability viaja como par request/response, ya sea sobre Matrix (eventos `m.room.message` con `msgtype = m.capability.*`) o sobre HTTP dentro del mesh WG (`POST /capability`).
|
||||
|
||||
### 1.1 Request
|
||||
|
||||
```json
|
||||
{
|
||||
"protocol_version": "mesh/1",
|
||||
"request_id": "req_01J9XYZABCDEF",
|
||||
"manifest_id": "manifest_home-wsl_v3",
|
||||
"capability": "fs.read",
|
||||
"args": {
|
||||
"path": "/var/log/syslog",
|
||||
"max_bytes": 4096
|
||||
},
|
||||
"ts": 1748131200,
|
||||
"nonce": "Yk9p6Xs_3hZQk4mB7lWcvA",
|
||||
"signature": "u2vh...QkA"
|
||||
}
|
||||
```
|
||||
|
||||
- `request_id`: ULID generado por el caller (agents_and_robots o el operador). Idempotency key — si la misma request llega 2x, device_agent debe devolver el mismo response sin re-ejecutar.
|
||||
- `manifest_id`: id del capability manifest contra el cual se evalua. El device debe tener este manifest activo o rechazar `manifest_invalid`.
|
||||
- `capability`: dotted name, ej. `shell.exec`, `fs.read`, `docker.container.list`. Debe estar en `manifest.capabilities[].name`.
|
||||
- `args`: objeto JSON especifico de la capability. Schema validado por device_agent contra el manifest.
|
||||
- `ts`: Unix seconds. Edad maxima 60s (ver §5).
|
||||
- `nonce`: 16 bytes random, base64url. Unico por request (ver §5).
|
||||
- `signature`: ed25519 sobre canonical bytes (ver 1.3).
|
||||
|
||||
### 1.2 Response
|
||||
|
||||
```json
|
||||
{
|
||||
"protocol_version": "mesh/1",
|
||||
"request_id": "req_01J9XYZABCDEF",
|
||||
"ok": true,
|
||||
"result": {
|
||||
"stdout": "May 24 12:00:00 localhost systemd[1]: Started session-1.scope.\n",
|
||||
"stderr": "",
|
||||
"exit_code": 0,
|
||||
"truncated": false
|
||||
},
|
||||
"error": null,
|
||||
"duration_ms": 42,
|
||||
"audit_hash": "a3f5...09bc"
|
||||
}
|
||||
```
|
||||
|
||||
- `ok`: boolean. Si false, `result` ausente y `error` poblado.
|
||||
- `error`: objeto `{code, message, details?}` cuando `ok=false`. `code` debe estar en §10.
|
||||
- `duration_ms`: tiempo de ejecucion en device_agent (no incluye latencia Matrix).
|
||||
- `audit_hash`: `this_hash` del registro en `audit_log` (ver §7). Permite al caller verificar la cadena.
|
||||
|
||||
Response NO va firmado por defecto — viaja sobre canal autenticado (Matrix E2EE o WG mesh). Si en el futuro se requiere firma de response (audit externo), se anade campo opcional `response_signature` con el mismo esquema canonical.
|
||||
|
||||
### 1.3 Canonical bytes para firma del request
|
||||
|
||||
```
|
||||
canonical = "mesh/1\n" +
|
||||
request_id + "\n" +
|
||||
manifest_id + "\n" +
|
||||
capability + "\n" +
|
||||
sha256_hex(json_canonical(args)) + "\n" +
|
||||
int_to_string(ts) + "\n" +
|
||||
nonce
|
||||
```
|
||||
|
||||
Bytes UTF-8, separador `\n` (0x0A). No trailing newline. Hash del args para no exponer args grandes a la firma (la firma se valida contra el hash, y `args` se reentrega tal cual; cualquier modificacion rompe la firma).
|
||||
|
||||
`json_canonical(args)`:
|
||||
1. Si `args` es null o ausente, `json_canonical = "null"`.
|
||||
2. Si `args` es objeto, recursivo: ordenar claves alfabeticamente, valores serializados sin espacios, strings con escape JSON estandar.
|
||||
3. Si `args` es array, recursivo sobre cada elemento, sin reordenar.
|
||||
|
||||
### 1.4 Transport binding
|
||||
|
||||
| Transport | Request encoding | Response encoding |
|
||||
|---|---|---|
|
||||
| Matrix room event | `content.body` = JSON string, `msgtype` = `m.capability.request` | `m.capability.response` event en el mismo room |
|
||||
| HTTP intra-mesh (`https://10.42.0.10:7777/capability`) | `POST` body JSON | response body JSON |
|
||||
| SSE (streaming logs, `docker.logs --follow`) | request via POST | response inicial JSON `{ok, result: {stream_id}}` + SSE `event: chunk` |
|
||||
|
||||
Matrix es default. HTTP solo lo activa el operador con `mesh_http=true` en el manifest para casos de baja latencia (`docker.logs` tail interactivo, transferencias >1MB que Matrix limita).
|
||||
|
||||
---
|
||||
|
||||
## 2. Capability manifest
|
||||
|
||||
Documento firmado por el operador que autoriza a un device a ejecutar un set acotado de capabilities. Sin manifest valido, device_agent rechaza todo.
|
||||
|
||||
### 2.1 Schema YAML (legible) — fuente de verdad
|
||||
|
||||
```yaml
|
||||
# manifest_home-wsl_v3.yaml
|
||||
protocol_version: mesh/1
|
||||
manifest_id: manifest_home-wsl_v3
|
||||
device_id: home-wsl
|
||||
operator: egutierrez@aurgi.com
|
||||
operator_pubkey_fingerprint: "a1b2c3d4e5f60718"
|
||||
issued_at: 1748131200
|
||||
expires_at: 1779667200 # 1 year later
|
||||
capabilities:
|
||||
- name: shell.exec
|
||||
requires_approval: false
|
||||
constraints:
|
||||
binaries_whitelist: [ls, cat, head, tail, grep, ps, df, du, uname, uptime]
|
||||
max_duration_s: 10
|
||||
max_output_bytes: 65536
|
||||
cwd_allowed: ["/home/lucas", "/tmp"]
|
||||
- name: fs.read
|
||||
requires_approval: false
|
||||
constraints:
|
||||
paths_allowed: ["/home/lucas/**", "/var/log/syslog", "/etc/os-release"]
|
||||
paths_denied: ["/home/lucas/.ssh/**", "/home/lucas/.password-store/**"]
|
||||
max_bytes: 1048576
|
||||
- name: fs.write
|
||||
requires_approval: true
|
||||
constraints:
|
||||
paths_allowed: ["/home/lucas/inbox/**"]
|
||||
max_bytes: 1048576
|
||||
- name: docker.container.list
|
||||
requires_approval: false
|
||||
- name: docker.container.exec
|
||||
requires_approval: true
|
||||
constraints:
|
||||
containers_allowed: ["agents_and_robots", "registry_api"]
|
||||
binaries_whitelist: [ls, cat, ps]
|
||||
max_duration_s: 30
|
||||
```
|
||||
|
||||
### 2.2 JSON canonical (lo que se firma)
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": [
|
||||
{"constraints": {"binaries_whitelist": ["ls","cat","head","tail","grep","ps","df","du","uname","uptime"], "cwd_allowed":["/home/lucas","/tmp"], "max_duration_s": 10, "max_output_bytes": 65536}, "name": "shell.exec", "requires_approval": false},
|
||||
{"constraints": {"max_bytes": 1048576, "paths_allowed": ["/home/lucas/**","/var/log/syslog","/etc/os-release"], "paths_denied": ["/home/lucas/.ssh/**","/home/lucas/.password-store/**"]}, "name": "fs.read", "requires_approval": false},
|
||||
{"constraints": {"max_bytes": 1048576, "paths_allowed":["/home/lucas/inbox/**"]}, "name": "fs.write", "requires_approval": true},
|
||||
{"name": "docker.container.list", "requires_approval": false},
|
||||
{"constraints": {"binaries_whitelist": ["ls","cat","ps"], "containers_allowed": ["agents_and_robots","registry_api"], "max_duration_s": 30}, "name": "docker.container.exec", "requires_approval": true}
|
||||
],
|
||||
"device_id": "home-wsl",
|
||||
"expires_at": 1779667200,
|
||||
"issued_at": 1748131200,
|
||||
"manifest_id": "manifest_home-wsl_v3",
|
||||
"operator": "egutierrez@aurgi.com",
|
||||
"operator_pubkey_fingerprint": "a1b2c3d4e5f60718",
|
||||
"protocol_version": "mesh/1"
|
||||
}
|
||||
```
|
||||
|
||||
Producido por `capability_manifest_canonicalize_go_infra` (function 0135 entrega).
|
||||
|
||||
### 2.3 Canonical bytes para firma del manifest
|
||||
|
||||
```
|
||||
manifest_canonical = "mesh/1/manifest\n" + json_canonical(manifest_without_signature)
|
||||
```
|
||||
|
||||
Donde `manifest_without_signature` es el JSON canonical de §2.2. El prefijo `mesh/1/manifest\n` es domain separator — evita que una firma de manifest pueda interpretarse como firma de envelope.
|
||||
|
||||
### 2.4 Manifest signed envelope (lo que se entrega al device)
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest": { /* §2.2 */ },
|
||||
"signature": "k7Yp...QwE"
|
||||
}
|
||||
```
|
||||
|
||||
Persistido en device como `~/.config/device_agent/manifests/manifest_home-wsl_v3.json`.
|
||||
|
||||
### 2.5 Reglas de verificacion (device_agent al arrancar y al recibir request)
|
||||
|
||||
1. Parsear `manifest` y `signature`.
|
||||
2. Computar `manifest_canonical`.
|
||||
3. Verificar `ed25519.Verify(operator_pubkey, manifest_canonical, signature)`.
|
||||
4. Rechazar si `expires_at < now()` → `manifest_invalid` con `details.reason = "expired"`.
|
||||
5. Rechazar si `issued_at > now() + 300` (clock skew) → `manifest_invalid` con `details.reason = "future_issued"`.
|
||||
6. Rechazar si `device_id` no coincide con `~/.config/device_agent/device_id` → `manifest_invalid`.
|
||||
7. Rechazar si `operator_pubkey_fingerprint` no coincide con la pubkey conocida → `manifest_invalid`.
|
||||
|
||||
### 2.6 Rotacion
|
||||
|
||||
Un manifest nuevo coexiste con el anterior hasta su `expires_at`. Para forzar revocacion inmediata: el hub publica un evento `manifest_revoked` (en room `#operator-broadcast`) firmado por el operador con la lista de `manifest_id` revocados. device_agent mantiene `~/.config/device_agent/revoked_manifests.json` y lo consulta antes de aceptar.
|
||||
|
||||
---
|
||||
|
||||
## 3. ed25519 signing flow
|
||||
|
||||
### 3.1 Keypair
|
||||
|
||||
- **Privada** del operador: `pass operator/ed25519`. Linea 1 = base64url de los 32 bytes del seed ed25519. Lineas siguientes = metadata (operador email, created_at, fingerprint).
|
||||
- **Publica** del operador: `~/.fn_operator.pub`. Contenido = base64url de los 32 bytes raw + `\n`. Distribuida a cada device en su `~/.config/device_agent/operator.pub` durante enrollment.
|
||||
|
||||
### 3.2 Generacion (una sola vez en la vida del operador, idempotente)
|
||||
|
||||
```bash
|
||||
# Funcion del registry: operator_keygen_bash_infra (0135 entrega)
|
||||
operator_keygen() {
|
||||
if pass show operator/ed25519 >/dev/null 2>&1; then
|
||||
echo "operator key already exists; skipping"
|
||||
return 0
|
||||
fi
|
||||
local seed pub fp
|
||||
seed=$(openssl rand 32 | base64 -w0 | tr '+/' '-_' | tr -d '=')
|
||||
pub=$(echo "$seed" | go_ed25519_derive_pub) # helper Go: seed → pub
|
||||
fp=$(echo -n "$(echo "$pub" | base64url -d)" | sha256sum | cut -c1-32)
|
||||
pass insert -m operator/ed25519 <<EOF
|
||||
$seed
|
||||
operator: $(git config user.email)
|
||||
created_at: $(date +%s)
|
||||
fingerprint: $fp
|
||||
pubkey: $pub
|
||||
EOF
|
||||
echo "$pub" > ~/.fn_operator.pub
|
||||
chmod 600 ~/.fn_operator.pub
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Sign
|
||||
|
||||
```go
|
||||
// capability_manifest_sign_go_infra (issue 0135)
|
||||
func SignManifest(m Manifest, seed []byte) ([]byte, error) {
|
||||
if len(seed) != ed25519.SeedSize {
|
||||
return nil, ErrInvalidSeed
|
||||
}
|
||||
canonical, err := canonicalizeManifest(m)
|
||||
if err != nil { return nil, err }
|
||||
msg := append([]byte("mesh/1/manifest\n"), canonical...)
|
||||
priv := ed25519.NewKeyFromSeed(seed)
|
||||
return ed25519.Sign(priv, msg), nil
|
||||
}
|
||||
```
|
||||
|
||||
Para envelopes:
|
||||
|
||||
```go
|
||||
func SignRequest(r Request, seed []byte) ([]byte, error) {
|
||||
canonical, err := canonicalRequestBytes(r)
|
||||
if err != nil { return nil, err }
|
||||
priv := ed25519.NewKeyFromSeed(seed)
|
||||
return ed25519.Sign(priv, canonical), nil
|
||||
}
|
||||
```
|
||||
|
||||
`canonicalRequestBytes` implementa §1.3.
|
||||
|
||||
### 3.4 Verify (device_agent)
|
||||
|
||||
```go
|
||||
// capability_manifest_verify_go_infra (issue 0135)
|
||||
func VerifyManifest(signed SignedManifest, pubkey []byte) error {
|
||||
if len(pubkey) != ed25519.PublicKeySize {
|
||||
return ErrInvalidPubkey
|
||||
}
|
||||
canonical, err := canonicalizeManifest(signed.Manifest)
|
||||
if err != nil { return err }
|
||||
msg := append([]byte("mesh/1/manifest\n"), canonical...)
|
||||
if !ed25519.Verify(pubkey, msg, signed.Signature) {
|
||||
return ErrSignatureInvalid
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Domain separators (criticos)
|
||||
|
||||
Cada tipo de firma usa prefix unico para evitar cross-protocol attacks:
|
||||
|
||||
| Tipo | Prefix |
|
||||
|---|---|
|
||||
| Manifest | `"mesh/1/manifest\n"` |
|
||||
| Request envelope | `"mesh/1/request\n"` (implicito en §1.3 — usa el `\n` join) |
|
||||
| Enrollment token | `"mesh/1/enroll\n"` |
|
||||
| Approval token | `"mesh/1/approval\n"` |
|
||||
| Manifest revocation | `"mesh/1/revoke\n"` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Enrollment token
|
||||
|
||||
Token corto firmado por el operador que un device usa **una sola vez** para registrarse contra `wg_hub` y obtener su config WireGuard + manifest inicial.
|
||||
|
||||
### 4.1 Payload JSON (canonical)
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed_capabilities": ["shell.exec", "fs.read", "docker.container.list"],
|
||||
"device_id": "home-wsl",
|
||||
"expires_at": 1748131800,
|
||||
"issued_at": 1748131200,
|
||||
"nonce": "Tk9NbjVxV3JLcF9j",
|
||||
"operator_pubkey_fingerprint": "a1b2c3d4e5f60718",
|
||||
"protocol_version": "mesh/1",
|
||||
"purpose": "enroll"
|
||||
}
|
||||
```
|
||||
|
||||
- `expires_at - issued_at` <= 600s (10 min). Hub rechaza si excede.
|
||||
- `allowed_capabilities`: subset que el operador autoriza a este enrollment. El manifest final puede ser mas restrictivo pero no mas amplio.
|
||||
- `nonce` previene replay incluso si el operador reusa el token por error.
|
||||
- `purpose: "enroll"` es discriminator interno; los otros valores reservados son `"approval"` (§6) y `"revoke"`.
|
||||
|
||||
### 4.2 Wire format
|
||||
|
||||
```
|
||||
base64url(json_canonical(payload)) + "." + base64url(ed25519_signature)
|
||||
```
|
||||
|
||||
Ejemplo (truncado):
|
||||
|
||||
```
|
||||
eyJhbGxvd2VkX2NhcGFiaWxpdGllcyI6WyJzaGVsbC5leGVjIiwiZnMucmVhZCJdLCJkZXZpY2VfaWQiOiJob21lLXdzbCIsLi4u.k7YpQwE9Vh...
|
||||
```
|
||||
|
||||
Aproximadamente 280-320 bytes. Cabe en un QR Code v6 (error correction M).
|
||||
|
||||
### 4.3 Generacion (operador)
|
||||
|
||||
```bash
|
||||
# enroll_device pipeline (issue 0139) llama:
|
||||
./fn run enrollment_token_create home-wsl \
|
||||
--capabilities "shell.exec,fs.read,docker.container.list" \
|
||||
--ttl 600
|
||||
# stdout: token base64url
|
||||
```
|
||||
|
||||
### 4.4 Verificacion (wg_hub `POST /enroll`)
|
||||
|
||||
```go
|
||||
// enrollment_token_verify_go_infra (issue 0135)
|
||||
func VerifyEnrollToken(raw string, pubkey []byte) (*EnrollPayload, error) {
|
||||
parts := strings.Split(raw, ".")
|
||||
if len(parts) != 2 { return nil, ErrTokenMalformed }
|
||||
payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
|
||||
if err != nil { return nil, ErrTokenMalformed }
|
||||
sig, err := base64.RawURLEncoding.DecodeString(parts[1])
|
||||
if err != nil { return nil, ErrTokenMalformed }
|
||||
msg := append([]byte("mesh/1/enroll\n"), payloadBytes...)
|
||||
if !ed25519.Verify(pubkey, msg, sig) {
|
||||
return nil, ErrSignatureInvalid
|
||||
}
|
||||
var p EnrollPayload
|
||||
if err := json.Unmarshal(payloadBytes, &p); err != nil {
|
||||
return nil, ErrTokenMalformed
|
||||
}
|
||||
now := time.Now().Unix()
|
||||
if p.ExpiresAt < now { return nil, ErrTokenExpired }
|
||||
if p.IssuedAt > now + 300 { return nil, ErrTokenFutureIssued }
|
||||
if p.Purpose != "enroll" { return nil, ErrTokenWrongPurpose }
|
||||
return &p, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 POST /enroll (wg_hub)
|
||||
|
||||
```
|
||||
POST https://organic-machine.com/enroll
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"enrollment_token": "eyJhbGxv...QwE",
|
||||
"device_pubkey_wg": "K3v8...j0c=", // WG public key del device, generada por wg_keygen
|
||||
"device_hostname": "home-wsl",
|
||||
"device_os": "linux-wsl2",
|
||||
"device_arch": "x86_64"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"wg_config": "[Interface]\nPrivateKey = <keep on device>\nAddress = 10.42.0.10/24\n[Peer]\nPublicKey = ...\nEndpoint = organic-machine.com:51820\nAllowedIPs = 10.42.0.0/24\nPersistentKeepalive = 25\n",
|
||||
"manifest": { /* signed manifest */ },
|
||||
"matrix_room": "!abc123:organic-machine.com",
|
||||
"matrix_invite_url": "https://matrix.to/#/!abc123:organic-machine.com?via=organic-machine.com"
|
||||
}
|
||||
```
|
||||
|
||||
Hub marca el token como `consumed` en `wg_enrollment_tokens` (token_nonce as PK) — segundo uso rechazado con `nonce_replay`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Replay protection
|
||||
|
||||
### 5.1 Nonces
|
||||
|
||||
- 16 bytes `crypto/rand` por request.
|
||||
- Server (device_agent O hub) mantiene tabla `seen_nonces`:
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS seen_nonces (
|
||||
nonce TEXT PRIMARY KEY, -- base64url
|
||||
seen_at INTEGER NOT NULL, -- unix seconds
|
||||
request_id TEXT NOT NULL,
|
||||
expires_at INTEGER NOT NULL -- seen_at + 300
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_seen_nonces_expires ON seen_nonces(expires_at);
|
||||
```
|
||||
|
||||
- TTL = 300s. Job periodico (cada 60s) borra entradas con `expires_at < now()`.
|
||||
|
||||
### 5.2 Timestamp
|
||||
|
||||
- `ts` debe estar en `[now-60, now+30]`. Mas viejo → `nonce_replay`. Mas futuro → `signature_invalid` con `details.reason="clock_skew"`.
|
||||
- Asume devices con NTP sync (`chrony`/`systemd-timesyncd`). Si un device tiene clock drift >30s, el operador recibe alerta en `#operator-approvals`.
|
||||
|
||||
### 5.3 Algoritmo
|
||||
|
||||
```go
|
||||
// Pseudo
|
||||
func AcceptNonce(db *sql.DB, nonce string, ts int64, requestID string) error {
|
||||
now := time.Now().Unix()
|
||||
if ts < now - 60 { return ErrNonceReplay }
|
||||
if ts > now + 30 { return ErrSignatureInvalid /* clock_skew */ }
|
||||
_, err := db.Exec(
|
||||
`INSERT INTO seen_nonces(nonce, seen_at, request_id, expires_at) VALUES(?,?,?,?)`,
|
||||
nonce, now, requestID, now+300,
|
||||
)
|
||||
if isUniqueViolation(err) { return ErrNonceReplay }
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
`AcceptNonce` se llama **antes** de ejecutar la capability, despues de verificar la firma. Si la firma es invalida pero el nonce es nuevo, NO se inserta (evita amplificar log spam).
|
||||
|
||||
---
|
||||
|
||||
## 6. Approval flow
|
||||
|
||||
Para capabilities con `requires_approval: true`, device_agent NO ejecuta sin recibir un approval token firmado por el operador.
|
||||
|
||||
### 6.1 Secuencia
|
||||
|
||||
```
|
||||
[operator] [agents_and_robots] [device_agent] [#operator-approvals]
|
||||
| | | |
|
||||
| !exec rm -rf /tmp/x in #dev-home-wsl | |
|
||||
|------------------->| | |
|
||||
| |--- request envelope ->| |
|
||||
| | |--- decide: approval needed
|
||||
| | | |
|
||||
| |<--- approval_request -| |
|
||||
| |--- post to #op-approvals ----------------->|
|
||||
| | | |
|
||||
|<--- notification --| | |
|
||||
| |
|
||||
|--- reacts 👍 OR posts !approve req_01J9... ------------------->|
|
||||
| |
|
||||
| |<--- captures reaction/cmd -----------------|
|
||||
| |--- signs approval_token (via operator key)
|
||||
| |--- posts approval_token to #dev-home-wsl
|
||||
| | | |
|
||||
| |--- approval_token --->| |
|
||||
| | |--- verifies token |
|
||||
| | |--- executes |
|
||||
| |<--- response ---------| |
|
||||
|<-- output in #dev-home-wsl |
|
||||
```
|
||||
|
||||
### 6.2 Approval token payload
|
||||
|
||||
```json
|
||||
{
|
||||
"protocol_version": "mesh/1",
|
||||
"purpose": "approval",
|
||||
"request_id": "req_01J9XYZABCDEF",
|
||||
"manifest_id": "manifest_home-wsl_v3",
|
||||
"capability": "shell.exec",
|
||||
"args_hash": "a3f5...09bc",
|
||||
"approver": "egutierrez@aurgi.com",
|
||||
"approved_at": 1748131245,
|
||||
"expires_at": 1748131305,
|
||||
"nonce": "Yk9p6Xs_3hZQk4mB7lWcvA"
|
||||
}
|
||||
```
|
||||
|
||||
`args_hash` debe coincidir con `sha256_hex(json_canonical(args))` del request original — evita que el operador apruebe `ls /tmp` y el bot reemplace por `rm -rf /tmp`.
|
||||
|
||||
### 6.3 Wire format
|
||||
|
||||
Igual que enrollment token: `base64url(payload) + "." + base64url(signature)`, domain separator `"mesh/1/approval\n"`.
|
||||
|
||||
### 6.4 Captura por agents_and_robots
|
||||
|
||||
`agents_and_robots` corre como bot Matrix con la operator key cargada (a traves de `pass operator/ed25519` montado en `/etc/agents_and_robots/operator.key` con permisos 400, owned by service user). Cuando detecta:
|
||||
|
||||
- Reaccion `m.reaction` con key `👍` (U+1F44D) sobre el evento `approval_request` en `#operator-approvals`, **emitida por el matrix_id del operador** (configurado en `apps/agents_and_robots/config.yaml::operator_matrix_id`).
|
||||
- O mensaje `!approve <request_id>` en `#operator-approvals` desde el mismo matrix_id.
|
||||
|
||||
Entonces firma el approval token y lo envia a device_agent (via Matrix event `m.capability.approval` en el room del device).
|
||||
|
||||
### 6.5 Timeout
|
||||
|
||||
Si device_agent no recibe approval token en 60s tras enviar approval_request, responde al room con error `approval_timeout`. El operador puede re-emitir el comando original (genera nuevo `request_id`, nuevo nonce, nueva approval).
|
||||
|
||||
### 6.6 Approval denegada
|
||||
|
||||
Reaccion `👎` (U+1F44E) o comando `!deny <request_id>` → bot firma un `approval_denied_token` (mismo formato + `denied=true`). device_agent responde `approval_denied`.
|
||||
|
||||
### 6.7 Verificacion en device_agent
|
||||
|
||||
```go
|
||||
// Pseudo
|
||||
func VerifyApproval(token string, req Request, pubkey []byte) error {
|
||||
payload, err := decodeApprovalToken(token, pubkey)
|
||||
if err != nil { return err }
|
||||
if payload.RequestID != req.RequestID { return ErrApprovalMismatch }
|
||||
if payload.Capability != req.Capability { return ErrApprovalMismatch }
|
||||
if payload.ArgsHash != sha256Hex(canonicalJSON(req.Args)) { return ErrApprovalMismatch }
|
||||
if payload.ExpiresAt < time.Now().Unix() { return ErrApprovalExpired }
|
||||
if payload.Denied { return ErrApprovalDenied }
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Audit log hash chain
|
||||
|
||||
Append-only log local a cada device_agent con hash chain que detecta tampering. Replicado periodicamente al hub para archivo tamper-evident off-device.
|
||||
|
||||
### 7.1 Schema (`apps/device_agent/audit.db`)
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS audit_log (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
ts INTEGER NOT NULL,
|
||||
request_id TEXT NOT NULL,
|
||||
manifest_id TEXT NOT NULL,
|
||||
capability TEXT NOT NULL,
|
||||
args_hash TEXT NOT NULL,
|
||||
approval_id TEXT, -- nullable, request_id del approval token usado
|
||||
exit_code INTEGER, -- nullable mientras no haya respuesta
|
||||
ok INTEGER NOT NULL, -- 0/1
|
||||
error_code TEXT, -- nullable
|
||||
duration_ms INTEGER NOT NULL,
|
||||
prev_hash TEXT NOT NULL, -- hex 64 chars
|
||||
this_hash TEXT NOT NULL, -- hex 64 chars
|
||||
UNIQUE(request_id)
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_audit_log_ts ON audit_log(ts);
|
||||
```
|
||||
|
||||
Migracion vive en `apps/device_agent/migrations/001_init.sql`. Regla `db_migrations.md`.
|
||||
|
||||
### 7.2 Hash chain
|
||||
|
||||
```
|
||||
record_canonical = ts + "|" + request_id + "|" + manifest_id + "|" +
|
||||
capability + "|" + args_hash + "|" + approval_id_or_empty + "|" +
|
||||
exit_code_str + "|" + ok_str + "|" + error_code_or_empty + "|" +
|
||||
duration_ms_str
|
||||
|
||||
this_hash = sha256_hex(prev_hash + "\n" + record_canonical)
|
||||
```
|
||||
|
||||
Para el primer registro `prev_hash = "0000...0000"` (64 zeros).
|
||||
|
||||
`wg_peer_revoke_go_infra` (ya existente) hace algo similar para revocations; este spec usa el mismo patron para todas las invocaciones.
|
||||
|
||||
### 7.3 Append helper
|
||||
|
||||
```go
|
||||
// device_audit_append_go_infra (issue 0135)
|
||||
func AppendAudit(db *sql.DB, rec Record) (string, error) {
|
||||
var prev string
|
||||
err := db.QueryRow(`SELECT this_hash FROM audit_log ORDER BY id DESC LIMIT 1`).Scan(&prev)
|
||||
if err == sql.ErrNoRows {
|
||||
prev = strings.Repeat("0", 64)
|
||||
} else if err != nil {
|
||||
return "", err
|
||||
}
|
||||
canonical := canonicalRecord(rec)
|
||||
h := sha256.Sum256([]byte(prev + "\n" + canonical))
|
||||
this := hex.EncodeToString(h[:])
|
||||
_, err = db.Exec(`INSERT INTO audit_log(...) VALUES(...)`, /* fields, prev, this */)
|
||||
if err != nil { return "", err }
|
||||
return this, nil
|
||||
}
|
||||
```
|
||||
|
||||
Transaccion con `BEGIN IMMEDIATE` para evitar carrera entre prev_hash select y insert.
|
||||
|
||||
### 7.4 Verificacion (cualquiera con copia del db)
|
||||
|
||||
```go
|
||||
// device_audit_verify_go_infra (issue 0135)
|
||||
func VerifyChain(db *sql.DB) error {
|
||||
rows, _ := db.Query(`SELECT id, prev_hash, this_hash, /* fields */ FROM audit_log ORDER BY id`)
|
||||
expected := strings.Repeat("0", 64)
|
||||
for rows.Next() {
|
||||
var rec Record
|
||||
rows.Scan(&rec.ID, &rec.PrevHash, &rec.ThisHash /* ... */)
|
||||
if rec.PrevHash != expected { return fmt.Errorf("chain broken at id %d", rec.ID) }
|
||||
canonical := canonicalRecord(rec)
|
||||
h := sha256.Sum256([]byte(rec.PrevHash + "\n" + canonical))
|
||||
if hex.EncodeToString(h[:]) != rec.ThisHash {
|
||||
return fmt.Errorf("hash mismatch at id %d", rec.ID)
|
||||
}
|
||||
expected = rec.ThisHash
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 7.5 Replicacion al hub
|
||||
|
||||
Cada 60s device_agent hace `POST /audit/replicate` al hub con el bloque de registros nuevos (delta sobre el ultimo replicado). El hub valida la cadena, anade su propio `replicated_at`, y almacena en `apps/wg_hub/operations.db::device_audit` (tabla espejo + meta `last_replicated_id` por device).
|
||||
|
||||
Si el hub detecta `chain_broken` o `hash_mismatch`, emite evento a `#operator-approvals` con severity=critical y marca device como `status='compromised'` en `wg_peers`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Room ↔ device mapping
|
||||
|
||||
### 8.1 Schema (`apps/agents_and_robots/operations.db`)
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS room_devices (
|
||||
room_id TEXT PRIMARY KEY, -- !abc123:organic-machine.com
|
||||
device_id TEXT NOT NULL,
|
||||
manifest_id TEXT NOT NULL,
|
||||
role TEXT NOT NULL, -- 'device' | 'container' | 'approval' | 'broadcast'
|
||||
created_at INTEGER NOT NULL,
|
||||
updated_at INTEGER NOT NULL,
|
||||
active INTEGER NOT NULL DEFAULT 1
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_room_devices_device_id ON room_devices(device_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_room_devices_role ON room_devices(role);
|
||||
```
|
||||
|
||||
Migracion: `apps/agents_and_robots/migrations/NNN_room_devices.sql`.
|
||||
|
||||
### 8.2 Roles especiales
|
||||
|
||||
- `role='approval'`: hay exactamente UN room con este rol, default alias `#operator-approvals:organic-machine.com`. Bot publica `approval_request` aqui y escucha reacciones del operador.
|
||||
- `role='broadcast'`: alias `#operator-broadcast:organic-machine.com`. Bot publica eventos de control firmados (revocations, manifest rotations).
|
||||
- `role='device'`: room 1:1 por device. Alias por convencion `#dev-<device_id>:organic-machine.com`.
|
||||
- `role='container'`: para modo "deep" docker (containers como peers WG). Alias `#cont-<container_id>:organic-machine.com`.
|
||||
|
||||
### 8.3 Resolucion al dispatchar
|
||||
|
||||
Cuando el bot recibe un `!cmd` en cualquier room:
|
||||
|
||||
1. Busca `SELECT device_id, manifest_id, role FROM room_devices WHERE room_id=? AND active=1`.
|
||||
2. Si no existe → ignora (o responde "this room is not bound to a device").
|
||||
3. Si `role='device'`, dispatcha al `device_agent` correspondiente.
|
||||
4. Si `role='approval'` o `role='broadcast'`, NO acepta `!exec`/`!fs.*`/`!docker.*` — solo `!approve`, `!deny`, `!revoke`, `!help`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Element commands
|
||||
|
||||
Comandos que el bot de `agents_and_robots` parsea y traduce a envelopes. Estos viven en rooms `role='device'` o `role='container'` (excepto `!approve`/`!deny` que viven en `role='approval'`).
|
||||
|
||||
| Command | Capability | Args | Notas |
|
||||
|---|---|---|---|
|
||||
| `!help` | (meta) | none | Bot responde con capability matrix del manifest del device del room |
|
||||
| `!exec <argv...>` | `shell.exec` | `{argv: [...], cwd?: string}` | argv splits por shlex, sin shell wrapping |
|
||||
| `!fs.read <path> [bytes]` | `fs.read` | `{path, max_bytes?}` | default max_bytes = manifest.max_bytes |
|
||||
| `!fs.write <path> <<<content` | `fs.write` | `{path, content_base64}` | content viene en heredoc o quoted; bot codifica base64 |
|
||||
| `!fs.ls <path>` | `fs.list` | `{path}` | output: array de {name,type,size} |
|
||||
| `!docker exec <container> <argv...>` | `docker.container.exec` | `{container, argv}` | container debe estar en `containers_allowed` |
|
||||
| `!docker logs <container> [tail]` | `docker.container.logs` | `{container, tail?, follow?}` | `--follow` activa SSE |
|
||||
| `!docker ps` | `docker.container.list` | `{}` | output: tabla containers vivos |
|
||||
| `!approve <req_id>` | (meta) | `{request_id}` | solo en `role='approval'`, solo del operator_matrix_id |
|
||||
| `!deny <req_id>` | (meta) | `{request_id, reason?}` | idem |
|
||||
| `!revoke <device_id>` | (meta) | `{device_id, reason?}` | solo del operator_matrix_id; emite `manifest_revoked` + `wg_peer_revoke` |
|
||||
| `!status` | (meta) | none | bot responde: device IP WG, last_handshake, manifest_id activo, capabilities count |
|
||||
|
||||
### 9.1 Parsing rules
|
||||
|
||||
- Lexer shlex-style (`shlex.split` Python o equivalente). Quoted strings respetan espacios.
|
||||
- Si parsing falla → `!help` corto en la misma linea + abort.
|
||||
- Args desconocidos para una capability → `manifest_invalid` con `details.unknown_args: [...]`.
|
||||
|
||||
### 9.2 Output rendering
|
||||
|
||||
El bot formatea responses para Matrix:
|
||||
|
||||
- `ok=true`, output corto (<2KB): formatted text con `<pre><code>...</code></pre>` (Matrix `formatted_body`).
|
||||
- `ok=true`, output largo: trim a 2KB + link al artifact subido (Matrix media repo si el homeserver lo permite, sino paste a `paste.organic-machine.com`).
|
||||
- `ok=false`: render como `[ERROR error_code] message\n<details>` con codigo de color rojo en clientes que soportan colored text.
|
||||
|
||||
---
|
||||
|
||||
## 10. Error model
|
||||
|
||||
Todos los `error.code` son strings snake_case. El cliente NO debe parsear `message` — solo `code`. `details` es objeto libre por code.
|
||||
|
||||
| code | meaning | details fields | retry? |
|
||||
|---|---|---|---|
|
||||
| `manifest_invalid` | Manifest no firma, expirado, device_id mismatch, o no tiene la capability | `reason`, `manifest_id`, `expires_at?` | no — pedir manifest nuevo |
|
||||
| `capability_denied` | Capability esta en manifest pero los args violan constraints | `constraint_violated`, `value` | no — ajustar args |
|
||||
| `binary_not_whitelisted` | shell.exec con binario fuera de `binaries_whitelist` | `binary`, `whitelist` | no |
|
||||
| `path_not_allowed` | fs.* con path fuera de `paths_allowed` o en `paths_denied` | `path`, `allowed_globs`, `denied_globs` | no |
|
||||
| `container_not_allowed` | docker.* sobre container fuera de `containers_allowed` | `container`, `allowed_list` | no |
|
||||
| `approval_timeout` | requires_approval=true y no llego token en 60s | `waited_s` | si — re-enviar |
|
||||
| `approval_denied` | operador denego | `approver`, `reason?` | no |
|
||||
| `approval_mismatch` | approval token args_hash != request args_hash | `expected_hash`, `got_hash` | no — posible MITM |
|
||||
| `nonce_replay` | nonce ya visto en ventana TTL=300s | `nonce`, `first_seen_at` | no — generar nonce nuevo |
|
||||
| `signature_invalid` | firma ed25519 no verifica | `reason` (e.g. `clock_skew`, `bad_pubkey`, `corrupted`) | no |
|
||||
| `token_expired` | enrollment o approval token expirado | `expires_at`, `now` | no |
|
||||
| `token_consumed` | enrollment token ya usado (nonce en `wg_enrollment_tokens`) | `first_use_at` | no |
|
||||
| `device_revoked` | device esta en revocation list | `revoked_at`, `reason` | no |
|
||||
| `capability_not_found` | capability name no existe en device_agent | `name`, `available` | no |
|
||||
| `execution_failed` | la capability ejecuto y devolvio exit != 0 | `exit_code`, `stderr` (trimmed) | depende — semantica de la capability |
|
||||
| `output_too_large` | output > `max_output_bytes` | `bytes`, `limit` | no — pedir con tail/head |
|
||||
| `duration_exceeded` | timeout `max_duration_s` excedido | `limit_s`, `killed_signal` | no |
|
||||
| `transport_error` | error de Matrix/HTTP transport debajo del envelope | `transport`, `inner_error` | si con backoff |
|
||||
| `internal` | bug en device_agent/hub/bot; NO leakear stack al room | `incident_id` | no — operator debe ver logs |
|
||||
|
||||
### 10.1 Mapping a HTTP status (transport HTTP intra-mesh)
|
||||
|
||||
| code | HTTP |
|
||||
|---|---|
|
||||
| `manifest_invalid`, `signature_invalid`, `token_*` | 401 |
|
||||
| `capability_denied`, `binary_not_whitelisted`, `path_not_allowed`, `container_not_allowed`, `device_revoked` | 403 |
|
||||
| `capability_not_found` | 404 |
|
||||
| `nonce_replay`, `approval_mismatch` | 409 |
|
||||
| `approval_timeout`, `duration_exceeded` | 408 |
|
||||
| `output_too_large` | 413 |
|
||||
| `approval_denied` | 403 |
|
||||
| `execution_failed` | 200 (con ok=false, exit_code en body) |
|
||||
| `transport_error`, `internal` | 500 |
|
||||
|
||||
Matrix transport ignora HTTP status — el `ok=false` y `error.code` son suficientes.
|
||||
|
||||
---
|
||||
|
||||
## 11. Security threat model
|
||||
|
||||
Top 10 ataques + mitigaciones. Listadas por probabilidad x impacto. Cada item refiere al control que lo mitiga.
|
||||
|
||||
### T1. Operator ed25519 key leak
|
||||
|
||||
- **Attack**: laptop comprometida, `pass operator/ed25519` exfiltrado.
|
||||
- **Impact**: atacante firma manifests + approvals — control total de devices.
|
||||
- **Mitigation**:
|
||||
- GPG-encrypted at rest via `pass` (depende de GPG subkey).
|
||||
- Rotacion forzada: `!revoke-all` en `#operator-broadcast` → todos los devices reciben `manifest_revoked` con `device_id="*"` → entran en modo enroll.
|
||||
- Hardware-backed key (YubiKey, ssh-agent con touch policy) — out of scope v1, candidato a issue futuro.
|
||||
- Detection: hub registra todas las firmas (mensaje `signed_by_operator_at`); operador revisa diariamente.
|
||||
|
||||
### T2. Compromised device executes unauthorized capabilities
|
||||
|
||||
- **Attack**: device_agent comprometido, atacante quiere ejecutar capabilities fuera del manifest.
|
||||
- **Impact**: limitado a las capabilities del manifest (asumiendo verify es correcto).
|
||||
- **Mitigation**:
|
||||
- Manifest verify obligatorio antes de cada request (§2.5).
|
||||
- Sandbox: `firejail` (Linux) o equivalente — ver issue 0140.
|
||||
- Whitelist binarios + paths + containers (§2).
|
||||
- Audit chain replicado a hub (§7.5) — atacante no puede borrar audit.
|
||||
|
||||
### T3. Replay attack
|
||||
|
||||
- **Attack**: atacante captura request firmado valido (de un log, de Matrix federation leak), lo reenvia.
|
||||
- **Impact**: capability ejecutada 2x.
|
||||
- **Mitigation**: §5. Nonce TTL=300s + ts window 60s. SQLite UNIQUE constraint.
|
||||
|
||||
### T4. MITM despite WireGuard
|
||||
|
||||
- **Attack**: alguien dentro del mesh WG (otro device comprometido) intercepta requests entre bot y device.
|
||||
- **Impact**: leer args/output; modificar args si firma se ignora.
|
||||
- **Mitigation**:
|
||||
- HTTP intra-mesh sobre TLS (cert auto-firmado mesh-only, pinned).
|
||||
- Matrix transport: E2EE via Olm/Megolm — bot debe verificar device keys del room antes de aceptar.
|
||||
- Firma del envelope (§1.3) — args modificados → `signature_invalid`.
|
||||
|
||||
### T5. Container escape
|
||||
|
||||
- **Attack**: container con `docker.container.exec` activado escapa a host.
|
||||
- **Impact**: host comprometido, no mas que T2.
|
||||
- **Mitigation**:
|
||||
- `binaries_whitelist` estricta en `docker.container.exec` (sin `bash`, `sh`, `nsenter`, `unshare`).
|
||||
- Modo "deep" (container con WG-peer propio) solo para containers de propia infra (`agents_and_robots`, `registry_api`).
|
||||
- Docker socket NUNCA expuesto via capability (capability solo via `docker_container_exec_go_infra` que NO usa `--privileged` en exec).
|
||||
- Detection: container con syscalls anomalas → logged por seccomp profile (out of scope v1).
|
||||
|
||||
### T6. Malicious manifest with crafted globs
|
||||
|
||||
- **Attack**: operador firma manifest con `paths_allowed: ["/home/lucas/**"]` pero device_agent tiene bug en glob matcher que permite `..` traversal.
|
||||
- **Impact**: fs.read fuera del directorio.
|
||||
- **Mitigation**:
|
||||
- Implementacion glob: `filepath.Match` Go + canonicalizar path con `filepath.Clean` + verificar `strings.HasPrefix(cleaned, allowed_prefix)`.
|
||||
- Reject paths con `..` antes de glob match.
|
||||
- Test suite con corpus de path traversal (`../../etc/passwd`, `/home/lucas/../etc/passwd`, symlinks).
|
||||
|
||||
### T7. Enrollment token theft
|
||||
|
||||
- **Attack**: token QR fotografiado por tercero.
|
||||
- **Impact**: tercero hace POST /enroll con su propia WG pubkey → device fantasma en la mesh.
|
||||
- **Mitigation**:
|
||||
- TTL=600s.
|
||||
- Single-use (nonce consumed en hub).
|
||||
- Operador recibe alerta en `#operator-approvals` cada vez que un device hace POST /enroll exitoso — si no esperabas un enroll, `!revoke` inmediato.
|
||||
|
||||
### T8. Matrix homeserver compromise
|
||||
|
||||
- **Attack**: atacante root en `organic-machine.com` modifica eventos Matrix.
|
||||
- **Impact**: si E2EE roto, todo el contenido leak. Si E2EE OK, solo metadata.
|
||||
- **Mitigation**:
|
||||
- Megolm E2EE entre operador y bot — keys nunca en disco del homeserver.
|
||||
- Envelope firmado (§1.3) — atacante no puede inyectar requests sin operator key.
|
||||
- Hub WG segregado: `wg_hub` corre en mismo VPS pero NO confia en Matrix para autorizacion (solo para transport).
|
||||
|
||||
### T9. Clock skew abuse
|
||||
|
||||
- **Attack**: device con clock muy adelantado firma requests con `ts` futuro grande, los almacena, los reenvia cuando `ts` cae en ventana.
|
||||
- **Impact**: replay extendido mas alla de TTL.
|
||||
- **Mitigation**:
|
||||
- Ventana ts: `[now-60, now+30]` — clock skew tolerado pequeño.
|
||||
- Devices forzados a sync NTP (chrony) — el provision check verifica `chronyc tracking` reporta `Leap status: Normal`.
|
||||
- Hub alerta a `#operator-approvals` si recibe replicacion de audit con `ts` que difiere >30s del `received_at`.
|
||||
|
||||
### T10. Denial of service via approval flooding
|
||||
|
||||
- **Attack**: atacante con manifest valido pero capabilities limitadas spam `requires_approval=true` requests para inundar `#operator-approvals`.
|
||||
- **Impact**: operador pierde signal en noise; legitimo approval enterrado.
|
||||
- **Mitigation**:
|
||||
- Rate limit en agents_and_robots: por device_id, max 10 approval_requests / 5min.
|
||||
- Excedente → silently dropped + audit entry + `#operator-approvals` recibe resumen agregado (`device home-wsl: 47 approval requests in 5min, throttled`).
|
||||
- Si pattern repetido, operador `!revoke home-wsl`.
|
||||
|
||||
---
|
||||
|
||||
## 12. Implementation order
|
||||
|
||||
Las issues 0135-0143 implementan lo definido en este spec. Dependencias y orden:
|
||||
|
||||
| # | Issue | Que entrega | Depende de | Bloquea |
|
||||
|---|---|---|---|---|
|
||||
| 0135 | capability manifest sign/verify funcs | `capability_manifest_sign_go_infra`, `capability_manifest_verify_go_infra`, `enrollment_token_create_go_infra`, `enrollment_token_verify_go_infra`, `device_audit_append_go_infra`, `device_audit_verify_go_infra`, `operator_keygen_bash_infra` | 0134 (spec) | 0136, 0137, 0140, 0142 |
|
||||
| 0136 | provision_wg_hub pipeline | `provision_wg_hub_bash_pipelines` que compone las 9 funciones `wg_*` (ver flow 0009 Fase C) | 0135 (audit funcs solamente; resto independiente) | 0137 |
|
||||
| 0137 | wg_hub Go service | `apps/wg_hub/` con endpoints `POST /enroll`, `GET /peers`, `POST /peers/:id/revoke`, `POST /audit/replicate`, SSE `/events` | 0135, 0136 | 0138, 0139 |
|
||||
| 0138 | agents_dashboard Mesh panel | Panel ImGui en `apps/agents_dashboard/` con lista de peers, last_handshake, bytes rx/tx, approval queue, boton revoke | 0137 | — |
|
||||
| 0139 | enroll_device pipeline | `enroll_device_bash_pipelines` que el operador corre en su laptop para enroll un device nuevo (genera token, lo muestra como QR, hace POST /enroll en nombre del device si tiene SSH) | 0135, 0137 | 0140, 0141 |
|
||||
| 0140 | device_agent Go binary | `apps/device_agent/` — Matrix client + capability dispatcher + sandbox firejail + audit chain. Cross-compile linux/amd64, linux/arm64, windows/amd64 | 0135, 0139 | 0142 |
|
||||
| 0141 | Android Termux variant | `apps/device_agent_android/` — variante para Termux con WG via wg-go (userspace) y capabilities limitadas (no firejail) | 0140 | — |
|
||||
| 0142 | Matrix bot dispatcher routes | Extender `apps/agents_and_robots/` con dispatcher `m.capability.*` → device, parse de comandos §9, room_devices table | 0135, 0137, 0140 | 0143 |
|
||||
| 0143 | Operator approval flow | Capturar reactions en `#operator-approvals`, firmar approval tokens, enviar a device, registrar timeout. En `apps/agents_and_robots/` | 0142 | — |
|
||||
|
||||
### 12.1 Paralelismo
|
||||
|
||||
- 0135 secuencial (todo lo demas depende).
|
||||
- 0136 + 0140 paralelos tras 0135.
|
||||
- 0137 espera 0136 (necesita las funciones `wg_*`).
|
||||
- 0138 + 0139 + 0140 paralelos tras 0137.
|
||||
- 0141 tras 0140.
|
||||
- 0142 + 0143 ultimo bloque.
|
||||
|
||||
Skill `parallel-fix-issues` puede orquestar 0136/0140 y 0138/0139 en worktrees aislados (ojo: 0140 crea sub-repo `apps/device_agent/`, requiere `git init` dentro como dice `apps_subrepo.md`).
|
||||
|
||||
### 12.2 Acceptance gate para cerrar 0134
|
||||
|
||||
- [ ] Este documento mergeado en `dev/issues/`.
|
||||
- [ ] Issues 0135-0143 creados con frontmatter coherente (`dependencies` apuntando aqui, `related_flows: [0009]`).
|
||||
- [ ] Capabilities groups `wireguard`, `device-agent`, `docker-agent` con stubs en `docs/capabilities/` referenciando este spec.
|
||||
- [ ] No changes en wire format hasta que todos los issues 0135-0143 cierren — cambios posteriores requieren nuevo issue + bump `protocol_version`.
|
||||
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
### Wire format evolution policy
|
||||
|
||||
`protocol_version: mesh/1` es immutable durante el ciclo de vida de las issues 0135-0143. Cualquier cambio breaking (renombrar campo, cambiar canonical bytes, anadir campo obligatorio) requiere bump a `mesh/2` con un issue nuevo que documente migracion y compat layer.
|
||||
|
||||
Cambios non-breaking aceptados sin bump:
|
||||
- Anadir nuevos `error.code` (clientes los manejan via fallback a `internal`).
|
||||
- Anadir nuevas capabilities (devices viejos las rechazan con `capability_not_found`).
|
||||
- Anadir campos opcionales con default backwards-compatible.
|
||||
|
||||
### Test corpus
|
||||
|
||||
Cada funcion de §3 y §4 entrega test fixtures en `cpp/functions/*/testdata/` o equivalente:
|
||||
|
||||
- `manifest_valid.json` + `manifest_valid.sig` — par validable.
|
||||
- `manifest_expired.json` — para test de §2.5 paso 4.
|
||||
- `manifest_tampered.json` + sig original — para test de signature_invalid.
|
||||
- `enroll_token_valid.txt`, `enroll_token_expired.txt`, `enroll_token_wrong_purpose.txt`.
|
||||
- `path_traversal_corpus.txt` con 50+ paths maliciosos para test T6.
|
||||
|
||||
### Capability groups stubs
|
||||
|
||||
Como parte de este issue se crean stubs minimos en:
|
||||
|
||||
- `docs/capabilities/wireguard.md` — lista de las 9 funciones `wg_*` (referenciadas desde flow 0009).
|
||||
- `docs/capabilities/device-agent.md` — capability dispatcher + sandbox + audit chain.
|
||||
- `docs/capabilities/docker-agent.md` — capabilities sobre containers.
|
||||
|
||||
Cada uno con seccion `## Ejemplo canonico` + `## Fronteras` segun regla `capability_groups.md`. Los stubs se llenan a medida que las funciones se crean en 0135-0142.
|
||||
|
||||
### Observabilidad
|
||||
|
||||
- Cada envelope request/response loggea en `call_monitor.calls` con `function_id = capability_<name>_<lang>_<domain>` cuando la implementacion exista. Si la capability es solo metadata (`!help`), no se loggea.
|
||||
- `audit_log` (§7) es separado de `call_monitor` — el primero es tamper-evident del operator, el segundo es telemetria del agente Claude.
|
||||
- Panel "Mesh" de `agents_dashboard` (issue 0138) consume:
|
||||
- `wg_hub::wg_peers` (peers vivos + last_handshake + tx/rx).
|
||||
- `wg_hub::device_audit` (replica de audit chains — para verificacion offline).
|
||||
- `agents_and_robots::room_devices` (mapping rooms ↔ devices).
|
||||
- `agents_and_robots::approvals_pending` (queue de approvals pendientes).
|
||||
|
||||
### Capability growth log
|
||||
|
||||
`v0.1.0 (2026-05-24)` — initial spec mesh/1.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,232 @@
|
||||
---
|
||||
id: "0146"
|
||||
title: "add-pc one-shot: añade PC al mesh + agente LLM en <2min desde movil"
|
||||
status: pending
|
||||
priority: high
|
||||
created: 2026-05-24
|
||||
related_flows: ["0009"]
|
||||
related_issues: ["0134", "0144", "0145"]
|
||||
dependencies: []
|
||||
tags: [mesh, wireguard, ssh, scaffolder, agents, llm, scaling, dx]
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
Reducir de 8 pasos manuales (~15min) a **1 comando (<2min)** el flujo de añadir un PC nuevo al mesh con su propio agente LLM conversacional. Goal final: chatear desde Element movil con cualquier PC del usuario tras un `./fn run add_pc <name>`.
|
||||
|
||||
## Estado actual (post-0145)
|
||||
|
||||
Pipeline manual funcional pero verboso:
|
||||
1. Instalar wireguard en PC nuevo.
|
||||
2. wg_keygen.
|
||||
3. wg_peer_add en hub (organic-machine.com).
|
||||
4. wg_client_config + wg_client_install.
|
||||
5. Build/scp device_agent binario.
|
||||
6. Manifest YAML local.
|
||||
7. systemd unit.
|
||||
8. provision-agent-user.sh + edit launcher main.go + rebuild + restart agents_and_robots.
|
||||
|
||||
Solo agent-wsl-lucas existe. Bloqueado por friccion de pasos para escalar a aurgi-pc, windows-lucas, raspberry, etc.
|
||||
|
||||
## Vision
|
||||
|
||||
```
|
||||
operador$ ./fn run add_pc aurgi-pc --via wg
|
||||
[1/9] generating WG keypair...
|
||||
[2/9] enrolling peer at hub (10.42.0.21)...
|
||||
[3/9] cross-compiling device_agent for linux/amd64...
|
||||
[4/9] uploading binary + manifest + systemd unit via SSH...
|
||||
[5/9] starting WG + device_agent on remote...
|
||||
[6/9] provisioning Matrix user @agent-aurgi-pc...
|
||||
[7/9] generating agent config + system prompt...
|
||||
[8/9] wiring launcher + rebuild...
|
||||
[9/9] restarting agents_and_robots.service...
|
||||
✓ agent-aurgi-pc live. Send a DM from your Matrix client.
|
||||
```
|
||||
|
||||
Y para hosts sin posibilidad de instalar binary:
|
||||
```
|
||||
operador$ ./fn run add_pc customer-vps-01 --via ssh --ssh-alias customer-prod
|
||||
✓ agent-customer-vps-01 live (ssh-backed). Send a DM.
|
||||
```
|
||||
|
||||
## Arquitectura
|
||||
|
||||
Dos backends para un mismo UX:
|
||||
|
||||
### Backend A — WG + device_agent (mesh nativo)
|
||||
- PC tiene WG client + binary device_agent corriendo.
|
||||
- Comandos viajan VPS → WG → device_agent → exec local → audit chain LOCAL.
|
||||
- 14 capabilities completas (fs.*, git.*, docker.*, pkg.*, proc.*, shell.exec, shell.eval).
|
||||
- Para tus PCs (laptop, desktop, raspberry, mac, movil rooted).
|
||||
|
||||
### Backend B — SSH-only (sin binary remoto)
|
||||
- PC tiene solo SSH server. VPS tiene SSH key autorizada.
|
||||
- Comandos viajan VPS → ssh.Executor → exec remoto → audit en VPS.
|
||||
- Tools reducidos: `ssh_exec(argv)`, `ssh_fs_read`, `ssh_fs_list`. Sin docker/git/pkg salvo wrapper.
|
||||
- Para customer servers, VPS terceros, throwaway boxes.
|
||||
|
||||
LLM agent ve diferentes tool sets segun backend. Mismo system prompt template.
|
||||
|
||||
## Tareas
|
||||
|
||||
### Fase 1 — Pipeline `add_pc_wg_bash_pipelines`
|
||||
|
||||
1.1. Cross-compile device_agent matrices:
|
||||
- `GOOS=linux GOARCH=amd64` (default)
|
||||
- `GOOS=linux GOARCH=arm64` (raspberry pi4+, mac M-series via Linux)
|
||||
- `GOOS=windows GOARCH=amd64`
|
||||
- `GOOS=darwin GOARCH=arm64`
|
||||
- Reusa `nohup` cgo-free build (swap mattn/go-sqlite3 → modernc.org/sqlite si no esta hecho ya).
|
||||
- Output: `cpp/build/cross/device_agent.<os>-<arch>`.
|
||||
|
||||
1.2. Funcion `cross_compile_device_agent_bash_infra(target_os, target_arch)` que devuelve path al binario.
|
||||
|
||||
1.3. Funcion `add_pc_wg_bash_pipelines(name, ssh_alias, target_os?, target_arch?)`. Compone:
|
||||
- wg_keygen_go_infra (hub side: priv hub + psk; client side: priv cliente)
|
||||
- wg_peer_add_go_infra (en hub via SSH al VPS)
|
||||
- wg_client_config_go_infra (genera client.conf)
|
||||
- ensure_remote_wireguard_installed (SSH al target, apt/dnf install wireguard si falta)
|
||||
- wg_client_install_bash_infra (en target via SSH push)
|
||||
- cross_compile_device_agent_bash_infra (local)
|
||||
- rsync_device_agent_bundle (binary + manifest template + systemd unit → target ~/.local/bin/ + ~/.config/device_agent/)
|
||||
- start_device_agent_service (systemctl --user enable --now device_agent)
|
||||
- provision_agent_user (ssh al VPS, ejecuta dev-scripts/agent/provision-agent-user.sh con --mode user)
|
||||
- wire_launcher_import (edita cmd/launcher/main.go en VPS, anade blank import, git commit + rebuild + restart service)
|
||||
- assert_dm_received (espera 30s a que el bot mande "hola" via notify-developer.sh)
|
||||
|
||||
1.4. Manifest template Y matrix per-OS: paths_allowed difieren (`/home/<user>/**` en Linux, `C:\Users\<user>\**` en Windows). Templates en `dev-scripts/agent/templates/manifest.<os>.yaml.tmpl`.
|
||||
|
||||
1.5. Idempotente: re-run con mismo name → no-op + verificar state. Si peer existe pero device_agent caido, restart.
|
||||
|
||||
1.6. Rollback: si paso N falla, deshacer 1..N-1. Estado parcial NO debe quedar (peer huerfano, Matrix user sin agent, etc).
|
||||
|
||||
### Fase 2 — Pipeline `add_pc_ssh_bash_pipelines` (backend B)
|
||||
|
||||
2.1. Funcion `ssh_exec_capability_go_infra` — wrapper que recibe `{argv, host}` y hace `ssh <host> -- <argv...>`. Whitelist binaries opcional. Audit en VPS (`apps/agents_and_robots/ssh_audit.db` o similar).
|
||||
|
||||
2.2. Funcion `ssh_fs_read_capability_go_infra`, `ssh_fs_list_capability_go_infra` (read-only, no write para evitar accidentes en customer boxes).
|
||||
|
||||
2.3. Tool registry adapter: cuando agent config tiene `device_mesh.backend: ssh`, el adapter no apunta a HTTP device_agent — apunta a las funciones `ssh_*` directamente. Mantener interface ToolRegistry pero swap implementation.
|
||||
|
||||
2.4. `add_pc_ssh_bash_pipelines(name, ssh_alias)` compone:
|
||||
- assert_ssh_reachable (BatchMode yes connect test)
|
||||
- provision_agent_user --mode user --backend ssh
|
||||
- generate agent config con `device_mesh.backend: ssh, ssh_alias: <alias>`
|
||||
- wire launcher + restart
|
||||
|
||||
NO toca el remote — solo VPS.
|
||||
|
||||
### Fase 3 — Cross-compile device_agent CGO-free
|
||||
|
||||
3.1. Swap mattn/go-sqlite3 (CGO) → modernc.org/sqlite (pure Go) en device_agent. Tests verde tras swap.
|
||||
|
||||
3.2. `cross_compile_device_agent_bash_infra` produce 4 binarios en <30s.
|
||||
|
||||
3.3. Bundle script `make-bundle.sh <os> <arch>` empaqueta zip con binario + manifest.template + systemd-unit/launchd-plist/Task-Scheduler.xml segun OS.
|
||||
|
||||
### Fase 4 — agents_dashboard "Add device" panel C++
|
||||
|
||||
4.1. Modal nuevo en panel "Devices" con:
|
||||
- Input: nombre del PC.
|
||||
- Dropdown backend: WG mesh / SSH-only.
|
||||
- Si WG: SSH alias para upload + OS/arch detect via uname remote.
|
||||
- Si SSH: solo alias.
|
||||
- Boton "Add". Spawn pipeline en background. Stream logs en TextLog.
|
||||
|
||||
4.2. Grid de status: device_id, IP mesh, last handshake, capabilities count, last command ts, audit chain integrity.
|
||||
|
||||
4.3. Boton "Revoke" por device → llama wg_peer_revoke + deactivate Matrix user + remove launcher import + restart. Confirmacion doble.
|
||||
|
||||
### Fase 5 — Health monitor cron + alertas
|
||||
|
||||
5.1. Cron 5min `monitor_mesh_health_bash_pipelines`:
|
||||
- wg_status → cada peer con last_handshake > 600s → mark stale.
|
||||
- HTTP GET /health a cada device_agent IP del mesh → si falla → mark unreachable.
|
||||
- verify_hash_chain por device → si rota → mark corrupted.
|
||||
|
||||
5.2. Alertas Matrix a `#operator-alerts` (room a crear) con mensaje formato:
|
||||
```
|
||||
[ALERT] device_id=aurgi-pc status=stale (handshake 8min ago)
|
||||
[ALERT] device_id=home-wsl status=hash_chain_corrupted (id=47 broken)
|
||||
```
|
||||
|
||||
5.3. Dashboard tab "Health" muestra el feed SSE.
|
||||
|
||||
### Fase 6 — Movil UX validation
|
||||
|
||||
6.1. Test en Element movil iOS/Android:
|
||||
- Lista de rooms con 1 per device.
|
||||
- Notifications activas → push cuando agent responde.
|
||||
- Smoke tests de capabilities mas comunes via voice-to-text.
|
||||
|
||||
6.2. Documentar `docs/mobile-control.md` con flujo recomendado:
|
||||
- Como agrupar rooms por device en Element favorites.
|
||||
- Comandos comunes ("status", "deploy X", "que esta caido").
|
||||
- Tiempos esperados (claude-code latency 3-5s + tool exec 0.1-2s).
|
||||
|
||||
## Aceptacion (DoD triada)
|
||||
|
||||
### Mecanica
|
||||
- `./fn run add_pc <name> --via wg` exit 0 + agent live en <2min en wallclock.
|
||||
- `./fn run add_pc <name> --via ssh` exit 0 + agent live en <30s.
|
||||
- Tests unit + integration verde en `bash/functions/pipelines/add_pc_*`.
|
||||
|
||||
### Cobertura
|
||||
- Smoke matrix: 4 target OS (linux/amd64, linux/arm64, windows/amd64, darwin/arm64) cada uno con add_pc_wg flujo end-to-end.
|
||||
- Rollback: simular falla en paso 5 (binary upload corrupted) → assert estado limpio (no peer huerfano, no Matrix user, no entry en launcher).
|
||||
- SSH backend: target solo con SSH + sin sudo → agent funciona con tools ssh_exec read-only.
|
||||
- Anti-criterio A3 (heredado de 0009): tras add_pc, smoke real via Matrix → audit DB en device tiene entries reales (no bot hallucination).
|
||||
|
||||
### Vida util
|
||||
- 5 PCs reales añadidos durante 7 dias.
|
||||
- 0 revokes manuales por error de provision.
|
||||
- Operador usa Element movil >=1 sesion/dia interactuando con >=2 devices distintos.
|
||||
- Health monitor detecta peer caido en <10min (test con `wg-quick down` aleatorio).
|
||||
|
||||
### Anti-criterios
|
||||
- Si add_pc deja estado parcial (peer en wg0 + no agent en launcher) → invalida.
|
||||
- Si SSH backend ejecuta comandos sin audit en VPS → invalida (no fake "ssh OK" sin log).
|
||||
- Si dashboard muestra device "online" pero ultimo handshake >24h → invalida (false positive grave).
|
||||
|
||||
## Sub-issues planificados
|
||||
|
||||
| ID | Titulo | Esfuerzo |
|
||||
|---|---|---|
|
||||
| 0146a | cross_compile_device_agent + CGO-free swap a modernc.org/sqlite | 2h ✅ |
|
||||
| 0146b | add_pc_wg_bash_pipelines (Fase 1) | 4h |
|
||||
| 0146c | add_pc_ssh_bash_pipelines + ssh_exec_capability (Fase 2) | 3h |
|
||||
| 0146d | Bundle script multi-OS + manifest templates (Fase 3) | 2h |
|
||||
| 0146e | agents_dashboard panel "Add device" + status grid (Fase 4) | 4h |
|
||||
| 0146f | monitor_mesh_health pipeline + alertas Matrix (Fase 5) | 1.5h |
|
||||
| 0146g | Movil UX doc + smoke real con 4 devices fisicos (Fase 6) | 1h+observacion 7d |
|
||||
|
||||
Total: ~17h dev + 7d observacion.
|
||||
|
||||
## Decisiones de diseño
|
||||
|
||||
1. **Pipeline en bash compose funciones del registry**, no codigo Go monolitico. Permite que cada paso sea trazable + reusable individualmente.
|
||||
|
||||
2. **modernc.org/sqlite** vs mattn/go-sqlite3: pure Go elimina CGO + cross-compile trivial. Performance es comparable (modernc benchmarks dentro del 10% para nuestro workload de audit append).
|
||||
|
||||
3. **Backend SSH NO replica el manifest enforcement remoto** — el manifest vive en VPS y filtra antes de SSH. Trade-off aceptable: SSH backend = "trust the VPS sudo enforcement". Para PCs propios usa WG backend.
|
||||
|
||||
4. **Cada device = un agent Matrix separado** (NO un agent multi-device). Razon: aislamiento blast radius + room por device = UX claro en Element + capability manifest distinto por device. Coste: mas Matrix users + mas claude-code subprocesses.
|
||||
|
||||
5. **NO usar Ansible/Terraform** para este flujo. Pipeline bash + funciones del registry es suficiente y evita la dep externa. Si crece a >50 PCs, reconsiderar.
|
||||
|
||||
## Riesgos
|
||||
|
||||
- **Cross-compile + CGO-free**: el swap a modernc puede romper audit en runtime si schemas no migran. Mitigar con test golden DB + WAL mode check.
|
||||
- **Windows systemd equivalente**: Task Scheduler es feo. Considera nssm.exe para autostart fiable. Documentar bien en bundle.
|
||||
- **SSH key trust amplification**: backend B requiere SSH agent del VPS confiable a TODOS los target hosts. Si VPS comprometido → todos los SSH targets caen. Reforzar con SSH key per-host + revocacion centralizada.
|
||||
- **Mac iCloud signing**: device_agent.app necesitaria notarization para auto-launch en macOS reciente. Skip para POC, abordar si añadimos Mac al mesh real.
|
||||
- **Movil notifications**: Element push depends on FCM (Android) / APNs (iOS). Sin push, el operador puede perderse approvals time-sensitive. Doc sobre alternativas (NTFY, Gotify).
|
||||
|
||||
## Notas
|
||||
|
||||
- **2026-05-24 — 0146a done**: swap mattn/go-sqlite3 → modernc.org/sqlite v1.50.1 (pure Go). 4 binarios cross-compile OK (linux-amd64 11MB, linux-arm64 10MB, windows-amd64 11MB, darwin-arm64 10MB), todos stripped + statically linked. Build script idempotente en `apps/device_agent/build_all.sh`. Self-test pass en linux-amd64 nativo. Quedan smoke tests reales en windows/darwin/arm cuando 0146b despliegue a peers fisicos.
|
||||
- `./fn run add_pc` deberia llamar via mcp__registry__fn_run para que telemetria de issue 0085 quede registrada.
|
||||
- Aprovechar 0144b provision-agent-user.sh que ya esta hecho — solo compone, no reescribe.
|
||||
- Sub-issue 0146g (UX movil) cierra el flow 0009 completo al fin: "humano controla N maquinas desde movil".
|
||||
- Si esto funciona, abrir issue 0147 para "voice control" — Element soporta voice messages; usar transcripcion (Whisper local en VPS) → inyectar como texto al agent.
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
id: "0164"
|
||||
title: "Bots agents_and_robots: cryptohelper.Init() cuelga al habilitar encryption=true"
|
||||
status: pending
|
||||
priority: high
|
||||
created: 2026-05-24
|
||||
related_flows: ["0009"]
|
||||
related_issues: ["0144", "0162"]
|
||||
dependencies: ["0162"]
|
||||
tags: [matrix, e2ee, mautrix, cryptohelper, agents, hang, debug]
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
Que los agents de `agents_and_robots` (`agent-wsl-lucas`, `agent-windows-lucas`, y futuros) puedan operar con `encryption.enabled=true` en su `config.yaml` y **leer + responder en DMs encrypted** (megolm) con el operator. Hoy todos corren con `enabled=false` para no colgarse; consecuencia: bot puede ENVIAR a room encrypted (cleartext que Element marca como warning) pero NO LEE replies del operator (megolm cifra, bot no descifra) → chat bidireccional roto.
|
||||
|
||||
Bloquea Flow 0009 DoD ("Element → PC interaction working") en el camino encrypted.
|
||||
|
||||
## Contexto
|
||||
|
||||
- mautrix-go v0.21.1 con cryptohelper (tag `goolm` pure-Go).
|
||||
- Synapse en VPS organic-machine.com con MSC3861/MAS activo (issue 0162 done 2026-05-24).
|
||||
- `encryption_enabled_by_default_for_room_type` activo en Synapse → TODA DM nueva nace con `m.megolm.v1.aes-sha2` (no override client-side).
|
||||
- Bots usan password tokens (no application_service). Tokens emitidos pre-migracion siguen validos (verificado: `/account/whoami` OK con bot token post-MAS).
|
||||
- `verify.sh agent-windows-lucas` corrio OK: genero crypto.db, upload cross-signing keys, escribio `SSSS_RECOVERY_KEY_AGENT_WINDOWS_LUCAS` en `.env`.
|
||||
|
||||
## Reproduccion
|
||||
|
||||
```bash
|
||||
# En VPS, agent-windows-lucas:
|
||||
sudo sed -i 's/enabled: false/enabled: true/' agents/agent-windows-lucas/config.yaml
|
||||
sudo systemctl restart agents_and_robots
|
||||
sleep 30
|
||||
# Bot stuck:
|
||||
sudo tail logs/agent-windows-lucas/2026-05-24.jsonl
|
||||
# Last line forever: "initializing e2ee" — runner nunca llega a "starting matrix sync"
|
||||
# /agents API endpoint reports running=false
|
||||
```
|
||||
|
||||
## Diagnostico actual (incompleto)
|
||||
|
||||
SIGQUIT al proceso launcher revelo bots NO-encrypted en `Listener.Run → SyncWithContext` (normal). NO se pudo aislar la stack de **windows-lucas** durante hang — necesita pprof targeted o log adicional dentro de `InitCrypto`.
|
||||
|
||||
Hipotesis (ordenadas):
|
||||
|
||||
| ID | Hipotesis | Evidencia que la apoya | Como confirmar |
|
||||
|---|---|---|---|
|
||||
| H1 | `cryptohelper.Init()` bloquea en primer `/keys/device_signing/upload` por UIA — MAS no acepta el formato auth heredado | MAS recien activo, password_config disabled, mautrix-go usa UIA password flow | inyectar log antes/despues de cada llamada en `cryptohelper.Init` |
|
||||
| H2 | `cryptohelper.Init()` bloquea en `OlmMachine.Load` por `crypto.db` schema mismatch | crypto.db generado por `cmd/verify` puede tener schema distinto al que cryptohelper espera | reset crypto.db + dejar que cryptohelper bootstrap solo (sin verify.sh) |
|
||||
| H3 | El listener trata de hacer initial sync ANTES de e2ee init terminar, deadlock en mutex | "starting matrix sync" NUNCA aparece post-`initializing e2ee` | revisar order en `devagents/runtime.go` |
|
||||
| H4 | Pickle key mismatch entre verify.sh (lo recibe en hex) y runtime (lo decodifica diferente) | Provision-script genero base64; nosotros pusimos hex; runtime acepta hex? | log de pickle key length en runtime |
|
||||
|
||||
## Tareas
|
||||
|
||||
### Fase 1 — Diagnostico
|
||||
|
||||
1.1. Inyectar logging EN `shell/matrix/client.go::InitCrypto` antes/despues de cada paso (cryptohelper construct, Init, OlmMachine.Load, etc) para identificar la linea que bloquea.
|
||||
|
||||
1.2. Reproducir hang en agent test aislado (`agent-e2ee-test`):
|
||||
- Crear bot fresh con provision-agent-user.sh
|
||||
- Activar encryption=true
|
||||
- Restart launcher
|
||||
- Capturar stack
|
||||
|
||||
1.3. Con stack identificado, decidir cual hipotesis (H1-H4) aplica.
|
||||
|
||||
### Fase 2 — Fix segun hipotesis
|
||||
|
||||
- **Si H1 (MAS UIA)**: investigar si mautrix-go v0.21.1 soporta MSC3861 UIA. Si no: bump a v0.22+ que soporta o usar `device_signing/upload` con SSSS-protected path.
|
||||
- **Si H2 (schema mismatch)**: dejar cryptohelper bootstrap solo, NO usar verify.sh primero. Verify.sh queda como "post-bootstrap repair".
|
||||
- **Si H3 (sync deadlock)**: refactor `devagents/runtime.go` para que e2ee init complete antes de spawn listener.
|
||||
- **Si H4 (pickle key)**: arreglar provision-agent-user.sh para generar pickle key como hex.
|
||||
|
||||
### Fase 3 — Validacion (DoD triada)
|
||||
|
||||
#### Mecanica
|
||||
- Bot con `encryption.enabled=true` start OK (running=true en /agents API).
|
||||
- No hang en logs (paso de "initializing e2ee" → "starting matrix sync" en < 30s).
|
||||
- Build limpio `go build -tags goolm`.
|
||||
|
||||
#### Cobertura
|
||||
|
||||
| Escenario | Cmd / evidencia | Resultado |
|
||||
|---|---|---|
|
||||
| Golden: operator envia mensaje encrypted en DM, bot lee + responde encrypted | Element web → `#agent-windows-lucas` DM → "hola" | bot responde en < 15s, log muestra decrypted msg + claude_code_response + encrypted send |
|
||||
| Edge: bot reinicia, crypto.db persiste, re-key OK | `sudo systemctl restart agents_and_robots` mid-conversation | bot continua descifrando mensajes anteriores + nuevos sin re-bootstrap |
|
||||
| Edge: operator reverify device | Element → device list → forget device → re-verify | bot detecta cambio, sigue cifrando OK |
|
||||
| Error: crypto.db corrupto | `rm crypto.db` mid-run | bot detecta + auto-recovery (per `docs/e2ee.md`) + re-bootstrap < 60s |
|
||||
| Error: token revoked | revocar via admin API | bot logout limpio + restart picks up nuevo token |
|
||||
|
||||
#### Vida util validada (7 dias)
|
||||
|
||||
| Metrica | Umbral | Donde | Ventana |
|
||||
|---|---|---|---|
|
||||
| Bot uptime con encryption=true | `> 99%` | `/agents/<id>` API | 7 dias |
|
||||
| Mensajes encrypted leidos | `>= 10` real conversation | `logs/agent-*/...jsonl` decrypted lines | 7 dias |
|
||||
| Crashes cryptohelper | `0` | journalctl `agents_and_robots` | 7 dias |
|
||||
| Latency decrypt msg | `p95 < 2s` | log timestamps | 7 dias |
|
||||
|
||||
### Anti-criterios
|
||||
|
||||
- NO marcar done si bot solo escribe pero no lee.
|
||||
- NO marcar done si hang reaparece tras reinicio del servicio.
|
||||
- NO marcar done si solo funciona en 1 bot (debe replicarse: wsl-lucas + windows-lucas + 1 mas).
|
||||
|
||||
## Estado actual workaround
|
||||
|
||||
- `agent-wsl-lucas`: `encryption.enabled=false`. DM con operator es UNencrypted (probablemente porque fue creada antes de Synapse activar default-encrypt). Funciona bidireccional.
|
||||
- `agent-windows-lucas`: `encryption.enabled=false`. DM con operator (room `!ymFSupZVqYpOWunuHI` o `!qeuqopdkeYHWdAfMaN`) es ENCRYPTED (Synapse forced). Bot envia clear-text → operator ve mensaje + warning. Operator reply encrypted → bot NO lee.
|
||||
|
||||
## Funciones del registry candidatas (post-fix)
|
||||
|
||||
- `mautrix_cryptohelper_init_with_timeout_go_infra` — wrapper con context.WithTimeout para evitar hang infinito.
|
||||
- `agent_e2ee_bootstrap_bash_pipelines` — pipeline: provision agent → set encryption=true → verify.sh → restart + wait healthy.
|
||||
|
||||
## Notas
|
||||
|
||||
**Pickle key format bug**: `provision-agent-user.sh` genera base64 (`openssl rand -base64 32`). `cmd/verify` espera hex. Fix in scope de este issue o nuevo issue (`0165-provision-pickle-key-hex.md`).
|
||||
|
||||
**Subagent investigation report** (2026-05-24) confirmo:
|
||||
- E2EE machinery YA existe end-to-end (InitCrypto, FetchCrossSigningKeys, SignOwnDevice, verify.sh).
|
||||
- docs/e2ee.md cubre failure modes conocidos.
|
||||
- mautrix-go v0.21.1 puede tener bug pre-MSC3861-aware con MAS.
|
||||
|
||||
**Pendiente upstream check**: mautrix-go release notes v0.22+ para MSC3861 support. Si esta soportado, bump version es probablemente el fix.
|
||||
|
||||
## Capability growth log
|
||||
|
||||
- v0.1.0 (2026-05-24) — issue creado tras reproducir hang post-MAS migration con verify.sh OK pero cryptohelper.Init aun cuelga.
|
||||
Reference in New Issue
Block a user