Module oauth 

OAuth token acquisition for auth.oauth’s three supported grants — client_credentials, password, and authorization_code — and OAuthTokenCache, the in-run, in-memory cache that lets many requests sharing one oauth: config reuse one token instead of re-authenticating per request.

client_credentials and password acquire automatically. acquire_token makes the token request itself, with no human involved — the shape crate::Request::resolve_oauth calls before every send.

authorization_code cannot acquire automatically. It needs a human to approve access in a browser and a local callback listener to catch the resulting code — a fundamentally different problem from making an HTTP call, and not something a headless send can do on its own. acquire_token refuses this grant outright (see its doc comment) rather than pretend it can proceed; instead, three building blocks let a front end — sendra-tui, concretely — drive the flow itself: generate_pkce (a fresh verifier/challenge pair — see RFC 7636), build_authorization_url (the URL to open a browser to), and exchange_authorization_code (trading the code the callback caught for a token). Once that exchange succeeds, OAuthTokenCache::insert_token puts the result in the exact same cache acquire_token reads, so every later request sharing this oauth: config — via the ordinary resolve_oauth path, completely unchanged — reuses it instead of asking the human to log in again.

PKCE is used unconditionally for authorization_code, not offered as a config toggle: RFC 8252 §8.1 (OAuth for native apps) treats it as required for exactly this kind of client, since a desktop/TUI app cannot keep a client_secret confidential the way a server-side client can, and is equally exposed to authorization-code interception on the loopback redirect either way.

refresh_token is not implemented: once expiry-checking exists here, it is not worth its own scope for the marginal request refresh_token would save over just re-running the same grant (or, for authorization_code, logging in again), so it is deferred rather than treated as a real gap.

No cross-invocation persistence. OAuthTokenCache lives only as long as the process that built it — never written to disk — the same conservative stance this project already takes on captured variables and the cookie jar: new statefulness is opt-in and scoped to one run, not silently carried between separate sendra invocations. A cached token on disk would need the same protection ${VAR} passthrough was designed around, for a feature nothing has asked for yet. This holds just as much for a token acquired interactively through authorization_code: it lives only in this cache, for this run, and is never written anywhere.

Structs

OAuthTokenCache

The in-run OAuth token cache: acquired (or failed) tokens, keyed by [CacheKey], shared by every request in one sendra invocation that resolves the same oauth: config.

PkcePair

A fresh PKCE verifier/challenge pair for one authorization_code login attempt (RFC 7636) — see the module doc comment for why this is used unconditionally rather than offered as config.

Functions

acquire_token

Acquire (or reuse a cached) access token for auth.

build_authorization_url

The URL to open a browser to for one authorization_code login attempt: auth.authorization_url with response_type=code, client_id, redirect_uri, code_challenge/code_challenge_method=S256 (from generate_pkce), state (from generate_state), and scope when auth has one, appended as query parameters — the standard shape an OAuth 2.0 authorization request takes (RFC 6749 §4.1.1) plus PKCE’s two parameters (RFC 7636 §4.3).

exchange_authorization_code

A code exchanged for exchange_authorization_code, obtained interactively (see the module doc comment) rather than from auth.oauth itself, so it cannot travel through OAuthAuth the way every other grant’s fields do.

generate_pkce

generate_state

A fresh CSRF state value for one authorization_code login attempt (RFC 6749 §10.12) — checked against the callback’s own state parameter by whichever front end ran build_authorization_url, not by anything in this module, since holding onto the value being checked against is specific to how that front end tracks a pending login.