refactor(auth): type auth providers and decouple Google auth from disk storage

- Make MailIntakeAuthProvider generic over credential type to enforce
  typed auth contracts between providers and adapters
- Refactor Google OAuth provider to use CredentialStore abstraction
  instead of filesystem-based pickle persistence
- Remove node-local state assumptions from Google auth implementation
- Clarify documentation to distinguish credential lifecycle from
  credential persistence responsibilities

This change enables distributed-safe authentication providers and
allows multiple credential persistence strategies without modifying
auth logic.

mail_intake/credentials/store.py

@@ -0,0 +1,96 @@
+"""
+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
+
+    Type Parameters:
+        T:
+            The concrete credential type managed by the store. This may
+            represent OAuth credentials, API tokens, session objects,
+            or any other authentication material.
+    """
+
+    @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.
+        """