Google

mail_intake.auth.google

Google authentication provider implementation for Mail Intake.

---

Summary

This module provides a Google OAuth–based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including: - Credential loading and persistence - Token refresh handling - Interactive OAuth flow initiation - Coordination with a credential persistence layer

No Google authentication details should leak outside this module.

Classes

MailIntakeGoogleAuth

MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available
- Refresh expired credentials when possible
- Initiate an interactive OAuth flow only when required
- Persist refreshed or newly obtained credentials via the store

Guarantees:

- This class is synchronous by design and maintains a minimal internal state

Initialize the Google authentication provider.

Parameters:

Name	Type	Description	Default
credentials_path	str	Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.	required
store	CredentialStore[Credentials]	Credential store responsible for persisting and retrieving Google OAuth credentials.	required
scopes	Sequence[str]	OAuth scopes required for Gmail access.	required

Functions

get_credentials

get_credentials() -> Any

Retrieve valid Google OAuth credentials.

Returns:

Name	Type	Description
Credentials	Any	A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type	Description
MailIntakeAuthError	If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store
- Refresh expired credentials when possible
- Perform an interactive OAuth login as a fallback
- Persist valid credentials for future use