Witnessed rotation

The active key proposes its successor, and the successor proves possession

A newly published public key alone gives a verifier no history to check: consumers could be shown incompatible histories, and a serving process could start signing with a key nobody accepted. The rotation protocol needs an agreed history as well as a replacement key.

So the proposal is a rotate event that carries the previous key's id and a witness roster binding, signed twice over the same bytes: an OldKeyAuthorization by the active key and a NewKeyProofOfPossession by the candidate. verify_rotation accepts exactly that pair, and refuses a previous-key id that differs from the active key.

begin_rotation appends the event to the durable operator log, obtains its checkpoint, and stages the candidate's signing backend as pending in the router. The candidate is now history a verifier can read, and the router still signs with the old key.

Two of three witnesses and both auditors gate activation

The operator commits a checkpoint covering the event. Activation needs a strict majority of the keyring's witnesses: witness_threshold computes n/2 + 1, and the runtime requires exactly three witnesses and two auditors, so two witnesses must sign. Each compares the checkpoint with its retained history before signing the same view, and both auditors confirm the witnessed head.

collect_witnesses_and_activate gathers those signatures. The activation commit then binds the event, its inclusion position, the checkpoint, the required witness set, and the next signing epoch. Serving switches through a generation-fenced backend, the capability authority's only signer, so no capability token can bypass the activated selector.

The new selector fences stale live signing epochs: a signature requested under the old epoch is refused. Receipts signed before the change keep their original bytes and signatures. A candidate can wait while a witness or auditor is unavailable: losing two witnesses prevents activation, and losing either auditor blocks activation and the production readiness report. Startup needs signed readiness from all five services, so one missing witness also blocks a trust-control restart. Treat the wait as a pending rotation, distinct from a failure of the active key, and preserve the original proposal.

Read more in Key log witnesses, which runs the services this stage needs.

An interrupted rotation resumes the candidate it already proposed

A restart at a pending tail boots from the latest accepted checkpoint and retains the pending operator head for synchronization. The router accepts a resumed signing backend only when its key id, public key, and algorithm match the durable pending key, so a process that lost its memory cannot substitute a fresh key. Each cutpoint has one continuation:

An activated tail takes the activated-tail recovery path; resuming a pending rotation there is the wrong transition. Keep each witness and audit service's state through a restore, and rehearse pending-tail recovery before relying on rotation in operation.

use chio_core_types::SigningBackend;
use chio_keyring::{
    EventId, IndependentKeyLogServices, KeyringError, SignedKeyLogEvent, WitnessedRotationOutcome,
    WitnessedRotationRuntime,
};

pub fn begin_reviewed_rotation(
    runtime: &WitnessedRotationRuntime,
    original_signed_event: &SignedKeyLogEvent,
    new_key_backend: Box<dyn SigningBackend>,
    services: &IndependentKeyLogServices,
) -> chio_keyring::Result<WitnessedRotationOutcome> {
    let mut pending = runtime.begin_rotation(original_signed_event, new_key_backend)?;
    runtime.collect_witnesses_and_activate(&mut pending, services)
}

/// Reopen the SAME validated durable log/router and recover the SAME pending
/// key from custody before calling. A begin error may already have appended.
pub fn resume_original_rotation(
    runtime: &WitnessedRotationRuntime,
    original_event_id: &EventId,
    same_pending_key_backend: Box<dyn SigningBackend>,
    services: &IndependentKeyLogServices,
) -> chio_keyring::Result<WitnessedRotationOutcome> {
    let mut pending = runtime.resume_pending_rotation(same_pending_key_backend)?;
    if &pending.event_id != original_event_id {
        return Err(KeyringError::IdentityMismatch);
    }
    // The real runtime persists witness progress, waits for auditors and runs
    // the final activation guard. Neither a staged key nor a quorum alone
    // grants the application permission to select this backend directly.
    runtime.collect_witnesses_and_activate(&mut pending, services)
}

Trust control runs the whole rotation behind one route

Serve trust control with keyring custody. chio trust serve always takes the service token, here as CHIO_TRUST_SERVICE_TOKEN. --authority-keyring-config adds the global --authority-seed-file and --receipt-db, its own --authority-keyring-receipt-anchor-root on a filesystem device separate from the receipt database, and a distinct --authority-workload-token, supplied here as CHIO_TRUST_AUTHORITY_WORKLOAD_TOKEN. Every configured witness and audit service proves readiness before the listener opens.

export CHIO_TRUST_SERVICE_TOKEN="$(cat /run/secrets/chio_service)"
export CHIO_TRUST_AUTHORITY_WORKLOAD_TOKEN="$(cat /run/secrets/chio_authority_workload)"
chio trust serve \
  --authority-seed-file /run/credentials/chio/authority.seed \
  --receipt-db /var/lib/chio/receipts.sqlite3 \
  --authority-keyring-config /etc/chio/authority-keyring.yaml \
  --authority-keyring-receipt-anchor-root /mnt/chio-anchors/keyring

POST /v1/authority then drives the rotation end to end. It stages the new key behind the pending selector: for the enterprise_keyring profile it writes a crash-safe pending seed handoff, obtains the witness quorum and both auditor acknowledgements, activates the selector, and only then replaces the active seed file, the sequence the operations runbook records. After a timeout or partial response, post again; rotating the seed file by hand bypasses the witnessed history.

Every refused rotation returns the same 503 on the route

Whichever keyring check refuses, the route answers 503 with one body. A Rust host that drives chio-keyring directly receives the typed KeyringError variant instead.

A recover event follows the same witnessed contract under a different authorization set, described with the other operations below. Cluster authority shows how a cluster consumes the active key once activation lands.

Next: run the witnesses a rotation needs