docs: record matrix_e2ee v0.3.0 deploy; fix and rename matrix-e2ee update runbook

- Deploy v0.3.0 (main 216cc99, W1N-180 bot-initiated device verification
  wizard) on hass.windy.lan; backup matrix_e2ee.bak-20260818-v0.2.10
- Fix runbook: tag-only prerequisite (v0.3.0 was untagged), working-tree
  HEAD check, rsync exit-23 note, actual setup log line, post-deploy record
  step, ssh_config.d -F /dev/null gotcha
- Rename runbook matrix-e2e-update.md -> matrix-e2ee-update.md and update
  AGENTS.md/hosts references (domain is matrix_e2ee, double-e)
- Unify matrix_e2ee naming and update version history in
  docs/home-assistant-matrix.md
This commit is contained in:
windyboy
2026-08-18 13:31:15 +08:00
parent 7cedba7f51
commit 079332e082
5 changed files with 216 additions and 187 deletions
+25 -22
View File
@@ -5,9 +5,9 @@ to the self-hosted Matrix homeserver at [`synapse.chans.xyz`](../hosts/synapse.c
Deliberately contains no Matrix passwords, access tokens, or room encryption material.
> **Status (2026-08-15, W1N-139):** the built-in `matrix` integration has been
> **retired** on `hass.windy.lan` and replaced by the custom \*\*\`matrix_e2e\`\*\*
> **retired** on `hass.windy.lan` and replaced by the custom **`matrix_e2ee`**
> integration. The sections below on the built-in integration are kept for
> reference only. See [matrix_e2e](#matrix-e2e-custom-e2e-integration) for the
> reference only. See [matrix_e2ee](#matrix-e2ee-custom-e2e-integration) for the
> active setup and [Device verification (SAS) model](#device-verification-sas-model)
> for how device trust works.
@@ -176,19 +176,19 @@ automation:
message: "It looks like you wrote !testword"
```
## matrix_e2e (custom E2E integration)
## matrix_e2ee (custom E2E integration)
Custom integration [`windyboy/ha-matrix-e2e`](https://github.com/windyboy/ha-matrix-e2e),
release **v0.2.6** (W1N-173/W1N-174), deployed on `hass.windy.lan`
2026-08-16 (upgraded from v0.2.4; v0.2.0 was the first Config Flow release, W1N-154).
Custom integration [`windyboy/ha-matrix-e2ee`](https://github.com/windyboy/ha-matrix-e2ee),
release **v0.3.0** (W1N-180/#32: bot-initiated device verification wizard),
deployed on `hass.windy.lan` 2026-08-18 (upgraded from v0.2.10).
Runs a dedicated bot with a **persistent E2EE device identity**.
- Domain `matrix_e2e`; Config Flow (UI) with YAML import migration, not in HACS. Does **not**
- Domain `matrix_e2ee`; Config Flow (UI) with YAML import migration, not in HACS. Does **not**
override the built-in `matrix` integration.
- Dependencies are declared **explicitly** in `manifest.json` to work around Home
Assistant's `is_installed` dropping the `[e2e]` extra (W1N-140):
`matrix-nio[e2e]==0.26.0` + `vodozemac` + `peewee` + `cachetools` + `atomicwrites`.
- **v0.2.0 migration:** YAML `matrix_e2e:` block was auto-imported into a Config Entry
- **v0.2.0 migration:** YAML `matrix_e2ee:` block was auto-imported into a Config Entry
(`source: import`) on first startup, then removed. All settings now managed via
**Settings → Devices & Services → Matrix E2EE → Configure**.
See [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) for the deployed state.
@@ -205,15 +205,15 @@ Runs a dedicated bot with a **persistent E2EE device identity**.
- `verify_device_by_fingerprint` (`user_id`, `device_id`, `ed25519`; added v0.1.3,
renamed from `verify_device` in v0.1.4; requires exact `ed25519` match)
- Events:
- `matrix_e2e_command` (`room_id`, `sender`, `command`, `args` only —
- `matrix_e2ee_command` (`room_id`, `sender`, `command`, `args` only —
never the raw body)
- `matrix_e2e_error` (codes, no secrets)
- `matrix_e2e_verification` (`stage`, `transaction_id`, `user_id`, `device_id`,
- `matrix_e2ee_error` (codes, no secrets)
- `matrix_e2ee_verification` (`stage`, `transaction_id`, `user_id`, `device_id`,
optional `emojis`, optional `expires_at`; `expires_at` added v0.1.3)
- `matrix_e2e_fingerprint` (`user_id`, `device_id`, `ed25519`, `curve25519`
- `matrix_e2ee_fingerprint` (`user_id`, `device_id`, `ed25519`, `curve25519`
public keys only; added v0.1.3)
- `notify.matrix_e2e` is **not implemented** (upstream deferred) — notifications
must call `matrix_e2e.send_message` (message + room_id).
- `notify.matrix_e2ee` is **not implemented** (upstream deferred) — notifications
must call `matrix_e2ee.send_message` (message + room_id).
- Commands fire Home Assistant events only; the integration never calls
`domain.service` itself. Map commands in automations.
- Encrypted rooms fail-closed on unverified devices.
@@ -223,10 +223,10 @@ Runs a dedicated bot with a **persistent E2EE device identity**.
### Storage & recovery
- `.storage/matrix_e2e_session.json` (`user_id`, `device_id`, `access_token`,
`pickle_key`) and `.storage/matrix_e2e_store/` (Olm/Megolm, device trust,
- `.storage/matrix_e2ee_session.json` (`user_id`, `device_id`, `access_token`,
`pickle_key`) and `.storage/matrix_e2ee_store/` (Olm/Megolm, device trust,
sync token). Both stay on the HA persistent volume and are in HA backups.
- Soft logout → `matrix_e2e.reauthenticate` (keeps `device_id` + crypto store;
- Soft logout → `matrix_e2ee.reauthenticate` (keeps `device_id` + crypto store;
rejected outside soft-logout state since v0.1.3).
- Hard logout / store loss → delete session + store, restart with password, re-SAS
(a **new device**; old history not decryptable).
@@ -240,7 +240,8 @@ matrix-nio [examples](https://matrix-nio.readthedocs.io/en/latest/examples.html)
[element-android#6832](https://github.com/vector-im/element-android/issues/6832),
Element [device-verification](https://element.io/features/device-verification).
`matrix_e2e` supports two verification paths:
`matrix_e2ee` supports three verification paths (the v0.3.0 wizard automates
the bot-initiated flow):
### 1. SAS (mutual, manual confirmation since v0.1.4)
@@ -256,7 +257,7 @@ Element [device-verification](https://element.io/features/device-verification).
- Element's "Verify" button only starts **in-DM user verification**; it has no
"verify a specific device of another user via to-device" flow (matrix.org
recommends hiding per-device verification for other users).
- `matrix_e2e` implements **raw to-device device SAS** (`start_verification`/
- `matrix_e2ee` implements **raw to-device device SAS** (`start_verification`/
`confirm_verification`), **no cross-signing / in-room**. This is a non-standard
cross-user path: works with matrix-nio + Element Web/Desktop (reported in
element-android#6832), **not** on Element Android/X.
@@ -282,16 +283,18 @@ Element [device-verification](https://element.io/features/device-verification).
`_max_age` 5 min); `_repair_dropped_start()` recovers SAS `start` events nio
dropped when the peer device was unknown (W1N-170/W1N-172);
`VERIFICATION_TIMEOUT_SECONDS` 600→240 (fires before nio's `_max_age`).
- **v0.2.11**: `receive_mac_event` no longer overrides canceled state (W1N-179/#31).
- **v0.3.0**: bot-initiated device verification wizard (W1N-180/#32).
- Inbound SAS is gated to `allowed_users` (v0.1.3).
### 2. One-sided fingerprint (added v0.1.3, hardened v0.1.4)
- Call `matrix_e2e.get_fingerprint` to get the bot's own `ed25519` device key
(read it from the `matrix_e2e_fingerprint` event).
- Call `matrix_e2ee.get_fingerprint` to get the bot's own `ed25519` device key
(read it from the `matrix_e2ee_fingerprint` event).
- In Element, open the bot user's sessions and use "Manually verify by text".
Compare the session key with the fingerprint.
- To trust another device from the bot's side, call
`matrix_e2e.verify_device_by_fingerprint` with the peer's `user_id`, `device_id`,
`matrix_e2ee.verify_device_by_fingerprint` with the peer's `user_id`, `device_id`,
and `ed25519` key. The match is exact (since v0.1.4's rename from `verify_device`).
Feed the **peer** key, not the bot's own key.
- This trusts from one side only; the peer still trusts the bot independently.