# The PDS: accounts and their records An atproto PDS: accounts, each with its repository, read and written over XRPC, with one firehose for them all. These pages say what the server must do and how it is checked. The specs they rest on are in this directory, and nothing else is needed to build it. What these pages say the server does, it must do, whether they say it as a fact ("is `400 InvalidRequest`") or with "must": their requirements are the statements themselves, and they use none of BCP 14's upper-case key words (RFC 2119, RFC 8174). Every part of a page is a requirement but text marked *Note:*, which says why and requires nothing; a section that opens with *This section is informative.*, which requires nothing, as W3C's specifications mark theirs non-normative; and its "How it is checked", which says what the harness does. Where a page says the server may choose, every choice conforms, and the harness compares none. This page says what the server is and serves in general. Each area of its methods has a page of its own: | Page | Area | | --- | --- | | [`ACCOUNTS.md`](ACCOUNTS.md) | accounts and sessions: `createAccount`, `createSession`, `getSession`, `describeServer` | | [`SESSIONS.md`](SESSIONS.md) | sessions' tokens, refreshing and ending them, and app passwords: `refreshSession`, `deleteSession`, `createAppPassword`, `listAppPasswords`, `revokeAppPassword` | | [`EMAIL.md`](EMAIL.md) | the account's email: `requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`, `updateEmail`, `requestPasswordReset`, `resetPassword`, the sign-in code, and the mailer | | [`REPO.md`](REPO.md) | the repository's records: the `com.atproto.repo` methods | | [`VALIDATION.md`](VALIDATION.md) | records checked against the lexicons of their types: `validate`, `validationStatus`, record keys, and the duplicates `createRecord` replaces | | [`SYNC.md`](SYNC.md) | the repository whole: `getRepo`, `getLatestCommit` and the firehose | | [`FEDERATION.md`](FEDERATION.md) | what a relay reads: `listRepos`, `getRepoStatus`, `getBlocks`, the sync `getRecord`, and the `requestCrawl` the server sends | | [`IDENTITY.md`](IDENTITY.md) | handles: `resolveHandle`, `updateHandle`, `getRecommendedDidCredentials`, `/.well-known/atproto-did`, and resolving a handle outside the server's domains | | [`BLOBS.md`](BLOBS.md) | blobs: `uploadBlob`, `getBlob`, `listBlobs`, and blob refs in records | | [`SPACES.md`](SPACES.md) | spaces, permissioned data: who takes part, each account's KEM key, and the building blocks (the shared secret, MACs, HTTP Message Signatures, STAR) | | [`LIFECYCLE.md`](LIFECYCLE.md) | deactivating, taking down and deleting an account, and what each does to every method: `deactivateAccount`, `activateAccount`, `checkAccountStatus`, `requestAccountDelete`, `deleteAccount`, `updateSubjectStatus`, `getSubjectStatus` | | [`MIGRATION.md`](MIGRATION.md) | moving an account between servers: `createAccount` with a DID, `importRepo`, `listMissingBlobs`, `submitPlcOperation`, `requestPlcOperationSignature`, `signPlcOperation` | | [`PROXY.md`](PROXY.md) | what the Bluesky app needs beyond the repository: requests forwarded to the AppView and other services with service tokens, `getServiceAuth`, and preferences | | [`SPACES-REPO.md`](SPACES-REPO.md) | each account's space repos: the `com.atproto.space` record writes and reads, `listSpaces`, and MACs on request | | [`SPACES-CREDENTIALS.md`](SPACES-CREDENTIALS.md) | spaces' credentials: delegation tokens, authorizing a syncer and the space credential it gets, verifying credentials, client attestations, revocation: `getDelegationToken`, `authorizeSpaceSync`, `notifyCredentialsRevoked` | | [`SPACES-POLICIES.md`](SPACES-POLICIES.md) | spaces' policies and lifecycle: `createSpace`, `updateSpace`, `getSpace`, `deleteSpace`, `removeWriter`, `exportSpaceMeta`, `importSpaceMeta`, and the memberspace's `putMembers`, `removeMembers`, `listMembers` | | [`SPACES-EXPORT.md`](SPACES-EXPORT.md) | a space repo whole and its blobs, and migration: `getRepo` (STAR), `getBlob`, `listBlobs`, `importRepo`; every repo read with a space credential; takedown and deactivation of those reads | | [`SPACES-SYNC.md`](SPACES-SYNC.md) | spaces' write notifications and writer set: `notifyRepoUpdate` sent and taken, `listWriters`, syncers' registrations, and the space updates sent them | | [`DURABILITY.md`](DURABILITY.md) | what survives the server being killed and started again | | [`STORE.md`](STORE.md) | what history it keeps and lets go, the firehose's backfill window, the bounds on its data directory, its memory and its start at any number of accounts and amount of data, and starting on a previous version's data | | [`OAUTH.md`](OAUTH.md) | OAuth: the server as authorization server for its accounts, with loopback clients, PAR, its sign-in and consent pages, DPoP, and the token and revocation endpoints | | [`OAUTH-SCOPES.md`](OAUTH-SCOPES.md) | OAuth access tokens on every method that takes a token, and what each method needs of their scopes | | [`OAUTH-CLIENTS.md`](OAUTH-CLIENTS.md) | OAuth's web, native and confidential clients: client metadata documents, `private_key_jwt` client authentication, silent sign-in | | [`OAUTH-PAGES.md`](OAUTH-PAGES.md) | what the authorization pages show a person and what each control calls, built from `web/` and served from the binary | | [`OAUTH-PERMISSION-SETS.md`](OAUTH-PERMISSION-SETS.md) | OAuth's permission sets (`include:` scopes): resolving a set's lexicon and checking its proof, what a set grants, and how a token's scope holds it | | [`OAUTH-MCP.md`](OAUTH-MCP.md) | OAuth for MCP clients: a second issuer for the MCP endpoint, client ID metadata documents without DPoP, the authorization request without PAR, bearer tokens for `/mcp` alone, and the `401` that starts a sign-in | | [`OAUTH-ACCOUNT.md`](OAUTH-ACCOUNT.md) | the account's own OAuth sessions and devices, listed and ended with its password session: `/xrpc/_oauthSessions`, `_oauthRevokeSession`, `_oauthDevices` and `_oauthRevokeDevice` | | [`PASSKEYS.md`](PASSKEYS.md) | passkeys: signing in on the authorization page with one instead of the password, and adding, listing and removing them with the password session: `/xrpc/_passkeyList`, `_passkeyAdd`, `_passkeyRemove`, and the page `/oauth/passkey` | | [`LIMITS.md`](LIMITS.md) | what keeps it up on the internet: invite codes, rate limits, request caps, quotas, and what it holds open: `createInviteCode`, `createInviteCodes`, `getAccountInviteCodes` | | [`OPERATIONS.md`](OPERATIONS.md) | what it tells whoever runs it, and how fast it must be: its log, `/xrpc/_health`, its metrics and traces, the admin's reads of them, `/xrpc/_logs` and `/xrpc/_stats`, and its performance beside the reference | | [`COMMANDS.md`](COMMANDS.md) | every method as an MCP tool and a CLI command | ## What it serves `pds serve` runs the server (`COMMANDS.md`), configured by its environment: | Variable | Is | Default | | --- | --- | --- | | `PDS_PORT` | the port to listen on | required | | `PDS_BIND_ADDRESS` | the address to listen on: an IPv4 or IPv6 address, as `0.0.0.0` for every IPv4 address of the machine, or `::` for every address an IPv6 socket is given, which on Linux and macOS is every IPv4 address too | `127.0.0.1` | | `PDS_DATA_DIR` | a directory for its data: empty the first time, and the server's own after | required | and the variables `ACCOUNTS.md`, `IDENTITY.md`, `FEDERATION.md`, `LIMITS.md`, `EMAIL.md`, `PROXY.md`, `BLOBS.md`, `STORE.md`, `OAUTH-PERMISSION-SETS.md` and `OPERATIONS.md` list, and, for development only, the ones `OAUTH-CLIENTS.md` and `IDENTITY.md` list. It starts with no accounts. By default it listens on the loopback alone, so that only a reverse proxy on the same machine reaches it; `PDS_BIND_ADDRESS` puts it where a proxy on another machine, or a container's network, reaches it. It listens on that address and no other: bound to `::1`, it does not answer on `127.0.0.1`. `/metrics` stays on `127.0.0.1` whatever this says (`OPERATIONS.md`). An empty `PDS_BIND_ADDRESS` is as if unset. A value that is not an IPv4 or IPv6 address as written, such as `localhost`, a host name, `[::1]` or an address with a port, makes `pds serve` exit 1 before it writes anything to standard output, with why on standard error, as `LIMITS.md` says of its variables. An address it cannot listen on, as one no interface of the machine has, makes it exit 1 too, with why on standard error. It serves the methods whose lexicons are in `lexicons/`, as they define them, over XRPC as `atproto/xrpc.md` describes, and each one also as an MCP tool and a CLI command, as `COMMANDS.md` says: - `com.atproto.server.describeServer`, `createAccount`, `createSession`, `getSession` (`ACCOUNTS.md`) - `com.atproto.server.refreshSession`, `deleteSession`, `createAppPassword`, `listAppPasswords`, `revokeAppPassword` (`SESSIONS.md`) - `com.atproto.server.requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`, `updateEmail`, `requestPasswordReset`, `resetPassword` (`EMAIL.md`) - `com.atproto.repo.createRecord`, `putRecord`, `deleteRecord`, `applyWrites`, `getRecord`, `listRecords`, `describeRepo` (`REPO.md`) - `com.atproto.sync.getRepo`, `getLatestCommit`, `subscribeRepos` (`SYNC.md`) - `com.atproto.sync.listRepos`, `getRepoStatus`, `getBlocks`, `getRecord` (`FEDERATION.md`) - `com.atproto.identity.resolveHandle`, `updateHandle`, `getRecommendedDidCredentials`, and `GET /.well-known/atproto-did` (`IDENTITY.md`) - `com.atproto.repo.uploadBlob`, `com.atproto.sync.getBlob`, `listBlobs` (`BLOBS.md`) - `com.atproto.space.createRecord`, `putRecord`, `deleteRecord`, `applyWrites`, `clearRecords`, `getRecord`, `listRecords`, `getLatestCommit`, `listRepoOps`, `listSpaces` (`SPACES-REPO.md`) - `com.atproto.space.getDelegationToken`, `authorizeSpaceSync`, `notifyCredentialsRevoked` (`SPACES-CREDENTIALS.md`) - `com.atproto.space.createSpace`, `updateSpace`, `getSpace`, `deleteSpace`, `removeWriter`, `exportSpaceMeta`, `importSpaceMeta`, and `com.atproto.memberspace.putMembers`, `removeMembers`, `listMembers` (`SPACES-POLICIES.md`) - `com.atproto.space.getRepo`, `getBlob`, `listBlobs`, `importRepo` (`SPACES-EXPORT.md`) - `com.atproto.space.notifyRepoUpdate`, `listWriters` (`SPACES-SYNC.md`) - `com.atproto.server.createInviteCode`, `createInviteCodes`, `getAccountInviteCodes` (`LIMITS.md`) - `com.atproto.server.deactivateAccount`, `activateAccount`, `checkAccountStatus`, `requestAccountDelete`, `deleteAccount`, and `com.atproto.admin.updateSubjectStatus`, `getSubjectStatus` (`LIFECYCLE.md`) - `com.atproto.repo.importRepo`, `listMissingBlobs`, and `com.atproto.identity.submitPlcOperation`, `requestPlcOperationSignature`, `signPlcOperation` (`MIGRATION.md`) - `com.atproto.server.getServiceAuth`, `app.bsky.actor.getPreferences`, `putPreferences`, `getProfile`, `getProfiles`, `app.bsky.feed.getTimeline`, `getAuthorFeed`, `getActorLikes`, `getPostThread`, `getFeed`, `app.bsky.notification.registerPush`, `unregisterPush`, and every method it does not serve, forwarded (`PROXY.md`) and, besides XRPC, OAuth's metadata, its `/oauth/*` endpoints and pages (`OAUTH.md`), and OAuth access tokens on every method that takes a token (`OAUTH-SCOPES.md`). Besides its methods, it serves `GET /`, `GET /xrpc/_health`, the admin's `GET /xrpc/_logs` and `GET /xrpc/_stats`, the account's own OAuth routes (`OAUTH-ACCOUNT.md`) and its passkeys' (`PASSKEYS.md`), and writes its log, keeps it, exports its traces and serves its metrics, as `OPERATIONS.md` says. `repo` parameters name an account by its handle or DID; DIDs and handles are as `atproto/did.md` and `atproto/handle.md` define them. A session's `accessJwt` is a bearer token for its account, a JWT as `SESSIONS.md` says. A bearer token the server did not give out, sent to a repository write or to `getSession`, is `400 InvalidToken`, as the reference answers one. ## Browsers An app in a browser, as bsky.app, calls the server from its own origin, so every path but OAuth's (`/.well-known/oauth-*`, `/oauth/*` and `/@atproto/oauth-provider/*`, whose cross-origin answers `OAUTH.md` and `OAUTH-MCP.md` give) answers as the reference does (CORS, the Fetch standard): - Every answer, of any status, carries `Access-Control-Allow-Origin: *`, whatever `Origin` the request has, or none. - A request of method `OPTIONS` is a preflight, whatever its path, served or not, and whatever its headers: `204` with no body, and `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE`, `Access-Control-Allow-Headers` the request's `Access-Control-Request-Headers` as sent (none when it sent none), `Access-Control-Max-Age: 86400` and `Vary: Access-Control-Request-Headers`. It reaches no method: it costs no rate limit, carries no `RateLimit-*` headers, and is not forwarded. `harness/checks/cors.mjs` holds the server to the reference: `GET`s and `POST`s answered `200`, `4xx` and `404`, with an `Origin` and without; and preflights on methods served, a method not served, `_health`, a path that is no NSID and a path outside `/xrpc/`, with and without `Access-Control-Request-Method` and `Access-Control-Request-Headers`. It compares the status and every `Access-Control-*` header, and that a preflight's `Vary` names `Access-Control-Request-Headers` and its body is empty. ## What the reference does that the specs leave open The lexicons and prose specs do not say these, and the reference PDS does them, so the server does too. Each area's page lists those of its methods. - A method's parameters and input are checked against its lexicon: one that is missing, of the wrong type, or of the wrong format (a DID, handle, NSID, record key, CID or TID that does not parse) is `400 InvalidRequest`, before anything else could refuse the call. Only a write's token is checked earlier. So a malformed `repo` is `InvalidRequest`, not `RepoNotFound` or `AccountNotFound`, and a malformed `swapCommit` is `InvalidRequest`, not `InvalidSwap`. - A write checks, in this order, its token, its input, its `repo`, and its record's `$type`. With no token it is `401 AuthMissing`, and with a token the server did not give out `400 InvalidToken`, however wrong its input. Input that is wrong, including a record outside the data model, is `400 InvalidRequest`, whatever its `repo`. Then a `repo` no account here has is `403 AccountNotFound`, and one another account here has is `401 AuthenticationRequired` (`ACCOUNTS.md`), and only then a `$type` other than the collection `400 InvalidRequest`, and then the record against its type's lexicon (`VALIDATION.md`). `getSession` with no token is `401 AuthMissing` too. - A method called with the other HTTP method, a query by `POST` or a procedure by `GET`, is `400 InvalidRequest`. *Note:* some look like accidents of the reference (the 500s); matching them is a choice, made here so that the harness can compare everything else. ## How it is checked `harness/compare.mjs` starts the server and the reference PDS, sends both the same random requests, and stops at the first answer that differs, saying what was asked and what each answered: ```sh cd harness && npm ci # once node compare.mjs --steps 400 --seed 1 -- ``` Both run without rate limits and with invite codes not required; `--limits` and `--invites` are runs of their own with each, which `LIMITS.md` says, and `--store` one with a short backfill window, which `STORE.md` says. Every run of `compare.mjs`, of any kind, ends by holding the server's log, health, metrics and traces to `OPERATIONS.md`. The answers must be equal after these are taken out, which differ between any two servers: each account's DID (the harness names an account's DID on both sides alike, by the order the accounts were made), each account's signing key, the server's URL, the `cid` and `rev` of each commit, tokens, cursors (each side is paged with its own), and error messages (the `error` name and HTTP status must match). A `didDoc` must equal the one the PLC directory serves for the DID. Both servers register their accounts' DIDs with the same PLC directory, the reference's own, and the harness reads each DID's operations from it: the server's must be what `ACCOUNTS.md` says. The server is held to the spaces alpha as well, which the reference PDS here does not serve: each account's KEM key (`SPACES.md`) and `describeServer`'s `spacesAlpha`. Where the `latest` reference cannot say, these runs hold the server to the spec instead, and take out of the comparison only what they hold that way: - each genesis operation's `verificationMethods.atproto_kem` must be a P-256 `did:key` of a point on the curve, and is then taken out of the operation the harness holds to `ACCOUNTS.md`; - `getRecommendedDidCredentials`' `verificationMethods.atproto_kem` must be that key, and is then taken out before the sides are compared; - a `didDoc` must still equal the document the directory serves, whole; only when the two sides' documents are compared with each other are the `#atproto_kem` verification method and the `@context` entry the directory adds for it (`SPACES.md`) taken out of both; - `describeServer`'s `spacesAlpha` must be `true` on the server, and is not compared. The reference is held to none of these. The spaces run (`harness/spaces/compare.mjs`, `SPACES.md`) compares all of them with the spaces alpha. Every few steps the harness also reads each account's whole repository from `getRepo`. The reference implementation's own library must verify it, signature, MST and every record, against the signing key the account's DID document names; and its MST root, the commit's `data`, must equal the reference's, which holds only if the records, their encoding and the tree are all the same. `getLatestCommit` must name that commit. The same checks, their core, run against other implementations of a PDS in a compatibility run, which [`COMPAT.md`](COMPAT.md) says: what it runs, and exactly what it lets an implementation other than Monolith have. Each check names the section it holds the server to, as `(spec/LIFECYCLE.md, "deactivateAccount")`: a page and one or more of its headings, each as written without its backticks, or a paragraph's bold label, as "When" of `LIMITS.md`'s rate limits. A page's "How it is checked", and a section that opens with *This section is informative.*, are no sections a check holds the server to, nor is anything under them. No page has one heading twice. `harness/spec-coverage.mjs`, among the `code` gates, fails on a heading twice in a page, on a citation of a heading or label its page does not have, and on a section no check cites. The few sections no check holds the server to yet it lists, each with what a check would need; one leaves the list once a check cites it, and the gate fails until it does. It prints how many sections of each page are cited. The `citations` workflow runs it on every pull that changes a page or the harness. ## Test vectors *This section is informative.* `interop/` has atproto's test vectors: the MST's key heights and examples, the data model's valid and invalid values, and the signature fixtures; and the spaces building blocks' vectors and STAR's fixtures (`SPACES.md`).