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
The PDS: accounts and their records; sessions and their tokens are as
Sessions says. atproto's HTTP API (XRPC) spec describes service
proxying and inter-service JWTs in general; this page says exactly what the
server does.
Environment
Section titled “Environment”| Variable | Description |
|---|---|
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://<PDS_HOSTNAME>/xrpc/com.atproto.sync.getBlob?did=<did>&cid=<cid>.
SSRF protection
Section titled “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: web, native and confidential clients), client attestations’ issuers
(Spaces: credentials), a managing app’s endpoint
(Spaces: policies and the space lifecycle), 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:webdocument, a client’s metadata or JWKS, an attestation issuer’s metadata or JWKS) or to ask a managing app, follows no redirect: a3xxis 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:webresolver refuses one too; so a public host cannot send the server on to a private one. -
Sizes. A
did:webdocument is read up to 65536 bytes: a longer one, byContent-Lengthor 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 and the space lifecycle) are read up to 524288 bytes (OAuth: web, native and confidential clients). 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 is502 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, “Requests out”).
Which requests are forwarded
Section titled “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:
- Its HTTP method.
GET,HEADandPOSTare forwarded as they are; any other is400 InvalidRequest. - 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,revokeAppPasswordandupdateEmail(allcom.atproto.server). The server serves each of them itself or not at all: one it does not serve, in any case, is400 InvalidToken, and is never sent anywhere. - The target, from the
atproto-proxyheader or the default (below). Its errors are400 InvalidRequestor500 InternalServerError, as below, whatever the token. Nothing is fetched for it before the call has paid its rate-limit point (Limits, “When”): a call over its limit is429with no document fetched, whatever itsAuthorization. - The token, as for any method (Sessions): none is
401 AuthMissing; a refresh token, or one the server did not give out, is400 InvalidToken. An OAuth access token with its proof is checked here (OAuth: access tokens on every method, and what scopes allow), then its scope forrpcof the method to the target:403 ScopeMissingError. Then the token’s account: taken down is401 AccountTakedown(Account lifecycle). - Privileged methods. A method whose name starts with
chat.bsky., in any case, needs a session of scopecom.atproto.accessorcom.atproto.appPassPrivileged: an app password’s session that is not privileged is400 InvalidToken. An OAuth session’s scope said already (OAuth: access tokens on every method, and what scopes allow, “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 (Account lifecycle). 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
Section titled “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:plcis read fromPDS_PLC_URL. One the directory does not know (404) is400 InvalidRequest; any other answer than2xxor404from the directory, or none, is500 InternalServerError. - A
did:webis read fromhttps://<host>/.well-known/did.json(orhttp, as SSRF protection above allows). An answer other than2xxor3xxis400 InvalidRequest. One that cannot be fetched, as when nothing listens there, a redirect (3xx, not followed), or a document longer than 65536 bytes (above), is500 InternalServerError. - Any other DID, of another method or not a DID at all (
did:key:…,did:example:…,notadid,DID:PLC:…in upper case), and adid:webwith a path (did:web:example.com:a), is500 InternalServerError. - A document that is not one, or not this DID’s, is
500 InternalServerError: not a JSON object, anidother than the DID, aservicethat is not a list, or an entry of it without a stringidandtype, or whoseserviceEndpointis 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
Section titled “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 itsContent-TypeandContent-Encoding, whatever they are, and none forGETorHEAD; - 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 withX-Atproto-; Accept-Encoding, the client’s, oridentitywith none;Authorization: Bearer <token>, a service token (below) withissthe token’s account,audthe target’s DID, andlxmthe 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
Section titled “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:
| 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
Section titled “Service tokens”A service token is a JWT, as atproto's HTTP API (XRPC) spec’s “Inter-Service
Authentication” says, signed with the account’s signing key (Accounts),
the key its DID document names as #atproto, as atproto's Cryptography spec
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:
| Claim | Description |
|---|---|
iat | when it was made, in seconds since the epoch |
iss | the account’s DID |
aud | the target’s DID alone, without #<service id>, 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's HTTP API (XRPC) spec notes that aud is to gain the service id; the
reference still sends the bare DID, and so does the server.
getServiceAuth
Section titled “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:
- The parameters against the lexicon, before the token:
audmissing,expnot an integer, orlxmnot an NSID (*too) is400 InvalidRequest. - The token: none is
401 AuthMissing, a refresh token or one the server did not give out400 InvalidToken. An OAuth session’s scope must allowrpcoflxm, or of*without one, toaudas given (OAuth: access tokens on every method, and what scopes allow): else403 ScopeMissingError. Then the token’s account: taken down is401 AccountTakedown, whateverlxm(Account lifecycle). audmust 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,.,_,:,%,-): adid:plcofdid:plc:and 24 characters ofa-zand2-7, or adid:webwith no path, and with no port but onlocalhost(did:web:localhost%3A2583). Anything else (did:key:…,did:example:…,did:plc:abc,<did>#,<did>#a b) is400 InvalidRequest. It need not resolve.- An
lxmof a privileged method, one starting withchat.bsky.or one that iscom.atproto.server.createAccount, both compared without regard to case, needs a session of scopecom.atproto.accessorcom.atproto.appPassPrivileged: an app password’s that is not privileged is400 InvalidRequest. Not asked of an OAuth session, whose scope said at step 2. exp, if given and not0, in seconds: before now is400 BadExpiration; more than an hour from now is400 BadExpiration; and more than a minute from now, withoutlxm, is400 BadExpiration.- An
lxmof a method never forwarded (above), compared without regard to case, is400 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 (Account lifecycle).
Preferences
Section titled “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). An account starts with none. A deactivated, taken-down
or deleted account’s getPreferences and putPreferences are as
Account lifecycle 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
Section titled “putPreferences”app.bsky.actor.putPreferences {preferences} replaces the account’s
preferences. It checks, in this order, and answers the first error:
- The token: none is
401 AuthMissing, a refresh token or one the server did not give out400 InvalidToken. - The input against
app.bsky.actor.defs#preferences: a list of objects, each with a string$type. An object whose$typeis 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 (abirthDatethat is not a datetime), or a string or list beyond itsmaxLengthormaxGraphemesis400 InvalidRequest.knownValuesare not enforced. Fields a definition does not name are kept, and a field the definition gives adefaultis filled in with it when missing (anadultContentPrefwithoutenabledis kept withenabled: false). An object of any other$typeis taken as it is. Fields of the input besidepreferencesare ignored. - Every
$typemust beapp.bskyor start withapp.bsky.: any other,""too, is400 InvalidRequest. Nothing more is asked of it:app.bsky.x ypasses. - A
personalDetailsPref, from a session of another scope thancom.atproto.access, is400 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
Section titled “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
Section titled “Other methods the server serves for the app”These are the server’s own methods, checked against their lexicons in
lexicons/ as The PDS: accounts and their records 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
Section titled “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’sdidis the account’s, itsdisplayName,description,avatarandbannerbecome 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 ofprofileswhosedidis the account’s.getActorLikes: when there is profile, each item offeedwhosepost.author.didis the account’s getsdisplayNameandavatarfrom it, as above.getAuthorFeed: when the feed is the account’s own, that is when its first item has noreasonand the account’spost.author.did, or areasonof typeapp.bsky.feed.defs#reasonRepostwhoseby.didis the account’s: authors as forgetActorLikes, then posts inserted as forgetTimeline. Otherwise nothing changes.getTimeline: posts inserted. Each post written after the feed’s last item’sindexedAt(all of them when the feed is empty), newest first, is put before the first item whoseindexedAtis earlier than its own, or at the end, as{post}, wherepostis{uri, cid, likeCount: 0, replyCount: 0, repostCount: 0, quoteCount: 0, author, record, embed, indexedAt}:recordis the post as stored, as JSON;indexedAtwhen it was written;authoris{did, handle, displayName, avatar}from the account’s handle and its profile as it is now, each left out when it has none; andembedis, for anapp.bsky.embed.imagespost,{$type: "app.bsky.embed.images#view", images}with each image{thumb, fullsize, alt, aspectRatio}(feed_thumbnailandfeed_fullsizeURLs), for anapp.bsky.embed.externalpost{$type: "app.bsky.embed.external#view", external: {uri, title, description, thumb}}(thumbafeed_thumbnailURL, 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
Section titled “com.atproto.repo.getRecord”A getRecord whose repo names no account the server holds, or one that
is not active (deactivated or taken down, Account lifecycle), 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
Section titled “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
Section titled “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
Account lifecycle says (“Its own calls”): neither is sent on.
What the reference does that the server need not
Section titled “What the reference does that the server need not”This section is informative.
com.atproto.moderation.createReportand thetools.ozonemethods 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), 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.
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 Records against their lexicons’s: records of
those types are checked against them.
How it is checked
Section titled “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(typeBskyAppView) and#bsky_notif(typeBskyNotificationService), both its own URL. The reference is configured with it, and the server started withPDS_BSKY_APP_VIEW_URL=http://localhost:<port>,PDS_BSKY_APP_VIEW_DIDits DID,PDS_BSKY_APP_VIEW_CDN_URL_PATTERN=http://cdn.pds-harness.test/%s/%s/%sandPDS_DISABLE_SSRF_PROTECTION=true, as the reference runs with no SSRF protection; - the chat service, a
did:plcthe harness registers with the directory, with#bsky_chat(typeBskyChatService); its own URL serves no DID document, sodid:web:localhost%3A<its port>answers404; - elsewhere,
did:web:localhost%3A<port>, whose document has#atproto_labeler,#bsky_xand<did>#full, its URL;#ip, its URL by127.0.0.1;#BSKY_Xand#down, a URL where nothing listens;#path,#queryand#fragment, its URL with one;#ftp, anftp://URL;#upper, anHTTP://one; and#object, an object; - a feed generator and a notification service,
did:plcs with#bsky_fgand#bsky_notifat elsewhere’s URL, and adid:plcwhose#bsky_notifis of another type; - two
did:webs whose documents are not theirs: one with anotherid, one with a service entry without atype.
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: access tokens on every method, and what scopes allow, “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, …), byGET,HEADorPOST, with random queries and bodies (JSON, gzipped, bytes, text, none), headers that go on and headers that do not, and noatproto-proxyheader, an empty one, or one naming each reachable service, with every kind of session but those achat.bskymethod refuses, and the service answering a random status, type, headers and body, errors among them, with and withouterrorandmessage; - 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,DELETEandPATCH; malformed method names; achat.bskymethod 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,lxmandexpdrawn from each rule above, with every kind of session, none, and a refresh token; - preferences:
putPreferencesof random lists of the union’s types and others,declaredAgePrefandpersonalDetailsPrefamong them, with defaults left out, sometimes with one refused, thengetPreferences, from every kind of session, and both sometimes with anatproto-proxyheader; 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 (Records against their lexicons),
then
getProfile,getProfiles,getTimeline,getAuthorFeedorgetActorLikes, the AppView answering views of the account and of others, valid or not, JSON or not, with a status of200,201or203, other headers or none, and anatproto-repo-revfrom 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: write notifications, the writer set and syncers, “How it is checked”): adid:webonlocalhostor an IP address, and a service endpoint there, are never connected to. What both sides read of adid:webdocument that redirects is compared in the--limitsrun (Limits), and the server alone held to the sizes above there: a document of 70000 bytes, an answer of 17 MiB. - The
Accept-Encodingsent on for the methods the server serves, and theContent-Encodingeither side answers with: each side negotiates its own. The harness asks foridentity, or forgzipand 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
--limitsrun fills (Limits). getPostThreadand record embeds, which the server need not munge (above): the harness sends nogetPostThreadand writes no post that embeds a record.createReportand thetools.ozonemethods, 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.