"""Exception hierarchy for a2a-passport.

Every error the library raises deliberately, on purpose, subclasses
A2APassportError -- callers can catch that one type to handle "something in
the auth/transport layer went wrong" without enumerating every leaf class.
"""
from __future__ import annotations


class A2APassportError(Exception):
    """Base class for all errors raised intentionally by this library."""


class TokenAcquisitionError(A2APassportError):
    """Raised when a TokenProvider fails to obtain a token from an IdP."""


class TokenVerificationError(A2APassportError):
    """Raised by a TokenVerifier when an inbound token fails verification.

    Carries an `error_code` matching the OAuth2-flavored codes returned over
    the wire (e.g. "invalid_token", "token_expired", "invalid_audience") so
    server code can map it to the right HTTP status without string-matching
    exception messages.
    """

    def __init__(self, message: str, *, error_code: str = "invalid_token"):
        super().__init__(message)
        self.error_code = error_code


class InsufficientScopeError(A2APassportError):
    """Raised when a verified token lacks a required scope."""

    def __init__(self, required_scope: str):
        super().__init__(f"token is missing required scope: {required_scope!r}")
        self.required_scope = required_scope
