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/auth/base.py

@@ -6,45 +6,54 @@ adapters to obtain provider-specific credentials.
 
 Authentication concerns are intentionally decoupled from adapter logic.
 Adapters depend only on this interface and must not be aware of how
-credentials are acquired, refreshed, or stored.
+credentials are acquired, refreshed, or persisted.
 """
 
 from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
 
 
-class MailIntakeAuthProvider(ABC):
+class MailIntakeAuthProvider(ABC, Generic[T]):
     """
-    Abstract authentication provider.
+    Abstract base class for authentication providers.
 
-    Mail adapters depend on this interface, not on concrete
-    OAuth or credential implementations.
+    This interface enforces a strict contract between authentication
+    providers and mail adapters by requiring providers to explicitly
+    declare the type of credentials they return.
 
-    Authentication providers encapsulate all logic required to acquire
-    valid credentials for a mail provider.
+    Authentication providers encapsulate all logic required to:
+    - Acquire credentials from an external provider
+    - Refresh or revalidate credentials as needed
+    - Handle authentication-specific failure modes
+    - Coordinate with credential persistence layers where applicable
 
-    Implementations may involve:
-    - OAuth flows
-    - Service account credentials
-    - Token refresh logic
-    - Secure credential storage
-
-    Adapters must treat the returned credentials as opaque and provider-specific.
+    Mail adapters must treat returned credentials as opaque and
+    provider-specific, relying only on the declared credential type
+    expected by the adapter.
     """
 
     @abstractmethod
-    def get_credentials(self):
+    def get_credentials(self) -> T:
         """
-        Return provider-specific credentials object.
+        Retrieve valid, provider-specific credentials.
 
-        This method is synchronous by design and must either
-        return valid credentials or raise MailIntakeAuthError.
+        This method is synchronous by design and represents the sole
+        entry point through which adapters obtain authentication
+        material.
+
+        Implementations must either return credentials of the declared
+        type ``T`` that are valid at the time of return or raise an
+        authentication-specific exception.
 
         Returns:
-            Provider-specific credentials object suitable for use by
-            the corresponding mail adapter.
+            Credentials of type ``T`` suitable for immediate use by the
+            corresponding mail adapter.
 
         Raises:
-            Exception: Authentication-specific errors defined by the
-                implementation.
+            Exception:
+                An authentication-specific exception indicating that
+                credentials could not be obtained or validated.
         """
         raise NotImplementedError