Phase 5: federation

Implements PLAN.md Phase 5: the Server-Server API. Warp joins rooms on
other servers and lets their users join its rooms, invites across servers
with the invitee's server countersigning, rejects remote invites (locally
if the inviter is unreachable), and exchanges events, typing, receipts and
to-device messages with other homeservers — all behind the runtime switch,
which now starts and stops real outbound traffic.

The protocol lives in internal/federation with no knowledge of rooms:
X-Matrix signing (fuzzed parser), the spec's discovery algorithm keeping
the dial address and the TLS name apart, a signed client that refuses
every request while the switch is off or the policy denies the
destination, and a key ring that caches other servers' keys for at most a
week, with optional notaries.

The roomserver takes events from elsewhere through the spec's intake:
signatures and hashes (a hash mismatch keeps the redacted form), the rules
against the event's own auth events, against the state before it — with
/get_missing_events for small gaps and /state_ids for wide ones — and
against the current state, where a failure is a soft failure. Events held
without their state are outliers: a column on roomserver_events, because
the current state of a room joined over federation is almost all
outliers, and excluded from every timeline query. Forks are resolved at
the room's head. Membership across servers is make_join/send_join,
make_leave/send_leave and countersigned invites, in both directions;
m.room.server_acl is enforced on everything another server sends.
History before a remote join is backfilled when /messages pages past it,
stored at negative stream positions.

internal/federationapi is the running component: the inbound endpoints,
and an outbound queue that persists what it owes each destination, sends
it in transactions of 50 PDUs and 100 EDUs, backs off from ten seconds to
six hours, survives restarts, and drops events persisted while federation
is off rather than delivering a backlog in one burst. Its Module is what
the switch starts and stops.

Also: a TLS listener for port 8448, trusted key servers, key validity and
an outbound CA bundle in the config; per-destination health and backoff
reset in the admin API; remote profiles, aliases and directories in the
Client-Server API; a Complement federation profile. See
docs/federation.md, including its known gaps (no partial-state joins, no
key rotation).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

server/internal/setup/federation.go

@@ -0,0 +1,77 @@
+package setup
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"fmt"
+	"os"
+	"sync"
+
+	"github.com/dariuszjaniak/warp/server/internal/federationapi"
+	"github.com/dariuszjaniak/warp/server/internal/roomserver"
+	"github.com/dariuszjaniak/warp/server/internal/storage"
+)
+
+// fanout is the roomserver's emit stage when more than one thing listens:
+// the sync notifier, which wakes long polls, and the federation queue,
+// which sends events to other servers.
+//
+// Each listener is held to the roomserver's rule for a Notifier — never
+// block — so calling them in turn under the room lock is fine.
+type fanout struct {
+	mu        sync.RWMutex
+	listeners []roomserver.Notifier
+}
+
+func (f *fanout) add(n roomserver.Notifier) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.listeners = append(f.listeners, n)
+}
+
+// EventPersisted implements roomserver.Notifier.
+func (f *fanout) EventPersisted(ctx context.Context, n roomserver.Notification) {
+	f.mu.RLock()
+	defer f.mu.RUnlock()
+	for _, l := range f.listeners {
+		l.EventPersisted(ctx, n)
+	}
+}
+
+// federationStatus adapts the module to the admin API.
+type federationStatus struct {
+	module *federationapi.Module
+}
+
+func (s federationStatus) Running() bool { return s.module.Running() }
+
+func (s federationStatus) Destinations(ctx context.Context) ([]storage.DestinationSummary, error) {
+	return s.module.Queue().Destinations(ctx)
+}
+
+func (s federationStatus) ResetBackoff(ctx context.Context, serverName string) error {
+	return s.module.Queue().ResetBackoff(ctx, serverName)
+}
+
+// federationTLS builds the client TLS configuration for outbound
+// federation: the system roots, plus a configured CA bundle.
+func federationTLS(caFile string) (*tls.Config, error) {
+	cfg := &tls.Config{MinVersion: tls.VersionTLS12}
+	if caFile == "" {
+		return cfg, nil
+	}
+	pool, err := x509.SystemCertPool()
+	if err != nil || pool == nil {
+		pool = x509.NewCertPool()
+	}
+	pem, err := os.ReadFile(caFile)
+	if err != nil {
+		return nil, fmt.Errorf("read federation.tls_ca_file: %w", err)
+	}
+	if !pool.AppendCertsFromPEM(pem) {
+		return nil, fmt.Errorf("federation.tls_ca_file %s contains no PEM certificates", caFile)
+	}
+	cfg.RootCAs = pool
+	return cfg, nil
+}

server/internal/setup/phase5_test.go

