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

Sessions

A session is a pair of tokens: an access token, sent as the bearer token of every call made for the account, and a refresh token, which makes new pairs and ends the session. createAccount and createSession start sessions (ACCOUNTS.md); this page says what the tokens are, how a session is refreshed and ended, and app passwords. What every method shares, and how the server is checked, is in PDS.md.

The methods: com.atproto.server.refreshSession, deleteSession, createAppPassword, listAppPasswords and revokeAppPassword.

Tokens

Both tokens are JWTs (RFC 7519), signed with a key only the server holds, and carry exactly these claims:

Access tokenRefresh token
header typat+jwtrefresh+jwt
scopethe session's scope, belowcom.atproto.refresh
subthe account's DIDthe account's DID
audthe server's DID, did:web:<PDS_HOSTNAME>the same
jtinonethe session's id
iatwhen it was made, in seconds since the epochthe same
expiat + 7200 (two hours)iat + 7776000 (90 days)

The server may choose the header's alg; the reference signs with HS256. A session's scope is com.atproto.access for a session made with the account's password, com.atproto.appPass for one made with an app password, and com.atproto.appPassPrivileged for one made with a privileged app password (and com.atproto.takendown for one a taken-down account made, LIFECYCLE.md). A refresh token's jti is a string the server makes, the same for every refresh token of one session (below), and different between sessions.

Note: clients read the tokens: Bluesky's app decodes the access token to read its exp, to know when to refresh, and its scope, to know an app password's session.

Which token where

Every method that takes a token, other than refreshSession and deleteSession, takes an access token; those two take a refresh token. The server checks the token before the input, as PDS.md says of writes. A bearer token is refused with 400 InvalidToken when:

  • it is not a JWT the server signed, including one whose claims were changed after it was signed, and one whose header says alg: none;
  • it is a refresh token sent where an access token is wanted, or an access token sent to refreshSession or deleteSession.

An access token is not checked against any session: it works until its exp, whatever happens to the session it came from. It still works after deleteSession ends that session, after refreshSession replaces it, and after the app password it was made with is revoked. A token past its exp is 400 ExpiredToken, but one of the wrong kind for the method is 400 InvalidToken first, expired or not. deleteSession takes a refresh token past its exp all the same, and ends its session.

The Authorization header's scheme is matched without regard to case (bearer is Bearer). A header that is not two words separated by one space, or whose scheme is not Bearer, Basic or DPoP, is 400 InvalidToken. refreshSession and deleteSession take only Bearer: a Basic header is 401 AuthMissing there, as if there were none, and so is a DPoP header. Elsewhere a Basic header is 400 InvalidToken. DPoP is OAuth's: every method that takes a token takes an OAuth access token with it (OAUTH-SCOPES.md).

refreshSession

refreshSession is a procedure with no input, called by POST with the refresh token as the bearer token. A request body is 400 InvalidRequest, after the token is checked. It answers what createSession answers for the account (ACCOUNTS.md): {accessJwt, refreshJwt, did, handle, email, emailConfirmed, emailAuthFactor, active: true} (EMAIL.md), with no didDoc, and without email for an account created without a password. The new tokens have the session's scope: a session made with an app password stays one.

The server keeps each session it gave out: its account, the app password it was made with if any, when it expires, and its successor, none at first. A refresh token whose session the server does not keep, as after deleteSession, or once the server dropped it as expired or past the account's 100 sessions (LIMITS.md), is 400 ExpiredToken. Refreshing with session S's token:

  1. If S has no successor, the server makes a new session id N, and S's successor is N. If it has one, that is N.

  2. S now expires two hours from now, or when it did, whichever is sooner: the old refresh token keeps working for two hours after it is first used.

    Note: so two clients that share a refresh token may both refresh.

  3. A session N is kept, with S's account and app password, expiring 90 days from now, unless one with that id is kept already.

  4. It answers a new access token and a refresh token whose jti is N.

So refreshing with the same token again within those two hours answers a refresh token of the same session as the first time, and with the newest token, a new one. Refreshes at once with the same token all succeed, and all answer tokens of the same session. Where step 3 finds N gone, because deleteSession ended it, it is kept again: the old token's grace brings it back.

deleteSession

deleteSession is a procedure with no input and no output, called by POST with the refresh token as the bearer token. A request body is 400 InvalidRequest, after the token is checked. The server stops keeping the session the token's jti names, and answers 200 with an empty body, whether or not it kept it. It ends that session alone: its successor, if it has one, and every other session carry on, and its access tokens work until they expire.

