byoi 0.1.0a1__py3-none-any.whl

byoi/dependencies.py

@@ -0,0 +1,144 @@
+"""FastAPI dependencies for the BYOI library.
+
+Provides FastAPI dependency injection utilities for accessing BYOI services.
+"""
+
+from typing import Annotated, Callable
+
+from fastapi import Depends, Request
+
+from byoi.providers import ProviderManager
+from byoi.service import AuthService
+
+__all__ = (
+    "get_provider_manager",
+    "get_auth_service",
+    "ProviderManagerDep",
+    "AuthServiceDep",
+)
+
+
+def get_provider_manager(request: Request) -> ProviderManager:
+    """FastAPI dependency to get the ProviderManager.
+
+    The ProviderManager must be stored in the application state
+    using the key "byoi_provider_manager".
+
+    Args:
+        request: The FastAPI request.
+
+    Returns:
+        The ProviderManager instance.
+
+    Raises:
+        RuntimeError: If BYOI is not configured in the application.
+
+    Example:
+        ```python
+        @app.get("/providers")
+        async def list_providers(
+            provider_manager: ProviderManagerDep,
+        ):
+            return provider_manager.list_providers()
+        ```
+    """
+    provider_manager = getattr(request.app.state, "byoi_provider_manager", None)
+    if provider_manager is None:
+        raise RuntimeError(
+            "BYOI is not configured. Call BYOI.setup() during application startup."
+        )
+    return provider_manager
+
+
+def get_auth_service(request: Request) -> AuthService:
+    """FastAPI dependency to get the AuthService.
+
+    The AuthService must be stored in the application state
+    using the key "byoi_auth_service".
+
+    Args:
+        request: The FastAPI request.
+
+    Returns:
+        The AuthService instance.
+
+    Raises:
+        RuntimeError: If BYOI is not configured in the application.
+
+    Example:
+        ```python
+        @app.post("/auth/login")
+        async def login(
+            request: TokenExchangeRequest,
+            auth_service: AuthServiceDep,
+        ):
+            return await auth_service.authenticate(request)
+        ```
+    """
+    auth_service = getattr(request.app.state, "byoi_auth_service", None)
+    if auth_service is None:
+        raise RuntimeError(
+            "BYOI is not configured. Call BYOI.setup() during application startup."
+        )
+    return auth_service
+
+
+# Type aliases for dependency injection
+ProviderManagerDep = Annotated[ProviderManager, Depends(get_provider_manager)]
+AuthServiceDep = Annotated[AuthService, Depends(get_auth_service)]
+
+
+def create_provider_manager_dependency(
+    provider_manager: ProviderManager,
+) -> Callable[[], ProviderManager]:
+    """Create a custom dependency that returns a specific ProviderManager.
+
+    Useful for testing or when not using the BYOI class for setup.
+
+    Args:
+        provider_manager: The ProviderManager to return.
+
+    Returns:
+        A dependency function.
+
+    Example:
+        ```python
+        provider_manager = ProviderManager(cache=my_cache)
+        app.dependency_overrides[get_provider_manager] = (
+            create_provider_manager_dependency(provider_manager)
+        )
+        ```
+    """
+
+    def dependency() -> ProviderManager:
+        return provider_manager
+
+    return dependency
+
+
+def create_auth_service_dependency(
+    auth_service: AuthService,
+) -> Callable[[], AuthService]:
+    """Create a custom dependency that returns a specific AuthService.
+
+    Useful for testing or when not using the BYOI class for setup.
+
+    Args:
+        auth_service: The AuthService to return.
+
+    Returns:
+        A dependency function.
+
+    Example:
+        ```python
+        auth_service = AuthService(...)
+        app.dependency_overrides[get_auth_service] = (
+            create_auth_service_dependency(auth_service)
+        )
+        ```
+    """
+
+    def dependency() -> AuthService:
+        return auth_service
+
+    return dependency

byoi/errors.py

@@ -0,0 +1,360 @@
+__all__ = (
+    "BYOIError",
+    "ConfigurationError",
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderDiscoveryError",
+    "AuthenticationError",
+    "InvalidStateError",
+    "StateExpiredError",
+    "InvalidCodeError",
+    "TokenExchangeError",
+    "TokenRefreshError",
+    "TokenValidationError",
+    "InvalidNonceError",
+    "InvalidIssuerError",
+    "InvalidAudienceError",
+    "TokenExpiredError",
+    "JWKSFetchError",
+    "IdentityError",
+    "IdentityAlreadyLinkedError",
+    "IdentityNotFoundError",
+    "CannotUnlinkLastIdentityError",
+    "UserNotFoundError",
+    "CacheError",
+)
+
+from typing import Any
+
+
+class BYOIError(Exception):
+    """Base class for all BYOI exceptions.
+
+    All BYOI errors have a message and a unique error code that can be used
+    for programmatic error handling.
+
+    Example:
+        ```python
+        from fastapi import HTTPException
+        from byoi import BYOIError, InvalidStateError
+
+        try:
+            result = await auth_service.exchange_code(request)
+        except InvalidStateError as e:
+            raise HTTPException(status_code=400, detail=e.to_dict())
+        ```
+    """
+
+    def __init__(self, message: str, code: str = "byoi_error") -> None:
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the error to a dictionary suitable for API responses.
+
+        Returns:
+            A dictionary with 'error', 'code', and 'message' keys.
+        """
+        return {
+            "error": self.__class__.__name__,
+            "code": self.code,
+            "message": self.message,
+        }
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+# =============================================================================
+# Configuration Errors
+# =============================================================================
+
+
+class ConfigurationError(BYOIError):
+    """Error in BYOI configuration."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="configuration_error")
+
+
+# =============================================================================
+# Provider Errors
+# =============================================================================
+
+
+class ProviderError(BYOIError):
+    """Base class for provider-related errors."""
+
+    def __init__(self, message: str, code: str = "provider_error") -> None:
+        super().__init__(message, code=code)
+
+
+class ProviderNotFoundError(ProviderError):
+    """The requested provider is not configured."""
+
+    def __init__(self, provider_name: str) -> None:
+        self.provider_name = provider_name
+        super().__init__(
+            f"Provider '{provider_name}' is not configured",
+            code="provider_not_found",
+        )
+
+
+class ProviderDiscoveryError(ProviderError):
+    """Failed to discover provider endpoints."""
+
+    def __init__(self, provider_name: str, reason: str) -> None:
+        self.provider_name = provider_name
+        self.reason = reason
+        super().__init__(
+            f"Failed to discover endpoints for provider '{provider_name}': {reason}",
+            code="provider_discovery_error",
+        )
+
+
+# =============================================================================
+# Authentication Errors
+# =============================================================================
+
+
+class AuthenticationError(BYOIError):
+    """Base class for authentication errors."""
+
+    def __init__(self, message: str, code: str = "authentication_error") -> None:
+        super().__init__(message, code=code)
+
+
+class InvalidStateError(AuthenticationError):
+    """The OAuth state parameter is invalid or not found."""
+
+    def __init__(self, state: str | None = None) -> None:
+        self.state = state
+        super().__init__(
+            "Invalid or unknown OAuth state parameter",
+            code="invalid_state",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(state={self.state!r})"
+
+
+class StateExpiredError(AuthenticationError):
+    """The OAuth state has expired."""
+
+    def __init__(self, state: str) -> None:
+        self.state = state
+        super().__init__(
+            "OAuth state has expired",
+            code="state_expired",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(state={self.state!r})"
+
+
+class InvalidCodeError(AuthenticationError):
+    """The authorization code is invalid."""
+
+    def __init__(self, reason: str | None = None) -> None:
+        self.reason = reason
+        message = "Invalid authorization code"
+        if reason:
+            message = f"{message}: {reason}"
+        super().__init__(message, code="invalid_code")
+
+
+class TokenExchangeError(AuthenticationError):
+    """Failed to exchange authorization code for tokens."""
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(
+            f"Token exchange failed: {reason}",
+            code="token_exchange_error",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(reason={self.reason!r})"
+
+
+class TokenRefreshError(AuthenticationError):
+    """Failed to refresh access token."""
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(
+            f"Token refresh failed: {reason}",
+            code="token_refresh_error",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(reason={self.reason!r})"
+
+
+# =============================================================================
+# Token Validation Errors
+# =============================================================================
+
+
+class TokenValidationError(AuthenticationError):
+    """Base class for token validation errors."""
+
+    def __init__(self, message: str, code: str = "token_validation_error") -> None:
+        super().__init__(message, code=code)
+
+
+class InvalidNonceError(TokenValidationError):
+    """The nonce in the ID token doesn't match the expected value."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "ID token nonce does not match expected value",
+            code="invalid_nonce",
+        )
+
+
+class InvalidIssuerError(TokenValidationError):
+    """The issuer in the ID token doesn't match the expected value."""
+
+    def __init__(self, expected: str, actual: str) -> None:
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"ID token issuer mismatch: expected '{expected}', got '{actual}'",
+            code="invalid_issuer",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(expected={self.expected!r}, actual={self.actual!r})"
+
+
+class InvalidAudienceError(TokenValidationError):
+    """The audience in the ID token doesn't match the expected value."""
+
+    def __init__(self, expected: str, actual: str | list[str]) -> None:
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"ID token audience mismatch: expected '{expected}', got '{actual}'",
+            code="invalid_audience",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(expected={self.expected!r}, actual={self.actual!r})"
+
+
+class TokenExpiredError(TokenValidationError):
+    """The token has expired."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Token has expired",
+            code="token_expired",
+        )
+
+
+class JWKSFetchError(TokenValidationError):
+    """Failed to fetch JWKS from the provider."""
+
+    def __init__(self, provider_name: str, reason: str) -> None:
+        self.provider_name = provider_name
+        self.reason = reason
+        super().__init__(
+            f"Failed to fetch JWKS for provider '{provider_name}': {reason}",
+            code="jwks_fetch_error",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(provider_name={self.provider_name!r}, reason={self.reason!r})"
+
+
+# =============================================================================
+# Identity Errors
+# =============================================================================
+
+
+class IdentityError(BYOIError):
+    """Base class for identity-related errors."""
+
+    def __init__(self, message: str, code: str = "identity_error") -> None:
+        super().__init__(message, code=code)
+
+
+class IdentityAlreadyLinkedError(IdentityError):
+    """The identity is already linked to a user."""
+
+    def __init__(
+        self,
+        provider_name: str,
+        provider_subject: str,
+        existing_user_id: str | None = None,
+    ) -> None:
+        self.provider_name = provider_name
+        self.provider_subject = provider_subject
+        self.existing_user_id = existing_user_id
+        super().__init__(
+            f"Identity from provider '{provider_name}' is already linked to a user",
+            code="identity_already_linked",
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(provider_name={self.provider_name!r}, "
+            f"provider_subject={self.provider_subject!r}, existing_user_id={self.existing_user_id!r})"
+        )
+
+
+class IdentityNotFoundError(IdentityError):
+    """The identity was not found."""
+
+    def __init__(self, identity_id: str) -> None:
+        self.identity_id = identity_id
+        super().__init__(
+            f"Identity '{identity_id}' not found",
+            code="identity_not_found",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(identity_id={self.identity_id!r})"
+
+
+class CannotUnlinkLastIdentityError(IdentityError):
+    """Cannot unlink the user's only identity."""
+
+    def __init__(self, user_id: str) -> None:
+        self.user_id = user_id
+        super().__init__(
+            f"Cannot unlink the only identity for user '{user_id}'",
+            code="cannot_unlink_last_identity",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(user_id={self.user_id!r})"
+
+
+class UserNotFoundError(IdentityError):
+    """The user was not found."""
+
+    def __init__(self, user_id: str) -> None:
+        self.user_id = user_id
+        super().__init__(
+            f"User '{user_id}' not found",
+            code="user_not_found",
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(user_id={self.user_id!r})"
+
+
+# =============================================================================
+# Cache Errors
+# =============================================================================
+
+
+class CacheError(BYOIError):
+    """Error in cache operations."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="cache_error")
+