byoi 0.1.0a1__py3-none-any.whl

byoi/cache.py

@@ -0,0 +1,346 @@
+"""Cache implementations for the BYOI library.
+
+Provides caching for JWKS and OIDC discovery documents.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import weakref
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Self
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+logger = logging.getLogger("byoi.cache")
+
+# Track all InMemoryCache instances for cleanup on interpreter shutdown
+_active_caches: weakref.WeakSet[InMemoryCache] = weakref.WeakSet()
+
+__all__ = (
+    "CacheProtocol",
+    "InMemoryCache",
+    "RedisCache",
+    "NullCache",
+)
+
+
+class CacheProtocol(ABC):
+    """Abstract base class for cache implementations."""
+
+    @abstractmethod
+    async def get(self, key: str) -> Any | None:
+        """Get a value from the cache.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            The cached value, or None if not found or expired.
+        """
+        ...
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Set a value in the cache.
+
+        Args:
+            key: The cache key.
+            value: The value to cache (must be JSON-serializable).
+            ttl_seconds: Time-to-live in seconds. None means no expiration.
+        """
+        ...
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """Delete a value from the cache.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            True if the key was deleted, False if not found.
+        """
+        ...
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all values from the cache."""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close the cache connection and release resources."""
+        ...
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the async context manager and close the cache."""
+        await self.close()
+
+
+class NullCache(CacheProtocol):
+    """A no-op cache implementation that doesn't cache anything.
+
+    Useful for testing or when caching is not desired.
+    """
+
+    async def get(self, key: str) -> Any | None:
+        """Always returns None."""
+        return None
+
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Does nothing."""
+        pass
+
+    async def delete(self, key: str) -> bool:
+        """Always returns False."""
+        return False
+
+    async def clear(self) -> None:
+        """Does nothing."""
+        pass
+
+    async def close(self) -> None:
+        """Does nothing."""
+        pass
+
+
+class InMemoryCache(CacheProtocol):
+    """In-memory cache implementation using a dictionary.
+
+    Suitable for single-process deployments or development.
+
+    Note: This cache is not shared across processes. For multi-process
+    deployments, use RedisCache instead.
+    """
+
+    def __init__(self, cleanup_interval_seconds: int = 300) -> None:
+        """Initialize the in-memory cache.
+
+        Args:
+            cleanup_interval_seconds: How often to run cleanup of expired entries.
+        """
+        self._cache: dict[str, tuple[Any, float | None]] = {}
+        self._lock = asyncio.Lock()
+        self._cleanup_interval = cleanup_interval_seconds
+        self._cleanup_task: asyncio.Task[None] | None = None
+        self._closed = False
+        self._started = False
+        # Track this instance for cleanup on interpreter shutdown
+        _active_caches.add(self)
+
+    def __del__(self) -> None:
+        """Cancel cleanup task on garbage collection if not properly closed."""
+        if self._cleanup_task is not None and not self._cleanup_task.done():
+            self._cleanup_task.cancel()
+            self._cleanup_task = None
+        self._closed = True
+
+    async def start(self) -> None:
+        """Start the background cleanup task.
+
+        This method is idempotent - calling it multiple times has no effect.
+        It is also called automatically on first cache operation.
+        """
+        if self._started or self._closed:
+            return
+        self._started = True
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+    async def _ensure_started(self) -> None:
+        """Ensure the cache cleanup task is started."""
+        if not self._started and not self._closed:
+            await self.start()
+
+    async def _cleanup_loop(self) -> None:
+        """Background task to periodically clean up expired entries."""
+        while not self._closed:
+            try:
+                await asyncio.sleep(self._cleanup_interval)
+                await self._cleanup_expired()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                # Log error but continue cleanup loop
+                logger.warning("Error during cache cleanup: %s", e)
+
+    async def _cleanup_expired(self) -> None:
+        """Remove expired entries from the cache."""
+        now = time.time()
+        async with self._lock:
+            expired_keys = [
+                key
+                for key, (_, expiry) in self._cache.items()
+                if expiry is not None and expiry < now
+            ]
+            for key in expired_keys:
+                del self._cache[key]
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value from the cache."""
+        await self._ensure_started()
+        async with self._lock:
+            if key not in self._cache:
+                return None
+
+            value, expiry = self._cache[key]
+            if expiry is not None and expiry < time.time():
+                del self._cache[key]
+                return None
+
+            return value
+
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Set a value in the cache."""
+        await self._ensure_started()
+        expiry = time.time() + ttl_seconds if ttl_seconds is not None else None
+        async with self._lock:
+            self._cache[key] = (value, expiry)
+
+    async def delete(self, key: str) -> bool:
+        """Delete a value from the cache."""
+        await self._ensure_started()
+        async with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                return True
+            return False
+
+    async def clear(self) -> None:
+        """Clear all values from the cache."""
+        await self._ensure_started()
+        async with self._lock:
+            self._cache.clear()
+
+    async def close(self) -> None:
+        """Stop the cleanup task and close the cache."""
+        self._closed = True
+        if self._cleanup_task is not None:
+            self._cleanup_task.cancel()
+            try:
+                await self._cleanup_task
+            except asyncio.CancelledError:
+                pass
+            self._cleanup_task = None
+
+
+class RedisCache(CacheProtocol):
+    """Redis-based cache implementation.
+
+    Suitable for multi-process and distributed deployments.
+
+    Requires the `redis` package to be installed:
+        pip install redis
+    """
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379/0",
+        key_prefix: str = "byoi:",
+        max_connections: int | None = None,
+        **redis_kwargs: Any,
+    ) -> None:
+        """Initialize the Redis cache.
+
+        Args:
+            url: Redis connection URL.
+            key_prefix: Prefix for all cache keys.
+            max_connections: Maximum number of connections in the pool.
+                If None, uses the redis library default.
+            **redis_kwargs: Additional arguments passed to Redis client.
+        """
+        self._url = url
+        self._key_prefix = key_prefix
+        self._max_connections = max_connections
+        self._redis_kwargs = redis_kwargs
+        self._client: Any = None
+        self._closed = False
+
+    async def _get_client(self) -> Any:
+        """Get or create the Redis client."""
+        if self._client is None:
+            try:
+                import redis.asyncio as redis
+                from redis.asyncio.connection import ConnectionPool
+            except ImportError as e:
+                raise ImportError(
+                    "Redis support requires the 'redis' package. "
+                    "Install it with: pip install redis"
+                ) from e
+
+            # Create connection pool with max_connections if specified
+            pool_kwargs: dict[str, Any] = {}
+            if self._max_connections is not None:
+                pool_kwargs["max_connections"] = self._max_connections
+
+            pool = ConnectionPool.from_url(self._url, **pool_kwargs, **self._redis_kwargs)
+            self._client = redis.Redis(connection_pool=pool)
+
+        return self._client
+
+    def _make_key(self, key: str) -> str:
+        """Create a prefixed cache key."""
+        return f"{self._key_prefix}{key}"
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value from Redis."""
+        client = await self._get_client()
+        value = await client.get(self._make_key(key))
+        if value is None:
+            return None
+        try:
+            return json.loads(value)
+        except (json.JSONDecodeError, TypeError):
+            return value
+
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Set a value in Redis."""
+        client = await self._get_client()
+        serialized = json.dumps(value)
+        if ttl_seconds is not None:
+            await client.setex(self._make_key(key), ttl_seconds, serialized)
+        else:
+            await client.set(self._make_key(key), serialized)
+
+    async def delete(self, key: str) -> bool:
+        """Delete a value from Redis."""
+        client = await self._get_client()
+        result = await client.delete(self._make_key(key))
+        return result > 0
+
+    async def clear(self) -> None:
+        """Clear all BYOI keys from Redis.
+
+        Warning: This uses SCAN to find keys with the prefix and deletes them.
+        For large datasets, this may be slow.
+        """
+        client = await self._get_client()
+        pattern = f"{self._key_prefix}*"
+        cursor = 0
+        while True:
+            cursor, keys = await client.scan(cursor, match=pattern, count=100)
+            if keys:
+                await client.delete(*keys)
+            if cursor == 0:
+                break
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        self._closed = True
+        if self._client is not None:
+            await self._client.close()
+            self._client = None

