Federation Guide

Federation turns a deployment into a network. Treat it as a Layer 2 responsibility backed by Layer 1 rules.

Minimum Checklist

• publish the public server name peers should use
• keep the signing key stable across restarts
• decide whether federation is open, moderated, or allow-list only
• monitor federation queue pressure separately from client API latency

Reference Configuration

server_name: chat.example.org
listen:
  - type: federation
    bind: 0.0.0.0
    port: 8448
federation:
  mode: allow_list
  allow:
    - newsroom.example.net
    - research.collective
  key_rotation_interval: 24h
  metadata_padding: enabled
  outbound_retry_backoff: exponential
security:
  signing_key_path: /data/keys/server_signing_key.pem
  trusted_root_store: system

Discovery Flow

Remote nodes discover your server through /.well-known/eccp/server, then negotiate supported capabilities. Keep the discovery document small and cache-friendly.

Operational Guidance

Rate Limits

Apply separate quotas to client sync requests and cross-server transactions. Federation spikes should not starve local users.

Metadata Reduction

ECCP can pad event envelopes and reduce room-name exposure for Shadow Rooms. Enable those features only if your observability pipeline still supports incident response.

Bridge Boundaries

Run bridges with separate credentials. Do not colocate bridge secrets with the primary federation signing key.