669 lines
29 KiB
Markdown
669 lines
29 KiB
Markdown
# QR Sign-In via Matrix Authentication Service — Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Enable "sign in with QR code" (MSC4108) for Matrix accounts on hobbs.farm, which requires deploying Matrix Authentication Service (MAS) as the homeserver's auth provider.
|
||
|
||
**Architecture:** QR sign-in is an OAuth 2.0 device grant, not a password login. Synapse 1.159.0 refuses to start with `msc4108_enabled: true` unless `matrix_authentication_service.enabled` is also true. MAS requires PostgreSQL, and — critically — **`syn2mas` can only read a Synapse whose own database is PostgreSQL**. Synapse here is on SQLite, so this is a three-stage chain: port Synapse to PostgreSQL, deploy MAS and migrate the accounts into it, then turn on the QR MSCs.
|
||
|
||
**Tech Stack:** Synapse 1.159.0 (SQLite → PostgreSQL 16), Matrix Authentication Service (Docker, ghcr.io/element-hq), PostgreSQL 16-alpine ×2, Traefik, Cloudflare DNS, Docker Compose on hf-pdocker-01.
|
||
|
||
## Why this is three migrations, not a config flag
|
||
|
||
Verified in the running image's own source (`synapse/config/experimental.py`):
|
||
|
||
```python
|
||
if (self.msc4108_enabled or self.msc4108_delegation_endpoint is not None) and not auth_delegated:
|
||
raise ConfigError("MSC4108 requires matrix_authentication_service to be enabled", ...)
|
||
```
|
||
|
||
The same guard exists for MSC4388 (the QR out-of-band channel). And from the MAS docs:
|
||
|
||
> "It is worth noting that MAS currently only supports PostgreSQL as a database backend."
|
||
> "The migration tool only supports reading from PostgreSQL for the Synapse database as well."
|
||
|
||
Synapse on this node currently runs `database: {name: sqlite3, database: /data/homeserver.db}`.
|
||
|
||
## Global Constraints
|
||
|
||
- Synapse image stays pinned at `ghcr.io/element-hq/synapse:v1.159.0` (**`v` prefix required**; `:1.159.0` 404s). Do not bump during this work.
|
||
- Synapse ≥1.143 requires **PostgreSQL 14+**. Use `postgres:16-alpine`.
|
||
- Synapse's PostgreSQL database MUST be created with `ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C'` — Synapse refuses any other collation.
|
||
- MAS requires its **own separate, blank** PostgreSQL database. Do not share Synapse's.
|
||
- All lock-prone databases go on **LOCAL disk**, never NFS (CLAUDE.md Known Issue #16). Use `/var/lib/synapse-db` and `/var/lib/mas-db`.
|
||
- On hf-pdocker-01, **`memswap_limit` must equal `mem_limit`** on every container (Known Issue #12 — a drift here crashed the whole node on 2026-07-12).
|
||
- Node headroom: ~8GB available of 23GB, Frigate is the main consumer. Budget ≤600MB total for the new containers.
|
||
- **hobbs.farm has no wildcard DNS record** (memory `hobbs-farm-dns`). Traefik uses DNS-01, so a certificate will be issued for a hostname with **no A record** — a valid cert does NOT mean the name resolves. Any new public hostname needs an explicit Cloudflare A record → `98.160.103.126`, DNS-only (grey cloud).
|
||
- Watchtower does not run on .192; pin every image tag explicitly.
|
||
- Synapse data lives at `/var/lib/synapse` on local NVMe. The NFS copy at `/mnt/docker-data/configs/matrix/data` is a stale backup — **never remount it**.
|
||
- The mandatory post-change checklist in CLAUDE.md applies (CLAUDE.md, MEMORY.md, Prometheus probes, wiki, Farm Manager links).
|
||
|
||
## Blast Radius
|
||
|
||
Authentication for **all 19 accounts** moves to MAS. Known consumers that must keep working:
|
||
|
||
| Account | How it authenticates | Migrates via |
|
||
|---|---|---|
|
||
| `@jeremy` | password `bigdog01` + 5 Element devices (2× Element X Android, 2× Element Desktop) | password hash + devices |
|
||
| `@frigate` | long-lived access token `syt_ZnJpZ2F0…` in `frigate-notify/.env` | access token |
|
||
| `@alertbot` | long-lived access token `syt_YWxlcnRib3Q…` in `matrix-receiver-config.yml` | access token |
|
||
| `@margaret` | openclaw.json contains **both** `accessToken` and `password` | both |
|
||
| `@spirit` | openclaw config (path differs from margaret's — resolve in Task 1) | TBD in Task 1 |
|
||
| `@clippyauto` | n8n credential on .100, polls `/sync` every ~2s | TBD in Task 1 |
|
||
| `@fry`, `@hermes`, `@julie`, `@pluto`, `@testbot`, `@admin1`, `@adminuser` | unknown | TBD in Task 1 |
|
||
|
||
MAS exposes a compatibility layer proxying `/_matrix/client/*/login`, so password-based bots are expected to keep working — **this is the single biggest assumption in the plan and Task 1 exists to test it, not trust it.**
|
||
|
||
## File Structure
|
||
|
||
- Create `compose/hf-pdocker-01/mas/docker-compose.yml` — MAS + `mas-db` PostgreSQL. One file, one responsibility: authentication.
|
||
- Modify `compose/hf-pdocker-01/matrix/docker-compose.yml` — re-add a `synapse-db` service (PostgreSQL 16, local disk). Note this partly reverses the 2026-08-20 removal of the *empty* postgres; this one will actually hold data.
|
||
- Create `/var/lib/synapse/homeserver-postgres.yaml` on the node — port-target config for `synapse_port_db` (node-only, not in repo — contains DB credentials).
|
||
- Create `/mnt/docker-data/configs/mas/config.yaml` on the node — MAS config (node-only, contains signing keys and secrets; back up to Vaultwarden).
|
||
- Modify `/mnt/docker-data/traefik/dynamic/temp-routes.yml` — add the `auth.hobbs.farm` router + service. (Yes, the Matrix, Home Assistant and Guacamole routes all live in a file called `temp-routes.yml`. It is load-bearing despite the name.)
|
||
- Modify `CLAUDE.md`, `MEMORY.md` — post-change checklist.
|
||
|
||
---
|
||
|
||
### Task 1: Auth inventory and full backup
|
||
|
||
**Files:**
|
||
- Create: `/var/lib/synapse.bak-premas/` (node), `docs/superpowers/plans/mas-auth-inventory.md` (repo)
|
||
|
||
**Interfaces:**
|
||
- Produces: a complete table of every account → auth method → config file location, used by Tasks 7 and 10 to verify nothing broke.
|
||
|
||
- [ ] **Step 1: Enumerate every device and its last-seen IP, to know what "still working" means later**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker exec synapse python3 -c "
|
||
import sqlite3
|
||
c=sqlite3.connect(\"file:/var/lib/synapse/homeserver.db?mode=ro\",uri=True)
|
||
for u,d,n,ip in c.execute(\"select user_id,device_id,display_name,last_seen_ip from devices order by user_id\"):
|
||
print(u,d,n,ip)
|
||
"'
|
||
```
|
||
|
||
Expected: rows for `@jeremy` (5 devices), plus bot devices for margaret/spirit/clippyauto/frigate/alertbot/fry.
|
||
|
||
- [ ] **Step 2: Locate spirit's and clippyauto's credentials (unresolved in planning)**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker inspect spirit --format "{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}"; docker exec spirit sh -c "ls -la /home/glyptic/.openclaw/ 2>/dev/null || find / -name openclaw.json -maxdepth 6 2>/dev/null | head"'
|
||
ssh glyptic@192.168.86.100 'docker exec n8n sh -c "printenv | grep -i matrix" 2>/dev/null; echo "---"; docker exec n8n-db psql -U n8n -tc "select name, type from credentials_entity;" 2>/dev/null | head'
|
||
```
|
||
|
||
Expected: a config path for spirit and a credential type for n8n. Record whether each uses an **access token** or a **password** — access tokens migrate untouched; passwords depend on the MAS compat layer.
|
||
|
||
- [ ] **Step 3: Write the inventory file**
|
||
|
||
Record one row per account: user id, auth method, exact file path holding the credential, and how to verify it post-migration. Save as `docs/superpowers/plans/mas-auth-inventory.md`.
|
||
|
||
- [ ] **Step 4: Take a cold, complete backup**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 '
|
||
cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose stop synapse
|
||
sudo rsync -a /var/lib/synapse/ /var/lib/synapse.bak-premas/
|
||
sudo python3 -c "
|
||
import sqlite3;c=sqlite3.connect(\"/var/lib/synapse.bak-premas/homeserver.db\")
|
||
print(\"integrity:\", c.execute(\"pragma integrity_check\").fetchone()[0])
|
||
print(\"users:\", c.execute(\"select count(*) from users\").fetchone()[0])
|
||
print(\"events:\", c.execute(\"select count(*) from events\").fetchone()[0])
|
||
"
|
||
docker compose start synapse'
|
||
```
|
||
|
||
Expected: `integrity: ok`, 19 users, ~93,884 events. **Do not proceed if integrity is anything but `ok`.**
|
||
|
||
- [ ] **Step 5: Commit the inventory**
|
||
|
||
```bash
|
||
git add docs/superpowers/plans/mas-auth-inventory.md
|
||
git commit -m "docs: matrix auth inventory ahead of MAS migration"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: PostgreSQL for Synapse (blank, correct collation)
|
||
|
||
**Files:**
|
||
- Modify: `compose/hf-pdocker-01/matrix/docker-compose.yml`
|
||
|
||
**Interfaces:**
|
||
- Produces: `synapse-db` reachable at `synapse-db:5432` on the `matrix-internal` network, database `synapse`, user `synapse`, C collation. Task 3 ports data into it.
|
||
|
||
- [ ] **Step 1: Add the service to the compose file**
|
||
|
||
```yaml
|
||
synapse-db:
|
||
image: postgres:16-alpine
|
||
container_name: synapse-db
|
||
restart: unless-stopped
|
||
environment:
|
||
- POSTGRES_USER=synapse
|
||
- POSTGRES_PASSWORD=<generate: openssl rand -base64 24>
|
||
- POSTGRES_DB=synapse
|
||
- POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
|
||
volumes:
|
||
- /var/lib/synapse-db:/var/lib/postgresql/data # LOCAL disk - Known Issue #16
|
||
networks:
|
||
- matrix-internal
|
||
mem_limit: 512M
|
||
memswap_limit: 512M # MUST equal mem_limit - Known Issue #12
|
||
labels:
|
||
- "com.centurylinklabs.watchtower.enable=false"
|
||
healthcheck:
|
||
test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
|
||
interval: 30s
|
||
timeout: 10s
|
||
retries: 3
|
||
start_period: 30s
|
||
logging:
|
||
driver: "json-file"
|
||
options: {max-size: "50m", max-file: "3"}
|
||
```
|
||
|
||
Note: **no `user: "1024:100"`** — that workaround is only for NFS root_squash. This volume is local.
|
||
|
||
- [ ] **Step 2: Deploy and verify collation**
|
||
|
||
```bash
|
||
scp compose/hf-pdocker-01/matrix/docker-compose.yml glyptic@192.168.86.192:/mnt/docker-data/compose/hf-pdocker-01/matrix/
|
||
ssh glyptic@192.168.86.192 'cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose up -d synapse-db && sleep 20 && docker exec synapse-db psql -U synapse -d synapse -c "show lc_collate;"'
|
||
```
|
||
|
||
Expected: `lc_collate` = `C`. **If it says anything else, delete `/var/lib/synapse-db` and redo** — Synapse will refuse to start otherwise, and fixing it later means re-porting.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add compose/hf-pdocker-01/matrix/docker-compose.yml
|
||
git commit -m "feat: add postgres for synapse (local disk, C collation) ahead of MAS"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Port Synapse SQLite → PostgreSQL
|
||
|
||
**Files:**
|
||
- Create: `/var/lib/synapse/homeserver-postgres.yaml` (node only)
|
||
- Modify: `/var/lib/synapse/homeserver.yaml` (node only)
|
||
|
||
**Interfaces:**
|
||
- Consumes: `synapse-db` from Task 2.
|
||
- Produces: a Synapse running on PostgreSQL — the precondition `syn2mas` requires in Task 7.
|
||
|
||
- [ ] **Step 1: Write the port-target config**
|
||
|
||
Copy `/var/lib/synapse/homeserver.yaml` to `homeserver-postgres.yaml` and replace the `database:` block with:
|
||
|
||
```yaml
|
||
database:
|
||
name: psycopg2
|
||
args:
|
||
user: synapse
|
||
password: <the password from Task 2>
|
||
dbname: synapse
|
||
host: synapse-db
|
||
cp_min: 5
|
||
cp_max: 10
|
||
```
|
||
|
||
- [ ] **Step 2: Stop Synapse (downtime starts)**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose stop synapse'
|
||
```
|
||
|
||
- [ ] **Step 3: Run the port**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker run --rm --network matrix_matrix-internal \
|
||
-v /var/lib/synapse:/data ghcr.io/element-hq/synapse:v1.159.0 \
|
||
synapse_port_db --sqlite-database /data/homeserver.db --postgres-config /data/homeserver-postgres.yaml'
|
||
```
|
||
|
||
Expected: a progress table per-table, ending in `Success!`. Budget 10–40 minutes for ~94k events on this hardware. If it fails partway, drop and recreate the database before retrying — **the port tool is not idempotent against a partially-filled database.**
|
||
|
||
- [ ] **Step 4: Verify row counts match the source**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker exec synapse-db psql -U synapse -d synapse -tc "select (select count(*) from users) as users, (select count(*) from events) as events;"'
|
||
```
|
||
|
||
Expected: `19 | 93884` (or higher for events if the server ran between backup and port). **Must not be lower.**
|
||
|
||
- [ ] **Step 5: Cut Synapse over**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'sudo cp /var/lib/synapse/homeserver.yaml /var/lib/synapse/homeserver.yaml.bak-presql
|
||
sudo cp /var/lib/synapse/homeserver-postgres.yaml /var/lib/synapse/homeserver.yaml
|
||
cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose start synapse'
|
||
```
|
||
|
||
- [ ] **Step 6: Verify the service on PostgreSQL**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 '
|
||
for i in $(seq 1 30); do [ "$(docker inspect synapse --format "{{.State.Health.Status}}")" = healthy ] && echo healthy && break; sleep 10; done
|
||
curl -s http://localhost:8008/_synapse/admin/v1/server_version; echo
|
||
curl -s -X POST http://localhost:8008/_matrix/client/v3/login -H "Content-Type: application/json" \
|
||
-d "{\"type\":\"m.login.password\",\"identifier\":{\"type\":\"m.id.user\",\"user\":\"jeremy\"},\"password\":\"bigdog01\"}" | head -c 80
|
||
docker logs synapse --since 5m 2>&1 | grep -cE " ERROR "'
|
||
```
|
||
|
||
Expected: `healthy`, version `1.159.0`, an `access_token` in the login response, `0` errors. Log out that verification session afterwards (`POST /_matrix/client/v3/logout`).
|
||
|
||
- [ ] **Step 7: Confirm bots reconnected before declaring the task done**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'sleep 60; docker logs synapse --since 60s 2>&1 | grep -oE "\{@[a-z0-9]+:hobbs.farm\}" | sort | uniq -c'
|
||
```
|
||
|
||
Expected: clippyauto, margaret, spirit, fry all present. **Rollback if not:** restore `homeserver.yaml.bak-presql` and restart — SQLite file is untouched and still authoritative until Task 7.
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git commit --allow-empty -m "chore: synapse ported from sqlite to postgres (node config, not in repo)"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: PostgreSQL for MAS
|
||
|
||
**Files:**
|
||
- Create: `compose/hf-pdocker-01/mas/docker-compose.yml`
|
||
|
||
**Interfaces:**
|
||
- Produces: `mas-db:5432`, database `mas`, user `mas`, on a new `mas` bridge network that also carries the MAS container.
|
||
|
||
- [ ] **Step 1: Create the compose file with the database service only**
|
||
|
||
Same shape as Task 2 Step 1, but: `container_name: mas-db`, `POSTGRES_USER=mas`, `POSTGRES_DB=mas`, volume `/var/lib/mas-db:/var/lib/postgresql/data`, `mem_limit: 256M`, `memswap_limit: 256M`, network `mas`. Default collation is fine — the C-collation requirement is Synapse's, not MAS's.
|
||
|
||
- [ ] **Step 2: Deploy and verify**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'cd /mnt/docker-data/compose/hf-pdocker-01/mas && docker compose up -d mas-db && sleep 20 && docker exec mas-db psql -U mas -d mas -tc "select 1;"'
|
||
```
|
||
|
||
Expected: `1`.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add compose/hf-pdocker-01/mas/docker-compose.yml
|
||
git commit -m "feat: add mas-db postgres for matrix authentication service"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: Generate MAS config and deploy the service
|
||
|
||
**Files:**
|
||
- Create: `/mnt/docker-data/configs/mas/config.yaml` (node only — contains secrets)
|
||
- Modify: `compose/hf-pdocker-01/mas/docker-compose.yml`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `mas-db` from Task 4.
|
||
- Produces: MAS listening on host port **8020** (verified free on .192: 8008/8010/8080/8082/8085/8086/8090/8123/8181/8199/8300/8310 are taken).
|
||
|
||
- [ ] **Step 1: Generate a config seeded from the Synapse config**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'sudo mkdir -p /mnt/docker-data/configs/mas && docker run --rm \
|
||
-v /var/lib/synapse:/synapse:ro -v /mnt/docker-data/configs/mas:/out \
|
||
ghcr.io/element-hq/matrix-authentication-service:latest \
|
||
config generate --synapse-config /synapse/homeserver.yaml --output /out/config.yaml'
|
||
```
|
||
|
||
Expected: `config.yaml` written, containing generated signing keys and a `matrix.secret` shared secret.
|
||
|
||
- [ ] **Step 2: Set the database URI, public base, and password hashing scheme**
|
||
|
||
Edit `/mnt/docker-data/configs/mas/config.yaml`:
|
||
|
||
```yaml
|
||
database:
|
||
uri: postgresql://mas:<password>@mas-db/mas
|
||
http:
|
||
public_base: https://auth.hobbs.farm
|
||
listeners:
|
||
- name: web
|
||
resources: [{name: discovery}, {name: human}, {name: oauth}, {name: compat}, {name: graphql}, {name: assets}]
|
||
binds: [{address: "[::]:8080"}]
|
||
passwords:
|
||
enabled: true
|
||
schemes:
|
||
- version: 1
|
||
algorithm: bcrypt
|
||
unicode_normalization: true # REQUIRED for imported Synapse hashes
|
||
- version: 2
|
||
algorithm: argon2id
|
||
```
|
||
|
||
The `unicode_normalization: true` on the bcrypt v1 scheme is what makes migrated Synapse password hashes verify. Without it, **every migrated password silently fails**.
|
||
|
||
- [ ] **Step 3: Add the MAS service to compose**
|
||
|
||
```yaml
|
||
mas:
|
||
image: ghcr.io/element-hq/matrix-authentication-service:latest # pin to the digest after first pull
|
||
container_name: mas
|
||
restart: unless-stopped
|
||
command: ["server", "--config", "/config/config.yaml"]
|
||
volumes:
|
||
- /mnt/docker-data/configs/mas:/config:ro
|
||
ports:
|
||
- "8020:8080"
|
||
networks: [mas, matrix-internal]
|
||
depends_on:
|
||
mas-db: {condition: service_healthy}
|
||
mem_limit: 256M
|
||
memswap_limit: 256M
|
||
labels:
|
||
- "com.centurylinklabs.watchtower.enable=false"
|
||
```
|
||
|
||
MAS needs to reach Synapse's admin API and Synapse needs to reach MAS, hence both networks.
|
||
|
||
- [ ] **Step 4: Run migrations and start**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'cd /mnt/docker-data/compose/hf-pdocker-01/mas && docker compose run --rm mas database migrate --config /config/config.yaml && docker compose up -d mas && sleep 15 && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8020/health'
|
||
```
|
||
|
||
Expected: migrations apply cleanly, health endpoint returns `200`.
|
||
|
||
- [ ] **Step 5: Store the MAS secrets in Vaultwarden and commit**
|
||
|
||
The generated `config.yaml` holds signing keys that cannot be regenerated without invalidating sessions. Store a copy in Vaultwarden (note: the vault master password is currently unknown — see memory `vault-master-password-stale`; resolve that first or keep an encrypted copy on the NAS).
|
||
|
||
```bash
|
||
git add compose/hf-pdocker-01/mas/docker-compose.yml
|
||
git commit -m "feat: deploy matrix authentication service on :8020"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: syn2mas check and dry-run
|
||
|
||
**Interfaces:**
|
||
- Consumes: Synapse-on-PostgreSQL (Task 3), MAS + DB (Tasks 4–5).
|
||
- Produces: a clean dry-run, the go/no-go gate for Task 7.
|
||
|
||
- [ ] **Step 1: Run the checker**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker exec mas mas-cli syn2mas check --config /config/config.yaml --synapse-config /synapse/homeserver.yaml'
|
||
```
|
||
|
||
(Mount `/var/lib/synapse` read-only into the MAS container as `/synapse` for this — add it in Task 5 Step 3 if not already present.)
|
||
|
||
Expected: no blocking findings. Known blockers it looks for: custom password provider modules, SAML/LDAP providers. This deployment has neither.
|
||
|
||
- [ ] **Step 2: Dry run**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker exec mas mas-cli syn2mas migrate --config /config/config.yaml --synapse-config /synapse/homeserver.yaml --dry-run'
|
||
```
|
||
|
||
Expected: a summary of users, password hashes, devices, and access tokens it *would* import. Cross-check the user count against **19** and the device count against Task 1 Step 1. **Do not proceed to Task 7 if the counts disagree.**
|
||
|
||
- [ ] **Step 3: Record the dry-run output in the inventory doc and commit**
|
||
|
||
```bash
|
||
git add docs/superpowers/plans/mas-auth-inventory.md
|
||
git commit -m "docs: syn2mas dry-run results"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: Migrate accounts into MAS and delegate Synapse auth
|
||
|
||
**Files:**
|
||
- Modify: `/var/lib/synapse/homeserver.yaml` (node only)
|
||
|
||
**Interfaces:**
|
||
- Produces: Synapse delegating all authentication to MAS — the precondition MSC4108 requires.
|
||
|
||
**This is the point of no return.** The MAS docs state migration "is not easily reversible and requires careful backup procedures before proceeding." Rollback means restoring both databases from backup.
|
||
|
||
- [ ] **Step 1: Fresh backup of both databases immediately before migrating**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 '
|
||
cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose stop synapse
|
||
docker exec synapse-db pg_dump -U synapse synapse | gzip > /tmp/synapse-premas.sql.gz
|
||
docker exec mas-db pg_dump -U mas mas | gzip > /tmp/mas-premigrate.sql.gz
|
||
sudo mv /tmp/*.gz /var/lib/synapse.bak-premas/ && ls -la /var/lib/synapse.bak-premas/*.gz'
|
||
```
|
||
|
||
Expected: two non-empty `.gz` files.
|
||
|
||
- [ ] **Step 2: Run the migration (Synapse stays stopped)**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker exec mas mas-cli syn2mas migrate --config /config/config.yaml --synapse-config /synapse/homeserver.yaml'
|
||
```
|
||
|
||
Expected: completes with an import summary matching the dry-run.
|
||
|
||
- [ ] **Step 3: Point Synapse at MAS**
|
||
|
||
Add to `/var/lib/synapse/homeserver.yaml`:
|
||
|
||
```yaml
|
||
matrix_authentication_service:
|
||
enabled: true
|
||
endpoint: http://mas:8080/
|
||
secret: <the matrix.secret value from /mnt/docker-data/configs/mas/config.yaml>
|
||
```
|
||
|
||
- [ ] **Step 4: Start Synapse and verify delegation is live**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 '
|
||
cd /mnt/docker-data/compose/hf-pdocker-01/matrix && docker compose start synapse
|
||
for i in $(seq 1 30); do [ "$(docker inspect synapse --format "{{.State.Health.Status}}")" = healthy ] && echo healthy && break; sleep 10; done
|
||
curl -s -o /dev/null -w "auth_metadata: %{http_code}\n" http://localhost:8008/_matrix/client/unstable/org.matrix.msc2965/auth_metadata'
|
||
```
|
||
|
||
Expected: `healthy`, and auth_metadata now returns **200** (it returns 404 today).
|
||
|
||
- [ ] **Step 5: Verify every account from the Task 1 inventory still authenticates**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 '
|
||
echo "--- password login via MAS compat layer:"
|
||
curl -s -X POST http://localhost:8008/_matrix/client/v3/login -H "Content-Type: application/json" \
|
||
-d "{\"type\":\"m.login.password\",\"identifier\":{\"type\":\"m.id.user\",\"user\":\"jeremy\"},\"password\":\"bigdog01\"}" | head -c 100; echo
|
||
echo "--- migrated access token (frigate):"
|
||
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8008/_matrix/client/v3/account/whoami -H "Authorization: Bearer syt_ZnJpZ2F0<rest-from-.env>"
|
||
echo "--- bots syncing:"
|
||
sleep 90; docker logs synapse --since 90s 2>&1 | grep -oE "\{@[a-z0-9]+:hobbs.farm\}" | sort | uniq -c'
|
||
```
|
||
|
||
Expected: an `access_token` for jeremy, `200` for the frigate token, and margaret/spirit/clippyauto/fry all syncing. **If password login fails, the bcrypt `unicode_normalization: true` setting from Task 5 Step 2 is the first thing to check.**
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git commit --allow-empty -m "feat: synapse auth delegated to MAS (node config)"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: Publish MAS and add DNS
|
||
|
||
**Files:**
|
||
- Modify: `/mnt/docker-data/traefik/dynamic/temp-routes.yml` (confirmed: this is the file holding the `mess`, `wellknown`, `yoda` and `solo` routers)
|
||
- External: Cloudflare DNS
|
||
|
||
- [ ] **Step 1: Add the Cloudflare A record FIRST**
|
||
|
||
`auth.hobbs.farm` → `98.160.103.126`, **DNS-only (grey cloud)**. There is no wildcard record on this zone, and Traefik's DNS-01 challenge will happily issue a valid certificate for a hostname that does not resolve — so a working cert proves nothing here (memory `hobbs-farm-dns`).
|
||
|
||
Verify from outside the LAN before continuing:
|
||
|
||
```bash
|
||
getent hosts auth.hobbs.farm
|
||
```
|
||
|
||
Expected: `98.160.103.126`.
|
||
|
||
- [ ] **Step 2: Add the Traefik router and service**
|
||
|
||
```yaml
|
||
auth:
|
||
rule: "Host(`auth.hobbs.farm`)"
|
||
service: auth
|
||
entryPoints: [websecure]
|
||
middlewares: [security-headers]
|
||
tls: {certResolver: letsencrypt}
|
||
```
|
||
```yaml
|
||
auth:
|
||
loadBalancer:
|
||
servers:
|
||
- url: "http://192.168.86.192:8020"
|
||
```
|
||
|
||
Do **not** add basicAuth — clients must reach this unauthenticated to log in.
|
||
|
||
- [ ] **Step 3: Verify publicly**
|
||
|
||
```bash
|
||
curl -s -o /dev/null -w "%{http_code}\n" https://auth.hobbs.farm/health
|
||
curl -s https://mess.hobbs.farm/_matrix/client/unstable/org.matrix.msc2965/auth_metadata | head -c 300
|
||
```
|
||
|
||
Expected: `200`, and auth metadata advertising `https://auth.hobbs.farm` endpoints.
|
||
|
||
- [ ] **Step 4: Confirm `.well-known` needs no change (verify, do not assume)**
|
||
|
||
Current contents, served from `/mnt/docker-data/configs/matrix/wellknown/` via `matrix-wellknown` on :8010:
|
||
|
||
```
|
||
client -> {"m.homeserver": {"base_url": "https://mess.hobbs.farm"}}
|
||
server -> {"m.server": "mess.hobbs.farm:443"}
|
||
```
|
||
|
||
Under MAS, clients discover the auth server from Synapse's `auth_metadata` endpoint, not from `.well-known`, so **both files should stay as they are**. Verify a client can complete discovery end to end:
|
||
|
||
```bash
|
||
curl -s https://hobbs.farm/.well-known/matrix/client
|
||
curl -s https://mess.hobbs.farm/_matrix/client/unstable/org.matrix.msc2965/auth_metadata | head -c 200
|
||
```
|
||
|
||
Expected: `.well-known` unchanged and still pointing at `mess.hobbs.farm`; auth_metadata returning the `auth.hobbs.farm` issuer. If a client cannot find the auth server, revisit `http.public_base` in the MAS config (Task 5 Step 2) before touching `.well-known`.
|
||
|
||
- [ ] **Step 5: Add a Prometheus blackbox probe for the new endpoint**
|
||
|
||
Add `https://auth.hobbs.farm/health` to the blackbox target list in `/mnt/docker-data/configs/prometheus/prometheus.yml`, then hot-reload:
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'curl -s -X POST http://localhost:9095/-/reload && sleep 5 && curl -s "http://localhost:9095/api/v1/query?query=probe_success" | grep -o "auth.hobbs.farm"'
|
||
```
|
||
|
||
Expected: the target appears and probes `1`. **Auth being down now means nobody can log in — this probe is not optional.**
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add compose/ && git commit -m "feat: publish MAS at auth.hobbs.farm with blackbox probe"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 9: Enable the QR MSCs
|
||
|
||
**Files:**
|
||
- Modify: `/var/lib/synapse/homeserver.yaml` (node only)
|
||
|
||
- [ ] **Step 1: Enable both MSCs**
|
||
|
||
```yaml
|
||
experimental_features:
|
||
msc4108_enabled: true
|
||
msc4388_mode: authenticated
|
||
```
|
||
|
||
`msc4388_mode: authenticated` requires the rendezvous channel user to be logged in — prefer it over `open`, which would let unauthenticated parties open rendezvous sessions on an internet-facing server.
|
||
|
||
- [ ] **Step 2: Restart and confirm Synapse actually starts**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'docker restart synapse && sleep 45 && docker logs synapse --since 2m 2>&1 | grep -iE "ConfigError|MSC4108|MSC4388" | head'
|
||
```
|
||
|
||
Expected: **no `ConfigError`**. If you see `MSC4108 requires matrix_authentication_service to be enabled`, Task 7 Step 3 did not take effect.
|
||
|
||
- [ ] **Step 3: Verify the feature is advertised**
|
||
|
||
```bash
|
||
ssh glyptic@192.168.86.192 'curl -s http://localhost:8008/_matrix/client/versions | python3 -c "
|
||
import sys,json; uf=json.load(sys.stdin)[\"unstable_features\"]
|
||
print(\"msc4108:\", uf.get(\"org.matrix.msc4108\"))
|
||
"'
|
||
```
|
||
|
||
Expected: `msc4108: True` (it is `False` today).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git commit --allow-empty -m "feat: enable MSC4108/MSC4388 QR sign-in"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 10: End-to-end QR sign-in test and documentation
|
||
|
||
- [ ] **Step 1: Test the actual feature**
|
||
|
||
On an already-signed-in Element X Android device: Settings → Sessions → "Sign in with QR code" / "Link new device". On a second client, choose "Sign in with QR code" and scan.
|
||
|
||
Expected: the new device signs in and receives E2EE keys **without** the password being typed. This is the deliverable — if it does not work here, the feature is not done regardless of what the config says.
|
||
|
||
- [ ] **Step 2: Re-verify the full account inventory one more time**
|
||
|
||
Re-run Task 7 Step 5. Expected: unchanged — all bots syncing, all tokens valid.
|
||
|
||
- [ ] **Step 3: Complete the mandatory post-change checklist (CLAUDE.md)**
|
||
|
||
- CLAUDE.md: MAS + two PostgreSQL containers on .192, port 8020, `auth.hobbs.farm`, Synapse now on PostgreSQL (supersedes Known Issues #24/#25 wording), new known issue for the MAS dependency — **auth is now a hard dependency for every login, including bots**
|
||
- MEMORY.md: new entry for the MAS migration; update `matrix-account` (the reset recipe changes — user management moves to MAS)
|
||
- Prometheus: done in Task 8 Step 4
|
||
- Farm Manager links page: add `auth.hobbs.farm` to `serverLinks` in `/opt/farm-manager/server/static/app.js`, then **rebuild the image** (links are baked in, not mounted) and redeploy
|
||
- Wiki: run the documentation-keeper agent
|
||
|
||
- [ ] **Step 4: Retire the backups once stable**
|
||
|
||
Leave `/var/lib/synapse.bak-premas/`, `/var/lib/synapse.bak-20260820-pre1159/`, and the SQLite file in place for **at least a week** of normal use. Only then delete.
|
||
|
||
- [ ] **Step 5: Final commit**
|
||
|
||
```bash
|
||
git add -A && git commit -m "docs: MAS QR sign-in deployment complete"
|
||
```
|
||
|
||
---
|
||
|
||
## Rollback Summary
|
||
|
||
| Failed at | Recovery |
|
||
|---|---|
|
||
| Task 3 (port to PG) | Restore `homeserver.yaml.bak-presql`; SQLite file untouched and still authoritative |
|
||
| Task 7 (syn2mas) | Restore `synapse-premas.sql.gz` + `mas-premigrate.sql.gz`; remove `matrix_authentication_service` block |
|
||
| Task 9 (MSCs) | Remove `experimental_features` block; restart — no data implications |
|
||
|
||
## Open Questions for the Operator
|
||
|
||
1. **Element Desktop compatibility.** Your two Element Desktop sessions are on the legacy auth stack. OIDC-native support in Element Web/Desktop has historically lagged Element X. Worth confirming before migrating, since a broken desktop client is a worse day than no QR code.
|
||
2. **Is `auth.hobbs.farm` the hostname you want?** It becomes permanent — it is baked into session state, and changing `public_base` later invalidates sessions.
|
||
3. **Vaultwarden is currently locked out** (memory `vault-master-password-stale`). MAS generates signing keys that must be backed up somewhere durable. Resolve the vault access first, or agree on an alternative.
|
||
4. **Node memory.** .192 sits at ~14/23GB with Frigate as the main consumer. This adds ~1GB across three containers (Synapse's PG, MAS's PG, MAS). If that is too tight, the MAS stack could go on .100 instead — it only needs network reachability to Synapse, not co-location.
|