Exosphere.ATProto.OAuth.ServerMetadata (Exosphere v0.4.0)

Copy Markdown View Source

Authorization Server and Resource Server metadata (RFC 8414 + the OAuth-Protected-Response draft used by ATProto).

ATProto authorization servers publish their capabilities at /.well-known/oauth-authorization-server, and PDSs (as resource servers) publish their authorization server at /.well-known/oauth-protected-resource. Both documents are validated strictly against the ATProto OAuth profile before use: the issuer must match the origin the document was fetched from, and the declared features (PAR, PKCE, DPoP/ES256, private_key_jwt, the atproto scope, the authorization-response iss parameter) must all be supported.

Summary

Types

t()

Functions

fetch(origin, opts \\ [])

Fetch and validate the Authorization Server metadata document for a server origin.

fetch_authorization_server(pds_origin, opts \\ [])

Fetch a PDS's Resource Server metadata (/.well-known/oauth-protected-resource) and return the authorization server origin it declares.

from_map(map)

Rebuild metadata serialized with to_map/1.

supported_scopes(server_metadata, desired)

The scopes to request: the intersection of the client's desired scopes with those the server supports.

to_map(metadata)

The metadata as a plain, Jason-encodable map for persistence. The raw document is dropped — the validated fields are what clients rely on.

validate(body, origin)

Validate a parsed Authorization Server metadata document against the ATProto OAuth profile requirements.

Types

t()

@type t() :: %Exosphere.ATProto.OAuth.ServerMetadata{
  authorization_endpoint: String.t(),
  issuer: String.t(),
  pushed_authorization_request_endpoint: String.t(),
  raw: map(),
  scopes_supported: [String.t()],
  token_endpoint: String.t()
}

Functions

fetch(origin, opts \\ [])

@spec fetch(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Fetch and validate the Authorization Server metadata document for a server origin.

origin is the server's scheme://host[:port] root (e.g. "https://bsky.social"). The document's issuer must equal this origin.

fetch_authorization_server(pds_origin, opts \\ [])

@spec fetch_authorization_server(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Fetch a PDS's Resource Server metadata (/.well-known/oauth-protected-resource) and return the authorization server origin it declares.

Per the spec the list must contain exactly one origin URL. Returns {:error, :protected_resource_metadata_not_found} when the PDS hosts its own authorization server (HTTP 404).

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, :invalid_server_metadata}

Rebuild metadata serialized with to_map/1.

supported_scopes(server_metadata, desired)

@spec supported_scopes(t(), [String.t()]) :: [String.t()]

The scopes to request: the intersection of the client's desired scopes with those the server supports.

to_map(metadata)

@spec to_map(t()) :: map()

The metadata as a plain, Jason-encodable map for persistence. The raw document is dropped — the validated fields are what clients rely on.

validate(body, origin)

@spec validate(map(), String.t()) :: {:ok, t()} | {:error, term()}

Validate a parsed Authorization Server metadata document against the ATProto OAuth profile requirements.