69 lines
2.2 KiB
Python
69 lines
2.2 KiB
Python
"""
|
|
# 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.
|
|
"""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import Generic, TypeVar
|
|
|
|
T = TypeVar("T")
|
|
|
|
|
|
class MailIntakeAuthProvider(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.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def get_credentials(self) -> T:
|
|
"""
|
|
Retrieve valid, provider-specific credentials.
|
|
|
|
Returns:
|
|
T:
|
|
Credentials of type `T` suitable for immediate use by the
|
|
corresponding mail adapter.
|
|
|
|
Raises:
|
|
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.
|
|
"""
|
|
raise NotImplementedError
|