chadtmiller.com/monolith
An atproto PDS
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 and sessions: createAccount, createSession, getSession, describeServer |
SESSIONS.md | sessions' tokens, refreshing and ending them, and app passwords: refreshSession, deleteSession, createAppPassword, listAppPasswords, revokeAppPassword |
EMAIL.md | the account's email: requestEmailConfirmation, confirmEmail, requestEmailUpdate, updateEmail, requestPasswordReset, resetPassword, the sign-in code, and the mailer |
REPO.md | the repository's records: the com.atproto.repo methods |
VALIDATION.md | records checked against the lexicons of their types: validate, validationStatus, record keys, and the duplicates createRecord replaces |
SYNC.md | the repository whole: getRepo, getLatestCommit and the firehose |
FEDERATION.md | what a relay reads: listRepos, getRepoStatus, getBlocks, the sync getRecord, and the requestCrawl the server sends |
IDENTITY.md | handles: resolveHandle, updateHandle, getRecommendedDidCredentials, /.well-known/atproto-did, and resolving a handle outside the server's domains |
BLOBS.md | blobs: uploadBlob, getBlob, listBlobs, and blob refs in records |
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 | deactivating, taking down and deleting an account, and what each does to every method: deactivateAccount, activateAccount, checkAccountStatus, requestAccountDelete, deleteAccount, updateSubjectStatus, getSubjectStatus |
MIGRATION.md | moving an account between servers: createAccount with a DID, importRepo, listMissingBlobs, submitPlcOperation, requestPlcOperationSignature, signPlcOperation |
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 | each account's space repos: the com.atproto.space record writes and reads, listSpaces, and MACs on request |
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 and lifecycle: createSpace, updateSpace, getSpace, deleteSpace, removeWriter, exportSpaceMeta, importSpaceMeta, and the memberspace's putMembers, removeMembers, listMembers |
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' write notifications and writer set: notifyRepoUpdate sent and taken, listWriters, syncers' registrations, and the space updates sent them |
DURABILITY.md | what survives the server being killed and started again |
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: 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 access tokens on every method that takes a token, and what each method needs of their scopes |
OAUTH-CLIENTS.md | OAuth's web, native and confidential clients: client metadata documents, private_key_jwt client authentication, silent sign-in |
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'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 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 | the account's own OAuth sessions and devices, listed and ended with its password session: /xrpc/_oauthSessions, _oauthRevokeSession, _oauthDevices and _oauthRevokeDevice |
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 | what keeps it up on the internet: invite codes, rate limits, request caps, quotas, and what it holds open: createInviteCode, createInviteCodes, getAccountInviteCodes |
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 | 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, andGET /.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, andcom.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, andcom.atproto.admin.updateSubjectStatus,getSubjectStatus(LIFECYCLE.md)com.atproto.repo.importRepo,listMissingBlobs, andcom.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: *, whateverOriginthe request has, or none. - A request of method
OPTIONSis a preflight, whatever its path, served or not, and whatever its headers:204with no body, andAccess-Control-Allow-Origin: *,Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE,Access-Control-Allow-Headersthe request'sAccess-Control-Request-Headersas sent (none when it sent none),Access-Control-Max-Age: 86400andVary: Access-Control-Request-Headers. It reaches no method: it costs no rate limit, carries noRateLimit-*headers, and is not forwarded.
harness/checks/cors.mjs holds the server to the reference: GETs and
POSTs 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 malformedrepoisInvalidRequest, notRepoNotFoundorAccountNotFound, and a malformedswapCommitisInvalidRequest, notInvalidSwap. - A write checks, in this order, its token, its input, its
repo, and its record's$type. With no token it is401 AuthMissing, and with a token the server did not give out400 InvalidToken, however wrong its input. Input that is wrong, including a record outside the data model, is400 InvalidRequest, whatever itsrepo. Then arepono account here has is403 AccountNotFound, and one another account here has is401 AuthenticationRequired(ACCOUNTS.md), and only then a$typeother than the collection400 InvalidRequest, and then the record against its type's lexicon (VALIDATION.md).getSessionwith no token is401 AuthMissingtoo. - A method called with the other HTTP method, a query by
POSTor a procedure byGET, is400 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:
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_kemmust be a P-256did:keyof a point on the curve, and is then taken out of the operation the harness holds toACCOUNTS.md; getRecommendedDidCredentials'verificationMethods.atproto_kemmust be that key, and is then taken out before the sides are compared;- a
didDocmust still equal the document the directory serves, whole; only when the two sides' documents are compared with each other are the#atproto_kemverification method and the@contextentry the directory adds for it (SPACES.md) taken out of both; describeServer'sspacesAlphamust betrueon 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 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).