Federation Overview

Why federation

A local Chio deployment governs calls with a capability, kernel policy, and signed receipt. Federation extends those controls when an agent calls a partner's tools or a partner verifies Chio evidence without treating the issuing organization as a universal trust root.

• Portable identity: an agent keypair should be the same name from Org A's perspective and Org B's perspective, without either side operating a shared directory.
• Portable delegation: a capability issued in Org A should be presentable at Org B and evaluated against Org B's local policy without a prior account provisioning step.
• Portable revocation: when Org A revokes a capability, Org B should stop honoring it on the next enforcement decision, with bounded staleness and no silent carry-over.
• Portable reputation: evidence of good behavior in Org A should be visible to Org B as an attenuated signal, not a shared score.

Self-Certifying Identifiers

A Chio identity uses an Ed25519 keypair. The did:chio method encodes the public key directly into the identifier, so basic resolution never requires a registry lookup.

did:chio:{64-hex-character-ed25519-public-key}

Example:
did:chio:bff663535a5cf58658cc38595d20dc4501f6dfc076ddf07e20571d413a3ceb5a

The method-specific identifier is the public key. A party that knows the DID can verify signatures with that key without contacting another service. Federation therefore does not require a shared identity provider for identity verification.

The resolved DID Document is deterministic:

• @context points at the W3C DID v1 context.
• A single verificationMethod entry named #key-1, shape Ed25519VerificationKey2020, with publicKeyMultibase base58btc encoding.
• authentication and assertionMethod both reference #key-1.
• Optional ChioReceiptLogService entries point at the operator's receipt query endpoint, so a counterparty can pull downstream evidence.

$ chio did resolve \
    --public-key 3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09 \
    --receipt-log-url https://trust.org-a.example/v1/receipts

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09",
  "verificationMethod": [
    {
      "id": "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09",
      "publicKeyMultibase": "z6MkiYpYWyUNXHzHZsgmMPy4xypRKqdJjgnmAmNMtN2DDTBW"
    }
  ],
  "authentication": [
    "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09#key-1"
  ],
  "assertionMethod": [
    "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09#key-1"
  ],
  "service": [
    {
      "id": "did:chio:3cdb65ef41fc1f109bcedbd8cfbd792e0851c6f2acbe5008576400bf91d04d09#receipt-log",
      "type": "ChioReceiptLogService",
      "serviceEndpoint": "https://trust.org-a.example/v1/receipts"
    }
  ]
}

The method identifier is the hex public key itself, so resolution is a local derivation with no registry lookup and no network call. Passing --did instead of --public-key takes the fully-qualified form and produces the same document. Dropping --receipt-log-url drops the service array; the rest is unchanged.

Verification is not admission. Self-certification settles whether a signature checks out; it says nothing about whether the key behind it should be let in. Chio keeps those questions apart. Trust establishment is bilateral, key pinning is per-peer, and revocation propagates by gossip. There is no master key, no validator election, and no quorum threshold on the routine path.

That leaves each operator one question the protocol deliberately does not answer: which kernel public keys do I accept a first handshake from? KernelTrustExchange resolves an incoming envelope against either a pre-configured trusted peer or one it has already pinned, and fails closed with MissingTrustAnchor when neither matches. Seeding that first entry is an operational procedure, not a wire format: operators bind it to an industry consortium roster, an out-of-band PKI, operator-mediated key exchange that stops scaling somewhere in the dozens of peers, or a sector regulator publishing the canonical roster. Chio enforces the anchor you configure. It does not issue one, and it does not reconcile two operators who chose differently, so a handshake completes only once each side already holds the other's kernel public key, pre-configured or previously pinned. A declared key that does not match the one held fails with UnexpectedPeerKey rather than being negotiated. This anchor is the key you admit at first contact, not chio-anchor, which publishes checkpoint roots to external chains.

Agent Passports as Verifiable Credentials

A Chio Agent Passport is a signed bundle of receipts, reputation projections, and enterprise identity provenance. Its native delivery format is compact CHIO passport data. For partners that require a standards-based envelope, Chio projects the same passport data into either application/dc+sd-jwt (SD-JWT VC) or jwt_vc_json (JWT VC JSON).

Claim families inside a passport projection:

• Always disclosed: iss, sub, vct, cnf, chio_passport_id, chio_subject_did, chio_credential_count.
• Selectively disclosable (SD-JWT lane only): chio_issuer_dids, chio_merkle_roots, chio_enterprise_identity_provenance.
• Optional: chio_passport_status sidecar pointing at the issuer's lifecycle endpoint.

Two Federation Paths

Chio provides two cross-operator 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 shares a scoped, signed slice of one operator's receipt log to a named partner. Both are fail-closed: federation data lets an operator see further, but it becomes runtime trust only after explicit local activation and review.

Cross-Kernel Federation

The federation profile covers listing, trust activation, governance, open-market, and portable-reputation features. It defines five root contracts, each with a fixed schema ID and a validator that rejects invalid input.

