Revocation Store

One question, asked per subject

A revocation store answers one question for one process: is this capability id in the revoked set? Revocation is not Kernel content, and the kernel says so itself. The portable core's evaluate module lists what it deliberately does not do, and revocation membership lookup is the first item:

//! What it does NOT do (fenced into `chio-kernel` proper):
//!
//! - Revocation membership lookup (stateful `RevocationStore`).
//! - Budget mutation (stateful `BudgetStore`).

Six more items follow in the same comment; Core and Shell reads the list out whole and explains why the split is drawn there. A revocation lookup needs mutable state that outlives the call, so it lives in the hosting kernel, not the verified core.

Model

The trait is four methods, and two of them carry defaults that decide the node's failure posture:

pub trait RevocationStore: Send + Sync {
    fn is_revoked(&self, capability_id: &str) -> Result<bool, RevocationStoreError>;

    /// Revoke a capability. Returns `true` if it was newly revoked.
    fn revoke(&self, capability_id: &str) -> Result<bool, RevocationStoreError>;

    fn observe_revocation(
        &self,
        capability_id: &str,
    ) -> Result<RevocationObservation, RevocationStoreError> {
        Ok(RevocationObservation {
            revoked: self.is_revoked(capability_id)?,
            commit: None,
        })
    }

    /// Whether this store loses its revocation set on process restart. The
    /// default is the safe (loud) assumption so an unknown store is treated as
    /// ephemeral; durable and remote stores override to `false`.
    fn is_ephemeral(&self) -> bool {
        true
    }
}

An implementor who forgets to override is_ephemeral gets denied dispatch, not silent data loss. InMemoryRevocationStore never overrides it, so the default store reports ephemeral by construction (in_memory_revocation_store_is_ephemeral_by_default in chio-kernel/src/kernel/tests/revocation_durability.rs).

The durability gate

Before any capability is verified, the pre-dispatch path runs four readiness checks in order: federated receipt-persistence readiness, TCB lock health, local receipt-persistence readiness, then revocation durability. Revocation durability is the last of the four, and the one that refuses an ephemeral store:

pub(crate) fn ensure_revocation_durability_ready(&self) -> Result<(), KernelError> {
    // A remote revocation view (federation/oracle) is consulted on every
    // delegated dispatch and is re-synced from its source after a restart, so
    // an installed view is itself a durable revocation source: it satisfies
    // the gate even when the local per-row store is the default in-memory one.
    if self.revocation_view.is_some() {
        return Ok(());
    }
    let ephemeral = self.with_revocation_store(|store| Ok(store.is_ephemeral()))?;
    if !ephemeral || self.config.allow_ephemeral_revocation_store {
        return Ok(());
    }
    Err(KernelError::Internal(
        "durable revocation state unavailable: no revocation store configured".to_string(),
    ))
}

Three ways to satisfy it: an installed view, a store that reports durable, or the explicit allow_ephemeral_revocation_store opt-in. The flag defaults to false in both chio-config/src/schema.rs and the control-plane policy types, so an unconfigured long-running node denies rather than accepting a token it had already revoked before a restart. Failing the gate produces a signed deny receipt, not a bare error: it routes through build_receipt_persistence_failclosed_deny_response_with_metadata, so the refusal is recorded with the reason text above. Note the attribution: that builder stamps the receipt's guard field with kernel.receipt_persistence regardless of which of the four readiness checks failed, so filter on the reason string when you are looking for revocation-durability denies specifically.

The CLI applies the distinction by runtime shape. chio run and chio check issue capabilities, evaluate, and exit inside one process lifetime, so opt_in_ephemeral_revocation_for_local_session calls the opt-in for them, and only when no durable backend is configured. An in-memory --revocation-db path counts as no backend for that test, so it takes the opt-in rather than the deny. The long-running edge built by build_mcp_edge_kernel never auto-opts in.

The store on disk

