Auth

mail_intake.auth

Authentication provider implementations for Mail Intake.

---

Summary

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.

---

Public API

MailIntakeAuthProvider
MailIntakeGoogleAuth

---

Classes

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.

Notes

Responsibilities:

- Acquire credentials from an external provider
- Refresh or revalidate credentials as needed
- Handle authentication-specific failure modes
- Coordinate with credential persistence layers where applicable

Constraints:

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

Functions

get_credentials abstractmethod

get_credentials() -> T

Retrieve valid, provider-specific credentials.

Returns:

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

Raises:

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

Notes

Guarantees:

- This method is synchronous by design
- 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 exception

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

• Base
• Google