Skip to main content
Version: v0.9.0a2
Spec

Spec-05-Federation-Trust

4 min readSpec contributor · Node operatorDraft · v0.9.0aN

What this spec defines

Peer admission, peer verification, replication authorization, per-hop scope enforcement, source-trust handling, and federation audit boundaries.

Extraction status​

This file contains the ADR-010 prose extraction for federation trust. It intentionally does not define manifest shape (Spec-04-Manifests), capability-token structure (Spec-06-Capability-Tokens), quarantine moderation (Spec-08-Quarantine-Garden), replay windows (Spec-11-Replay-Protection), or transport hardening (Spec-10-Hardening).

Peer declaration​

A peer declaration binds a node id, reachable node URL, public federation key, and allowed replication scopes.

A node MUST NOT replicate with a peer until that peer is registered and verified.

PeerDeclaration {
  node_id:        URI
  node_url:       URL
  public_key:     base64url Ed25519 public key
  allowed_scopes: FactScope[]
  signed_at:      ISO 8601 UTC
  signature:      base64url Ed25519 signature
}

The signature covers the canonical declaration body. The public key can be confirmed through the peer's manifest and discovery document.

Verification​

Peer verification MUST:

  1. Resolve the peer's discovery document.
  2. Resolve or verify the peer manifest per Spec-04-Manifests.
  3. Verify the declaration signature against the declared public key.
  4. Confirm the declared node id and public key match the resolved peer evidence.
  5. Transition the peer to active only after all required checks pass.

Rejected peers MUST NOT receive or send replicated facts. Implementations SHOULD retain rejection reason and timestamp for audit.

Replication authorization​

Replication is authorized by the intersection of all applicable scopes.

The fact's own scope, the source peer's allowed scopes, the current peer relationship's allowed scopes, and any peer-token or capability constraints required by the route. Nodes MUST NOT return facts outside that intersection. Nodes MUST reject inbound facts whose scope exceeds the sender's authorization.

Pull vs push replication​

Mode
Status
Behavior
Pull
default
The requesting peer provides a cursor and a limit; the responding node returns facts after that cursor, filtered by the authorization rules above. Cursors are opaque to clients. Reusing the same cursor MUST be idempotent: receivers must not create duplicate facts when the same page is ingested more than once.
Push
optional
Low-latency. Nodes that advertise push support MUST apply the same inbound validation, deduplication, scope checks, and audit logging as pull ingestion. Nodes that do not support push SHOULD omit the push endpoint from discovery or return 405 Method Not Allowed.

Scope propagation​

Scope enforcement is per-hop.

A relay node MUST NOT escalate a fact's scope when serving another peer. Company-scoped facts received from one peer MUST NOT be re-federated to another peer unless a future accepted spec explicitly defines an operator opt-in path. Relay nodes SHOULD retain origin metadata sufficient to enforce the original peer's allowed-scope boundary when serving later peers.

Source trust​

Federation trust may compute a source-trust score from manifest validity, attestation evidence, peer history, and configured trust mode. Trust scores are local derived values; peers MUST NOT be allowed to provide a source-trust value that the receiver accepts as authoritative.

Advanced trust scoring remains subject to calibration and should be kept separate from basic peer admission and scope authorization.

Federation audit​

Nodes SHOULD audit federation events that materially affect trust or data flow:

Peer registered

Peer verified

Peer rejected

Fact accepted

Fact rejected

Scope violation

Replay violation

Manifest/signature failure

Verification failure.

Audit record shape belongs to Spec-09-Audit-Log.

Out of scope​

This spec does not define:

Manifest schema

Or transparency-log evidence.

Capability-token wire format

Quarantine operations

Promote/reject.

mTLS certificate requirements

Replay nonce windows

Content-addressed fact IDs