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

Passkeys

An account may sign in on the authorization page (OAUTH.md) with a passkey instead of its password: a WebAuthn credential (webauthn/) that a browser, a phone or a password manager keeps, which proves it is there by signing what the server asks. The account adds one through a link it asks for with its password session, opened in a browser; lists and removes them with the same session. The reference PDS has no passkeys: everything here is the server's own, and checked against this page alone.

RouteMethodDoes
/xrpc/_passkeyListGETlists the account's passkeys
/xrpc/_passkeyAddPOSTmakes a link that adds one
/xrpc/_passkeyRemovePOSTremoves one
/oauth/passkeyGETthe page the link opens, which adds the passkey

The first three are routes of the server's own, of no lexicon and no NSID, as OAUTH-ACCOUNT.md's are; their MCP tools and CLI commands are in COMMANDS.md, "The account's passkeys". The page and its API call, passkey-register, and the authorization page's two calls that sign in with a passkey, passkey-options and passkey-sign-in, are below. What each page shows a person is in OAUTH-PAGES.md.

Sources

This section is informative.

FileIsLicence
webauthn/webauthn-3.mdWeb Authentication, Level 3: registering a credential (§7.1), verifying an assertion (§7.2), authenticator data (§6.1), attested credential data (§6.5.1), none attestation (§8.7), and test vectors (§16)W3C Software and Document License, webauthn/LICENSE-W3C.md
webauthn/rfc8949.txtCBORIETF Trust (BCP 78)
webauthn/rfc9052.txtCOSE structures: the COSE_Key (§7)IETF Trust
webauthn/rfc9053.txtCOSE algorithms: ES256 (§2.1), EC2 keys (§7.1)IETF Trust
webauthn/rfc8230.txtRSA in COSE: RSA keys (§4) and their sizes (§6.1)IETF Trust
webauthn/rfc8812.txtCOSE registrations for WebAuthn: RS256 (§2)IETF Trust
webauthn/rfc8017.txtPKCS #1: RSASSA-PKCS1-v1_5 (§8.2)IETF Trust

webauthn/README.md says where each is from. In WebAuthn's words, the server is the Relying Party, a passkey a client-side discoverable public key credential, its record on the server a credential record, and the link's page and the authorization page the scripts that run its registration and authentication ceremonies.

The relying party

  • RP ID. The host of the issuer (OAUTH.md, "The issuer"), without its port: pds.example.com for https://pds.example.com, localhost for http://localhost:2583.

    Note: a browser takes no IP address as an RP ID, so with an issuer of http://127.0.0.1:<port> the routes and checks below answer as said, but no browser makes or uses a passkey. A passkey is bound to the RP ID it was made for: once PDS_PUBLIC_URL names another host, browsers no longer offer the passkeys made before, which the server still keeps until they are removed.

  • Origin. The issuer, exactly: scheme, host and port.

  • Algorithms. ES256: ECDSA on P-256 with SHA-256, COSE algorithm -7 (webauthn/rfc9053.txt, §2.1); and RS256: RSASSA-PKCS1-v1_5 with SHA-256, COSE algorithm -257 (webauthn/rfc8812.txt, §2), with a modulus of 2048 to 4096 bits. A browser asks an authenticator for ES256 first.

    Note: the two every authenticator is asked to support, so that none fails to make a passkey for want of one; Chromium says so of a page that offers fewer.

  • User handle. Each account has one: 32 bytes, the HMAC-SHA-256 of its DID under a key of 32 random bytes the server makes once and keeps, so the same for all its links and passkeys, whatever happens to the account, and made by nothing outside the server. It is not the account's DID, and shows nothing of it (webauthn/webauthn-3.md, §14.6.1).

  • Encoding. Every byte string in JSON here, a credential ID, a challenge, a user handle and each of a credential's members that WebAuthn types Base64URLString, is base64url without padding (RFC 4648, §5). A string sent to the server that is not is refused as the step reading it says.

An account has at most 20 passkeys.

Auth

_passkeyList, _passkeyAdd and _passkeyRemove take the token OAUTH-ACCOUNT.md's routes take, and refuse the others as they do (OAUTH-ACCOUNT.md, "Auth"): no Authorization header is 401 AuthMissing; an app password's session, a refresh token or a Basic header 400 InvalidToken; an OAuth access token 403 Forbidden; and at /mcp, with no token, the sign-in challenge, and with an MCP session's token the tool error 403 Forbidden.

Note: a passkey signs in as the password does; what may add one is what may change the password, the account's password session alone.

Requests

Past the auth, each route checks, in this order:

  1. Its HTTP method: 400 InvalidRequest.
  2. For _passkeyAdd, the account's state: taken down is 401 AccountTakedown, and deleted 403 AccountNotFound (LIFECYCLE.md, "Its own calls").
  3. For _passkeyAdd and _passkeyRemove, the body: one longer than 153600 bytes is 413 PayloadTooLargeError, as for any method with a JSON input (LIMITS.md, "Request size"); then Content-Type: application/json, and a JSON object with, for _passkeyAdd, name a string of 1 to 64 characters (Unicode code points), and for _passkeyRemove, id a string; else 400 InvalidRequest. Their other properties are ignored.

_passkeyList takes no parameters, and ignores any given. Each route answers 200 with Content-Type: application/json; charset=utf-8, costs a point of global (LIMITS.md), and has its route, as _passkeyList, in its request line, its metrics and its span, as any request (OPERATIONS.md). None is refused below PDS_MIN_FREE_BYTES: _passkeyAdd keeps nothing on disk, and _passkeyRemove keeps the end of something, as OAUTH-ACCOUNT.md's revocations do.

_passkeyList

{"passkeys": [{"id": "…", "name": "Laptop", "createdAt": "2026-11-14T09:02:11.500Z", "lastUsedAt": "2026-11-14T09:05:40.031Z", "backedUp": true}]}

passkeys holds every passkey of the token's account, the latest createdAt first, then by id; none of another account's. Of each:

  • id is its credential ID.
  • name is the name _passkeyAdd was given for it.
  • createdAt is when passkey-register added it, and lastUsedAt its last sign-in by passkey-sign-in, left out when it has none; each a datetime as atproto/lexicon.md defines it, in UTC, with milliseconds.
  • backedUp is the backup state (BS) its authenticator data last gave (webauthn/webauthn-3.md, §6.1.3).

_passkeyAdd

{name} makes a link that adds a passkey of that name to the token's account, and answers:

{"url": "https://pds.example.com/oauth/passkey?token=…", "expiresAt": "2026-11-14T09:17:11.500Z"}

An account that has 20 passkeys is 400 InvalidRequest, and makes none.

  • url is <issuer>/oauth/passkey?token=<token>, where <token> is 32 random bytes, base64url: the link. It is a secret: whoever opens it in time adds a passkey to the account.
  • expiresAt is 900 seconds from now, a datetime as above: the link ends then.

The link holds the account, the name, and a challenge of 32 random bytes, the registration's. An account has one link at a time: a new one ends the one before, whose page and passkey-register then answer as for a link ended. A link is used once: the passkey it adds ends it. Links are held in memory alone ("Durability").

_passkeyRemove

{id} removes the token's account's passkey of that credential ID: from then on, passkey-sign-in with it is refused, and _passkeyList no longer lists it. It answers 200 {}, whether or not the account had a passkey of that id; a passkey of another account's is left as it was. The devices the passkey signed the account in on stay signed in, as the sessions made through them stay: OAUTH-ACCOUNT.md's routes end those.

The passkey page

GET /oauth/passkey?token=<token> is a navigation, and is refused otherwise, as the authorization page is (OAUTH.md, "The authorization page"): a 400 error page invalid_request. Its other methods are 404. Then a token missing, or none of a link held, ended or past its time, or the link of an account taken down or deleted, is a 400 error page invalid_request.

Otherwise the page answers 200, Cache-Control: no-store, as OAUTH-PAGES.md builds a page ("How the pages are built"), with one statement, window["__passkeyData"]=JSON.parse("…");, of:

  • account: {did, handle}, and name and picture when the account has them, as OAUTH.md gives an account's (OAUTH.md, "The authorization page").
  • name: the link's name.
  • expiresAt: when the link ends, as _passkeyAdd answered it.
  • options: the registration's options, PublicKeyCredentialCreationOptions in the JSON form parseCreationOptionsFromJSON() takes (webauthn/webauthn-3.md, §5.1.8), byte strings in base64url:
MemberIs
rp{id, name}, both the RP ID
user{id, name, displayName}: the account's user handle, its handle, and its name when it has one, else its handle
challengethe link's challenge
pubKeyCredParams[{"type": "public-key", "alg": -7}, {"type": "public-key", "alg": -257}]
timeout300000
excludeCredentialseach of the account's passkeys, as {type: "public-key", id}, with transports when it kept any
authenticatorSelection{"residentKey": "required", "requireResidentKey": true, "userVerification": "required"}
attestation"none"

The page sets the csrf-token cookie as the authorization page does, and no device cookies. Loading it keeps nothing and ends nothing: it may be loaded again while the link holds. It costs no rate limit, and is not refused below PDS_MIN_FREE_BYTES.

