Federation protocol

This sovereign group instance runs independently and federates into the hosted global app for aggregation, discovery, and cross-instance interaction. Federation uses a PeerMesh protocol built on Ed25519-signed events authenticated against a peer registry — the signature, not an asserted node id, is the principal. See Auth models for how this sits alongside session and MCP-token auth.

Trust model

• Signed events. Each federated mutation is an Ed25519-signed event. The receiver verifies the signature against the sender's registered peer key before materializing anything.
• Peer registry. Instances register each other (/api/federation/peers) with a shared secret + public key; unknown peers cannot inject events.
• Replay protection. Signature + nonce dedup reject replays. A locally-initiated pull-sync cron may set allowHistorical to catch up after >7-day downtime; push/import routes stay strict.
• FK-safe actors. Imported events bind actorId to the materialized local agent id, never the raw remote external id. If a resource event arrives before its owner, the importer projects a minimal private placeholder agent that the next agent upsert upgrades in place.
• Credential authority. This instance delegates password verification to app.rivr.social/api/federation/sso/issue with a local bcrypt fallback.

Endpoints

The federation surface lives under /api/federation/** (registry, mutations, sync, remote-auth), with the Universal Manifest served at /.well-known/universal-manifest.json only — there is no /api/universal-manifest route on this instance — alongside the rest of discovery under /.well-known/**. These prefixes are auth-optional (peer signatures gate the mutating routes) per PUBLIC_API_PREFIXES in src/lib/route-access.ts.

See also the Federation & SSO identity wiki page for the user-facing side of sovereign homes and cross-instance identity.