~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
758 lines · 43.5 KB Raw History

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:

StateStatusMade byEnded by
activenonecreateAccountany of the others
deactivateddeactivateddeactivateAccount, or the adminactivateAccount, or the admin
taken downtakendownthe adminthe admin
deleteddeleteddeleteAccountnothing

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:

  1. 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 by createSession with allowTakendown (com.atproto.takendown, below); an app password's session, privileged or not, is 400 InvalidToken, as is any other token the server would refuse (SESSIONS.md).
  2. The input, a JSON body: none, or a deleteAfter that is not a datetime (atproto/lexicon.md), is 400 InvalidRequest. {} is taken.
  3. A deleted account, whose token still works until its exp (SESSIONS.md), is 400 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:

  1. The token: none is 401 AuthMissing; anything but an access token of a session made with the account's password is 400 InvalidToken: an app password's, and a com.atproto.takendown one's, too.
  2. A request body is 400 InvalidRequest.
  3. The account's DID document must name this server, as checkAccountStatus's validDid says (below), read from the PLC directory now: data that does not name this server, or a DID the directory does not know, is 400 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, is 400 InvalidRequest when the rest does not name this server, and 500 InternalServerError when it does, as the reference answers it. A did:web account's document is read from its host instead, and names this server by its endpoint and signing key alone, as MIGRATION.md ("A did:web account") says, with the errors it gives.
  4. 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:

FieldIs
activatedfalse if the account is deactivated or taken down, true otherwise
validDidwhether 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
repoCommitthe CID of the repository's latest commit
repoRevthat commit's rev
repoBlockshow many distinct blocks the latest commit and its tree are: the commit, every MST node, and every record, each CID counted once
indexedRecordshow many records the repository has
privateStateValues0
expectedBlobshow many distinct blobs the account's records reference
importedBlobshow 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:

  1. The token: none is 401 AuthMissing; anything but an access token of a session made with the account's password is 400 InvalidToken.
  2. A taken-down account is 401 AccountTakedown; a deleted one 403 AccountNotFound.
  3. A request body is 400 InvalidRequest.
  4. An account without an email (made without a password, ACCOUNTS.md) is 400 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:

  1. The input against the lexicon: a did that is not a DID, or any of the three missing, is 400 InvalidRequest. Fields it does not name are ignored.
  2. A password longer than 512 UTF-16 code units, counted as ACCOUNTS.md counts a password, is 401 AuthenticationRequired.
  3. A did no account here has, including one deleted, is 400 InvalidRequest.
  4. A password that is not the account's password is 401 AuthenticationRequired. An app password is not the account's password, and an account made without a password has none to give.
  5. A token that is not the account's delete_account token is 400 InvalidToken; one past its 15 minutes, 400 ExpiredToken. It is matched as EMAIL.md matches 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, a Basic value that does not decode or has no :, a DPoP header, and any request while PDS_ADMIN_PASSWORD is unset or empty (LIMITS.md): 401 AuthenticationRequired;
  • a Bearer token: the reference takes it for a moderation service's JWT, which the server does not take. A JWT whose header typ is at+jwt or refresh+jwt, as each of the server's own tokens is, is 401 BadJwtType; any other value 401 BadJwt;
  • a header that is not two words: 400 InvalidToken, as SESSIONS.md says.

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):

  1. takedown.applied: true with deactivated.applied: false is 400 InvalidRequest.

  2. With takedown, a subject of a $type other than the three is 400 InvalidRequest, whatever applied is and whatever deactivated is. Without takedown, one is taken and changes nothing: deactivated, either way, or neither attribute, is 200, with nothing on the firehose.

  3. takedown is applied first:

    • An account. applied: true takes it down, with ref as the takedown's reference, or the time, as a datetime, if none is given; again, it replaces the reference. applied: false lifts 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 then 401 AccountTakedown while it is down, and 400 ExpiredToken after, or at once if it is not down (SESSIONS.md); access tokens work until their exp, where the account's state lets them (below). Tokens mailed to it stay. Either way, #account goes 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 #account on the firehose for that DID, with active: false, status: "deleted".
    • A record, by its uri: applied: true takes down the record its repository now has at that collection/rkey, whatever cid says; applied: false lifts that. A key the repository does not hold is taken down by nothing, and 200 all 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. A uri whose authority is a handle, or a DID no account here has, is 500 InternalServerError. A uri of 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 is 200.
    • A blob of the account did names: applied: true takes it down, with ref or the time, as for an account; applied: false lifts it. A blob the account does not hold is taken down by nothing, and 200; one it stops holding (BLOBS.md) loses its takedown with it. A did no account here has is 500 InternalServerError.
  4. Then deactivated, of an account: applied: true deactivates it, and applied: false activates 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 as activateAccount's step 3 reads it, with the same errors: 400 InvalidRequest for one that does not name this server, 502 UpstreamFailure when the directory cannot be read. Of a DID no account here has, applied: true is 400 InvalidRequest; applied: false reads the directory too: 400 InvalidRequest for a DID it does not know or whose data does not name this server, 502 UpstreamFailure when it cannot be read, and 500 InternalServerError for one whose data names this server, as a deleted account's. Neither puts anything on the firehose. deactivated of a record or a blob, whatever its uri or did, changes nothing.

    The two are applied one after the other, not as one: when deactivated is refused, what takedown did stays, with its #account on the firehose, and the answer is deactivated's error. So a takedown lifted with deactivated.applied: false from an account whose DID document does not name this server is lifted, with #account of the status it now has, and the answer is 400 InvalidRequest.

  5. With neither takedown nor deactivated, an account subject puts #account on 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:

  1. blob: needs did, else 400 InvalidRequest. A did no account here has is 400 NotFound. A blob the account holds answers {subject: {$type: "com.atproto.admin.defs#repoBlobRef", did, cid}, takedown}; one it does not is 400 NotFound.
  2. uri: one whose authority is a handle is 500 InternalServerError, whether or not an account has that handle. A DID no account here has is 400 NotFound. A record the repository holds at that key answers {subject: {$type: "com.atproto.repo.strongRef", uri, cid}, takedown}, cid the record's as it is now; a key it does not hold, and a uri with no key (at://<did>, at://<did>/<collection>), is 400 NotFound.
  3. did: an account here answers {subject: {$type: "com.atproto.admin.defs#repoRef", did}, takedown, deactivated}; a DID no account here has is 400 NotFound.
  4. 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

MethodDeactivatedTaken downDeleted
describeRepo, by DID or handle400 RepoDeactivated400 RepoTakendown400 RepoNotFound
com.atproto.repo.getRecordas of a repository the server does not hold (PROXY.md)the samethe same
listRecords400 InvalidRequest400 InvalidRequest400 InvalidRequest
getLatestCommit, getRepo, getBlocks, the sync getRecord, getBlob, listBlobs400 RepoDeactivated400 RepoTakendown400 RepoNotFound
getRepoStatus{did, active: false, status: "deactivated"}{did, active: false, status: "takendown"}400 RepoNotFound
listReposlisted 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.takendown one too for getRepo, getBlob and listBlobs, or with the admin's Basic, they answer as if the account were active: the account and the admin read its repository and blobs, deactivated or taken down. Deleted, it is 400 RepoNotFound all the same.
  • Another account's token is the same as none. A token the server would refuse, a refresh token, or a com.atproto.takendown token for getLatestCommit, getBlocks or the sync getRecord, is 400 InvalidToken; one past its exp, 400 ExpiredToken; a Basic header 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: the Authorization is checked before the DID, so a bad one is answered with its own error, not 400 RepoNotFound, which a good one, of any account or the admin's, or none, is.
  • A DPoP header is an OAuth access token, checked with its proof as OAUTH-SCOPES.md says, before the DID too: one the server did not give out as an OAuth token, a session's accessJwt or a forged one, is 401 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:

MethodDeactivatedTaken downDeleted
getSession200, active: false, status: "deactivated"400 InvalidRequest400 InvalidRequest
refreshSession, with its refresh token200, the same401 AccountTakedown400 InvalidRequest
deleteSession, with its refresh token200200200
createSession200, the samebelow401 AuthenticationRequired
createAppPassword200401 AccountTakedown403 AccountNotFound
listAppPasswords200200200 {passwords: []}
revokeAppPassword200200200
_oauthSessions, _oauthDevices (OAUTH-ACCOUNT.md)200200200, none listed
_oauthRevokeSession, _oauthRevokeDevice (OAUTH-ACCOUNT.md)200200200
_passkeyList (PASSKEYS.md)200200200, none listed
_passkeyAdd (PASSKEYS.md)200401 AccountTakedown403 AccountNotFound
_passkeyRemove (PASSKEYS.md)200200200
createRecord, putRecord, deleteRecord, applyWrites401 AccountDeactivated401 AccountTakedown403 AccountNotFound
uploadBlob200401 AccountTakedown403 AccountNotFound
updateHandle200, as for an active account401 AccountTakedown403 AccountNotFound
getRecommendedDidCredentials200200, without alsoKnownAs500 InternalServerError
checkAccountStatus200, activated: false200, activated: false400 NotFound
deactivateAccount200200400 InvalidRequest
activateAccount200400 AccountNotFound500 InternalServerError
requestAccountDelete200401 AccountTakedown403 AccountNotFound
getServiceAuth (PROXY.md)200, as for an active account401 AccountTakedown500 InternalServerError
importRepo (MIGRATION.md)200401 AccountTakedown403 AccountNotFound
listMissingBlobs (MIGRATION.md)200200400 NotFound
submitPlcOperation (MIGRATION.md)as for an active accountas for an active account500 InternalServerError, once its operation's form, rotation key and service are checked
requestPlcOperationSignature (MIGRATION.md)200200400 InvalidRequest
signPlcOperation (MIGRATION.md)as for an active accountas for an active account400 InvalidToken: it has no token
a call forwarded to another service (PROXY.md)forwarded as for an active account401 AccountTakedown, sent nowhere500 InternalServerError, sent nowhere
requestEmailConfirmation, confirmEmail, requestEmailUpdate, updateEmail (EMAIL.md)as for an active account401 AccountTakedown403 AccountNotFound
getAccountInviteCodes (LIMITS.md)400 NotFound401 AccountTakedown403 AccountNotFound
getPreferences (PROXY.md)200, as for an active account200, as for an active account400 NotFound
putPreferences (PROXY.md)200, as for an active account401 AccountTakedown403 AccountNotFound
registerPush, unregisterPush (PROXY.md)sent on as for an active account401 AccountTakedown, sent nowhere500 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 for deactivateAccount, as the account's own token for getRepo, getBlob and listBlobs, for getPreferences, and for requestPlcOperationSignature and signPlcOperation, so that a taken-down account may still move away (MIGRATION.md); every other method that takes a token answers it 400 InvalidToken;
  • the refresh token is of scope com.atproto.refresh, but the server keeps no session for it: refreshSession with it is 401 AccountTakedown while the account is down, and 400 ExpiredToken after, and deleteSession with it 200.

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 needs account:status?action=manage, OAUTH-SCOPES.md) ends every OAuth session of the account, that token's and the others', at once: their access tokens are 401 invalid_token from then on, and their refresh tokens 400 invalid_grant, after the account is activated again too. Password sessions stay. It deletes every app password of the account too, but unlike revokeAppPassword (SESSIONS.md) the sessions made with them stay, and refresh: listAppPasswords answers none, and createSession with one is 401 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_token at 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, is 400 invalid_request, Account was taken down, and so with its passkey (PASSKEYS.md). A deactivated account signs in, by either, its account showing deactivated: true, but its consent ends the request with access_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 with invalid_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: with prompt=none and no other hinted account the request ends with login_required, and with no prompt the 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.md ends 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:

