Federation protocol
Sovereign instances (person, group, locale, region) run independently and federate 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
allowHistoricalto catch up after >7-day downtime; push/import routes stay strict. - FK-safe actors. Imported events bind
actorIdto 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. All instances delegate password verification to
app.rivr.social/api/federation/sso/issuewith a local bcrypt fallback.
Endpoints
26 federation, universal-manifest, and discovery endpoints — generated from the route tree.
| Endpoint | Methods | Access | Description |
|---|---|---|---|
| /.well-known/matrix/client | GET OPTIONS | public | — |
| /.well-known/matrix/server | GET OPTIONS | public | — |
| /.well-known/mcp | GET | public | — |
| /.well-known/openid-configuration | GET | public | Static OIDC-style discovery document for agent/federated-app access. |
| /.well-known/universal-manifest.json | GET | public | — |
| /api/federation/discover | GET | public | - Resolve an identity cue (email, handle, persona id, node id, or domain) |
| /api/federation/email/send | POST | public | - Let a trusted peer Rivr instance delegate outbound transactional |
| /api/federation/events | GET | public | GET /api/federation/events?since={sequence}&limit={limit} |
| /api/federation/events/export | POST | public | - Queues and returns exportable federation events for the authenticated local node. |
| /api/federation/events/import | POST | public | - Ingests event batches from a peer into the authenticated local node context. |
| /api/federation/manifest | GET | public | Manifest expiry: 30 days from issuance. |
| /api/federation/mutations | POST | public | F4 — sender-node Ed25519 signature over the mutation envelope |
| /api/federation/node-status | GET | public | Node-level federation status for this instance, consumed by the post composer |
| /api/federation/peers | POST | public | - Accepts authenticated requests to connect/register a peer node relationship. |
| /api/federation/query | GET | public | Maximum resources returned per query to prevent oversized responses. |
| /api/federation/registry | GET POST OPTIONS | public | GET /api/federation/registry |
| /api/federation/registry/[agentId] | GET | public | UUID v1–v5 validation pattern. |
| /api/federation/remote-auth | POST | public | - Accept a signed SSO assertion minted by the global identity authority |
| /api/federation/remote-password/verify | POST | public | Server-to-server credential verification for a locally-homed account. |
| /api/federation/signup | POST | public | Federation signup endpoint — sovereign instances delegate new-account |
| /api/federation/sso/issue | POST | public | - Accept an email-or-handle + password (or, in a later revision, a |
| /api/federation/sso/land | GET | public | Federation SSO landing consumer: the sovereign side of the global→home |
| /api/federation/sso/session-handoff | GET | public | - When global redirects a sovereign-homed user to their home instance |
| /api/federation/status | GET | public | — |
| /api/federation/users/search | GET | public | - Let a peer app (e.g. Spirit / rivr-group, rivr-locale-commons, etc.) |
| /api/universal-manifest/[kind]/[id] | GET | public | — |
See also the full /api/federation REST reference and the Federation & SSO identity wiki page.