passkey-register

The passkey page's script calls POST /@atproto/oauth-provider/~api/passkey-register with {credential}, checked as OAUTH.md checks the API's calls ("The API"), but for the Referer: the issuer's origin, path /oauth/passkey, and a token query parameter. The call is then for that link. A passkey-register with the authorization page's Referer, and any other endpoint with the passkey page's, is 400 invalid_request.

credential is what the browser's navigator.credentials.create() gave, as its toJSON() gives it (RegistrationResponseJSON, webauthn/webauthn-3.md, §5.1). The call checks, as §7.1 does, in this order, each failure 400 with {"error", "error_description"}:

  1. The link: held, not ended, not past its time, and its account neither taken down nor deleted: else access_denied. A link adds one passkey: of two calls through it at once that would each add one, one does, and the other is access_denied. Every check after this one fails with invalid_request.
  2. Its form: credential an object with id and rawId the same string, base64url; type public-key; and response an object with clientDataJSON and attestationObject base64url strings, and transports, when present, an array of strings. Its other members are ignored.
  3. The client data (§7.1, steps 5 to 11): clientDataJSON UTF-8, a leading byte order mark dropped, a JSON object whose type is webauthn.create, whose challenge is the link's, base64url, whose origin is the origin above, whose crossOrigin is absent or false, and which has no topOrigin. Its other members are ignored.
  4. The attestation object (§7.1, steps 13 and 19 to 24): attestationObject one CBOR item (webauthn/rfc8949.txt), with nothing after it: a map of exactly fmt, attStmt and authData; fmt none, and attStmt an empty map (§8.7); authData a byte string.
  5. The authenticator data (§6.1, §7.1, steps 14 to 18): rpIdHash the SHA-256 of the RP ID; UP set; UV set; BS set only with BE; AT set; then the attested credential data (§6.5.1): aaguid, 16 bytes; credentialIdLength, 2 bytes, big-endian; credentialId, of that many bytes, at most 1023, and the bytes rawId names; and credentialPublicKey, one CBOR item, a COSE_Key (webauthn/rfc9052.txt, §7) of one of the algorithms above: for ES256, a map of exactly 1 (kty) 2 (EC2), 3 (alg) -7, -1 (crv) 1 (P-256), and -2 (x) and -3 (y) byte strings of 32 bytes each, a point on P-256; for RS256, a map of exactly 1 (kty) 3 (RSA), 3 (alg) -257, -1 (n) a byte string of 256 to 512 bytes whose first is not zero, and -2 (e) a byte string of 1 to 8 bytes whose first is not zero, an odd number of at least 3 (webauthn/rfc8230.txt, §4). With ED set, one CBOR map follows it, the extensions, which are ignored; with ED clear, nothing does. Nothing follows that.
  6. New: no account has a passkey of that credential ID (§7.1, step 26).

Below PDS_MIN_FREE_BYTES, a call that passes these is 507 {"error": "temporarily_unavailable", "error_description"}, keeping nothing, and the link holds. Otherwise the passkey is the account's: its credential ID; its public key; its signature count, BE and BS, as the authenticator data gave them; its transports, those of usb, nfc, ble, smart-card, hybrid and internal the credential gave, each once, in the order given; the link's name; and createdAt now. The link ends, and the call answers 200 {}.

Signing in

The authorization page signs an account in with a passkey by a challenge its device holds, which the page's own statement gives it as it loads, or passkey-options gives it at once, and then passkey-sign-in. The calls are checked as OAUTH.md checks every call of the API ("The API"), the authorization page's Referer among them. Neither needs the request the Referer names to be held, as sign-in does not.

A device's challenge is 32 random bytes, held for the device (OAUTH.md, "Devices") for 300 seconds. A device holds one challenge: a new one replaces it. Challenges are held in memory alone ("Durability"). The options of a challenge are the authentication's, PublicKeyCredentialRequestOptions in the JSON form parseRequestOptionsFromJSON() takes (webauthn/webauthn-3.md, §5.1.9):

{"challenge": "…", "rpId": "pds.example.com", "timeout": 300000, "userVerification": "required", "allowCredentials": []}

allowCredentials is empty: the browser offers the passkeys it has for the RP ID, and the one chosen names its account (§7.2, step 6).

The page's options

The authorization page, when it answers 200 (OAUTH.md, "The authorization page"), gives the device it answers a new challenge, and has one statement more, window["__passkeyOptions"]=JSON.parse("…");, of its options. The page offers the device's passkeys in its identifier field's autofill with them, as it appears, so it calls nothing to have them (OAUTH-PAGES.md, "Sign in"). The page is not refused below PDS_MIN_FREE_BYTES for it: a challenge is kept in memory alone.

