Compatibility: any PDS against the reference
harness/compat.mjs runs the core of harness/compare.mjs’s checks against
an implementation other than Monolith, beside the reference, and reports
area by area what agrees, going on past a difference. Its areas: OAuth, its
scopes and its clients; sessions; accounts; records and their validation;
the repository; sync; the firehose; identity; blobs. compat/README.md
lists which checks are in each, and which are not run.
Monolith is held to all of The PDS: accounts and their records and the pages it links, in its gates and in a compatibility run alike: nothing on this page applies to it. What follows is what a compatibility run lets any other implementation have, and why. It lets it nothing else.
Taken out of every answer
Section titled “Taken out of every answer”The same as for Monolith (The PDS: accounts and their records, “How it is checked”): each account’s
DID, its signing key, the server’s URL (each of them, where the URL its DID
documents name is not the one it is called at and its OAuth issuer names),
each commit’s cid and rev, tokens, cursors, and error messages. The
error name and the HTTP status must match, and a didDoc must be the one
the PLC directory serves.
The KEM key
Section titled “The KEM key”An implementation may publish an atproto_kem key for an account, or not.
If its genesis operation has one, it must be a P-256 did:key other than
the signing key, and getRecommendedDidCredentials must name the same key,
as Spaces asks of Monolith; it is then taken out before the sides are
compared, as Monolith’s is. Why: the key is the spaces alpha’s, which the
reference does not serve, so the reference cannot say whether a server has
one; requiring it would hold another server to Monolith’s own spec.
describeServer’s spacesAlpha is not checked, for the same reason.
OAuth access tokens’ life
Section titled “OAuth access tokens’ life”An access token’s expires_in may be 899 to 900 (15 minutes, as
OAuth: the authorization server has Monolith answer) or 3599 to 3600 (60 minutes, as the
reference answers). Why: OAuth: the authorization server lists the reference’s 60 minutes as
where it departs from atproto’s OAuth profile, which asks for less than 30;
either is one a client already meets. Any other life is a difference.
describeServer
Section titled “describeServer”Only did, availableUserDomains and inviteCodeRequired are compared,
as for Monolith: the rest of the answer (links, contact, the blob limit) is
each server’s own.
Exact numbers of limits
Section titled “Exact numbers of limits”Two checks are sent to Monolith alone, as their numbers are its own
choices that the reference happens to share: a blob of exactly the upload
limit and one byte past it, with describeServer’s blobUploadLimit; and a
PAR body of exactly 100 KiB and one byte past it. Neither is part of the
protocol.
Signing in
Section titled “Signing in”The reference’s authorization page is driven through its own API
(/@atproto/oauth-provider/~api/*), which Monolith serves too. Another
implementation signs in on its own page, through its adapter’s signIn:
the account’s identifier and password, then approving (or refusing) the
request. The reference’s page and API answers are then its own and are not
compared; what is compared starts at the redirect back to the client (its
target, code, state, iss or error), and goes on as for Monolith: the
token exchange, DPoP, refresh, revocation, and every call with the
session’s tokens. Why: atproto’s OAuth profile leaves the sign-in page to
each server.
Where a server’s page cannot consent to a narrower scope than the one asked (it has no consent step, or its form can only take scopes away), the scope asked is the one approved.
Checks of the reference’s page API itself (oauthAuthorizeRefused,
oauthDeviceCookies, oauthSilentSignIn, and the 404s of its API in the
metadata check) are not run.
Monolith’s own departures
Section titled “Monolith’s own departures”Where OAuth: the authorization server and OAuth: web, native and confidential clients hold Monolith to the spec rather than
the reference (their “Where the reference departs” tables), another
implementation is not held to them: oauthDepartures,
oauthClientDepartures, and the authorization server metadata’s
request_parameter_supported: false.
One account
Section titled “One account”An implementation may host one account, by design, and make it its own way
rather than by createAccount. Its adapter then has claim: given the
handle and email of the reference’s first account, it makes the server’s
one account, with the password the server was started with, and answers its
DID and a session. The reference’s account is made with createAccount, with
that password; the two answers are not compared, nor is the server’s genesis
operation, as neither is createAccount’s. Each area then has that one
account on each side, where it would have two or three.
The checks that make an account (the accounts area, and the firehose’s createAccount) or need a second one (writes to another account’s repository, two accounts racing for a handle, and in updateHandle’s refusals a handle another account has) are not run. Every other check runs on the one account, held to the reference as before. Why: atproto lets a PDS host one account; what it does with that account the reference can still say.
The account’s rotation key is taken from its genesis operation, where the adapter cannot name one before the account is made: the server’s own PLC operations are then held to that key.
Password rules
Section titled “Password rules”An implementation may refuse passwords by a rule of its own, as a minimum
length or the kinds of character one must have. Its adapter then has
passwordFor(p), which turns a password the harness drew into one the rule
takes, the same p always to the same password, and draws nothing from
the run’s seeded source. Each area’s first accounts, made only so that the
area has accounts (supporting steps, not counted in it), are made with
that password on both sides, and are signed in with it after. Every check
that sends a password of its own, among them the accounts area’s
createAccount and its refusals, sends it as before, so the server’s
refusals of the harness’s passwords are reported where they are made. Why:
atproto leaves what passwords a PDS takes to it; with every first account
refused, an area would have no account and run no check.
Its own address
Section titled “Its own address”An implementation may name itself by an https origin it is not reached at
in the run: its OAuth issuer, the endpoint in its DID documents, and the
htu it holds DPoP proofs to, as a server behind a TLS front does. Its
adapter then answers that origin as its public URL, the URL the harness
reaches it at, and fronted. Every request the harness makes for that
origin, of any check, is sent to that URL instead, as the front would send
it, and is otherwise as before: its proofs, tokens and parameters still
name the origin, and so the server is held to its own. Why: atproto names a
server by its https address, and a run on one machine has no certificate
for it. Its adapter lists address among the settings it cannot be given
(below): the atproto OAuth client library, which oauthClientLibrary
signs in with, refuses an https address on a loopback host.
Settings an implementation cannot be given
Section titled “Settings an implementation cannot be given”An adapter lists each setting of the run its implementation cannot be
given, with why. The checks that need one are not run, and the report names
each, with the reason. The settings: OAuth client documents fetched from
the harness’s web (the oauth clients area); the hostname localhost (the
requestCrawl checks); the handle domains .test and .example
(describeServer); more than one account (the checks the section above
names); a rotation key the harness can sign with (its own PLC operations,
made before updateHandle, which ask the server to carry on from one it did
not post); the reference’s recovery key, among the rotation keys
(getRecommendedDidCredentials, which names them); one DID every
NSID’s lexicon is resolved from, the harness’s set publisher (the oauth
permission sets area); and a directory to keep its log in,
PDS_LOG_DIR (Operations, “Kept”; the lines _logs reads back,
their bound, and the starts with that directory unset or not writable);
and being reached at the address it names, http on loopback as the
reference’s (oauthClientLibrary, as the section above says).