From 103f7bb9586f325132c41d161b00472f6072fd3c Mon Sep 17 00:00:00 2001 From: alvis Date: Thu, 19 Mar 2026 11:05:23 +0000 Subject: [PATCH] Update Matrix docs: bootstrap order, gotchas, verification details --- Matrix.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/Matrix.md b/Matrix.md index 0c436d7..c1647a3 100644 --- a/Matrix.md +++ b/Matrix.md @@ -31,10 +31,13 @@ FastAPI service (port 3002) running two matrix-nio E2EE clients: 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` +1. Upload device keys to homeserver (`keys_upload`) +2. Generate master, self-signing, and user-signing olm key pairs +3. Upload via `keys/device_signing/upload` with UIAA password auth +4. Self-sign the device key via `keys/signatures/upload` +5. Persist key material to `/data/{adolf,zabbix}/cross_signing.json` + +Device keys must be uploaded before cross-signing — otherwise the server doesn't know the device and self-signing fails. On subsequent starts, keys are loaded from the persisted file — no regeneration. @@ -56,10 +59,19 @@ Element X Bot ├─ 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. +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 (green verified star). + +Outgoing verification events must NOT contain `transaction_id` (that field is for to-device only) — only `m.relates_to` with `rel_type: m.reference`. To-device verification is also handled as a fallback. +### Gotchas + +- **Device key upload before cross-signing**: `keys_upload()` must run before `bootstrap_cross_signing()`, otherwise the server can't find the device for self-signing. +- **Store corruption on copy**: Never copy olm store directories while the bot is running — the olm identity keys will diverge from what the server has. If you need to rename the store directory, stop the container first. +- **Changing device ID**: If you change the device ID, you must: get a new access token (login with new device_id), clear the store, delete the old device from the server, and re-bootstrap cross-signing. Element X caches device keys aggressively — a new device ID forces a fresh key fetch. +- **`transaction_id` in room events**: nio's `accept_verification()`, `share_key()`, `get_mac()` return `ToDeviceMessage` objects whose `.content` includes `transaction_id`. Strip it before sending as a room event — Element X may ignore events with this field. + ### Environment Variables in `~/matrixbot/.env`, passed through `docker-compose.yml`: