From 7cedba7f51c9b1c5404e8c90db330bb3cc07e10c Mon Sep 17 00:00:00 2001 From: windyboy Date: Sun, 16 Aug 2026 20:34:38 +0800 Subject: [PATCH] docs: rename integration name from matrix_e2ee to matrix_e2e - Rename runbook: matrix-e2ee-update.md -> matrix-e2e-update.md - Update all references in AGENTS.md, hass.windy.lan.md, home-assistant-matrix.md to use the short name matrix_e2e - The code domain stays matrix_e2ee (E2EE) in source; all doc prose and command references now use matrix_e2e --- AGENTS.md | 1 + docs/home-assistant-matrix.md | 134 ++++++++++++++++++++++++++++++++++ hosts/hass.windy.lan.md | 42 +++++++++++ runbooks/matrix-e2e-update.md | 126 ++++++++++++++++++++++++++++++++ 4 files changed, 303 insertions(+) create mode 100644 runbooks/matrix-e2e-update.md diff --git a/AGENTS.md b/AGENTS.md index 34dc30f..3b5e481 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,6 +83,7 @@ not maintain a second copy of the machine table here. | RustDesk health (hk2) | [runbooks/rustdesk-health.md](runbooks/rustdesk-health.md) | | AdGuard Home health | [runbooks/adguard-home-health.md](runbooks/adguard-home-health.md) | | Home Assistant maintenance | [runbooks/home-assistant-maintenance.md](runbooks/home-assistant-maintenance.md) + [scripts/ha-maintenance.sh](runbooks/scripts/ha-maintenance.sh) | +| matrix_e2e update (hass.windy.lan) | [runbooks/matrix-e2e-update.md](runbooks/matrix-e2e-update.md) | | Matrix upstream refs | [docs/matrix-upstream.md](docs/matrix-upstream.md) | | Hermes Agent Matrix channel | [docs/hermes-matrix.md](docs/hermes-matrix.md) | | UniFi local-service proxy bypass | [docs/unifi-openclash-localhost.md](docs/unifi-openclash-localhost.md) | diff --git a/docs/home-assistant-matrix.md b/docs/home-assistant-matrix.md index 19684bc..cd749d3 100644 --- a/docs/home-assistant-matrix.md +++ b/docs/home-assistant-matrix.md @@ -4,6 +4,13 @@ Reference for wiring the Home Assistant [Matrix integration](https://www.home-as to the self-hosted Matrix homeserver at [`synapse.chans.xyz`](../hosts/synapse.chans.xyz.md). 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\`\*\* +> integration. The sections below on the built-in integration are kept for +> reference only. See [matrix_e2e](#matrix-e2e-custom-e2e-integration) for the +> active setup and [Device verification (SAS) model](#device-verification-sas-model) +> for how device trust works. + ## Purpose The integration lets Home Assistant send messages to Matrix rooms and react to @@ -169,6 +176,133 @@ automation: message: "It looks like you wrote !testword" ``` +## matrix_e2e (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). +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** + 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 + (`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. + +### Services & events + +- Services (all admin-only since v0.1.4): + - `send_message` (`message`, `room_id`) + - `start_verification` (`user_id`, `device_id`) + - `confirm_verification` (`transaction_id`) + - `cancel_verification` (`transaction_id`) + - `reauthenticate` (`password`) — soft-logout only + - `get_fingerprint` (no fields; returns bot's own `ed25519`/`curve25519` keys; added v0.1.3) + - `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 — + never the raw body) + - `matrix_e2e_error` (codes, no secrets) + - `matrix_e2e_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` — + 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). +- Commands fire Home Assistant events only; the integration never calls + `domain.service` itself. Map commands in automations. +- Encrypted rooms fail-closed on unverified devices. +- Since v0.1.4: `start_verification`, `confirm_verification`, `cancel_verification`, + `verify_device_by_fingerprint`, and `reauthenticate` are enforced as HA admin-only + via `async_register_admin_service`; non-admin users cannot call them. + +### Storage & recovery + +- `.storage/matrix_e2e_session.json` (`user_id`, `device_id`, `access_token`, + `pickle_key`) and `.storage/matrix_e2e_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; + 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). + +## Device verification (SAS + fingerprint) model + +Researched 2026-08-15 (W1N-139 stage-6 pre-study), updated for v0.1.3/v0.1.4. +Sources: matrix.org +[cross-signing guide](https://matrix.org/docs/guides/implementing-more-advanced-e-2-ee-features-such-as-cross-signing/), +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: + +### 1. SAS (mutual, manual confirmation since v0.1.4) + +- SAS is device-to-device: exchange ephemeral keys → derive emojis → **a human on + each side compares and confirms** (`m.key.verification.mac`). +- Matrix distinguishes two cases (spec uses *should*, not *must*): + - **same user, two devices** → to-device messages (SAS); + - **two different users** → **in-room (DM) messages**, verifying the *user* + (cross-signing master key), not a specific device. +- Cross-signing: each user has master / self-signing / user-signing keys. A device + looks "verified" to another user via the chain + `my master → my user-signing → their master → their self-signing → their device`. +- 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`/ + `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. +- **v0.1.3**: inbound SAS auto-complete was added; SAS events include `expires_at`. +- **v0.1.4 (breaking)**: auto-confirm was removed. **Every** device — including + another device of the bot's own account — requires explicit `confirm_verification` + after emoji comparison. Only the bot's own account or users in `allowed_users` + may initiate SAS (`verification_peer_denied` otherwise). +- **v0.2.1**: storage I/O moved off the event loop (`asyncio.to_thread`, + W1N-167); own-keys query on startup so inbound SAS can build a session (W1N-166). +- **v0.2.2** (not deployed): intermediate version. +- **v0.2.3**: sync loop runs as a background task (fixes bootstrap setup timeout, + W1N-168); SAS double-send of key and MAC fixed (W1N-169). +- **v0.2.6**: `_log_verification_state()` tracks SAS state transitions with + `async_write_ha_state` for diagnosis (W1N-174); + `_bridge_verification_request()` handles inbound + `m.key.verification.request` → `m.key.verification.ready` since nio lacks a + `request` framework (W1N-173). +- **v0.2.5**: bridge `m.key.verification.request` → `ready` (nio lacks + request framework, W1N-173). +- **v0.2.4**: `_patch_nio_sas_timeout()` works around nio 0.26.0 + `_last_event_time` bug (SAS timed out at 60s regardless of activity — now uses + `_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`). +- 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). +- 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`, + 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. +- Both `get_fingerprint` and `verify_device_by_fingerprint` are HA admin-only. + +### Consequence + +Whether `@zhiqiang`'s device can be verified depends on which Element client +they use. Open options recorded in W1N-139 (A: Web SAS test; B: upstream +in-room/cross-signing; C: unencrypted-room downgrade). + ## References - Home Assistant Matrix integration: diff --git a/hosts/hass.windy.lan.md b/hosts/hass.windy.lan.md index 9ac5d89..312e18c 100644 --- a/hosts/hass.windy.lan.md +++ b/hosts/hass.windy.lan.md @@ -111,6 +111,7 @@ getent hosts hass.windy.lan ## Local patches (custom components) + ### Manual custom-component install (this host) Home Assistant loads custom integrations from @@ -246,6 +247,47 @@ The `_unrecorded_attributes` mechanism exists in Core 2026.8.1 (`Entity.__init_subclass__` → `state_info["unrecorded_attributes"]`, consumed by recorder `shared_attrs_bytes_from_event`). + +### `matrix_e2e` live tree (E2E Matrix bot, verified 2026-08-16, W1N-175) + +**v0.2.7** (W1N-176: SAS cancel code/reason logging for diagnosis): +source copy from `/home/windy/project/ha-matrix-e2e` (development clone) deployed +2026-08-16 via SSH rsync from workstation (upgraded from v0.2.6). Custom **`matrix_e2e`** integration — **Config Flow** +(UI). See [docs/home-assistant-matrix.md](../docs/home-assistant-matrix.md). +**Update runbook:** [runbooks/matrix-e2e-update.md](../runbooks/matrix-e2e-update.md). + +- Bot `@hass:chans.xyz` reused (E2EE device `rO1R915ncu`). v0.2.0 YAML import + migrated existing config into a **Config Entry** (`source: import`), then the + YAML block was removed from `configuration.yaml`. All settings now managed via + **Settings → Devices & Services → Matrix E2EE → Configure**. +- Config Entry options: `allowed_rooms` `["!gidvAzpDzwtzfEDrqu:chans.xyz", "!boxfylDSzOvrWkcsyY:chans.xyz"]`, + `allowed_users` `["@zhiqiang:chans.xyz"]`, `command_prefix` `"!"`. +- Storage (persistent volume, in HA backups as of upgrade): `/config/.storage/matrix_e2e_session.json` + + `/config/.storage/matrix_e2e_store/`. Config backups: + `/homeassistant/.matrix-e2ee-backups/` (`matrix_e2e.bak-20260816`, + `matrix_e2e.bak-20260816-v0.2.3`, `matrix_e2e.bak-20260816-v0.2.4`); + full HA backup slugs `3d9d36db` (pre-v0.1.4) + `9f223f35` (pre-v0.2.0). +- v0.2.6 changes: `_log_verification_state()` tracks SAS state transitions + with `async_write_ha_state` for diagnosis (W1N-174); `_bridge_verification_request()` + handles inbound `m.key.verification.request` → `m.key.verification.ready` since + nio lacks a `request` framework (W1N-173). +- v0.2.5 changes: bridge `m.key.verification.request` → `ready` (nio lacks + request framework, W1N-173). +- v0.2.4 changes: `_patch_nio_sas_timeout()` workaround for nio 0.26.0 + `_last_event_time` stale-timestamp bug (SAS timed out at 60s regardless of + activity); `_repair_dropped_start()` recovers SAS `start` events nio dropped + when the peer device was unknown; `_query_device_keys()` generalized beyond + own device keys; `VERIFICATION_TIMEOUT_SECONDS` 600→240 (fires before nio's + 5 min `_max_age`). Earlier undocumented deploys: v0.2.3 (W1N-168 sync loop + background task, W1N-169 SAS double-send fix), v0.2.1 (W1N-167 storage I/O + `asyncio.to_thread`, W1N-166 own-keys query). +- Automation `1761188403590`「Matrix 聊天关卫生间灯」unchanged: trigger + `matrix_e2e_command` (command `关卫生间灯`), actions `light.turn_off` + + `matrix_e2e.send_message` (room `!gidvAzpDzwtzfEDrqu`). +- **SAS not yet completed:** every device requires explicit `confirm_verification`. + Encrypted-room commands stay fail-closed until `@zhiqiang`'s device is verified. + Two paths available: SAS manual confirm or fingerprint, see + [docs/home-assistant-matrix.md § Device verification](../docs/home-assistant-matrix.md). ## Known issues **Bluetooth hci0 instability — RTL8821CS (verified 2026-08-13, W1N-74):** diff --git a/runbooks/matrix-e2e-update.md b/runbooks/matrix-e2e-update.md new file mode 100644 index 0000000..a61f941 --- /dev/null +++ b/runbooks/matrix-e2e-update.md @@ -0,0 +1,126 @@ +# matrix_e2e update (hass.windy.lan) + +Update the custom **`matrix_e2e`** integration on `hass.windy.lan`. + +Facts: [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) (see § `matrix_e2e` live tree) +Source: `/home/windy/project/ha-matrix-e2e` (development clone on workstation) +Access: `ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i '` + +## Prerequisites + +- The source repo at `/home/windy/project/ha-matrix-e2e` is on the correct tag/commit. +- The tag exists: `git tag -l 'v*'` shows the target version. +- The remote host is reachable and `sudo -n -i ha core info` succeeds. +- The workstation HTTP proxy does not interfere — LAN hosts must be reachable + without proxying (unset `http_proxy` / `HTTP_PROXY` if needed). + +## Update procedure + +### 1. Backup the live tree + +```bash +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i mkdir -p /homeassistant/.matrix-e2e-backups && + sudo -n -i cp -a /homeassistant/custom_components/matrix_e2e \ + /homeassistant/.matrix-e2e-backups/matrix_e2e.bak-$(date +%Y%m%d)-v' +``` + +The backup lives in `/homeassistant/.matrix-e2e-backups/` — a directory +separated from `custom_components/` to avoid HA scanning it as a custom +component domain. + +### 2. Rsync the new source + +```bash +rsync -a --delete -e 'ssh -o BatchMode=yes' \ + /home/windy/project/ha-matrix-e2e/custom_components/matrix_e2e/ \ + hassio@hass.windy.lan:/homeassistant/custom_components/matrix_e2e/ +``` + +The `--delete` cannot remove Core-owned `__pycache__` — that is handled +in the next step. Source `.py` files and `manifest.json` are transferred +correctly even with the `__pycache__` errors. + +### 3. Wipe `__pycache__` (as root) and restart Core + +```bash +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e/__pycache__ \ + /homeassistant/custom_components/matrix_e2e/*/__pycache__ && + sudo -n -i ha core restart' +``` + +Stale `cpython-314` bytecode in Core-owned `__pycache__` keeps the old +coordinator in memory until restart. Wipe before restart. + +Wait for `Command completed successfully.` (typically 1–2 min). + +### 4. Verify the deployment + +#### 4a. Confirm manifest version + +```bash +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i cat /homeassistant/custom_components/matrix_e2e/manifest.json' +``` + +Expect `"version": ""`. + +#### 4b. Check Core logs for matrix_e2e + +```bash +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i ha core logs -n 2500' | grep -E 'matrix_e2e|Setting up matrix' | head -20 +``` + +Expect: +- `Setting up matrix_e2e` +- `matrix_e2e restored existing device; user=@hass:chans.xyz device=rO1R915ncu` +- No `ERROR` level messages from `custom_components.matrix_e2e` +- The `_patch_nio_sas_timeout` WARNING is expected (known nio workaround) + +> The code domain is `matrix_e2e` (E2EE = End-to-End Encryption), so log +> entries and file paths use `matrix_e2e`. The integration's short name is +> `matrix_e2e`. + +#### 4c. Verify the entry is loaded (optional, via Supervisor API) + +```bash +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i python3 -c " +import os, json, urllib.request +req = urllib.request.Request( + \"http://supervisor/core/api/config/config_entries/entry/\", + headers={\"Authorization\": \"Bearer \" + os.environ[\"SUPERVISOR_TOKEN\"]}, +) +entries = json.loads(urllib.request.urlopen(req, timeout=30).read()) +for e in entries: + if e[\"domain\"] == \"matrix_e2e\": + print(f\"{e[\"domain\"]}: state={e[\"state\"]} source={e[\"source\"]}\") +"' +``` + +Expect `state: loaded`. + +## Rollback + +If Core fails to start after the update: + +```bash +# Restore the backup +ssh -o BatchMode=yes hassio@hass.windy.lan \ + 'sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e && + sudo -n -i cp -a /homeassistant/.matrix-e2e-backups/matrix_e2e.bak--v \ + /homeassistant/custom_components/matrix_e2e && + sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e/__pycache__ && + sudo -n -i ha core restart' +``` + +If a full HA backup exists (pre-update), restore via `ha backups restore `. + +## References + +- [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) — current live version and config +- [docs/home-assistant-matrix.md](../docs/home-assistant-matrix.md) — integration architecture and verification model +- [home-assistant-maintenance.md](home-assistant-maintenance.md) — general HA maintenance procedures +- [ha-matrix-e2e source](https://github.com/windyboy/ha-matrix-e2e) — GitHub repo \ No newline at end of file