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

Moving an account between servers

An account keeps its DID wherever it is hosted, and may move from one PDS to another with its repository, its blobs and its preferences, as atproto's account migration does. This page says what the server does as the server an account moves to, and as the one it moves away from. What every method shares, and how the server is checked, is in PDS.md; accounts are as ACCOUNTS.md says, their states as LIFECYCLE.md says, handles as IDENTITY.md says, and email tokens as EMAIL.md says.

The methods: com.atproto.repo.importRepo and listMissingBlobs; com.atproto.identity.submitPlcOperation, requestPlcOperationSignature and signPlcOperation; and createAccount with a did.

The move

A client, holding a session on the old server, moves an account so:

StepOnCall
1oldgetServiceAuth with aud the new server's DID and lxm com.atproto.server.createAccount (PROXY.md)
2newcreateAccount with the account's did, and the service token from step 1 as its bearer token: the account is made, deactivated
3old, newgetRepo on the old, importRepo of it on the new
4new, oldlistMissingBlobs on the new; for each, getBlob on the old and uploadBlob on the new
5old, newgetPreferences on the old, putPreferences on the new (PROXY.md)
6newgetRecommendedDidCredentials (IDENTITY.md)
7oldrequestPlcOperationSignature, which mails a token; signPlcOperation with that token and step 6's fields
8newsubmitPlcOperation of step 7's operation
9new, oldactivateAccount on the new, deactivateAccount on the old (LIFECYCLE.md)

The server serves every step of both sides. Between steps 2 and 9 the account is deactivated on the new server, so that nothing it holds there is served to others or put on the firehose until it is whole and its DID document names the new server.

Moving in

createAccount with a DID

createAccount takes an optional bearer token, a service token (atproto/xrpc.md) the account's current server made for it. Its checks, in this order, before and among those ACCOUNTS.md lists:

  1. The Authorization header, before the input. None is taken. A header that is not two words is 400 InvalidToken, as SESSIONS.md says of any header's form. A scheme other than Bearer, such as DPoP or Basic, is 401 AuthenticationRequired. A Bearer token is a service token, checked in this order, each fault 401 with this name:

    1. not three parts joined by .: BadJwt. A first or second part that is not base64url of JSON is 500 InternalServerError, as the reference answers it;
    2. a header that is not an object with a string alg: BadJwt;
    3. a header typ of at+jwt, refresh+jwt or dpop+jwt, as each of the server's own tokens and DPoP proofs has: BadJwtType. So a session's accessJwt is BadJwtType;
    4. a payload that is not an object with string iss and aud, number exp, and lxm a string if it is there and not empty: BadJwt;
    5. exp before now, in seconds: JwtExpired;
    6. lxm other than com.atproto.server.createAccount, or none: BadJwtLexiconMethod;
    7. iss not a DID, alone or followed by # and a fragment of one or more characters with no second #: BadJwtIss;
    8. iss's DID document, read as "A did:web account" below says of an account's (a did:plc from PDS_PLC_URL, a did:web from its host): one that cannot be read (the directory or the host answers anything but 2xx), or that names no #atproto key (#atproto_label for a fragment of #atproto_labeler), is 401 AuthenticationRequired. A did:web whose host does not answer, or whose answer is not a DID document of that DID, is 500 InternalServerError, as the reference answers it;
    9. a signature that is not that key's over the first two parts, by alg (ES256K for a secp256k1 key, ES256 for P-256), high-S signatures taken: BadJwtSignature. Before it answers so, the server reads the document again from the directory, past anything it kept (IDENTITY.md), and tries its key, so that a key rotated a moment ago is not refused;
    10. aud other than the server's DID, did:web:<PDS_HOSTNAME>, a fragment included: BadJwtAudience.

    A token that passes names its iss as the caller. Nothing else of it is kept: the same token may be given again until its exp.

  2. The input, as ACCOUNTS.md's steps 1 to 5: the lexicon, the password's length, with PDS_INVITE_REQUIRED the code (LIMITS.md), the email, the handle, then the handle and email another account has. A plcOp given, of any value, is 400 InvalidRequest after the lexicon. With did given, a handle outside PDS_HANDLE_DOMAINS is an external one: it must resolve to did (IDENTITY.md, "Resolving a handle"), else 400 InvalidRequest; ACCOUNTS.md's other rules of a handle do not apply to it.

  3. did against the caller. A did other than the token's iss, or given with no token, is 401 AuthenticationRequired. A token given without did makes an account as one made without a token: the token is checked as above, and then not used.

  4. did itself. A did that is neither a did:plc nor a did:web as atproto/did.md allows one (a host name, no path, a port only on localhost) is 400 InvalidRequest. A did an account here has, in any state but deleted, is 400 AlreadyExists.

  5. The invite code, as ACCOUNTS.md's step 7.

