Two-Org Worked Example

pub const FEDERATION_HANDSHAKE_SCHEMA: &str = "chio.federation-kernel-handshake.v1";

// ...

/// Challenge body signed by one kernel during the handshake.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct HandshakeChallenge {
    pub schema: String,
    pub local_kernel_id: String,
    pub remote_kernel_id: String,
    pub nonce: String,
    pub timestamp: u64,
    #[serde(default, skip_serializing_if = "is_default_capability_negotiation")]
    pub capabilities: CapabilityNegotiation,
    #[serde(default, skip_serializing_if = "is_default_conformance_tier")]
    pub conformance_tier: ConformanceTier,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ladder_manifest_ref: Option<LadderManifestRef>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct PeerHandshakeEnvelope {
    pub challenge: HandshakeChallenge,
    pub declared_public_key: PublicKey,
    pub signature: Signature,
}

/// Pinned federation peer entry.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationPeer {
    pub kernel_id: String,
    pub public_key: PublicKey,
    /// Cross-surface conformance tier that was signed into the peer's most
    /// recent accepted handshake.
    #[serde(default)]
    pub conformance_tier: ConformanceTier,
    /// Unix seconds at which the peer was last pinned via a successful
    /// handshake.
    pub established_at: u64,
    /// Unix seconds at which the pin expires. After this timestamp the
    /// peer is treated as stale and MUST be re-handshaked before any
    /// federation-level operation is accepted against it.
    pub rotation_due: u64,
    /// Peer-advertised protocol feature bitset. Missing on compatibility peers
    /// defaults to current capability semantics without optional features.
    #[serde(default)]
    pub capabilities: CapabilityNegotiation,
    /// Optional signed ladder manifest reference accepted during handshake.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ladder_manifest_ref: Option<LadderManifestRef>,
}

pub const CHIO_FEDERATION_ACTIVATION_EXCHANGE_SCHEMA: &str =
    "chio.federation-activation-exchange.v1";

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationActivationExchangeArtifact {
    pub schema: String,
    pub exchange_id: String,
    pub issued_at: u64,
    pub expires_at: u64,
    pub source_operator_id: String,
    pub target_operator_id: String,
    pub listing_id: String,
    pub activation_ref: FederationArtifactReference,
    pub listing_ref: FederationArtifactReference,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub governing_charter_ref: Option<FederationArtifactReference>,
    pub scope: FederationTrustScope,
    pub delegation_control: FederationDelegationControl,
    pub import_control: FederationImportControl,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
}

{
  "body": {
    "schema": "chio.federation-activation-exchange.v1",
    "exchangeId": "fex-partner-001",
    "issuedAt": 1714291200,
    "expiresAt": 1716883200,
    "sourceOperatorId": "partner-operator",
    "targetOperatorId": "larkfield",
    "listingId": "listing-pricing-quote",
    "activationRef": {
      "kind": "trust_activation",
      "schema": "chio.registry.trust-activation.v1",
      "artifactId": "activation-77",
      "operatorId": "larkfield",
      "sha256": "91c4…7be0"
    },
    "listingRef": {
      "kind": "listing",
      "schema": "chio.registry.listing.v1",
      "artifactId": "listing-pricing-quote",
      "operatorId": "larkfield",
      "sha256": "2e6d…a013"
    },
    "scope": {
      "namespace": "pricing.larkfield.example",
      "subjectOperatorId": "larkfield",
      "allowedActorKinds": ["tool_server"],
      "allowedAdmissionClasses": ["bond_backed"]
    },
    "delegationControl": {
      "delegatorOperatorId": "partner-operator",
      "delegateOperatorId": "larkfield",
      "maxHops": 1,
      "attenuationRequired": true,
      "visibilityOnlyUntilLocalActivation": true
    },
    "importControl": {
      "explicitLocalActivationRequired": true,
      "manualReviewRequired": true,
      "rejectStaleInputs": true,
      "allowVisibilityWithoutRuntimeTrust": true,
      "prohibitAmbientRuntimeAdmission": true
    }
  },
  "signerKey": "4f1c…a2e9",
  "signature": "0d7c…e5a8"
}

/// 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,
}

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)
);
CREATE INDEX IF NOT EXISTS idx_federated_lineage_bridges_parent
    ON federated_lineage_bridges(parent_capability_id);

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
);
CREATE INDEX IF NOT EXISTS idx_federated_evidence_shares_imported_at
    ON federated_evidence_shares(imported_at);

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)
);
CREATE INDEX IF NOT EXISTS idx_federated_share_receipts_capability
    ON federated_share_tool_receipts(capability_id);
CREATE INDEX IF NOT EXISTS idx_federated_share_receipts_subject
    ON federated_share_tool_receipts(subject_key);

{
  "kernelId": "kernel.halden.example",
  "publicKey": "9b07…d31c",
  "establishedAt": 1745784000,
  "rotationDue": 1745827200
}