# 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`](PDS.md); sessions and their tokens are as [`SESSIONS.md`](SESSIONS.md) says. `atproto/xrpc.md` describes service proxying and inter-service JWTs in general; this page says exactly what the server does. ## Environment | Variable | Is | | --- | --- | | `PDS_BSKY_APP_VIEW_URL` | the default AppView's URL, such as `https://api.bsky.app` | | `PDS_BSKY_APP_VIEW_DID` | its DID, such as `did:web:api.bsky.app` | | `PDS_BSKY_APP_VIEW_CDN_URL_PATTERN` | optional: 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_PROTECTION` | optional: `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:///xrpc/com.atproto.sync.getBlob?did=&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/` 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. `` 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 `#`. 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 `#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:///.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 `#` or `#`, 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/?`, 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 `, 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/+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: | Status | `error` | `message` | | --- | --- | --- | | 400 | `InvalidRequest` | `Invalid Request` | | 401 | `AuthenticationRequired` | `Authentication Required` | | 403 | `Forbidden` | `Forbidden` | | 404 | `XRPCNotSupported` | `XRPC Not Supported` | | 406 | `NotAcceptable` | `Not Acceptable` | | 413 | `PayloadTooLarge` | `Payload Too Large` | | 415 | `UnsupportedMediaType` | `Unsupported Media Type` | | 429 | `RateLimitExceeded` | `Rate Limit Exceeded` | | 500, as 502 | `UpstreamFailure` | `Upstream Failure` | | 501 | `MethodNotImplemented` | `Method Not Implemented` | | 502 | `UpstreamFailure` | `Upstream Failure` | | 503 | `NotEnoughResources` | `Not Enough Resources` | | 504 | `UpstreamTimeout` | `Upstream 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 `
.`, each base64url without padding). Its header is `{typ: "JWT", alg: "ES256K"}`, and its payload has exactly: | Claim | Is | | --- | --- | | `iat` | when it was made, in seconds since the epoch | | `iss` | the account's DID | | `aud` | the target's DID alone, without `#`, for every token the server sends; for `getServiceAuth`, its `aud` as given | | `exp` | `iat` + 60, or for `getServiceAuth` its `exp` when given | | `lxm` | the method it is for; left out by `getServiceAuth` without one | | `jti` | a 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`, `#`, `#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 `personalDetailsPref`s, 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 `#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 `personalDetailsPref`s for a session of another scope than `com.atproto.access`, and then, if the first `personalDetailsPref` kept has a `birthDate`, a `declaredAgePref`, last: ```json {"$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 `#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:////` first reads the feed's record from the default AppView, whatever the header: `GET /xrpc/com.atproto.repo.getRecord?repo=&collection=&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://`, `at:///`) is `500 InternalServerError`, and nothing is read; one with a handle for `` 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/` 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`, 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:`, `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` answers `404`; - **elsewhere**, `did:web:localhost%3A`, whose document has `#atproto_labeler`, `#bsky_x` and `#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:plc`s with `#bsky_fg` and `#bsky_notif` at elsewhere's URL, and a `did:plc` whose `#bsky_notif` is of another type; - two `did:web`s 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 `birthDate`s the harness puts are more than two days from any birthday, as the reference works out ages in its own time zone.