alvis/AgapHost
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Update Matrix docs: bootstrap order, gotchas, verification details

alvis
2026-03-19 11:05:23 +00:00
parent f0c3a0f7a3
commit 103f7bb958
1 changed files with 17 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
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: Both bots bootstrap cross-signing keys on first startup:
1. Generate master, self-signing, and user-signing olm key pairs 1. Upload device keys to homeserver (`keys_upload`)
2. Upload via `keys/device_signing/upload` with UIAA password auth 2. Generate master, self-signing, and user-signing olm key pairs
3. Self-sign the device key via `keys/signatures/upload` 3. Upload via `keys/device_signing/upload` with UIAA password auth
4. Persist key material to `/data/{bot,zabbix}/cross_signing.json` 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. On subsequent starts, keys are loaded from the persisted file — no regeneration.
@@ -56,10 +59,19 @@ Element X Bot
├─ 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. 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. 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 ### Environment
Variables in `~/matrixbot/.env`, passed through `docker-compose.yml`: Variables in `~/matrixbot/.env`, passed through `docker-compose.yml`: