__init__.py

"""
Error classes for the auth0-server-python SDK.
These exceptions provide specific error types for different failure scenarios.
"""
from typing import Any, Optional


class Auth0Error(Exception):
    """Base class for all Auth0 SDK errors."""

    def __init__(self, message=None):
        self.message = message
        super().__init__(message)


class MissingTransactionError(Auth0Error):
    """
    Error raised when a required transaction is missing.
    This typically happens during the callback phase when the transaction
    from the initial authorization request cannot be found.
    """
    code = "missing_transaction_error"

    def __init__(self, message=None):
        super().__init__(message or "The transaction is missing.")
        self.name = "MissingTransactionError"


class ApiError(Auth0Error):
    """
    Error raised when an API request to Auth0 fails.
    Contains details about the original error from Auth0.
    """

    def __init__(self, code: str, message: str, cause=None):
        super().__init__(message)
        self.code = code
        self.cause = cause

        # Extract additional error details if available
        if cause:
            self.error = getattr(cause, "error", None)
            self.error_description = getattr(cause, "error_description", None)
        else:
            self.error = None
            self.error_description = None


class PollingApiError(ApiError):
    """
    Error raised when a polling API request to Auth0 fails.
    Contains details about the original error from Auth0 and the requested polling interval.
    """

    def __init__(self, code: str, message: str, interval: Optional[int], cause=None):
        super().__init__(code, message, cause)
        self.interval = interval

class MyAccountApiError(Auth0Error):
    """
    Error raised when an API request to My Account API fails.
    Contains details about the original error from Auth0.
    """

    def __init__(
            self,
            title: Optional[str],
            type: Optional[str],
            detail: Optional[str],
            status: Optional[int],
            validation_errors: Optional[list[dict[str, str]]] = None
        ):
        super().__init__(detail)
        self.title = title
        self.type = type
        self.detail = detail
        self.status = status
        self.validation_errors = validation_errors

class AccessTokenError(Auth0Error):
    """Error raised when there's an issue with access tokens."""

    def __init__(self, code: str, message: str, cause=None):
        super().__init__(message)
        self.code = code
        self.name = "AccessTokenError"
        self.cause = cause


class MissingRequiredArgumentError(Auth0Error):
    """
    Error raised when a required argument is missing.
    Includes the name of the missing argument in the error message.
    """
    code = "missing_required_argument_error"

    def __init__(self, argument: str):
        message = f"The argument '{argument}' is required but was not provided."
        super().__init__(message)
        self.name = "MissingRequiredArgumentError"
        self.argument = argument


class ConfigurationError(Auth0Error):
    """
    Error raised when SDK configuration is invalid.
    This includes invalid combinations of parameters or incorrect configuration values.
    """
    code = "configuration_error"

    def __init__(self, message: str):
        super().__init__(message)
        self.name = "ConfigurationError"

class InvalidArgumentError(Auth0Error):
    """
    Error raised when a given argument is an invalid value.
    """
    code = "invalid_argument"

    def __init__(self, argument: str, message: str):
        super().__init__(message)
        self.name = "InvalidArgumentError"
        self.argument = argument


class IssuerValidationError(Auth0Error):
    """
    Error raised when token issuer validation fails.
    This can happen when the issuer claim in a token does not match
    the expected issuer for the configured domain.
    """
    code = "issuer_validation_error"

    def __init__(self, message: str):
        super().__init__(message)
        self.name = "IssuerValidationError"


class BackchannelLogoutError(Auth0Error):
    """
    Error raised during backchannel logout processing.
    This can happen when validating or processing logout tokens.
    """
    code = "backchannel_logout_error"

    def __init__(self, message: str):
        super().__init__(message)
        self.name = "BackchannelLogoutError"


class DomainResolverError(Auth0Error):
    """
    Error raised when domain resolver function fails or returns invalid value.

    This error indicates an issue with the custom domain resolver function
    provided for MCD (Multiple Custom Domains) support.
    """
    code = "domain_resolver_error"

    def __init__(self, message: str, original_error: Exception = None):
        super().__init__(message)
        self.name = "DomainResolverError"
        self.original_error = original_error


class AccessTokenForConnectionError(Auth0Error):
    """Error when retrieving access tokens for a specific connection fails."""

    def __init__(self, code: str, message: str):
        super().__init__(message)
        self.code = code
        self.name = "AccessTokenForConnectionError"

class StartLinkUserError(Auth0Error):
    """
    Error raised when user linking process fails to start.
    This typically happens when trying to link accounts without
    having an authenticated user first.
    """
    code = "start_link_user_error"

    def __init__(self, message: str):
        super().__init__(message)
        self.name = "StartLinkUserError"


