From 03778fa7594016fed068962d7145167ab0d399a4 Mon Sep 17 00:00:00 2001
From: alvis <allogn@gmail.com>
Date: Thu, 19 Mar 2026 09:52:42 +0000
Subject: [PATCH] Add Matrix wiki page, update index

---
 Home.md   |   1 +
 Matrix.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+)
 create mode 100644 Matrix.md

diff --git a/Home.md b/Home.md
index daacaf3..f062064 100644
--- a/Home.md
+++ b/Home.md
@@ -20,6 +20,7 @@
 - [[Omo]] — AI coding agent (oh-my-opencode, local LLM via Bifrost)
 - [[Vaultwarden]] — Password manager (Bitwarden-compatible)
 - [[Seafile]] — File sync and document editing
+- [[Matrix]] — Synapse homeserver, E2EE bot adapter (Adolf + Zabbix)
 
 ## Quick Start
 
diff --git a/Matrix.md b/Matrix.md
new file mode 100644
index 0000000..57c5cf4
--- /dev/null
+++ b/Matrix.md
@@ -0,0 +1,106 @@
+# Matrix
+
+Self-hosted Matrix homeserver (Synapse) with an E2EE bot adapter serving as the bridge between Adolf/Zabbix and Matrix rooms.
+
+## Synapse
+
+Homeserver: `mtx.alogins.net` (Caddy → Synapse container port 8008)
+
+Compose directory: `agap_git/matrix/`
+
+## Matrix Bot
+
+Repo: `~/matrixbot/` — `http://localhost:3000/alvis/matrixbot` (if pushed)
+
+FastAPI service (port 3002) running two matrix-nio E2EE clients:
+
+| Account | Device ID | Purpose |
+|---------|-----------|---------|
+| `@bot:mtx.alogins.net` | `BOTDEVICE` | Adolf channel adapter — inbound (forwards to deepagents) and outbound |
+| `@zabbix:mtx.alogins.net` | `ZABBIXDEVICE` | Zabbix notifications — outbound only |
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/send` | Send message as `@bot` — body: `{"room_id": "...", "text": "..."}` |
+| `POST` | `/zabbix/send` | Send message as `@zabbix` — body: `{"room_id": "...", "text": "..."}` |
+| `GET` | `/health` | Health check |
+
+### E2EE and Cross-Signing
+
+Both bots bootstrap cross-signing keys on first startup:
+
+1. Generate master, self-signing, and user-signing olm key pairs
+2. Upload via `keys/device_signing/upload` with UIAA password auth
+3. Self-sign the device key via `keys/signatures/upload`
+4. Persist key material to `/data/{bot,zabbix}/cross_signing.json`
+
+On subsequent starts, keys are loaded from the persisted file — no regeneration.
+
+### In-Room SAS Verification
+
+Both bots support interactive emoji verification initiated from Element X. The full flow:
+
+```
+Element X                       Bot
+    ├─ m.key.verification.request ─→
+    ←─ m.key.verification.ready ───┤
+    ├─ m.key.verification.start ──→
+    ←─ m.key.verification.accept ──┤
+    ├─ m.key.verification.key ────→
+    ←─ m.key.verification.key ─────┤
+    ←─ m.key.verification.mac ─────┤
+    ├─ m.key.verification.mac ────→
+    ←─ m.key.verification.done ────┤
+    ├─ m.key.verification.done ───→
+```
+
+The bot auto-accepts emoji matches. Master cross-signing key is included in the MAC so Element X can establish the cross-signing trust chain.
+
+To-device verification is also handled as a fallback.
+
+### Environment
+
+Variables in `~/matrixbot/.env`, passed through `docker-compose.yml`:
+
+| Variable | Description |
+|----------|-------------|
+| `MATRIX_HOMESERVER` | Synapse URL (internal: `http://synapse:8008`) |
+| `MATRIX_BOT_TOKEN` | `@bot` access token |
+| `MATRIX_BOT_PASSWORD` | `@bot` password (for UIAA during cross-signing) |
+| `MATRIX_BOT_DEVICE_ID` | `BOTDEVICE` |
+| `MATRIX_ZABBIX_TOKEN` | `@zabbix` access token |
+| `MATRIX_ZABBIX_PASSWORD` | `@zabbix` password |
+| `MATRIX_ZABBIX_DEVICE_ID` | `ZABBIXDEVICE` |
+| `DEEPAGENTS_URL` | Adolf deepagents endpoint (`http://host.docker.internal:8000`) |
+
+Tokens and passwords stored in Vaultwarden: `MATRIX_BOT_TOKEN`, `MATRIX_BOT_PASSWORD`, `MATRIX_ZABBIX_TOKEN`, `MATRIX_ZABBIX_PASSWORD`.
+
+### Stack
+
+```
+~/matrixbot/
+├── bot.py                 Single-file bot (FastAPI + matrix-nio)
+├── docker-compose.yml     Service definition, networks: matrix_frontend, zabbix_frontend
+├── Dockerfile             python:3.12-slim + libolm-dev
+├── requirements.txt       matrix-nio[e2e]==0.25.2, fastapi, uvicorn, httpx, pydantic
+├── .env                   Tokens and passwords
+└── data/                  Persisted state (olm sessions, cross-signing keys)
+    ├── bot/
+    └── zabbix/
+```
+
+### Start
+
+```bash
+cd ~/matrixbot
+docker compose up -d --build
+```
+
+### Networks
+
+The container joins two external Docker networks:
+
+- `matrix_frontend` — access to Synapse container
+- `zabbix_frontend` — allows Zabbix media type to reach `/zabbix/send`