byoi/config.py

@@ -0,0 +1,349 @@
+"""BYOI - Bring Your Own Identity.
+
+Main configuration and lifecycle management for the BYOI library.
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from fastapi import FastAPI
+from pydantic import BaseModel, ConfigDict, Field
+
+from byoi.cache import CacheProtocol, InMemoryCache
+from byoi.errors import ConfigurationError
+from byoi.models import OIDCProviderConfig
+from byoi.providers import ProviderManager
+from byoi.service import AuthService
+
+if TYPE_CHECKING:
+    from byoi.repositories import (
+        AuthStateRepositoryProtocol,
+        LinkedIdentityRepositoryProtocol,
+        UserRepositoryProtocol,
+    )
+
+__all__ = (
+    "BYOI",
+    "BYOIConfig",
+)
+
+
+class BYOIConfig(BaseModel):
+    """Configuration for the BYOI library.
+
+    This Pydantic model holds all configuration needed to initialize BYOI.
+
+    Attributes:
+        user_repository: Repository for user data persistence.
+        identity_repository: Repository for linked identity data persistence.
+        auth_state_repository: Repository for auth state (PKCE, nonce) persistence.
+        cache: Cache implementation for JWKS and discovery docs.
+        providers: List of OIDC provider configurations to register.
+        discovery_ttl_seconds: TTL for cached discovery documents.
+        jwks_ttl_seconds: TTL for cached JWKS.
+        state_expiration_minutes: How long auth states are valid.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        frozen=False,
+    )
+
+    user_repository: Any = Field(
+        ...,
+        description="Repository for user data persistence (must implement UserRepositoryProtocol)",
+    )
+    identity_repository: Any = Field(
+        ...,
+        description="Repository for linked identity data persistence (must implement LinkedIdentityRepositoryProtocol)",
+    )
+    auth_state_repository: Any = Field(
+        ...,
+        description="Repository for auth state (PKCE, nonce) persistence (must implement AuthStateRepositoryProtocol)",
+    )
+    cache: CacheProtocol | None = Field(
+        default=None,
+        description="Cache implementation for JWKS and discovery docs. Defaults to InMemoryCache.",
+    )
+    providers: list[OIDCProviderConfig] = Field(
+        default_factory=list,
+        description="List of OIDC provider configurations to register.",
+    )
+    discovery_ttl_seconds: int = Field(
+        default=3600,
+        ge=0,
+        description="TTL for cached discovery documents in seconds.",
+    )
+    jwks_ttl_seconds: int = Field(
+        default=3600,
+        ge=0,
+        description="TTL for cached JWKS in seconds.",
+    )
+    state_expiration_minutes: int = Field(
+        default=10,
+        ge=1,
+        le=60,
+        description="How long auth states are valid in minutes.",
+    )
+    http_timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=120.0,
+        description="Timeout for HTTP requests to identity providers in seconds.",
+    )
+
+
+class BYOI:
+    """Main BYOI class for configuration and lifecycle management.
+
+    This class provides a single point to initialize and configure BYOI,
+    and can be integrated with FastAPI's lifespan for proper resource
+    management.
+
+    Example:
+        ```python
+        from contextlib import asynccontextmanager
+        from fastapi import FastAPI
+        from byoi import BYOI, BYOIConfig, OIDCProviderConfig
+
+        # Create your repository implementations
+        user_repo = MyUserRepository()
+        identity_repo = MyIdentityRepository()
+        auth_state_repo = MyAuthStateRepository()
+
+        # Configure BYOI
+        config = BYOIConfig(
+            user_repository=user_repo,
+            identity_repository=identity_repo,
+            auth_state_repository=auth_state_repo,
+            providers=[
+                OIDCProviderConfig(
+                    name="google",
+                    display_name="Google",
+                    issuer="https://accounts.google.com",
+                    client_id="your-client-id",
+                    client_secret="your-client-secret",
+                ),
+            ],
+        )
+
+        byoi = BYOI(config)
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            await byoi.setup(app)
+            yield
+            await byoi.shutdown()
+
+        app = FastAPI(lifespan=lifespan)
+        ```
+    """
+
+    def __init__(self, config: BYOIConfig) -> None:
+        """Initialize BYOI.
+
+        Args:
+            config: The BYOI configuration.
+        """
+        self._config = config
+        self._provider_manager: ProviderManager | None = None
+        self._auth_service: AuthService | None = None
+        self._http_client: httpx.AsyncClient | None = None
+        self._cache: CacheProtocol | None = None
+        self._is_setup = False
+
+    @property
+    def provider_manager(self) -> ProviderManager:
+        """Get the provider manager.
+
+        Raises:
+            RuntimeError: If BYOI is not set up.
+        """
+        if self._provider_manager is None:
+            raise RuntimeError("BYOI is not set up. Call setup() first.")
+        return self._provider_manager
+
+    @property
+    def auth_service(self) -> AuthService:
+        """Get the auth service.
+
+        Raises:
+            RuntimeError: If BYOI is not set up.
+        """
+        if self._auth_service is None:
+            raise RuntimeError("BYOI is not set up. Call setup() first.")
+        return self._auth_service
+
+    async def setup(self, app: FastAPI | None = None) -> None:
+        """Set up BYOI and register with FastAPI app.
+
+        This method initializes all BYOI components and stores them
+        in the FastAPI app state for dependency injection.
+
+        Args:
+            app: Optional FastAPI application to register with.
+
+        Raises:
+            ConfigurationError: If configuration is invalid.
+        """
+        if self._is_setup:
+            return
+
+        # Create HTTP client
+        self._http_client = httpx.AsyncClient(
+            timeout=httpx.Timeout(self._config.http_timeout_seconds),
+            follow_redirects=True,
+        )
+
+        # Set up cache
+        if self._config.cache is not None:
+            self._cache = self._config.cache
+        else:
+            cache = InMemoryCache()
+            await cache.start()
+            self._cache = cache
+
+        # Create provider manager
+        self._provider_manager = ProviderManager(
+            cache=self._cache,
+            http_client=self._http_client,
+            discovery_ttl_seconds=self._config.discovery_ttl_seconds,
+            jwks_ttl_seconds=self._config.jwks_ttl_seconds,
+            http_timeout_seconds=self._config.http_timeout_seconds,
+        )
+
+        # Register providers
+        for provider_config in self._config.providers:
+            try:
+                self._provider_manager.register_provider(provider_config)
+            except ValueError as e:
+                raise ConfigurationError(str(e)) from e
+
+        # Create auth service
+        self._auth_service = AuthService(
+            provider_manager=self._provider_manager,
+            user_repository=self._config.user_repository,
+            identity_repository=self._config.identity_repository,
+            auth_state_repository=self._config.auth_state_repository,
+            state_expiration_minutes=self._config.state_expiration_minutes,
+            http_client=self._http_client,
+            http_timeout_seconds=self._config.http_timeout_seconds,
+        )
+
+        # Register with FastAPI app
+        if app is not None:
+            app.state.byoi_provider_manager = self._provider_manager
+            app.state.byoi_auth_service = self._auth_service
+            app.state.byoi = self
+
+        self._is_setup = True
+
+    async def shutdown(self) -> None:
+        """Shut down BYOI and release resources.
+
+        This should be called when the application is shutting down.
+        """
+        if not self._is_setup:
+            return
+
+        # Close auth service
+        if self._auth_service is not None:
+            await self._auth_service.close()
+            self._auth_service = None
+
+        # Close provider manager
+        if self._provider_manager is not None:
+            await self._provider_manager.close()
+            self._provider_manager = None
+
+        # Close HTTP client
+        if self._http_client is not None:
+            await self._http_client.aclose()
+            self._http_client = None
+
+        # Close cache
+        if self._cache is not None:
+            await self._cache.close()
+            self._cache = None
+
+        self._is_setup = False
+
+    def add_provider(self, config: OIDCProviderConfig) -> None:
+        """Add a provider after setup.
+
+        Args:
+            config: The provider configuration.
+
+        Raises:
+            RuntimeError: If BYOI is not set up.
+            ValueError: If the provider is already registered.
+        """
+        if not self._is_setup:
+            raise RuntimeError("BYOI is not set up. Call setup() first.")
+        self._provider_manager.register_provider(config)
+
+    def remove_provider(self, name: str) -> bool:
+        """Remove a provider after setup.
+
+        Args:
+            name: The provider name.
+
+        Returns:
+            True if the provider was removed, False if not found.
+
+        Raises:
+            RuntimeError: If BYOI is not set up.
+        """
+        if not self._is_setup:
+            raise RuntimeError("BYOI is not set up. Call setup() first.")
+        return self._provider_manager.unregister_provider(name)
+
+    @asynccontextmanager
+    async def lifespan(
+        self,
+        app: FastAPI,
+    ) -> AsyncGenerator[None, None]:
+        """FastAPI lifespan context manager for BYOI.
+
+        Use this as your FastAPI lifespan to automatically set up
+        and shut down BYOI.
+
+        Args:
+            app: The FastAPI application.
+
+        Example:
+            ```python
+            byoi = BYOI(config)
+            app = FastAPI(lifespan=byoi.lifespan)
+            ```
+        """
+        await self.setup(app)
+        try:
+            yield
+        finally:
+            await self.shutdown()
+
+    @staticmethod
+    def create_lifespan(
+        config: BYOIConfig,
+    ):
+        """Create a lifespan context manager for a given config.
+
+        This is a convenience method that creates a BYOI instance
+        and returns its lifespan method.
+
+        Args:
+            config: The BYOI configuration.
+
+        Returns:
+            A lifespan context manager.
+
+        Example:
+            ```python
+            app = FastAPI(lifespan=BYOI.create_lifespan(config))
+            ```
+        """
+        byoi = BYOI(config)
+        return byoi.lifespan