atproto-tailnet

Federation

Status: off by default. Federation is not available on a standard instance. The code exists, but the service hides it unless you set FEDERATION_ENABLED=true. Keep it off for these reasons:

  • The federation data plane needs Docker. Only the legacy Headscale mode has it.
  • Cross-instance traffic is not implemented. In the coordinator stack, links carry no traffic.

When federation is off, the federation and traversal API paths return 404. The broker does not start. The dashboard hides the Federation and Traversal Policy tabs. The Rust federation endpoints also need COORD_FEDERATION_ENABLED=true. The rest of this guide describes the design and the code.

Federation connects separate mesh networks (collectives). Devices in one network can then reach devices in another network. Each side keeps full control of the routes it shares and of the users who can connect. Each side also decides to accept or reject link proposals.

Concepts

Collectives

A collective is the mesh network of a tenant, seen as a federation participant. Each collective has these items:

Collective Federation Protocol (CFP)

CFP is the wire protocol for communication between collectives. It sends JSON messages over HTTPS. Detached JWS signatures over the raw request body authenticate the messages. Each message carries a CFP-Recipient header that identifies the target collective by DID.

Federation posture

Each collective has a federation posture. The posture controls how the collective responds to inbound link requests from strangers:

Posture Behavior Route visibility
Closed Refuses all inbound link requests. The collective is invisible to federation. Hidden from parent tenants in hierarchy.
Selective Queues inbound requests for the operator to review. The operator sees the DID and proposed CIDRs of the requesting collective. The operator then accepts or rejects the request. Visible to parent tenants.
Open Is identical to selective at this time (operator approval is required). Reserved for future auto-accept under traversal policy. Visible to parent tenants.

Closed is the default for new tenants. Most production deployments must use selective.

Two more gates apply on top of the posture:

How federation works

A federation link follows this sequence:

  1. **Link request** One collective sends a `LINK_REQUEST` to another collective. The request proposes shared CIDR prefixes. It includes the DID of the sender and a signed description of the IP ranges that the sender wants to share.
  2. **Operator review** If the posture of the recipient is `selective` (or `open`), the request appears in the **Federation** tab of the recipient's dashboard. The operator reviews these items: - The DID and domain of the requesting collective - The proposed CIDR prefixes - Conflicts between the prefixes and existing routes The operator can **accept** or **reject** the request.
  3. **Session handshake** After acceptance, the accepting side starts a CFP session handshake: ``` Acceptor Requester │ │ ├── HELLO (signed) ───────────────►│ │ │ │◄────────── CHALLENGE (nonce) ────┤ │ │ ├── COMMIT (signed nonce) ────────►│ │ │ │◄───────── ESTABLISHED ──────────┤ │ │ ``` At each step, both sides verify the signatures against the public key in the DID document of the peer.
  4. **Route exchange** After the session is established, both sides exchange signed route announcements in periodic `KEEPALIVE` messages (every 30 seconds). The system imports only the prefixes that the link specifies. `filterImportedPrefixes` rejects all prefixes outside the agreed scope. The system installs imported routes as auto-approved routes for the special tag `tag:federation-relay`. The data plane then forwards the packets.
  5. **Ongoing** Each side can **revoke** the link at any time. Revocation tears down the session and removes the imported routes.

CIDR validation

The system validates the shared CIDRs before it establishes a link:

Route scoping

Routes that the system learns through federation carry scope metadata:

Scope Priority Description
Local 300 Peers within about 50 km (measured by geographic coordinates)
Regional 200 Same broad region
Global 100 Any distance

When more than one path exists to the same prefix, the coordinator selects the best route with these rules:

  1. Select the lowest measured latency (if latency data is available).
  2. If no latency data is available, select the highest scope priority plus preference score.

Setting up federation

Prerequisites

Configure posture

Set the federation posture of your collective in the Federation tab of the dashboard or with the API:

curl -X PUT https://yourdomain.com/api/tenants/<tenant-id>/federation/posture \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"posture": "selective"}'

In the Federation tab, enter the DID of the peer collective (did:web:...). Then enter the CIDR prefixes that you want to share. The system resolves the DID document of the peer and discovers the broker endpoint. Then it sends a signed LINK_REQUEST.

When a link request arrives, it appears in your Federation tab as a pending request. Review the identity of the sender and the proposed CIDRs. Then accept or reject the request.

The dashboard shows these items for each active federation link:

Click Revoke on an active link. This action sends a REVOKE message to the peer. It also tears down the session and removes all imported routes.

Sub-collective hierarchy

Tenants can form a parent/child hierarchy. The hierarchy has a maximum of two levels:

Parent collective
  ├── Child A (posture: selective)  → routes visible to parent
  ├── Child B (posture: closed)     → routes hidden from parent
  └── Child C (posture: open)       → routes visible to parent

A parent tenant sees the aggregated routes from all children that are not closed. The parent sees these routes in its route table and in streaming map updates. This structure lets a parent network provide shared infrastructure. The children keep independent control of their federation posture.

Security considerations