The space repo
The repo host’s part of spaces: each account’s records in a space, its space repo, written by the account and read back by it. What spaces are, their keys, and the building blocks this page uses (LtHash, record CIDs, commits, MACs and their headers) are in Spaces; what every method shares, and how the server is checked, is in The PDS: accounts and their records.
The methods, all com.atproto.space: createRecord, putRecord,
deleteRecord, applyWrites and clearRecords, which write; and
getRecord, listRecords, getLatestCommit, listRepoOps and
listSpaces, which read. Their lexicons are in lexicons/com/atproto/space,
with defs (the commit).
A space repo
Section titled “A space repo”An account has one space repo in each space it has written to. A space repo
is a set of records, each named by a collection (an NSID) and a record key,
as in a public repository, and its commit, {ver: 1, repo, space, rev, data} as Spaces defines it: repo the account’s DID, space the
space’s URI, rev a TID, and data the LtHash digest of the elements
{collection}/{rkey}/{cid} of every record it holds.
- A space repo comes to be with the first write that makes a commit (below). There is no method that creates or deletes one. A write that makes no commit, or is refused, leaves no repo behind.
- A record is a DRISL value, stored and served as a public record is
(The repository's records): a record without
$typeis stored with$typeset to its collection, which is part of what its CID covers, and its CID is the Spaces record CID. - A record’s URI is
at://{authority}/space/{type}/{skey}/{account}/{collection}/{rkey}: the space’s URI, the account’s DID, the collection and the key. - Each write that changes the repo, or that
applyWritesmakes from a batch, is one commit: a newrev, later than the repo’s last, anddataof the records after it. Itsrevis a TID of the time it was made, or the TID one after the lastrevif that is not later. All the operations of one commit share itsrev. - The operation log holds one entry per operation, in order:
{rev, collection, rkey, cid, prev},cidthe record’s CID after it (nullfor a delete) andprevits CID before (nullfor a create),revthat of the commit it was part of. An operation’s position is its commit’srevand its index within that commit, from 0. The log holds every operation since the repo began, or since its lastclearRecords. - A space repo is apart from the account’s public repository: no write here
changes the public repository, its commit or its
rev, and nothing of it is on the firehose.
Who may call
Section titled “Who may call”Each method takes the account’s access token, from a session made with its
password or an app password (Sessions), as the public repository’s
methods do: none is 401 AuthMissing, and one the server did not give out,
or a refresh token, 400 InvalidToken; and an OAuth access token, allowed
what its space: permissions allow (OAuth: access tokens on every method, and what scopes allow, “Spaces”). A space
credential is for the reads of others (the credentials part, below).
- A write is to the caller’s own repo only: a
repoother than the token’s DID is403 Forbidden, whether or not any account has that DID. A handle is not a DID, so it is400 InvalidRequest(repo’s lexicon format). - A read with a token reads the caller’s own repo only: a
repoother than the token’s DID is400 RepoNotFound, whether or not that account has a repo in the space.
Writes
Section titled “Writes”The order of the checks
Section titled “The order of the checks”A write checks, in this order, and answers the first that fails:
- its token (above), and then its account’s state (Account lifecycle, taken
down before deactivated): deactivated is
401 AccountDeactivated, taken down401 AccountTakedown, for as long as an access token made before lives. These are the public repository’s writes’ answers, but come here before anything else of the request, its body’s size, its input and itsrepoincluded; - the size of its body: a JSON body longer than 1000000 bytes for
createRecord,putRecordandapplyWrites, or 153600 bytes fordeleteRecordandclearRecords, is413 PayloadTooLargeError. A body of exactly the limit is taken; - its input against the lexicon,
400 InvalidRequest:spacemust be aspace-ref(Spaces),repoa DID,collectionan NSID,rkeya record key,recordan object, each ofapplyWrites’writesan object whose$typeiscom.atproto.space.applyWrites#create,#updateor#delete(notcom.atproto.repo.applyWrites’s), with its properties. Properties the lexicon does not name are ignored; repo, as above;- for
applyWrites, more than 200 writes is400 InvalidRequest; 200 is taken, and so are none; - each record and collection, below, all
400 InvalidRequest; - then what depends on what is stored: the space (below), and whether the records named exist.
Records
Section titled “Records”As for a public record (The repository's records), each 400 InvalidRequest:
- a
$typeother than the collection; - a value outside the data model, such as a float. A JSON number whose value
is whole is an integer however it is written:
1e3,1E3and1000.0are the integer 1000, and-0is0, so the record is the same as with1000or0; validate: true, as the server knows no lexicon for any record type. Withvalidate: falsethe write is made, and its answer, or eachapplyWritesresult, has novalidationStatus; otherwisevalidationStatusisunknown.
And for a space record:
-
a record whose DRISL encoding is longer than 1048576 bytes (1 MiB, the longest value a STAR archive of the repo may hold, Spaces) is refused. One of exactly 1048576 bytes is taken.
Note: a JSON body within its limit can still hold one, as an integer like
9e15takes 4 bytes of JSON and 9 of DRISL.
The published collections, com.atproto.space.policy and
com.atproto.memberspace.member, are written only by the space host, from
a space’s configuration (the policies part). A write naming either, as
createRecord, putRecord or deleteRecord’s collection or any write
of an applyWrites, is refused, in every repo and every space, whatever
its record. createRecord and putRecord check the collection before the
record; applyWrites checks every write’s record, in order, then every
write’s collection. Each refusal is 400 InvalidRequest either way.
The space
Section titled “The space”A write into a space whose authority is another DID is taken without asking
whether the space exists, or whether its authority does. A write into a
space whose authority is the caller itself must find that space created
on this server and not deleted (the policies part’s createSpace and
deleteSpace); otherwise a write that would make a commit is 400 SpaceNotFound. The space is checked before any record’s existence. A write
that makes no commit is not refused this way: deleteRecord of a record
that does not exist, clearRecords of a repo with no records, and an empty
applyWrites answer as below.
Note: the repo host holds the account’s records, and it is the space host that decides whose writes count (Spaces, the proposal).
Each write
Section titled “Each write”createRecord{space, repo, collection, rkey?, record, validate?}creates a record and answers{uri, cid, validationStatus?}. Withoutrkeythe key is a TID (atproto's Timestamp Identifiers (TIDs) spec), later than the last the server made. A record that exists at that key is400 RecordAlreadyExists.putRecord{space, repo, collection, rkey, record, validate?}creates the record or replaces it, answering ascreateRecord. It always makes a commit, even when the record is exactly the one stored: a newrev, the samedata, and an operation whosecidandprevare equal.deleteRecord{space, repo, collection, rkey}deletes the record and answers{}. A record that does not exist answers{}too, and makes no commit.applyWrites{space, repo, writes, validate?}makes every write, in order, as one commit, and answers{results}: for each write in order,{$type: "com.atproto.space.applyWrites#createResult", uri, cid, validationStatus?},#updateResultlikewise, or{$type: "com.atproto.space.applyWrites#deleteResult"}. Each write sees those before it in the batch: a batch may create a record and then update or delete it. A create of a record that exists is400 RecordAlreadyExists, and an update or delete of one that does not400 RecordNotFound; either refuses the whole batch, and nothing of it is kept. A batch whose writes leave the repo as it was still makes a commit. An empty batch answers{results: []}and makes none.clearRecords{space, repo}deletes every record of the repo and its operation log, and answers{}. If it deleted any record, that is a commit: a newrev,datathe digest of the records left (the empty digest, Spaces, unless some were kept), and an empty operation log. A repo with no records, or no repo, answers{}and makes no commit. In the authority’s own repo in its space, the records of the published collections are kept (the policies part writes them).
Each read
Section titled “Each read”-
getRecord?space&repo&collection&rkeyanswers{uri, cid, value}; a record not in the repo, or no repo, is400 RecordNotFound. -
listRecords?space&repo&collection?&limit?&cursor?&excludeValues?answers{records, cursor?}, each record{collection, rkey, cid, value}, withoutvaluewhenexcludeValuesistrue. Records are listed in descending order of the bytes of{collection}/{rkey}; withcollection, only those of it. Areverse, ascom.atproto.repo.listRecordstakes, is ignored, whatever its value, as is every parameter the lexicon does not name: the order is always descending.limitis 1 to 1000, 50 by default. Acursoris answered when the page is full (limitrecords): the URI of its last record, asgetRecordanswers it,{space}/{repo}/{collection}/{rkey}. A cursor of that form, of thespaceandrepoasked, is a position, whether or not such a record is or was ever there: the next page is the records whose{collection}/{rkey}is below the cursor’s, in the same order. So a client may start a page below a key of its choosing, as{space}/{repo}/{collection}/{prefix}.~starts below every key that begins with{prefix}.. No repo answers{records: []}. -
getLatestCommit?space&repoanswers{commit}, the repo’s commit,dataas{"$bytes": <base64>}. No repo is400 RepoNotFound. -
listRepoOps?space&repo&since?&limit?&cursor?&excludeValues?answers the operation log,{ops, commit, cursor?}: the operations in order of their position, with arevlater thansinceif it is given, after the cursor’s operation if one is given, at mostlimit(1 to 1000, 100 by default). Every page hascommit, the repo’s commit asgetLatestCommitanswers it, whether or not it has a cursor, the first page and the last included. A page of exactlylimitoperations has acursor, and any other none; a full page that happens to be the last has one, and the page after it is empty. An operation whosecidis that of the record its collection and key hold now hasvalue, the record, unlessexcludeValuesistrue; others have none. No repo is400 RepoNotFound, as forgetLatestCommit. -
listSpaces?spaceType?&spaceDid?&limit?&cursor?answers{spaces, cursor?}: every space the caller has a repo in, and every space whose authority it is that it created and has not deleted (the policies part), each once, withspaceTypeonly those of that type and withspaceDidonly those of that authority, in ascending order of the URI’s bytes.spaceDidmust be a DID (400 InvalidRequest); adid, or any other parameter the lexicon does not name, is ignored. Each is{space, repoRev?, data?, spaceRev?}:space, the space’s URI;repoRevanddata, therevanddataof the commit of the caller’s repo in the space,dataas{"$bytes": <base64>}, when the repo has a commit; a space the caller created whose repo has none yet has neither;spaceRev, for a space whose authority is the caller, the space’s latestspaceRev, that of the latest change to its writer set, removals included (Spaces: write notifications, the writer set and syncers, “The writer set: listWriters”), once it has one; none for another authority’s space.
limitis 1 to 100, 50 by default; acursoris answered when the page is full, and the next page is the spaces after its last.
Cursors
Section titled “Cursors”The server may choose what a listRepoOps or listSpaces cursor is: the
harness passes each side only the cursors it answered. A listRecords
cursor is a record’s URI, as the reference’s is (above), since clients
build one to start below a key. Every cursor listRecords, listRepoOps
and listSpaces answer has a / in it (the reference’s are the last
record’s URI, {rev}/{index} of the last operation, and the last space’s
URI), and a cursor with no / is 400 InvalidCursor. It is checked
after the repo and the account’s state (above) and before the repo is
read, so a space with no repo answers it too: for listRepoOps after its
Accept-Signature (below), and for listSpaces after the token. A
listRecords cursor with a / that is not a record URI of the space
and repo asked is 400 InvalidCursor; another method’s cursor with a
/ that the server did not answer may be taken or refused
InvalidCursor. listBlobs (Spaces: a repo whole, its blobs, and migration) takes any cursor.
MACs on request
Section titled “MACs on request”getRecord, getLatestCommit and listRepoOps authenticate what they
answer when asked, with the request header Accept-Signature, read as
Spaces (“MACs”) reads it for the one profile the method answers:
atproto-space-record for getRecord, and atproto-space-commit for the
other two (and for getRepo, Spaces: a repo whole, its blobs, and migration). With a token the header
is optional:
-
Without it, or with one that asks for no MAC of the method’s profile (no member tagged with it, as an empty header, or one asking only for the other profile’s), there is no MAC.
-
The header is read after the token, the
repo(above: another account’sRepoNotFound) and the account’s state, and before anything of the space repo is read: a header Spaces refuses (not a Dictionary, two members tagged with the profile, the member’s Inner List or its parameters other than they must be, a key share that is no P-256 key) is400 InvalidSpaceMac, even where the record or the repo does not exist; forlistRepoOps, before itscursor. -
With one that asks for a MAC, a
200has the profile’s three headers, as Spaces (“MACs”, “Answering”) says, under the shared secret of the key share and the account’s KEM key: forgetRecordAtproto-Space-Recordof the record’s full URI and its CID, and for the other twoAtproto-Space-Commitof the commit answered, on every page oflistRepoOps;Signature-Input, of the request’s label and Inner List; andSignature, the MAC. It also hasAccess-Control-Expose-Headersnaming, in any letter case, the covered header,Signature-InputandSignature.Note: it is there so a browser app can read them.
-
An answer that is an error has no MAC.
Every 200 of these three has Vary naming Accept-Signature, with the
header or without it. listRecords and listSpaces take no MAC, ignore
the header whatever it is, refused or not, and answer none of the MAC
headers.
Durability
Section titled “Durability”The space repos are the server’s state as the public repository is
(Durability): a write the server has answered survives it being killed
at any moment after, with its records, commit and operation log; a write it
is killed during lands whole or not at all; and the first commit of a space
repo after a restart has a rev later than every one before.
Commands
Section titled “Commands”Each method is an MCP tool and a CLI command, as Commands: every method as an MCP tool and a CLI command makes them
from the lexicons: group space, so space_create_record and pds space create-record, and so on; repo may be left out, as there. Every answer
is JSON, so each has a tool. deleteRecord, putRecord, applyWrites
and clearRecords may delete or replace records, so their tools have
destructiveHint: true; createRecord’s has false. Neither the tools nor
the commands send Accept-Signature: they answer the method’s JSON,
with no MAC.
For other parts
Section titled “For other parts”What other parts of spaces build on, as behaviour:
on_commit(space, repo, rev, data): the repo host calls it once for every commit of a space repo on this server, with the commit’s fields, after the commit is durable and before the write answers: for every write above that makes a commit,clearRecords’ included, and for no write that makes none. It never refuses or undoes the write: what it does with the commit (telling the space host,notifyRepoUpdate, and retrying) is Spaces: write notifications, the writer set and syncers’s (“Telling the space host: notifyRepoUpdate, sent”).- Whether a space exists, for the own-space rule above, is the policies
part’s: a space exists here from its
createSpaceuntil itsdeleteSpace. Its published records reach the authority’s own repo through the commits above, as records like any other (indata, the operation log and the reads), past the published-collection refusal, which is only for the methods’ callers. - A space credential (
verify_space_credential, Spaces: credentials, “For the other parts”) lets a syncer call the four readsgetRecord,listRecords,getLatestCommitandlistRepoOpson any account’s repo in the credential’s space, with the answers above; Spaces: a repo whole, its blobs, and migration (“Who may read”) says the order of the checks and that a MAC is then required. - Full state (
getRepo, Spaces: a repo whole, its blobs, and migration) is the repo’s commit and its records in ascending order of{collection}/{rkey}, as above.importRepothere makes a commit but calls noon_commit.
How it is checked
Section titled “How it is checked”The spaces run (Spaces) starts the alpha with a second PDS, the space
host: the harness makes accounts there, the authorities, and each
creates spaces on it with the alpha’s createSpace. Each account the run
makes on both sides then writes into those spaces from its own repo host,
the alpha’s first PDS on the reference side and the server on the other,
and into spaces of authorities no PDS has (a random did:plc, a
did:web), which no repo host checks. Both sides write into the same
spaces, so the spaces’ URIs are the same on both sides. --space-steps N
sets how many steps it takes, 200 by default.
Writes into a space of the caller’s own are refused on both sides, as neither has created one: until the server serves the policies part, the run has no space of the server’s own to write to, and the own-space rule is checked only as a refusal.
Each step is drawn from the run’s seed and sent to both sides, and the
answers are compared as The PDS: accounts and their records says, with each side’s account DIDs named
alike, record keys the server made (TIDs) named by their order, revs,
repoRevs and spaceRevs named by their rank in time among each answer’s,
data taken out after it is checked on each side (below), and which of the
MAC headers an answer has compared. The steps: each write, with records
good and bad, in the authorities’ spaces, unknown authorities’ spaces, the
account’s own space, malformed space-refs, another account’s repo, the
published collections, validate set and not; clearRecords; each read,
paging listRecords (sometimes with a reverse), listRepoOps and
listSpaces (with spaceDid, and sometimes a did) through with the
side’s own cursors; reads of another account’s repo; calls with no token, a
bad token, a refresh token and an app password’s token; cursors with no
/; and Accept-Signature headers drawn from the seed: none, one as a
syncer formats it (mac, sig or another label, with alg or without),
or one of interop/spaces/mac.json’s accept_signature cases, with the
harness’s key share and the method’s profile put in, refused, asking for
no MAC, or asking for one, as the case says.
On each side, and so on the reference too, which checks the check:
- the harness keeps the records it wrote, with CIDs it computes from the
DRISL it encodes itself; each answer’s
cidmust be that, and every commit’sdatathe LtHash digest of the records, computed byharness/spaces/lib/spec.mjs; - every
revis a TID later than the repo’s last commit’s; listRecordsis in descending order whateverreversesays;listRepoOpsfrom the start, replayed from the empty LtHash (eachcidadded, eachprevremoved), must give the commit’sdata, every page must have the repo’s commit, and acursorexactly when it is full; a repo never written must beRepoNotFound;listSpacesmust list the spaces the account wrote to, each with therepoRevanddataof its repo’s commit;- a cursor with no
/must be400 InvalidCursor; - with a MAC asked for, the answer’s MAC must verify with
spec.mjsfrom the harness’s own key share, its covered header name the record or commit the answer holds, itsSignature-Inputbe the request’s label and Inner List, and the answer have theVaryandAccess-Control-Expose-Headersabove; with none asked for, it must haveVaryand none of the MAC headers; a refused header must be400 InvalidSpaceMac, whether or not the record or repo exists; - the account’s public repository’s
getLatestCommitis unchanged by them.
The size limits are checked at their edges: bodies of 1000000 and 1000001
bytes, and of 153600 and 153601, and records whose DRISL is 1048576 and
1048577 bytes, with whole numbers written as exponents. Then the server is
killed and started again (Spaces), and every space repo read whole
again must still match the reference’s; a write after it must have a later
rev.
Not compared: a cursor’s text, which is each side’s own; listRecords
and listRepoOps given a cursor with a / the side did not answer (the
reference takes x/1 for listRepoOps, reading x as a rev); Vary and
Access-Control-Expose-Headers on an error (the reference answers them
on the errors that come after the header is read); error messages;
the firehose (the public repository’s unchanged commit stands for it); a
write the server is killed during; and space credentials, OAuth tokens
(OAuth: access tokens on every method, and what scopes allow, “Spaces”, checks them), and the notifications the repo
host sends, which are other parts’. An
account deactivated or taken down is checked by the policies’ stage 5
(Spaces: policies and the space lifecycle): each write above, with the account’s token from
before, and with a body past the limit, input the lexicon refuses and
another account’s repo, is refused for the state, compared once the
server can put an account in it.