d3chat Federation Protocol

Source of truth:

• d3chat/backend/app/federation/inbox.py
• d3chat/backend/app/federation/client.py
• d3chat/backend/app/federation/discovery.py
• d3chat/backend/app/federation/handlers.py
• d3chat/backend/app/federation/relay.py
• d3chat/backend/app/crypto/signing.py

Protocol Objectives

Federation in d3chat provides:

1. cross-server channel/user interoperability
2. signed request authenticity
3. replay resistance
4. duplicate-event suppression
5. bounded-abuse controls on peer traffic

It is designed as a signed event relay protocol over HTTP, not a distributed consensus system.

Server Identity and Discovery

Well-known endpoint

Every server exposes:

GET /.well-known/d3chat-server

Returns:

• domain
• signing_key_public
• api_base_url
• protocol_version

Discovery flow

When a server needs unknown peer metadata:

1. query local servers table
2. if absent/stale, fetch well-known over HTTPS (fallback HTTP for development)
3. cache and persist peer metadata

Discovery is cached in-memory with TTL and persisted in database.

Request Signing Model

Signature payload

Signing payload is:

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + SHA256(BODY)

Signed with Ed25519 private key. Signature is base64-encoded.

Required headers

• X-D3Chat-Origin
• X-D3Chat-Timestamp
• X-D3Chat-Signature

Verification steps (inbound)

1. validate required headers
2. parse and validate timestamp
3. enforce replay window
4. enforce per-origin rate limit
5. discover origin server and fetch verify key
6. verify signature over canonical payload

Replay and Dedup Semantics

Replay window

Requests are rejected if timestamp exceeds ±5 minute window.

Event dedup

Each event carries event_id. Inbound handler uses Redis SET NX with TTL (24h) to suppress duplicates.

Federation Endpoints

POST /federation/inbox

Single event ingress route for all event types.

General event envelope:

{
  "event_id": "<unique-id>",
  "origin_server": "chat.example.com",
  "timestamp": "<iso8601-or-compatible>",
  "type": "message.relay",
  "...": "event-specific payload"
}

GET /federation/user-lookup?username=<name>

Signed lookup endpoint for remote servers to resolve local users.

Response example:

{
  "found": true,
  "username": "alice",
  "user_id": "<uuid>",
  "server_domain": "chat.example.com"
}

Event Types and Handling

channel.invite

Behavior:

1. resolves local invitee
2. resolves/creates remote inviter user
3. creates federated channel if missing
4. adds memberships
5. publishes channel.new to invitee websocket topic

message.relay

Behavior:

1. resolves/creates remote sender
2. verifies channel existence and sender membership
3. inserts message row with origin metadata
4. publishes local message.new

sender_key.distribute

Behavior:

1. upserts sender key for remote device/channel
2. publishes sender_key.new event for local clients to refetch keys

channel.join / channel.leave

Behavior:

• mutates membership state for remote user in local channel context

Outbound Relay Behavior

Message relay

On local message creation in federated channel:

1. compute remote server list from remote members
2. construct signed event payload
3. POST to remote inbox with timeout

Sender key relay

On sender-key distribution in federated channel:

• emit signed sender_key.distribute to remote peers

Invite relay

When adding remote user to local channel:

• emit signed channel.invite to remote user’s server

Reliability and Failure Model

Expected failures

• remote server unreachable
• signature rejection due to clock drift or stale keys
• partial peer fanout success

Current behavior

• logs failures and returns boolean success on sender side
• no durable retry queue in current implementation

For stronger delivery guarantees, production operators may add deferred retry queues and idempotency tracking outside current baseline.

Security and Abuse Controls

1. origin-level request rate limits on inbox path
2. replay window enforcement
3. explicit signature verification against discovered peer key
4. event dedup to suppress replayed payload effects

Residual risk areas:

• peer key rotation handling maturity
• long network partitions without retry queue
• deployment misconfiguration (clock skew, TLS termination issues)

Mobile Client Implications

Clients do not sign federation directly, but must correctly handle resulting cross-server effects:

• remote users appearing via lookup
• federated channel flags
• relay-originated messages and sender-key updates
• eventual consistency timing across peers

Recommended client strategy:

1. treat realtime events as hints
2. re-fetch authoritative channel/message slices on reconnect
3. tolerate duplicate or reordered relay arrivals using id dedup and created_at ordering