Skip to content

# Store

## `` mail_intake.credentials.store

### Summary

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.

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