Bootstrap Federated Trust

cd federation-guide
cargo run --locked --bin handshake

use chio_core_types::crypto::{Keypair, PublicKey};
use chio_federation::trust_establishment::KernelTrustExchange;

// Larkfield side.
let local_keypair = load_local_kernel_keypair()?;
let halden_public_key: PublicKey = load_remote_anchor("halden")?;

let exchange = KernelTrustExchange::new(
    "kernel.larkfield.example",
    local_keypair,
)
.with_trusted_peer("kernel.halden.example", halden_public_key);

use chio_federation::trust_establishment::{
    KernelTrustExchange, KernelTrustExchangeConfig,
};

let exchange = KernelTrustExchange::new("kernel.larkfield.example", local_keypair)
    .with_config(KernelTrustExchangeConfig {
        // Default: 12 * 60 * 60 (twelve hours).
        rotation_window_secs: 12 * 60 * 60,
        // Default: 5 * 60 (five minutes).
        max_handshake_skew_secs: 5 * 60,
    })
    .with_trusted_peer("kernel.halden.example", halden_public_key);

use std::time::{SystemTime, UNIX_EPOCH};

let now = SystemTime::now()
    .duration_since(UNIX_EPOCH)
    .map(|d| d.as_secs())
    .unwrap_or(0);

// Build our signed envelope addressed to the remote kernel.
let local_envelope = exchange.local_envelope(
    "kernel.halden.example",        // remote_kernel_id
    "nonce-2026-04-21-01", // caller-supplied nonce
    now,
)?;

// Serialize and send it over the authenticated transport between
// trust control planes (HTTPS with mutual TLS, or signed bodies).
let wire = serde_json::to_vec(&local_envelope)?;
transport.send("kernel.halden.example", &wire).await?;

fn handshake_succeeds_and_pins_both_sides() {
    let kp_a = Keypair::generate();
    let kp_b = Keypair::generate();
    let now: u64 = 1_800_000_000;

    let exchange_a = KernelTrustExchange::new("kernel.org-a", kp_a.clone())
        .with_trusted_peer("kernel.org-b", kp_b.public_key());
    let exchange_b = KernelTrustExchange::new("kernel.org-b", kp_b.clone())
        .with_trusted_peer("kernel.org-a", kp_a.public_key());

    // Each side builds its own signed envelope.
    let envelope_a = exchange_a
        .local_envelope("kernel.org-b", "nonce-a", now)
        .unwrap();
    let envelope_b = exchange_b
        .local_envelope("kernel.org-a", "nonce-b", now)
        .unwrap();

    // Each side verifies and pins the remote.
    let peer_b = exchange_a
        .accept_envelope(&envelope_b, "kernel.org-b", now)
        .unwrap();
    let peer_a = exchange_b
        .accept_envelope(&envelope_a, "kernel.org-a", now)
        .unwrap();

    assert_eq!(peer_b.kernel_id, "kernel.org-b");
    assert_eq!(peer_a.kernel_id, "kernel.org-a");
    assert_eq!(peer_b.conformance_tier, ConformanceTier::Bronze);
    assert_eq!(peer_a.conformance_tier, ConformanceTier::Bronze);
    assert!(peer_b.rotation_due > now);
    assert!(peer_a.rotation_due > now);

    // Resolve while fresh succeeds.
    let resolved = exchange_a.resolve("kernel.org-b", now + 60).unwrap();
    assert_eq!(resolved.public_key.to_hex(), kp_b.public_key().to_hex());
}

let remote_envelope: PeerHandshakeEnvelope = serde_json::from_slice(&incoming)?;

let pinned_peer = exchange.accept_envelope(
    &remote_envelope,
    "kernel.halden.example", // expected_remote_kernel_id
    now,
)?;

println!(
    "pinned {} until {} (window = {}s)",
    pinned_peer.kernel_id,
    pinned_peer.rotation_due,
    exchange.rotation_window_secs(),
);

use chio_kernel::ChioKernel;

let peers = exchange.peers()?; // Vec<FederationPeer>
let kernel = ChioKernel::new(config)
    .with_federation_peers(peers);

kernel.set_federation_local_kernel_id("kernel.larkfield.example");

use chio_federation::trust_establishment::{ConformanceEvidence, ConformanceTier};

let evidence = ConformanceEvidence {
    threat_coverage_bps: 10_000, // 100%
    mutation_kill_bps: 8_200,    // 82%
    kani_trust_boundary_crates: 9,
};
let tier: ConformanceTier = evidence.derive_tier()?; // ConformanceTier::Gold

