chadtmiller.com/monolith
An atproto PDS
0
0
# 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 -- <command that starts the server>
```
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`).