passkey-options

passkey-options {} gives the call's device a new challenge, and answers {options}, its options. A call that names no device, with no device cookies or ones the server did not set, is 400 invalid_request.

passkey-sign-in

passkey-sign-in {locale, credential, remember?}: locale as sign-in takes it, remember a boolean, and credential what the browser's navigator.credentials.get() gave, as its toJSON() gives it (AuthenticationResponseJSON, §5.1). It checks, as §7.2 does, in this order, each failure 400 invalid_request:

  1. The challenge: the call's device holds one, within its 300 seconds. It is spent now, whatever follows: a device's challenge signs in once, or fails once.

  2. Its form: credential an object with id and rawId the same string, base64url; type public-key; and response an object with clientDataJSON, authenticatorData, signature and userHandle, base64url strings. Its other members are ignored.

  3. The passkey (§7.2, step 6): a passkey of the credential ID rawId names, whose account's user handle is userHandle.

  4. The client data (§7.2, steps 8 to 14): as passkey-register's, but type webauthn.get, and challenge the device's.

  5. The authenticator data (§7.2, steps 15 to 19): at least 37 bytes; rpIdHash the SHA-256 of the RP ID; UP set; UV set; BS set only with BE; BE as the passkey's; AT clear; with ED set, one CBOR map after the 37 bytes, ignored, and with it clear, nothing.

  6. The signature (§7.2, steps 20 and 21): signature, by the passkey's public key, over authenticatorData followed by the SHA-256 of clientDataJSON: for ES256, an ECDSA signature, DER-encoded, an s in the curve's upper half taken as in its lower; for RS256, an RSASSA-PKCS1-v1_5 signature with SHA-256, as many bytes as the modulus.

  7. The signature count (§7.2, step 22): when the authenticator data's or the passkey's count is not zero, the authenticator data's is greater than the passkey's.

    Note: a count that did not grow is a sign the passkey was copied; the server refuses it rather than weigh it.

  8. The account: one taken down is 400 invalid_request, Account was taken down, as sign-in answers it (LIFECYCLE.md, "OAuth sessions"). A deactivated one signs in, as with its password.

Below PDS_MIN_FREE_BYTES, a call that passes these is 507 {"error": "temporarily_unavailable", "error_description"}, keeping nothing. Otherwise the passkey's signature count and BS are the authenticator data's, its lastUsedAt is now, and the account is signed in as sign-in signs it in (OAUTH.md, "The API"): with remember: true, or with remember left out when the account is already signed in on this device, on the device, its sign-in time there now, with its User-Agent and client address (OAUTH-ACCOUNT.md); otherwise not, and the answer has an ephemeralToken too. It answers {account}, as sign-in does.

A passkey stands for both of the account's factors: with its email factor on (EMAIL.md), passkey-sign-in signs in with no code, and mails none. It costs no rate limit, as the API's other calls (OAUTH.md, "Rate limits"), and answers as soon as it is checked: it hashes no password, and names no identifier whose time could show anything.

The account's consent, reject and redirect are then as after sign-in, for either issuer's request (OAUTH-MCP.md), which uses the same page.

The account's states

  • _passkeyList, _passkeyAdd and _passkeyRemove answer in each of the account's states as LIFECYCLE.md's "Its own calls" gives them.
  • A deactivation, a takedown, applied or lifted, and a change of email leave the passkeys as they were: a taken-down account's passkeys sign in again once the takedown is lifted.
  • A password reset (EMAIL.md, "resetPassword") removes every passkey of the account, and ends its link, as it ends what else whoever had its password may have left.
  • A deletion (LIFECYCLE.md, "deleteAccount") removes every passkey of the account and ends its link.

Durability

As DURABILITY.md says of every answered write: a passkey passkey-register added, its removal by _passkeyRemove, a password reset or a deletion, and each passkey-sign-in's signature count, BS and lastUsedAt, with the sign-in on the device it made, survive the server being killed, and so does the key user handles are made with. A link and a challenge are held in memory alone: after a restart none is held, so the page of a link made before is the error page, its passkey-register access_denied, and a passkey-sign-in 400 invalid_request, until a new link or challenge is made.

How it is checked

