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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user