Federated relay fabric

WireGuard gives plexsphere its data plane: one encrypted mesh per Domain, with the control plane distributing keys, peers, and topology while plexd agents run the tunnels. What WireGuard does not give us is reachability — two nodes behind NAT cannot find each other without help. Today that help is a tenant-supplied bridge node that relays over WireGuard, and when no reachable bridge exists the peer pair is silently unreachable.

This document proposes evolving that bridge relay-fallback into a provider-operated, steerable relay fabric, and then — on top of the same fabric — a federation layer that lets two independent plexsphere instances interconnect. It is a forward-looking proposal: none of it is implemented, and it is written as a standalone argument rather than folded into the mesh or bridge bounded-context references.

The idea in one shift

Today a relay is a mesh member: the bridge node holds mesh keys and forwards WireGuard traffic as a peer. That model cannot scale to a provider point of presence that serves many tenants, because a single node cannot be a key-holding member of every tenant's mesh without breaking the Domain isolation boundary.

The one shift this proposal rests on: a relay becomes a dumb, authenticated packet mover that never terminates WireGuard and cannot decrypt. It forwards opaque encrypted frames keyed by destination identity. This is the model Tailscale's DERP relays use. It is what makes a relay (a) multi-tenant — one point of presence serves every Domain without joining any mesh, (b) provider-operable, and (c) the natural substrate for federation, because a frame from another instance is just another opaque frame to forward. Everything else follows from that shift.

Where this sits in plexsphere today

Concern	Today	Owned by
Encrypted data plane	one WireGuard mesh per Domain	plexd agents
Reachability / NAT traversal	per-peer relay-fallback through a tenant bridge node	internal/mesh/peers/
Relay wire format	none — the relay is a second WireGuard endpoint the agent dials	left to WireGuard
Node addressing	mesh IP from the Domain CIDR, per-Domain and operator-set	internal/identity/tenancy/
Top-level boundary	Domain — nothing crosses it; no inter-instance concept exists	internal/identity/

Two facts from this baseline drive the rest of the design. First, the relay has no plexsphere-defined protocol — so we are free to define one. Second, mesh CIDRs are per-Domain and uncoordinated across instances, so two instances can both hand out the same range; federation will face overlapping address spaces.

Target architecture

 Plane              What runs there                                  Controlled by
 ─────────────────  ───────────────────────────────────────────────  ──────────────────────
 Tenant data plane  WireGuard — end-to-end encryption + segmentation  plexd agents
 Reachability       relay fabric — opaque, authenticated relays;      control-plane assignment
                    key-derived addressing (collision-free)           (region / residency aware)
 Federation         peering agreement between instance A and B;       control-plane to
                    scoped, audited, trust anchors exchanged          control-plane (pairwise)

WireGuard stays the policy and segmentation layer, unchanged. The relay fabric is the reachability layer the control plane steers. The federation layer punches explicit, audited holes through the Domain boundary between two instances.

The provider-operated relay fabric

A new bounded context (proposed name relayfabric; transit and edge are the naming alternatives) owns:

• Relay — a provider-operated packet mover at a point of presence. A platform resource, not a tenant node; it authenticates to the control plane and carries region, capacity, and health.
• RelaySession — an authenticated forwarding association between two endpoints through a relay.
• RelayAssignment — which relay or relays a node uses. This evolves today's per-peer assignment by adding region and data-residency awareness.
• the relay wire protocol — plexsphere's first data-plane protocol: a lean authentication handshake to the relay using the node's key, then opaque frame forwarding by destination identity. DERP is the reference design; we define our own minimal protocol rather than adopt DERP wholesale, so it maps onto our identity model and we control its evolution.

Steering is where the fabric earns its keep, and where it differs from an emergent overlay: the assigner is region- and policy-aware, so the control plane can express constraints such as "this Domain's traffic may only transit relays in a given jurisdiction." The reachability state machine that already drives bridge selection feeds relay liveness.

The existing tenant-supplied bridge relay does not go away; it becomes one relay kind (bring-your-own) alongside the provider fabric, under one assignment abstraction.

This phase is shippable on its own — provider points of presence, no tenant bridge required, controlled paths — and de-risks cross-instance federation.

Cross-instance federation

A second new context (federation) treats another plexsphere instance as a first-class, sovereign peer. It owns:

• FederationPeer — a remote instance.
• PeeringAgreement — what may cross: which Domains or Projects on each side may interconnect, in which direction, under which policy.
• TrustAnchor — the exchanged signing keys that let each side verify the other.
• FederatedCatalog — a projection of the remote endpoints reachable under the agreement.

It is an anti-corruption layer and a context map at the deployment level, plus a control-plane-to-control-plane protocol (signed) that exchanges relay endpoints, the federated catalog, peering policy, and revocations. Two problems define this phase.

Addressing and the collision problem

Mesh CIDRs are per-Domain and uncoordinated across instances, so two instances both hand out, say, 100.64.0.0/10; when a node in instance A talks to a node in instance B their mesh IPs collide. The proposal sidesteps this rather than coordinating CIDRs globally: the federation plane is not addressed by mesh IP at all. Every participating endpoint gets a globally-unique address derived from its public key — keys are already globally unique — and the relay forwards on that key-address. The local mesh IP rides inside the WireGuard payload and is meaningful only within its own Domain. The boundary maps the key-address to the local mesh IP per agreement. This is collision-free by construction and needs no global allocator.