Two createAccounts at once with one did make one account at most; the other is 400 AlreadyExists.

The server then makes the account as ACCOUNTS.md says, but:

  • it posts no operation to the directory: the DID is the account's already, and its document names the old server until step 8;
  • it makes a new signing key and a new KEM key, as for any account, for getRecommendedDidCredentials to name;
  • the account is made deactivated (LIFECYCLE.md), and nothing goes on the firehose: no #identity, #account, #commit or #sync. Its empty repository's first commit is the start of its history here;
  • it answers {handle, did, didDoc, accessJwt, refreshJwt} as any createAccount does, didDoc the document the directory serves for the DID now, which names the old server and its handle there.

The session is the account's as any other: getSession answers active: false, status: "deactivated", and the account may do with it what a deactivated account does (LIFECYCLE.md), importRepo, uploadBlob, putPreferences, getRecommendedDidCredentials, submitPlcOperation and activateAccount among them.

importRepo

importRepo takes a repository as a CAR file, the request body, and makes it the token's account's repository. 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; an app password's session, privileged or not, and a com.atproto.takendown one, are 400 InvalidToken, as is any other token the server would refuse. A taken-down account is 401 AccountTakedown, a deleted one 403 AccountNotFound. A deactivated one may import.

  2. The Content-Type: none is 400 InvalidRequest, and so is any media type but application/vnd.ipld.car.

  3. The size: a body longer than PDS_MAX_REPO_IMPORT_SIZE (LIMITS.md) is 413 PayloadTooLarge.

  4. The CAR, as atproto/repository.md describes one:

    • a body that is not a CAR (empty, cut short, or anything else), a header naming no root, a root whose block is not in it, a root that is no commit (a map with did, data and rev, of version 2 or 3), or a block the commit does not reach, is 500 InternalServerError, as the reference answers each. Whether the tree is whole (below) is asked before whether every block is reached, so a CAR without its tree's root is 400;
    • a header naming more than one root is 400 InvalidRequest;
    • an MST node reached twice, a key that is not a collection/rkey path, and a record that does not decode as the data model (atproto/data-model.md) or is not a map, are 400 InvalidRequest;
    • a commit whose did is not the account's; a tree that is not whole, an MST node or a record it names missing from the CAR; and a tree that is not the one its records make, its root built again from their keys and CIDs as atproto/repository.md's MST is not the commit's data, are 400 InvalidRequest ("Where the reference departs", below).

    The commit's signature is not checked: the key that made it may be rotated away already. Records are not checked against their lexicons.

Otherwise the repository is the CAR's tree, and the server answers 200 with an empty body. It does so as a write does, all or nothing:

  • the repository's records are the tree's, each by its key: what the account had and the tree has not is deleted, what both have and differ in is replaced, and what the tree adds is made. Each is the CAR's block, byte for byte, at the CID the tree names, through a restart too, though JSON would write it as another record's: a map of the one key $link, a CID string, as some servers wrote a blob ref's ref, is written as a link is, and a map with $bytes as bytes are. Each stays the map it is (BLOBS.md, "Blob refs in records");
  • its head is a new commit, signed with the account's signing key, whose data is the tree's root and whose rev is a new TID, later than every rev before (DURABILITY.md), with prev null. Its getRepo, getLatestCommit and checkAccountStatus answer that commit, and getRepo verifies against the key the account's DID document names once step 8 is done;
  • every blob the tree's records reference is the account's to hold: one it holds already is referenced, and one it does not is missing, until it is uploaded (listMissingBlobs). A blob that no record references any more is as after a write that deletes the last record that did (BLOBS.md). checkAccountStatus' expectedBlobs counts every blob the records reference, missing or not, and importedBlobs every blob the account holds;
  • a record takedown on a key the tree has no record at ends, as a deletion ends it (LIFECYCLE.md).

