# Identity The `com.atproto.identity` methods the server serves, `resolveHandle`, `updateHandle` and `getRecommendedDidCredentials`; how it resolves a handle outside its own domains; the handle resolution it serves over HTTP, `GET /.well-known/atproto-did`; and what `describeRepo` says of an account's DID document. What every method shares, and how the server is checked, is in [`PDS.md`](PDS.md); accounts, their handles and their DIDs are as [`ACCOUNTS.md`](ACCOUNTS.md) says. `submitPlcOperation`, `requestPlcOperationSignature` and `signPlcOperation`, which move an account's DID to another server, are [`MIGRATION.md`](MIGRATION.md)'s. ## Environment | Variable | Is | Default | | --- | --- | --- | | `PDS_HANDLE_DNS_SERVER` | the DNS server asked for a handle's `_atproto` TXT records: an IPv4 or IPv6 address, with an optional port, as `127.0.0.1:5353` or `[::1]:5353` | unset: the system's resolver | | `PDS_HANDLE_FETCH` | for development and testing only: a base URL, `http://` or `https://`, a host, an optional port and path, with no trailing `/`, from which every handle's `/.well-known/atproto-did` is fetched instead (below) | unset | A value that does not parse makes `pds serve` exit 1, with why on standard error. ## Resolving a handle A handle outside `PDS_HANDLE_DOMAINS` is an external one, which the server takes for an account only if it resolves to that account's DID: in `createAccount` with a `did` (`MIGRATION.md`) and in `updateHandle` (below). It resolves the handle, lowercased, as `atproto/handle.md` describes, both ways at once: - **DNS.** The TXT records of `_atproto.`, each record's strings joined, asked once and given 3 seconds. Of those starting `did=`, exactly one must be there; what follows `did=` is the DID. None, two or more, or a lookup that fails or takes longer, find none. - **HTTPS.** `GET https:///.well-known/atproto-did`, following up to 10 redirects, each through the same guard, given 3 seconds in all. A `200` whose body's first line, trimmed of white space, starts with `did:` finds that line; anything else, no answer in time included, finds none. Only the first 8192 bytes of the body are read, and a longer body is read no further, not refused; bytes that are not UTF-8 are read as U+FFFD. DNS's DID wins when it finds one; otherwise the HTTPS one. The handle resolves to the account's DID only if the DID found is that DID exactly. Nothing is kept: each check resolves the handle again, and an account's handle is not checked again once it is the account's. With `PDS_HANDLE_FETCH` set, the HTTPS fetch goes to `//.well-known/atproto-did` instead, as `PDS_OAUTH_CLIENT_FETCH` maps client documents (`OAUTH-CLIENTS.md`): through the same guard, so that a base on this machine or a private network is reached only with `PDS_DISABLE_SSRF_PROTECTION=true` as well. A server open to the internet must not set it. Each fetch is an outbound request of target `handle` (`OPERATIONS.md`); a DNS lookup is none. ## resolveHandle `resolveHandle` takes no token, and ignores one, even one the server did not give out. A `handle` that is missing, or is not a handle by `atproto/handle.md`, is `400 InvalidRequest`. Otherwise the handle is lowercased, and: - an active account's handle, in any case, answers `{did}`, the account's DID; one whose account is not active is as no account's (`LIFECYCLE.md`); - a handle ending in one of `PDS_HANDLE_DOMAINS` that is no account's is `400 HandleNotFound`: one no account has had, one an account had before it changed it, and one no account could have, such as `a.b.test` or `admin.test`; - any other handle is not the server's, unless it is an account's (above). The reference asks its AppView (`PROXY.md`), and answers `400 InvalidRequest` when that finds no DID. The server does not look it up, and answers `400 InvalidRequest` for every such handle, whatever its top-level domain. ## updateHandle `updateHandle` changes the handle of the token's account. It checks, in this order, and answers the first error: 1. The token: none is `401 AuthMissing`, and one the server did not give out `400 InvalidToken`, however wrong the input. A session made with an app password, privileged or not, may change the handle, as the reference's may (`SESSIONS.md`). Then the rate limits of `LIMITS.md` count it, after its input is checked. 2. The input against the lexicon: a `handle` that is missing, not a string, or not a handle by `atproto/handle.md` is `400 InvalidRequest`. Fields the lexicon does not name are ignored. 3. The handle, lowercased, as step 4 of `createAccount` checks it (`ACCOUNTS.md`), but for a handle outside the server's domains: - a top-level domain that `atproto/handle.md` disallows, such as `.example` or `.invalid`, is `400 InvalidHandle`; - a handle ending in one of `PDS_HANDLE_DOMAINS` must have one label of 3 to 18 characters before it: a dot in it, then a length outside that range, is `400 InvalidHandle`, and then a label in `data/reserved-handles.txt` is `400 HandleNotAvailable`; - a handle not ending in one of them is an external one: it must resolve to the account's DID ("Resolving a handle", above), else it is `400 InvalidRequest`. Its labels are not checked further. 4. A handle another account has, compared in lower case, is `400 HandleNotAvailable` (where `createAccount` answers `InvalidRequest`). A handle that passes is the account's, even when it is the handle the account has already: that is a change like any other, with its operation and its event. The server then: - for a `did:plc`, posts an update operation for the account's DID to `PDS_PLC_URL`, as `atproto/did-plc.md` describes. Its fields are those of the DID's last operation in the directory (as `GET //log/last` answers it), which may be one the server did not post, with `alsoKnownAs` changed and nothing else: its first `at://` entry becomes `at://`, or, with none, `at://` goes first. `prev` is the CID of that last operation, and it is signed with the server's rotation key (`PDS_PLC_ROTATION_KEY_HEX`). A `did:web` account posts none: its document must name the handle already, as `MIGRATION.md` ("A `did:web` account") says; - gives the account the handle, which frees the one it had: another account, or a new one, may take that at once; - sends `#identity` on the firehose, with the account's `did` and the new `handle`, numbered after every event before it. It answers `200` with no body. After it, every method that names an account by handle knows it by the new one (`describeRepo`, `getRecord`, `listRecords`, writes, `createSession`, `resolveHandle`, and `/.well-known/atproto-did`), and by the old one knows no account: `describeRepo` of it is `400 RepoNotFound`, a write naming it `403 AccountNotFound`. `getSession` and `createSession` answer the new handle. The account's sessions still hold. A refused change posts no operation, changes nothing, and sends no event. If the directory refuses the operation, the handle does not change, there is no event, and the answer is `400 InvalidRequest` with the directory's message; if the directory cannot be reached, `502 UpstreamFailure`. ### At once - Two `updateHandle`s of different accounts to the same handle at once, or an `updateHandle` and a `createAccount` of it, give it to one account at most. The server answers the other as if the handle were already taken: `400 HandleNotAvailable` for an `updateHandle`. The reference sometimes answers the loser `500 InternalServerError` instead, having already posted its operation, so that the loser's DID document names a handle another account has. That is a fault, and the server does not copy it: it posts no operation for a change it then refuses, and the document the directory serves for each of its DIDs names the account's handle. - Of two `updateHandle`s of one account at once, the reference refuses one when its directory refuses the second operation, built on the same last operation as the first: `400 InvalidRequest`. The server may instead make them one after the other. Whichever it does, the handle it ends with is the one the directory's document names. ### Crashes A handle change is kept as a write is (`DURABILITY.md`): one the server has answered survives it being killed at any moment after, both in the server and in the directory, which holds its operation. One it is killed during lands whole or not at all. Whole is the account with the new handle, the directory's log with the operation, and the `#identity` event; not at all is the account with its old handle and the directory's log without the operation. As the directory and the server are apart, the server records the operation, with the handle, before it posts it, and keeps the handle taken while it is in flight. An operation it recorded and had not finished when it stopped does not hold up its start: it serves at once, and settles the operation in the background, asking the directory for the DID's log until the directory answers. - Until it is settled, the account's handle is the old one everywhere: `getSession`, `describeRepo`, `resolveHandle` and `/.well-known/atproto-did` all answer it. The new handle stays taken, so no other account can have it. Another `updateHandle` of the account waits until it is settled, then goes on as any change does: while the directory cannot be reached, that is `502 UpstreamFailure`. - If the directory's log holds an operation with its CID, the directory accepted it, and the change lands: the account takes the handle, the old one is free, and `#identity` goes on the firehose, numbered after every event before it. - If not, the change is dropped: the new handle is free again, and nothing else changes. With the directory up, as the harness runs it, that is settled as the server starts, before or soon after its first answer. ## /.well-known/atproto-did `GET /.well-known/atproto-did` resolves the handle the request's `Host` header names, less any `:port`, as `atproto/handle.md`'s HTTPS method asks. The host is matched as it is given, not lowercased: as every handle here is lower case, one with a capital letter names no account here. An account's handle answers `200`, `Content-Type: text/plain; charset=utf-8`, with the account's DID as the whole body, with no newline. Any other host, including a handle an account had before, the server's own hostname, and an IP address, is `404`. ## getRecommendedDidCredentials `getRecommendedDidCredentials` needs the account's token: none is `401 AuthMissing`, and one the server did not give out `400 InvalidToken`. It answers what a DID document of the account on this server holds, as `createAccount`'s genesis operation would hold it now: - `alsoKnownAs`, `["at://"]`, the account's handle now, whatever the directory's document says; - `verificationMethods`, `{atproto: , atproto_kem: }` (`SPACES.md`); - `rotationKeys`, `PDS_RECOVERY_DID_KEY` if set, then the rotation key's `did:key`; - `services`, `{atproto_pds: {type: "AtprotoPersonalDataServer", endpoint: PDS_PUBLIC_URL}}`. ## describeRepo's didDoc and handleIsCorrect `describeRepo`'s `didDoc` is the document the directory serves for the DID now, or for a `did:web`, the document its host serves (`MIGRATION.md`, "A `did:web` account"): after a handle change, the one that names the new handle, and after an operation the server did not post, the one that operation made. `handleIsCorrect` is whether the first `at://` entry of the document's `alsoKnownAs` is `at://`, the account's handle, which for a `did:plc` account here is `true`, and for a `did:web` one whatever its owner's document says. A `did:web` document that cannot be read makes `describeRepo` `400 InvalidRequest`, as the reference answers. The reference keeps the DID documents it resolves for an hour, and its `describeRepo` answers the one it kept, so after a change it answers the document as it was, with `handleIsCorrect: false`. The server keeps them too, for `PDS_DID_CACHE_SECS`, so that `describeRepo` does not call the directory each time; but after an operation it posts, a handle change, it serves the document that operation made at once (`LIMITS.md`). An operation it did not post shows once what it kept is older than `PDS_DID_CACHE_SECS`; the harness's runs set it to 0, so that every `describeRepo` asks the directory, and the run of `LIMITS.md` checks the rest. ## How it is checked Every run serves handles to both sides from `harness/lib/handles.mjs`: a DNS server the server is given as `PDS_HANDLE_DNS_SERVER`, and an HTTP web it is given as `PDS_HANDLE_FETCH`, with `PDS_DISABLE_SSRF_PROTECTION=true` to reach it. The reference, which runs in the harness's process, asks the same two for every handle it resolves. Each answers only the handles a check gave it; every other handle resolves to nothing, both ways. `harness/checks/identity.mjs` holds the server to the reference, as `PDS.md` says, with each account's DID named alike on both sides: - `resolveHandle` of an account's handle in mixed case; of a handle under `.test` that no account has, that an account had before, or that none could have; of an external handle, under `example.com`, `example.net`, `example.org` or `.invalid`, which resolve to nothing; and of handles the lexicon refuses. Compared whole. - `updateHandle` to a new handle, to the account's own in mixed case, or to one another account had before; and with each fault of its checks, alone or with a missing or bad token, compared by status and `error`. External handles here are only those under `example.com`, `example.net` and `example.org`, which resolve to nothing; the migration run (`MIGRATION.md`) changes handles to external ones that resolve, by DNS or HTTPS, to the account's DID or another's. After each, on each side, the directory's log must have grown by one operation, or by none for a refused change, and that operation must be the update above: `prev` the CID of the one before, every field but `alsoKnownAs` the same, and its signature the side's rotation key's. Then `getSession`, `describeRepo` by the new handle and the old, `resolveHandle` of both, and `/.well-known/atproto-did` of both are compared. - Sometimes, before a change, the harness posts an operation of its own for the DID on each side, signed with that side's rotation key, that adds an `https://` entry to `alsoKnownAs`: the change must keep it, and build on that operation. - `/.well-known/atproto-did` with the `Host` of an account's handle, with a port, in mixed case, of a handle no account has, or of a host that is no handle. The status is compared, and for a `200`, the body, with DIDs named alike, and that the content type is `text/plain`. - `getRecommendedDidCredentials` with the account's token, none, or one never given out, compared with keys and URLs taken out; on each side `rotationKeys` must be the side's recovery and rotation keys, and `verificationMethods.atproto` the account's signing key. On the server, `verificationMethods.atproto_kem` must be the KEM key of the account's genesis operation; the `latest` reference has no KEM key, so that entry is held to this rule and taken out before the sides are compared (`PDS.md`). - Two accounts changing to the same new handle at once: as many changes land on each side, one, and on the server the other is `400 HandleNotAvailable`, and each account's handle is the one its DID document names. Which account wins may differ between the sides, so the harness then gives both accounts new handles, one after the other, on both. As that makes events the other side does not have, this is not sent with `--firehose`. With `--firehose`, each `#identity` event must carry the handle the account had been given by then, in order, and the server's events other than commits are compared with the reference's (`SYNC.md`). With `--crash-every`, the server is sometimes killed while a handle change is on its way. Once it serves again, the directory's log must be as it was, and then the server's handle must stay the old one; or have the update operation, and then the server must answer the new handle within 3 seconds. A change that landed is then made on the reference too, and its events compared. That the server starts and answers while the directory is down is not checked: the harness's directory is always up. As the reference keeps DID documents for an hour, the harness, which runs it in its own process, has it resolve a DID's document again after every change it makes to it, so that its `describeRepo` answers as the server's must. `handleIsCorrect` is then compared. Not compared: the body and content type of a `404` from `/.well-known/atproto-did`; the reference also answers that path with a trailing slash, in any case, and to `HEAD`, and takes the host from `X-Forwarded-Host` on a request from the loopback address, none of which a client resolving a handle sends. A directory that refuses an operation or cannot be reached, as the harness's directory takes every operation it is sent. Two changes of one account at once, which the reference answers by a race. An `updateHandle` and a `createAccount` of one handle at once, where which wins decides which accounts exist. The reference may refuse handles it finds offensive, and so may the server; the harness sends none.