91 lines
3.1 KiB
Python
91 lines
3.1 KiB
Python
"""
|
|
Credential persistence abstractions for Mail Intake.
|
|
|
|
This module defines the generic persistence contract used to store and
|
|
retrieve authentication credentials across Mail Intake components.
|
|
|
|
The ``CredentialStore`` abstraction establishes a strict separation
|
|
between credential *lifecycle management* and credential *storage*.
|
|
Authentication providers are responsible for acquiring, validating,
|
|
refreshing, and revoking credentials, while concrete store
|
|
implementations are responsible solely for persistence concerns.
|
|
|
|
By remaining agnostic to credential structure, serialization format,
|
|
and storage backend, this module enables multiple persistence
|
|
strategies—such as local files, in-memory caches, distributed stores,
|
|
or secrets managers—without coupling authentication logic to any
|
|
specific storage mechanism.
|
|
"""
|
|
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import Generic, Optional, TypeVar
|
|
|
|
T = TypeVar("T")
|
|
|
|
|
|
class CredentialStore(ABC, Generic[T]):
|
|
"""
|
|
Abstract base class defining a generic persistence interface for
|
|
authentication credentials.
|
|
|
|
This interface separates *credential lifecycle management* from
|
|
*credential storage mechanics*. Implementations are responsible
|
|
only for persistence concerns, while authentication providers
|
|
retain full control over credential creation, validation, refresh,
|
|
and revocation logic.
|
|
|
|
The store is intentionally agnostic to:
|
|
- The concrete credential type being stored
|
|
- The serialization format used to persist credentials
|
|
- The underlying storage backend or durability guarantees
|
|
"""
|
|
|
|
@abstractmethod
|
|
def load(self) -> Optional[T]:
|
|
"""
|
|
Load previously persisted credentials.
|
|
|
|
Implementations should return ``None`` when no credentials are
|
|
present or when stored credentials cannot be successfully
|
|
decoded or deserialized.
|
|
|
|
The store must not attempt to validate, refresh, or otherwise
|
|
interpret the returned credentials.
|
|
|
|
Returns:
|
|
An instance of type ``T`` if credentials are available and
|
|
loadable; otherwise ``None``.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def save(self, credentials: T) -> None:
|
|
"""
|
|
Persist credentials to the underlying storage backend.
|
|
|
|
This method is invoked when credentials are newly obtained or
|
|
have been refreshed and are known to be valid at the time of
|
|
persistence.
|
|
|
|
Implementations are responsible for:
|
|
- Ensuring durability appropriate to the deployment context
|
|
- Applying encryption or access controls where required
|
|
- Overwriting any previously stored credentials
|
|
|
|
Args:
|
|
credentials:
|
|
The credential object to persist.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def clear(self) -> None:
|
|
"""
|
|
Remove any persisted credentials from the store.
|
|
|
|
This method is called when credentials are known to be invalid,
|
|
revoked, corrupted, or otherwise unusable, and must ensure that
|
|
no stale authentication material remains accessible.
|
|
|
|
Implementations should treat this operation as idempotent.
|
|
"""
|