Expand description
OAuth device flow (RFC 8628) for a Mac app that signs in to a provider (GitHub first: a GitHub App’s user-to-server
token), with no client secret on the Mac. The rules live here, with no network: the app gives a Transport (one
form POST that answers JSON), and the tokens are kept through crate::secrets::SecretStore (the Keychain), on the
Rust side only — the page sees Session (connected as whom), never a token.
Steps: start asks a code; the app shows DeviceCode::user_code and DeviceCode::verification_uri;
wait polls (honouring slow_down, stopping on expired_token / access_denied); TokenVault::save keeps the
tokens; TokenVault::access_token returns a valid one, refreshing it when it is about to expire;
TokenVault::sign_out removes both secrets (revoking at the provider is the person’s, in its settings).
Structs§
- Device
Code - What the person sees: the code to type and where.
- Provider
- A provider’s two endpoints and the app’s public client id (no secret: the device flow has none).
- Session
- What the page may know: whether the person is connected, never a token.
- Token
Vault - The tokens in a
SecretStore(the Keychain), under<prefix>.access/.refresh/.expires. - Tokens
- The tokens, with the instant (unix seconds) the access token stops being valid; the refresh token is optional (a provider without expiring tokens gives none).
- Transport
Error - The app’s HTTP client could not do the request (offline, refused, not JSON…). The text is the client’s own.
Enums§
- Failure
- How the flow ends when it is not a token.
- Vault
Error - Why the token vault failed: the secret store, or the refresh the vault tried.
Constants§
- DEFAULT_
EXPIRES_ IN - How long a device code lives when the provider does not say.
- DEFAULT_
INTERVAL - The smallest wait between two polls, whatever the provider says (it asks 5 s).
- REFRESH_
MARGIN - A token is refreshed this many seconds before it expires.
- SLOW_
DOWN_ STEP - Added to the interval on
slow_down.
Traits§
- Transport
- One form POST that answers JSON (
Accept: application/json). The app supplies it (ureq, reqwest…); tests mock it.
Functions§
- refresh
- Exchange a refresh token for a new pair (the provider rotates the refresh token: the old one is spent).
- start
- Step 1: ask the provider for a device and user code.
- wait
- Step 2: poll until the person approves, the code expires or the request is denied.
sleepandnoware the app’s (tests pass a recorder and a counter),cancelledlets the window close the wait.