Federation

When you need it

Federation is not a scaling mechanism. One deployment handles an organization, and two cost you a synchronization problem. Reach for it only when a boundary you cannot move forces the split: separate ownership, a data-residency region, or a network that will never let one side reach the other.

What crosses the wire is the event log, not memory. Events carry ids, kinds, actors and bounded scope metadata (subject_id, kind, trust, status), never observation or claim content. Credentials are never replicated.

Registering a peer

curl -X POST http://127.0.0.1:8787/v1/federation/peers \
  -H "authorization: Bearer $TITEN_API_KEY" -H 'content-type: application/json' \
  -d '{"name":"eu-node","endpoint":"https://eu.example.com/v1/federation/push",
       "shared_secret":"a-long-enough-shared-secret","direction":"bidirectional"}'

{ "data": { "peer_id": "fpeer_ea73516ceccf4454964273750e70af14", "name": "eu-node",
    "endpoint": "https://eu.example.com/v1/federation/push",
    "direction": "bidirectional", "status": "active",
    "created_at": "2026-07-30T10:49:13.337Z" } }

shared_secret must be at least 16 characters. direction is push, pull or bidirectional, and it is enforced per operation: a push-only peer refuses pull with 403 Peer is configured for push only., and the mirror case holds. One endpoint per organization; a duplicate returns 409.

POST /v1/federation/peers/:id/suspend is the stop switch behind “a scope can stop sharing”: a suspended peer’s pull and push both return 403 Peer is not active. before any event is read or written. The refusal happens ahead of the log, so it shows up as an absence of new rows rather than a rejection entry.

Filters bound both directions

A filter says what may leave and what may be accepted, per resource type.

curl -X POST http://127.0.0.1:8787/v1/federation/peers/$PEER/filters \
  -H "authorization: Bearer $TITEN_API_KEY" -H 'content-type: application/json' \
  -d '{"resource_type":"claim","include_kinds":"claim.materialized","min_trust":"verified"}'

Pull, push, and the cursor

POST /v1/federation/pull returns local events after the peer’s stored cursor, capped at 200 per call, filtered, and advances the cursor.

{ "data": { "events": [ { "id": "evt_4ff141c765f045d6824c7e2b66732eb5",
        "kind": "claim.materialized",
        "actor_id": "agent_8df7b8699a0945488ceb3d4b104006d6",
        "resource_type": "claim",
        "resource_id": "claim_f3963d7b876143f5bfc8230db2757067",
        "payload": { "subject_id": "user_rama", "kind": "procedural",
          "status": "active", "trust": "verified" },
        "created_at": "2026-07-30T10:38:59.741Z" } ],
    "cursor": "evt_0b6e9d6a45ae4e72b46eebe6e692320d" } }

The returned cursor is the last event scanned, not the last event sent. Notice that the id above appears nowhere in events. Filtered-out events are permanently behind the cursor and will not be re-offered on the next pull, which keeps the scan bounded. Widening a filter therefore does not retroactively release history: the peer sees the change from that point forward.

POST /v1/federation/push accepts a batch from a remote deployment. It needs two independent proofs.

const body = JSON.stringify({ peer_id: peerId, events });
const key = await crypto.subtle.importKey(
  'raw', new TextEncoder().encode(sharedSecret),
  { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
);
const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(body));
const hex = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, '0')).join('');

await fetch('http://127.0.0.1:8787/v1/federation/push', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.TITEN_API_KEY}`,
    'content-type': 'application/json',
    'x-titen-peer-signature': `sha256=${hex}`,
  },
  body,
});

The API key proves the caller may use the endpoint. The signature over the raw body proves the batch came from the peer that was registered. Without the second one, any authorized caller inside the organization could inject records attributed to a remote deployment. A missing header and a wrong signature are both 403 FORBIDDEN before any event is read. The message names which of the two happened, Peer signature header is required. or Peer signature is invalid.:

{ "error": { "code": "FORBIDDEN", "message": "Peer signature header is required." } }

The comparison is constant-time. Each event in the batch reports its own outcome, so a bad event does not fail the batch:

The log

GET /v1/federation/log requires a peer_id query parameter and returns newest first. limit defaults to 50 and is capped at 200.

{ "data": { "entries": [ { "id": "flog_7675e7c5751a492092cd7c5a3c6fb23f",
        "direction": "sent", "resource_type": "claim",
        "resource_id": "evt_75cc5557bff34da8a9fd298c6231ac63",
        "status": "success", "detail": null,
        "created_at": "2026-07-30T10:49:22.138Z" } ] } }

Both directions land here: sent rows from pull, received rows from push, including the rejected ones with the reason in detail. This is the record that answers “did that subject’s events ever leave this deployment?”.

What is not settled

Federation ships as eight working routes, and the protocol around them is not finished. The threat model registers forged or replayed federation events as TM-16, with verification pending a separate protocol review, and does not approve the protocol. Two gaps in the current code:

Run it between deployments you control, on a network you trust, and read the log. If you need one deployment serving several teams, use workspaces and memberships instead.

Next