Skip to content

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).

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 $type is stored with $type set 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 applyWrites makes from a batch, is one commit: a new rev, later than the repo’s last, and data of the records after it. Its rev is a TID of the time it was made, or the TID one after the last rev if that is not later. All the operations of one commit share its rev.
  • The operation log holds one entry per operation, in order: {rev, collection, rkey, cid, prev}, cid the record’s CID after it (null for a delete) and prev its CID before (null for a create), rev that of the commit it was part of. An operation’s position is its commit’s rev and its index within that commit, from 0. The log holds every operation since the repo began, or since its last clearRecords.
  • 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.

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 repo other than the token’s DID is 403 Forbidden, whether or not any account has that DID. A handle is not a DID, so it is 400 InvalidRequest (repo’s lexicon format).
  • A read with a token reads the caller’s own repo only: a repo other than the token’s DID is 400 RepoNotFound, whether or not that account has a repo in the space.

A write checks, in this order, and answers the first that fails:

  1. its token (above), and then its account’s state (Account lifecycle, taken down before deactivated): deactivated is 401 AccountDeactivated, taken down 401 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 its repo included;
  2. the size of its body: a JSON body longer than 1000000 bytes for createRecord, putRecord and applyWrites, or 153600 bytes for deleteRecord and clearRecords, is 413 PayloadTooLargeError. A body of exactly the limit is taken;
  3. its input against the lexicon, 400 InvalidRequest: space must be a space-ref (Spaces), repo a DID, collection an NSID, rkey a record key, record an object, each of applyWrites’ writes an object whose $type is com.atproto.space.applyWrites#create, #update or #delete (not com.atproto.repo.applyWrites’s), with its properties. Properties the lexicon does not name are ignored;
  4. repo, as above;
  5. for applyWrites, more than 200 writes is 400 InvalidRequest; 200 is taken, and so are none;
  6. each record and collection, below, all 400 InvalidRequest;
  7. then what depends on what is stored: the space (below), and whether the records named exist.

As for a public record (The repository's records), each 400 InvalidRequest:

  • a $type other 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, 1E3 and 1000.0 are the integer 1000, and -0 is 0, so the record is the same as with 1000 or 0;
  • validate: true, as the server knows no lexicon for any record type. With validate: false the write is made, and its answer, or each applyWrites result, has no validationStatus; otherwise validationStatus is unknown.

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 9e15 takes 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.

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).

  • createRecord {space, repo, collection, rkey?, record, validate?} creates a record and answers {uri, cid, validationStatus?}. Without rkey the key is a TID (atproto's Timestamp Identifiers (TIDs) spec), later than the last the server made. A record that exists at that key is 400 RecordAlreadyExists.
  • putRecord {space, repo, collection, rkey, record, validate?} creates the record or replaces it, answering as createRecord. It always makes a commit, even when the record is exactly the one stored: a new rev, the same data, and an operation whose cid and prev are 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?}, #updateResult likewise, 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 is 400 RecordAlreadyExists, and an update or delete of one that does not 400 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 new rev, data the 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).
  • getRecord ?space&repo&collection&rkey answers {uri, cid, value}; a record not in the repo, or no repo, is 400 RecordNotFound.

  • listRecords ?space&repo&collection?&limit?&cursor?&excludeValues? answers {records, cursor?}, each record {collection, rkey, cid, value}, without value when excludeValues is true. Records are listed in descending order of the bytes of {collection}/{rkey}; with collection, only those of it. A reverse, as com.atproto.repo.listRecords takes, is ignored, whatever its value, as is every parameter the lexicon does not name: the order is always descending. limit is 1 to 1000, 50 by default. A cursor is answered when the page is full (limit records): the URI of its last record, as getRecord answers it, {space}/{repo}/{collection}/{rkey}. A cursor of that form, of the space and repo asked, 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&repo answers {commit}, the repo’s commit, data as {"$bytes": <base64>}. No repo is 400 RepoNotFound.

  • listRepoOps ?space&repo&since?&limit?&cursor?&excludeValues? answers the operation log, {ops, commit, cursor?}: the operations in order of their position, with a rev later than since if it is given, after the cursor’s operation if one is given, at most limit (1 to 1000, 100 by default). Every page has commit, the repo’s commit as getLatestCommit answers it, whether or not it has a cursor, the first page and the last included. A page of exactly limit operations has a cursor, and any other none; a full page that happens to be the last has one, and the page after it is empty. An operation whose cid is that of the record its collection and key hold now has value, the record, unless excludeValues is true; others have none. No repo is 400 RepoNotFound, as for getLatestCommit.

  • 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, with spaceType only those of that type and with spaceDid only those of that authority, in ascending order of the URI’s bytes. spaceDid must be a DID (400 InvalidRequest); a did, or any other parameter the lexicon does not name, is ignored. Each is {space, repoRev?, data?, spaceRev?}:

    • space, the space’s URI;
    • repoRev and data, the rev and data of the commit of the caller’s repo in the space, data as {"$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 latest spaceRev, 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.

    limit is 1 to 100, 50 by default; a cursor is answered when the page is full, and the next page is the spaces after its last.

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.

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’s RepoNotFound) 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) is 400 InvalidSpaceMac, even where the record or the repo does not exist; for listRepoOps, before its cursor.

  • With one that asks for a MAC, a 200 has the profile’s three headers, as Spaces (“MACs”, “Answering”) says, under the shared secret of the key share and the account’s KEM key: for getRecord Atproto-Space-Record of the record’s full URI and its CID, and for the other two Atproto-Space-Commit of the commit answered, on every page of listRepoOps; Signature-Input, of the request’s label and Inner List; and Signature, the MAC. It also has Access-Control-Expose-Headers naming, in any letter case, the covered header, Signature-Input and Signature.

    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.

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.

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.

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 createSpace until its deleteSpace. Its published records reach the authority’s own repo through the commits above, as records like any other (in data, 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 reads getRecord, listRecords, getLatestCommit and listRepoOps on 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. importRepo there makes a commit but calls no on_commit.

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 cid must be that, and every commit’s data the LtHash digest of the records, computed by harness/spaces/lib/spec.mjs;
  • every rev is a TID later than the repo’s last commit’s;
  • listRecords is in descending order whatever reverse says;
  • listRepoOps from the start, replayed from the empty LtHash (each cid added, each prev removed), must give the commit’s data, every page must have the repo’s commit, and a cursor exactly when it is full; a repo never written must be RepoNotFound;
  • listSpaces must list the spaces the account wrote to, each with the repoRev and data of its repo’s commit;
  • a cursor with no / must be 400 InvalidCursor;
  • with a MAC asked for, the answer’s MAC must verify with spec.mjs from the harness’s own key share, its covered header name the record or commit the answer holds, its Signature-Input be the request’s label and Inner List, and the answer have the Vary and Access-Control-Expose-Headers above; with none asked for, it must have Vary and none of the MAC headers; a refused header must be 400 InvalidSpaceMac, whether or not the record or repo exists;
  • the account’s public repository’s getLatestCommit is 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.