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

Proxying, service auth and preferences

What the Bluesky app needs from its PDS beyond the repository: requests for other services (the AppView, the chat service, labelers, feed generators) forwarded with a token the account signs, the tokens themselves from com.atproto.server.getServiceAuth, and the account's private preferences, app.bsky.actor.getPreferences and putPreferences, kept by the server. What every method shares, and how the server is checked, is in PDS.md; sessions and their tokens are as SESSIONS.md says. atproto/xrpc.md describes service proxying and inter-service JWTs in general; this page says exactly what the server does.

Environment

VariableIs
PDS_BSKY_APP_VIEW_URLthe default AppView's URL, such as https://api.bsky.app
PDS_BSKY_APP_VIEW_DIDits DID, such as did:web:api.bsky.app
PDS_BSKY_APP_VIEW_CDN_URL_PATTERNoptional: the URL of an image on the AppView's CDN, with three %s, as https://cdn.bsky.app/img/%s/plain/%s/%s@jpeg
PDS_DISABLE_SSRF_PROTECTIONoptional: true or 1 turns protection off, false, 0, empty or unset leaves it on; for development and testing only, a server open to the internet must not set it. Any other value makes pds serve exit 1, with why on standard error (the reference takes it as unset)

The URL and the DID come together: one without the other makes pds serve exit 1, with why on standard error. Without them the server has no default AppView: every request that would go to it is 400 InvalidRequest, and the methods below that the server serves itself, getPreferences among them, are not served but forwarded like any other, and so 400 InvalidRequest too unless an atproto-proxy header names a service. A com.atproto.repo.getRecord of a repository the server does not hold is then 400 InvalidRequest.

There is no chat variable: a chat.bsky.* request without an atproto-proxy header goes to the default AppView like any other.

