atproto_oauth library

Classes

DPoPKeyPair

An encoded DPoP key pair. The encoding is opaque to callers and is interpreted only by the DPoPSigner that produced it, so a signer backed by a keystore may return handles/references rather than raw key material.

DPoPNonceCache

Caches the most recent DPoP nonce per URL origin (RFC 9449 §8). The authorization server and the PDS have distinct origins, so their nonces never collide — fixing the refresh/API nonce ping-pong.

DPoPSigner

Generates DPoP key pairs and signs DPoP proof JWTs (RFC 9449). Inject a custom implementation to sign with a platform keystore / non-extractable key. The DPoPKeyPair strings are opaque to everyone but the signer.

HttpIdentityResolver

Default HTTP-based IdentityResolver: handle→DID via com.atproto.identity.resolveHandle, DID document via the PLC directory (did:plc) or well-known/path location (did:web), then the #atproto_pds service endpoint. When starting from a handle, verifies the DID document claims the handle back through alsoKnownAs.

IdentityResolver

Resolves a handle or DID to its atproto identity.

InMemoryDPoPNonceCache

Process-memory DPoPNonceCache.

InMemoryOAuthSessionStore

Process-memory OAuthSessionStore. Sessions are lost on restart.

InMemoryOAuthStateStore

Process-memory OAuthStateStore. State is lost on restart.

OAuthClient

A customizable, dependency-injected atproto OAuth 2.0 client.

OAuthClientMetadata

OAuthContext

Per-authorization state that must be carried from authorize to callback.

OAuthServerMetadata

OAuth 2.0 Authorization Server Metadata (RFC 8414).

OAuthSession

A class that manages OAuth 2.0 session information with DPoP (Demonstrating Proof of Possession) support.

OAuthSessionManager

Owns an OAuth session's lifecycle for API use: builds DPoP Authorization headers per request (nonce cached per origin) and refreshes the access token before it expires or on a 401. atproto_core delegates to this.

OAuthSessionStore

Persists OAuthSessions keyed by account sub (DID). Inject a secure implementation (e.g. platform keychain) to persist across restarts — sessions contain the DPoP private key and tokens.

OAuthStateStore

Persists per-authorization OAuthContext between authorize and callback, keyed by the OAuth state parameter. Inject a durable implementation to support callbacks that arrive after an app restart.

PointyCastleDPoPSigner

Default DPoPSigner: EC P-256 / ES256 via pointycastle, reusing the library's existing key encoding and proof helpers.

ResolvedIdentity

The outcome of resolving a handle or DID to its atproto identity.

Extensions

OAuthClientMetadataPatterns on OAuthClientMetadata

Adds pattern-matching-related methods to OAuthClientMetadata.

OAuthContextPatterns on OAuthContext

Adds pattern-matching-related methods to OAuthContext.

Functions

getClientMetadata(String clientId, {Client? client}) → Future<OAuthClientMetadata>

Retrieves OAuth 2.0 client metadata from a client configuration endpoint.

getDPoPHeader({required String clientId, required String endpoint, required String method, String? dPoPNonce, String? authorizationServer, String? accessToken, required String publicKey, required String privateKey}) → String

Generates a DPoP (Demonstrating Proof-of-Possession) proof JWT header for OAuth 2.0 requests.

Exceptions / Errors

OAuthException

OAuthSessionRevokedException

Thrown when a refresh fails with invalid_grant or the session has been revoked. The session has been removed from the session store; callers should route the user back through authorize.