oauth
diapason.connectors.oauth
¶
Shared OAuth 2.0 helpers for all connectors.
Provides:
- OAuthProvider registry with configs for Google, Strava, Spotify
- Generic run_connector_oauth() that opens browser + catches callback
- URL builder, token persistence, and token cleanup utilities
OAuthProvider
dataclass
¶
Configuration for an OAuth 2.0 provider.
build_google_auth_url(client_id, redirect_uri=_DEFAULT_REDIRECT_URI, scopes=None)
¶
Build a Google OAuth2 consent URL.
Parameters¶
client_id:
The OAuth 2.0 client ID from the Google Cloud Console.
redirect_uri:
Where Google should redirect after consent. Defaults to the local
callback server at http://localhost:8789/callback.
scopes:
List of OAuth scopes to request. Defaults to
["openid", "email", "profile"].
Returns¶
str Full consent URL including query string.
delete_tokens(path)
¶
Delete the credentials file at path if it exists.
exchange_google_token(code, client_id, client_secret, redirect_uri=_DEFAULT_REDIRECT_URI)
¶
Exchange an authorization code for access + refresh tokens.
Parameters¶
code: The authorization code received from Google's consent redirect. client_id: OAuth 2.0 client ID. client_secret: OAuth 2.0 client secret. redirect_uri: Must match the redirect URI used when obtaining the auth code.
Returns¶
dict
Token response containing access_token, refresh_token,
token_type, and expires_in.
get_client_credentials(provider)
¶
Load stored client_id and client_secret for provider.
Checks credential files in ~/.diapason/connectors/ and falls
back to environment variables DIAPASON_{NAME}_CLIENT_ID and
DIAPASON_{NAME}_CLIENT_SECRET.
get_provider_for_connector(connector_id)
¶
Return the OAuthProvider that covers connector_id, or None.
load_tokens(path)
¶
Load OAuth tokens from a JSON file.
Returns None if the file is missing, unreadable, or contains
invalid JSON.
refresh_google_token(path)
¶
Refresh a Google access token using the stored refresh token.
Reads the credentials file at path, exchanges its refresh_token
(plus client_id/client_secret) for a new access_token
against Google's OAuth token endpoint, persists the refreshed payload
back to path, and returns the new access token.
Returns None if any required field is missing or the refresh call
fails (network error or Google returns a non-2xx response — typically
invalid_grant when the refresh token has been revoked).
resolve_google_credentials(connector_path)
¶
Return the best available Google credentials file path.
Checks the connector-specific file first, then falls back to the
shared google.json. Returns connector_path if neither exists
(so is_connected() correctly returns False).
run_connector_oauth(connector_id, client_id='', client_secret='')
¶
Run a complete OAuth flow for connector_id.
- Look up the
OAuthProvider - Resolve client credentials (arg → stored → env)
- Build auth URL and open the user's browser
- Start localhost callback server and wait for the code
- Exchange the code for tokens
- Save tokens to all relevant credential files
Returns the raw token response dict.
run_oauth_flow(client_id, client_secret, scopes, credentials_path, redirect_uri=_DEFAULT_REDIRECT_URI)
¶
Run the full OAuth flow: browser consent, callback, token exchange.
Steps:
- Build consent URL
- Start localhost callback server
- Open browser to consent URL
- Wait for Google to redirect with
?code=... - Exchange code for
access_token+refresh_token - Save tokens to credentials_path
- Return the tokens dict
Parameters¶
client_id:
OAuth 2.0 client ID.
client_secret:
OAuth 2.0 client secret.
scopes:
List of OAuth scopes to request.
credentials_path:
Where to persist the resulting tokens.
redirect_uri:
Local callback URI. Defaults to http://localhost:8789/callback.
Returns¶
dict
Token response from Google (access_token, refresh_token, etc.).
Raises¶
RuntimeError If the user denies authorization or the callback times out.
save_client_credentials(provider, client_id, client_secret)
¶
Persist client credentials so the user never has to enter them again.
save_tokens(path, tokens)
¶
Persist tokens to path as JSON with owner-only (0o600) permissions.
Creates parent directories as needed.