chadtmiller.com/monolith
An atproto PDS
Account lifecycle
An account is active from when it is made. Its owner may deactivate it and
activate it again; the admin may take it down, and its records and blobs
one by one; and its owner may delete it, with its password and a token
mailed to its email. This page says how, and
what each state does to every other method. What every method shares, and
how the server is checked, is in PDS.md; accounts and their
sessions are as ACCOUNTS.md and
SESSIONS.md say; the mailer and email tokens are
EMAIL.md's; the admin's auth is LIMITS.md's.
The methods: com.atproto.server.deactivateAccount, activateAccount,
checkAccountStatus, requestAccountDelete and deleteAccount; and
com.atproto.admin.updateSubjectStatus and getSubjectStatus.
Note: an owner deactivates an account when moving it to another server.
States
An account is in one of these states. Its status is the word the methods below answer for it:
| State | Status | Made by | Ended by |
|---|---|---|---|
| active | none | createAccount | any of the others |
| deactivated | deactivated | deactivateAccount, or the admin | activateAccount, or the admin |
| taken down | takendown | the admin | the admin |
| deleted | deleted | deleteAccount | nothing |
Deactivated and taken down are two facts, each set and cleared on its own:
an account may be both, and its status is then takendown. Lifting a
takedown leaves it deactivated if it was. A deleted account is gone: the
server keeps nothing of it but its firehose event of deletion, and its DID
is no account's, as one never made.
An account that is not active is still the account's for the checks of
createAccount and updateHandle: its handle and its email are taken, as
an active one's are, until it is deleted. Then they are free: a new account
may be made with them, or an account change its handle to that one.
Nothing in the server ends a state by time, and no method answers
deleteAfter: whether the server keeps it, it may choose.
deactivateAccount
deactivateAccount {deleteAfter?} deactivates the token's account. It
checks, in this order:
- The token: none is
401 AuthMissing. It takes an access token of a session made with the account's password (com.atproto.access) or one made bycreateSessionwithallowTakendown(com.atproto.takendown, below); an app password's session, privileged or not, is400 InvalidToken, as is any other token the server would refuse (SESSIONS.md). - The input, a JSON body: none, or a
deleteAfterthat is not a datetime (atproto/lexicon.md), is400 InvalidRequest.{}is taken. - A deleted account, whose token still works until its
exp(SESSIONS.md), is400 InvalidRequest.
Otherwise the account is deactivated, taken down or not, and already
deactivated or not, and the answer is 200 with an empty body. Each call
puts #account on the firehose, with the status the account now has
(below). The account's sessions and app passwords stay, and its OAuth
sessions too, unless the token is an OAuth one: then its OAuth sessions
end and its app passwords are deleted ("OAuth sessions", below).
activateAccount
activateAccount has no input. It checks, in this order:
- The token: none is
401 AuthMissing; anything but an access token of a session made with the account's password is400 InvalidToken: an app password's, and acom.atproto.takendownone's, too. - A request body is
400 InvalidRequest. - The account's DID document must name this server, as
checkAccountStatus'svalidDidsays (below), read from the PLC directory now: data that does not name this server, or a DID the directory does not know, is400 InvalidRequest; a directory that cannot be read (no answer, or an error),502 UpstreamFailure. Its rotation keys and its endpoint are looked at before its signing key, so a deleted account, whose key is gone, is400 InvalidRequestwhen the rest does not name this server, and500 InternalServerErrorwhen it does, as the reference answers it. Adid:webaccount's document is read from its host instead, and names this server by its endpoint and signing key alone, asMIGRATION.md("Adid:webaccount") says, with the errors it gives. - A taken-down account is
400 AccountNotFound.
Otherwise the account is no longer deactivated, whether it was or not, and
the answer is 200 with an empty body. Each call puts on the firehose, in
this order: #account with active: true, #identity with the account's
handle, and #sync of its latest commit, as a new account's #sync is
(SYNC.md).
checkAccountStatus
checkAccountStatus takes any access token of the account, an app
password's too, but not a com.atproto.takendown one (400 InvalidToken);
none is 401 AuthMissing. It answers, in every state but deleted:
| Field | Is |
|---|---|
activated | false if the account is deactivated or taken down, true otherwise |
validDid | whether the PLC directory's current data for the DID names this server: its services.atproto_pds.endpoint is PDS_PUBLIC_URL, its verificationMethods.atproto is the account's signing key, and its rotationKeys include the server's rotation key; false when the directory cannot be read, the answer 200 all the same. For a did:web account, whether its document names this server as MIGRATION.md ("A did:web account") says, false when it cannot be read |
repoCommit | the CID of the repository's latest commit |
repoRev | that commit's rev |
repoBlocks | how many distinct blocks the latest commit and its tree are: the commit, every MST node, and every record, each CID counted once |
indexedRecords | how many records the repository has |
privateStateValues | 0 |
expectedBlobs | how many distinct blobs the account's records reference |
importedBlobs | how many blobs the account holds (BLOBS.md), referenced or not |
For a deleted account it is 400 NotFound.
requestAccountDelete
requestAccountDelete has no input. It checks, in this order:
- The token: none is
401 AuthMissing; anything but an access token of a session made with the account's password is400 InvalidToken. - A taken-down account is
401 AccountTakedown; a deleted one403 AccountNotFound. - A request body is
400 InvalidRequest. - An account without an email (made without a password,
ACCOUNTS.md) is400 InvalidRequest.
Otherwise the server makes a token of purpose delete_account, as
EMAIL.md says of every email token, which replaces any earlier one of the
account's, mails it to the account's email, kind deleteAccount, and
answers 200 with an empty body. A deactivated account may ask.
deleteAccount
deleteAccount {did, password, token} takes no token: an
Authorization header, of any kind, is ignored. It checks, in this order:
- The input against the lexicon: a
didthat is not a DID, or any of the three missing, is400 InvalidRequest. Fields it does not name are ignored. - A
passwordlonger than 512 UTF-16 code units, counted asACCOUNTS.mdcounts a password, is401 AuthenticationRequired. - A
didno account here has, including one deleted, is400 InvalidRequest. - A
passwordthat is not the account's password is401 AuthenticationRequired. An app password is not the account's password, and an account made without a password has none to give. - A
tokenthat is not the account'sdelete_accounttoken is400 InvalidToken; one past its 15 minutes,400 ExpiredToken. It is matched asEMAIL.mdmatches tokens.
Otherwise the account is deleted, whatever its state, taken down too, and
the answer is 200 with an empty body. A token the account was mailed
before it was taken down still deletes it.
Deleting an account removes its repository, records, blobs, sessions,
tokens, app passwords and status, and frees its handle and email; puts
#account with active: false, status: "deleted" on the firehose; and
drops every earlier event of the account from what the firehose serves
(below). The server does not change the DID's document in the PLC
directory: it still names this server, which no longer has it.
The admin
updateSubjectStatus and getSubjectStatus take the admin's auth,
Authorization: Basic with the user admin and the password
PDS_ADMIN_PASSWORD, as LIMITS.md says, the scheme matched without
regard to case. The auth is checked before the input. A request without it
is 401, with these names:
- no
Authorization, another user or password, aBasicvalue that does not decode or has no:, aDPoPheader, and any request whilePDS_ADMIN_PASSWORDis unset or empty (LIMITS.md):401 AuthenticationRequired; - a
Bearertoken: the reference takes it for a moderation service's JWT, which the server does not take. A JWT whose headertypisat+jwtorrefresh+jwt, as each of the server's own tokens is, is401 BadJwtType; any other value401 BadJwt; - a header that is not two words:
400 InvalidToken, asSESSIONS.mdsays.
A subject is an account (com.atproto.admin.defs#repoRef, {did}), a
record (com.atproto.repo.strongRef, {uri, cid}), or a blob
(com.atproto.admin.defs#repoBlobRef, {did, cid}), each with its
$type. A status attribute is {applied, ref?}.
updateSubjectStatus
updateSubjectStatus {subject, takedown?, deactivated?}, after the auth
and the lexicon (a subject without $type, a did that is not a DID, a
takedown without applied, all 400 InvalidRequest):
-
takedown.applied: truewithdeactivated.applied: falseis400 InvalidRequest. -
With
takedown, a subject of a$typeother than the three is400 InvalidRequest, whateverappliedis and whateverdeactivatedis. Withouttakedown, one is taken and changes nothing:deactivated, either way, or neither attribute, is200, with nothing on the firehose. -
takedownis applied first:- An account.
applied: truetakes it down, withrefas the takedown's reference, or the time, as a datetime, if none is given; again, it replaces the reference.applied: falselifts it, if it was down. Either one ends every session of the account, as the reference does even for a lifting of an account that was not down: each refresh token is then401 AccountTakedownwhile it is down, and400 ExpiredTokenafter, or at once if it is not down (SESSIONS.md); access tokens work until theirexp, where the account's state lets them (below). Tokens mailed to it stay. Either way,#accountgoes on the firehose, with the status the account now has. Of a DID no account here has, deleted or never made, it changes nothing, and still puts#accounton the firehose for that DID, withactive: false, status: "deleted". - A record, by its
uri:applied: truetakes down the record its repository now has at thatcollection/rkey, whatevercidsays;applied: falselifts that. A key the repository does not hold is taken down by nothing, and200all the same. The takedown stays on the key while the record is updated (putRecord,applyWrites), and ends when it is deleted: a record made there again is not taken down. Auriwhose authority is a handle, or a DID no account here has, is500 InternalServerError. Auriof an account here that names no record, its DID alone (at://<did>) or a collection and no key (at://<did>/<collection>), takes down nothing, and is200. - A blob of the account
didnames:applied: truetakes it down, withrefor the time, as for an account;applied: falselifts it. A blob the account does not hold is taken down by nothing, and200; one it stops holding (BLOBS.md) loses its takedown with it. Adidno account here has is500 InternalServerError.
- An account.
-
Then
deactivated, of an account:applied: truedeactivates it, andapplied: falseactivates it, each as its method above does, with the same firehose events, but for any account and with no token: a taken-down one may be deactivated, and is still refused activation (400 AccountNotFound); its DID document is read asactivateAccount's step 3 reads it, with the same errors:400 InvalidRequestfor one that does not name this server,502 UpstreamFailurewhen the directory cannot be read. Of a DID no account here has,applied: trueis400 InvalidRequest;applied: falsereads the directory too:400 InvalidRequestfor a DID it does not know or whose data does not name this server,502 UpstreamFailurewhen it cannot be read, and500 InternalServerErrorfor one whose data names this server, as a deleted account's. Neither puts anything on the firehose.deactivatedof a record or a blob, whatever itsuriordid, changes nothing.The two are applied one after the other, not as one: when
deactivatedis refused, whattakedowndid stays, with its#accounton the firehose, and the answer isdeactivated's error. So a takedown lifted withdeactivated.applied: falsefrom an account whose DID document does not name this server is lifted, with#accountof the status it now has, and the answer is400 InvalidRequest. -
With neither
takedownnordeactivated, an account subject puts#accounton the firehose with its status, and changes nothing.
It answers 200 with {subject, takedown}: the input's subject and
takedown as given, takedown left out if it was.
getSubjectStatus
getSubjectStatus takes did, uri and blob (a CID), and answers the
first of these that applies:
blob: needsdid, else400 InvalidRequest. Adidno account here has is400 NotFound. A blob the account holds answers{subject: {$type: "com.atproto.admin.defs#repoBlobRef", did, cid}, takedown}; one it does not is400 NotFound.uri: one whose authority is a handle is500 InternalServerError, whether or not an account has that handle. A DID no account here has is400 NotFound. A record the repository holds at that key answers{subject: {$type: "com.atproto.repo.strongRef", uri, cid}, takedown},cidthe record's as it is now; a key it does not hold, and auriwith no key (at://<did>,at://<did>/<collection>), is400 NotFound.did: an account here answers{subject: {$type: "com.atproto.admin.defs#repoRef", did}, takedown, deactivated}; a DID no account here has is400 NotFound.- None of the three:
400 InvalidRequest.
takedown is {applied: true, ref} while the subject is down, and
{applied: false} otherwise, with no ref. deactivated is {applied}.
Answering changes nothing.
Records and blobs taken down
A record taken down is not served by com.atproto.repo.getRecord, which
answers it 400 RecordNotFound, to the account's own token too, nor listed
by listRecords. It is still in the repository: getRepo, getBlocks,
the sync getRecord, describeRepo's collections and the firehose are
as they were, and it may be updated or deleted.
A blob taken down is answered by getBlob as one the account does not hold
(400 InvalidRequest), to the account and the admin too. listBlobs still
lists it. A record referencing it is 400 BlobNotFound, and uploading its
bytes again 400 InvalidRequest.
Neither puts anything on the firehose.
What each state does to every method
An access token works until its exp, whatever happens to its account
(SESSIONS.md); each method then answers by the account's state, as here.
"Its token" is an access token of one of the account's sessions, made with
its password or an app password, unless it says otherwise.
The space methods are in none of the tables below: each space page says
what an account's state does to its methods, with the state this page
keeps ("Takedown and deactivation" of SPACES-POLICIES.md and
SPACES-EXPORT.md, "The order of the checks" of SPACES-REPO.md,
getDelegationToken and authorizeSpaceSync in SPACES-CREDENTIALS.md,
and SPACES-SYNC.md): the space repo's writes by a deactivated or
taken-down account (401 AccountDeactivated, 401 AccountTakedown, with
an access token made before too), its getDelegationToken (the same),
authorizeSpaceSync of a space whose authority it is (400 RepoDeactivated, 400 RepoTakendown), notifyRepoUpdate, importRepo, and
the space getRepo, getBlob and listBlobs among them.
Its repository, read by anyone
| Method | Deactivated | Taken down | Deleted |
|---|---|---|---|
describeRepo, by DID or handle | 400 RepoDeactivated | 400 RepoTakendown | 400 RepoNotFound |
com.atproto.repo.getRecord | as of a repository the server does not hold (PROXY.md) | the same | the same |
listRecords | 400 InvalidRequest | 400 InvalidRequest | 400 InvalidRequest |
getLatestCommit, getRepo, getBlocks, the sync getRecord, getBlob, listBlobs | 400 RepoDeactivated | 400 RepoTakendown | 400 RepoNotFound |
getRepoStatus | {did, active: false, status: "deactivated"} | {did, active: false, status: "takendown"} | 400 RepoNotFound |
listRepos | listed as {did, head, rev, active: false, status: "deactivated"} | the same, status: "takendown" | not listed |
describeRepo answers so to every caller, the account and the admin too.
Taken down and deactivated at once is answered as taken down.
The six sync reads of the fourth row take an optional Authorization:
- With none, they answer as above.
- With the account's own token, a
com.atproto.takendownone too forgetRepo,getBlobandlistBlobs, or with the admin'sBasic, they answer as if the account were active: the account and the admin read its repository and blobs, deactivated or taken down. Deleted, it is400 RepoNotFoundall the same. - Another account's token is the same as none. A token the server would
refuse, a refresh token, or a
com.atproto.takendowntoken forgetLatestCommit,getBlocksor the syncgetRecord, is400 InvalidToken; one past itsexp,400 ExpiredToken; aBasicheader that is not the admin's,401 AuthenticationRequired. These hold for an active account too, and for a DID no account here has, deleted or never made: theAuthorizationis checked before the DID, so a bad one is answered with its own error, not400 RepoNotFound, which a good one, of any account or the admin's, or none, is. - A
DPoPheader is an OAuth access token, checked with its proof asOAUTH-SCOPES.mdsays, before the DID too: one the server did not give out as an OAuth token, a session'saccessJwtor a forged one, is401 invalid_token, whatever the account's state or none. One that passes is its account's own token, as above: an OAuth session of a deactivated account reads its repository and blobs as its password session does.
describeRepo, listRepos, getRepoStatus and resolveHandle ignore any
Authorization.
Its handle
resolveHandle of the handle of an account that is not active is 400 HandleNotFound, and /.well-known/atproto-did with it as the host is
404, as for a handle no account has (IDENTITY.md). It is still taken
(above), until the account is deleted.
Its own calls
With its token, the password session's unless the row says otherwise:
| Method | Deactivated | Taken down | Deleted |
|---|---|---|---|
getSession | 200, active: false, status: "deactivated" | 400 InvalidRequest | 400 InvalidRequest |
refreshSession, with its refresh token | 200, the same | 401 AccountTakedown | 400 InvalidRequest |
deleteSession, with its refresh token | 200 | 200 | 200 |
createSession | 200, the same | below | 401 AuthenticationRequired |
createAppPassword | 200 | 401 AccountTakedown | 403 AccountNotFound |
listAppPasswords | 200 | 200 | 200 {passwords: []} |
revokeAppPassword | 200 | 200 | 200 |
_oauthSessions, _oauthDevices (OAUTH-ACCOUNT.md) | 200 | 200 | 200, none listed |
_oauthRevokeSession, _oauthRevokeDevice (OAUTH-ACCOUNT.md) | 200 | 200 | 200 |
_passkeyList (PASSKEYS.md) | 200 | 200 | 200, none listed |
_passkeyAdd (PASSKEYS.md) | 200 | 401 AccountTakedown | 403 AccountNotFound |
_passkeyRemove (PASSKEYS.md) | 200 | 200 | 200 |
createRecord, putRecord, deleteRecord, applyWrites | 401 AccountDeactivated | 401 AccountTakedown | 403 AccountNotFound |
uploadBlob | 200 | 401 AccountTakedown | 403 AccountNotFound |
updateHandle | 200, as for an active account | 401 AccountTakedown | 403 AccountNotFound |
getRecommendedDidCredentials | 200 | 200, without alsoKnownAs | 500 InternalServerError |
checkAccountStatus | 200, activated: false | 200, activated: false | 400 NotFound |
deactivateAccount | 200 | 200 | 400 InvalidRequest |
activateAccount | 200 | 400 AccountNotFound | 500 InternalServerError |
requestAccountDelete | 200 | 401 AccountTakedown | 403 AccountNotFound |
getServiceAuth (PROXY.md) | 200, as for an active account | 401 AccountTakedown | 500 InternalServerError |
importRepo (MIGRATION.md) | 200 | 401 AccountTakedown | 403 AccountNotFound |
listMissingBlobs (MIGRATION.md) | 200 | 200 | 400 NotFound |
submitPlcOperation (MIGRATION.md) | as for an active account | as for an active account | 500 InternalServerError, once its operation's form, rotation key and service are checked |
requestPlcOperationSignature (MIGRATION.md) | 200 | 200 | 400 InvalidRequest |
signPlcOperation (MIGRATION.md) | as for an active account | as for an active account | 400 InvalidToken: it has no token |
a call forwarded to another service (PROXY.md) | forwarded as for an active account | 401 AccountTakedown, sent nowhere | 500 InternalServerError, sent nowhere |
requestEmailConfirmation, confirmEmail, requestEmailUpdate, updateEmail (EMAIL.md) | as for an active account | 401 AccountTakedown | 403 AccountNotFound |
getAccountInviteCodes (LIMITS.md) | 400 NotFound | 401 AccountTakedown | 403 AccountNotFound |
getPreferences (PROXY.md) | 200, as for an active account | 200, as for an active account | 400 NotFound |
putPreferences (PROXY.md) | 200, as for an active account | 401 AccountTakedown | 403 AccountNotFound |
registerPush, unregisterPush (PROXY.md) | sent on as for an active account | 401 AccountTakedown, sent nowhere | 500 InternalServerError, sent nowhere |
getSession, refreshSession and createSession answer active and
status as getRepoStatus does: active: true and no status for an
active account. A token's own checks come first, as SESSIONS.md says,
and each method's input after it; but createAppPassword, uploadBlob,
updateHandle, requestAccountDelete, the four email methods,
getAccountInviteCodes and putPreferences refuse a taken-down or deleted
account with the token, before the input, at no cost of the rate limits
(LIMITS.md). The token's own checks still come first: an app password's
session is 400 InvalidToken for requestEmailUpdate, updateEmail and
getAccountInviteCodes, whatever the account's state; and a query's
parameters come before the token, as PDS.md says, so a bad
getAccountInviteCodes parameter is 400 InvalidRequest in every state.
registerPush and unregisterPush check their input first, and refuse a
taken-down account where the service token would be made: no service token
is made for it, as for getServiceAuth below. A deleted account's is 500 InternalServerError there, and nothing is sent. The reference sends a
taken-down account's on (below, "What the reference does that the server
does not copy").
Neither requestPasswordReset nor resetPassword takes a token, and the
account's state changes neither: a deactivated or taken-down account's
email is mailed a reset_password token, and its password reset with it,
though a taken-down account still signs in only as above. A deleted
account's email is no account's (400 InvalidRequest), and a token mailed
to it before is no token (400 InvalidToken).
getServiceAuth and a forwarded call refuse a taken-down account just
after the token, in the order PROXY.md gives, whatever lxm and the
method: no service token is made for it. A deleted account's token, still
within its exp, passes every check and is then 500 InternalServerError, as the reference answers it: there is no key to sign
with. A deactivated account's are answered as an active one's, with its
OAuth session too. The reference makes service tokens for a taken-down
account too (below, "What the reference does that the server does not
copy").
Note: a deactivated account may still move to another server, which takes a service token.
A write names its repository by repo, and the repository's account
decides: after the token and the input are checked, a repo whose account
is deactivated is 401 AccountDeactivated, taken down 401 AccountTakedown, and deleted 403 AccountNotFound, whoever's token it is,
before it is asked whether the token is that account's (ACCOUNTS.md). A
write from a deactivated or taken-down account's token to another account's
repository is 401 AuthenticationRequired, as it would be from an active
one's.
uploadBlob checks the account's state with its token, before anything
of the body: a taken-down account is 401 AccountTakedown, and a deleted
one 403 AccountNotFound, whatever the Content-Type and however large
the body (BLOBS.md's checks come after).
updateHandle of a deactivated account changes its handle as for an
active one, in the server and in the PLC directory, with #identity on the
firehose; it still does not resolve.
Sessions of a taken-down account
createSession of a taken-down account checks the identifier and password
first: a wrong password, an app password, or an identifier no account has
is 401 AuthenticationRequired. With the account's password, it is 401 AccountTakedown, unless allowTakendown is true. Then it answers as
for any account, with active: false, status: "takendown", and tokens of
scope com.atproto.takendown:
- the access token is as
SESSIONS.md's table says, with that scope. It works fordeactivateAccount, as the account's own token forgetRepo,getBlobandlistBlobs, forgetPreferences, and forrequestPlcOperationSignatureandsignPlcOperation, so that a taken-down account may still move away (MIGRATION.md); every other method that takes a token answers it400 InvalidToken; - the refresh token is of scope
com.atproto.refresh, but the server keeps no session for it:refreshSessionwith it is401 AccountTakedownwhile the account is down, and400 ExpiredTokenafter, anddeleteSessionwith it200.
allowTakendown changes nothing for an account that is not taken down.
OAuth sessions
OAUTH.md's sessions, with what the reference does to them, probed:
- A deactivation with an OAuth token (
deactivateAccount, which needsaccount:status?action=manage,OAUTH-SCOPES.md) ends every OAuth session of the account, that token's and the others', at once: their access tokens are401 invalid_tokenfrom then on, and their refresh tokens400 invalid_grant, after the account is activated again too. Password sessions stay. It deletes every app password of the account too, but unlikerevokeAppPassword(SESSIONS.md) the sessions made with them stay, and refresh:listAppPasswordsanswers none, andcreateSessionwith one is401 AuthenticationRequired, after the account is activated again too, while an app password made after it works. It also forgets the clients the account approved (OAUTH-CLIENTS.md, "Silent sign-in"): each needs its consent again. A deactivation by a password session, an app password's, a taken-down session or the admin ends none and deletes none: an OAuth session of a deactivated account answers as its password session does (the table below), and refreshes. - A takedown, applied or lifted, of an account down or not, ends every
OAuth session of the account as it ends its password sessions, but its
access tokens too:
401 invalid_tokenat once. - A deletion ends them all, and forgets the requests approved for the
account, its sign-ins on every device, the clients it approved, and its
passkeys (
PASSKEYS.md). - Signing in on the authorization page (
OAUTH.md): a taken-down account, with its right password, is400 invalid_request,Account was taken down, and so with its passkey (PASSKEYS.md). A deactivated account signs in, by either, itsaccountshowingdeactivated: true, but its consent ends the request withaccess_denied,This account has been deactivated. - The authorization page lists the accounts signed in on its device
but a taken-down one, which stays signed in there, and shows again once
its takedown is lifted; nor is it a
login_hint's account: a hint of its DID is shown as given, not as its handle, and selects nothing. Its consent there, as signed in before, ends the request withinvalid_request(the description is not compared). - Silent sign-in (
OAUTH-CLIENTS.md) looks only at the accounts the page lists: a taken-down one, signed in on the device, is never approved there without asking, and is not counted. A deactivated one is listed but is not a hinted account: withprompt=noneand no other hinted account the request ends withlogin_required, and with nopromptthe page is shown, where its consent ends the request as above. - Requests approved and not yet exchanged. A takedown, applied or
lifted, of an account down or not, and a deactivation, by any of its
ways, end every request approved for the account whose code was not yet
exchanged, as
OAUTH.mdends a request: its code is spent, and the token endpoint refuses it,400 invalid_grant, after the takedown is lifted or the account activated again too. And the token endpoint refuses a code whose account is, when it is exchanged, taken down or deactivated,400 invalid_grant, whenever it was approved. The reference refuses only a taken-down account's code (below, "What the reference does that the server does not copy").
Each end is logged in the frame of the change that makes it, so that a
restart finds the sessions ended (DURABILITY.md).
The firehose
The events each change puts on the firehose, numbered after every event before them, in the order given:
| Change | Events |
|---|---|
deactivated, by deactivateAccount or the admin | #account with active: false and its status: deactivated, or takendown if it is down too |
activated, by activateAccount or the admin | #account with active: true; #identity with its handle; #sync of its latest commit |
| taken down, or the takedown lifted | #account with the status it now has: active: true and none, or active: false and deactivated or takendown |
updateSubjectStatus of an account with neither attribute | #account with its status |
updateSubjectStatus of a DID no account here has, deleted or never made, with takedown or with neither attribute | #account with active: false, status: "deleted" |
| deleted | #account with active: false, status: "deleted" |
| a record or a blob taken down or lifted | none |
Each is put on the firehose by each call, even one that changes nothing,
such as deactivating an account already deactivated. #account is {seq, did, time, active, status?} as the lexicon has it. A call that is
refused puts nothing.
Once an account is deleted, the firehose no longer serves any event of the
account but the #account of its deletion: a subscription from a cursor
before them replays the events of every other account, in the same order,
and the deletion's, and skips the deleted account's, leaving gaps in seq.
A subscriber already live when the account is deleted has had the events
before, and gets the deletion's after them. Numbers are never given out
again: the next event is numbered after every one given out, dropped or
not.
Rate limits
With PDS_RATE_LIMITS_ENABLED (LIMITS.md), these methods have limits of
their own, by the rules of LIMITS.md's "Rate limits", and each also costs
one point of global. In the table's order, as LIMITS.md uses it for the
headers and the 429 (the day's limit before the hour's: past both, the
reference answers the day's):
| Limit | Methods | Key | Points | Window |
|---|---|---|---|---|
| account deletion, day | requestAccountDelete | the token's DID | 15 | 86400 s |
| account deletion, hour | requestAccountDelete | the token's DID | 5 | 3600 s |
| delete | deleteAccount | client address | 50 | 300 s |
The other methods of this page have only global.
Durability
As DURABILITY.md says of every answered write: a deactivation, an
activation, a takedown of an account, a record or a blob and its lifting,
with the sessions a takedown ended, a delete_account token, and a
deletion, with everything it removed and the events it dropped, all survive
the server being killed. A deletion the server is killed during is whole or
not at all when it serves again: the account is there with everything it
had, or gone with nothing of it served, its handle and email free, and its
#account of deletion on the firehose.
What the reference does that the server does not copy
-
App passwords of a deleted account. The reference keeps them:
listAppPasswordswith an access token of the deleted account, still within itsexp, lists them. The server keeps nothing of a deleted account, and answers{passwords: []}. -
Events not yet sent. The reference drops a deleted account's events from its store at once, and a live subscriber that had not yet been sent one, because the account was deleted just after it, never gets it. The server sends a live subscriber every event in order, up to and including the deletion's.
-
Service tokens of a taken-down account. The reference makes them, by
getServiceAuth, for every call it forwards, and forregisterPushandunregisterPush, with an access token the account had before its takedown, of its password or an app password, until that token'sexp(probed:getServiceAuth200with and withoutlxm, a forwardedGETandPOSTsent on,200, andregisterPushandunregisterPushsent on,200). The server refuses them,401 AccountTakedown.Note: a takedown would otherwise leave the account speaking to every other service for two hours.
-
Requests approved before a change. The reference keeps them: a code approved before a deactivation (by the account, with its password or an OAuth token, or by the admin), before a takedown that was then lifted, or before a takedown lifted from an account not down, is exchanged after it, and a session made; a deactivated account's session so made answers
getSession(probed). It refuses only the code of an account taken down at the exchange. The server ends them, and refuses a deactivated account's code, as above ("OAuth sessions").Note: so no new session is made for an account its owner or the admin has just stopped.
How it is checked
node compare.mjs --lifecycle -- <server> is a run of its own:
harness/checks/lifecycle.mjs. It starts both sides as every run does, the
server with PDS_ADMIN_PASSWORD the reference's and PDS_DEV_MAIL_DIR
(EMAIL.md), subscribes to both firehoses from the start, makes accounts
with records, uploads and app passwords, and then, for --steps steps (80
by default), picks an account and a change, makes it on both sides, and
compares:
- The changes.
deactivateAccountwith and withoutdeleteAfter, a bad one, no body, no token, an app password's session, privileged or not;activateAccountwith a body, no token, an app password's session;updateSubjectStatusof an account, taking it down with and without aref, lifting it, deactivating and activating it, both attributes at once and the pair it refuses, neither, a DID no account has and a deleted account's DID with each attribute, and with wrong auth of each kind above; subjects that name nothing to change, each time all of them: a record'suriof a DID alone or a collection alone, of a DID no account has, a record's and a blob's of a DID no account has withdeactivated, and a subject of another$typewithdeactivated, with neither, and with a lifted takedown;getSubjectStatusof suchuris and of a record by handle, an account's or no account's;requestAccountDeleteanddeleteAccountwith each of its errors, in order, and then for real; and a password reset, asked for by the account's email and made with its token, in whatever state it is. Each answer is compared, with a takedown'srefthat the server made held to within a few seconds of the request and then taken out. - What each state does. After each change, every method of the tables
above, for the account: its repository read without a token, with its
token, an app password's, another account's, the admin's, a wrong
Basic, a refresh token, a forged one, aDPoPheader of a word, of its token and of a forged one; the same reads, some, of a DID no account has; its handle resolved; and each of its own calls with its token, andcreateSessionwith its password, an app password, a wrong one, andallowTakendown;uploadBlobwith noContent-Type, and sometimes of 5 MiB and a byte;createAppPassword,updateHandleandrequestAccountDeletewith bad input; the email methods, with a wrong token and with bad input,getAccountInviteCodeswith and without a bad parameter,getPreferenceswith its token and an app password's session,putPreferenceswith and without bad input,requestPasswordResetby its email, andregisterPushandunregisterPushto the harness's AppView. ThencreateAccountandupdateHandlewith its handle, and its email. Each answer is compared, asPDS.mdsays: a CAR file or a blob by status, and commit CIDs and revs taken out, withrepoCommitandrepoRev, andgetRepoStatus'srev, held to the side's latest commit, as the admin reads it; but a taken-down account'sregisterPushandunregisterPush, held to this page on the server alone. - OAuth sessions. Each account signs in through
OAUTH.md's flow with a client whose scope allows deactivating it; after each change its OAuth session callsgetSession,checkAccountStatus,createRecord,activateAccount,getServiceAuth, a forwarded call and some of the six sync reads, and refreshes, each compared with theWWW-Authenticateerror (a sync read's CAR file or blob by status); a session the reference ended is dropped, and a new one signed in for, which a taken-down account is refused at sign-in and a deactivated one at consent. Some deactivations are made with the OAuth token. - Requests approved before a change. Before some changes to an active account, a request is approved for it, and its code exchanged after the change: compared where the reference refuses it or neither side should, and held to this page on the server alone where the change or the account's state ends it and the reference does not.
- Silent sign-in. Each account signs in on a device of its own,
remembered, and approves a confidential client there
(
OAUTH-CLIENTS.md); after each change, a request of that client with the account's handle aslogin_hint,prompt=noneor none, and scopeatproto, is loaded there, compared: its code, if one is given at once, exchanged. The client is approved there again, now and then, while the account is active. - Service tokens and forwarded calls. After each change,
getServiceAuthandapp.bsky.feed.getPostsforwarded to the harness's AppView, with its token and an app password's session: compared, but for a taken-down account, held to this page on the server alone. - Taken-down sessions. For a taken-down account, a session made with
allowTakendown: its tokens' claims held toSESSIONS.md's table withscopecom.atproto.takendown, and both tokens used on the methods above, before and after the takedown is lifted. - Records and blobs.
updateSubjectStatusandgetSubjectStatusof records and blobs, there or not, taken down and lifted, then updated, deleted and made again; and each ofgetRecord,listRecords, the syncgetRecord,getBlob,listBlobs, a write referencing the blob, and uploading it again, compared. - validDid. An account's DID moved to another server by a PLC
operation each side signs with its own rotation key:
checkAccountStatusthen saysvalidDid: false, andactivateAccountand the admin's activation are refused, the latter sometimes with a takedown lifted in the same call, which stays lifted; moved back, they are not. Or the directory down, for both sides: the server's requests to it go through a proxy of the harness's, which then closes each connection or answers500, and the reference's PLC client is pointed at that proxy while it is down; thencheckAccountStatus,activateAccount, sometimesdeactivateAccount, and the admin's activation of the account, with a takedown lifted in the same call, and of a DID no account has. - The mail. Each
requestAccountDelete's email, compared bytoandkindwith the token's form held toEMAIL.md's; each side then deletes with its own token, in upper case or lower, and with the other side's token, an old one, or another account's. - After a deletion. Every method above for the deleted account;
activateAccountwith a body, and sometimes, with its DID moved elsewhere,activateAccountand the admin's activation;resetPasswordwith a token mailed to it before; then a new account made with its handle and its email, or another account's handle changed to its; and the server'slistAppPasswordswith its token, which must be{passwords: []}. - The firehose. After each change, both sides' new events must be the
same, in order, by type, account,
active,statusand handle, and each#syncchecked as a new account's is. After each deletion, a new subscription from cursor 0 on each side must replay the same events, in order, with none of the deleted account's but its deletion, and everyseqafter the one before. - Crashes. With
--crash-every N, the server is killed everyNsteps, sometimes with a change on its way, and started again; then every account's state is read again as above, against the reference, which was not killed, and the firehose replayed from cursor 0.
Not compared:
getRecordof an account that is not active, which each side forwards (PROXY.md); the harness's AppView decides what it answers.- A token past its 15 minutes, which the harness does not wait for; the reference's rule was seen by making its token older in its database.
- An access token past its
expon the sync reads: the harness does not wait two hours, and cannot sign one for the server; the reference's rule was seen with one signed with its own key. - The rate limits above: this run, as every run but
--limits, has them off on both sides;--limitscompares them (LIMITS.md). deleteAfterbeyond its form: no method answers it.- What the reference does that the server does not copy, above: the
server's
listAppPasswordsafter a deletion, a taken-down account'sgetServiceAuth, forwarded calls,registerPushandunregisterPush, and the exchange of a code that a change ended or of a deactivated account, are held to this page alone, and the harness waits for each change's events before it deletes.