@@ -0,0 +1,441 @@
+package setup_test
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/json"
+	"encoding/pem"
+	"log/slog"
+	"math/big"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/config"
+	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/signing"
+	"github.com/dariuszjaniak/warp/server/internal/setup"
+	"github.com/dariuszjaniak/warp/server/internal/userapi"
+)
+
+// The end-to-end federation tests: complete servers, each behind its own
+// TLS listener, finding each other through a resolver that maps their
+// names to those listeners. Everything between the client API on one
+// server and the client API on the other is real — X-Matrix signing, key
+// fetches, the routes, the gate, the outbound queue.
+
+// fedNode is one server of an end-to-end federation.
+type fedNode struct {
+	name string
+	srv  *setup.Server
+	ts   *httptest.Server
+
+	// handler is the server's handler, set once it exists. The listener
+	// has to be up before the server is built — every server needs every
+	// other's address — so it starts out answering 503.
+	handler atomic.Pointer[http.Handler]
+}
+
+func (n *fedNode) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	h := n.handler.Load()
+	if h == nil {
+		http.Error(w, "not ready", http.StatusServiceUnavailable)
+		return
+	}
+	(*h).ServeHTTP(w, r)
+}
+
+// newFederation starts servers that can reach each other.
+func newFederation(t *testing.T, names ...string) map[string]*fedNode {
+	t.Helper()
+	nodes := map[string]*fedNode{}
+	for _, name := range names {
+		node := &fedNode{name: name}
+		node.ts = httptest.NewUnstartedServer(node)
+		node.ts.StartTLS()
+		t.Cleanup(node.ts.Close)
+		nodes[name] = node
+	}
+
+	// Every test listener has the same certificate, for "example.com"; the
+	// Host is that name with the listener's port, and the address is the
+	// listener. That is the delegated-by-SRV shape: TLS is checked against
+	// one name and the connection goes somewhere else.
+	resolve := func(_ context.Context, name string) (federation.Resolved, error) {
+		node, ok := nodes[name]
+		if !ok {
+			return federation.Resolved{}, &net.DNSError{Err: "no such host", Name: name, IsNotFound: true}
+		}
+		addr := node.ts.Listener.Addr().String()
+		_, port, _ := net.SplitHostPort(addr)
+		return federation.Resolved{Addresses: []string{addr}, Host: "example.com:" + port}, nil
+	}
+	anyTS := nodes[names[0]].ts
+	clientTLS := anyTS.Client().Transport.(*http.Transport).TLSClientConfig.Clone()
+
+	for _, name := range names {
+		node := nodes[name]
+		key, err := signing.Generate("")
+		if err != nil {
+			t.Fatal(err)
+		}
+		keyPath := filepath.Join(t.TempDir(), name+".key")
+		if err := key.Save(keyPath); err != nil {
+			t.Fatal(err)
+		}
+		cfg := config.Default()
+		cfg.Global.ServerName = name
+		cfg.Global.PrivateKeyPath = keyPath
+		cfg.Database.ConnectionString = "file:" + filepath.ToSlash(filepath.Join(t.TempDir(), name+".db")) +
+			"?_pragma=busy_timeout(10000)&_pragma=journal_mode(WAL)"
+		cfg.Registration.Enabled = true
+		cfg.ClientAPI.RateLimit.Enabled = false
+		cfg.Federation.Enabled = true
+		if err := cfg.Validate(); err != nil {
+			t.Fatalf("config: %v", err)
+		}
+		srv, err := setup.New(t.Context(), cfg, setup.Options{
+			Logger:            slog.New(slog.DiscardHandler),
+			FederationResolve: resolve,
+			FederationTLS:     clientTLS,
+		})
+		if err != nil {
+			t.Fatalf("setup.New(%s): %v", name, err)
+		}
+		t.Cleanup(func() { _ = srv.Close() })
+		node.srv = srv
+		h := srv.Handler()
+		node.handler.Store(&h)
+		t.Cleanup(srv.FederationModule().Stop)
+		if err := srv.FederationModule().Start(t.Context()); err != nil {
+			t.Fatalf("start federation on %s: %v", name, err)
+		}
+	}
+	return nodes
+}
+
+// eventually polls until check passes or the deadline is reached.
+func eventually(t *testing.T, what string, check func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(15 * time.Second)
+	for time.Now().Before(deadline) {
+		if check() {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatalf("timed out waiting for %s", what)
+}
+
+// messageBodies reads the message bodies of a room's recent history.
+func messageBodies(t *testing.T, srv *setup.Server, roomID, token string) []string {
+	t.Helper()
+	rec := getWithToken(t, srv, "/_matrix/client/v3/rooms/"+url.PathEscape(roomID)+"/messages?dir=b&limit=50", token)
+	if rec.Code != http.StatusOK {
+		return nil
+	}
+	var resp struct {
+		Chunk []struct {
+			Type    string `json:"type"`
+			Content struct {
+				Body string `json:"body"`
+			} `json:"content"`
+		} `json:"chunk"`
+	}
+	_ = json.Unmarshal(rec.Body.Bytes(), &resp)
+	var out []string
+	for _, e := range resp.Chunk {
+		if e.Type == "m.room.message" {
+			out = append(out, e.Content.Body)
+		}
+	}
+	return out
+}
+
+func contains(list []string, s string) bool {
+	for _, v := range list {
+		if v == s {
+			return true
+		}
+	}
+	return false
+}
+
+func sendMessage(t *testing.T, srv *setup.Server, roomID, token, txn, body string) {
+	t.Helper()
+	rec := put(t, srv, "/_matrix/client/v3/rooms/"+url.PathEscape(roomID)+"/send/m.room.message/"+txn,
+		map[string]any{"msgtype": "m.text", "body": body}, token)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("send %q: status %d: %s", body, rec.Code, rec.Body.String())
+	}
+}
+
+func TestFederationEndToEnd(t *testing.T) {
+	if testing.Short() {
+		t.Skip("starts two servers")
+	}
+	nodes := newFederation(t, "hs-a.example", "hs-b.example")
+	a, b := nodes["hs-a.example"].srv, nodes["hs-b.example"].srv
+
+	aliceToken := registerThrough(t, a, "alice")
+	bobToken := registerThrough(t, b, "bob")
+
+	rec := post(t, a, "/_matrix/client/v3/createRoom", map[string]any{
+		"preset": "public_chat", "name": "Across", "room_alias_name": "across",
+	}, aliceToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("createRoom: %d %s", rec.Code, rec.Body.String())
+	}
+	roomID, _ := decode[map[string]any](t, rec)["room_id"].(string)
+
+	// Bob joins by alias: the alias is resolved by asking A, then the join
+	// goes through A.
+	rec = post(t, b, "/_matrix/client/v3/join/"+url.PathEscape("#across:hs-a.example"), map[string]any{}, bobToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("remote join: %d %s", rec.Code, rec.Body.String())
+	}
+	if got, _ := decode[map[string]any](t, rec)["room_id"].(string); got != roomID {
+		t.Fatalf("joined %q, want %q", got, roomID)
+	}
+
+	// Alice hears of the join without any queue involved: it went
+	// through her server.
+	rec = getWithToken(t, a, "/_matrix/client/v3/rooms/"+url.PathEscape(roomID)+"/joined_members", aliceToken)
+	if !strings.Contains(rec.Body.String(), "@bob:hs-b.example") {
+		t.Fatalf("A's joined members lack bob: %s", rec.Body.String())
+	}
+
+	// Messages in both directions go through the queues.
+	sendMessage(t, a, roomID, aliceToken, "a1", "hello from A")
+	eventually(t, "A's message on B", func() bool {
+		return contains(messageBodies(t, b, roomID, bobToken), "hello from A")
+	})
+	sendMessage(t, b, roomID, bobToken, "b1", "hello from B")
+	eventually(t, "B's message on A", func() bool {
+		return contains(messageBodies(t, a, roomID, aliceToken), "hello from B")
+	})
+
+	// Remote profile lookup.
+	rec = getWithToken(t, b, "/_matrix/client/v3/profile/@alice:hs-a.example", bobToken)
+	if rec.Code != http.StatusOK {
+		t.Errorf("remote profile: %d %s", rec.Code, rec.Body.String())
+	}
+
+	// Switching A's federation off: B's next message cannot be delivered,
+	// and B records the failure. Switching it back on and clearing the
+	// backoff delivers it.
+	if err := a.Settings().SetFederationEnabled(t.Context(), false); err != nil {
+		t.Fatal(err)
+	}
+	a.FederationModule().Stop()
+	sendMessage(t, b, roomID, bobToken, "b2", "while A is away")
+	eventually(t, "B to record A as failing", func() bool {
+		ds, err := b.FederationModule().Queue().Destinations(t.Context())
+		if err != nil {
+			return false
+		}
+		for _, d := range ds {
+			if d.ServerName == "hs-a.example" && d.Failures > 0 && d.QueuedPDUs > 0 {
+				return true
+			}
+		}
+		return false
+	})
+	if contains(messageBodies(t, a, roomID, aliceToken), "while A is away") {
+		t.Fatal("a message reached A while its federation was off")
+	}
+
+	// The admin API shows the backlog and the backoff.
+	root, err := b.Users().CreateAccount(t.Context(), userapi.NewAccountRequest{
+		Localpart: "root", Password: "sUp3rs3kr1t", Admin: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	session, err := b.Users().CreateSession(t.Context(), userapi.SessionRequest{Localpart: root.Localpart})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rec = getWithToken(t, b, "/_warp/admin/v1/federation/destinations", session.AccessToken)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET destinations: %d %s", rec.Code, rec.Body.String())
+	}
+	var listing struct {
+		Running      bool `json:"running"`
+		Destinations []struct {
+			ServerName string `json:"server_name"`
+			Failures   int    `json:"failures"`
+			QueuedPDUs int    `json:"queued_pdus"`
+		} `json:"destinations"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &listing); err != nil {
+		t.Fatal(err)
+	}
+	if !listing.Running || len(listing.Destinations) == 0 ||
+		listing.Destinations[0].ServerName != "hs-a.example" || listing.Destinations[0].Failures == 0 {
+		t.Errorf("destinations = %s", rec.Body.String())
+	}
+
+	if err := a.Settings().SetFederationEnabled(t.Context(), true); err != nil {
+		t.Fatal(err)
+	}
+	if err := a.FederationModule().Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	if err := b.FederationModule().Queue().ResetBackoff(t.Context(), "hs-a.example"); err != nil {
+		t.Fatal(err)
+	}
+	eventually(t, "the held message on A", func() bool {
+		return contains(messageBodies(t, a, roomID, aliceToken), "while A is away")
+	})
+}
+
+func TestFederationEndpointsAreGated(t *testing.T) {
+	srv := newSigningServer(t, nil)
+	for _, path := range []string{
+		"/_matrix/key/v2/server",
+		"/_matrix/federation/v1/version",
+	} {
+		if rec := get(t, srv, http.MethodGet, path); rec.Code != http.StatusNotFound {
+			t.Errorf("%s with federation off = %d, want 404", path, rec.Code)
+		}
+	}
+
+	if err := srv.Settings().SetFederationEnabled(t.Context(), true); err != nil {
+		t.Fatal(err)
+	}
+	rec := get(t, srv, http.MethodGet, "/_matrix/key/v2/server")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("key server with federation on = %d", rec.Code)
+	}
+	if name, _ := decode[map[string]any](t, rec)["server_name"].(string); name != "warp.example" {
+		t.Errorf("key response server_name = %q", name)
+	}
+
+	// An unsigned request to an authenticated endpoint is refused.
+	rec = get(t, srv, http.MethodGet, "/_matrix/federation/v1/event/$abc")
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("unsigned /event = %d, want 401", rec.Code)
+	}
+}
+
+// writeSelfSignedCert writes a certificate for 127.0.0.1 and its key, and
+// returns their paths and a pool that trusts the certificate.
+func writeSelfSignedCert(t *testing.T) (string, string, *x509.CertPool) {
+	t.Helper()
+	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tmpl := &x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject:      pkix.Name{CommonName: "warp.example"},
+		NotBefore:    time.Now().Add(-time.Hour),
+		NotAfter:     time.Now().Add(time.Hour),
+		IPAddresses:  []net.IP{net.ParseIP("127.0.0.1")},
+		KeyUsage:     x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:  []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+	}
+	der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &priv.PublicKey, priv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	keyDER, err := x509.MarshalECPrivateKey(priv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	certPath, keyPath := filepath.Join(dir, "cert.pem"), filepath.Join(dir, "key.pem")
+	if err := os.WriteFile(certPath, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(keyPath, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER}), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cert, err := x509.ParseCertificate(der)
+	if err != nil {
+		t.Fatal(err)
+	}
+	pool := x509.NewCertPool()
+	pool.AddCert(cert)
+	return certPath, keyPath, pool
+}
+
+func TestFederationListenerServesTLS(t *testing.T) {
+	certPath, keyPath, pool := writeSelfSignedCert(t)
+	srv := newSigningServer(t, func(c *config.Config) {
+		c.Listen.Address = "127.0.0.1:0"
+		c.Listen.FederationAddress = "127.0.0.1:0"
+		c.Listen.TLSCertFile = certPath
+		c.Listen.TLSKeyFile = keyPath
+		c.Federation.Enabled = true
+		c.Database.ConnectionString = "file:" + filepath.ToSlash(filepath.Join(t.TempDir(), "warp.db"))
+	})
+
+	ctx, cancel := context.WithCancel(t.Context())
+	done := make(chan error, 1)
+	go func() { done <- srv.Run(ctx) }()
+	defer func() {
+		cancel()
+		<-done
+	}()
+
+	var addr string
+	for range 200 {
+		if addr = srv.FederationAddr(); addr != "" {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if addr == "" {
+		t.Fatal("the federation listener never started")
+	}
+	if !srv.FederationModule().Running() {
+		t.Error("Run did not start the federation module with federation on")
+	}
+
+	client := &http.Client{Transport: &http.Transport{TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12}}}
+	resp, err := client.Get("https://" + addr + "/_matrix/key/v2/server")
+	if err != nil {
+		t.Fatalf("GET over TLS: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("key server over TLS = %d", resp.StatusCode)
+	}
+
+	// The runtime switch stops the module while Run is serving.
+	if err := srv.Settings().SetFederationEnabled(t.Context(), false); err != nil {
+		t.Fatal(err)
+	}
+	if srv.FederationModule().Running() {
+		t.Error("switching federation off did not stop the module")
+	}
+	if err := srv.Settings().SetFederationEnabled(t.Context(), true); err != nil {
+		t.Fatal(err)
+	}
+	if !srv.FederationModule().Running() {
+		t.Error("switching federation back on did not start the module")
+	}
+}
+
+func TestFederationListenerNeedsACertificate(t *testing.T) {
+	cfg := config.Default()
+	cfg.Global.ServerName = "warp.example"
+	cfg.Listen.FederationAddress = ":8448"
+	if err := cfg.Validate(); err == nil || !strings.Contains(err.Error(), "tls_cert_file") {
+		t.Errorf("Validate = %v, want a complaint about the certificate", err)
+	}
+}

server/internal/setup/routes.go

@@ -14,10 +14,10 @@ import (
 // actually uses from it work. Accounts, sessions, devices, profiles,
 // account data, rooms and — with Phase 4 — the event stream all do, which
 // is enough for a client to be used. What is still missing is end-to-end
-// encryption (Phase 7), media (Phase 6), push (Phase 8) and federation
-// (Phase 5); a client discovers each of those from the endpoint it needs
-// rather than from this list, which is why their absence does not make a
-// version listed here a lie.
+// encryption (Phase 7), media (Phase 6) and push (Phase 8); a client
+// discovers each of those from the endpoint it needs rather than from this
+// list, which is why their absence does not make a version listed here a
+// lie.
 var SpecVersions = []string{"v1.13", "v1.14"}
 
 // UnstableFeatures advertises MSC support. Simplified Sliding Sync
@@ -62,6 +62,9 @@ func (s *Server) routes() *httputil.Router {
 	r.Handle("GET /.well-known/matrix/server", s.federation.ProtectFunc(s.handleWellKnownServer))
 
 	s.clientAPI.RegisterRoutes(r)
+	if s.fedAPI != nil {
+		s.fedAPI.RegisterRoutes(r)
+	}
 	s.adminAPI.RegisterRoutes(r)
 
 	r.HandleFunc("GET /healthz", s.handleHealth)

server/internal/setup/server.go

@@ -5,6 +5,7 @@ package setup
 
 import (
 	"context"
+	"crypto/tls"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -18,6 +19,7 @@ import (
 	"github.com/dariuszjaniak/warp/server/internal/clientapi"
 	"github.com/dariuszjaniak/warp/server/internal/config"
 	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/federationapi"
 	"github.com/dariuszjaniak/warp/server/internal/httputil"
 	"github.com/dariuszjaniak/warp/server/internal/matrix/signing"
 	"github.com/dariuszjaniak/warp/server/internal/metrics"
@@ -46,11 +48,30 @@ type Server struct {
 	clientAPI *clientapi.ClientAPI
 	adminAPI  *adminapi.AdminAPI
 
+	// The federation components. All nil when the server started without
+	// a signing key, because nothing that federates can work without one.
+	fedClient *federation.Client
+	keyRing   *federation.KeyRing
+	fedModule *federationapi.Module
+	fedAPI    *federationapi.Server
+
+	// tlsConfig serves the federation listener; nil when there is none.
+	tlsConfig *tls.Config
+
+	// running is set while Run is serving. The federation switch only
+	// starts and stops the module while it is: a server that was built and
+	// never run must not leave a queue running behind it.
+	running atomic.Bool
+
 	handler http.Handler
 
 	// addr is the address Run is listening on; empty until then.
 	addr atomic.Pointer[string]
 
+	// fedAddr is the TLS federation listener's address while Run is
+	// serving one; empty otherwise.
+	fedAddr atomic.Pointer[string]
+
 	// ownsDB is false when the caller supplied the database and will close
 	// it itself.
 	ownsDB bool
@@ -69,6 +90,13 @@ type Options struct {
 	// Only tests and `warp migrate` use it: a real server must be able to
 	// sign.
 	SkipSigningKey bool
+
+	// FederationResolve replaces server discovery, and FederationTLS the
+	// outbound TLS configuration. Tests that run several servers in one
+	// process use them to point server names at local listeners whose
+	// certificates they trust.
+	FederationResolve federation.ResolveFunc
+	FederationTLS     *tls.Config
 }
 
 // New builds the server: storage, migrations, settings, routes. It does not
@@ -128,12 +156,24 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 		settingsService.FederationEnabled,
 		federation.NewPolicy(cfg.Federation.Allowlist, cfg.Federation.Denylist),
 	)
-	// Phase 5 replaces this with starting and stopping the federation
-	// module; for now it is the audit trail for a runtime toggle.
+	// The switch starts and stops the federation module. The gate and the
+	// client read the switch on every request and need no telling.
 	settingsService.Subscribe(func(snap settings.Snapshot) {
 		log.Info("federation switch applied", "enabled", snap.FederationEnabled)
+		if s.fedModule != nil && s.running.Load() {
+			s.fedModule.Apply(context.Background(), snap.FederationEnabled)
+		}
 	})
 
+	if cfg.Listen.FederationAddress != "" {
+		cert, err := tls.LoadX509KeyPair(cfg.Listen.TLSCertFile, cfg.Listen.TLSKeyFile)
+		if err != nil {
+			_ = s.closeDB()
+			return nil, fmt.Errorf("load the federation listener's certificate: %w", err)
+		}
+		s.tlsConfig = &tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12}
+	}
+
 	s.users, err = userapi.New(userapi.Options{
 		ServerName:           cfg.Global.ServerName,
 		Store:                s.db.Users(),
@@ -159,8 +199,40 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 	// The notifier is built first and handed to both: it is the
 	// roomserver's emit stage and the syncapi's wake-up, which is exactly
 	// the seam Phase 3 left for this.
+	//
+	// Federation hangs off the same key. The client and the key ring are
+	// built whether or not the switch is on — they refuse everything while
+	// it is off — and the outbound queue is a second listener on the
+	// roomserver's emit stage next to the notifier.
 	if s.signingKey != nil {
 		notifier := syncapi.NewNotifier()
+		emit := &fanout{}
+		emit.add(notifier)
+
+		clientTLS := opts.FederationTLS
+		if clientTLS == nil {
+			if clientTLS, err = federationTLS(cfg.Federation.TLSCAFile); err != nil {
+				_ = s.closeDB()
+				return nil, err
+			}
+		}
+		s.fedClient = federation.NewClient(federation.ClientOptions{
+			ServerName: cfg.Global.ServerName,
+			Key:        s.signingKey,
+			Resolve:    opts.FederationResolve,
+			TLSConfig:  clientTLS,
+			Enabled:    settingsService.FederationEnabled,
+			Policy:     s.federation.Policy(),
+		})
+		s.keyRing = federation.NewKeyRing(federation.KeyRingOptions{
+			ServerName: cfg.Global.ServerName,
+			Key:        s.signingKey,
+			Store:      s.db.Federation(),
+			Client:     s.fedClient,
+			Notaries:   cfg.Federation.TrustedKeyServers,
+			Validity:   cfg.Federation.KeyValidityPeriod,
+			Logger:     log,
+		})
 
 		s.rooms, err = roomserver.New(roomserver.Options{
 			ServerName:        cfg.Global.ServerName,
@@ -168,7 +240,9 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 			Profiles:          s.users,
 			SigningKey:        s.signingKey,
 			FederationEnabled: settingsService.FederationEnabled,
-			Notifier:          notifier,
+			Notifier:          emit,
+			Remote:            s.fedClient,
+			Keys:              s.keyRing,
 			Logger:            log,
 		})
 		if err != nil {
@@ -176,6 +250,17 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 			return nil, err
 		}
 
+		queue := federationapi.NewQueue(federationapi.QueueOptions{
+			ServerName: cfg.Global.ServerName,
+			Store:      s.db.Federation(),
+			Sender:     s.fedClient,
+			Rooms:      s.rooms,
+			Policy:     s.federation.Policy(),
+			Logger:     log,
+		})
+		emit.add(queue)
+		s.fedModule = federationapi.NewModule(queue, log)
+
 		s.sync, err = syncapi.New(syncapi.Options{
 			ServerName:      cfg.Global.ServerName,
 			Rooms:           s.rooms,
@@ -191,10 +276,36 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 			_ = s.closeDB()
 			return nil, err
 		}
+		s.sync.SetOutbound(federationapi.NewEDUs(queue, s.rooms))
+
+		s.fedAPI, err = federationapi.NewServer(federationapi.ServerOptions{
+			ServerName: cfg.Global.ServerName,
+			Gate:       s.federation,
+			Keys:       s.keyRing,
+			Rooms:      s.rooms,
+			Ephemeral:  s.sync,
+			Profiles:   s.users,
+			Store:      s.db.Federation(),
+			Logger:     log,
+		})
+		if err != nil {
+			_ = s.closeDB()
+			return nil, err
+		}
 	} else {
 		log.Warn("started without a signing key: rooms and /sync are unavailable")
 	}
 
+	// The interfaces below are left nil rather than set to a nil pointer
+	// when there is no federation: a nil *federation.Client in an
+	// interface is not a nil interface, and would be called.
+	var remoteProfiles clientapi.RemoteProfiles
+	var fedStatus adminapi.FederationStatus
+	if s.fedClient != nil {
+		remoteProfiles = s.fedClient
+		fedStatus = federationStatus{module: s.fedModule}
+	}
+
 	s.clientAPI, err = clientapi.New(clientapi.Options{
 		ServerName:         cfg.Global.ServerName,
 		ClientBaseURL:      cfg.ClientBaseURL(),
@@ -203,6 +314,7 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 		Sync:               s.sync,
 		Settings:           settingsService,
 		Federation:         s.federation,
+		RemoteProfiles:     remoteProfiles,
 		Registration:       cfg.Registration,
 		RateLimit:          cfg.ClientAPI.RateLimit,
 		TrustXForwardedFor: cfg.ClientAPI.TrustXForwardedFor,
@@ -214,13 +326,14 @@ func New(ctx context.Context, cfg *config.Config, opts Options) (*Server, error)
 	}
 
 	s.adminAPI, err = adminapi.New(adminapi.Options{
-		ServerName: cfg.Global.ServerName,
-		Users:      s.users,
-		Rooms:      s.rooms,
-		Settings:   settingsService,
-		Federation: s.federation,
-		Database:   s.db,
-		Logger:     log,
+		ServerName:       cfg.Global.ServerName,
+		Users:            s.users,
+		Rooms:            s.rooms,
+		Settings:         settingsService,
+		Federation:       s.federation,
+		FederationStatus: fedStatus,
+		Database:         s.db,
+		Logger:           log,
 	})
 	if err != nil {
 		_ = s.closeDB()
@@ -292,29 +405,65 @@ func (s *Server) SigningKey() *signing.KeyPair { return s.signingKey }
 // Run listens and serves until ctx is cancelled, then shuts down
 // gracefully: it stops accepting connections and gives in-flight requests
 // up to listen.shutdown_timeout to finish.
+//
+// With listen.federation_address set there are two listeners, the plain
+// one and a TLS one for other servers, serving the same handler: what a
+// request may reach is decided by the gate and the routes, not by which
+// port it came in on. The federation module is started here rather than
+// in New, so that a server that is built and never run leaves nothing
+// running behind it, and is stopped before the listeners close.
 func (s *Server) Run(ctx context.Context) error {
 	listener, err := net.Listen("tcp", s.cfg.Listen.Address)
 	if err != nil {
 		return fmt.Errorf("listen on %s: %w", s.cfg.Listen.Address, err)
 	}
+	listeners := []net.Listener{listener}
+	if s.tlsConfig != nil {
+		fedListener, err := net.Listen("tcp", s.cfg.Listen.FederationAddress)
+		if err != nil {
+			_ = listener.Close()
+			return fmt.Errorf("listen on %s: %w", s.cfg.Listen.FederationAddress, err)
+		}
+		listeners = append(listeners, tls.NewListener(fedListener, s.tlsConfig))
+	}
 
 	addr := listener.Addr().String()
 	s.addr.Store(&addr)
 	defer s.addr.Store(nil)
 
-	httpServer := &http.Server{
-		Handler:           s.handler,
-		ReadHeaderTimeout: s.cfg.Listen.ReadHeaderTimeout,
-		ReadTimeout:       s.cfg.Listen.ReadTimeout,
-		WriteTimeout:      s.cfg.Listen.WriteTimeout,
-		IdleTimeout:       s.cfg.Listen.IdleTimeout,
-		MaxHeaderBytes:    s.cfg.Listen.MaxHeaderBytes,
-		ErrorLog:          slog.NewLogLogger(s.log.Handler(), slog.LevelDebug),
-		BaseContext:       func(net.Listener) context.Context { return ctx },
+	newHTTPServer := func() *http.Server {
+		return &http.Server{
+			Handler:           s.handler,
+			ReadHeaderTimeout: s.cfg.Listen.ReadHeaderTimeout,
+			ReadTimeout:       s.cfg.Listen.ReadTimeout,
+			WriteTimeout:      s.cfg.Listen.WriteTimeout,
+			IdleTimeout:       s.cfg.Listen.IdleTimeout,
+			MaxHeaderBytes:    s.cfg.Listen.MaxHeaderBytes,
+			ErrorLog:          slog.NewLogLogger(s.log.Handler(), slog.LevelDebug),
+			BaseContext:       func(net.Listener) context.Context { return ctx },
+		}
 	}
 
+	s.running.Store(true)
+	defer s.running.Store(false)
+	if s.fedModule != nil {
+		if s.settings.FederationEnabled() {
+			if err := s.fedModule.Start(ctx); err != nil {
+				s.log.Error("could not start federation", "error", err)
+			}
+		}
+		defer s.fedModule.Stop()
+	}
+
+	federationAddr := ""
+	if len(listeners) > 1 {
+		federationAddr = listeners[1].Addr().String()
+		s.fedAddr.Store(&federationAddr)
+		defer s.fedAddr.Store(nil)
+	}
 	s.log.Info("warp is listening",
 		"address", addr,
+		"federation_address", federationAddr,
 		"server_name", s.cfg.Global.ServerName,
 		"version", buildinfo.String(),
 		"database", s.db.Driver(),
@@ -323,32 +472,52 @@ func (s *Server) Run(ctx context.Context) error {
 		"presence", s.cfg.Sync.Presence,
 	)
 
-	errCh := make(chan error, 1)
-	go func() {
-		err := httpServer.Serve(listener)
-		if errors.Is(err, http.ErrServerClosed) {
-			err = nil
-		}
-		errCh <- err
-	}()
+	servers := make([]*http.Server, len(listeners))
+	errCh := make(chan error, len(listeners))
+	for i, l := range listeners {
+		servers[i] = newHTTPServer()
+		go func(srv *http.Server, l net.Listener) {
+			err := srv.Serve(l)
+			if errors.Is(err, http.ErrServerClosed) {
+				err = nil
+			}
+			errCh <- err
+		}(servers[i], l)
+	}
 
+	var serveErr error
 	select {
-	case err := <-errCh:
-		return err
+	case serveErr = <-errCh:
+		// One listener failing takes the server down: half a homeserver
+		// is worse than a restart.
 	case <-ctx.Done():
 	}
 
 	s.log.Info("shutting down", "timeout", s.cfg.Listen.ShutdownTimeout)
+	if s.fedModule != nil {
+		s.fedModule.Stop()
+	}
 	shutdownCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), s.cfg.Listen.ShutdownTimeout)
 	defer cancel()
 
-	if err := httpServer.Shutdown(shutdownCtx); err != nil {
-		s.log.Warn("graceful shutdown timed out; closing connections", "error", err)
-		_ = httpServer.Close()
+	for _, srv := range servers {
+		if err := srv.Shutdown(shutdownCtx); err != nil {
+			s.log.Warn("graceful shutdown timed out; closing connections", "error", err)
+			_ = srv.Close()
+		}
 	}
-	// Serve has returned by now; surface anything it reported.
-	if err := <-errCh; err != nil {
-		return err
+	// Every Serve has returned by now; surface anything they reported.
+	remaining := len(servers)
+	if serveErr != nil {
+		remaining--
+	}
+	for range remaining {
+		if err := <-errCh; err != nil && serveErr == nil {
+			serveErr = err
+		}
+	}
+	if serveErr != nil {
+		return serveErr
 	}
 	s.log.Info("stopped")
 	return nil
@@ -356,6 +525,9 @@ func (s *Server) Run(ctx context.Context) error {
 
 // Close releases the resources New acquired.
 func (s *Server) Close() error {
+	if s.fedModule != nil {
+		s.fedModule.Stop()
+	}
 	if s.sync != nil {
 		// The typing tracker holds a timer per typing user; a server
 		// shutting down should not wait for them.
@@ -378,3 +550,17 @@ func (s *Server) closeDB() error {
 func contextWithTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
 	return context.WithTimeout(ctx, d)
 }
+
+// FederationModule exposes the federation module, or nil when the server
+// started without a signing key. Tests that never call Run start it
+// themselves.
+func (s *Server) FederationModule() *federationapi.Module { return s.fedModule }
+
+// FederationAddr reports the address of the TLS federation listener while
+// Run is serving one, or "".
+func (s *Server) FederationAddr() string {
+	if p := s.fedAddr.Load(); p != nil {
+		return *p
+	}
+	return ""
+}