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 The PDS: accounts and their records; accounts, their emails and passwords are as Accounts says, and sessions as Sessions 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
Account lifecycle (“Its own calls”).
The account’s email
Section titled “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): both are false, and it can have
neither.
Tokens
Section titled “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
-, asAB2CD-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), andauth_factor(createSession’sauthFactorToken). Account lifecycle addsdelete_account, and Moving an account between serversplc_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-ef7ghisAB2CD-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 is400 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, Account lifecycle’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
Section titled “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:
- The token, as Sessions says: none is
401 AuthMissing, one the server did not give out, or a refresh token,400 InvalidToken. - A request body is
400 InvalidRequest. - 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
Section titled “confirmEmail”confirmEmail {email, token} is called with an access token of the
account, of any scope. It checks, in this order:
- The token, as above.
- The input against the lexicon:
emailortokenmissing, or not a string, is400 InvalidRequest. - An
emailthat, lowercased, is not the account’s email is400 InvalidEmail; so is anyemailfor an account without a password. - A
tokenthat is not the account’sconfirm_emailtoken is400 InvalidToken, and one past its 15 minutes400 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
Section titled “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_emailtoken, mails it to the account’s email as it is now (kindupdateEmail), and answers{tokenRequired: true}. - If not, it makes no token, sends nothing, and answers
{tokenRequired: false}.
updateEmail
Section titled “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:
-
emailAuthFactor: true. If the account’s email is confirmed and isemail, the factor is turned on (if it was not), and the call answers200with an empty body: the email does not change, andtokenis not looked at. Otherwise it is400 InvalidRequest. -
emailAuthFactor: false, withemailthe account’s email. If the factor is off, the call answers200and changes nothing. If it is on:- with no
token, the server makes anupdate_emailtoken, mails it to the email (kindupdateEmail), and answers400 TokenRequired; - with one, it must be the account’s
update_emailtoken (400 InvalidToken,400 ExpiredToken); the factor is turned off, the token used up, and the call answers200. The email does not change, and stays confirmed.
- with no
-
Otherwise (no
emailAuthFactor, orfalsewith another address), the email changes, after these checks:emailmust be an address as step 3 ofcreateAccountsays (Accounts): one that is not is400 InvalidRequest. The reference also refuses disposable-mail domains; the server need not, and the harness sends none.- A
token, if given, must be the account’supdate_emailtoken (400 InvalidToken,400 ExpiredToken), whether or not one is needed. With none, an account whose email is confirmed is400 TokenRequired. - For an account without a password, the call answers
200and changes nothing: it still keeps no email. That holds for an email another account has, too. - 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 answers200with an empty body. That holds whenemailis 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
Section titled “The email factor and createSession”createSession (Accounts) 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’sauth_factortoken (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_factortoken, mails it to the account’s email (kindsignInAuthFactor), and answers401 AuthFactorTokenRequired, making no session. An app password needs no code.
requestPasswordReset
Section titled “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
Section titled “resetPassword”resetPassword {token, password} takes no token, and ignores one. It
checks, in this order:
- The input against the lexicon:
tokenorpasswordmissing, or not a string, is400 InvalidRequest. - A
passwordlonger than 256 UTF-16 code units, ascreateAccountcounts it (Accounts), is400 InvalidRequest. - The token names its account: one that is no account’s
reset_passwordtoken is400 InvalidToken, and one past its 15 minutes400 ExpiredToken.
The account’s password is then password, hashed as Limits 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): 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
(Account lifecycle): 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: the authorization server, “Devices”). Every passkey of the account is
removed, and its link to add one ended (Passkeys, “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
Section titled “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 (Account lifecycle) | delete_account | Account Deletion Requested |
plcOperation | requestPlcOperationSignature (Moving an account between servers) | plc_operation | PLC Update Operation Requested |
No other method sends email: not createAccount, nor updateEmail when it
changes the email.
| Variable | Description |
|---|---|
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
Section titled “The message”Each email is one multipart/alternative message of two parts, in this
order:
text/plain; charset=utf-8: a body that gives the token; the server may choose the rest of it.text/html; charset=utf-8: the same email in the authorization pages’ look (OAuth: what the authorization pages show), from one template built with them inweb/(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
Section titled “The development sink”| Variable | Description |
|---|---|
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": <address>, "kind": <kind>, "token": <token>}, the address as the account keeps it, in lower case; - it is written under a name starting with
., and renamed into place, to<name>.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
Section titled “Rate limits”With PDS_RATE_LIMITS_ENABLED (Limits), these methods have limits of
their own, by the rules of Limits’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 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
Section titled “Durability”As Durability 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
Section titled “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
getSessionand refresh, a code approved before is exchanged, and the devices it was signed in on still list it (probed). The server ends them all, asresetPasswordsays.
How it is checked
Section titled “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_emailtoken, an earlier one, the current one in lower case, a token of another purpose, one never made, or"". ThengetSession, compared. - requestEmailUpdate, and updateEmail to a new address (at the
edges of what
createAccounttakes 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 currentupdate_emailtoken, an earlier one, the current one in lower case, another purpose’s, one never made, or""; sometimes withemailAuthFactor: false, and withemailAuthFactor: trueand another address. ThengetSession, compared, andcreateSessionby the new email. - the email factor, in one step:
updateEmailturning it on, for an account confirmed or not;createSessionwith 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; thenupdateEmailturning 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’createSessions 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). ThencreateSessionwith the old and the new password, andrefreshSessionwith 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:getSessionwith 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,
requestEmailConfirmationorrequestPasswordReset: where the reference answers200, the server500 InternalServerError, its email in the development sink all the same; then the token not delivered used,confirmEmailandgetSession, orresetPasswordandcreateSessionwith 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:
ExpiredTokenfor 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
resetPasswords 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’s
--limitsrun checks them.