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
2026-08-18 13:31:15 +08:00
parent 343c5db415
commit 7cedba7f51
4 changed files with 303 additions and 0 deletions
@@ -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) |
@@ -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: <https://www.home-assistant.io/integrations/matrix>
@@ -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):**
@@ -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 <cmd>'`
+
+## 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<OLD_VERSION>'
+```
+
+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": "<NEW_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-<DATE>-v<OLD_VERSION> \
+     /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 <slug>`.
+
+## 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