# Email What the server does with an account's email: confirming it, changing it, resetting the password by it, and signing in with a code sent to it; the tokens it mails for each; and the mailer that sends them. What every method shares, and how the server is checked, is in [`PDS.md`](PDS.md); accounts, their emails and passwords are as [`ACCOUNTS.md`](ACCOUNTS.md) says, and sessions as [`SESSIONS.md`](SESSIONS.md) says. The methods: `com.atproto.server.requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`, `updateEmail`, `requestPasswordReset` and `resetPassword`; and of `createSession`, its `authFactorToken`. What a deactivated, taken-down or deleted account's calls of them answer is in [`LIFECYCLE.md`](LIFECYCLE.md) ("Its own calls"). ## The account's email An account created with a password keeps its email, in lower case, and two facts about it, both `false` when the account is made: - **confirmed**: whether its owner has shown they read mail sent to it (`confirmEmail`). Changing the email makes it unconfirmed again, even to the same address. - **the email factor**: whether signing in with the account's password also needs a code mailed to the email (below). Only a confirmed email may have it, and changing the email turns it off. `getSession`, `createSession` and `refreshSession` answer them as `emailConfirmed` and `emailAuthFactor`. An account created without a password keeps no email (`ACCOUNTS.md`): both are `false`, and it can have neither. ## Tokens Each email the server sends for an account carries a token, which the account's owner gives back to the server to show they read it: - **Form.** Two groups of five characters, each an upper case letter or a digit 2 to 7, joined by `-`, as `AB2CD-EF7GH`: ten characters of base32 (RFC 4648's alphabet), from at least 50 random bits. - **Purpose.** Each token is for one purpose, and works for that alone: `confirm_email` (`confirmEmail`), `update_email` (`updateEmail`, both to change the email and to turn the email factor off), `reset_password` (`resetPassword`), and `auth_factor` (`createSession`'s `authFactorToken`). `LIFECYCLE.md` adds `delete_account`, and `MIGRATION.md` `plc_operation` (`signPlcOperation`). - **One at a time.** An account has at most one token of each purpose. Making one replaces the account's earlier token of that purpose, which then no longer works. - **Matching.** A token given is matched without regard to case, so `ab2cd-ef7gh` is `AB2CD-EF7GH`; otherwise exactly: without its `-`, or with spaces around it, it is wrong. - **Lifetime.** A token works for 15 minutes from when it was made. Given after that, it is `400 ExpiredToken`, and stays so until it is replaced or used up; a token that is not the account's of that purpose at all is `400 InvalidToken`. Both before anything else the method would change. - **Used once.** A token that does what it was for is used up: given again, it is `400 InvalidToken`. Of several calls at once with one token, one succeeds. A call refused for another reason, after its token was found good, leaves the token as it was. - **Changing the email** (`updateEmail`) ends every token the account has, of every purpose, `LIFECYCLE.md`'s too. An empty token, `""`, is the same as none where a token is optional (`updateEmail`, `createSession`), and a wrong one where it is required. The reference does one thing here that the server does not copy: several `resetPassword` calls at once with one token all succeed there, each setting the password. ## requestEmailConfirmation A procedure with no input, called by `POST` with an access token of the account, of any scope (an app password's session's too). It checks, in this order: 1. The token, as `SESSIONS.md` says: none is `401 AuthMissing`, one the server did not give out, or a refresh token, `400 InvalidToken`. 2. A request body is `400 InvalidRequest`. 3. An account created without a password, which keeps no email, is `400 InvalidRequest`. It then makes a `confirm_email` token, mails it to the account's email (kind `confirmEmail`, below), and answers `200` with an empty body. It does so whether or not the email is confirmed already. ## confirmEmail `confirmEmail` `{email, token}` is called with an access token of the account, of any scope. It checks, in this order: 1. The token, as above. 2. The input against the lexicon: `email` or `token` missing, or not a string, is `400 InvalidRequest`. 3. An `email` that, lowercased, is not the account's email is `400 InvalidEmail`; so is any `email` for an account without a password. 4. A `token` that is not the account's `confirm_email` token is `400 InvalidToken`, and one past its 15 minutes `400 ExpiredToken`. It then marks the email confirmed, uses the token up, and answers `200` with an empty body. Confirming an email that is confirmed already is allowed, and changes nothing else. ## requestEmailUpdate A procedure with no input, called by `POST`. Only a session of scope `com.atproto.access`, made with the account's own password, may call it: an app password's session, privileged or not, is `400 InvalidToken`. Then a request body is `400 InvalidRequest`, and an account without a password `400 InvalidRequest`. - If the account's email is confirmed, it makes an `update_email` token, mails it to the account's email as it is now (kind `updateEmail`), and answers `{tokenRequired: true}`. - If not, it makes no token, sends nothing, and answers `{tokenRequired: false}`. ## updateEmail `updateEmail` `{email, emailAuthFactor?, token?}` changes the account's email, or turns its email factor on or off. Like `requestEmailUpdate`, only a session of scope `com.atproto.access` may call it: an app password's session is `400 InvalidToken`. Then the input against the lexicon: `email` missing, or a field of the wrong type, is `400 InvalidRequest`. `email` is lowercased, and then: 1. **`emailAuthFactor: true`.** If the account's email is confirmed and is `email`, the factor is turned on (if it was not), and the call answers `200` with an empty body: the email does not change, and `token` is not looked at. Otherwise it is `400 InvalidRequest`. 2. **`emailAuthFactor: false`, with `email` the account's email.** If the factor is off, the call answers `200` and changes nothing. If it is on: - with no `token`, the server makes an `update_email` token, mails it to the email (kind `updateEmail`), and answers `400 TokenRequired`; - with one, it must be the account's `update_email` token (`400 InvalidToken`, `400 ExpiredToken`); the factor is turned off, the token used up, and the call answers `200`. The email does not change, and stays confirmed. 3. **Otherwise** (no `emailAuthFactor`, or `false` with another address), the email changes, after these checks: 1. `email` must be an address as step 3 of `createAccount` says (`ACCOUNTS.md`): one that is not is `400 InvalidRequest`. The reference also refuses disposable-mail domains; the server need not, and the harness sends none. 2. A `token`, if given, must be the account's `update_email` token (`400 InvalidToken`, `400 ExpiredToken`), whether or not one is needed. With none, an account whose email is confirmed is `400 TokenRequired`. 3. For an account without a password, the call answers `200` and changes nothing: it still keeps no email. That holds for an email another account has, too. 4. An email another account has is `400 InvalidRequest`, and leaves the token as it was. An account without a password keeps no email, so its email is no other account's. The account's email is then `email`, unconfirmed, with the email factor off; every token the account has is ended; and the call answers `200` with an empty body. That holds when `email` is the address it had: it is unconfirmed again. Nothing is mailed to the new address, nor to the old. So, when the email is confirmed, changing it takes two calls: one to `requestEmailUpdate`, and one to `updateEmail` with the token mailed to the old address. When it is not, `updateEmail` alone changes it. ## The email factor and createSession `createSession` (`ACCOUNTS.md`) takes an optional `authFactorToken`. After it has found the account and checked the password, so that a wrong one is still `401 AuthenticationRequired`: - With an `authFactorToken`, it must be the account's `auth_factor` token (`400 InvalidToken`, `400 ExpiredToken`), whether or not the factor is on, and whether the password is the account's or an app password's. It is used up, and the session made. - With none, if the account's email factor is on and the password is the account's own, the server makes an `auth_factor` token, mails it to the account's email (kind `signInAuthFactor`), and answers `401 AuthFactorTokenRequired`, making no session. An app password needs no code. ## requestPasswordReset `requestPasswordReset` `{email}` takes no token, and ignores one, even one the server did not give out. `email` missing or not a string is `400 InvalidRequest`. The email is lowercased; if no account with a password has it (an account without a password keeps none, and a string that is not an address is no account's), it is `400 InvalidRequest`. Otherwise the server makes a `reset_password` token for that account, mails it to the account's email (kind `resetPassword`), and answers `200` with an empty body. ## resetPassword `resetPassword` `{token, password}` takes no token, and ignores one. It checks, in this order: 1. The input against the lexicon: `token` or `password` missing, or not a string, is `400 InvalidRequest`. 2. A `password` longer than 256 UTF-16 code units, as `createAccount` counts it (`ACCOUNTS.md`), is `400 InvalidRequest`. 3. The token names its account: one that is no account's `reset_password` token is `400 InvalidToken`, and one past its 15 minutes `400 ExpiredToken`. The account's password is then `password`, hashed as `LIMITS.md` says ("Passwords"), and the token used up. The empty password is allowed here: `createSession` with `""` then logs in. Every session the account has is ended, those made with its app passwords too, as `deleteSession` ends one (`SESSIONS.md`): their refresh tokens are `400 ExpiredToken` from then on, and their access tokens work until they expire. Every OAuth session of the account ends too, as a takedown ends them (`LIFECYCLE.md`): their access tokens are `401 invalid_token` at once, and their refresh tokens `400 invalid_grant`. Every request approved for it whose code was not yet exchanged is ended, its code refused `400 invalid_grant`, and the account is signed out of every device it was signed in on (`OAUTH.md`, "Devices"). Every passkey of the account is removed, and its link to add one ended (`PASSKEYS.md`, "The account's states"). *Note:* a password reset is how an account is taken back from whoever had its password, and none of these may be left to them. The reference ends only the sessions above (below, "What the reference does that the server does not copy"). Its app passwords stay, and still log in. Its email, whether it is confirmed, its email factor, and its tokens of other purposes are as they were. It answers `200` with an empty body. ## The mailer Every email the server sends goes through one mailer, as one of these kinds, each with its token: | Kind | Sent by | Token's purpose | Subject | | --- | --- | --- | --- | | `confirmEmail` | `requestEmailConfirmation` | `confirm_email` | Email Confirmation | | `updateEmail` | `requestEmailUpdate`; `updateEmail` turning the factor off | `update_email` | Email Update Requested | | `resetPassword` | `requestPasswordReset` | `reset_password` | Password Reset Requested | | `signInAuthFactor` | `createSession` | `auth_factor` | Sign-in Confirmation | | `deleteAccount` | `requestAccountDelete` (`LIFECYCLE.md`) | `delete_account` | Account Deletion Requested | | `plcOperation` | `requestPlcOperationSignature` (`MIGRATION.md`) | `plc_operation` | PLC Update Operation Requested | No other method sends email: not `createAccount`, nor `updateEmail` when it changes the email. ### SMTP | Variable | Is | | --- | --- | | `PDS_EMAIL_SMTP_URL` | the SMTP server to send through: `smtp://[user:password@]host[:port]`, upgraded with STARTTLS when the server offers it, or `smtps://...` for TLS from the start; user and password percent-encoded | | `PDS_EMAIL_FROM` | the address each email is from | Both are set, or neither: one without the other makes `pds serve` exit 1, with `pds: ` and why on standard error. With both, each email is sent to the account's email, from `PDS_EMAIL_FROM`, with its kind's subject, as "The message" says. With neither, nothing is sent, and every method answers as if it had been. A token is kept before its email is sent. If sending fails, the method answers `500 InternalServerError`, and the token works all the same. ### The message Each email is one `multipart/alternative` message of two parts, in this order: 1. `text/plain; charset=utf-8`: a body that gives the token; the server may choose the rest of it. 2. `text/html; charset=utf-8`: the same email in the authorization pages' look (`OAUTH-PAGES.md`), from one template built with them in `web/` (`web/dist/email.html`), its styles written on its elements, as mail clients read them. It holds, as text: the server's host (`PDS_HOSTNAME`), the kind's heading below, the token, and that it works for 15 minutes, once; the server may choose the rest. | Kind | Heading | | --- | --- | | `confirmEmail` | Confirm your email | | `updateEmail` | Change your email | | `resetPassword` | Reset your password | | `signInAuthFactor` | Your sign-in code | | `deleteAccount` | Delete your account | | `plcOperation` | Confirm a change to your account | Nothing in the HTML part comes from the account or its request: no address, handle or name, so no text a person chose is drawn in the server's look. Every value the server puts in the template is escaped as HTML text. The part loads nothing: no image, stylesheet or font from anywhere, so opening it tells no one it was opened; a client that has the pages' typefaces draws them, and any other its own. ### The development sink | Variable | Is | | --- | --- | | `PDS_DEV_MAIL_DIR` | optional: a directory each email is also written to, for tests | With `PDS_DEV_MAIL_DIR` set, each email, sent through SMTP or not, is also written to that directory as a file of its own, before any SMTP sending, and before the method that sends it answers: - its content is JSON, `{"to":
, "kind": , "token": }`, the address as the account keeps it, in lower case; - it is written under a name starting with `.`, and renamed into place, to `.json`; - each name sorts after every earlier one's in that directory, also after a restart: the time in nanoseconds since the epoch, as 20 digits, `-`, and a counter, does. The server does not read the directory, nor remove what it wrote. Unset, it writes nothing anywhere. *Note:* it is for the harness, and for development: an operator leaves it unset. ## 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": when a call costs points, windows, the client address, the headers and the `429`. Each also costs one point of `global`. Each limit is the method's own: the two `requestEmail*` methods do not share theirs. In the table's order, as `LIMITS.md` uses it for the headers and the `429` (the day's limit before the hour's, as `login, day` comes before `login`): | Limit | Methods | Key | Points | Window | | --- | --- | --- | --- | --- | | email confirmation, day | `requestEmailConfirmation` | the token's DID | 15 | 86400 s | | email confirmation, hour | `requestEmailConfirmation` | the token's DID | 5 | 3600 s | | email update, day | `requestEmailUpdate` | the token's DID | 15 | 86400 s | | email update, hour | `requestEmailUpdate` | the token's DID | 5 | 3600 s | | password reset, day | `requestPasswordReset` | client address | 50 | 86400 s | | password reset, hour | `requestPasswordReset` | client address | 15 | 3600 s | | reset | `resetPassword` | client address | 50 | 300 s | `confirmEmail` and `updateEmail` have only `global`. A `requestPasswordReset` for an email no account has costs its points as one that finds one does. ## Durability As `DURABILITY.md` says of every answered write: a token the server answered for, a confirmation, a changed email, the email factor turned on or off, a token used up, and a reset password, with the sessions, requests and device sign-ins it ended, all survive the server being killed. A token keeps its 15 minutes across a restart. ## What the reference does that the server does not copy - **What a password reset leaves.** The reference ends only the account's password and app password sessions: its OAuth sessions still answer `getSession` and refresh, a code approved before is exchanged, and the devices it was signed in on still list it (probed). The server ends them all, as `resetPassword` says. ## How it is checked `harness/compare.mjs` starts the server with `PDS_DEV_MAIL_DIR`, an empty directory of its own, and catches the reference's emails in its process, as its mailer is about to send them. After each call, it takes the emails each side sent during it, in order, and compares them by `to` and `kind`; each token must be of the form above. The harness then uses each side's own tokens. Before each step of this page it also takes the emails sent since the last, and compares them the same way, so that no other method sends one where the reference does not. Each step picks an account, and keeps the tokens each side mailed it, by purpose, current or replaced, to give back later, maybe after a crash: - **requestEmailConfirmation** with the account's access token, none, its refresh token, or one never given out. - **confirmEmail** with the account's email, in mixed case, another account's, or none of the input; and its current `confirm_email` token, an earlier one, the current one in lower case, a token of another purpose, one never made, or `""`. Then `getSession`, compared. - **requestEmailUpdate**, and **updateEmail** to a new address (at the edges of what `createAccount` takes too), the same address, in mixed case, another account's, one only an account without a password had, or one that is not an address; with no token, the current `update_email` token, an earlier one, the current one in lower case, another purpose's, one never made, or `""`; sometimes with `emailAuthFactor: false`, and with `emailAuthFactor: true` and another address. Then `getSession`, compared, and `createSession` by the new email. - **the email factor**, in one step: `updateEmail` turning it on, for an account confirmed or not; `createSession` with the password and no code, with a code replaced since, one never made, another purpose's, with an app password, and with the code, once and again; then `updateEmail` turning it off, without a token, with a wrong one, and with the one mailed. The factor is off again when the step ends, so that the other steps' `createSession`s are not asked for codes. - **requestPasswordReset** by the account's email in mixed case, an email no account has, an account's without a password, or a string that is no address; and **resetPassword** with the current token, an earlier one, the current one in lower case, another account's (which resets that account's password), another purpose's, or one never made; a new password, one of 256 UTF-16 units, one over, or `""` (then set again by a second reset in the same step). Then `createSession` with the old and the new password, and `refreshSession` with a session's refresh token from before, all compared. Sometimes, before the reset, the account signs in through OAuth and has a request approved; after it, held to this page on the server alone: `getSession` with each of its OAuth sessions (`401 invalid_token`), a refresh of each public client's (`400 invalid_grant`), the approved request's code (`400 invalid_grant`), and the page on each device it signed in on, which lists it no more. The harness then drops those sessions and devices on both sides. - **app passwords and these methods:** each of the four that take a token, called with an app password's session made for the step. - **SMTP refusing:** with the harness's SMTP sink refusing every message, `requestEmailConfirmation` or `requestPasswordReset`: where the reference answers `200`, the server `500 InternalServerError`, its email in the development sink all the same; then the token not delivered used, `confirmEmail` and `getSession`, or `resetPassword` and `createSession` with the old password and the new, compared. The server is also given `PDS_EMAIL_SMTP_URL`, the harness's SMTP sink on the loopback with a user and password to percent-decode, and `PDS_EMAIL_FROM`, and held to "SMTP" and "The message" on the server alone: every email the development sink takes arrives over SMTP once, logged in, from `PDS_EMAIL_FROM` in the envelope and `From:`, to the account's email in the envelope and `To:`, with its kind's subject; as `multipart/alternative` of a `text/plain` part and a `text/html` part, in that order, the token in each; the HTML part's text holding the server's host and the kind's heading, and no `src`, `href` or `url(` naming anything to load; and no message arrives that the development sink did not take. The end of every run starts the server with one of the two variables and not the other: it must exit 1, with `pds: ` and why on standard error. Accounts with a password change email and password as the reference's do, and the harness follows: other steps log in with the new password and email. Not compared: - `ExpiredToken` for a token past its 15 minutes: the harness does not wait 15 minutes. - The reference's subject, sender, body and HTML, and its SMTP: only the address it goes to, its kind, and its token's form. `smtps://` and STARTTLS: the sink offers neither. - Calls at once with one token: which wins is a race, and the reference lets several `resetPassword`s through. - Disposable-mail domains, which the reference refuses from its list. - The rate limits above in this run, which has them off on both sides: `LIMITS.md`'s `--limits` run checks them.