Auth

mail_intake.auth

Summary

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.

---

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.