ChangeEvents
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 liftednone

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):

LimitMethodsKeyPointsWindow
account deletion, dayrequestAccountDeletethe token's DID1586400 s
account deletion, hourrequestAccountDeletethe token's DID53600 s
deletedeleteAccountclient address50300 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: listAppPasswords with an access token of the deleted account, still within its exp, 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 for registerPush and unregisterPush, with an access token the account had before its takedown, of its password or an app password, until that token's exp (probed: getServiceAuth 200 with and without lxm, a forwarded GET and POST sent on, 200, and registerPush and unregisterPush sent 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. deactivateAccount with and without deleteAfter, a bad one, no body, no token, an app password's session, privileged or not; activateAccount with a body, no token, an app password's session; updateSubjectStatus of an account, taking it down with and without a ref, 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's uri of 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 with deactivated, and a subject of another $type with deactivated, with neither, and with a lifted takedown; getSubjectStatus of such uris and of a record by handle, an account's or no account's; requestAccountDelete and deleteAccount with 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's ref that 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, a DPoP header 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, and createSession with its password, an app password, a wrong one, and allowTakendown; uploadBlob with no Content-Type, and sometimes of 5 MiB and a byte; createAppPassword, updateHandle and requestAccountDelete with bad input; the email methods, with a wrong token and with bad input, getAccountInviteCodes with and without a bad parameter, getPreferences with its token and an app password's session, putPreferences with and without bad input, requestPasswordReset by its email, and registerPush and unregisterPush to the harness's AppView. Then createAccount and updateHandle with its handle, and its email. Each answer is compared, as PDS.md says: a CAR file or a blob by status, and commit CIDs and revs taken out, with repoCommit and repoRev, and getRepoStatus's rev, held to the side's latest commit, as the admin reads it; but a taken-down account's registerPush and unregisterPush, 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 calls getSession, checkAccountStatus, createRecord, activateAccount, getServiceAuth, a forwarded call and some of the six sync reads, and refreshes, each compared with the WWW-Authenticate error (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 as login_hint, prompt=none or none, and scope atproto, 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, getServiceAuth and app.bsky.feed.getPosts forwarded 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 to SESSIONS.md's table with scope com.atproto.takendown, and both tokens used on the methods above, before and after the takedown is lifted.
  • Records and blobs. updateSubjectStatus and getSubjectStatus of records and blobs, there or not, taken down and lifted, then updated, deleted and made again; and each of getRecord, listRecords, the sync getRecord, 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: checkAccountStatus then says validDid: false, and activateAccount and 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 answers 500, and the reference's PLC client is pointed at that proxy while it is down; then checkAccountStatus, activateAccount, sometimes deactivateAccount, 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 by to and kind with the token's form held to EMAIL.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; activateAccount with a body, and sometimes, with its DID moved elsewhere, activateAccount and the admin's activation; resetPassword with 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's listAppPasswords with 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, status and handle, and each #sync checked 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 every seq after the one before.
  • Crashes. With --crash-every N, the server is killed every N steps, 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:

  • getRecord of 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 exp on 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; --limits compares them (LIMITS.md).
  • deleteAfter beyond its form: no method answers it.
  • What the reference does that the server does not copy, above: the server's listAppPasswords after a deletion, a taken-down account's getServiceAuth, forwarded calls, registerPush and unregisterPush, 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.