Atproto spaces (alpha)
Spaces are the AT Protocol’s proposal for permissioned data (proposal 0016): records that live on your PDS like public records do, but are only readable by people the space’s owner has authorized. A private bookmarks collection, a members-only forum, a shared group — each is a space.
Cirrus implements the spaces alpha behind the SPACES_ENABLED flag. Everything about it — the protocol, the lexicons, the dependencies — is alpha and can break between builds. See Enable spaces for setup, and read the caveats below before turning it on.
What a space is
Section titled “What a space is”A space is identified by a URI like:
at://did:web:alice.example.com/space/app.bsky.group/3kbcq3p7ad400That’s an authority (the DID that owns the space and decides who may read it), a type (an NSID describing what kind of space it is), and a key distinguishing multiple spaces of the same type.
Every participant stores their own records for a space in their own PDS — their permissioned repo for that space. Reading a space means collecting the repos of its writers from wherever each is hosted.
The three roles Cirrus plays
Section titled “The three roles Cirrus plays”Because Cirrus is single-user, one account wears three hats:
- Repo host — serving your own permissioned repos, one per space you have written into, whether you own the space or not.
- Space host — for spaces you own: issuing credentials to readers, tracking who has written (and who has been removed), notifying syncers of those changes, and managing membership.
- Your PDS — minting short-lived delegation tokens so apps you’ve signed into can read spaces hosted elsewhere.
How access control works
Section titled “How access control works”Reading a space requires a space credential from its authority. The flow:
- Your app asks your PDS for a delegation token: a 60-second, single-use JWT proving the app acts for you.
- The app generates a P-256 key and asks the space’s authority for a credential bound to it: a ten-minute JWT. A space that is publicly readable issues one without a delegation token.
- Every read presents the credential with an HTTP message signature by that key, naming the service it is addressed to. A stolen credential is useless without the key, and a signed request for one host can’t be replayed at another.
Whether the authority grants a credential is up to the space’s policy. Cirrus implements the three baseline policies every PDS supports:
- personalspace: only you. For bookmarks, drafts, mutes.
- memberspace: a member list you manage, where each member can be allowed to read, to write, or both. It can be opened to everyone for reading (
publicRead) or writing (publicWrite), and restricted to named apps (allowedApps, checked against client attestations). - managedspace: a nominated app service (named as
did#service) is asked to decide, per user, per request. If it can’t be reached the request fails withUpstreamFailure, rather than being treated as a refusal.
Someone the policy refuses is told the space doesn’t exist, so a refusal reveals nothing about it. A memberspace or managedspace can also publish its policy, and a memberspace its member list, as records in your own repo in the space, so readers can see who else is in it.
A syncer that wants to hear about changes passes a webhook endpoint and a token of its own with its credential request. The first time, your PDS calls the syncer back (confirmRegistration) to check it really asked; after that, every writer update goes to the endpoint, with the token, until the registration lapses with the credential. A registration that lapses gets one final notice saying so, and if the space is deleted every syncer that ever registered is told, with retries for up to three days.
Writes never use credentials: they’re ordinary authenticated requests to your own PDS, covered by OAuth space: grants or your own full-access session. App passwords are deliberately excluded.
Proving data came from you
Section titled “Proving data came from you”Space data isn’t signed. Instead, your PDS has a second key, published in your DID document as #atproto_kem. A syncer reading your repo sends an ephemeral key with each request, both sides derive a one-off shared secret, and your PDS returns a MAC: an HTTP message signature keyed by that secret, over an Atproto-Space-Commit or Atproto-Space-Record header describing the data. The syncer knows the data is yours; but because the syncer could have computed the same MAC itself, a leaked response proves nothing to anyone else. That’s the point: private data shouldn’t come with a signature that lets it be passed around as authentic.
Cirrus can’t serve space data to syncers without this key. pds spaces kem creates it; see Enable spaces.
A blob referenced only from a space record is fetchable only through the credential-gated com.atproto.space.getBlob — never from the public sync.getBlob, even by someone who knows its CID. To enforce this cheaply, uploads are staged (<did>/staged/<cid> in R2) until a record references them, then copied to a public or per-space key. This staging applies to the public path too, flag or no flag: it closes the gap where any uploaded blob was public the moment it was uploaded.
Isolation, by construction
Section titled “Isolation, by construction”Space state never touches your public repository. It lives in its own Durable Objects (one per space, plus a small index) and its own R2 prefix (<did>/space/). The account Durable Object — your MST, your firehose — has no space tables and no space code paths.
This is what makes the alpha safe to run: when an alpha build breaks the schema, the space Durable Objects refuse to open and every space endpoint returns a clear error, while your public repo and firehose carry on untouched. Recovery is one command:
pds spaces resetwhich deletes all space data — and can only delete space data. There is no migration between alpha schema versions, matching the upstream policy.
Alpha caveats
Section titled “Alpha caveats”- Interop is the point, stability is not. Cirrus targets the reference alpha PDS and apps like bulletin.my. Expect breaking changes; expect
pds spaces resetto be part of upgrading. - Migration is new. The protocol can now move space data between hosts:
pds spaces exportwrites each space repo as a STAR archive (and, for spaces you own, the space’s policy, members and writers as a space meta archive), whichcom.atproto.space.importSpaceMetaandimportRepoaccept on the new host. Notification registrations, revoked credentials and deleted-space tombstones don’t move. Nothing migrates between alpha builds: that’s stillpds spaces reset. - Access control, not encryption. Space data is not encrypted at rest beyond what R2 and Durable Object storage already do. Your PDS (and any space host) can read what it stores.
- Pinned dependencies. The
@atproto/spaceand@atproto/oauth-scopesalpha builds are pinned exactly and excluded from automatic updates.@atproto/spaceand its alpha dependencies are bundled into@getcirrus/spaces, because several of them have broken releases that would otherwise be installed in their place.