Federation Architecture

Cloudillo is designed as a federated system where independent instances communicate to share content, enable collaboration, and maintain user sovereignty. Like email, any Cloudillo server can communicate with any other – users don’t need to be on the same instance.

Core Principles

No central authority: Each instance operates autonomously
User sovereignty: Users choose where their data lives
Explicit consent: Relationship-based sharing with cryptographic verification
Standard protocols: HTTP/HTTPS, WebSocket, JWT, DNS-based identity
Content addressing: SHA256 ensures integrity across instances

Inter-Instance Communication

Request Module

A shared request client handles all federated HTTP calls. It exposes generic get/post methods that take an id_tag and a path, resolve the target host as https://cl-o.{id_tag}, and attach a federation bearer token when the call needs authentication (see ProxyToken Authentication). Public variants (get_public, post_public, get_noauth) skip the token for endpoints that are open to any instance, such as the profile/key endpoint GET /api/me.

DNS Is for Provisioning, Not Routing

“DNS-based identity” above does not mean peers are discovered through DNS records. Peer location is prefix-derived: the host is cl-o. prepended to the validated id_tag, with no lookup of any Cloudillo-specific record. Ordinary DNS resolution then happens inside TLS, exactly as it would for any other HTTPS URL.

Where Cloudillo does use DNS directly is domain-ownership validation during provisioning. cloudillo-core’s resolver performs true recursive resolution from the ICANN root nameservers — deliberately not trusting a local caching resolver — and validate_domain_address walks the CNAME chain (bounded at 8 hops) to confirm that the domain being claimed really points at this instance. That is a one-time proof of control, not a per-request routing step.

Federation Flow

When Alice (on instance A) follows Bob (on instance B):

Instance A                          Instance B
  |                                   |
  |--- GET /api/me ------------------>| (Fetch Bob's profile)
  |<-- 200 OK {profile} --------------|
  |                                   |
  |--- Create FLLW action token ---   |
  |                                   |
  |--- POST /api/inbox -------------->| (Send follow action)
  |    {token: "eyJhbGc..."}         |
  |                                   |--- Queue for async verification
  |<-- 201 Created -------------------|
  |                                   |--- Verify signature, check perms, store