Google

mail_intake.auth.google

Summary

Google authentication provider implementation for Mail Intake.

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.