The Core Insight

ATProto is a stateful, universally addressed data protocol. Records exist. They persist. They outlive any particular action taken on them. This is not incidental — it is the foundational property that makes ATProto what it is.

Capability Trees is built around this property. In the online verification case, statefulness is the point. A delegation is not a token you present at invocation time. It is a record that exists on its issuer's PDS right now, or it does not. Verification resolves live records and asks: does this chain currently exist? The answer is in the state of the world at the moment of asking. This is a different trust model than token-based capability systems, and the difference matters.

The Problem

Traditional object capability systems assume a controlled runtime. Possession of an unforgeable reference is sufficient authorization — if you hold it, you can use it. This works in closed systems where the runtime mediates all access.

In an open decentralized protocol like ATProto, this assumption breaks. Anyone can read records, build clients, and attempt to use references. The runtime cannot be trusted to mediate all access.

Modern distributed capability systems address this with audience restriction: a capability is cryptographically bound to its intended recipient and requires a signature from that recipient at invocation time. Possession alone is insufficient; you must prove you are the intended audience.

These systems are invocation-oriented — a capability token is presented to perform an action. ATProto is different in kind. It is a stateful, universally addressed data protocol where records persist and outlive any particular invocation. Capability Trees is built for this model. Authority is not carried in a token presented at invocation time. It exists in the state of the world — in records on PDSes, right now — and is verified by resolving that state directly. Capability Trees adds one property this model makes uniquely tractable: sovereign revocation without a revocation list, grounded in ATProto's existing deletion semantics.

The Mechanism

Online verification: signed request as audience proof

Every capability delegation is a record on the issuer's PDS. As with all ATProto records, signing and attribution are cryptographically enforced by the protocol — this is ambient infrastructure, not something Capability Trees adds. Each delegation specifies its intended recipient's DID. Every delegation chain traces back to a root record on the issuing party's PDS — deleting it returns a 404, breaking the chain immediately, without coordination, without a revocation list, without notifying downstream delegatees. Absence of the record is the answer.

To verify a capability, the verifier resolves the full delegation chain live — every signed link from the root to the terminal recipient, each from its authoritative PDS. The verification request itself is the audience proof. The requester signs the request with their private key. The verifier finds the intended recipient DID at the terminal link and checks it against the DID document of whoever signed the request. If they match, the requester has proven they are the intended audience without presenting anything beyond an authenticated request. This is the same inter-service authentication ATProto already uses throughout — Capability Trees inherits it as ambient infrastructure.

Each party in the chain is accountable upward to whoever granted them access, and authoritative downward over whoever they delegated to. Governance happens as close to the terrain as possible.

UCAN attestation: portable audience binding

When the verifier issues a snapshot, it wraps the confirmed chain into a UCAN — a JWT signed by the verification service's DID, with the audience field set to the requester's DID and an expiry bounding the staleness window. To use the UCAN, the holder proves they control the private key of the audience DID by signing a challenge with it. A verifier checks the signature against the public key in the audience DID's document. Possession of the UCAN alone is insufficient — you must also hold the private key of the DID it was issued to.

The PKI is identical to the online case. The difference is where the verification work happens — live resolution at request time versus a previously issued attestation the holder carries forward. The trust model is the same in both modes.

Revocation

The issuer deletes their delegation record. The PDS returns a 404. The verifier's cache updates. Active UCAN holders are notified immediately — point-to-point, no broadcast, no list. Offline holders are caught the moment they reconnect. The revoker performs one action and the rest of the system converges on its own schedule, without coordination, without waiting for expiry. In the UCAN case, the verifier is required to notify active UCAN holders directly when a chain they hold is revoked — point-to-point, immediate, directly from the verifier's persistent state.

UCAN deliberately leaves revocation underspecified — it is designed to be flexible across deployment contexts, and revocation is a problem each deployment must solve for itself. Capability Trees is that solution for ATProto. The gap UCAN left open is filled precisely and completely by the verifier's persistent state, without requiring anything beyond what the protocol already provides.

This is not a workaround. It is the best revocation infrastructure you could ask for — and it falls out of the architecture for free.

Verification

The chain is distributed across records on each issuer's PDS. Verification resolves each link from its authoritative source. Because links are resolved in parallel, verification latency is bounded by the slowest single PDS in the chain — not by chain depth.

The verification service returns one of three results:

  • Green light — 200 OK; all links resolved and valid; the chain currently exists. Body contains UCAN if requested.

  • Abort — 403 Forbidden; a PDS returned a definitive 404; the chain is broken; revocation is authoritative. The delegation record's absence on its issuer's PDS becomes a 403 to the requester — you are not authorized because the authorization no longer exists.

  • Unresolvable — 503 Service Unavailable; one or more PDSes did not respond; the state is ambiguous. The 503 already carries the correct semantic of "try again later" — the client knows this is an infrastructure problem, not a rejection.

The mapping to HTTP status codes is not incidental. The distinction between 403 and 503 at the HTTP layer is the same load-bearing distinction between abort and unresolvable in the trust model. A 404 on a delegation record is authoritative — the authorization no longer exists. A timeout is ambiguity about state. Collapsing these into the same signal would force clients to treat a network hiccup as a revocation, undermining the entire value of the stateful model. Any HTTP client already knows 403 and 503 mean different things. The semantic clarity is inherited for free.

Two Verification Modes

Online Verification: Stage and Commit

For one-off operations, the application stages the operation optimistically and waits for the green light before committing. The user sees a fast response immediately. Data integrity waits on the authoritative result in the background. On an unresolvable result, the operation is bounced and the user is told why — it is a temporary infrastructure issue, not a rejection.

