Credentials

mail_intake.credentials

Credential persistence interfaces and implementations for Mail Intake.

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides: - A generic CredentialStore abstraction defining the persistence contract - Local filesystem–based storage for development and single-node use - Distributed, Redis-backed storage for production and scaled deployments

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

CredentialStore

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

clear abstractmethod

clear() -> 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.

load abstractmethod

load() -> 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:

Type	Description
Optional[T]	An instance of type T if credentials are available and
Optional[T]	loadable; otherwise None.

save abstractmethod

save(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

Parameters:

Name	Type	Description	Default
credentials	T	The credential object to persist.	required

PickleCredentialStore

PickleCredentialStore(path: str)

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

This implementation: - Stores credentials on the local filesystem - Uses pickle for serialization and deserialization - Does not provide encryption, locking, or concurrency guarantees

Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class.

Initialize a pickle-backed credential store.

Parameters:

Name	Type	Description	Default
path	str	Filesystem path where credentials will be stored. The file will be created or overwritten as needed.	required

clear

clear() -> None

Remove persisted credentials from the local filesystem.

This method deletes the credential file if it exists and should be treated as an idempotent operation.

load

load() -> Optional[T]

Load credentials from the local filesystem.

If the credential file does not exist or cannot be successfully deserialized, this method returns None.

The store does not attempt to validate or interpret the returned credentials.

Returns:

Type	Description
Optional[T]	An instance of type T if credentials are present and
Optional[T]	successfully deserialized; otherwise None.

save

save(credentials: T) -> None

Persist credentials to the local filesystem.

Any previously stored credentials at the configured path are overwritten.

Parameters:

Name	Type	Description	Default
credentials	T	The credential object to persist.	required

RedisCredentialStore

RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

The store is intentionally generic and delegates all serialization concerns to caller-provided functions. This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited.

This class is responsible only for persistence and retrieval. It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored.

Initialize a Redis-backed credential store.

Parameters:

Name	Type	Description	Default
redis_client	Any	An initialized Redis client instance (for example, redis.Redis or a compatible interface) used to communicate with the Redis server.	required
key	str	The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.	required
serialize	Callable[[T], bytes]	A callable that converts a credential object of type T into a bytes representation suitable for storage in Redis.	required
deserialize	Callable[[bytes], T]	A callable that converts a bytes payload retrieved from Redis back into a credential object of type T.	required
ttl_seconds	Optional[int]	Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If None, credentials are stored without an expiration.	None

clear

clear() -> None

Remove stored credentials from Redis.

This operation deletes the configured Redis key if it exists. Implementations should treat this method as idempotent.

load

load() -> Optional[T]

Load credentials from Redis.

If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns None.

The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable.

Returns:

Type	Description
Optional[T]	An instance of type T if credentials are present and
Optional[T]	successfully deserialized; otherwise None.

save

save(credentials: T) -> None

Persist credentials to Redis.

Any previously stored credentials under the same key are overwritten. If a TTL is configured, the credentials will expire automatically after the specified duration.

Parameters:

Name	Type	Description	Default
credentials	T	The credential object to persist.	required