A deactivated account's import puts nothing on the firehose: its activateAccount puts #sync of the head then. An active account's puts #sync of the new head, as SYNC.md describes it, with the account's DID and the new rev, so that every consumer takes the new state whole.

The same CAR imported again makes a new commit of the same tree. Imports of one account at once are made one after the other, each whole.

listMissingBlobs

listMissingBlobs {limit?, cursor?} lists the blobs the token's account's records reference that it does not hold. Its parameters are checked first, as the lexicon says (limit 1 to 1000, by default 500): any fault is 400 InvalidRequest. Then the token: none is 401 AuthMissing; any access token of the account is taken, an app password's too, but not a com.atproto.takendown one (400 InvalidToken). A deleted account is 400 NotFound; a deactivated or taken-down one is answered.

It answers {blobs, cursor}:

  • blobs lists each missing blob once, {cid, recordUri}, recordUri a record of the account that references it (which one, when several do, is the server's choice), in the order of their CIDs as strings, the first limit of those whose CID is after cursor as strings, or all with no cursor. A cursor that is no CID is a string all the same: zzz is after every CID;
  • cursor is the last listed blob's CID, and is left out when blobs is empty.

A blob is missing until the account holds it: uploadBlob of its bytes takes it off the list, at once, and getBlob and listBlobs then serve it as any referenced blob (BLOBS.md).

submitPlcOperation

submitPlcOperation {operation} sends a PLC operation for the token's account's DID to the directory, once it has checked that the operation leaves the DID hosted here. It checks, in this order:

  1. The token: none is 401 AuthMissing. Any access token of the account is taken, an app password's too, privileged or not, but not a com.atproto.takendown one (400 InvalidToken). The account may be deactivated or taken down.

  2. The input against the lexicon: operation missing or not an object is 400 InvalidRequest.

  3. operation must be a signed operation of atproto/did-plc.md's form: type "plc_operation", rotationKeys a list of strings, verificationMethods a map of strings, alsoKnownAs a list of strings, services a map of {type, endpoint} strings, prev a string or null, and sig a string. Anything else, a plc_tombstone and a legacy create among them, is 400 InvalidRequest.

  4. Each of these, in order, else 400 InvalidRequest:

    • rotationKeys includes the server's rotation key, as a did:key;
    • services.atproto_pds.type is AtprotoPersonalDataServer;
    • services.atproto_pds.endpoint is PDS_PUBLIC_URL;
    • verificationMethods.atproto is the account's signing key, as a did:key. A deleted account, whose key is gone, is 500 InternalServerError here, as the reference answers it;
    • the first entry of alsoKnownAs is at://<handle>, the account's handle.

    Nothing else of it is checked here: its signature, its prev and any keys besides those above are the directory's to check.

  5. A did:web account's DID is no directory's: its operation is 400 InvalidRequest, and nothing is posted ("A did:web account", below).

  6. The directory: it is posted to PDS_PLC_URL as the DID's next operation. One the directory refuses, as for a bad signature or a prev that is not its last operation, is 400 InvalidRequest with the directory's message; a directory that cannot be reached, 502 UpstreamFailure.

Otherwise it answers 200 with an empty body, and puts #identity on the firehose with the account's did and no handle, whatever the account's state. describeRepo, checkAccountStatus and activateAccount read the document that operation made at once, as after a handle change (IDENTITY.md).

The server keeps no record of the operation: unlike a handle change, it is the directory's alone, and a submit the server is killed during is in the directory or not, as the directory took it.

Moving out

getServiceAuth, getRepo, listBlobs, getBlob, getPreferences and deactivateAccount serve a deactivated account as an active one (LIFECYCLE.md), so that an account may move away at any point. The two methods below sign the operation that points its DID elsewhere.

requestPlcOperationSignature

requestPlcOperationSignature has no input. 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, or a com.atproto.takendown one (LIFECYCLE.md); an app password's session, privileged or not, is 400 InvalidToken, as is any other token the server would refuse.
  2. A request body is 400 InvalidRequest.
  3. A deleted account 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 plc_operation, 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 plcOperation, and answers 200 with an empty body. A deactivated or taken-down account may ask.

signPlcOperation

signPlcOperation {token?, rotationKeys?, alsoKnownAs?, verificationMethods?, services?} answers the account's DID's next PLC operation, signed by the server, without sending it anywhere. It checks, in this order:

  1. The token, as requestPlcOperationSignature's.
  2. The input against the lexicon: rotationKeys or alsoKnownAs that is not a list of strings, and verificationMethods or services that is not an object, are 400 InvalidRequest. Fields it does not name are ignored.
  3. token missing or empty is 400 InvalidRequest.
  4. token must be the account's plc_operation token, matched as EMAIL.md matches tokens: one that is not is 400 InvalidToken, one past its 15 minutes 400 ExpiredToken. A deleted account has none.
  5. The DID's last operation, read from PDS_PLC_URL as GET <PLC>/<did>/log/last answers it: a directory that cannot be reached is 502 UpstreamFailure; a DID it does not know, as every did:web, is 400 InvalidRequest; a DID whose last operation is a tombstone is 400 InvalidRequest.

Otherwise it answers 200 with {operation}: a plc_operation whose rotationKeys, alsoKnownAs, verificationMethods and services are the input's where given and the last operation's where not, each whole, with prev the CID of the last operation, signed with the server's rotation key (PDS_PLC_ROTATION_KEY_HEX) as atproto/did-plc.md describes. The given fields are taken as they are: nothing checks that they make a document the directory will take, or that the server's rotation key may sign the DID's next operation.

The token is used up, as EMAIL.md says. The operation changes nothing until someone submits it to the directory, by the new server's submitPlcOperation or otherwise; the account here stays as it was until its owner deactivates or deletes it.

A did:web account

An account's DID may be a did:web (atproto/did.md), whose document its owner serves at its host, rather than a did:plc. Such an account is made here only by createAccount with its did ("Moving in"), the server never making one: its service token is signed by whichever server holds it now, or, for an account new to every server, by its owner with the key its document names. It then moves in as any account does, but that no operation is submitted: its owner changes its document instead, to name getRecommendedDidCredentials' key and endpoint, and then activates it.

The server reads a did:web's document from https://<host>/.well-known/did.json, or http:// for localhost, as PROXY.md reads a did:web, and holds it as it holds a did:plc's document from the directory, for PDS_DID_CACHE_SECS (IDENTITY.md). Of the document it takes, as atproto/did.md says: the handle, the first at:// entry of alsoKnownAs; the signing key, the first verificationMethod whose id ends #atproto, as a did:key; and the endpoint, the first service whose id ends #atproto_pds and whose type is AtprotoPersonalDataServer, its serviceEndpoint. Where a did:plc account's document is read for what it names, a did:web account's is read so too, with these differences:

  • It names this server (activateAccount, checkAccountStatus's validDid, LIFECYCLE.md) when its endpoint is PDS_PUBLIC_URL and its signing key the account's. It has no rotation keys, and none are asked of it. Its handle is not asked either.
  • It cannot be read. For activateAccount, a host that answers anything but 2xx is 400 InvalidRequest, and one that does not answer, or answers with what is no document of the DID, 500 InternalServerError, as the reference answers the first two. For checkAccountStatus, validDid is false. For describeRepo, 400 InvalidRequest (IDENTITY.md), whatever kept it from being read.
  • updateHandle (IDENTITY.md) posts no operation: the owner changes the document first. After the handle's own checks, the document is read again, past anything kept, and its handle must be the new one exactly, as given lowercased: else 400 InvalidRequest, and nothing changes. A document that cannot be read is 500 InternalServerError, as the reference answers it. A handle that passes is the account's at once, with its #identity event, as for any account; kept as a handle change is (IDENTITY.md, "Crashes"), but with no operation to settle: one the server stopped during lands whole when it starts again.
  • No PLC method applies. requestPlcOperationSignature mails its token as for any account; signPlcOperation with it is 400 InvalidRequest, as the directory knows no such DID (step 5); submitPlcOperation is 400 InvalidRequest before anything is posted (step 5).

Moving away, a did:web account's owner points its document at the new server; the old server's part is getServiceAuth, getRepo, getBlob and deactivateAccount, as for any account.

Where the reference departs

The reference takes, in importRepo, what would leave a repository the server could not serve whole or sign; the server refuses or mends it:

The referenceThe server
takes a CAR whose commit names another DID, and serves that commit as the account's400 InvalidRequest
takes a tree with MST nodes or records missing, and serves what it found400 InvalidRequest
takes a tree whose nodes are not the MST its records make, without building it again400 InvalidRequest
keeps the CAR's own commit as the head, signed by whoever signed it, so that the repository does not verify against the account's new key until its next write; and its #sync on activation carries that commitmakes a new commit of the tree, signed with the account's key
puts nothing on the firehose when an active account imports, so that consumers keep the state before itputs #sync of the new head
posts a did:web account's submitPlcOperation to the directory, and answers the directory's refusal 502 UpstreamFailure400 InvalidRequest, nothing posted

What each state does

LIFECYCLE.md's table of an account's own calls has a row for each method here. The space methods' importRepo, com.atproto.space.importRepo, is another method (SPACES-EXPORT.md).

How it is checked

node compare.mjs --moves -- <server command> is a run of its own, harness/checks/moves.mjs. Beside the reference and the server it starts a third PDS, the reference on the same PLC directory, which accounts move from and to, and it serves handles, DNS and HTTPS, for all three (IDENTITY.md, "How it is checked"). It subscribes to both firehoses, makes on both sides an account whose handle and email others then ask for, and one without a password, and then each of --steps, 6 by default, is a move in, a move out, the states or a did:web account, in turn. Each request goes to both sides alike, and their answers are compared by status and error, or whole where they answer, with each side's DIDs, handles, keys and URLs named alike:

  • In. An account for each side on the third PDS, alike, with records and blobs, some blob referenced by two records, and preferences. Then: createAccount with a sample of the refusals above, each drawn: no token, one that is no JWT or of four parts, a session's, a header with no alg or a typ of dpop+jwt or refresh+jwt, no aud, an exp that is a string or has passed, another lxm or none, an iss that is no DID or one no directory knows, a key not the DID's, another aud or one with a fragment, the DPoP scheme, a did not the token's, a plcOp, a handle of a disallowed top-level domain, and a handle or email another account has; and always an external handle that resolves to nothing and one that resolves to another DID, by DNS or HTTPS. Then the account made, with its third PDS's service token, with a handle under the sides' domains, or an external one resolving by DNS, by HTTPS, or by HTTPS where DNS finds two DIDs; its didDoc held to the directory's; and sometimes again, 400 AlreadyExists. Nothing of it on either firehose. getSession, checkAccountStatus, describeRepo and getRepoStatus. importRepo with, each drawn, no token, an app password's, a JSON Content-Type or none, a body that is no CAR or empty, one larger than PDS_MAX_REPO_IMPORT_SIZE, which both sides are started with at 1 MiB so that the body is cheap to send, a CAR of two roots, one whose root is the tree's; then the third PDS's getRepo, and sometimes again. The server alone is held to "Where the reference departs", each drawn: a CAR of another DID's commit, one with a record taken out, and one with the tree's root taken out, 400 InvalidRequest; and after the good one, a head whose data is the CAR's, whose rev is later than the first commit's, verifying against the account's new key. getLatestCommit and checkAccountStatus, and nothing on either firehose. listMissingBlobs with no token, limit 0 and 1001, an app password's, a cursor of zzz, each drawn; then the list whole, and paged by one; recordUri compared where one record references the blob, and else held only to name a record. Each blob uploaded, in a drawn order, and the list again. putPreferences with the third PDS's, and getPreferences. Then the third PDS signs the operation of the side's getRecommendedDidCredentials, and on each side submitPlcOperation with, each drawn, no token, no operation, null, one not of the form, a tombstone, rotation keys without the side's, a service of another type, another endpoint, another signing key, another handle, and a signature the directory refuses, after each of which the directory's log must be as it was; then the good one, after which it must have that operation more, and sometimes again. #identity with no handle on both firehoses. checkAccountStatus, activateAccount, and the third PDS's deactivateAccount; #account, #identity with the handle and #sync on both. getSession, describeRepo, resolveHandle, a write, its #commit, and each side's getRepo verified against the key its DID document names. Sometimes then updateHandle to an external handle of another DID, refused, and to one of the account's, by DNS or HTTPS, with its #identity. Sometimes an import into the account once active: the server's #sync, and the reference's nothing.
  • Out. An account on both sides, alike, with records and blobs. getServiceAuth for createAccount with the third PDS's DID as aud; with another such token from each side, the third PDS makes the account, which must succeed for the server's token as for the reference's. requestPlcOperationSignature with, each drawn, no token, an app password's, a body, and the account with no email, then good, the emails compared as EMAIL.md says. signPlcOperation with, each drawn, no token, no token, an empty one, a wrong one, rotationKeys not a list, services not an object, and an app password's token; then good, the token sometimes in lower case, with a drawn subset of the fields the third PDS's getRecommendedDidCredentials answers. Each side's operation must be the update above: prev the CID of the DID's last operation, each field the input's or the last operation's, signed with the side's rotation key; the two sides' are compared with their keys and URLs named alike and the KEM key taken out (PDS.md). Sometimes the token again, 400 InvalidToken; and the directory's log as it was. With every field given, the third PDS then takes the move whole, each step of which must succeed for the server as for the reference: importRepo of the side's getRepo, each blob listMissingBlobs names from the side's getBlob, submitPlcOperation of the side's operation, and activateAccount. Then on both sides deactivateAccount, getRepoStatus, describeRepo, checkAccountStatus, and getRepo with the account's token.
  • States. An account on both sides deactivated, taken down by the admin, and deleted by its emailed token, each having signed an operation before; then importRepo, listMissingBlobs, requestPlcOperationSignature, signPlcOperation with the token mailed, and submitPlcOperation not of the form, and for the deleted the operation signed before; with its password session's token, and taken down, its com.atproto.takendown one's too.
  • A did:web account. For each side a did:web of the harness's own, did:web:localhost%3A<port>, its document served on that port and changed as the owner changes it (the reference made to read it again each time). createAccount with, each drawn, no token, a token signed by a key its document does not name, and its document not found; then with a token the harness signs, its didDoc held to the document served. getSession, checkAccountStatus, describeRepo; importRepo of a repository the harness builds and signs with the DID's key; nothing on either firehose. getRecommendedDidCredentials, requestPlcOperationSignature with its email, signPlcOperation with the token mailed; the server alone held to submitPlcOperation's 400 ("Where the reference departs"). activateAccount while the document names the old server; the document pointed at the side, with the recommended key; checkAccountStatus, activateAccount, its #account, #identity and #sync; describeRepo, a write and its #commit, getRepo verified against the recommended key. updateHandle to a handle the document does not name, refused with no event; the document changed, updateHandle again, its #identity, describeRepo and resolveHandle by the new handle; the directory holding nothing of the DID. Sometimes then the document gone: describeRepo, checkAccountStatus, activateAccount.

Not compared: the recordUri of a blob more than one record references; a directory that cannot be reached, as the harness's is always up; a did:web whose host does not answer, or answers with what is no document of it; and an MST node reached twice or a tree that is not the one its records make, which the harness does not build.