belgie 0.1.0a4__py3-none-any.whl

belgie/auth/providers/google.py

@@ -0,0 +1,284 @@
+from collections.abc import AsyncGenerator, Callable
+from datetime import UTC, datetime, timedelta
+from typing import Literal
+from urllib.parse import urlencode, urlparse, urlunparse
+
+import httpx
+from belgie_proto import AdapterProtocol, DBConnection
+from fastapi import APIRouter, Depends
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_settings import SettingsConfigDict
+
+from belgie.auth.core.exceptions import InvalidStateError, OAuthError
+from belgie.auth.core.hooks import HookContext, HookRunner
+from belgie.auth.core.settings import CookieSettings, ProviderSettings
+from belgie.auth.utils.crypto import generate_state_token
+
+
+class GoogleProviderSettings(ProviderSettings):
+    """Google OAuth provider settings loaded from environment.
+
+    Contains only Google-specific OAuth configuration.
+    Session and redirect settings are passed via get_router() parameters.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="BELGIE_GOOGLE_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    scopes: list[str] = Field(default=["openid", "email", "profile"])
+    access_type: str = Field(default="offline")
+    prompt: str = Field(default="consent")
+
+    def __call__(self) -> "GoogleOAuthProvider":
+        """Create and return Google OAuth provider instance.
+
+        Returns:
+            GoogleOAuthProvider configured with these settings
+        """
+        return GoogleOAuthProvider(settings=self)
+
+
+class GoogleUserInfo(BaseModel):
+    model_config = ConfigDict(strict=True, extra="ignore")
+
+    id: str
+    email: str
+    verified_email: bool
+    name: str | None = None
+    given_name: str | None = None
+    family_name: str | None = None
+    picture: str | None = None
+    locale: str | None = None
+
+
+class GoogleOAuthProvider:
+    """Google OAuth provider - self-contained implementation."""
+
+    AUTHORIZATION_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+    TOKEN_URL = "https://oauth2.googleapis.com/token"  # noqa: S105
+    USER_INFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo"
+
+    def __init__(self, settings: GoogleProviderSettings) -> None:
+        self.settings = settings
+
+    @property
+    def provider_id(self) -> Literal["google"]:
+        return "google"
+
+    def generate_authorization_url(self, state: str) -> str:
+        """Generate Google OAuth authorization URL."""
+        params = {
+            "client_id": self.settings.client_id,
+            "redirect_uri": self.settings.redirect_uri,
+            "response_type": "code",
+            "scope": " ".join(self.settings.scopes),
+            "state": state,
+            "access_type": self.settings.access_type,
+            "prompt": self.settings.prompt,
+        }
+        parsed = urlparse(self.AUTHORIZATION_URL)
+        return urlunparse(
+            (
+                parsed.scheme,
+                parsed.netloc,
+                parsed.path,
+                "",
+                urlencode(params),
+                "",
+            ),
+        )
+
+    async def exchange_code_for_tokens(self, code: str) -> dict:
+        """Exchange authorization code for access and refresh tokens."""
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    self.TOKEN_URL,
+                    data={
+                        "client_id": self.settings.client_id,
+                        "client_secret": self.settings.client_secret.get_secret_value(),
+                        "code": code,
+                        "redirect_uri": self.settings.redirect_uri,
+                        "grant_type": "authorization_code",
+                    },
+                )
+                response.raise_for_status()
+                tokens = response.json()
+
+                if "access_token" not in tokens:
+                    msg = "missing required field in token response: access_token"
+                    raise OAuthError(msg)
+
+                # Calculate expires_at if expires_in is present
+                return {
+                    "access_token": tokens["access_token"],
+                    "token_type": tokens.get("token_type"),
+                    "refresh_token": tokens.get("refresh_token"),
+                    "scope": tokens.get("scope"),
+                    "id_token": tokens.get("id_token"),
+                    "expires_at": (
+                        datetime.now(UTC) + timedelta(seconds=tokens["expires_in"]) if "expires_in" in tokens else None
+                    ),
+                }
+        except httpx.HTTPStatusError as e:
+            # Safely extract error code from response without exposing sensitive details
+            error_detail = ""
+            try:
+                error_data = e.response.json()
+                if isinstance(error_data, dict) and "error" in error_data:
+                    error_detail = f" ({error_data['error']})"
+            except (ValueError, KeyError, TypeError):
+                # Ignore JSON parsing errors or missing fields
+                pass
+            msg = f"oauth token exchange failed: {e.response.status_code}{error_detail}"
+            raise OAuthError(msg) from e
+        except httpx.RequestError as e:
+            msg = "oauth token exchange request failed"
+            raise OAuthError(msg) from e
+
+    async def get_user_info(self, access_token: str) -> GoogleUserInfo:
+        """Fetch user information from Google using access token."""
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    self.USER_INFO_URL,
+                    headers={"Authorization": f"Bearer {access_token}"},
+                )
+                response.raise_for_status()
+                user_data = response.json()
+                return GoogleUserInfo(**user_data)
+        except httpx.HTTPStatusError as e:
+            # Safely extract error code from response without exposing sensitive details
+            error_detail = ""
+            try:
+                error_data = e.response.json()
+                if isinstance(error_data, dict) and "error" in error_data:
+                    error_detail = f" ({error_data['error']})"
+            except (ValueError, KeyError, TypeError):
+                # Ignore JSON parsing errors or missing fields
+                pass
+            msg = f"failed to fetch user info: {e.response.status_code}{error_detail}"
+            raise OAuthError(msg) from e
+        except httpx.RequestError as e:
+            msg = "user info request failed"
+            raise OAuthError(msg) from e
+
+    def get_router(  # noqa: PLR0913
+        self,
+        adapter: AdapterProtocol,
+        cookie_settings: CookieSettings,
+        session_max_age: int,
+        signin_redirect: str,
+        signout_redirect: str,  # noqa: ARG002
+        hook_runner: HookRunner,
+        db_dependency: Callable[[], DBConnection | AsyncGenerator[DBConnection, None]],
+    ) -> APIRouter:
+        """Create router with Google OAuth endpoints."""
+        router = APIRouter(prefix=f"/{self.provider_id}", tags=["auth", "oauth"])
+
+        async def signin(db: DBConnection = Depends(db_dependency)) -> RedirectResponse:  # noqa: B008
+            """Initiate Google OAuth flow."""
+            # Generate and store state token with expiration
+            state = generate_state_token()
+            expires_at = datetime.now(UTC) + timedelta(minutes=10)
+            await adapter.create_oauth_state(
+                db,
+                state=state,
+                expires_at=expires_at.replace(tzinfo=None),
+            )
+
+            # Generate authorization URL using helper method
+            auth_url = self.generate_authorization_url(state)
+            return RedirectResponse(url=auth_url, status_code=302)
+
+        async def callback(code: str, state: str, db: DBConnection = Depends(db_dependency)) -> RedirectResponse:  # noqa: B008
+            """Handle Google OAuth callback."""
+            # Validate and delete state token (use walrus operator)
+            if not await adapter.get_oauth_state(db, state):
+                msg = "Invalid OAuth state"
+                raise InvalidStateError(msg)
+            await adapter.delete_oauth_state(db, state)
+
+            # Exchange code for tokens using helper method
+            tokens = await self.exchange_code_for_tokens(code)
+
+            # Fetch user info using helper method
+            user_info = await self.get_user_info(tokens["access_token"])
+
+            created = False
+            # Get or create user (use walrus operator)
+            if not (user := await adapter.get_user_by_email(db, user_info.email)):
+                user = await adapter.create_user(
+                    db,
+                    email=user_info.email,
+                    email_verified=user_info.verified_email,
+                    name=user_info.name,
+                    image=user_info.picture,
+                )
+                created = True
+
+            # Create or update OAuth account (use dict.get for optional tokens)
+            if await adapter.get_account_by_user_and_provider(
+                db,
+                user.id,
+                self.provider_id,
+            ):
+                await adapter.update_account(
+                    db,
+                    user_id=user.id,
+                    provider=self.provider_id,
+                    access_token=tokens["access_token"],
+                    refresh_token=tokens.get("refresh_token"),
+                    expires_at=tokens.get("expires_at"),
+                    scope=tokens.get("scope"),
+                )
+            else:
+                await adapter.create_account(
+                    db,
+                    user_id=user.id,
+                    provider=self.provider_id,
+                    provider_account_id=user_info.id,
+                    access_token=tokens["access_token"],
+                    refresh_token=tokens.get("refresh_token"),
+                    expires_at=tokens.get("expires_at"),
+                    scope=tokens.get("scope"),
+                )
+
+            # Hooks: signup (only on create)
+            if created:
+                async with hook_runner.dispatch("on_signup", HookContext(user=user, db=db)):
+                    pass
+
+            # Create session with proper expiration
+            expires_at = datetime.now(UTC) + timedelta(seconds=session_max_age)
+            session = await adapter.create_session(
+                db,
+                user_id=user.id,
+                expires_at=expires_at.replace(tzinfo=None),
+            )
+
+            async with hook_runner.dispatch("on_signin", HookContext(user=user, db=db)):
+                pass
+
+            # Set session cookie using centralized cookie settings
+            response = RedirectResponse(url=signin_redirect, status_code=302)
+            response.set_cookie(
+                key=cookie_settings.name,
+                value=str(session.id),
+                max_age=session_max_age,
+                httponly=cookie_settings.http_only,
+                secure=cookie_settings.secure,
+                samesite=cookie_settings.same_site,
+                domain=cookie_settings.domain,
+            )
+            return response
+
+        # Register routes
+        router.add_api_route("/signin", signin, methods=["GET"])
+        router.add_api_route("/callback", callback, methods=["GET"])
+
+        return router

belgie/auth/providers/protocols.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Callable  # noqa: TC003
+from typing import TYPE_CHECKING, NotRequired, Protocol, TypedDict, runtime_checkable
+
+from pydantic_settings import BaseSettings
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+    from belgie_proto import AdapterProtocol, DBConnection
+    from fastapi import APIRouter
+
+    from belgie.auth.core.hooks import HookRunner
+    from belgie.auth.core.settings import CookieSettings
+    from belgie.auth.providers.google import GoogleProviderSettings
+
+
+@runtime_checkable
+class OAuthProviderProtocol[S: BaseSettings](Protocol):
+    """Protocol that all OAuth providers must implement."""
+
+    def __init__(self, settings: S) -> None: ...
+
+    @property
+    def provider_id(self) -> str: ...
+
+    def get_router(  # noqa: PLR0913
+        self,
+        adapter: AdapterProtocol,
+        cookie_settings: CookieSettings,
+        session_max_age: int,
+        signin_redirect: str,
+        signout_redirect: str,
+        hook_runner: HookRunner,
+        db_dependency: Callable[[], DBConnection | AsyncGenerator[DBConnection, None]],
+    ) -> APIRouter: ...
+
+
+class Providers(TypedDict, total=False):
+    """Type-safe provider registry for Auth initialization."""
+
+    google: NotRequired[GoogleProviderSettings]

belgie/auth/session/__init__.py

@@ -0,0 +1,3 @@
+from belgie.auth.session.manager import SessionManager
+
+__all__ = ["SessionManager"]

belgie/auth/session/manager.py

@@ -0,0 +1,168 @@
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from belgie_proto import (
+    AccountProtocol,
+    AdapterProtocol,
+    DBConnection,
+    OAuthStateProtocol,
+    SessionProtocol,
+    UserProtocol,
+)
+
+
+class SessionManager[
+    UserT: UserProtocol,
+    AccountT: AccountProtocol,
+    SessionT: SessionProtocol,
+    OAuthStateT: OAuthStateProtocol,
+]:
+    """Manages user sessions with sliding window expiration.
+
+    The SessionManager handles session creation, retrieval, validation, and automatic
+    expiration refresh. It implements a sliding window mechanism where sessions are
+    automatically extended when accessed within the update_age threshold.
+
+    Attributes:
+        adapter: Database adapter for session persistence
+        max_age: Maximum session lifetime in seconds
+        update_age: Minimum time before expiry to trigger session refresh (in seconds)
+
+    Example:
+        >>> manager = SessionManager(
+        ...     adapter=adapter,
+        ...     max_age=3600 * 24 * 7,  # 7 days
+        ...     update_age=3600,  # Refresh if < 1 hour until expiry
+        ... )
+        >>> session = await manager.create_session(db, user_id=user.id)
+    """
+
+    def __init__(
+        self,
+        adapter: AdapterProtocol[UserT, AccountT, SessionT, OAuthStateT],
+        max_age: int,
+        update_age: int,
+    ) -> None:
+        """Initialize the SessionManager.
+
+        Args:
+            adapter: Database adapter for session persistence
+            max_age: Maximum session lifetime in seconds
+            update_age: Minimum time before expiry to trigger session refresh (in seconds)
+        """
+        self.adapter = adapter
+        self.max_age = max_age
+        self.update_age = update_age
+
+    async def create_session(
+        self,
+        db: DBConnection,
+        user_id: UUID,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+    ) -> SessionT:
+        """Create a new session for a user.
+
+        Args:
+            db: Database connection
+            user_id: UUID of the user
+            ip_address: Optional IP address of the client
+            user_agent: Optional User-Agent string of the client
+
+        Returns:
+            Newly created session object
+
+        Example:
+            >>> session = await manager.create_session(
+            ...     db, user_id=user.id, ip_address="192.168.1.1", user_agent="Mozilla/5.0..."
+            ... )
+        """
+        expires_at = datetime.now(UTC) + timedelta(seconds=self.max_age)
+        return await self.adapter.create_session(
+            db,
+            user_id=user_id,
+            expires_at=expires_at,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+
+    async def get_session(
+        self,
+        db: DBConnection,
+        session_id: UUID,
+    ) -> SessionT | None:
+        """Retrieve and validate a session with sliding window refresh.
+
+        Retrieves the session, checks if it's expired (deletes if expired), and
+        automatically extends the expiration if the session is within update_age
+        of expiring (sliding window mechanism).
+
+        Args:
+            db: Database connection
+            session_id: UUID of the session to retrieve
+
+        Returns:
+            Valid session object or None if not found/expired
+
+        Example:
+            >>> session = await manager.get_session(db, session_id)
+            >>> if session:
+            ...     print(f"Session expires at {session.expires_at}")
+            ... else:
+            ...     print("Session not found or expired")
+        """
+        session = await self.adapter.get_session(db, session_id)
+
+        if not session:
+            return None
+
+        now = datetime.now(UTC)
+
+        if session.expires_at.replace(tzinfo=UTC) <= now:
+            await self.adapter.delete_session(db, session_id)
+            return None
+
+        time_until_expiry = session.expires_at.replace(tzinfo=UTC) - now
+        if time_until_expiry.total_seconds() < self.update_age:
+            new_expires_at = now + timedelta(seconds=self.max_age)
+            session = await self.adapter.update_session(
+                db,
+                session_id,
+                expires_at=new_expires_at,
+            )
+
+        return session
+
+    async def delete_session(self, db: DBConnection, session_id: UUID) -> bool:
+        """Delete a session.
+
+        Args:
+            db: Database connection
+            session_id: UUID of the session to delete
+
+        Returns:
+            True if session was deleted, False if it didn't exist
+
+        Example:
+            >>> deleted = await manager.delete_session(db, session_id)
+            >>> if deleted:
+            ...     print("Session deleted successfully")
+        """
+        return await self.adapter.delete_session(db, session_id)
+
+    async def cleanup_expired_sessions(self, db: DBConnection) -> int:
+        """Delete all expired sessions from the database.
+
+        Useful for periodic cleanup tasks to remove stale session data.
+
+        Args:
+            db: Database connection
+
+        Returns:
+            Number of sessions deleted
+
+        Example:
+            >>> count = await manager.cleanup_expired_sessions(db)
+            >>> print(f"Deleted {count} expired sessions")
+        """
+        return await self.adapter.delete_expired_sessions(db)

belgie/auth/utils/__init__.py

@@ -0,0 +1,9 @@
+from belgie.auth.utils.crypto import generate_session_id, generate_state_token
+from belgie.auth.utils.scopes import parse_scopes, validate_scopes
+
+__all__ = [
+    "generate_session_id",
+    "generate_state_token",
+    "parse_scopes",
+    "validate_scopes",
+]

belgie/auth/utils/crypto.py

@@ -0,0 +1,10 @@
+import secrets
+from uuid import UUID, uuid4
+
+
+def generate_state_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def generate_session_id() -> UUID:
+    return uuid4()

belgie/auth/utils/scopes.py

@@ -0,0 +1,49 @@
+import json
+from collections.abc import Sequence
+
+
+def parse_scopes(scopes_str: str) -> list[str]:
+    scopes_str = scopes_str.strip()
+
+    if not scopes_str:
+        return []
+
+    if scopes_str.startswith("["):
+        try:
+            parsed = json.loads(scopes_str)
+            if isinstance(parsed, list):
+                return [str(scope) for scope in parsed]
+        except json.JSONDecodeError:
+            pass
+
+    return [scope.strip() for scope in scopes_str.split(",") if scope.strip()]
+
+
+def validate_scopes[S: str](
+    user_scopes: Sequence[S] | None,
+    required_scopes: Sequence[S],
+) -> bool:
+    # Normalize to sets for comparison
+    # Generic over any str subclass (including StrEnum)
+    # Accepts any sequence type (list, tuple, set, etc.)
+    # None is treated as empty set (no scopes)
+    user_scopes_set = set(user_scopes) if user_scopes is not None else set()
+    required_scopes_set = set(required_scopes)
+
+    # Check if all required scopes are present in user scopes
+    return required_scopes_set.issubset(user_scopes_set)
+
+
+def has_any_scope[S: str](
+    user_scopes: Sequence[S] | None,
+    required_scopes: Sequence[S],
+) -> bool:
+    # Normalize to sets for comparison
+    # Generic over any str subclass (including StrEnum)
+    # Accepts any sequence type (list, tuple, set, etc.)
+    # None is treated as empty set (no scopes)
+    user_scopes_set = set(user_scopes) if user_scopes is not None else set()
+    required_scopes_set = set(required_scopes)
+
+    # Check if user has any of the required scopes
+    return bool(user_scopes_set & required_scopes_set)

belgie/mcp.py

@@ -0,0 +1,12 @@
+"""MCP re-exports for belgie consumers."""
+
+_MCP_IMPORT_ERROR = "belgie.mcp requires the 'mcp' extra. Install with: uv add belgie[mcp]"
+
+try:
+    from belgie_mcp import hello  # type: ignore[import-not-found]
+except ModuleNotFoundError as exc:
+    raise ImportError(_MCP_IMPORT_ERROR) from exc
+
+__all__ = [
+    "hello",
+]

belgie/oauth.py

@@ -0,0 +1,12 @@
+"""OAuth re-exports for belgie consumers."""
+
+_OAUTH_IMPORT_ERROR = "belgie.oauth requires the 'oauth' extra. Install with: uv add belgie[oauth]"
+
+try:
+    from belgie_oauth import hello  # type: ignore[import-not-found]
+except ModuleNotFoundError as exc:
+    raise ImportError(_OAUTH_IMPORT_ERROR) from exc
+
+__all__ = [
+    "hello",
+]

belgie/proto.py

@@ -0,0 +1,22 @@
+"""Protocol re-exports for belgie consumers."""
+
+_PROTO_IMPORT_ERROR = "belgie.proto requires belgie-proto. Install with: uv add belgie-proto"
+
+try:
+    from belgie_proto import (  # type: ignore[import-not-found]
+        AccountProtocol,
+        AdapterProtocol,
+        OAuthStateProtocol,
+        SessionProtocol,
+        UserProtocol,
+    )
+except ModuleNotFoundError as exc:
+    raise ImportError(_PROTO_IMPORT_ERROR) from exc
+
+__all__ = [
+    "AccountProtocol",
+    "AdapterProtocol",
+    "OAuthStateProtocol",
+    "SessionProtocol",
+    "UserProtocol",
+]