egutierrez
daef7ea190
Helper functions (matrix-mas capability group): - mas_client_register_bash_infra: register/sync OAuth clients via mas-cli - mas_syn2mas_migration_bash_infra: dry-run + apply user migration to MAS - synapse_msc3861_enable_go_infra: edit homeserver.yaml MSC3861 block (with diff) - wellknown_oidc_patch_go_infra: patch well-known JSON with msc2965.authentication - synapse_login_flows_check_go_infra: health-check post-migration login flows Flows + issues for custom Matrix clients (PC + Android): - 0010 matrix-client-pc: Wails + React+Mantine (issues 0147-0153) - 0011 matrix-client-android: Kotlin + Compose (issues 0154-0161) - 0162 enable MAS as auth provider (Synapse delegate) — EXECUTED on VPS - 0163 custom admin panel propio (sustituye synapse-admin) Production state (organic-machine.com): - Synapse migrated SQLite -> Postgres - MSC3861 active, password_config disabled - 21 users + 41 access_tokens migrated via syn2mas - 4 MAS clients registered (element, matrix_pc, matrix_android, admin_panel) - synapse-admin container removed + Coolify route deleted - well-known patched with org.matrix.msc2965.authentication Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
158 lines
9.4 KiB
Markdown
158 lines
9.4 KiB
Markdown
---
|
|
name: matrix-client-pc
|
|
id: 0010
|
|
status: pending
|
|
created: 2026-05-24
|
|
updated: 2026-05-24
|
|
priority: high
|
|
risk: medium
|
|
related_issues: [0147, 0148, 0149, 0150, 0151, 0152, 0153, 0162, 0163]
|
|
related_flows: [0009, 0011]
|
|
apps: [matrix_client_pc]
|
|
projects: [element_agents]
|
|
vaults: []
|
|
capability_groups: [matrix-client, livekit-calls, e2ee, widgets]
|
|
trigger: manual
|
|
schedule: ""
|
|
expected_runtime_s: 0
|
|
tags: [matrix, element, wails, react, mantine, livekit, e2ee, widgets, agents]
|
|
---
|
|
|
|
## Goal
|
|
|
|
Cliente Matrix propio para PC (Win/Linux/macOS) construido con Wails (Go backend) + React+Mantine+`@fn_library` frontend. Replica capacidades actuales de Element Web (chat, E2EE, calls LiveKit) y se abre a mejoras propias: mini-webapps embebidas en conversaciones gestionadas por agentes del project `element_agents`, paneles especiales para llamadas, integracion directa con `agents_and_robots` + `agents_dashboard` + `device_agent` + futuro mesh WireGuard (flow 0009).
|
|
|
|
## Pre-requisitos
|
|
|
|
- Synapse + MAS + LiveKit funcionando en `organic-machine.com` (app `element_matrix_chat` ya desplegada, 5+ semanas uptime).
|
|
- `livekit-jwt` container vivo para generar tokens (ver `docker-compose.livekit.yml`).
|
|
- Sygnal push gateway (Synapse) — TBD si no existe, anadir container para push notifs PC + Android.
|
|
- Cuenta Matrix de test (`@dev-pc:matrix-af2f3d.organic-machine.com`) registrada via MAS.
|
|
- Go 1.22+ + Wails CLI v2 instalado (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`).
|
|
- pnpm + Node 20+ (ya en el repo para `frontend/`).
|
|
|
|
## Funciones del registry recomendadas
|
|
|
|
| Rol | Funcion candidata | Estado |
|
|
|---|---|---|
|
|
| Matrix client init (Go) | `matrix_client_init_go_infra` | FALTA: wrapper sobre `mautrix-go` (login MAS OIDC, sync, store SQLite) |
|
|
| LiveKit token gen (Go) | `livekit_token_gen_go_infra` | FALTA: JWT con `livekit-server-sdk-go` |
|
|
| Matrix room subscribe SSE (Go) | `matrix_room_subscribe_go_infra` | FALTA: stream eventos Synapse -> frontend Wails via SSE/IPC |
|
|
| Matrix message send (Go) | `matrix_message_send_go_infra` | FALTA: text + markdown + reply + edit + reaction |
|
|
| Matrix E2EE bootstrap (Go) | `matrix_e2ee_bootstrap_go_infra` | FALTA: cross-signing keys, recovery passphrase |
|
|
| Matrix device verify (Go) | `matrix_device_verify_go_infra` | FALTA: SAS verification flow |
|
|
| LiveKit room hook (TS) | `livekit_room_ts_ui` | FALTA: hook React wrapper sobre `livekit-client` |
|
|
| Widget host iframe (TS) | `widget_host_ts_ui` | FALTA: iframe sandbox + postMessage Matrix Widget API v2 |
|
|
| Matrix timeline hook (TS) | `useMatrixTimeline_ts_ui` | FALTA: hook React con pagination, dedupe, optimistic UI |
|
|
| Markdown render (TS) | reuse existing `markdown_render_ts_ui` si existe, sino crear | check |
|
|
| HTTP client (Go) | `http_json_client_go_infra` | OK (reusar) |
|
|
| SQLite open (Go) | `sqlite_open_go_infra` | OK (reusar) |
|
|
| HTTP server SSE | `http_sse_server_go_infra` | OK (reusar) |
|
|
| Notify (impure) | `notify_desktop_go_infra` | FALTA: Win/Linux/mac notifications nativas |
|
|
|
|
## Apps tocadas
|
|
|
|
- `projects/element_agents/apps/matrix_client_pc` (nueva — Wails + React).
|
|
- `projects/element_agents/apps/element_matrix_chat` (backend ya activo; quiza anadir sygnal container).
|
|
- `projects/element_agents/apps/agents_and_robots` (consumidor — el cliente PC dialoga con agentes via rooms Matrix).
|
|
- `projects/element_agents/apps/agents_dashboard` (referencia UI — algunos paneles se reusan).
|
|
|
|
## Projects relacionados
|
|
|
|
- `element_agents` (root project — agrupa todo).
|
|
|
|
## Vaults / storage
|
|
|
|
- Local del PC: `~/.matrix_client_pc/store.db` (sync state + crypto store SQLite).
|
|
- Cache media: `~/.matrix_client_pc/media/`.
|
|
|
|
## Capability groups consultados
|
|
|
|
- `matrix-client` (a crear: documenta wrappers `mautrix-go`).
|
|
- `livekit-calls` (a crear: token gen + room join + UI calls).
|
|
- `e2ee` (a crear: bootstrap + verification + recovery).
|
|
- `widgets` (a crear: Matrix Widget API v2 host + sandbox + permisos).
|
|
|
|
## Flow
|
|
|
|
Pasos numerados. Cada paso = issue propio (ver `related_issues`).
|
|
|
|
1. **0147 — Scaffold Wails + login MAS.** Crear app `matrix_client_pc/` con Wails init, conectar a Synapse via MAS OIDC, mostrar perfil del usuario logueado. Persistencia tokens en `pass` o keychain del SO.
|
|
2. **0148 — Rooms list + timeline.** Sidebar con rooms (DMs + spaces + grupos), panel central timeline con pagination scroll-up, dedupe, optimistic UI. Reusar layout `AppShell` Mantine.
|
|
3. **0149 — Composer + interacciones.** Composer markdown, replies, edits, reactions, threads, upload media (imagenes, files, voice msg). Drag&drop. Slash commands placeholder.
|
|
4. **0150 — E2EE.** `mautrix-go` con crypto store SQLite. Cross-signing setup, recovery passphrase, SAS verification de devices, key backup. UI para verificar otros usuarios.
|
|
5. **0151 — Calls LiveKit.** Boton call en room -> token JWT desde Go backend -> join LiveKit room -> UI con tiles participantes, mute/cam/screen/hangup. 1:1 + grupales hasta 16 (limite actual del config).
|
|
6. **0152 — Mini-webapps embebidas.** Implementar Matrix Widget API v2: iframe sandbox + postMessage handshake + permisos (capabilities `m.always_on_screen`, `org.matrix.msc2762.send.event`, etc.). Lanzar webapps desde slash command `/widget <url>` o desde state event `m.widget`. Agentes pueden publicar widgets en su room (ej. dashboard de telemetria, formulario, kanban inline).
|
|
7. **0153 — Agent integration.** Paneles especiales para rooms operados por agentes de `agents_and_robots`: timeline + panel lateral con estado del agente (uptime, cola de tasks, last_error). Reusar SSE del `agents_dashboard`.
|
|
|
|
## Acceptance
|
|
|
|
- [ ] App Wails compila y arranca en Win+Linux con binario standalone.
|
|
- [ ] Login MAS OIDC completo, token persistido entre arranques.
|
|
- [ ] Sync incremental con Synapse funciona; reconexion automatica tras red caida.
|
|
- [ ] E2EE: enviar/recibir mensajes cifrados con otro cliente (Element Web o Android).
|
|
- [ ] Call 1:1 con video+audio funcional via LiveKit.
|
|
- [ ] Widget de prueba (HTML estatico servido por `agents_and_robots`) se carga en iframe sandbox y postMessage handshake completa.
|
|
|
|
## Definition of Done
|
|
|
|
### Mecanica (pre-requisito)
|
|
|
|
- `go build -tags wails` verde para Win + Linux.
|
|
- `pnpm build` frontend verde.
|
|
- `fn doctor cpp-apps` no aplica; `fn doctor services` confirma backend Matrix sano.
|
|
- `app.md` con `uses_functions` declarando todas las dependencias del registry.
|
|
|
|
### Cobertura de comportamiento
|
|
|
|
| Escenario | Tipo | Comando / evidencia | Resultado esperado |
|
|
|---|---|---|---|
|
|
| Golden: login + recibir mensaje E2EE | e2e | `e2e/test_login_and_receive.sh` | mensaje aparece en timeline en <2s, descifrado OK |
|
|
| Edge: red cae 30s, vuelve | e2e | `e2e/test_reconnect.sh` | sync se reanuda sin perder mensajes |
|
|
| Edge: 2000 mensajes en 1 room | e2e | `e2e/test_perf_timeline.sh` | scroll a 60fps, memoria <500MB |
|
|
| Edge: device nuevo no verificado envia msg | e2e | `e2e/test_unverified_device.sh` | warning visible en UI, msg cifra a este device solo si user confirma |
|
|
| Error: token MAS expira | e2e | `e2e/test_token_refresh.sh` | refresh automatico, sin logout visible |
|
|
| Error: LiveKit SFU caido | e2e | `e2e/test_livekit_down.sh` | error claro en UI, no crash de la app |
|
|
|
|
### Vida util validada (>=7 dias uso real)
|
|
|
|
| Metrica | Umbral | Donde se observa | Ventana |
|
|
|---|---|---|---|
|
|
| Crashes proceso PC | `0` | `journalctl --user -u matrix_client_pc` (Linux) / Event Viewer (Win) | 7 dias |
|
|
| Latencia send msg | `p95 < 500ms` | panel propio de la app + `call_monitor` | 7 dias |
|
|
| Calls fallidas | `< 5%` | counter en app + logs LiveKit | 7 dias |
|
|
| Uso real diario | `>= 4 dias/semana` | `last_active_at` en store local | 7 dias |
|
|
| Onboarding nuevo usuario | `< 5min hasta primer msg E2EE` | screencast operador | 1 sesion |
|
|
|
|
### Anti-criterios
|
|
|
|
- NO marcar done si E2EE se silent-falla (mensajes no se descifran y la UI no lo dice).
|
|
- NO marcar done si la app solo funciona en `home-wsl` y peta en `aurgi-pc`.
|
|
- NO marcar done si widget host carga `javascript:` URLs (XSS).
|
|
- NO marcar done si calls grupales >3 participantes lagean con audio cortado.
|
|
|
|
## Notas
|
|
|
|
**Onboarding rapido:**
|
|
1. `cd projects/element_agents/apps/matrix_client_pc`
|
|
2. `wails dev` para desarrollo con hot-reload.
|
|
3. `wails build -platform linux/amd64,windows/amd64` para release.
|
|
4. Tokens MAS guardados via `keyring` (Go bindings al keychain del SO).
|
|
5. Para probar E2EE: crear segundo usuario en Synapse Admin, abrir Element Web como segundo cliente, intercambiar verifications.
|
|
|
|
**Camino futuro (post-DoD):**
|
|
- Push notifs nativas via `sygnal` + APNs/FCM-equivalent desktop (Win Action Center, Linux notify-send).
|
|
- Mini-webapp catalog: registry de widgets internos (`projects/element_agents/widgets/`) publicables a rooms con un comando.
|
|
- Threads UI mejorado (vs Element que es plano).
|
|
- Integracion `agents_and_robots`: panel embebido que muestra logs del agente del room actual.
|
|
- Cuando flow 0009 (mesh wireguard) este vivo: este cliente PC habla con `device_agent` de cada PC del mesh via su room Matrix.
|
|
|
|
**Decisiones clave (justificacion en hilo Claude 2026-05-24):**
|
|
- Wails > Tauri: Go es stack principal del registry, reusa funciones existentes, `mautrix-go` es el SDK Matrix mas maduro en Go.
|
|
- React+Vite+Mantine+`@fn_library`: defaults del proyecto, ver `frontend_theming.md`.
|
|
- 2 codebases (PC Wails + Android Kotlin nativo): tradeoff aceptado por calidad nativa Android + reuso Go en PC. Contrato compartido en `docs/client_contract.md` (TBD).
|
|
|
|
## Capability growth log
|
|
|
|
- v0.1.0 (2026-05-24) — baseline (flow creado).
|