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
43 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/oauth-authorization-server | GET | public | RFC 8414 — OAuth 2.0 Authorization Server Metadata. |
| /.well-known/oauth-protected-resource | GET | public | RFC 9728 — OAuth 2.0 Protected Resource Metadata. |
| /.well-known/openid-configuration | GET | public | Static OIDC-style discovery document for agent/federated-app access. |
| /.well-known/spatial-fabric | GET OPTIONS | public | RFC 8615 discovery for the worlds this instance hosts (Open Spatial Lab's labeled extension). |
| /.well-known/universal-manifest.json | GET | public | — |
| /api/federation/connect/onboarding | POST | public | account, so it is the only instance that may create one or mint an onboarding |
| /api/federation/connect/payout | POST | public | authority. A sovereign instance (e.g. Spirit) whose job payout must reach a |
| /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/entity-status | POST | public | Federation entity-status probe — the ORIGIN half of the reconciliation lane |
| /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 PATCH | 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/stripe/checkout | POST | public | Stripe PLATFORM. Sovereign instances hold Stripe CONNECT accounts, so they |
| /api/federation/stripe/refund | POST | public | so it is the only instance that may create a refund. |
| /api/federation/users/search | GET | public | - Let a peer app (e.g. Spirit / rivr-group, rivr-locale-commons, etc.) |
| /api/spatial-web/tags/[scheme]/[id] | GET OPTIONS | public | `GET /api/spatial-web/tags/{scheme}/{id}` — a scanned tag resolves to its public object: where its record and manifest live. |
| /api/spatial-web/traveller | POST | gated | `POST /api/spatial-web/traveller` — the presentation a signed-in person carries through a portal: |
| /api/universal-manifest/[kind]/[id] | GET | public | — |
| /wow/portal/[portalId] | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/portal/{portalId}` — a portal with its destination (the report's decision 1). |
| /wow/spatial/[spatialID] | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/spatial/{spatialID}` — a hosted world's composition graph. |
| /wow/spatial/[spatialID]/node/[nodeId] | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/spatial/{spatialID}/node/{nodeId}` — one node of a hosted world, with the live state of the physical object standing at it. |
| /wow/user | POST OPTIONS | public | WoWAPI 0.0.1 User aspect — `POST /wow/user`: a traveller presents their Universal Manifest at the door of a world this instance hosts. |
| /wow/user/[userId] | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/user/{id}` — who is present in the world this instance hosts, by receipt id or subject. |
| /wow/view/[viewId] | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/view/{viewId}` — a named arrival inside a hosted world. |
| /wow/world | GET OPTIONS | public | WoWAPI 0.0.1 `GET /wow/world` — this instance's primary hosted world. |
See also the full /api/federation REST reference and the Federation & SSO identity wiki page.