Federation Model

Each operator pins the other's kernel in its own trust store

Each operator runs its own trust domain with chio trust serve, on its own hosts, under its own key custody. The partner's card is the first contact: chio partner add partner-card.json --name partner reads the partner's org DID, trust-control URL, authority key history, receipt-signer keys, and status resolve URL, and pins the partner's kernel key, 9b07…d31c in the Quickstart. The partner adds your card the same way, so each kernel holds its own pin.

chio partner add partner-card.json --name partner

partner    did:chio:z6MkpA7…c2T, named partner
kernel     9b07…d31c, pinned from its card
control    https://kernel.halden.example, authority key history and status resolve URL from the card
transport  https, mutual TLS
handshake  verified both ways, tier silver, rotation deadline in 12 h

The two kernels then run the peer handshake. Each signs a challenge that binds both kernel ids, a fresh nonce, and the time; the receiver verifies the response against its pin, negotiates protocol capabilities, and checks the declared conformance tier against local policy. The verified peer record keeps the key, its rotation deadline, and any manifest references on the receiver's side.

MissingTrustAnchor refuses a peer whose card was never added, and UnexpectedPeerKey refuses a declared key that differs from the pin, before any peer state is written. A new key reaches the trust store only through a new card or the partner's authority key history, so exchange cards over a channel you already authenticate. Rejecting a replayed handshake belongs to the transport or the receiving host; the exchange binds a nonce and keeps no seen-nonce store of its own.

Read more in Peer Handshake, which runs the exchange and lists every refusal.

A treaty names what crosses, and the serving kernel admits each action

A treaty lists the actions two operators cooperate on. Both kernels sign it.

import { Computer } from "@chio-protocol/sdk";

const project = await Computer.open("quickstart");
const partner = await Computer.connect("partner");
const treaty = await project.treaty({
  partner: partner,
  actions: ["workspace.read", "workspace.write", "model.invoke", "merge"],
  expiresIn: "7d",
});
console.log(treaty.describe());

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

from chio import Computer

project = Computer.open("quickstart")
partner = Computer.connect("partner")
treaty = project.treaty(
    partner=partner,
    actions=["workspace.read", "workspace.write", "model.invoke", "merge"],
    expires_in="7d",
)
print(treaty.describe())

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

use chio::{Computer, Treaty};

let project = Computer::open("quickstart").await?;
let partner = Computer::connect("partner").await?;
let treaty = project
    .treaty(
        Treaty::with(&partner)
            .actions(["workspace.read", "workspace.write", "model.invoke", "merge"])
            .expires_in("7d"),
    )
    .await?;
println!("{}", treaty.describe());

treaty           trt-01aa…4c19, signed by both kernels
participants     you · partner (did:chio:z6MkpA7…c2T)
action           you       them      admitted as
workspace.read   allow     allow     either kernel admits under its own policy
workspace.write  allow     allow     either kernel admits under its own policy
model.invoke     allow     allow     charged at your door
merge            co-sign   co-sign   both kernels sign
expires          in 7 days

Each kernel computes the intersection of both operators' governance ladders for every action, so the stricter requirement wins on both sides. A co-sign action such as merge needs both kernels' signatures. Every other action is admitted by the kernel that serves it, under that kernel's own policy, and a resource is charged at its owner's door.

A grant issued under the treaty travels to the partner's agents, and those agents present a DPoP proof of possession with it at your door. A copied grant without the holder's proof carries no authority.

Read more in Treaties and Proof of possession.

Federated work and shared evidence travel on two paths

The cross-kernel federation profile moves signed trust, quorum, admission, reputation, and qualification contracts between two kernels and gates the receipts they co-sign. Bilateral evidence sharing hands a scoped, signed slice of one operator's receipt log to a named partner. Both fail closed: federation data lets an operator see further, and it becomes runtime trust only after the receiver's explicit local activation and review.

Both paths cross over HTTPS by default, authenticated by mutual TLS or a signature over each body. Operators who want a direct connection add the optional iroh lane, authenticated QUIC through self-hosted relays, which carries the signals, revocation, and co-sign lanes. The compliance mappings for NIST AI RMF, the EU AI Act, and ISO/IEC 42001 build on the evidence path.

Read more in Trust Activation Exchange and Share Evidence with a Partner.

Every contract that crosses is a signed document with a registered schema

Three families of signed documents carry every contract. The federation profile, docs/standards/CHIO_FEDERATION_PROFILE.md, defines five root contracts: chio.federation-activation-exchange.v1, chio.federation-quorum-report.v1, chio.federation-open-admission-policy.v1, chio.federation-reputation-clearing.v1, and chio.federation-qualification-matrix.v1. Section 10.2 of the protocol specification adds five more: chio.evidence_export_manifest.v1, chio.evidence_export_disclosure_notice.v1, chio.federation-policy.v1, chio.federated-evidence-share.v1, and chio.federated-delegation-policy.v1. The wire schemas in the schema registry are the third family.

The pages that own the contracts group them by what they settle between the two operators:

• Who the peer is. Operator identity, the peer handshake, peer pins, and the two-org worked example.
• What the relationship permits. Treaties, the trust activation exchange, open admission and stake, and quorum and anti-eclipse.
• What carries a signature across. Federation authority, cross-operator delegation, the revocation oracle, and revocation checkpoints.
• What flows back. Evidence sharing, receipt lineage and buyer packets, and reputation clearing.
• How bytes move. Iroh transport, the transport directory, transport lanes, and limits and backpressure.
• Who stands behind a bearer token. Enterprise identity and the provider registry and SCIM.
• Running and assuring it. Operations, refusal codes, assurance, and the evidence exchange walkthrough.

Revocation and status reach a partner as signed state it checks locally

A receiver enforces revocation from the verified state it holds. Once an update arrives and is installed, every later check refuses the affected capability and its descendants. Signed revocation feeds and catch-up move that state between operators, so propagation takes the time a feed takes to arrive.

A deployment with a revocation view also refuses snapshots outside the view's configured freshness bound; without one, validation reads the local revocation store. Each kernel pulls its partner's issuer-signed lifecycle status from the status resolve URL and keeps it for its TTL, and a status past its TTL fails closed until a fresh one arrives. Revoking a treaty ends every grant issued under it, delegated grants included.

Key rotation is not a revocation. The partner's new authority key extends the history its card carries, so the pin follows the rotation without an outage, and a receipt signed under a previous key still verifies offline.

Read more in Bilateral Receipts, which covers feed publication, subscription, and freshness.

Two operators declare every relationship, one peer at a time

Federation connects operators who chose each other. Four consequences shape what a deployment can expect from it:

• Declared, pinned relationships. Each relationship is declared by its operators and pinned peer by peer; Chio runs no permissionless global identity network.
• Local reputation. Imported reputation is attenuated, tagged with its provenance, and kept apart from the receiver's native local record. No universal score exists.
• Discovery without admission. A discovered public identity document supports interoperability. Authority widens only through a card, a treaty, and the receiver's own admission.
• Defined credential transport. Credentials travel in the Chio projected-passport family and the narrow OID4VP verifier profile, in place of DIDComm or generic wallet messaging.

Next: pin your first partner