Revocation Epochs

A continuation signs the id and list root of the epoch it was minted under

The task graph names the epoch, and each continuation carries the epoch’s id and list root inside its own signature body.

The terminal graph receipt names the epoch id and carries no root. At runtime, the request’s epoch evidence pair binds the id and canonical whole-artifact digest to the stored epoch before the bundle is verified. The verifier recomputes the root before any continuation check, so each token is compared with a root already checked against the lists.

The list root covers the lists, and the epoch’s signature covers its whole body. A continuation’s id and root fields leave the rest of the epoch uncommitted: a newly signed epoch with the same id and lists and a different window keeps the same root. Its window and signature face their own checks, and a runtime evidence reference to the old whole-artifact digest is rebuilt for it.

A listed subject or task refuses the whole bundle

An epoch carries revokedSubjects and revokedTaskIds. The subject list is matched against the graph’s issuer, its planner subject, and every witness-hop issuer; the task list is matched against every node in the graph.

One match refuses the bundle whole. The verifier returns no accepted subset with the revoked branch cut away, and work already dispatched keeps running. Capability ids in node and cluster stores are withdrawn through Revocation Propagation, and federated revocation through the Revocation Oracle, which answers with membership or non-membership evidence against an accumulator root.

The list root is the digest of two sorted lists

Sort each list, serialize this object as canonical JSON, and take its SHA-256. The epoch id, timestamps, issuer, schema, and signature stay out of it.

{"revokedSubjects":[],"revokedTaskIds":["task-child-a"]}

1d8a51dddeecdf187968776b181b57d45367737df9de95433ed4dfaeff6093e3

Two empty lists produce 144bab856830b54b1d138a96909cfac3f8c92cd33090cf6918de3949ac9fb5b2, the root of the valid fixture. Reordering a list leaves the root unchanged; a duplicate entry changes it, because sorting keeps duplicates. The root is a digest of the full lists, so verification needs the lists themselves and offers no Merkle inclusion proof.

The epoch stage stops the verifier at its first failed check

The epoch stage runs after the graph, route, join, and budget checks and before terminal receipts, continuations, and witnesses. Inside it, five checks run in order.

1. Shape and reference. The schema tag, non-empty fields, and the graph’s revocationEpochRef equal to epochId.
2. Window. The evaluation time falls in the half-open window: issued at or before now, and now strictly before validUntilUnixMs.
3. Root. rootHash equals the digest recomputed from the two sorted lists.
4. Signature. The issuer parses to a pinned key, and the signature verifies over the canonical epoch.
5. Membership. No graph signer is a revoked subject, and no graph node is a revoked task.

At validUntilUnixMs the epoch is stale, and continuing takes a replacement epoch. The verifier keeps no record of newer epochs, so a superseded epoch passes while its window is open: the operator chooses the current view and bounds how long a window may run.

The prepared example revokes a child and re-signs its continuations

The downloadable Rust project verifies the original bundle, adds task-child-a to the revoked set, recomputes the sorted root, signs the epoch, and rebinds the continuations to the new root.

cargo run --locked --bin revocation

use chio_swarm_authority::verify_swarm_authority_bundle;
use swarm_authority_examples::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut bundle = build_bundle()?;
    verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())?;
    println!("before revocation: verified");
    bundle
        .revocation_epoch
        .revoked_task_ids
        .push("task-child-a".into());
    // Hash sorted subject/task lists, sign the epoch, then rebind continuations.
    // This isolates revocation from a stale-digest or bad-signature failure.
    refresh_revocation_epoch_root(&mut bundle)?;
    println!(
        "revoked child: {}",
        verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())
            .expect_err("revoked child cannot verify")
    );
    Ok(())
}

pub fn revocation_epoch_root_hash(
    revoked_subjects: &[String],
    revoked_task_ids: &[String],
) -> Result<String, Box<dyn Error>> {
    let mut subjects = revoked_subjects
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    subjects.sort_unstable();
    let mut task_ids = revoked_task_ids
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    task_ids.sort_unstable();
    canonical_hash(&serde_json::json!({
        "revokedSubjects": subjects,
        "revokedTaskIds": task_ids,
    }))
}

pub fn refresh_revocation_epoch_root(
    bundle: &mut SwarmAuthorityBundle,
) -> Result<(), Box<dyn Error>> {
    let root_hash = revocation_epoch_root_hash(
        &bundle.revocation_epoch.revoked_subjects,
        &bundle.revocation_epoch.revoked_task_ids,
    )?;
    bundle.revocation_epoch.root_hash = root_hash.clone();
    sign_revocation_epoch(&mut bundle.revocation_epoch)?;
    for token in &mut bundle.continuation_tokens {
        token.revocation_epoch_root_hash = root_hash.clone();
        sign_continuation_token(token)?;
    }
    Ok(())
}

before revocation: verified
revoked child: swarm task is revoked: task-child-a

You should see the original bundle verify and the rebound bundle refused with swarm task is revoked: task-child-a. Re-signing the continuations clears the root comparison; the membership check still refuses the revoked child.

A revoked child takes its siblings’ authority with it

The negative fixture lists task-child-a in revokedTaskIds while the graph still contains that node, and both continuation tokens carry the epoch’s new root. Verification reaches the membership check and refuses the bundle.

$ chio proof verify ./swarm/negatives/revoked-task --trust ./swarm/trust.toml

REFUSED   revoked-task  swarm task is revoked: task-child-a
trust     ./swarm/trust.toml (fixture keys)

The task id in the message names the membership that refused the bundle; the siblings are refused with it. When siblings must continue independently after one branch is revoked, give them separate graphs.

A replacement view re-signs every continuation that commits to it

Changing who is revoked changes the root, and every artifact that carries the root or the id moves with it.

1. Build the new subject and task lists and compute their canonical root.
2. Choose the epoch id and window, then sign the epoch with a pinned key.
3. Update each continuation’s epoch reference and root and sign it again. A new epoch id also means rebuilding the graph’s reference.
4. Rebuild the whole-artifact evidence references and verify the complete replacement bundle before admission.

Old tokens presented with a changed root fail their root comparison. A replacement that revokes a task still in the graph refuses first at membership, even after every token is re-signed. The admission stores hold one bundle per task-graph id and refuse a different bundle under an existing id with duplicate_swarm_authority_bundle_mismatch, so a replacement view arrives as a new bundle.

Read more in Task Graphs, which defines the graph boundary a revocation reaches.

Epoch fields, diagnostics, and boundaries

Next: carry the epoch into each child’s admission