Firmiana
  • English

      • Federation

      Federation allows homeservers to communicate with each other, enabling cross-server room participation.

      Federation Endpoints

      All endpoints are under /_matrix/federation/v1/ (except invite v2).

      EndpointMethodPurpose
      /send/{txnId}PUTSend transaction (PDUs + EDUs)
      /make_join/{roomId}/{userId}GETPrepare a join event
      /send_join/{roomId}/{eventId}PUTSubmit a join event
      /make_leave/{roomId}/{userId}GETPrepare a leave event
      /send_leave/{roomId}/{eventId}PUTSubmit a leave event
      /invite/{roomId}/{eventId}PUTInvite a remote user (v2)
      /state/{roomId}GETGet room state
      /state_ids/{roomId}GETGet state event IDs
      /event_auth/{roomId}/{eventId}GETGet event auth chain
      /backfill/{roomId}GETBackfill events
      /get_missing_events/{roomId}POSTGet missing events
      /query/profileGETQuery user profile
      /query/directoryGETQuery room directory
      /query/publicRoomsGETQuery public rooms
      /query/user_devicesGETQuery user devices
      /query/keysGETQuery user keys
      /hierarchy/{roomId}GETGet space hierarchy
      /relations/{roomId}/{eventId}GETGet event relations

      Request Signing

      Every federation request is signed using the server's ed25519 signing key.

      Signing Process

      1. Build canonical JSON of the request body
      2. Compute SHA-256 hash → base64url (no padding)
      3. Build signing string: origin destination method uri ts content_hash
      4. Sign with server's private key
      5. Attach Authorization: X-Matrix origin=...,destination=...,key=...,sig=...,ts=...

      Verification

      FederationRequestSigningService.verifyRequestSignature() checks:

      • Authorization header format (X-Matrix ...)
      • Origin/destination matching
      • Clock skew (within 5 minutes)
      • Content hash integrity
      Note

      Cryptographic signature verification against remote server's public key is currently accept-all. Full verification requires fetching the remote signing key from /_matrix/key/v2/server.

      Key Cache

      FederationKeyCache caches remote server signing keys:

      • TTL: Keys cached for configurable duration
      • Negative cache: Failed key lookups cached briefly to avoid hammering
      • Notary: Query other servers for a target server's key via /_matrix/key/v2/query

      Destination Queue

      FederationDestinationQueue manages outbound transactions:

      • Exponential backoff: Failed deliveries retry with increasing delays
      • Dead detection: Mark destinations as unreachable after repeated failures
      • Transaction IDs: Monotonically increasing per destination

      EDU Processing

      Ephemeral Data Units (EDUs) carry real-time state across servers:

      EDU TypeSourcePurpose
      m.typingTypingUserRepositoryTyping notifications
      m.presencePresenceRepositoryOnline/offline status
      m.receiptReceiptRepositoryRead receipts

      Server Discovery

      GET /.well-known/matrix/server → { "m.server": "example.com:8448" }
GET /_matrix/key/v2/server → { server_name, verify_keys, valid_until_ts }

      SigningKeyService manages the local server's ed25519 key pair with automatic rotation (7-day period).