Bilateral Receipts

Kernel wiring

On your side, install a BilateralCoSigningProtocol implementation that reaches the partner over the cross-organization transport: HTTPS with mutual TLS or signed bodies by default, or the iroh co-sign lane where both partners run iroh on self-hosted relays. On the partner's side, the signing key stays local, and the co-signer validates each request against the expected host identity and key.

// Embedding the kernel at Larkfield. larkfield_kernel is mutable during construction.
larkfield_kernel.set_federation_local_kernel_id("kernel.larkfield.example");
larkfield_kernel.set_federation_cosigner(origin_cosigner);
larkfield_kernel.set_federation_artifact_store(bilateral_artifact_store);

origin_cosigner has type Arc<dyn BilateralCoSigningProtocol>; bilateral_artifact_store has type Arc<dyn FederationArtifactStore>. InProcessCoSigner holds the origin’s signing keypair directly and serves in-process tests and local examples.

Bind the origin before dispatch. The federated request names the partner in federated_origin_kernel_id; connect that identity to the authenticated peer and the admitted authority, because a caller-supplied string is not peer authentication. Preserve the request and receipt identifiers the application uses; the exchange consumes the locally signed receipt.

Federation builder methods

• with_federation_peers(peers) pins the trusted peer set after the handshake.
• set_federation_cosigner(cosigner) installs the implementation that contacts the origin kernel for a co-signature.
• set_federation_local_kernel_id(id) advertises this kernel’s stable name. It defaults to the hex of the signing public key.
• set_federation_artifact_store(store) (construction.rs:1288) writes each co-sign artifact through before it enters the cache.

The kernel caches co-sign artifacts in a bounded in-memory map, federation_dual_receipts, that drops the oldest at capacity. With a store installed, dual_signed_receipt falls back to the store on a cache miss; without one, an evicted co-sign artifact is gone while the durable receipt store still holds the base receipt. Use a durable store for retained evidence.

if let Some(dual) = kernel.dual_signed_receipt(&receipt.id) {
    dual.verify_pinned(ExpectedBilateralPeers {
        org_a_kernel_id: "kernel.halden.example",
        org_a_public_key: &halden_public_key,
        org_b_kernel_id: "kernel.larkfield.example",
        org_b_public_key: &larkfield_public_key,
    })?;
    // both expected kernels signed off
}

DualSignedReceipt

/// A receipt co-signed by two kernels across a federation boundary.
///
/// * `body` -- the underlying `ChioReceipt` that both kernels agreed on.
/// * `org_a_signature` -- detached signature by the origin (Org A) kernel
///   over the canonical [`CoSigningBody`].
/// * `org_b_signature` -- detached signature by the tool-host (Org B) kernel
///   over the same canonical body.
///
/// The existing receipt's built-in `signature` and `kernel_key` fields are
/// unchanged: a classic verifier can still check the receipt in isolation,
/// while a federation-aware verifier additionally checks both detached
/// signatures via [`DualSignedReceipt::verify`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct DualSignedReceipt {
    pub schema: String,
    pub body: ChioReceipt,
    pub org_a_kernel_id: String,
    pub org_b_kernel_id: String,
    pub org_a_signature: Signature,
    pub org_b_signature: Signature,
}

verify(org_a_public_key, org_b_public_key) (bilateral.rs:125) takes the expected ids from the artifact. verify_pinned(ExpectedBilateralPeers) (bilateral.rs:153) takes them from the caller, and its doc comment names it the one to use at a trust boundary. Both rebuild the canonical CoSigningBody and return Ok only when both detached signatures validate. co_sign_with_origin runs the check before it returns (bilateral.rs:571).

The kernel construction code defines the setters and artifact write-through. The bilateral module defines the request, the response, the signature checks, and InProcessCoSigner (bilateral.rs:437).

Audit walk output

chio receipt explain detects the bilateral shape from the input file (chio-cli/src/cli/types/receipt.rs:80-101). The renderer, print_bilateral_human (chio-cli/src/cli/trust/receipt/explain.rs:558), prints three labeled sections:

• Header. schema and shape: the report names itself chio.cli.receipt-explain.bilateral.v1 over a BilateralCoSignArtifacts document.
• DualSignedReceipt (NON-SECTION-6-CONFORMANT). receipt_id, schema, org_a_kernel_id, org_b_kernel_id, and a disclaimer line giving the reason for the heading: this half signs the canonical JSON of CoSigningBody, not the DSSE PAE preimage.
• DSSE envelope (signature-slice API artifact). schema, payload_type, payload_hex truncated to 96 characters with the decoded byte count, one entry per signature with its keyid and a sig truncated to 32 characters, and a closing conformance note.

A keyid reads as 64 hex characters, the SHA-256 of the signing kernel’s passport public key. --inspect-bilateral adds a fourth section, a numbered structural trace that opens by stating it is an inspection trace and that Ed25519 signatures are not verified in it; without the flag no trace renders (explain.rs:108, :128).

The renderer holds neither operator’s passport key, so it makes no verification claim. chio_federation::bilateral_dsse::verify_dsse_envelope (bilateral_dsse/verify.rs:17) verifies the DSSE half, the one the disclaimer points to for section 6 conformance. Its conformance note keeps the boundary narrow: the signatures cover the PAE bytes, and the predicate is the signature-slice profile rather than the strict bilateral invocation schema. The auditor then walks lineage through federated_lineage_bridges to the parent capability at the partner, and from there into the partner’s own capability lineage where available, each step a signed record verified offline.

Bilateral co-sign predicate

The predicate is normative in CHIO_BILATERAL_COSIGN_INVOCATION.md (v1, 2026-05-04) and implemented in chio-federation’s bilateral_dsse.rs and bilateral_verifier.rs. The specification names bilateral.rs, the CoSigningBody and DualSignedReceipt pair, as the verification operation it wraps. The proof package embeds no peer pins, ladder references, or action-class policy.

The specification reserves a second URI for the same predicate, https://in-toto.io/attestation/bilateral-cosign-invocation/v1. A verifier treats the two as semantically equivalent inside one deployment and MUST NOT rewrite either into the other, because the predicate type sits inside the signed Statement and rewriting breaks signature verification.

Federated lineage tables

Cross-org delegation produces capability lineage that crosses a federation boundary. The receipt store records it in three related tables, created as inline CREATE TABLE statements in chio-store-sqlite/src/receipt_store/bootstrap/open.rs.

federated_lineage_bridges

Maps a local capability id to its parent in another organization and the share id that imported the parent. The table joins local capability_lineage rows to imported evidence, so a child-to-parent walk lands on a recognizable record even when the parent was issued at a different kernel.

CREATE TABLE IF NOT EXISTS federated_lineage_bridges (
    local_capability_id TEXT PRIMARY KEY
        REFERENCES capability_lineage(capability_id) ON DELETE CASCADE,
    parent_capability_id TEXT NOT NULL,
    share_id TEXT REFERENCES federated_evidence_shares(share_id)
);

federated_evidence_shares

One row per signed evidence package imported from a partner. The manifest hash is the content identifier; issuer and partner name the two operators; the signer public key identifies the partner’s signing key at import time.

CREATE TABLE IF NOT EXISTS federated_evidence_shares (
    share_id TEXT PRIMARY KEY,
    manifest_hash TEXT NOT NULL,
    imported_at INTEGER NOT NULL,
    exported_at INTEGER NOT NULL,
    issuer TEXT NOT NULL,
    partner TEXT NOT NULL,
    signer_public_key TEXT NOT NULL,
    require_proofs INTEGER NOT NULL DEFAULT 0,
    query_json TEXT NOT NULL
);

federated_share_tool_receipts

Receipt rows attached to an imported share. Each row carries the receipt id, capability id, subject and issuer keys, and the raw receipt JSON for verification. The composite primary key (share_id, seq) orders the receipts inside one share, and a unique constraint on (share_id, receipt_id) prevents duplicate import.