SqliteRevocationStore::open creates the parent directory, refuses a database already provisioned with a joint serving owner, refuses one whose application_id belongs to another product or whose stamped revision is newer than the supported one, initializes the schema, stamps revision 2 under the revocation key, and runs a foreign_key_check. The base table and its index:

PRAGMA journal_mode = WAL;
PRAGMA synchronous = FULL;
PRAGMA busy_timeout = 5000;
PRAGMA foreign_keys = ON;

CREATE TABLE IF NOT EXISTS revoked_capabilities (
    capability_id TEXT PRIMARY KEY,
    revoked_at INTEGER NOT NULL,
    revocation_index INTEGER UNIQUE,
    admission_authority_commit_index INTEGER UNIQUE
);

CREATE INDEX IF NOT EXISTS idx_revoked_capabilities_revoked_at
    ON revoked_capabilities(revoked_at);

That excerpt is not the whole schema. initialize_revocation_schema also creates the singleton counter table revocation_replication_meta, or, when the store is opened alongside a joint serving owner, admission_authority_meta plus an admission_authority_commits log and a migration table. Which of the two index columns a row gets depends on that same mode.

chio trust status and chio trust revoke are the two reads and the one write, against whichever backend the process is pointed at. Here the backend is a chio trust serve process holding a SQLite revocation database, so backend echoes the control URL rather than a file path. The fourth command repeats the third:

$ chio --control-url http://127.0.0.1:8940 --control-token "$TOKEN" \
    trust status --capability-id cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
capability_id: cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
revoked:       false
backend:       http://127.0.0.1:8940

$ chio --control-url http://127.0.0.1:8940 --control-token "$TOKEN" \
    trust revoke --capability-id cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
capability_id: cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
revoked:       true
newly_revoked: true
backend:       http://127.0.0.1:8940

$ chio --control-url http://127.0.0.1:8940 --control-token "$TOKEN" \
    trust status --capability-id cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
capability_id: cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
revoked:       true
backend:       http://127.0.0.1:8940

$ chio --control-url http://127.0.0.1:8940 --control-token "$TOKEN" \
    trust revoke --capability-id cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
capability_id: cap-019fbe33-b0ac-7712-a128-fc72a40b3c75
revoked:       true
newly_revoked: false
backend:       http://127.0.0.1:8940

newly_revoked is the return value of the store call, and it is the whole of what idempotence means here. revoke is idempotent: an id already present rolls the transaction back and returns false. upsert_revocation only ever moves a stored revoked_at forward; an incoming record at or before the stored timestamp is a no-op. Every mutation allocates the next value from the singleton counter row via allocate_revocation_index and stamps it into the row. Reads run in a deferred transaction that is rolled back rather than committed. Writes take TransactionBehavior::Immediate and verify a serving-owner fence first, so a store whose lease has been taken over returns RevocationStoreError::Fenced instead of writing behind the current owner. That fence only bites for the co-located store built through SqliteServingOwner: a standalone --revocation-db store carries no owner, and open has already refused any database that carries one, so on that path the fence check is a no-op against an unprovisioned file.

A failed commit does not become a plain error. It becomes RevocationStoreError::OutcomeUnknown: the revocation may or may not be durable, and the caller is told exactly that rather than a false negative.

Who consults it, and when

check_revocation tests the leaf capability id first, then every delegation_chain[i].capability_id, one store call per subject. A revoked leaf raises KernelError::CapabilityRevoked; a revoked ancestor raises KernelError::DelegationChainRevoked. The tool-call path calls it at four points:

Four is the count on the tool-call path, not for every capability-backed operation. Resource and prompt admissions route through evaluation/evaluation_entry.rs, which calls check_revocation once before delegation admission; plan-step evaluation and the governed active-response path each call it once as well. None of those three take the trace-emitting admission wrapper.