App passwords

An app password is a password for logging in to one account, with a name, made by the account itself, and revocable on its own. Each is kept with its name, a hash of it, when it was made, and whether it is privileged.

  • createAppPassword {name, privileged?} makes one, and answers {name, password, createdAt, privileged}: privileged is false unless given true; createdAt is when it was made, a datetime as atproto/lexicon.md defines; and password is four groups of four characters, each a lower case letter or a digit 2 to 7, joined by -, as abcd-efgh-2345-ijkl, random. The password is answered only here. name is any string, the empty one too. A name the account already has for an app password is 500 InternalServerError, as the reference answers it, and makes none; of several at once with the same name, one is made. Only a session of scope com.atproto.access may make one: an app password's session is 400 InvalidToken, whatever the input. An account has at most 50: a 51st is 400 TooManyAppPasswords (LIMITS.md).
  • listAppPasswords answers {passwords}, the account's app passwords, newest first, each {name, createdAt, privileged}, as created.
  • revokeAppPassword {name} deletes the account's app password of that name, and stops keeping every session made with it, so their refresh tokens are 400 ExpiredToken from then on, those of sessions refreshed from them too. Their access tokens work until they expire. It answers 200 with an empty body, whether or not the account had one of that name. It touches no other account's app passwords.

listAppPasswords and revokeAppPassword take any access token of the account, an app password's session's too, which may revoke the app password it was made with.

createSession takes an app password where it takes the account's password, by handle, email or DID, exactly as given: in upper case, or without its dashes, it is wrong. An account created without a password has none to log in with, but may make app passwords with its first session, and logs in with them by handle or DID; it keeps no email, so not by email. A session made with an app password, privileged or not, answers as any other, and may do what the account's own sessions do, but for createAppPassword and getAccountInviteCodes (LIMITS.md), which answer it 400 InvalidToken, and requestEmailUpdate and updateEmail (EMAIL.md). It may change the account's handle with updateHandle, as the reference's may.

One thing the reference does is a fault, and the server does not copy it. A session made with an app password named "" becomes, when it is refreshed, a full session of scope com.atproto.access, which may make app passwords, and revoking that app password does not end it or the sessions refreshed from it. The server keeps such a session an app password's session, as above.

Note: the harness makes, lists and revokes app passwords named "", but does not log in with one.

Durability

Sessions are kept as DURABILITY.md says: a session the server answered, the refresh that answered it, and its end by deleteSession or revokeAppPassword, all survive the server being killed. So does each app password and its revocation.

How it is checked

harness/compare.mjs keeps, for each account, the sessions it has had on each side, and each step picks one:

  • refreshSession with a session's refresh token, current or replaced, ended or not, on both sides, compared; a new session it answers joins the account's.
  • deleteSession with a session's refresh token, compared.
  • wrong tokens: each method of this page, getSession and createRecord, given a refresh token where an access token is wanted, an access token where a refresh token is, a token with its sub changed or its alg made none, a token never given out, or an Authorization header with another scheme, in lower case, or of three words; and a session's access token, whatever became of the session, on getSession.
  • app passwords: createAppPassword with names old and new, odd ones, and privileged or not, with a full session or an app password's; listAppPasswords; revokeAppPassword of a name the account has or not, or another account has; createSession with an app password, revoked or not, by handle, email or DID, in upper case, or another account's.
  • races: several refreshSessions at once with one token, which all succeed with tokens of one session; several createAppPasswords at once with one name, of which one makes it.
  • crashes: after each restart, some of every account's sessions are refreshed and its app passwords listed, compared with the reference, which was not killed.

Every session's tokens the harness uses are decoded and held to the table above, as the reference's are: the header's typ, and the claims, with the DIDs named alike and times taken out. exp - iat must be exactly as above, and for tokens refreshSession or createSession with an app password answered, iat within a second of when the request was sent and answered. A refresh token's jti is named on each side by the order the harness first saw it, so the sessions refreshes answer must be the same ones on both sides, as above. Each app password must be of the form above; its createdAt must be a datetime within a second of the request, and the same in listAppPasswords as when created, and is taken out. The rest is compared as PDS.md says, tokens taken out.

Not compared:

  • An ExpiredToken for a token past its exp: the harness does not wait two hours, nor ninety days, nor the end of an old refresh token's grace. It checks exp - iat instead.
  • refreshSession and deleteSession with one token at once: which lands first is a race on both sides.
  • Which algorithm signs the tokens, and the jti itself.