timmy-config/infra/matrix/HERMES_INTEGRATION_VERIFICATION.md

# Hermes Matrix Integration Verification Runbook

> **Issue**: [#166](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/166) — Stand up Matrix/Conduit for human-to-fleet encrypted communication  
> **Scaffold**: [#183](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/183)  
> **Decisions**: [#187](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/187)  
> **Created**: 2026-04-05 by Ezra, Archivist  
> **Purpose**: Prove that encrypted operator-to-fleet messaging is technically feasible and exactly one deployment away from live verification.

---

## Executive Summary

The Matrix/Conduit deployment scaffold is complete. What has **not** been widely documented is that the **Hermes gateway already contains a production Matrix platform adapter** (`hermes-agent/gateway/platforms/matrix.py`).

This runbook closes the loop:
1. It maps the existing adapter to #166 acceptance criteria.
2. It provides a step-by-step protocol to verify E2EE operator-to-fleet messaging the moment a Conduit homeserver is live.
3. It includes an executable verification script that can be run against any Matrix homeserver.

**Verdict**: #166 is blocked only by #187 (host/domain/proxy decisions). The integration code is already in repo truth.

---

## 1. Existing Code Reference

The Hermes Matrix adapter is a fully-featured gateway platform implementation:

| File | Lines | Capabilities |
|------|-------|--------------|
| `hermes-agent/gateway/platforms/matrix.py` | ~1,200 | Login (token/password), sync loop, E2EE, typing indicators, replies, threads, edits, media upload (image/audio/file), voice message support |
| `hermes-agent/tests/gateway/test_matrix.py` | — | Unit/integration tests for message send/receive |
| `hermes-agent/tests/gateway/test_matrix_voice.py` | — | Voice message delivery tests |

**Key facts**:
- E2EE is supported via `matrix-nio[e2e]`.
- Megolm session keys are exported on disconnect and re-imported on reconnect.
- Unverified devices are handled with automatic retry logic.
- The adapter supports both access-token and password authentication.

---

## 2. Environment Variables

To activate the Matrix adapter in any Hermes wizard house, set these in the local `.env`:

```bash
# Required
MATRIX_HOMESERVER="https://matrix.timmy.foundation"
MATRIX_USER_ID="@ezra:matrix.timmy.foundation"

# Auth: pick one method
MATRIX_ACCESS_TOKEN="syt_..."
# OR
MATRIX_PASSWORD="<32+ char random string>"

# Optional but recommended
MATRIX_ENCRYPTION="true"
MATRIX_ALLOWED_USERS="@alexander:matrix.timmy.foundation"
MATRIX_HOME_ROOM="!operatorRoomId:matrix.timmy.foundation"
```

---

## 3. Pre-Deployment Verification Script

Run this **before** declaring #166 complete to confirm the adapter can connect, encrypt, and respond.

### Usage

```bash
# On the host running Hermes (e.g., Hermes VPS)
export MATRIX_HOMESERVER="https://matrix.timmy.foundation"
export MATRIX_USER_ID="@ezra:matrix.timmy.foundation"
export MATRIX_ACCESS_TOKEN="syt_..."
export MATRIX_ENCRYPTION="true"

./infra/matrix/scripts/verify-hermes-integration.sh
```

### What It Verifies

1. `matrix-nio` is installed.
2. Required env vars are set.
3. The homeserver is reachable.
4. Login succeeds.
5. The operator room is joined.
6. A test message (`!ping`) is sent.
7. E2EE state is initialized (if enabled).

---

## 4. Manual Verification Protocol (Post-#187)

Once Conduit is deployed and the operator room `#operator-room:matrix.timmy.foundation` exists:

### Step 1: Create Bot Account
```bash
# As Conduit admin
curl -X POST "https://matrix.timmy.foundation/_matrix/client/v3/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"ezra","password":"<random>","type":"m.login.dummy"}'
```

### Step 2: Obtain Access Token
```bash
curl -X POST "https://matrix.timmy.foundation/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@ezra:matrix.timmy.foundation",
    "password": "<random>"
  }'
```

### Step 3: Run Verification Script
```bash
cd /opt/timmy-config
./infra/matrix/scripts/verify-hermes-integration.sh
```

### Step 4: Human Test (Alexander)
1. Open Element Web or native Element app.
2. Log in as `@alexander:matrix.timmy.foundation`.
3. Join `#operator-room:matrix.timmy.foundation`.
4. Send `!ping`.
5. Confirm `@ezra:matrix.timmy.foundation` replies with `Pong`.
6. Verify the room shield icon shows encrypted (🔒).

---

## 5. Acceptance Criteria Mapping

Maps #166 criteria to existing implementations:

| #166 Criterion | Status | Evidence |
|----------------|--------|----------|
| Deploy Conduit homeserver | 🟡 Blocked by #187 | `infra/matrix/` scaffold complete |
| Create fleet rooms/channels | 🟡 Blocked by #187 | `scripts/bootstrap-fleet-rooms.py` ready |
| **Verify encrypted operator-to-fleet messaging** | ✅ **Code exists** | `hermes-agent/gateway/platforms/matrix.py` + this runbook |
| Alexander can message the fleet over Matrix | 🟡 Pending live server | Adapter supports command routing; `HERMES_MATRIX_CLIENT_SPEC.md` defines command vocabulary |
| Telegram is no longer the only command surface | 🟡 Pending cutover | `CUTOVER_PLAN.md` ready |

---

## 6. Accountability

| Task | Owner | Evidence |
|------|-------|----------|
| Conduit deployment | @allegro / @timmy | Close #187, run `deploy-matrix.sh` |
| Bot account provisioning | @ezra | This runbook §1–4 |
| Integration verification | @ezra | `verify-hermes-integration.sh` |
| Human E2EE test | @rockachopa | Element client + operator room |
| Telegram cutover | @ezra | `CUTOVER_PLAN.md` |

---

## 7. Risk Mitigation

| Risk | Mitigation |
|------|------------|
| `matrix-nio[e2e]` not installed | Verification script checks this and exits with install command |
| E2EE key import fails | Adapter falls back to plain text; verification script warns |
| Homeserver federation issues | Protocol uses direct client-server API, not federation |
| Bot cannot join encrypted room | Ensure bot is invited *before* encryption is enabled, or use admin API to force-join |

---

*Last updated: 2026-04-05 by Ezra, Archivist*