belgie 0.1.0a4__py3-none-any.whl

belgie/__init__.py

@@ -0,0 +1,97 @@
+"""Belgie - Modern authentication and analytics for FastAPI."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from belgie.auth import (
+    Auth,
+    AuthClient,
+    AuthenticationError,
+    AuthorizationError,
+    AuthSettings,
+    BelgieError,
+    ConfigurationError,
+    CookieSettings,
+    DBConnection,
+    GoogleOAuthProvider,
+    GoogleProviderSettings,
+    GoogleUserInfo,
+    HookContext,
+    HookEvent,
+    HookRunner,
+    Hooks,
+    InvalidStateError,
+    OAuthError,
+    OAuthProviderProtocol,
+    Providers,
+    SessionExpiredError,
+    SessionManager,
+    SessionSettings,
+    URLSettings,
+    generate_session_id,
+    generate_state_token,
+    parse_scopes,
+    validate_scopes,
+)
+
+if TYPE_CHECKING:
+    from belgie_alchemy import AlchemyAdapter as AlchemyAdapter
+
+__version__ = "0.1.0"
+
+_ALCHEMY_IMPORT_ERROR = "AlchemyAdapter requires the 'alchemy' extra. Install with: uv add belgie[alchemy]"
+
+
+def __getattr__(name: str) -> object:
+    if name != "AlchemyAdapter":
+        msg = f"module 'belgie' has no attribute {name!r}"
+        raise AttributeError(msg)
+
+    try:
+        module = import_module("belgie_alchemy")
+    except ModuleNotFoundError as exc:
+        raise ImportError(_ALCHEMY_IMPORT_ERROR) from exc
+
+    return module.AlchemyAdapter
+
+
+__all__ = [  # noqa: RUF022
+    # Version
+    "__version__",
+    # Core
+    "Auth",
+    "AuthClient",
+    "AuthSettings",
+    "Hooks",
+    "HookContext",
+    "HookEvent",
+    "HookRunner",
+    # Adapters
+    "AlchemyAdapter",
+    "DBConnection",
+    # Session
+    "SessionManager",
+    # Providers
+    "GoogleOAuthProvider",
+    "GoogleProviderSettings",
+    "GoogleUserInfo",
+    "OAuthProviderProtocol",
+    "Providers",
+    # Settings
+    "SessionSettings",
+    "CookieSettings",
+    "URLSettings",
+    # Exceptions
+    "BelgieError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "SessionExpiredError",
+    "InvalidStateError",
+    "OAuthError",
+    "ConfigurationError",
+    # Utils
+    "generate_session_id",
+    "generate_state_token",
+    "parse_scopes",
+    "validate_scopes",
+]

belgie/alchemy.py

@@ -0,0 +1,24 @@
+"""Alchemy re-exports for belgie consumers."""
+
+_ALCHEMY_IMPORT_ERROR = "belgie.alchemy requires the 'alchemy' extra. Install with: uv add belgie[alchemy]"
+
+try:
+    from belgie_alchemy import (  # type: ignore[import-not-found]
+        AlchemyAdapter,
+        Base,
+        DatabaseSettings,
+        DateTimeUTC,
+        PrimaryKeyMixin,
+        TimestampMixin,
+    )
+except ModuleNotFoundError as exc:
+    raise ImportError(_ALCHEMY_IMPORT_ERROR) from exc
+
+__all__ = [
+    "AlchemyAdapter",
+    "Base",
+    "DatabaseSettings",
+    "DateTimeUTC",
+    "PrimaryKeyMixin",
+    "TimestampMixin",
+]

belgie/auth/__init__.py

@@ -0,0 +1,65 @@
+"""Belgie Auth - Authentication components."""
+
+from belgie_proto import DBConnection
+
+from belgie.auth.core.auth import Auth
+from belgie.auth.core.client import AuthClient
+from belgie.auth.core.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    BelgieError,
+    ConfigurationError,
+    InvalidStateError,
+    OAuthError,
+    SessionExpiredError,
+)
+from belgie.auth.core.hooks import HookContext, HookEvent, HookRunner, Hooks
+from belgie.auth.core.settings import (
+    AuthSettings,
+    CookieSettings,
+    SessionSettings,
+    URLSettings,
+)
+from belgie.auth.providers import OAuthProviderProtocol, Providers
+from belgie.auth.providers.google import GoogleOAuthProvider, GoogleProviderSettings, GoogleUserInfo
+from belgie.auth.session.manager import SessionManager
+from belgie.auth.utils.crypto import generate_session_id, generate_state_token
+from belgie.auth.utils.scopes import parse_scopes, validate_scopes
+
+__all__ = [  # noqa: RUF022
+    # Core
+    "Auth",
+    "AuthClient",
+    "AuthSettings",
+    "Hooks",
+    "HookContext",
+    "HookEvent",
+    "HookRunner",
+    # Adapters
+    "DBConnection",
+    # Session
+    "SessionManager",
+    # Providers
+    "GoogleOAuthProvider",
+    "GoogleProviderSettings",
+    "GoogleUserInfo",
+    "OAuthProviderProtocol",
+    "Providers",
+    # Settings
+    "SessionSettings",
+    "CookieSettings",
+    "URLSettings",
+    # Exceptions
+    "BelgieError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "SessionExpiredError",
+    "InvalidStateError",
+    "OAuthError",
+    "ConfigurationError",
+    # Utils
+    "generate_session_id",
+    "generate_state_token",
+    "parse_scopes",
+    "validate_scopes",
+]

belgie/auth/core/auth.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable  # noqa: TC003
+from functools import cached_property
+from typing import Protocol, cast
+from uuid import UUID
+
+from belgie_proto import (
+    AccountProtocol,
+    AdapterProtocol,
+    DBConnection,
+    OAuthStateProtocol,
+    SessionProtocol,
+    UserProtocol,
+)
+from fastapi import APIRouter, Depends, Request, status
+from fastapi.responses import RedirectResponse
+from fastapi.security import SecurityScopes  # noqa: TC002
+
+from belgie.auth.core.client import AuthClient
+from belgie.auth.core.hooks import HookRunner, Hooks
+from belgie.auth.core.settings import AuthSettings  # noqa: TC001
+from belgie.auth.providers.protocols import OAuthProviderProtocol, Providers  # noqa: TC001
+from belgie.auth.session.manager import SessionManager
+
+
+class DBDependencyProvider(Protocol):
+    """Protocol for database dependency providers.
+
+    This allows Auth to work with any dependency injection system
+    without coupling to a specific implementation.
+    """
+
+    @property
+    def dependency(self) -> Callable[[], DBConnection | AsyncGenerator[DBConnection, None]]:
+        """FastAPI dependency that provides database connections."""
+        ...
+
+
+class _AuthCallable:
+    """Descriptor that makes Auth instances callable with instance-specific dependencies.
+
+    This allows Depends(auth) to work seamlessly - each Auth instance gets its own
+    callable that has the Auth instance's database dependency baked into the signature.
+    """
+
+    def __get__(self, obj: Auth | None, objtype: type | None = None) -> object:
+        """Return instance-specific callable when accessed through an instance."""
+        if obj is None:
+            # Accessed through class, return descriptor itself
+            return self
+
+        # Return a callable with this instance's db.dependency
+        if obj.db is None:
+            msg = "Auth.db must be configured with a dependency"
+            raise RuntimeError(msg)
+        dependency = obj.db.dependency
+
+        def __call__(  # noqa: N807
+            db: DBConnection = Depends(dependency),  # noqa: B008
+        ) -> AuthClient:
+            return AuthClient(
+                db=db,
+                adapter=obj.adapter,
+                session_manager=obj.session_manager,
+                cookie_name=obj.settings.cookie.name,
+                hook_runner=obj.hook_runner,
+            )
+
+        return __call__
+
+
+class Auth[UserT: UserProtocol, AccountT: AccountProtocol, SessionT: SessionProtocol, OAuthStateT: OAuthStateProtocol]:
+    """Main authentication orchestrator for Belgie.
+
+    The Auth class provides a complete OAuth 2.0 authentication solution with session management,
+    user creation, and FastAPI integration. It automatically loads OAuth providers from environment
+    variables and creates router endpoints for authentication.
+
+    Type Parameters:
+        UserT: User model type implementing UserProtocol
+        AccountT: Account model type implementing AccountProtocol
+        SessionT: Session model type implementing SessionProtocol
+        OAuthStateT: OAuth state model type implementing OAuthStateProtocol
+
+    Attributes:
+        settings: Authentication configuration settings
+        adapter: Database adapter for persistence operations
+        session_manager: Session manager instance for session operations
+        providers: Dictionary of registered OAuth providers keyed by provider_id
+        router: FastAPI router with authentication endpoints (cached property)
+
+    Example:
+        >>> from belgie import Auth, AuthSettings, AlchemyAdapter
+        >>> from belgie.auth.providers.google import GoogleOAuthProvider, GoogleProviderSettings
+        >>> from myapp.models import User, Account, Session, OAuthState
+        >>>
+        >>> settings = AuthSettings(
+        ...     secret="your-secret-key",
+        ...     base_url="http://localhost:8000",
+        ... )
+        >>>
+        >>> adapter = AlchemyAdapter(
+        ...     user=User,
+        ...     account=Account,
+        ...     session=Session,
+        ...     oauth_state=OAuthState,
+        ... )
+        >>> db = DatabaseSettings(dialect={"type": "sqlite", "database": ":memory:"})
+        >>>
+        >>> # Explicitly pass provider settings
+        >>> providers: Providers = {
+        ...     "google": GoogleProviderSettings(
+        ...         client_id="your-client-id",
+        ...         client_secret="your-client-secret",
+        ...         redirect_uri="http://localhost:8000/auth/provider/google/callback",
+        ...     ),
+        ... }
+        >>> auth = Auth(settings=settings, adapter=adapter, providers=providers, db=db)
+        >>> app.include_router(auth.router)
+    """
+
+    # Use descriptor to make each instance callable with its own dependency
+    __call__: Callable[..., AuthClient] = cast("Callable[..., AuthClient]", _AuthCallable())
+
+    def __init__(
+        self,
+        settings: AuthSettings,
+        adapter: AdapterProtocol[UserT, AccountT, SessionT, OAuthStateT],
+        db: DBDependencyProvider,
+        providers: Providers | None = None,
+        hooks: Hooks | None = None,
+    ) -> None:
+        """Initialize the Auth instance.
+
+        Args:
+            settings: Authentication configuration including session, cookie, and URL settings
+            adapter: Database adapter for user, account, session, and OAuth state persistence
+            db: Database dependency provider
+            providers: Dictionary of provider settings. Each setting is callable and returns its provider.
+                      If None, no providers are registered.
+
+        Raises:
+        """
+        self.settings = settings
+        self.adapter = adapter
+        self.db = db
+
+        self.session_manager = SessionManager(
+            adapter=adapter,
+            max_age=settings.session.max_age,
+            update_age=settings.session.update_age,
+        )
+
+        self.hook_runner = HookRunner(hooks or Hooks())
+
+        # Instantiate providers by calling the settings
+        self.providers: dict[str, OAuthProviderProtocol] = (
+            {provider_id: provider_settings() for provider_id, provider_settings in providers.items()}  # ty: ignore[call-non-callable]
+            if providers
+            else {}
+        )
+
+    @cached_property
+    def router(self) -> APIRouter:
+        """FastAPI router with all provider routes (cached).
+
+        Creates a router with the following structure:
+        - /auth/provider/{provider_id}/signin - Provider signin endpoints
+        - /auth/provider/{provider_id}/callback - Provider callback endpoints
+        - /auth/signout - Global signout endpoint
+
+        Returns:
+            APIRouter with all authentication endpoints
+        """
+        main_router = APIRouter(prefix="/auth", tags=["auth"])
+        provider_router = APIRouter(prefix="/provider")
+
+        if self.db is None:
+            msg = "Auth.db must be configured with a dependency"
+            raise RuntimeError(msg)
+        dependency = self.db.dependency
+
+        # Include all registered provider routers
+        for provider in self.providers.values():
+            # Provider's router has prefix /{provider_id}
+            # Combined with provider_router prefix: /auth/provider/{provider_id}/...
+            provider_specific_router = provider.get_router(
+                self.adapter,
+                self.settings.cookie,
+                session_max_age=self.settings.session.max_age,
+                signin_redirect=self.settings.urls.signin_redirect,
+                signout_redirect=self.settings.urls.signout_redirect,
+                hook_runner=self.hook_runner,
+                db_dependency=dependency,
+            )
+            provider_router.include_router(provider_specific_router)
+
+        # Add signout endpoint to main router (not provider-specific)
+        async def _get_db(db: DBConnection = Depends(dependency)) -> DBConnection:  # noqa: B008
+            return db
+
+        @main_router.post("/signout")
+        async def signout(
+            request: Request,
+            db: DBConnection = Depends(_get_db),  # noqa: B008, FAST002
+        ) -> RedirectResponse:
+            session_id_str = request.cookies.get(self.settings.cookie.name)
+
+            if session_id_str:
+                try:
+                    session_id = UUID(session_id_str)
+                    await self.sign_out(db, session_id)
+                except ValueError:
+                    pass
+
+            response = RedirectResponse(
+                url=self.settings.urls.signout_redirect,
+                status_code=status.HTTP_302_FOUND,
+            )
+
+            response.delete_cookie(
+                key=self.settings.cookie.name,
+                domain=self.settings.cookie.domain,
+            )
+
+            return response
+
+        # Include provider router in main router
+        main_router.include_router(provider_router)
+        return main_router
+
+    async def get_user_from_session(
+        self,
+        db: DBConnection,
+        session_id: UUID,
+    ) -> UserT | None:
+        """Retrieve user from a session ID.
+
+        This method maintains backward compatibility by delegating to AuthClient internally.
+
+        Args:
+            db: Database connection
+            session_id: UUID of the session
+
+        Returns:
+            User object if session is valid and user exists, None otherwise
+
+        Example:
+            >>> user = await auth.get_user_from_session(db, session_id)
+            >>> if user:
+            ...     print(f"Found user: {user.email}")
+        """
+        client = self.__call__(db)
+        return await client.get_user_from_session(session_id)
+
+    async def sign_out(
+        self,
+        db: DBConnection,
+        session_id: UUID,
+    ) -> bool:
+        """Sign out a user by deleting their session.
+
+        This method maintains backward compatibility by delegating to AuthClient internally.
+
+        Args:
+            db: Database connection
+            session_id: UUID of the session to delete
+
+        Returns:
+            True if session was deleted, False if session didn't exist
+
+        Example:
+            >>> success = await auth.sign_out(db, session_id)
+            >>> if success:
+            ...     print("User signed out successfully")
+        """
+        client = self.__call__(db)
+        return await client.sign_out(session_id)
+
+    async def _get_session_from_cookie(
+        self,
+        request: Request,
+        db: DBConnection,
+    ) -> SessionT | None:
+        """Extract and validate session from request cookies.
+
+        This method delegates to AuthClient for consistency.
+
+        Args:
+            request: FastAPI Request object
+            db: Database connection
+
+        Returns:
+            Session if valid, None otherwise
+        """
+        client = self.__call__(db)
+        return await client._get_session_from_cookie(request)  # noqa: SLF001
+
+    async def user(
+        self,
+        security_scopes: SecurityScopes,
+        request: Request,
+        db: DBConnection,
+    ) -> UserT:
+        """FastAPI dependency for retrieving the authenticated user.
+
+        Extracts the session from cookies, validates it, and returns the authenticated user.
+        Optionally validates user-level scopes if specified.
+
+        This method maintains backward compatibility by delegating to AuthClient internally.
+
+        Args:
+            security_scopes: FastAPI SecurityScopes for scope validation
+            request: FastAPI Request object containing cookies
+            db: Database connection
+
+        Returns:
+            Authenticated user object
+
+        Raises:
+            HTTPException: 401 if not authenticated or session invalid
+            HTTPException: 403 if required scopes are not granted
+
+        Example:
+            >>> from fastapi import Depends, Security
+            >>>
+            >>> @app.get("/protected")
+            >>> async def protected_route(user: User = Depends(auth.user)):
+            ...     return {"email": user.email}
+            >>>
+            >>> @app.get("/resource")
+            >>> async def resource_route(user: User = Security(auth.user, scopes=[Scope.READ])):
+            ...     return {"data": "..."}
+        """
+        client = self.__call__(db)
+        return await client.get_user(security_scopes, request)
+
+    async def session(
+        self,
+        request: Request,
+        db: DBConnection,
+    ) -> SessionT:
+        """FastAPI dependency for retrieving the current session.
+
+        Extracts and validates the session from cookies.
+
+        This method maintains backward compatibility by delegating to AuthClient internally.
+
+        Args:
+            request: FastAPI Request object containing cookies
+            db: Database connection
+
+        Returns:
+            Active session object
+
+        Raises:
+            HTTPException: 401 if not authenticated or session invalid/expired
+
+        Example:
+            >>> from fastapi import Depends
+            >>>
+            >>> @app.get("/session-info")
+            >>> async def session_info(session: Session = Depends(auth.session)):
+            ...     return {"session_id": str(session.id), "expires_at": session.expires_at.isoformat()}
+        """
+        client = self.__call__(db)
+        return await client.get_session(request)