docs(api): update package docs for credential store–based auth design

- Update package-level documentation to reflect credential persistence
  as a first-class concept
- Replace token_path-based examples with CredentialStore usage
- Add credentials module to documented public API surface
- Clarify auth vs credential persistence responsibilities
- Align design guarantees with distributed-safe authentication model
This commit is contained in:
2026-01-10 16:44:20 +05:30
parent 91eab636bb
commit 985194cd5b
2 changed files with 41 additions and 10 deletions

View File

@@ -1,8 +1,29 @@
"""
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 filesystembased 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.
"""
from mail_intake.credentials.store import CredentialStore
from mail_intake.credentials.pickle import PickleCredentialStore
from mail_intake.credentials.redis import RedisCredentialStore
from google.oauth2.credentials import Credentials
GoogleCredentialStore = CredentialStore[Credentials]
"""
__all__ = [
"CredentialStore",
"PickleCredentialStore",
"RedisCredentialStore",
]