Skip to content

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.

  1. Look up the OAuthProvider
  2. Resolve client credentials (arg → stored → env)
  3. Build auth URL and open the user's browser
  4. Start localhost callback server and wait for the code
  5. Exchange the code for tokens
  6. 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:

  1. Build consent URL
  2. Start localhost callback server
  3. Open browser to consent URL
  4. Wait for Google to redirect with ?code=...
  5. Exchange code for access_token + refresh_token
  6. Save tokens to credentials_path
  7. 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.