Module token 

Token exchange, refresh, and what a token response has to prove.

The validation here is stricter than “did it parse”, because several fields are load-bearing in ways that fail silently if waved through:

• token_type must be exactly DPoP. Accepting Bearer discards the proof-of-possession binding — the only thing making a stolen access token useless.
• scope must contain atproto, and the granted scope is what gets stored. Recording the requested scope instead means a narrowed grant is discovered as a mystery failure much later.
• sub must be a well-formed atproto DID before it becomes a database key.
• id_token must be absent — its presence means the server thinks it is doing OIDC, and nothing good follows from proceeding.
• expires_in is optional; a missing one means no proactive refresh, not a fabricated expiry.

Structs

TokenResponse

A validated token response.

Enums

RefreshFailure

What a failed refresh means for the stored session.

Constants

MIN_REFRESH_MARGIN_SECS

Refresh at least this far ahead of expiry.

REFRESH_JITTER_SECS

Extra, randomized margin on top of MIN_REFRESH_MARGIN_SECS.

Functions

classify_refresh_failure

Classify a failed refresh.

is_stale

Whether a session should be refreshed now.

is_stale_with_margin

Whether a session should be refreshed now, against an explicit margin.

parse_token_response

Validate a token response before anything is stored or sent.

refresh_margin

A jittered refresh margin.

refresh_request_params

Form parameters for a refresh.

token_request_params

Form parameters for the authorization-code exchange.