Auth

mail_intake.auth

Authentication provider implementations for Mail Intake.

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes: - A stable, provider-agnostic authentication contract - Concrete authentication providers for supported platforms

Authentication providers: - Are responsible for credential acquisition and lifecycle management - Are intentionally decoupled from adapter logic - May be extended by users to support additional providers

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

MailIntakeAuthProvider

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Authentication providers encapsulate all logic required to: - Acquire credentials from an external provider - Refresh or revalidate credentials as needed - Handle authentication-specific failure modes - Coordinate with credential persistence layers where applicable

Mail adapters must treat returned credentials as opaque and provider-specific, relying only on the declared credential type expected by the adapter.

get_credentials `abstractmethod`

get_credentials() -> T

Retrieve valid, provider-specific credentials.

This method is synchronous by design and represents the sole entry point through which adapters obtain authentication material.

Implementations must either return credentials of the declared type T that are valid at the time of return or raise an authentication-specific exception.

Returns:

Type	Description
`T`	Credentials of type `T` suitable for immediate use by the
`T`	corresponding mail adapter.

Raises:

Type	Description
`Exception`	An authentication-specific exception indicating that credentials could not be obtained or validated.

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.

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

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[Any]`	Credential store responsible for persisting and retrieving Google OAuth credentials.	required
`scopes`	`Sequence[str]`	OAuth scopes required for Gmail access.	required

get_credentials

get_credentials() -> Any

Retrieve valid Google OAuth credentials.

This method attempts to: 1. Load cached credentials from the configured credential store 2. Refresh expired credentials when possible 3. Perform an interactive OAuth login as a fallback 4. Persist valid credentials for future use