let exchange = KernelTrustExchange::new("kernel.larkfield.example", local_keypair)
    .with_conformance_tier(ConformanceTier::Gold)
    .with_trusted_peer("kernel.halden.example", halden_public_key);

use chio_federation::trust_establishment::QuorumPolicy;

// Refuse any peer below Silver.
let policy = QuorumPolicy { min_tier: ConformanceTier::Silver };

let pinned_peer = exchange.accept_envelope_with_policy(
    &remote_envelope,
    "kernel.halden.example",
    now,
    &policy,
)?;

use std::sync::Arc;
use chio_federation::bilateral::InProcessCoSigner;

// set_federation_cosigner takes &mut self, so the kernel binding is mutable.
let mut kernel = kernel;

// On the tool-host (Halden) kernel, install a cosigner that reaches the
// origin (Larkfield) kernel. InProcessCoSigner serves single-host tests.
kernel.set_federation_cosigner(Arc::new(InProcessCoSigner::new(
    "kernel.larkfield.example",             // origin_kernel_id
    origin_keypair.clone(),     // single-host tests only
    tool_host_public_key,       // origin verifies Halden's sig before co-signing
)));

let mut request = build_tool_call_request(/* ... */);
request.federated_origin_kernel_id = Some("kernel.larkfield.example".to_string());

let response = kernel.evaluate_tool_call_blocking(&request)?;
assert_eq!(response.verdict, Verdict::Allow);

// The DSSE envelope is the authorization and audit record for the
// bilateral invocation. Verify it with the strict Chio bilateral verifier
// against both pinned peer keys (org A = origin, org B = tool host).
let envelope = kernel
    .federation_dsse_envelope(&response.receipt.id)
    .expect("federated call must produce a DSSE envelope");

let statement = chio_federation::bilateral_dsse::verify_chio_bilateral_dsse_envelope(
    &envelope,
    &origin_public_key,
    &tool_host_public_key,
)?;

// The same call records a DualSignedReceipt keyed by the same receipt id,
// with detached signatures. Use the DSSE verifier above for authorization
// and audit.
let dual = kernel
    .dual_signed_receipt(&response.receipt.id)
    .expect("federated call also produces a dual-signed receipt");

/// Errors raised by the trust-establishment primitives. Every variant is
/// fail-closed: callers MUST refuse to pin a peer when any step fails.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum PeerHandshakeError {
    #[error("unsupported handshake schema: {0}")]
    UnsupportedSchema(String),

    #[error("canonical JSON encoding failed: {0}")]
    CanonicalJson(String),

    #[error("handshake signing failed: {0}")]
    SigningFailed(String),

    #[error("remote handshake signature is invalid")]
    InvalidSignature,

    #[error("capability negotiation failed closed: {0}")]
    CapabilityNegotiation(String),

    #[error("remote envelope is addressed to kernel_id {addressed_to} but we are {actual}")]
    AddressMismatch {
        addressed_to: String,
        actual: String,
    },

    #[error("remote envelope declares self as kernel_id {declared} but we expected {expected}")]
    KernelIdMismatch { declared: String, expected: String },

    #[error("remote envelope timestamp {envelope} drifts from local clock {local} beyond {skew}s")]
    ClockSkewExceeded {
        envelope: u64,
        local: u64,
        skew: u64,
    },

    #[error("peer {0} is not pinned; run a handshake before resolving")]
    PeerNotPinned(String),

    #[error("peer {0} is stale and must be re-handshaked before use")]
    PeerStale(String),

    #[error("peer {0} is not trusted for first contact; configure a trust anchor before accepting handshakes")]
    MissingTrustAnchor(String),

    #[error("peer {kernel_id} declared unexpected public key; expected {expected}, got {actual}")]
    UnexpectedPeerKey {
        kernel_id: String,
        expected: String,
        actual: String,
    },

    #[error("peer {kernel_id} conformance tier {actual:?} is below required {minimum:?}")]
    ConformanceTierBelowMinimum {
        kernel_id: String,
        actual: ConformanceTier,
        minimum: ConformanceTier,
    },

    #[error("invalid conformance evidence: {0}")]
    InvalidConformanceEvidence(String),

    #[error("invalid ladder manifest reference: {0}")]
    InvalidLadderManifestRef(String),

    #[error("trust store is poisoned and cannot service requests")]
    StorePoisoned,
}