"""
Authentication provider contracts for Mail Intake.

This module defines the **authentication abstraction layer** used by mail
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.
"""

from abc import ABC, abstractmethod


class MailIntakeAuthProvider(ABC):
    """
    Abstract authentication provider.

    Mail adapters depend on this interface, not on concrete
    OAuth or credential implementations.

    Authentication providers encapsulate all logic required to acquire
    valid credentials for a mail provider.

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

    @abstractmethod
    def get_credentials(self):
        """
        Return provider-specific credentials object.

        This method is synchronous by design and must either
        return valid credentials or raise MailIntakeAuthError.

        Returns:
            Provider-specific credentials object suitable for use by
            the corresponding mail adapter.

        Raises:
            Exception: Authentication-specific errors defined by the
                implementation.
        """
        raise NotImplementedError