This is the one idea worth borrowing from Yggdrasil — cryptographic addressing — adopted deliberately and under our control, without adopting Yggdrasil's emergent routing.

Trust and what crosses

Each instance is a sovereign control plane; Domain is its hard isolation boundary. Federation must therefore be explicit, scoped, and audited, never an implicit full mesh of every node on both sides. A peering agreement names exactly which Projects or services may interconnect; the relay enforces the scope; every crossing is an audited event on the platform audit chain. Federation punches deliberate, recorded holes in the Domain boundary — it does not dissolve it.

The recommended trust topology is pairwise peering agreements: each instance stays sovereign and the trust graph stays explicit. A hub or a shared registry centralises trust and is a larger commitment; either can come later if the pairwise count becomes painful.

Bounded-context shape

Two new contexts, in domain-driven terms:

• relayfabric — owns Relay, RelaySession, RelayAssignment, the relay wire protocol, and region/residency metadata. It is a supplier to the existing mesh context: mesh keeps ownership of peers and pre-shared keys and consumes the relay set and wire protocol. The bring-your-own bridge relay and the provider fabric unify under one assignment abstraction.
• federation — owns FederationPeer, PeeringAgreement, TrustAnchor, and FederatedCatalog. It is a customer of relayfabric (the fabric is its interconnect substrate) and an anti-corruption layer to the remote instance's identity model.

Adding a bounded context in this repository is deliberately gated: the workspace file, the cross-context dependency deny-lists, the per-context container images, the dependency-update manifest, the code-owners file, and the layout reference all have to change in lockstep. That cost is part of the relay-fabric stage, not a follow-up.

Key design decisions

Decision	Recommendation	Rejected alternative and why
Relay data plane	a lean, plexsphere-defined opaque relay protocol, DERP as reference	adopting DERP wholesale ties us to another ecosystem's semantics; keeping the relay-as-mesh-member model cannot serve multiple tenants or federate without breaking Domain isolation
Federation addressing	a key-derived, globally-unique federation address plane	a federation-global CIDR plan with boundary NAT needs a global allocator and cross-instance coordination; routing on mesh IPs directly collides, because CIDRs are uncoordinated across instances
Federation trust topology	pairwise peering agreements	a hub or shared registry centralises trust and weakens instance sovereignty; an implicit full mesh of both instances' nodes dissolves the Domain isolation boundary

Why not Yggdrasil as the substrate

We evaluated running an existing encrypted mesh overlay as an always-on reachability underlay beneath WireGuard. It solves NAT traversal and global addressing for free, but it was rejected as the substrate for three reasons that matter to a connectivity product:

• It removes path control. Such an overlay's routing is emergent and self-arranging; it offers no guarantee that traffic follows a chosen region and no way to express data residency. Steering paths is a core reason to build this fabric, so ceding it to the underlay is self-defeating.
• Double encryption and encapsulation. The overlay is already end-to-end encrypted; WireGuard on top means two crypto and two encapsulation layers on the hot path, plus a third address plane and real maximum-transmission-unit pressure.
• Maturity. It is an early-stage project whose core routing scheme has been rewritten several times across minor versions — too movable a foundation for a base reachability layer under a service-level objective.

The relay fabric keeps the one good idea — key-derived addressing — and keeps path selection under the control plane.

Tests and documentation plan

Per the repository's four-aspect rule, each phase names all four up front:

• Unit — aggregate invariants: Relay validation, peering-agreement scoping rules, key-address derivation, and the region/residency assigner logic.
• Integration — assignment against the reachability state machine; the control-plane-to-control-plane handshake; address mapping at the boundary; the peering-uniqueness database constraints.
• E2E — chainsaw suites: a node dialing through a provider relay; two instances federating with a scoped cross-instance flow traversing the fabric; residency enforcement through a jurisdiction-restricted relay set.
• Documentation — this page is the design of record. When a phase is built, its bounded-context reference lands under docs/contexts/, a decision record under docs/explanation/adr/, and the sidebar and doc-drift gates change in the same commit.

Security and threat model

Federation widens the trust surface: cross-instance trust, and the relay as a target. The opaque-relay shift bounds a relay compromise to traffic analysis and denial of service — never content — because the relay cannot decrypt. Trust anchors are verified out of band, with an explicit revocation path. The whole surface warrants a threat-model sign-off alongside the existing security decision record, and every cross-instance crossing is recorded on the audit chain.

Status and open questions

This is a proposal at the design stage; nothing here is built. Open questions to settle before implementation:

• The bounded-context name: relayfabric, transit, or edge.
• Whether the provider fabric and the bring-your-own bridge relay share one assignment surface from day one, or converge later.
• Whether the control-plane-to-control-plane channel is synchronous request/response or an asynchronous signed event exchange.
• The exact key-address derivation, and how it binds to the existing node key and identity model.

References

• Yggdrasil network — the encrypted mesh overlay evaluated as a candidate substrate.
• Tailscale DERP servers — the opaque relay design used as the reference for the relay wire protocol.
• WireGuard — the data-plane transport this fabric carries.