Base

mail_intake.auth.base

Summary

Authentication provider contracts for Mail Intake.

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

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

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.