# Error code enumerations - these can be used to identify specific error scenarios

class AccessTokenErrorCode:
    """Error codes for access token operations."""
    MISSING_SESSION = "missing_session"
    MISSING_REFRESH_TOKEN = "missing_refresh_token"
    FAILED_TO_REFRESH_TOKEN = "failed_to_refresh_token"
    FAILED_TO_REQUEST_TOKEN = "failed_to_request_token"
    REFRESH_TOKEN_ERROR = "refresh_token_error"
    AUTH_REQ_ID_ERROR = "auth_req_id_error"
    INCORRECT_AUDIENCE = "incorrect_audience"
    MISSING_SESSION_DOMAIN = "missing_session_domain"
    DOMAIN_MISMATCH = "domain_mismatch"


class OrganizationTokenValidationError(Auth0Error):
    """
    Raised when org_id or org_name claim in the ID token fails validation
    against the organization value that was requested at login.
    """
    code = "organization_token_validation_error"

    def __init__(self, message: str):
        super().__init__(message)
        self.name = "OrganizationTokenValidationError"


class AccessTokenForConnectionErrorCode:
    """Error codes for connection-specific token operations."""
    MISSING_REFRESH_TOKEN = "missing_refresh_token"
    FAILED_TO_RETRIEVE = "failed_to_retrieve"
    API_ERROR = "api_error"
    FETCH_ERROR = "retrieval_error"
    MISSING_SESSION_DOMAIN = "missing_session_domain"
    DOMAIN_MISMATCH = "domain_mismatch"


class CustomTokenExchangeError(Auth0Error):
    """
    Error raised during custom token exchange operations.
    """
    def __init__(self, code: str, message: str, cause=None):
        super().__init__(message)
        self.code = code
        self.name = "CustomTokenExchangeError"
        self.cause = cause


class CustomTokenExchangeErrorCode:
    """Error codes for custom token exchange operations."""
    INVALID_TOKEN_FORMAT = "invalid_token_format"
    MISSING_ACTOR_TOKEN_TYPE = "missing_actor_token_type"
    TOKEN_EXCHANGE_FAILED = "token_exchange_failed"
    INVALID_RESPONSE = "invalid_response"


# =============================================================================
# MFA Error Classes
# =============================================================================

class MfaApiError(Auth0Error):
    """Base class for MFA API errors."""

    def __init__(
        self,
        code: str,
        message: str,
        cause: Optional[dict[str, Any]] = None
    ):
        super().__init__(message)
        self.code = code
        self.cause = cause


class MfaListAuthenticatorsError(MfaApiError):
    """Error thrown when listing authenticators fails."""

    def __init__(self, message: str, cause: Optional[dict] = None):
        super().__init__("mfa_list_authenticators_error", message, cause)


class MfaEnrollmentError(MfaApiError):
    """Error thrown when enrolling an authenticator fails."""

    def __init__(self, message: str, cause: Optional[dict] = None):
        super().__init__("mfa_enrollment_error", message, cause)


class MfaChallengeError(MfaApiError):
    """Error thrown when initiating an MFA challenge fails."""

    def __init__(self, message: str, cause: Optional[dict] = None):
        super().__init__("mfa_challenge_error", message, cause)


class MfaVerifyError(MfaApiError):
    """Error thrown when MFA verification fails."""

    def __init__(self, message: str, cause: Optional[dict] = None):
        super().__init__("mfa_verify_error", message, cause)


class MfaRequiredError(AccessTokenError):
    """
    Error thrown when MFA step-up is required during token refresh.

    Contains an encrypted mfa_token that can be passed to MfaClient methods.
    This error is raised in get_access_token() when the token endpoint returns
    'mfa_required'.
    """

    def __init__(
        self,
        message: str,
        mfa_token: str,
        mfa_requirements=None,
        cause: Optional[Exception] = None
    ):
        super().__init__("mfa_required", message, cause)
        self.mfa_token = mfa_token
        self.mfa_requirements = mfa_requirements


class MfaTokenExpiredError(Auth0Error):
    """Error thrown when the encrypted MFA token has expired."""

    def __init__(self):
        super().__init__("The MFA token has expired.")
        self.code = "mfa_token_expired"


class MfaTokenInvalidError(Auth0Error):
    """Error thrown when the encrypted MFA token is invalid or tampered."""

    def __init__(self):
        super().__init__("The MFA token is invalid.")
        self.code = "mfa_token_invalid"