On top of the contracts, two kernels co-sign the receipts that cross the boundary and pin each other's keys:

• DSSE bilateral co-signed receipts: a ChioReceipt carries a detached dual signature and a DSSE in-toto envelope, verified against pinned peer keys, a receipt store, a revocation oracle, and a bound treaty.
• Signed peer-pinning handshake: a challenge/response exchange negotiates protocol capabilities and a conformance tier and sets an explicit key-rotation deadline before either side pins the other's signing key.
• Governance-ladder treaty intersection: two or more kernels compute the action-class intersection they share under a treaty scope, then admit a specific cross-boundary action against it with verified evidence.
• Revocation-epoch and pheromone gossip: signed revocation roots and reputation deposits move between bilateral peers over per-peer push queues with a bounded catch-up protocol.

# Compute the governance-ladder intersection two kernels share.
$ chio federation treaty intersect \
    --treaty-scope ./treaty-scope.json \
    --manifest ./org-a-ladder.json \
    --manifest ./org-b-ladder.json \
    --now-unix-ms 1767225600000 \
    --report ./ladder-intersection.json

# Admit one cross-boundary action against that intersection.
$ chio federation treaty admit \
    --treaty-scope ./treaty-scope.json \
    --ladder-intersection ./ladder-intersection.json \
    --expected-ladder-intersection-sha256 <hex> \
    --action-class-id billing.charge \
    --evidence receipt=<artifact-sha256> \
    --now-unix-ms 1767225600000 \
    --report ./admission-report.json

# Publish a signed revocation checkpoint from local authority state.
$ chio federation authority checkpoint \
    --profile ./authority-profile.json \
    --revocations ./revocations.json \
    --signing-keys ./authority-signing-keys.json \
    --out ./revocation-checkpoint.json

Bilateral Evidence Sharing

The narrower lane shares a scoped slice of one operator's receipt log with a named partner. A signed bilateral federation policy states the issuer, the partner, and the export scope (capability, agent subject, and time window) plus an expiry and whether full checkpoint coverage is required. The policy is a signed document, produced with chio evidence federation-policy create and attached to an export through --federation-policy.

The policy carries the read boundary, so --tenant or --admin-all is required when the policy is signed rather than when it is used. --since, --until, and --expires-at are Unix seconds, and an --expires-at already in the past is refused at signing time.

$ chio evidence federation-policy create \
    --output ./org-a-to-org-b.json \
    --signing-seed-file ./federation-signing.seed \
    --issuer org-a \
    --partner org-b \
    --capability cap-billing-q2 \
    --admin-all \
    --since 1767225600 \
    --until 1775001599 \
    --expires-at 4102444800 \
    --require-proofs \
    --purpose "quarterly billing evidence for org-b review"

federation policy created
output:              ./org-a-to-org-b.json
issuer:              org-a
partner:             org-b
signer_public_key:   4cb5abf6ad79fbf5abbccafcc269d85cd2651ed4b885b5869f241aedf0a5ba29
require_proofs:      true

# Export under that policy; it carries the scope and the read boundary,
# so the export needs no --tenant or --admin-all of its own.
$ chio evidence export \
    --federation-policy ./org-a-to-org-b.json \
    --receipt-db ./receipts.sqlite3 \
    --output ./org-b-share

# On the partner side, import the verified package for later delegation.
# Import also needs a destination: --receipt-db, or --control-url.
$ chio evidence import \
    --receipt-db ./org-b-receipts.sqlite3 \
    --input ./org-b-share

Import prints a six-line summary of what it took in: share_id, issuer, partner, signer_public_key, tool_receipts, and capability_lineage (crates/platform/chio-control-plane/src/evidence_export.rs). The counts are the receiving side's record of the share, not a grant of anything.

The package those commands write and read, the offline verifier that checks it without a store or a network, and what an import does to the receiving node are Evidence Export.

The trust control plane also includes the open-admission registry, and it keeps two things apart that are easy to run together. The signed, exportable half is FederatedOpenAdmissionPolicyArtifact, which carries governingOperatorId, allowedAdmissionClasses, stakeRequirements, a charter and fee-schedule reference, and the two local-review booleans (crates/trust/chio-federation/src/open_admission.rs). The anti-sybil knobs are not in it. A rate limit, a proof-of-work bit count, and a bond-backed-only flag live on FederationAdmissionAntiSybilControls, and a minimum reputation score on the enclosing FederationAdmissionPolicyRecord (crates/platform/chio-control-plane/src/federation_policy.rs).

Operators manage those records and dry-run a peer's admission through chio trust federation-policy. upsert, list, get, and delete take a local registry file through --federation-policies-file when --control-url is not set, and refuse when neither is given. evaluate has no local path at all: it requires --control-url and a --control-token, because anti-sybil state is enforced centrally (crates/products/chio-cli/src/admin.rs). Its --input is a FederationAdmissionEvaluationRequest.

Cross-Org Delegation

