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

Accounts

The server holds any number of accounts. Each has a DID, a did:plc the server makes or a did:web the account moves in with (MIGRATION.md), a handle, an email, an optional password, its own signing key, its own KEM key (SPACES.md), and its own repository. Each account's data is kept apart from every other's: what one account's writes, recovery or storage touch is that account's alone.

Environment

Besides PDS_PORT and PDS_DATA_DIR (PDS.md):

VariableIs
PDS_HOSTNAMEthe server's hostname; the server's DID is did:web:<hostname>
PDS_PUBLIC_URLthe URL its DID documents name as the account's PDS
PDS_HANDLE_DOMAINSthe domains handles may end in, comma-separated, each with its leading dot, such as .test
PDS_PLC_URLthe PLC directory it registers DIDs with
PDS_PLC_ROTATION_KEY_HEXits secp256k1 PLC rotation key, 32 bytes as hex
PDS_RECOVERY_DID_KEYoptional: a did:key listed before the server's own as a rotation key of every DID it creates

describeServer answers did, availableUserDomains (the handle domains in the order given), inviteCodeRequired, as PDS_INVITE_REQUIRED sets it (LIMITS.md), and spacesAlpha: true (SPACES.md). The reference also answers links and contact from its own configuration; the server may leave them out, and the harness does not compare them.

createAccount

createAccount takes an optional bearer token, a service token by which an account moves here from another server, checked before anything else as MIGRATION.md says. It checks its input in this order and answers the first error:

  1. The input against the lexicon: a handle that is not a handle by atproto/handle.md is 400 InvalidRequest, and so is any other lexicon error. Then a plcOp given is 400 InvalidRequest: the server takes no operation made elsewhere.

  2. A password longer than 256 UTF-16 code units, as JavaScript counts a string's length (a character beyond U+FFFF counts two), is 400 InvalidRequest. None is allowed, and an empty one is the same as none: an account without a password exists, but no createSession logs into it, and it keeps no email. Its email is not taken by it, no createSession finds it by that email, and its sessions' answers leave email out. Its email must still pass the checks below, and must not be one another account has.

  3. A missing email is 400 InvalidRequest, and so is one that is not an address of this form. Emails are compared and kept in lower case.

    • A local part, @, and a domain, with no spaces or quotes anywhere.
    • The local part is at most 64 characters: dot-separated runs of letters (any script), digits and !#$%&'*+/=?^_`{|}~-, with no dot first, last, or next to another.
    • The domain is two or more dot-separated labels, with no dot last: each 1 to 63 letters (any script), digits or hyphens, not starting with a hyphen. The last label is not all digits, so an IP address is no domain, and neither is [1.2.3.4].

    The reference also refuses addresses at disposable-mail domains, from a list it keeps. The server need not, and the harness sends none.

  4. The handle, lowercased:

    • a top-level domain that atproto/handle.md disallows, such as .example, is 400 InvalidHandle;
    • a handle not ending in one of PDS_HANDLE_DOMAINS is 400 UnsupportedDomain. Where it ends in more than one, the longest is its domain. With did given, such a handle is instead an external one, which must resolve to that DID (IDENTITY.md, "Resolving a handle"), else it is 400 InvalidRequest; the rules below do not apply to it;
    • the part before that domain must be one label, of 3 to 18 characters. A dot in it, then a length outside that range, is 400 InvalidHandle;
    • a label in data/reserved-handles.txt is 400 HandleNotAvailable.
  5. A handle another account has is 400 InvalidRequest, then an email another account has is 400 InvalidRequest, both compared in lower case.

  6. did given, other than the token's (MIGRATION.md), or with no token, is 401 AuthenticationRequired; then a did that is neither a did:plc nor a did:web (MIGRATION.md) is 400 InvalidRequest, and one an account here has, in any state but deleted, 400 AlreadyExists.

  7. An inviteCode given, not empty, that is not an available code is 400 InvalidInviteCode. With PDS_INVITE_REQUIRED, the code is checked earlier instead, as LIMITS.md says.

An account made with did moves here from another server, and is made otherwise than below: MIGRATION.md says how.

Two createAccounts at once with the same handle or email create one account at most. Rate limits, the request's size, and the free space on disk may refuse it first (LIMITS.md).

The server then creates the account (if anything below fails, such as the PLC directory refusing the operation, no account is made, and the answer is 500 InternalServerError):

  • a new secp256k1 signing key, which signs every commit of its repository;
  • a new P-256 KEM key (SPACES.md);
  • a did:plc, by the genesis operation atproto/did-plc.md describes, posted to PDS_PLC_URL. It has:
    • verificationMethods.atproto, the signing key's did:key, and verificationMethods.atproto_kem, the KEM key's;
    • rotationKeys, PDS_RECOVERY_DID_KEY if set, then the rotation key's did:key;
    • alsoKnownAs, ["at://<handle>"];
    • services.atproto_pds, {type: "AtprotoPersonalDataServer", endpoint: PDS_PUBLIC_URL}.
  • an empty repository, with its first commit.

It answers {handle, did, didDoc, accessJwt, refreshJwt}, where didDoc is the DID document the directory serves for the DID. On the firehose it is #identity with the handle, #account with active: true, a #commit of the empty repository, then #sync, numbered after every event before them.

Sessions

createSession takes as identifier a handle, an email, or a DID, with handles and emails compared in lower case. A wrong password, or an identifier no account has, is 401 AuthenticationRequired, no sooner than 350 ms after the input was checked, as a success is (LIMITS.md). The session and its tokens are the account's. getSession answers {did, handle, email, emailConfirmed, emailAuthFactor, active: true}, and createSession the same with accessJwt and refreshJwt, without didDoc: emailConfirmed and emailAuthFactor are false until EMAIL.md changes them, which also says what createSession's authFactorToken does. For an account created without a password, email is left out of both. An account that is not active answers active: false and its status instead (LIFECYCLE.md). What the tokens are, refreshing and ending a session, and app passwords, which createSession also takes, are in SESSIONS.md.

Writes to another account

A write names its repository by repo. After the token and the input are checked, a repo no account here has is 403 AccountNotFound, and one that another account here has is 401 AuthenticationRequired, whatever else is wrong with the write.

Queries

describeRepo, getRecord, listRecords, getRepo and getLatestCommit answer any account's repository, by handle or DID. A handle in repo is matched as it is given, not lowercased: as every handle here is lower case, one with a capital letter names no account here.

Data

This section is informative.

data/reserved-handles.txt is from @atproto/pds, MIT licensed, and atproto/did-plc.md from did-method-plc, MIT or Apache-2.0. The server may refuse other handles it finds offensive; nothing checks that.