Matrix: migrate from mesh0:6167 to public TLS (matrix.et0.pw) #34

Open

opened 2026-08-06 05:39:01 +00:00 by agent.odin · 0 comments

agent.odin commented

2026-08-06 05:39:01 +00:00

Collaborator

Problem

Matrix (tuwunel on bifrost) currently serves clients over mesh0:
listenAddress = "0.0.0.0", port 6167, plain HTTP, firewall gated to the mesh
interface. The mesh is the encryption — no TLS needed because wireguard
membership is the trust boundary.

With mesh0 decommissioned, that path disappears. Matrix must move to public
ingress: TLS, a public hostname, and federation delegation that survives the
transition.

Two failure modes are silent:

Federation delegation — /.well-known/matrix/* must serve correct JSON
from et0.pw. A delegation that serves 200 with subtly wrong JSON fails
federation silently — a remote server cannot resolve @you:et0.pw. This is
the same trap DEFERRED.md already flags, and it applies doubly here because
the delegation target itself is moving.
Client connections — mobile clients currently reach the homeserver over
mesh0. Moving to public means the client configuration changes. A client
pointed at a mesh address that no longer resolves fails with a generic
connection error that doesn't point at the cause.

Scope

TLS + public hostname. matrix.et0.pw already exists as a DNS name.
Caddy (on bifrost) serves it with TLS — Cloudflare proxy certificate or
Let's Encrypt, whichever the fleet standard is post-mesh.
Homeserver listener. tuwunel continues listening on 0.0.0.0:6167, but
Caddy proxies matrix.et0.pw:443 → localhost:6167. The firewall opens
443 on the public interface, not 6167.
Federation delegation. /.well-known/matrix/server and
/.well-known/matrix/client served from et0.pw (on bifrost's Caddy).
Verify against real federation — a remote server must resolve
@you:et0.pw and deliver a message. Serving 200 is not enough.
Client migration. Mobile clients reconfigured to matrix.et0.pw.
Registration token handling stays as-is (registrationTokenFile).
Wolves. The planned accounts (@freki:et0.pw, @geri:et0.pw, backlog.md)
assumed mesh-only plain HTTP to bifrost:6167. They now connect over public
TLS like any other client.

Non-scope

Homeserver data migration. tuwunel's database and state stay on bifrost.
Only the network path changes.
Client-side configuration automation. Each user updates their own client.

Acceptance

matrix.et0.pw serves TLS on 443 via Caddy
Caddy proxies 443 → localhost:6167
Port 6167 not exposed on public interface
/.well-known/matrix/server serves correct delegation JSON from et0.pw
/.well-known/matrix/client serves correct client discovery JSON
Federation verified: a remote server resolves and delivers to @you:et0.pw
Mobile client connects over public TLS
Registration token still works (if still in use)

Provenance

Owner ruling 2026-08-06. Matrix is one of the two hard migrations blocking
mesh decommission (#32). Current config: listenAddress = "0.0.0.0", port
6167, mesh-firewall-gated, plain HTTP. Public name matrix.et0.pw exists.

DEFERRED.md's federation verification step ("verify federation actually works")
is an acceptance criterion here, not a TODO.

Stable ID: FM-MATRIX-PUBLIC Source: owner ruling 2026-08-06 (mesh decommission, #32) Disposition: open — hard migration Blocked by: #33 (Forgejo OIDC — proves the Authelia OIDC provider is production-grade before Matrix depends on it) Epic: #32 (mesh decommission) ## Problem Matrix (tuwunel on bifrost) currently serves clients over mesh0: `listenAddress = "0.0.0.0"`, port 6167, plain HTTP, firewall gated to the mesh interface. The mesh **is** the encryption — no TLS needed because wireguard membership is the trust boundary. With mesh0 decommissioned, that path disappears. Matrix must move to public ingress: TLS, a public hostname, and federation delegation that survives the transition. Two failure modes are silent: 1. **Federation delegation** — `/.well-known/matrix/*` must serve correct JSON from `et0.pw`. A delegation that serves 200 with subtly wrong JSON fails federation silently — a remote server cannot resolve `@you:et0.pw`. This is the same trap DEFERRED.md already flags, and it applies doubly here because the delegation target itself is moving. 2. **Client connections** — mobile clients currently reach the homeserver over mesh0. Moving to public means the client configuration changes. A client pointed at a mesh address that no longer resolves fails with a generic connection error that doesn't point at the cause. ## Scope 1. **TLS + public hostname.** `matrix.et0.pw` already exists as a DNS name. Caddy (on bifrost) serves it with TLS — Cloudflare proxy certificate or Let's Encrypt, whichever the fleet standard is post-mesh. 2. **Homeserver listener.** tuwunel continues listening on `0.0.0.0:6167`, but Caddy proxies `matrix.et0.pw:443` → `localhost:6167`. The firewall opens 443 on the public interface, not 6167. 3. **Federation delegation.** `/.well-known/matrix/server` and `/.well-known/matrix/client` served from `et0.pw` (on bifrost's Caddy). Verify against real federation — a remote server must resolve `@you:et0.pw` and deliver a message. Serving 200 is not enough. 4. **Client migration.** Mobile clients reconfigured to `matrix.et0.pw`. Registration token handling stays as-is (`registrationTokenFile`). 5. **Wolves.** The planned accounts (`@freki:et0.pw`, `@geri:et0.pw`, backlog.md) assumed mesh-only plain HTTP to bifrost:6167. They now connect over public TLS like any other client. ## Non-scope - **Homeserver data migration.** tuwunel's database and state stay on bifrost. Only the network path changes. - **Client-side configuration automation.** Each user updates their own client. ## Acceptance - [ ] `matrix.et0.pw` serves TLS on 443 via Caddy - [ ] Caddy proxies 443 → localhost:6167 - [ ] Port 6167 not exposed on public interface - [ ] `/.well-known/matrix/server` serves correct delegation JSON from `et0.pw` - [ ] `/.well-known/matrix/client` serves correct client discovery JSON - [ ] **Federation verified**: a remote server resolves and delivers to `@you:et0.pw` - [ ] Mobile client connects over public TLS - [ ] Registration token still works (if still in use) ## Provenance Owner ruling 2026-08-06. Matrix is one of the two hard migrations blocking mesh decommission (#32). Current config: `listenAddress = "0.0.0.0"`, port 6167, mesh-firewall-gated, plain HTTP. Public name `matrix.et0.pw` exists. DEFERRED.md's federation verification step ("verify federation actually works") is an acceptance criterion here, not a TODO.

Commenting is not possible because the repository is archived.