belgie-core 0.1.0__py3-none-any.whl

belgie_core/core/client.py

@@ -0,0 +1,250 @@
+from dataclasses import dataclass, field
+from uuid import UUID
+
+from belgie_proto import (
+    AccountProtocol,
+    AdapterProtocol,
+    DBConnection,
+    OAuthStateProtocol,
+    SessionProtocol,
+    UserProtocol,
+)
+from fastapi import HTTPException, Request, Response, status
+from fastapi.security import SecurityScopes
+
+from belgie_core.core.hooks import HookContext, HookRunner, Hooks
+from belgie_core.core.settings import CookieSettings
+from belgie_core.session.manager import SessionManager
+from belgie_core.utils.scopes import validate_scopes
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BelgieClient[
+    UserT: UserProtocol,
+    AccountT: AccountProtocol,
+    SessionT: SessionProtocol,
+    OAuthStateT: OAuthStateProtocol,
+]:
+    """Client for authentication operations with injected database session.
+
+    This class provides authentication methods with a captured database session,
+    allowing for convenient auth operations without explicitly passing db to each method.
+
+    Typically obtained via Belgie.__call__() as a FastAPI dependency:
+        client: BelgieClient = Depends(belgie)
+
+    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:
+        db: Captured database connection
+        adapter: Database adapter for persistence operations
+        session_manager: Session manager for session lifecycle operations
+        cookie_settings: Settings for the session cookie
+
+    Example:
+        >>> @app.delete("/account")
+        >>> async def delete_account(
+        ...     client: BelgieClient = Depends(belgie),
+        ...     request: Request,
+        ... ):
+        ...     user = await client.get_user(SecurityScopes(), request)
+        ...     await client.delete_user(user)
+        ...     return {"message": "Account deleted"}
+    """
+
+    db: DBConnection
+    adapter: AdapterProtocol[UserT, AccountT, SessionT, OAuthStateT]
+    session_manager: SessionManager[UserT, AccountT, SessionT, OAuthStateT]
+    cookie_settings: CookieSettings = field(default_factory=CookieSettings)
+    hook_runner: HookRunner = field(default_factory=lambda: HookRunner(Hooks()))
+
+    async def _get_session_from_cookie(self, request: Request) -> SessionT | None:
+        """Extract and validate session from request cookies.
+
+        Args:
+            request: FastAPI Request object containing cookies
+
+        Returns:
+            Valid session object or None if cookie missing/invalid/expired
+        """
+        if not (session_id_str := request.cookies.get(self.cookie_settings.name)):
+            return None
+
+        try:
+            session_id = UUID(session_id_str)
+        except ValueError:
+            return None
+
+        return await self.session_manager.get_session(self.db, session_id)
+
+    async def get_user(self, security_scopes: SecurityScopes, request: Request) -> UserT:
+        """Get the authenticated user from the request session.
+
+        Extracts the session from cookies, validates it, and returns the authenticated user.
+        Optionally validates user-level scopes if specified.
+
+        Args:
+            security_scopes: FastAPI SecurityScopes for scope validation
+            request: FastAPI Request object containing cookies
+
+        Returns:
+            Authenticated user object
+
+        Raises:
+            HTTPException: 401 if not authenticated or session invalid
+            HTTPException: 403 if required scopes are not granted
+
+        Example:
+            >>> user = await client.get_user(SecurityScopes(scopes=["read"]), request)
+            >>> print(user.email)
+        """
+        if not (session := await self._get_session_from_cookie(request)):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="not authenticated",
+            )
+
+        if not (user := await self.adapter.get_user_by_id(self.db, session.user_id)):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="user not found",
+            )
+
+        # Validate user-level scopes if required
+        if security_scopes.scopes and not validate_scopes(user.scopes, security_scopes.scopes):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Insufficient permissions",
+            )
+
+        return user
+
+    async def get_session(self, request: Request) -> SessionT:
+        """Get the current session from the request.
+
+        Extracts and validates the session from cookies.
+
+        Args:
+            request: FastAPI Request object containing cookies
+
+        Returns:
+            Active session object
+
+        Raises:
+            HTTPException: 401 if not authenticated or session invalid/expired
+
+        Example:
+            >>> session = await client.get_session(request)
+            >>> print(session.expires_at)
+        """
+        if not (session := await self._get_session_from_cookie(request)):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="not authenticated",
+            )
+
+        return session
+
+    async def delete_user(self, user: UserT) -> bool:
+        """Delete a user and all associated data."""
+        async with self.hook_runner.dispatch("on_delete", HookContext(user=user, db=self.db)):
+            return await self.adapter.delete_user(self.db, user.id)
+
+    async def get_user_from_session(self, session_id: UUID) -> UserT | None:
+        """Retrieve user from a session ID.
+
+        Args:
+            session_id: UUID of the session
+
+        Returns:
+            User object if session is valid and user exists, None otherwise
+
+        Example:
+            >>> from uuid import UUID
+            >>> session_id = UUID("...")
+            >>> user = await client.get_user_from_session(session_id)
+            >>> if user:
+            ...     print(f"Found user: {user.email}")
+        """
+        if not (session := await self.session_manager.get_session(self.db, session_id)):
+            return None
+
+        return await self.adapter.get_user_by_id(self.db, session.user_id)
+
+    async def sign_up(  # noqa: PLR0913
+        self,
+        email: str,
+        *,
+        request: Request | None = None,
+        name: str | None = None,
+        image: str | None = None,
+        email_verified: bool = False,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+    ) -> tuple[UserT, SessionT]:
+        if not (user := await self.adapter.get_user_by_email(self.db, email)):
+            user = await self.adapter.create_user(
+                self.db,
+                email=email,
+                name=name,
+                image=image,
+                email_verified=email_verified,
+            )
+            async with self.hook_runner.dispatch("on_signup", HookContext(user=user, db=self.db)):
+                pass
+
+        if request:
+            if ip_address is None and request.client:
+                ip_address = request.client.host
+            if user_agent is None:
+                user_agent = request.headers.get("user-agent")
+
+        session = await self.session_manager.create_session(
+            self.db,
+            user_id=user.id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+
+        async with self.hook_runner.dispatch("on_signin", HookContext(user=user, db=self.db)):
+            pass
+
+        return user, session
+
+    def create_session_cookie[R: Response](self, session: SessionT, response: R) -> R:
+        response.set_cookie(
+            key=self.cookie_settings.name,
+            value=str(session.id),
+            max_age=self.session_manager.max_age,
+            httponly=self.cookie_settings.http_only,
+            secure=self.cookie_settings.secure,
+            samesite=self.cookie_settings.same_site,
+            domain=self.cookie_settings.domain,
+        )
+        return response
+
+    async def sign_out(self, session_id: UUID) -> bool:
+        """Sign out a user by deleting their session.
+
+        Args:
+            session_id: UUID of the session to delete
+
+        Returns:
+            True if session was deleted, False if session didn't exist
+
+        Example:
+            >>> session = await client.get_session(request)
+            >>> await client.sign_out(session.id)
+        """
+        if not (session := await self.session_manager.get_session(self.db, session_id)):
+            return False
+
+        if not (user := await self.adapter.get_user_by_id(self.db, session.user_id)):
+            return False
+
+        async with self.hook_runner.dispatch("on_signout", HookContext(user=user, db=self.db)):
+            return await self.session_manager.delete_session(self.db, session_id)

belgie_core/core/exceptions.py

@@ -0,0 +1,26 @@
+class BelgieError(Exception):
+    pass
+
+
+class AuthenticationError(BelgieError):
+    pass
+
+
+class AuthorizationError(BelgieError):
+    pass
+
+
+class SessionExpiredError(AuthenticationError):
+    pass
+
+
+class InvalidStateError(BelgieError):
+    pass
+
+
+class OAuthError(BelgieError):
+    pass
+
+
+class ConfigurationError(BelgieError):
+    pass

belgie_core/core/hooks.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextlib import AbstractAsyncContextManager, AbstractContextManager, AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, cast
+
+if TYPE_CHECKING:
+    from belgie_proto import DBConnection
+else:  # pragma: no cover
+    DBConnection = object
+
+from belgie_proto import UserProtocol
+
+HookEvent = Literal["on_signup", "on_signin", "on_signout", "on_delete"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HookContext[UserT: UserProtocol]:
+    user: UserT
+    db: DBConnection
+
+
+type HookFunc = Callable[[HookContext], None | Awaitable[None]]
+type HookCtxMgr = Callable[[HookContext], AbstractContextManager[None] | AbstractAsyncContextManager[None]]
+type HookHandler = HookFunc | HookCtxMgr
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Hooks:
+    on_signup: HookHandler | Sequence[HookHandler] | None = None
+    on_signin: HookHandler | Sequence[HookHandler] | None = None
+    on_signout: HookHandler | Sequence[HookHandler] | None = None
+    on_delete: HookHandler | Sequence[HookHandler] | None = None
+
+
+class HookRunner:
+    def __init__(self, hooks: Hooks) -> None:
+        self._hooks = hooks
+
+    @asynccontextmanager
+    async def dispatch(self, event: HookEvent | str, context: HookContext) -> AsyncIterator[None]:
+        handlers = self._normalize(self._handlers_for(event))
+
+        if not handlers:
+            yield
+            return
+
+        async with AsyncExitStack() as stack:
+            for handler in handlers:
+                result = handler(context)
+
+                if hasattr(result, "__aenter__") and hasattr(result, "__aexit__"):
+                    await stack.enter_async_context(result)  # type: ignore[arg-type]
+                    continue
+
+                if hasattr(result, "__enter__") and hasattr(result, "__exit__"):
+                    stack.enter_context(result)  # type: ignore[arg-type]
+                    continue
+
+                if inspect.isawaitable(result):
+                    await result
+
+            yield
+
+    def _handlers_for(self, event: HookEvent | str) -> HookHandler | Sequence[HookHandler] | None:
+        match event:
+            case "on_signup":
+                return self._hooks.on_signup
+            case "on_signin":
+                return self._hooks.on_signin
+            case "on_signout":
+                return self._hooks.on_signout
+            case "on_delete":
+                return self._hooks.on_delete
+            case _:
+                return None
+
+    def _normalize(self, handlers: HookHandler | Sequence[HookHandler] | None) -> list[HookHandler]:
+        if handlers is None:
+            return []
+
+        if isinstance(handlers, Sequence) and not isinstance(handlers, (str, bytes)):
+            return list(cast("Sequence[HookHandler]", handlers))
+
+        return [cast("HookHandler", handlers)]

belgie_core/core/protocols.py

@@ -0,0 +1,19 @@
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fastapi import APIRouter
+
+if TYPE_CHECKING:
+    from belgie_core.core.belgie import Belgie
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Protocol for Belgie plugins."""
+
+    def router(self, belgie: "Belgie") -> APIRouter:
+        """Return the FastAPI router for this plugin."""
+        ...
+
+    def public_router(self, belgie: "Belgie") -> APIRouter:
+        """Return the FastAPI router for public root-level routes."""
+        ...

belgie_core/core/settings.py

@@ -0,0 +1,100 @@
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from belgie_core.providers.protocols import OAuthProviderProtocol
+
+
+class ProviderSettings(BaseSettings):
+    """Base settings class for OAuth providers.
+
+    All provider-specific settings should inherit from this class
+    to ensure consistent configuration structure.
+
+    Subclasses must implement __call__ to construct their provider instance.
+    """
+
+    client_id: str
+    client_secret: SecretStr
+    redirect_uri: str
+
+    @field_validator("client_id", "redirect_uri")
+    @classmethod
+    def validate_non_empty(cls, v: str, info) -> str:  # noqa: ANN001
+        """Ensure required OAuth fields are non-empty."""
+        if not v or not v.strip():
+            msg = f"{info.field_name} must be a non-empty string"
+            raise ValueError(msg)
+        return v.strip()
+
+    @field_validator("client_secret")
+    @classmethod
+    def validate_client_secret(cls, v: SecretStr) -> SecretStr:
+        """Ensure client_secret is non-empty and trim whitespace."""
+        secret_value = v.get_secret_value()
+        if not secret_value or not secret_value.strip():
+            msg = "client_secret must be a non-empty string"
+            raise ValueError(msg)
+        # Return a new SecretStr with trimmed value
+        return SecretStr(secret_value.strip())
+
+    @abstractmethod
+    def __call__(self) -> "OAuthProviderProtocol":
+        """Create and return the OAuth provider instance.
+
+        Returns:
+            OAuth provider configured with these settings
+        """
+        ...
+
+
+class SessionSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="BELGIE_SESSION_")
+
+    max_age: int = Field(default=604800)
+    update_age: int = Field(default=86400)
+
+
+class CookieSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="BELGIE_COOKIE_")
+
+    name: str = Field(default="belgie_session")
+    secure: bool = Field(default=True)
+    http_only: bool = Field(default=True)
+    same_site: Literal["lax", "strict", "none"] = Field(default="lax")
+    domain: str | None = Field(default=None)
+
+
+class URLSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="BELGIE_URLS_")
+
+    signin_redirect: str = Field(default="/dashboard")
+    signout_redirect: str = Field(default="/")
+
+
+class BelgieSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="BELGIE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+    secret: str
+    base_url: str
+
+    session: SessionSettings = Field(default_factory=SessionSettings)
+    cookie: CookieSettings = Field(default_factory=CookieSettings)
+    urls: URLSettings = Field(default_factory=URLSettings)
+
+    @field_validator("secret", "base_url")
+    @classmethod
+    def validate_non_empty(cls, value: str, info) -> str:  # noqa: ANN001
+        """Ensure required Belgie settings are non-empty."""
+        if not value or not value.strip():
+            msg = f"{info.field_name} must be a non-empty string"
+            raise ValueError(msg)
+        return value.strip()

belgie_core/providers/__init__.py

@@ -0,0 +1,10 @@
+from belgie_core.providers.google import GoogleOAuthProvider, GoogleProviderSettings, GoogleUserInfo
+from belgie_core.providers.protocols import OAuthProviderProtocol, Providers
+
+__all__ = [
+    "GoogleOAuthProvider",
+    "GoogleProviderSettings",
+    "GoogleUserInfo",
+    "OAuthProviderProtocol",
+    "Providers",
+]