oauth/io.github.kikin81.atproto.oauth/DiscoveryChain

DiscoveryChain

class DiscoveryChain(httpClient: HttpClient, json: Json = Json { ignoreUnknownKeys = true })

Implements the AT Protocol discovery chain:

Handle → DID: HTTP fallback via /.well-known/atproto-did on the handle's domain. (DNS _atproto.<handle> TXT is preferred but requires a DNS library; HTTP fallback covers all cases.)
DID → PDS: Fetch the DID document from plc.directory (for did:plc) or the DID method's resolution endpoint, extract the #atproto_pds service endpoint.
PDS → Auth Server: Fetch /.well-known/oauth-protected-resource → authorization_servers[0], then /.well-known/oauth-authorization-server → extract all OAuth endpoint URLs.
Bidirectional handle verification: verify the DID document's alsoKnownAs field claims the original handle.

For signup flows where no handle/DID is known up front, use resolveKnownAuthServer to short-circuit the chain and fetch only the auth-server metadata; identity is hydrated post-token-exchange via hydrateIdentityFromDid.

Constructors

DiscoveryChain

constructor(httpClient: HttpClient, json: Json = Json { ignoreUnknownKeys = true })

Functions

resolve

suspend fun resolve(handleOrDid: String): AuthServerMetadata

Resolves a handle or DID all the way to a fully-populated AuthServerMetadata ready for the OAuth flow.

resolveKnownAuthServer

suspend fun resolveKnownAuthServer(authServerUrl: String): AuthServerMetadata

Short-circuits the discovery chain for flows where the auth server is already known (e.g. signup, where the user has no handle/DID yet). Fetches only the auth-server metadata; AuthServerMetadata.did, AuthServerMetadata.handle, and AuthServerMetadata.pdsUrl are left null — populate them post-token-exchange via hydrateIdentityFromDid.