Auth models

RIVR authenticates three kinds of principal. Every API surface derives identity server-side from one of these — client-supplied identity, owner, signer, or wallet is never trusted to bypass server derivation.

1. Session Session

The default for the browser app. A NextAuth v5 session cookie establishes the signed-in user; server components and route handlers read it via auth() and derive the acting agent id from the session — never from request input.

• Used by: all interactive pages, most /api/** write routes, and MCP tools marked enabledFor: ["session"] (e.g. account data export, which returns the user's complete personal data set and is intentionally session-only).
• Credential authority: password verification is delegated to app.rivr.social/api/federation/sso/issue with a local bcrypt fallback, so sovereign instances can verify a global identity without holding its password.

2. MCP token MCP Token

A Bearer token presented to the MCP endpoint (POST /api/mcp). This is how agents and automations act. The instance's static AIAGENT_MCP_TOKEN authorizes an act-as context: the tool call runs as a specific actor/controller, and every invocation is written to the MCP provenance log (rivr.audit.recent).

• Used by: MCP tools marked enabledFor: ["session", "token"] — 117 of the 118 tools. See the MCP tool reference for per-tool badges.
• Discovery: /.well-known/mcp and /llms.txt advertise the endpoint; /api/mcp/authorize handles the device-authorization approval flow.
• Scope: a token call can only invoke tools whose enabledFor includes "token". Destructive, irreversible operations (e.g. account deletion) are deliberately withheld from MCP and require the interactive UI.

3. Peer signature Peer Signature

The federation trust rail. Sovereign instances exchange Ed25519-signed events authenticated against a peer registry (/api/federation/peers, /api/federation/remote-auth). The signature — not a header or an asserted node id — is the principal. Nonce + signature dedup prevent replay; imported events bind their actor to the materialized local agent id (FK-safe), never to the raw remote id.

• Used by: the federation import/push/query endpoints — see the Federation protocol page for the full endpoint list and the signed-event model.
• Catch-up: a locally-initiated pull-sync cron may set an allowHistorical flag to replay events after >7-day downtime; push/import routes stay strict.

Public (auth-optional) Public

A subset of routes is intentionally public — discovery, health, manifests, federation handshakes, Stripe webhooks, map tiles, and this docs site. These are enumerated in PUBLIC_PAGE_PREFIXES / PUBLIC_API_PREFIXES (src/lib/route-access.ts) and marked Public in the REST reference.

See also

• Federation protocol — the signed-event endpoints and trust model.
• MCP tools — per-tool auth badges.
• Federation & SSO identity (wiki) — the user-facing side of sovereign homes and cross-instance identity.