with_revocation_store takes no kernel-level lock, unlike the budget store; concurrency control belongs to the store implementation. Both revoke_capability and the admission check take the runtime-trace transition lock so trace events (RevocationCommitted, RevocationAdmission) are ordered, and both recover from a poisoned lock rather than failing: poisoned_runtime_trace_lock_does_not_disable_revocation_or_admission pins that a poisoned trace lock never disables the revocation check itself.

observe_revocation is the stricter read. The SQLite implementation answers membership and reads the commit index in one transaction, attaching RevocationCommitMetadata only when a serving owner is attached. The durable-admission coordinator uses it for supplemental quota claims and refuses the call when the observation carries no commit metadata (supplemental authorization requires atomic revocation observation) or when the guarantee level is not SingleNodeAtomic or HaLinearizable. A plain membership boolean is not enough to bind a revocation into a budget admission record. That cuts both ways: the SQLite store is the only in-tree implementation that overrides observe_revocation, and it attaches commit metadata only in joint serving-owner mode. InMemoryRevocationStore and RemoteRevocationStore both inherit the trait default and return commit: None, so neither can back a supplemental quota claim.

The read-only view

RevocationView is the only revocation state the portable core defines, and it is read-only by construction: an ArcSwap<RevocationSnapshot> that readers load without blocking writers. A snapshot carries an epoch, a 32-byte root_hash, an issued_at_unix_ms, and a sorted BTreeSet of revoked subjects. Serde is deny_unknown_fields.

Writers go through install_if_newer, a compare-and-swap loop that rejects any candidate whose epoch does not strictly advance the installed one with RevocationViewError::NonMonotoneEpoch and leaves the active snapshot untouched. Unit tests cover equal-epoch replay, stale-epoch rewind, and eight concurrent writers racing to install epochs 1 through 8, after which the view reads 8 and a subsequent epoch-7 write still fails. The core does not re-verify root_hash; its own doc comment says so, and signature verification belongs to the layer that produced the snapshot. That layer has a page of its own: Revocation Oracle documents the signed epoch root a snapshot is built from, the freshness window applied before it is merged, and what the signature does not cover.

When a view is installed, the kernel consults it in validate_delegation_admission through consult_revocation_view, which loads the snapshot once and then tests the leaf and every chain link against it. Before any membership test it applies a freshness gate: DEFAULT_REVOCATION_VIEW_MAX_STALENESS_MS is 500, and a snapshot older than that, or issued in the future, denies with KernelError::DelegationInvalid. With no view installed the helper returns Ok(()) and the per-row store lookup is the whole check.

Two boundaries on that sentence. First, the call site is #[cfg(feature = "delegation")]. That feature is in chio-kernel's default set, so a stock build consults the view, but a --no-default-features build drops the consultation entirely and leaves only the per-row lookup. The comment on the feature itself still reads “Default OFF for the trust boundary,” which contradicts the default = ["delegation"] line above it; trust the default list. Second, the 500 ms window is compared against a whole-second clock: consult_revocation_view computes now as current_unix_timestamp().saturating_mul(1000), so the effective resolution of the freshness test is one second, not one millisecond.

Guarantees and limits

Two gaps remain. The store answers membership, not why: there is no reason field, no revoker identity, and no un-revoke, and no code path deletes from revoked_capabilities. And a node with a durable store has no mechanism of its own for learning about a revocation another node recorded. It exposes the read the cluster layer needs, list_revocations_after over the (revoked_at, capability_id) cursor, and nothing more. Something above it has to do the pulling: today that is the control-plane cluster snapshot and delta handlers, plus the denylist warm-up in chio-api-protect.

Next Steps

• Replication & Convergence · the delta stream that carries a revocation to nodes that did not record it
• Core and Shell · the exclusion list this page is the first entry of
• Capabilities · what a capability id and a delegation chain are
• Fail-Closed Semantics · the wider invariant the durability gate belongs to
• Backup & Restore · operating the SQLite files a node depends on