A cross-boundary action is admitted when its action class lies in the treaty intersection the two operators share and the inbound capability chain verifies. The chain part is straightforward because capability chains are already content-signed and monotonically attenuated; the admission part is the treaty check.

1. An agent in Org A already holds a capability issued by Org A's authority. The capability carries an ed25519 signature from an issuer key Org B trusts through the activated federation relationship and the peer-pinning handshake.
2. The agent signs a delegated child capability for a downstream worker whose subject key lives in Org B. The child strictly attenuates scope, expiry, and budget relative to the parent.
3. The Org B kernel receives a tool call carrying the delegated chain. It verifies the parent signature against its pinned copy of Org A's authority keys, verifies the child signature against the parent subject, and then evaluates the action against the treaty.
4. The action is admitted only if its action class is inside the shared ladder intersection and its evidence verifies. The kernel emits a receipt and either dispatches or denies.

Federated Revocation

When Org A revokes a capability, Org B stops honoring it at its next enforcement decision. Chio uses signed, append-only revocation feeds that a counterparty's trust control plane subscribes to and merges idempotently, backed by a bounded catch-up protocol and a staleness ceiling for an unreachable peer. The feed mechanics, publishing, subscription, and enforcement are documented in Bilateral Receipts.

Imported Reputation Is Attenuated

Chio treats imported reputation as an operator-visible signal. When Org B imports an evidence package from Org A, the local comparison view reports native reputation and imported trust side by side, with explicit provenance, a policy echo of the import-time bilateral controls, and conservative defaults (proofless shares rejected, stale signals expired, an attenuated composite score). The mechanics, provenance fields, policy echo, and scoring are documented in Portable Reputation.

Agent Passport as Portable Reputation

The Agent Passport is the container that makes reputation portable. It bundles the subject's receipt roots, the operator's attestation of reputation signals, and optional enterprise identity provenance from the issuing organization. The counterparty verifies the passport signature, verifies each referenced Merkle root against the local copy of the issuer's receipt log, and then applies its local verifier policy to decide whether to treat the passport as input to an authorization decision.

• A presented passport is not a bearer token. It does not itself authorize a tool call; it feeds the policy evaluation that decides whether a capability issued under the passport's subject key is honored.
• Multi-issuer composition is supported through the bounded CrossIssuerPortfolio profile. A portfolio is an evidence container, not a synthetic new trust root.
• Lifecycle state is pulled from the issuer's signed status sidecar. PassportLifecycleState has five members and only active is healthy; stale, superseded, revoked, and not-found fail closed at the verifier.

Enterprise Identity Federation

"Identity federation" has a second, unrelated meaning in Chio: letting an enterprise's existing OIDC, SAML, or SCIM identity resolve to a stable Chio subject at a bearer-authenticated MCP HTTP edge. The same enterprise principal converges on the same Chio subject across sessions, so receipt attribution follows the human or workload behind the token rather than a random per-session key.

• chio mcp serve-http admits OAuth bearer tokens by JWT verification (--auth-jwt-public-key, or discovery via --auth-jwt-discovery-url) or by opaque-token introspection (--auth-introspection-url).
• Authenticated principals are canonicalized as oidc:<issuer>#sub:<sub>, or oidc:<issuer>#oid:<oid> under the Azure AD profile (--auth-jwt-provider-profile azure-ad).
• --identity-federation-seed-file derives a stable Chio subject key from that principal and issues session capabilities against it. The mapping is exposed through authContext.method.enterpriseIdentity and authContext.method.federatedClaims.

# Serve an MCP edge that maps Azure AD principals to stable Chio subjects.
$ chio mcp serve-http \
    --policy ./policy.yaml \
    --server-id wrapped-http \
    --listen 127.0.0.1:8931 \
    --auth-jwt-discovery-url https://login.example.com/tenant/v2.0/.well-known/openid-configuration \
    --auth-jwt-provider-profile azure-ad \
    --auth-jwt-audience chio-mcp \
    --identity-federation-seed-file ./identity-federation.seed \
    --admin-token <admin-token> \
    -- python3 ./mock_server.py

Trust Control Plane Federation

The open-admission registry and enterprise-provider registry are part of the trust control plane. Each operator runs its own Chio trust service. The record-management subcommands take either a local registry file or a remote service through the global --control-url; evaluate is the one that takes only the remote service.

Topology

A minimal bilateral federation has two trust control planes and a shared public-key registry that each side pins locally. The registry is not a central authority; it is a mirror each operator maintains of the other's trusted keys, fed by signed snapshots.

Non-Goals

• A permissionless global identity network. Every relationship is bilateral and operator-declared.
• A universal reputation score. Imported reputation is attenuated, provenance-tagged, and never merged into native local truth.
• Automatic widening of authority on the strength of a discovered public identity document. Discovery supports interoperability, not admission.
• DIDComm or generic wallet messaging. The supported transport is the documented Chio projected-passport family plus the narrow OID4VP verifier profile.

For the specific compliance frameworks that benefit from this federation posture, continue with NIST AI RMF, EU AI Act, and ISO/IEC 42001.