Note: the reference has none. The Bluesky app names its chat service in every chat request (atproto-proxy: did:web:api.bsky.chat#bsky_chat).

The CDN pattern makes the image URLs of read-after-write (below): its %s are replaced, in order, by the kind of image (avatar, banner, feed_thumbnail or feed_fullsize), the account's DID and the blob's CID. Without one, an image's URL is https://<PDS_HOSTNAME>/xrpc/com.atproto.sync.getBlob?did=<did>&cid=<cid>.

SSRF protection

Unless PDS_DISABLE_SSRF_PROTECTION=true, the server sends a request only to an https URL whose host is not an IP address but a public unicast one and resolves only to public unicast addresses (no unspecified, loopback, private, shared, link-local, documentation, benchmarking, multicast, broadcast or reserved address, nor an IPv6 form of one; of IPv6, global unicast alone, less Teredo, ORCHID and documentation), the default AppView's URL included; localhost and other names that resolve to such addresses are refused like the addresses themselves, and the address connected to is one the check passed, so a name that resolves otherwise the second time is no way around it. Any port is allowed. Every request the server sends to a URL others name goes through this one guard: a service here, every did:web document the server reads (here, and of an issuer, a managing app or a syncer, SPACES*.md), OAuth clients' documents and JWKS (OAUTH-CLIENTS.md), client attestations' issuers (SPACES-CREDENTIALS.md), a managing app's endpoint (SPACES-POLICIES.md), and the spaces' notifications. A request it will not send is answered as if the service could not be reached, 502 UpstreamFailure. A did:web document is then fetched only over https from such a host, and one it will not fetch is 500 InternalServerError. With true, http URLs and every address are allowed, and a did:web whose host is localhost is fetched over http (did:web:localhost%3A2583 from http://localhost:2583/.well-known/did.json); with protection on, never.

Whether protection is on or off:

  • No redirects. A request the server sends for itself, to read a document (a did:web document, a client's metadata or JWKS, an attestation issuer's metadata or JWKS) or to ask a managing app, follows no redirect: a 3xx is as no answer at all, a document that cannot be fetched. A forwarded request's redirect is answered as it is (below), not followed.

    Note: the reference's did:web resolver refuses one too; so a public host cannot send the server on to a private one.

  • Sizes. A did:web document is read up to 65536 bytes: a longer one, by Content-Length or as it comes, is as one that cannot be fetched, and the rest is not read. A client's metadata, a JWKS, an issuer's metadata, and a managing app's answer (SPACES-POLICIES.md) are read up to 524288 bytes (OAUTH-CLIENTS.md). A forwarded answer, or a service's answer to a method the server serves by asking it (getProfile, getFeed, ...), is read up to 16777216 bytes (16 MiB): a longer one is 502 UpstreamFailure, and nothing of it is answered. Every other answer the server reads (a notification's) up to 65536 bytes.

  • Time. Each such request is given up after 10 seconds with no answer, as below, and at most 256 are in flight at once (LIMITS.md, "Requests out").

Which requests are forwarded

A request to /xrpc/<method> for a method the server does not serve is forwarded. Method names are compared without regard to case: the server serves com.atproto.server.GETSESSION as getSession, and forwards only names that are none of its methods in any case. <method> here is runs of ASCII letters and digits joined by single . or -, with an optional / after it, and is not checked further: foo, a.b and 9a.b.c are forwarded. Anything else after /xrpc/, such as a..b or a.b/c, is 400 InvalidRequest.

A forwarded request is checked in this order, and the first error is the answer:

  1. Its HTTP method. GET, HEAD and POST are forwarded as they are; any other is 400 InvalidRequest.
  2. Methods never forwarded. These are for the account's own server alone: com.atproto.admin.sendEmail, com.atproto.identity.requestPlcOperationSignature, com.atproto.identity.signPlcOperation, com.atproto.identity.updateHandle, com.atproto.server.activateAccount, confirmEmail, createAppPassword, deactivateAccount, getAccountInviteCodes, getSession, listAppPasswords, requestAccountDelete, requestEmailConfirmation, requestEmailUpdate, revokeAppPassword and updateEmail (all com.atproto.server). The server serves each of them itself or not at all: one it does not serve, in any case, is 400 InvalidToken, and is never sent anywhere.
  3. The target, from the atproto-proxy header or the default (below). Its errors are 400 InvalidRequest or 500 InternalServerError, as below, whatever the token. Nothing is fetched for it before the call has paid its rate-limit point (LIMITS.md, "When"): a call over its limit is 429 with no document fetched, whatever its Authorization.
  4. The token, as for any method (SESSIONS.md): none is 401 AuthMissing; a refresh token, or one the server did not give out, is 400 InvalidToken. An OAuth access token with its proof is checked here (OAUTH-SCOPES.md), then its scope for rpc of the method to the target: 403 ScopeMissingError. Then the token's account: taken down is 401 AccountTakedown (LIFECYCLE.md).
  5. Privileged methods. A method whose name starts with chat.bsky., in any case, needs a session of scope com.atproto.access or com.atproto.appPassPrivileged: an app password's session that is not privileged is 400 InvalidToken. An OAuth session's scope said already (OAUTH-SCOPES.md, "Proxied calls").

A deleted account's token, still within its exp, that passes these is 500 InternalServerError, and nothing is sent: there is no key to sign with (LIFECYCLE.md). A deactivated account's calls are forwarded.

Methods the server serves ignore the atproto-proxy header, but for those of the sections below that say otherwise: createRecord with one is a write to the account's repository, and describeServer with a malformed one is answered as without.

The target

With no atproto-proxy header, or an empty one, the target is the default AppView: PDS_BSKY_APP_VIEW_URL, with PDS_BSKY_APP_VIEW_DID and the service id bsky_appview. With none configured, the request is 400 InvalidRequest.

The header is <did>#<service id>. Its value, as HTTP gives it (without leading or trailing white space), is checked in this order, each failure 400 InvalidRequest:

  • it starts with #: no DID;
  • it has no #, or ends with it: no service id;
  • it has a second #;
  • it has a space.

The header exactly <PDS_BSKY_APP_VIEW_DID>#bsky_appview is the default AppView, at PDS_BSKY_APP_VIEW_URL, without its DID document being read. Any other DID is resolved:

  • A did:plc is read from PDS_PLC_URL. One the directory does not know (404) is 400 InvalidRequest; any other answer than 2xx or 404 from the directory, or none, is 500 InternalServerError.
  • A did:web is read from https://<host>/.well-known/did.json (or http, as SSRF protection above allows). An answer other than 2xx or 3xx is 400 InvalidRequest. One that cannot be fetched, as when nothing listens there, a redirect (3xx, not followed), or a document longer than 65536 bytes (above), is 500 InternalServerError.
  • Any other DID, of another method or not a DID at all (did:key:…, did:example:…, notadid, DID:PLC:… in upper case), and a did:web with a path (did:web:example.com:a), is 500 InternalServerError.
  • A document that is not one, or not this DID's, is 500 InternalServerError: not a JSON object, an id other than the DID, a service that is not a list, or an entry of it without a string id and type, or whose serviceEndpoint is neither a string nor an object.

In the document, the service is the first entry of service whose id is #<service id> or <did>#<service id>, compared exactly, case and all; its type is not looked at. Its serviceEndpoint must be a string that starts with http:// or https:// (in lower case) and parses as a URL. No such entry, or such an endpoint, is 400 InvalidRequest.

The request goes to the endpoint's origin. An endpoint with a path other than /, a query or a fragment cannot be reached that way: the request is 502 UpstreamFailure, as the reference answers it. A user and password in the endpoint are ignored.

The server may keep resolved DID documents for a while; nothing here checks how long.

What is sent

The request goes to the target with:

  • the same HTTP method, and the same path and query, byte for byte as received: /xrpc/<method>?<query>, with the method's name in the case it came in;
  • the body as received, byte for byte, for a POST, with its Content-Type and Content-Encoding, whatever they are, and none for GET or HEAD;
  • these request headers, each as received when the client sent it: Accept-Language, atproto-accept-labelers, X-Bsky-Topics, and every header whose name starts with X-Atproto-;
  • Accept-Encoding, the client's, or identity with none;
  • Authorization: Bearer <token>, a service token (below) with iss the token's account, aud the target's DID, and lxm the method's name as in the path.

No other header the client sent goes on: not its Authorization, cookies, atproto-proxy, DPoP, or any other. The server adds only what HTTP needs (Host, Content-Length, and the like).

What is answered

The target's answer, if its status is below 400, is the answer: the same status, the body byte for byte, and of the target's response headers only Content-Type, Content-Language, Content-Encoding, atproto-repo-rev, atproto-content-labelers and Retry-After. A redirect is answered as it is, not followed.

A status of 400 or more is an error. Its status is the target's, but 500, which is 502. Its body is JSON, {error, message}: unless the target's Content-Type is present and is not JSON (application/json, or application/<x>+json), its body is read as JSON, and its error and message, where they are strings, are kept. Without one, error is the status's name, and message its text:

Statuserrormessage
400InvalidRequestInvalid Request
401AuthenticationRequiredAuthentication Required
403ForbiddenForbidden
404XRPCNotSupportedXRPC Not Supported
406NotAcceptableNot Acceptable
413PayloadTooLargePayload Too Large
415UnsupportedMediaTypeUnsupported Media Type
429RateLimitExceededRate Limit Exceeded
500, as 502UpstreamFailureUpstream Failure
501MethodNotImplementedMethod Not Implemented
502UpstreamFailureUpstream Failure
503NotEnoughResourcesNot Enough Resources
504UpstreamTimeoutUpstream Timeout

Any other status, such as 418, has no name of its own: the body is the target's error and message, where they are strings, and neither where they are not ({}). No header of the target's goes on with an error.

A target that cannot be reached, refuses the connection, or sends no response headers within 10 seconds is 502 UpstreamFailure.

Service tokens

A service token is a JWT, as atproto/xrpc.md's "Inter-Service Authentication" says, signed with the account's signing key (ACCOUNTS.md), the key its DID document names as #atproto, as atproto/cryptography.md says (a low-S signature, 64 bytes, over the bytes of <header>.<payload>, each base64url without padding). Its header is {typ: "JWT", alg: "ES256K"}, and its payload has exactly:

ClaimIs
iatwhen it was made, in seconds since the epoch
issthe account's DID
audthe target's DID alone, without #<service id>, for every token the server sends; for getServiceAuth, its aud as given
expiat + 60, or for getServiceAuth its exp when given
lxmthe method it is for; left out by getServiceAuth without one
jtia new random string, a different one in every token (the reference's is 32 hex digits)

Note: atproto/xrpc.md notes that aud is to gain the service id; the reference still sends the bare DID, and so does the server.

getServiceAuth

com.atproto.server.getServiceAuth makes a service token for the token's account, {token}. It checks, in this order, and answers the first error:

  1. The parameters against the lexicon, before the token: aud missing, exp not an integer, or lxm not an NSID (* too) is 400 InvalidRequest.
  2. The token: none is 401 AuthMissing, a refresh token or one the server did not give out 400 InvalidToken. An OAuth session's scope must allow rpc of lxm, or of * without one, to aud as given (OAUTH-SCOPES.md): else 403 ScopeMissingError. Then the token's account: taken down is 401 AccountTakedown, whatever lxm (LIFECYCLE.md).
  3. aud must be an atproto DID, optionally followed by # and a non-empty fragment of the characters a DID may hold (A-Z, a-z, 0-9, ., _, :, %, -): a did:plc of did:plc: and 24 characters of a-z and 2-7, or a did:web with no path, and with no port but on localhost (did:web:localhost%3A2583). Anything else (did:key:…, did:example:…, did:plc:abc, <did>#, <did>#a b) is 400 InvalidRequest. It need not resolve.
  4. An lxm of a privileged method, one starting with chat.bsky. or one that is com.atproto.server.createAccount, both compared without regard to case, needs a session of scope com.atproto.access or com.atproto.appPassPrivileged: an app password's that is not privileged is 400 InvalidRequest. Not asked of an OAuth session, whose scope said at step 2.
  5. exp, if given and not 0, in seconds: before now is 400 BadExpiration; more than an hour from now is 400 BadExpiration; and more than a minute from now, without lxm, is 400 BadExpiration.
  6. An lxm of a method never forwarded (above), compared without regard to case, is 400 InvalidRequest.

The token's claims are those of the table above: aud as given, fragment and all; lxm as given, or none; exp as given, or iat + 60 when it is not. exp: 0 passes step 5 and is the token's exp, as the reference makes it. A deleted account's token, still within its exp, that passes every step is 500 InternalServerError; a deactivated account's is answered as an active one's (LIFECYCLE.md).

Preferences

The server keeps each account's preferences: a list of JSON objects, each with a $type, in the order last put. They are the account's alone, and survive the server being killed once putPreferences has answered (DURABILITY.md). An account starts with none. A deactivated, taken-down or deleted account's getPreferences and putPreferences are as LIFECYCLE.md says ("Its own calls").

The type app.bsky.actor.defs#personalDetailsPref is private: only a session of scope com.atproto.access reads or writes it. The type app.bsky.actor.defs#declaredAgePref is never kept: it is worked out when read.

putPreferences

app.bsky.actor.putPreferences {preferences} replaces the account's preferences. It checks, in this order, and answers the first error:

  1. The token: none is 401 AuthMissing, a refresh token or one the server did not give out 400 InvalidToken.
  2. The input against app.bsky.actor.defs#preferences: a list of objects, each with a string $type. An object whose $type is one of the union's types must be valid by that type's definition: a missing required field, a value of the wrong type or format (a birthDate that is not a datetime), or a string or list beyond its maxLength or maxGraphemes is 400 InvalidRequest. knownValues are not enforced. Fields a definition does not name are kept, and a field the definition gives a default is filled in with it when missing (an adultContentPref without enabled is kept with enabled: false). An object of any other $type is taken as it is. Fields of the input beside preferences are ignored.
  3. Every $type must be app.bsky or start with app.bsky.: any other, "" too, is 400 InvalidRequest. Nothing more is asked of it: app.bsky.x y passes.
  4. A personalDetailsPref, from a session of another scope than com.atproto.access, is 400 InvalidRequest.

Then the account's preferences become: those it had that the session may not write (its personalDetailsPrefs, for an app password's session), then the given ones in the order given, but for any declaredAgePref, which is dropped. Two of a type are both kept. The answer is 200 with an empty body.

An atproto-proxy header other than <PDS_BSKY_APP_VIEW_DID>#bsky_appview, even a malformed one, makes it 500 InternalServerError, after step 2, and nothing is kept or sent.

Note: the reference forwards only queries.

getPreferences

app.bsky.actor.getPreferences answers {preferences}: the account's preferences in their order, without personalDetailsPrefs for a session of another scope than com.atproto.access, and then, if the first personalDetailsPref kept has a birthDate, a declaredAgePref, last:

{"$type": "app.bsky.actor.defs#declaredAgePref", "isOverAge13": true, "isOverAge16": true, "isOverAge18": false}

each true when the account is at least that old: its age is the whole years from birthDate to today, in UTC, one fewer if this year's birthday is still to come. Every session gets it, an app password's too.

It takes any access token; none is 401 AuthMissing. Parameters are ignored. With an atproto-proxy header other than <PDS_BSKY_APP_VIEW_DID>#bsky_appview, it is not answered from the preferences kept but forwarded to that target, as above, after the token is checked, with the service token's lxm app.bsky.actor.getPreferences.

Other methods the server serves for the app

These are the server's own methods, checked against their lexicons in lexicons/ as PDS.md says (a query's parameters before its token, a procedure's input after), each needing an access token, and then forwarded to the target (the default AppView, or as the atproto-proxy header says), as above, with these differences.

Read after write

app.bsky.actor.getProfile, getProfiles, app.bsky.feed.getTimeline, getAuthorFeed, getActorLikes and getPostThread are forwarded as GET with the same path and query, the headers above but no body and no Content-Type, an Accept-Encoding the server may choose, and a service token whose lxm is the method. Errors are answered as above.

Their answer may then show the account's own records that the target has not seen yet. If the target's answer has an atproto-repo-rev header, rev, and a JSON Content-Type (or none), the server looks at the account's records written by commits whose rev is after rev: the first 10 by commit, oldest first, of those the repository still holds. With none, or when no record of the account's was written at or before rev (rev then means nothing here), the answer is the target's, as above. Otherwise the server reads the target's body: if it is not valid by the method's output lexicon, the answer is the target's body as it is, with the target's headers as above. If it is, the answer is the body below, as JSON, with Content-Type: application/json and an Atproto-Upstream-Lag header, the milliseconds since the oldest of those records that is the account's profile (app.bsky.actor.profile/self) or a post (app.bsky.feed.post) was written, when there is one, and no other header of the target's: no atproto-repo-rev, Content-Language, atproto-content-labelers or Retry-After.

Every method of this page that the server serves and forwards (these, the getRecord, getFeed and getPreferences below and above) answers 200 for any status of the target's below 400 (201, 204 and the rest), with the target's body; only the methods the server does not serve pass the target's success status on.

What changes, where profile is the account's app.bsky.actor.profile/self among those records, and posts the app.bsky.feed.post records among them:

  • getProfile: when there is profile and the answer's did is the account's, its displayName, description, avatar and banner become profile's: the strings as they are, the images as URLs (above), and each left out when profile has none.
  • getProfiles: the same for each of profiles whose did is the account's.
  • getActorLikes: when there is profile, each item of feed whose post.author.did is the account's gets displayName and avatar from it, as above.
  • getAuthorFeed: when the feed is the account's own, that is when its first item has no reason and the account's post.author.did, or a reason of type app.bsky.feed.defs#reasonRepost whose by.did is the account's: authors as for getActorLikes, then posts inserted as for getTimeline. Otherwise nothing changes.
  • getTimeline: posts inserted. Each post written after the feed's last item's indexedAt (all of them when the feed is empty), newest first, is put before the first item whose indexedAt is earlier than its own, or at the end, as {post}, where post is {uri, cid, likeCount: 0, replyCount: 0, repostCount: 0, quoteCount: 0, author, record, embed, indexedAt}: record is the post as stored, as JSON; indexedAt when it was written; author is {did, handle, displayName, avatar} from the account's handle and its profile as it is now, each left out when it has none; and embed is, for an app.bsky.embed.images post, {$type: "app.bsky.embed.images#view", images} with each image {thumb, fullsize, alt, aspectRatio} (feed_thumbnail and feed_fullsize URLs), for an app.bsky.embed.external post {$type: "app.bsky.embed.external#view", external: {uri, title, description, thumb}} (thumb a feed_thumbnail URL, left out without one), and left out for others.
  • Every other key of the answer is as the target sent it.

The reference does more that the server need not, and that the harness does not check: for a post that embeds a record, it asks the AppView for that record's view; and getPostThread puts the account's new replies into the thread, or answers a thread of the account's own new post when the target says NotFound. The server forwards getPostThread as above and changes nothing in its answer.

com.atproto.repo.getRecord

A getRecord whose repo names no account the server holds, or one that is not active (deactivated or taken down, LIFECYCLE.md), is forwarded to the target, as a read-after-write method is, but with no Authorization at all: with or without a token, and with the atproto-proxy header if there is one. Its answer is the target's, as above.

getFeed

app.bsky.feed.getFeed ?feed=at://<did>/<collection>/<rkey> first reads the feed's record from the default AppView, whatever the header: GET <PDS_BSKY_APP_VIEW_URL>/xrpc/com.atproto.repo.getRecord?repo=<did>&collection=<collection>&rkey=<rkey>, with no Authorization, none of the client's headers, and Accept-Language: *, whatever the client's, as the reference's HTTP client sends. A feed that is an AT URI without a collection and a record key (at://<did>, at://<did>/<collection>) is 500 InternalServerError, and nothing is read; one with a handle for <did> is read with that handle as repo. An error there is answered as above. An answer that is not valid by getRecord's output lexicon is 502 InvalidResponse. A value.did that is not a string is 400 InvalidRequestError (sic: that is the reference's error name). Otherwise the request is forwarded to the target as a read-after-write method is (without changing its answer), with a service token whose aud is that value.did, and whose lxm is app.bsky.feed.getFeedSkeleton.

registerPush and unregisterPush

app.bsky.notification.registerPush and unregisterPush {serviceDid, token, platform, appId, ...} send their input on, as JSON, by POST to /xrpc/<method> of the notification service, with a service token whose aud is serviceDid and lxm the method, Content-Type: application/json, Accept-Language: * as getFeed's record read has it, and none of the client's headers (not its Accept-Language, atproto-accept-labelers or X-Atproto-*). A serviceDid that is PDS_BSKY_APP_VIEW_DID is the default AppView's URL. Any other is resolved as above, and its service is the entry #bsky_notif of type BskyNotificationService; a DID that resolves to nothing, or no such entry, is 400 InvalidRequest. The service's errors are answered as above. A success is 200 with an empty body, whatever the service's body, but for one whose Content-Type is JSON and whose body is not (an empty one too), which is 502 InvalidResponse. A taken-down or deleted account's are as LIFECYCLE.md says ("Its own calls"): neither is sent on.

What the reference does that the server need not

This section is informative.

  • com.atproto.moderation.createReport and the tools.ozone methods go, with no header, to the reference's moderation service, which the server does not have; the harness sends none of them.
  • A request body of more than 150 KB is 413 (LIMITS.md), forwarded or not; nothing here checks what the reference does with a forwarded one.
  • Values in preferences that are not plain JSON ($bytes, $link): the reference stores them oddly, and the harness sends none.

Data

The lexicons of this page's methods, and every one they refer to, are in lexicons/: app.bsky.* from lexicons/ of https://github.com/bluesky-social/bsky at be148a09fb (2026-11-01), where the app.bsky lexicons are published now, and com.atproto.* from lexicons/ of https://github.com/bluesky-social/atproto at 0849c24d49 (2026-11-09), both MIT or Apache-2.0, unchanged. The record lexicons among them, and the others the server knows, are VALIDATION.md's: records of those types are checked against them.

How it is checked

harness/lib/services.mjs runs the services the two sides forward to, HTTP servers on localhost that record every request they get and answer what the step running sets:

  • the AppView, did:web:localhost%3A<port>, which serves its DID document at /.well-known/did.json, with #bsky_appview (type BskyAppView) and #bsky_notif (type BskyNotificationService), both its own URL. The reference is configured with it, and the server started with PDS_BSKY_APP_VIEW_URL=http://localhost:<port>, PDS_BSKY_APP_VIEW_DID its DID, PDS_BSKY_APP_VIEW_CDN_URL_PATTERN=http://cdn.pds-harness.test/%s/%s/%s and PDS_DISABLE_SSRF_PROTECTION=true, as the reference runs with no SSRF protection;
  • the chat service, a did:plc the harness registers with the directory, with #bsky_chat (type BskyChatService); its own URL serves no DID document, so did:web:localhost%3A<its port> answers 404;
  • elsewhere, did:web:localhost%3A<port>, whose document has #atproto_labeler, #bsky_x and <did>#full, its URL; #ip, its URL by 127.0.0.1; #BSKY_X and #down, a URL where nothing listens; #path, #query and #fragment, its URL with one; #ftp, an ftp:// URL; #upper, an HTTP:// one; and #object, an object;
  • a feed generator and a notification service, did:plcs with #bsky_fg and #bsky_notif at elsewhere's URL, and a did:plc whose #bsky_notif is of another type;
  • two did:webs whose documents are not theirs: one with another id, one with a service entry without a type.

Every step that sends something that may be forwarded sends it to the reference, takes what the services got, then sends the same to the server and takes what they got: the two sides' forwarding is never mixed. What each side forwarded is compared: which service got it, the HTTP method, the path and query as bytes, the headers this page lists (Accept-Encoding only for methods the server does not serve), that none of the client's Cookie, Origin, Referer, DPoP, atproto-proxy, its user agent, or an X-Not-Forwarded went on, and the body, as bytes, or for registerPush and unregisterPush as JSON. What each side answered is compared too: the status; for an error its error and the response headers this page lists; otherwise the type (without parameters), those headers, whether Atproto-Upstream-Lag is there, and the body, as JSON or as text; with each account's DID named alike on both sides (in a query too, encoded), the commits' revs named by which they are, and the indexedAt of each record the side wrote taken out. Every service token either side sends or answers is decoded and held to the table above: the header, exactly these claims, exp - iat, iat within two seconds of the request, a jti not seen before, and a signature that verifies against the atproto key of the account's DID in the directory. Their claims are then compared, with DIDs named alike and the times and jti taken out.

harness/checks/proxy.mjs has the steps, among the others of compare.mjs. "Every kind of session" is the account's password session, its app passwords' (privileged or not), and its OAuth sessions, signed in with loopback clients whose scopes mix transition:generic, transition:chat.bsky and rpc permissions of some of the methods and services below, or none (OAUTH-SCOPES.md, "Proxied calls"), each call then made with DPoP and a proof and its nonce, WWW-Authenticate error and ScopeMissingError message compared too. Read after write, getFeed and the push methods are made with the password session or an OAuth one.

  • forwarded: a method neither side serves (app.bsky.feed.getPosts, app.bsky.graph.muteActor, chat.bsky.convo.listConvos, NSIDs of odd case and form, ...), by GET, HEAD or POST, with random queries and bodies (JSON, gzipped, bytes, text, none), headers that go on and headers that do not, and no atproto-proxy header, an empty one, or one naming each reachable service, with every kind of session but those a chat.bsky method refuses, and the service answering a random status, type, headers and body, errors among them, with and without error and message;
  • refused: each malformed or unreachable target above, with a token or none; no token, a refresh token, a token never given out, or Basic; PUT, DELETE and PATCH; malformed method names; a chat.bsky method with an app password's session, privileged or not; a method served, in another case; and the methods never forwarded, in any case, of which only that neither side sent anything is compared, as the reference serves them all;
  • getServiceAuth: aud, lxm and exp drawn from each rule above, with every kind of session, none, and a refresh token;
  • preferences: putPreferences of random lists of the union's types and others, declaredAgePref and personalDetailsPref among them, with defaults left out, sometimes with one refused, then getPreferences, from every kind of session, and both sometimes with an atproto-proxy header; and after every crash, each account's preferences;
  • read after write: the account's profile, with or without an avatar and banner, and up to two posts, with images, a link card or neither, written on both sides and compared as any write (VALIDATION.md), then getProfile, getProfiles, getTimeline, getAuthorFeed or getActorLikes, the AppView answering views of the account and of others, valid or not, JSON or not, with a status of 200, 201 or 203, other headers or none, and an atproto-repo-rev from before the writes, after them, from before every record, one after every rev, or none;
  • getRecord of a repository not here, with a token or none, and getFeed (with a feed named by DID or handle, or missing its collection or key), registerPush and unregisterPush (with headers the client sends that do not go on), with the services answering each way.

Not compared:

  • What needs the real AppView, chat service or labelers: what they answer, and whether they accept the server's tokens. The harness verifies the tokens itself, as a service would.
  • SSRF protection: both sides run without it, as the services are on localhost. With it on, the server is checked alone in the spaces run (SPACES-SYNC.md, "How it is checked"): a did:web on localhost or an IP address, and a service endpoint there, are never connected to. What both sides read of a did:web document that redirects is compared in the --limits run (LIMITS.md), and the server alone held to the sizes above there: a document of 70000 bytes, an answer of 17 MiB.
  • The Accept-Encoding sent on for the methods the server serves, and the Content-Encoding either side answers with: each side negotiates its own. The harness asks for identity, or for gzip and reads what comes.
  • How long either side keeps a DID document: the services' documents never change.
  • A target that answers slowly: the harness waits for no timeout but the 10 s wait for a slot of the requests out, whose 256 the --limits run fills (LIMITS.md).
  • getPostThread and record embeds, which the server need not munge (above): the harness sends no getPostThread and writes no post that embeds a record.
  • createReport and the tools.ozone methods, above.
  • The birthDates the harness puts are more than two days from any birthday, as the reference works out ages in its own time zone.