Custody model

Each custodian holds one class of secret and acts for one caller

A private key can still be misused through its API. A signer that signs whatever statement a caller selects, or a broker that sends whatever request a caller writes, lets clients spend the key without ever reading its bytes. Custody therefore pairs a protected secret with a constrained interface for asking its owner to act.

1. Secret broker. Holds provider credentials and uses them for the executor of an admitted operation. It leaves a broker execution receipt.
2. Kernel signing authority. Holds the receipt signing keys and signs for the kernel. It leaves signed receipts.
3. Keyring. Holds the trust control plane's signing keys and their history. It leaves key-log events and checkpoints.

The roles stay apart because they authorize different things: a provider credential acts at an external service, a receipt key authenticates the kernel's statement about an operation, and a key-history authority decides which signing identity is current. Combined, a compromise is harder to contain and the evidence harder to read. Separate custody also needs defined behavior when a custodian is unavailable, including recovery of work it already accepted.

Read more in Secrets and signing keys, which provisions and rotates each key class, and Cluster authority, which carries these keys across peers.

The secret broker uses a credential and returns only output and evidence

The broker encrypts provider credentials at rest and decrypts them inside its own process. The supervisor delivers its tenant master key through an inherited sealed descriptor, consumed once. The executor receives provider output and signed execution evidence, and a verbatim match of the credential in response headers or body becomes a retained failure receipt, withheld from the caller.

Follow one admitted issue request across the boundary: the agent supplies a credential reference, the host calls the pinned broker, and the broker owns provider authentication. The host's final call takes the supervisor-owned BrokerIpcClientConfig, the original request, and an evidence writer that commits to the host's private journal. It returns bounded output and a signed success or failure record, and the client has no secret-export call.

use chio_core_types::SigningBackend;
use chio_secret_broker::ipc_client::{
    BrokerIpcClient, BrokerIpcClientConfig, BrokerIpcExecutionOutcome,
};
use chio_secret_broker::protocol::BrokerExecuteRequest;
use chio_secret_broker::Result;
use std::sync::Arc;

/// Called by the configured host for an already registered, captured original
/// operation. Configuration comes from the supervisor's independent peer/key pins.
pub fn use_original_broker_request(
    config: BrokerIpcClientConfig,
    registration_authority: Arc<dyn SigningBackend>,
    original: &BrokerExecuteRequest,
    persist_private_outcome: impl FnOnce(&BrokerIpcExecutionOutcome) -> Result<()>,
) -> Result<BrokerIpcExecutionOutcome> {
    let client = BrokerIpcClient::new(config, registration_authority)?;
    let outcome = client.execute_evidenced(original)?;
    // A signed failure is evidence too. Persist it before the caller interprets
    // provider output. A transport error remains an unresolved original attempt.
    persist_private_outcome(&outcome)?;
    Ok(outcome)
}

Change the expected broker process, UID, GID, or receipt key, and the client refuses authentication or outcome verification. If the socket fails, keep the original request and its uncertainty: a new connection, credential version, or attempt ledger says nothing about whether the first provider call happened, and recovery follows the custodian that owns the retained operation. A copy of the same provider token in the tool's environment is a route around the boundary, so host composition removes it along with any direct network path to the provider.

Read more in Credential broker, Prepared connections, Credential custody, and Daemon credentials.

Signing keys stay with the kernel and the keyring

The kernel owns its receipt, threshold-proposal, and session-report signing authority. Callers ask through kernel operations and never reach the private signing authority directly; Signing authority selects the backend and names the separately owned artifact roles.

The trust control plane's keyring retains signing history and stamps each signature with its current signing epoch. A rotation makes the previous epoch stale, and the store refuses stale-epoch signatures, so two keys are never valid at once. The keyring serves authority through the activated, generation-fenced selector, and a verifier checks each kernel receipt under the receipt identity it pinned independently. Witnessed rotation changes the authority and Key log witnesses verify its history.

A custodian acts only for the caller it was provisioned to trust

For the broker, the operator provisions the trusted service UID and the authorized client UID independently. Key files belong to the service UID, the Linux IPC endpoint checks the connecting client's UID, and the client checks the broker's expected peer identity. Keyring rotation enters through POST /v1/authority, and the edge's administrative rotation forwards there when a control plane is configured.

The daemon stops on a custody failure, and the client sees a closed connection when the daemon rejects its UID. Repair a refusal with these checks enabled: restore the provisioned identity, key file, or witness set, and leave the check in place.

Custodian source reference

Each entry names the types, files, and lines that implement one custodian's contract.

pub struct SealedKeyFd {
    file: File,
    expected_owner: u32,
    consumed: bool,
}

Next: let an agent use a credential it never holds