Federation

Instance-to-instance federation enables multiple CortexPrism instances to establish trusted relationships for cross-instance collaboration, resource sharing, and agent dispatch.

Overview

Federation allows independent CortexPrism instances to:

Share agent resources across organizational boundaries
Dispatch agents to remote instances
Establish trust relationships with pairing tokens
Maintain instance identity for audit trails

Instance Identity

Each CortexPrism instance maintains an identity in the instance_identity table:

Field	Description
`instance_id`	Unique instance UUID
`instance_name`	Human-readable instance label
`public_key`	Ed25519 public key for signature verification
`created_at`	Identity creation timestamp

Federation Peers

Trusted peers are registered in the federation_peers table:

Field	Description
`peer_id`	Unique peer identifier
`instance_id`	Remote instance UUID
`instance_name`	Remote instance display name
`pairing_token_hash`	SHA-256 hash of the pairing token
`peer_url`	Remote instance API URL
`trust_level`	`read_only` / `agent_dispatch` / `full`
`created_at`	Trust establishment timestamp
`last_seen_at`	Last heartbeat timestamp

Pairing Flow

Instance A                            Instance B
  │                                       │
  ├── Generate pairing token              │
  ├── Share token out-of-band ──────────→ │
  │                                       ├── POST /api/federation/pair
  │                                       │     { token, instance_url }
  │                                       ├── Validate token
  │                                       ├── Exchange instance metadata
  │                                       ├── Store federation_peer row
  │                                       └── Return { peer_id, trust_level }
  │                                       │
  │ ←── ACK + peer metadata ──────────────┤
  │                                       │
  ├── Store federation_peer row           │
  └── Trust established ✓                 │

API Endpoints

Method	Path	Description
`POST`	`/api/federation/pair`	Establish trust with another instance
`GET`	`/api/federation/peers`	List trusted peers
`DELETE`	`/api/federation/peers/:id`	Revoke trust relationship
`POST`	`/api/federation/generate-token`	Create a new pairing token

Trust Levels

Level	Capabilities
`read_only`	View agent status, session history (no actions)
`agent_dispatch`	Dispatch agents, query resources, forward messages
`full`	Full access including configuration and management

Security

Pairing tokens are generated with cryptographically random bytes
Tokens are SHA-256 hashed before storage — plaintext never persisted
Trust relationships can be revoked at any time by either party
All cross-instance communication uses HTTPS
Instance identity is verified via Ed25519 signatures