67 lines
2.1 KiB
Python
67 lines
2.1 KiB
Python
"""
|
|
Authentication provider contracts for Mail Intake.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
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
|