harness/checks/passkeys.mjs, on the server alone: the reference has no passkeys. Its authenticator is the harness's own, made with node:crypto as webauthn/webauthn-3.md describes one: a P-256 key for each passkey, and clientDataJSON, authenticator data and attestation objects written byte by byte, so that each can be made wrong in one way. Its pages are loaded and its API called as harness/lib/oauth.mjs does, with the issuer's origin.

  • Auth. Each of the three routes with no token, a token the server did not give out, an app password's session, a refresh token, the admin's Basic, and an OAuth access token with its proof: the errors above, and nothing listed, made or removed. With a password token: the other HTTP method; _passkeyAdd and _passkeyRemove with no body, a body that is not JSON, with no name or id, a name of 0 and of 65 characters, and one of 64 characters of four bytes each, taken; one of 153601 bytes, 413 PayloadTooLargeError.
  • Adding. _passkeyAdd: its url and expiresAt 900 seconds on, within a second. The page: __passkeyData as above, its options member by member, user.id the same 32 bytes for each of an account's links, before its first passkey and after, after a password reset and after a restart, of no other account's, and excludeCredentials the account's passkeys, compared as a set; at 20 passkeys, _passkeyAdd 400 InvalidRequest; two passkey-registers through one link at once, one 200 {} and the other access_denied, one passkey added; the navigation refused as the authorization page's is; a missing token, a token of no link, and the first link's after a second _passkeyAdd, each the error page. Then passkey-register with the harness's authenticator: 200 {}, _passkeyList listing it with its name, createdAt within a second, no lastUsedAt, and backedUp, with BE and BS each set and clear; the link then ended, page and call. Refused, each with one thing wrong and nothing added, the link still holding but for the first: an ended link (access_denied); the credential's form; type webauthn.get; another challenge; another origin, and the issuer's with another port; crossOrigin: true; a topOrigin; a byte order mark, taken; another rpIdHash; UP clear; UV clear; BS without BE; AT clear; fmt packed; a non-empty attStmt; an attestation object with a fourth key, and with a byte after it; a credential ID other than rawId, and one of 1024 bytes (1023 taken); a key of alg -257 with kty 2, of alg -7 with kty 3, of crv 2, with a sixth member, and off the curve; an RS256 key of 2048 and of 4096 bits, taken, and one with n of 255 bytes, of 513, and with a first byte of zero, and with e even, and 1; extensions with ED clear, and none with ED set; a byte after the key; a credential ID another account has. passkey-register with the authorization page's Referer, and sign-in with the passkey page's, 400 invalid_request.
  • Signing in. The authorization page's __passkeyOptions: its options as above, a new challenge each load, which passkey-sign-in from that device takes, and which a later load or passkey-options replaces. passkey-options: its options as above, a new challenge each call, and with no device cookies 400 invalid_request. passkey-sign-in with remember: true: {account}, the page's __sessions then listing it, _passkeyList its lastUsedAt within a second, _oauthDevices the device; with remember: false, an ephemeralToken that consent takes, and the account not listed; both through to a code and a token, for each issuer. With the email factor on, signed in with no code, and nothing mailed. Refused, each with one thing wrong and no sign-in: no challenge; a challenge already spent, by a sign-in and by a failure; the challenge of another device; the credential's form; no userHandle, and another account's; a credential ID of no passkey, and of one removed; type webauthn.create; another challenge; another origin; crossOrigin: true; a topOrigin; another rpIdHash; UP clear; UV clear; BE other than the passkey's; AT set; a signature by another key, over other bytes, and not DER; with an RS256 passkey, which signs in, a signature by another key and one a byte short; a count not greater than the last, and a count of zero after one that was not; a taken-down account. A signature with s in the upper half, taken; a count of zero, twice, taken; a deactivated account, signed in, its consent access_denied.
  • Removing. _passkeyRemove of one: its sign-in refused, the account's other passkey still signing in; another account's id, and an id no passkey has, 200 {}, removing nothing.
  • States. A password reset: every passkey of the account gone, and its link ended. A takedown: sign-in refused, then taken again once lifted. With --lifecycle, after each change of an account's state, its password token on the three routes, as the rows of LIFECYCLE.md's "Its own calls" give them, and a deleted account's passkey no longer signing in.
  • Free space. With --limits, below PDS_MIN_FREE_BYTES: passkey-register and passkey-sign-in 507, adding and signing in nothing; _passkeyAdd and _passkeyRemove answered.
  • Commands. The tools and commands as COMMANDS.md checks them.
  • Crashes. With --crash-every, a passkey added, one removed, and a sign-in made before a kill: after the restart, the first listed and signing in, the second neither, and the sign-in's count kept, so that an assertion with that count is refused; a link made before, its page the error page; a challenge made before, passkey-sign-in refused.
  • Pages. With --pages, OAUTH-PAGES.md's passkey flows, in Chromium with its virtual authenticator, on a server whose PDS_PUBLIC_URL is http://localhost:<port>, a host a browser takes as an RP ID.