type: agent name: Federation Broker slug: federation-broker status: active (MVP, awaiting Desktop integration) readiness_pct: 50 created: 2026-05-10 last_updated: 2026-05-10

Federation Broker — VPS↔Desktop handoff WebSocket

Що це

Заміна файлових папок outbox-to-desktop/ і inbox-from-desktop/ на двосторонній WebSocket-канал з ed25519-підписами повідомлень.

Стан

✅ MVP на VPS працює (Etap 1+2+3 з federation-upgrade-plan) ✅ Desktop integration done 2026-05-10 (Etap 3) — Desktop SessionStart hook переключено на broker-first з file-based fallback ✅ Bridge service federation-bridge.service — пересилає push'и у Telegram-чат VPS Claude (безшовна push-комунікація, 2026-05-11)

Стек

Broker: Python websockets 16.0 + sqlite3 для черги + pynacl для ed25519
Auth: shared_secret для початкового handshake + ed25519 signature на кожне повідомлення
Protocol: JSON-over-WebSocket (cmd: auth/send/poll/ack/subscribe)
Endpoint (зараз): ws://127.0.0.1:8091 (local-only)
Endpoint (план): wss://federation.deltamedicalservices.online після NS handoff і Caddy

Файлова структура

/srv/services/federation-broker/
├── broker.py            # WS-сервер
├── client.py            # SDK + CLI (для VPS і Desktop)
├── bridge.py            # Push-listener що пересилає у Telegram VPS-чат
├── messages.sqlite      # черга повідомлень
└── .venv/               # websockets + pynacl

/etc/systemd/system/federation-broker.service
/etc/systemd/system/federation-bridge.service

/srv/passepartout/federation/
├── shared-secret.txt          # 32-byte random, chmod 600
├── vps-claude.signing.key     # ed25519 SK для VPS Claude
└── desktop-claude.signing.key # ed25519 SK для Desktop Claude (буде після onboarding)

Протокол

client ──auth──> broker        # перший handshake
client ──send─→ broker         # надіслати msg (broker верифікує signature)
broker ──push──> client        # live push підписаному отримувачу
client ──poll──> broker        # витягти непрочитані
client ──ack───> broker        # підтвердити отримання → marked acked у sqlite

CLI (для VPS, для Desktop — той же файл)

# Send
python client.py send --from-id vps-claude --to desktop-claude --topic test --body "Привіт"

# Poll
python client.py poll --from-id vps-claude

# Listen (live)
python client.py listen --from-id vps-claude

# Ack
python client.py ack --from-id vps-claude --msg-id <uuid>

Smoke test

✅ Loopback test (vps-claude → vps-claude): send 200ms, poll returns msg with verified signature

Migration plan

✅ MVP broker live на VPS
⏳ Desktop онбординг через outbox handoff (2026-05-10T184500Z-federation-broker-desktop-onboarding.md)
⏳ Перші handoff'и через broker паралельно з file-based outbox/inbox
⏳ 2 тижні fallback period (за рішенням Сергія 2026-05-10)
⏳ Deprecate file-based outbox/inbox
⏳ Migrate to public domain (federation.deltamedicalservices.online) після NS handoff

Open TODOs

[ ] Caddy reverse-proxy + mTLS після Cloudflare DNS handoff
[ ] Health endpoint для Watchdog
[ ] Slash-команда /fed-push у Telegram-боті
[ ] Sentry / Telegram-alert при broker downtime
[ ] Migration tooling outbox→broker для існуючих handoff'ів

Цитати з обговорення

Сергій 2026-05-10: «по Federation робимо послідовно [після SPARC]» (3802)
Сергій 2026-05-10: «по домену теж поки [self-signed CA + 127.0.0.1]» (3803)
Сергій 2026-05-10: «по handoff пишемо і в Telegram також» (3804)
Сергій 2026-05-10: «нового каналу Federation, залишаємо паралельно на два тижні, потім розберемось» (3812)