CREATE TABLE IF NOT EXISTS federated_share_tool_receipts (
    share_id TEXT NOT NULL
        REFERENCES federated_evidence_shares(share_id) ON DELETE CASCADE,
    seq INTEGER NOT NULL,
    receipt_id TEXT NOT NULL,
    timestamp INTEGER NOT NULL,
    capability_id TEXT NOT NULL,
    subject_key TEXT,
    issuer_key TEXT,
    raw_json TEXT NOT NULL,
    PRIMARY KEY (share_id, seq),
    UNIQUE (share_id, receipt_id)
);

A companion table, federated_share_capability_lineage, records imported capability lineage, including delegation depth and parent capability id, so a partner’s chain can be walked offline against the share manifest.

Federated evidence shares

Beside co-signed receipts on the request path, the federation API shares evidence asynchronously. A partner packages receipts and lineage rows into a signed share and sends it across the boundary, and the receiving organization imports it under its bilateral FederationImportControl:

• Explicit local activation, required by default. Imported shares stay visibility-only until an operator activates them.
• Manual review, required by default before activation.
• Stale inputs rejected. reject_stale_inputs is a boolean that defaults to true. The control carries no age threshold of its own; the receiving side decides freshness for each artifact kind.
• Ambient runtime admission prohibited. Imported evidence feeds visibility and reputation displays and leaves runtime authority unchanged.

Imported shares feed comparison views and reputation projections. Runtime authority, even after activation, still requires a locally issued capability that satisfies the local guard pipeline.

Revocation root gossip

When your partner revokes a capability, your kernel stops honoring it at its next enforcement decision. What crosses the boundary is a signed sparse Merkle tree root per epoch. chio-revocation-oracle owns the tree and the signing; chio-federation::revocation_gossip owns the wire envelope, the batched push queue, and the gap-fill protocol.

The envelope is RevocationRootGossip, schema chio.federation-revocation-root-gossip.v1 (chio-federation/src/revocation_gossip.rs:40). It carries the signed epoch root, the signer identity, the epoch duplicated outside the signature for cheap routing, and ts_unix_ms, the sender’s emit time, which the receiver uses for freshness gating and to age out a stalled feed. Four things fail closed on the receiving side:

• Structure before cryptography. validate_envelope rejects a wrong schema tag, an epoch that disagrees with signed_root.root.epoch, and a signer_id that disagrees with the one inside the signature. It verifies no signature: the caller still runs SignedEpochRoot::verify against a pinned signer before trusting the root.
• A pinned signer. The wire types carry no endpoint and no public key. A receiver verifies each root against a key it already holds, so the transport contributes origin, ordering, and reliability, and authenticity comes from the pin.
• Bounded push. RevocationGossipPushQueue keeps a per-peer FIFO ring. Inside one tick a newer root for the same epoch replaces the one queued before it, and a strictly higher epoch evicts every queued lower epoch, so a high revoke rate coalesces. flush_batches_at drains each peer into a RevocationGossipBatch, and an empty queue produces no batch.
• Bounded catch-up. A peer that missed epochs sends a RevocationCatchupRequest naming an inclusive range. An inverted range and a range wider than REVOCATION_CATCHUP_MAX_EPOCHS are refused, so one stalled peer cannot make a responder materialize an unbounded history slice. validate_response requires strictly increasing epochs with no internal gap and surfaces a short answer as truncation.

HTTPS with mutual TLS or signed bodies carries the feed by default. Where the partners run the optional iroh transport on self-hosted relays, the revocation lane of chio-federation-transport-iroh carries both the pushed batch and the catch-up exchange (lanes/revocation.rs:1-41). Its accept handler runs three mandatory checks: the admission gate refuses an endpoint not bound to an admitted kernel, the frame’s signer_id must be pinned to that same authenticated endpoint, and the SignedEpochRoot must verify against the bound key.