# 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.md`](SPACES.md); what every method shares, and how the server is checked, is in [`PDS.md`](PDS.md). 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 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.md` 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 (`REPO.md`): 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.md` 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. ## Who may call Each method takes the account's access token, from a session made with its password or an app password (`SESSIONS.md`), 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-SCOPES.md`, "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. ## Writes ### The order of the checks A write checks, in this order, and answers the first that fails: 1. its token (above), and then its account's state (`LIFECYCLE.md`, 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.md`), `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. ### Records As for a public record (`REPO.md`), 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.md`) 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. ### 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.md`, the proposal). ### Each write - **`createRecord`** `{space, repo, collection, rkey?, record, validate?}` creates a record and answers `{uri, cid, validationStatus?}`. Without `rkey` the key is a TID (`atproto/tid.md`), 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.md`, 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). ## Reads ### Each read - **`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": }`. 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": }`, 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-SYNC.md`, "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. ### 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-EXPORT.md`) takes any cursor. ### MACs on request `getRecord`, `getLatestCommit` and `listRepoOps` authenticate what they answer when asked, with the request header `Accept-Signature`, read as `SPACES.md` ("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-EXPORT.md`). 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.md` 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.md` ("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. ## Durability The space repos are the server's state as the public repository is (`DURABILITY.md`): 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 Each method is an MCP tool and a CLI command, as `COMMANDS.md` 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 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-SYNC.md`'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.md`, "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-EXPORT.md` ("Who may read") says the order of the checks and that a MAC is then required. - **Full state** (`getRepo`, `SPACES-EXPORT.md`) 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`. ## How it is checked The spaces run (`SPACES.md`) 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 `PDS.md` says, with each side's account DIDs named alike, record keys the server made (TIDs) named by their order, `rev`s, `repoRev`s and `spaceRev`s 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-ref`s, 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.md`), 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-SCOPES.md`, "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.md`): 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.