This is standard optimistic concurrency. No exotic error handling required.

UCAN Attestation: Snapshot for Sustained Work

For high-frequency or offline use cases, the application requests a UCAN attestation from the verification service upfront.

The verification service resolves the chain online, confirms audience binding at each link, and if everything checks out issues a UCAN attesting to the validity of that chain for the requesting DID, with an expiry bounding the staleness window. The UCAN is a JWT — signed by the verification service's DID, audience-bound to the requester, expiring at a time the application chooses.

The recipient holds a standard UCAN they can use locally without further network calls. Any consumer that can verify JWTs can check it. Revocations that happen after issuance are bounded by the expiry window — the same tradeoff as any offline capability system.

This mode serves two cases with the same mechanism:

High-frequency work: If you are exercising a capability heavily over a bounded window — many writes in a minute, a sustained editing session — request a UCAN at the start of the work. Pay the verification cost once. Use the UCAN locally through the window. Refresh when it expires. Network bandwidth is not consumed on every operation.

Offline operation: If you know you will not have network access, request a UCAN with a longer expiry before going offline. Use it while disconnected. The staleness tradeoff is explicit and chosen.

The verification service is identical in both cases. Expiry window is the only variable the application controls.

Capability Trees and UCAN

Capability Trees is the stateful layer. It answers: does this authorization currently exist in the world? The answer lives in PDS records, resolved live. This is the authoritative source of truth.

UCAN is the invocation layer. It answers: I was authorized at a specific moment — here is a portable proof of that. The answer lives in a signed token, carried forward through time or across a network boundary.

These are not competing models. They are complementary layers of the same system. You verify against the stateful layer to establish ground truth. You issue a UCAN when you need to carry that ground truth somewhere that cannot or should not re-verify from scratch — a high-frequency work session, an offline context, a consumer that needs a portable credential. The UCAN does not replace the stateful check. It is a snapshot of it, valid for a bounded window, for a specific recipient.

This is also why Capability Trees fits ATProto naturally in a way that a pure token-based system would not. ATProto's data outlives any particular invocation. So does the authority Capability Trees encodes. The stateful layer is primary. UCAN appears only as a transport for verified state.

The verifier's persistent state closes the revocation story

The verifier is stateful by necessity — it maintains a cache of chain states to avoid resolving live on every UCAN usage. That same statefulness, for free, gives near-instant revocation even in the UCAN case.

When a delegation record is deleted, the verifier's cache updates. Two things follow automatically. For connected UCAN holders, the verifier pushes a revocation notification directly — point-to-point, no revocation list, just an update to the party holding the affected UCAN. For offline holders, the cache has already updated by the time they reconnect. They present their UCAN, the verifier checks the cache, and if the chain broke while they were gone, 403. The holder never exercises a revoked capability regardless of the UCAN's expiry window.

Expiry is therefore not a revocation mechanism. It is a cleanup mechanism — how long the verifier retains its record of an issued UCAN. Revocation happens when state changes, which the verifier observes continuously. The expiry window is a ceiling that in practice almost never determines when access ends.

The system fails safe in both directions. If the verifier revokes conservatively — say, a PDS was temporarily unreachable and it couldn't confirm the chain was still live — the holder simply requests a fresh UCAN. The verifier resolves live, confirms the chain, issues a new UCAN. The cost of a false revocation is a brief interruption. The cost of a false authorization is a revoked party retaining access. The asymmetry favors caution, and the recovery mechanism makes caution cheap: if the verifier made a mistake, just ask for another UCAN.

Metadata and Space Boundaries

A concern raised about Capability Trees is that delegation records stored in the issuer's repository are public, leaking metadata about the existence and membership of permissioned spaces.

This concern points at a real tradeoff, not a flaw. The boundary of a permissioned space must be visible to the network to be enforceable by it. A space that is completely invisible cannot be enforced. Some metadata exposure is a precondition for network-level access control, not an artifact of a particular design choice.

The question is whether that exposure is proportionate and contained. Work in the ATProto Private Data Working Group — in particular Nick Gerakines' metadata-only CAR proposal — addresses this at the infrastructure layer. A metadata-only CAR makes the structure of a repository visible without exposing record content. Applied to delegation records, the network can confirm that a delegation exists and verify its CID against the MST without reading the content of the delegation. This is the appropriate separation: structure visible for enforcement, content gated for privacy.

Capability Trees and the metadata-only CAR infrastructure are complementary layers. The infrastructure layer handles what the network can see. The governance layer handles what authority flows from what it sees.

Properties

  • No ACLs at any layer

  • No revocation lists

  • No central administrator

  • No coordination required for revocation

  • Revocation effective within a single network round trip to the issuer's PDS

  • Verification latency bounded by slowest PDS, not chain depth

  • Two verification modes: online stateful for one-off operations, UCAN attestation for sustained or offline work

  • Verifier written once, shared by every project

  • Delegation chains fully legible and auditable

  • Fractal accountability: authority flows downward, accountability flows upward

  • Space identity stable across governance changes

Open Questions

The most significant open question is how permissioned spaces are bounded — how membership is defined, how the edges of a space are expressed in the protocol, and how that interacts with the authority model Capability Trees describes. These questions are coupled. The shape of a space affects what a capability chain needs to express, and the authority model affects what space boundaries can meaningfully enforce.

Work is actively underway in the ATProto Private Data Working Group. Nick Gerakines' metadata-only CAR proposal is an important piece of this — it addresses how the network can see that a space exists and enforce its boundaries without exposing the content of permissioned records. That work and Capability Trees are complementary layers of the same problem, and we are working to understand how they fit together precisely.

We are still working through these questions. Please bear with us.