A GenServer that keeps an OAuth session fresh for long-running applications.

The manager is opt-in: the SDK starts no processes on its own, so add it to the host application's supervision tree:

children = [
  {Registry, keys: :unique, name: MyApp.OAuthRegistry},
  {ProtoRune.Atproto.OAuth.SessionManager,
   session: session,
   client: client,
   store: {ProtoRune.Security.TokenStore.Dets, path: "/var/myapp/tokens.dets"},
   key: key,
   registry: MyApp.OAuthRegistry}
]

It schedules a refresh at 75% of the remaining token lifetime (from the session's expires_at; a 30 minute lifetime is assumed when the session carries none), rotates the tokens through ProtoRune.Atproto.OAuth.refresh/2 and persists each new session through the configured ProtoRune.Security.TokenStore backend under the session's DID.

Sessions are always encrypted at rest: the serialized session is encrypted with ProtoRune.Security.Crypto before it reaches the store, so TokenStore backends never see plaintext. This is mandatory because the session's dpop_key is private key material, as sensitive as the tokens themselves.

When a refresh fails the manager stops with {:refresh_failed, reason} and lets the supervisor decide the restart policy. logout/1 revokes the refresh token (best effort: a revocation failure does not block the logout), deletes the stored session and stops the process.

Hosts that manage their own processes can keep calling ProtoRune.Atproto.OAuth.refresh/2 and ProtoRune.Atproto.OAuth.revoke/2 directly; the manager only composes them.

Options

• :session - Required. The ProtoRune.Atproto.OAuth.Session to manage.
• :client - Required. The ProtoRune.Atproto.OAuth.Client the session was issued to.
• :store - Required. A {module, opts} ProtoRune.Security.TokenStore backend used to persist each refreshed session under its DID.
• :key - Required. A ProtoRune.Security.Crypto key used to encrypt every persisted session. Generate one with ProtoRune.Security.generate_key/0 and keep it outside the token storage (see ProtoRune.Security).
• :registry - Optional name of a Registry started by the host application. When given, the manager registers itself under the session's DID and can be addressed with {:via, Registry, {registry, did}}. The SDK never starts a Registry itself.
• :refresh_fraction - Fraction of the remaining token lifetime to wait before refreshing (default 0.75). Mainly a testing escape hatch.

Telemetry

The manager emits :telemetry events following the same span conventions as the bot framework (see the ProtoRune.Bot moduledoc):

• [:proto_rune, :oauth, :refresh, :start] / :stop / :exception - wrap each token refresh via :telemetry.span/3. Metadata: :did; stop events for failed refreshes also carry :error.
• [:proto_rune, :oauth, :revoke, :start] / :stop / :exception - wrap the revocation performed by logout/1. Same metadata conventions as the refresh events.