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

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 PDS.md 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

The same as for Monolith (PDS.md, "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

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.md 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

An access token's expires_in may be 899 to 900 (15 minutes, as OAUTH.md has Monolith answer) or 3599 to 3600 (60 minutes, as the reference answers). Why: OAUTH.md 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

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

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

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

Where OAUTH.md and OAUTH-CLIENTS.md 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

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

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

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

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.md, "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).