Skip to content

# 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:

    1
    2
    3
    4

    - 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:

    1
    2
    3
    4

    - 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`

    1

    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:

    1
    2
    3
    4
    5

    - 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

    1

    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:

    1
    2
    3
    4

    - 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:

    1
    2

    - 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

    1

    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:

    1
    2
    3
    4

    - 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.