Skip to content

pds

The atproto network adapter. Package @unset/infrastructure-pds. Identity lookups are ADR 0013. The OAuth client is ADR 0021. PDS calls are ADR 0024. Web egress is ADR 0022, decided (0001 log), acceptance pending.

Owns

ModuleWhat it holds
infrastructure/pds/identity-network.tscreateIdentityNetwork. Implements the identity domain’s IdentityNetwork on net-guard.
infrastructure/pds/oauth/oauth-client.tscreateOAuthClient, ClientKeys, clientMetadata, publicJwks, oauthFields.
infrastructure/pds/oauth/identity-resolvers.tsHandle and DID resolvers the client library is given. Not exported from index.ts.
infrastructure/pds/oauth/scopes.tsgrantCovers, SCOPE_METADATA. Uses @atproto/oauth-scopes.
infrastructure/pds/oauth/sign-in.tsauthorize, completeAuthorization.
infrastructure/pds/pds-call.tscreatePdsCall. The file that calls client.restore and new Agent.
infrastructure/pds/pds-errors.tsisDpopNonceHandshake.
infrastructure/pds/profile-record.tsloadProfileRecord, saveProfileRecord, PROFILE_COLLECTION, PROFILE_RKEY. Reads and writes sh.unset.profile/self on the member’s PDS, swap on the stored cid.
infrastructure/pds/repo-record.tsloadRecord, saveRecord: one record of the member’s own repo by collection and key. saveRecord reads, lets the caller build, and writes with swapRecord set to the cid it read; a change in between is conflict.
infrastructure/pds/card-records.tslistCardRecords (first 100 sh.unset.card records, own repo only), createCardRecord (the PDS picks the key), saveCardRecord (swap on the stored cid; a card that is gone is refused as card.missing, never recreated), deleteCardRecord. Only the list is retried.

createIdentityNetwork throws ConfigError on PLC_URL unless the URL is https: and its host is in the plc policy’s host list. get uses policy plc when the request target is plc, and atproto otherwise. A body cap in this file is 64 KiB, and the call also passes Math.min(request.maxBytes, MAX_BYTES). txt uses resolveTxt. Net-guard errors map through the FAILURE record onto unavailable, refused and no_such_host. Any other thrown value is rethrown.

createOAuthClient builds NodeOAuthClient with the caller’s state store, session store, requestLock, fetch, and the resolvers from identity-resolvers.ts. It passes didCache and handleCache as NO_CACHE, whose get, set and del each resolve to undefined. onSessionDeleted logs a reason word. ownIssuerOnly sends the library’s fetch only when the URL origin equals ownIssuer.

authorize returns the URL only when its query has request_uri and no code_challenge. Otherwise it logs oauth.authorize_failed with kind ParMissingError and returns { ok: false, reason: "failed" }. A URL with no request_uri fails that check. A non-PAR URL that already names a request_uri fails it too: when the server offers no PAR endpoint and does not require PAR, the library copies the request onto the authorization endpoint, including code_challenge.

oauthFields allows OAUTH_ALLOW_HTTP: true only when UNSET_ENV is dev. deployment/preflight/checks/local-only-keys.ts (C29) refuses that key unless the stage is local. interfaces/web/src/lib/server/compose.ts passes cfg.OAUTH_ALLOW_HTTP as allowHttp.

createPdsCall takes endSessions and tokenSetRemains as arguments. The file’s comment says this package does not import infrastructure/session. The infrastructure row allows net-guard and seal beside the package’s own folder, not session.

May import

The infrastructure row. This package imports net-guard and does not import seal or postgres.

Declared in infrastructure/pds/package.json:

DependencyVersion
@atproto/api0.29.1
@atproto/jwk-jose0.2.4
@atproto/oauth-client-node0.5.12
@atproto/oauth-scopes0.5.14
@unset/domains-identityworkspace
@unset/infrastructure-net-guardworkspace
@unset/shared-configworkspace
@unset/shared-errorsworkspace
@unset/shared-lexiconsworkspace
@unset/shared-logworkspace

vendor-sdk-one-adapter confines @atproto/oauth-client-node and @atproto/api to this folder. pds-call.guard.test.ts walks .ts and .tsx from the repository root. It skips node_modules, dist, .git, tests and *.test.ts. It allows client.restore( or @atproto/api together with new Agent( only in infrastructure/pds/pds-call.ts.

Entry points

RolePath
Package export .infrastructure/pds/index.ts
Compositioninterfaces/web/src/lib/server/compose.ts

No main.ts and no Compose service for this package. The pds service in deployment/compose.dev.yaml runs the first-party ghcr.io/undefined6799/unset/pds image by lock digest, built from deployment/pds/pds.Dockerfile (P2.24y), not this folder. deployment/compose.dev.source.yaml builds pds from deployment/pds/pds.Dockerfile.

Data

No SQL in this package. The OAuth state and token-set stores are infrastructure/postgres/oauthStores.ts, passed in. Tables app.oauth_state and app.oauth_session are on the postgres page. createPdsCall’s endSessions is how a dead grant reaches infrastructure/session destroyAllForDid; the function is an argument, not an import.