Peer Pins & Trust Bundles

Look up what a verifier pins, from the partner kernel keys its cards added to the strict trust bundle it assembles.

On this page

A peer pin is a partner kernel key your verifier trusts. Adding a partner's card pins its kernel key, and each operator adds the other's card, so each kernel keeps its own pin.

The peer pins document records the partners your kernel has pinned and handshaken with, beside the vendor signers and action classes a workflow may require. A verifier trust bundle joins those pins with four more inputs the verifier owns.

Partner cardChoose what the card does.

Adding the card pins their kernel key

chio partner add partner-card.json --name partner reads the card the partner sent: its org DID, did:chio:z6MkpA7…c2T, its trust-control URL, its authority key history, its receipt-signer keys, and its status resolve URL. Adding it pins the partner's kernel key, 9b07…d31c, in your trust store. Each operator adds the other's card, so each kernel keeps its own pin. Peer pins.

The partner card as chio partner add reads it: the five fields it carries and the kernel key adding it pins. The DID and key are the Quickstart's illustrative values. Treaty terms, transport, and the conformance evidence the handshake carries are left out.

Terminalbash

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

Output

partner    did:chio:z6MkpA7…c2T, named partner
kernel     9b07…d31c, pinned from its card

The card carries the partner's organization DID, trust-control URL, authority key history, receipt-signer keys, and status resolve URL. A key outside that history reaches your trust store only through a new card.

Synopsis

The authority assembles a verifier trust bundle from five verifier-owned inputs: the authority profile, the peer pins, the workflow intersection, the disclosure policy, and the signed revocation checkpoint. Every input comes from the verifier's own side, never from a peer.

Terminalbash

chio federation authority trust-bundle assemble \
  --profile profile.json --peer-pins peer-pins.json \
  --workflow-intersection workflow-intersection.json \
  --disclosure-policy disclosure-policy.json \
  --checkpoint checkpoint.json --out trust-bundle.json

Peer pins document

The peer pins document (chio.federation.peer-pins.v1) carries its schema id and three lists.

`schema`

stringSchema id

The document schema id.

Example"chio.federation.peer-pins.v1"

`peers[]`

arrayOne entry per handshaken peer

Each entry carries kernelId and publicKey, the kernel key the partner card pinned, and ladderManifestRef, the signed governance ladder the peer's handshake referenced, with manifestId, sha256, issuedAtUnixMs, and expiresAtUnixMs.

`vendors[]`

arrayvendorId, publicKey

The vendor signers a workflow may require, each named by vendorId with its publicKey.

`actionClasses[]`

arrayactionClassId, toolName, kind

Each action class maps an actionClassId to a toolName and a kind, one of routine or receipt_backed. Every bundle pins the two reference workflow classes, workflow.grant_issue and workflow.aggregate_publish, and assembly refuses a pin set without them.

Example"workflow.grant_issue"

Verification context

The verification context (chio.federation.verification-context.v1) states who a disclosure is for and the window it is valid in.

`schema`

stringSchema id

The context schema id.

Example"chio.federation.verification-context.v1"

`audience`

stringRecipient

Who the disclosure is for.

`challenge`

stringVerifier challenge

The verifier's challenge the proof binds to.

`proofPurpose`

stringPurpose

What the proof is for.

Example"workflow-disclosure"

`issuedAtUnixMs`, `expiresAtUnixMs`

integerUnix milliseconds

The window the context is valid in.

Verifier trust bundle

assemble_verifier_trust_bundle returns a chio.federation.verifier-trust-bundle.v1 document from five inputs:

Authority profile. Validated; the bundle copies its lease authorities, governance authorities, BBS issuers, and runtime policy issuer keys.
Peer pins. The validated peer pins document above.
Workflow intersection. The intersection with its canonical digest.
Disclosure policy. The verifier's own disclosure policy.
Signed revocation checkpoint. The only way the revocation authority enters the bundle.

Before it returns, assembly parses the document with ChioVerifierTrustBundle::from_document, the strict parser the buyer's verifier uses, so every bundle an authority ships parses at the verifier. The buyer can still refuse a parsed bundle whose checkpoint does not cover the verification context window.

Bilateral verifier configuration

At verification time the pins become a PeerPinSet inside a VerifierConfig, beside the lookup traits the verifier consults: ReceiptStore, CapabilityLeaseRegistry, GovernanceReceiptStore, and RevocationOracle. The configuration also holds the pinned epoch, the action-class map, and the policy for an unknown action class.

Example

Assemble the verifier trust bundle with the CLI

Terminalbash

chio federation authority trust-bundle assemble --profile authority-inputs/profile.json --peer-pins authority-inputs/peer-pins.json --workflow-intersection authority-inputs/workflow-intersection.json --disclosure-policy authority-inputs/disclosure-policy.json --checkpoint authority-inputs/cli-checkpoint.json --out authority-inputs/cli-trust-bundle.json
jq '.schema' authority-inputs/cli-trust-bundle.json

Output · exit 0

"chio.federation.verifier-trust-bundle.v1"

The authority program refuses a pin set missing a reference workflow class; its last captured line on Federation Authority shows the refusal.

Errors

ChioAuthorityError::TrustBundle: a missing reference workflow class, or a bundle the strict parser rejects.
ChioAuthorityError::Profile: a key id that does not match its public key, or a runtime policy issuer key that overlaps an authority key. An inactive authority is refused later as Issuance, Revocation, or TrustBundle.
VerifierError::PeerUnpinnedOrKeyidMismatch: a predicate's kernel id is unpinned, or its passport key fingerprint differs from the pin; checked before any signature.
SignatureServerAInvalid and SignatureServerBInvalid: a signature failure on either side, checked after the pin.

Every code is indexed on Federation Refusal Codes.

Source files

The reference workflow classes are checked in crates/trust/chio-attest-buyer-core/src/trust_bundle.rs and crates/trust/chio-federation-authority/src/lib.rs. The verifier configuration is crates/trust/chio-federation/src/bilateral_verifier/config.rs.

Next: prove the pinned key at the handshake

Peer handshakeAnswer a signed challenge against the pin and record the peer's tier and rotation deadline.Federation authorityIssue leases and checkpoints, then assemble the bundle.Refusal codesFind every federation refusal by code.

PreviousPeer Handshake NextTreaties