Skip to content

# Credentials

## `` mail_intake.credentials

### Summary

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.

### Public API

- `CredentialStore`
- `PickleCredentialStore`
- `RedisCredentialStore`

### Classes

#### `` CredentialStore

Bases: `ABC`, `Generic[T]`

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

    1
    2
    3

    - Provide persistent storage separating life-cycle management from
      storage mechanics.
    - Keep implementation focused only on persistence.

Constraints:

    1
    2
    3
    4

    - 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.

##### Functions

###### `` clear `abstractmethod`

    1

    clear() -> None

Remove any persisted credentials from the store.

Notes

Lifecycle:

    1
    2

    - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable
    - Must ensure that no stale authentication material remains accessible

Guarantees:

    1

    - Implementations should treat this operation as idempotent

###### `` load `abstractmethod`

    1

    load() -> Optional[T]

Load previously persisted credentials.

Returns:

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

Notes

Guarantees:

    1
    2
    3
    4
    5

    - 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.

###### `` save `abstractmethod`

    1

    save(credentials: T) -> None

Persist credentials to the underlying storage backend.

Parameters:

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

Notes

Lifecycle:

    1

    - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence

Responsibilities:

    1
    2
    3

    - Ensuring durability appropriate to the deployment context
    - Applying encryption or access controls where required
    - Overwriting any previously stored credentials

#### `` PickleCredentialStore

    1

    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.

Notes

Guarantees:

    1
    2
    3

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

Constraints:

    1
    2

    - 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

##### Functions

###### `` clear

    1

    clear() -> None

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

    1

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

###### `` load

    1

    load() -> Optional[T]

Load credentials from the local filesystem.

Returns:

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

Notes

Guarantees:

    1
    2
    3
    4

    - 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.

###### `` save

    1

    save(credentials: T) -> None

Persist credentials to the local filesystem.

Parameters:

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

Notes

Responsibilities:

    1

    - Any previously stored credentials at the configured path are overwritten

#### `` RedisCredentialStore

    1

    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.

Notes

Responsibilities:

    1
    2
    3

    - 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.

Guarantees:

    1
    2
    3
    4

    - 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.

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`

##### Functions

###### `` clear

    1

    clear() -> None

Remove stored credentials from Redis.

Notes

Lifecycle:

    1
    2

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

###### `` load

    1

    load() -> Optional[T]

Load credentials from Redis.

Returns:

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

Notes

Guarantees:

    1
    2
    3
    4
    5
    6

    - 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.

###### `` save

    1

    save(credentials: T) -> None

Persist credentials to Redis.

Parameters:

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

Notes

Responsibilities:

    1
    2

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