fastapi-cachex 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

fastapi_cachex/session/models.py

@@ -0,0 +1,185 @@
+"""Session data models and user structures."""
+
+import logging
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel
+from pydantic import Field
+
+logger = logging.getLogger(__name__)
+
+# Token format constant
+TOKEN_PARTS_COUNT = 3
+
+
+class SessionStatus(str, Enum):
+    """Session status enumeration."""
+
+    ACTIVE = "active"
+    EXPIRED = "expired"
+    INVALIDATED = "invalidated"
+
+
+class SessionUser(BaseModel):
+    """Base session user model.
+
+    This can be extended by application-specific user models.
+    """
+
+    user_id: str
+    username: str | None = None
+    email: str | None = None
+    roles: list[str] = Field(default_factory=list)
+    permissions: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"extra": "allow"}
+
+
+class Session(BaseModel):
+    """Core session model containing all session data."""
+
+    session_id: str = Field(default_factory=lambda: str(uuid4()))
+    user: SessionUser | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    last_accessed: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None
+    status: SessionStatus = SessionStatus.ACTIVE
+    ip_address: str | None = None
+    user_agent: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    flash_messages: list[dict[str, Any]] = Field(default_factory=list)
+
+    model_config = {"use_enum_values": True}
+
+    def is_valid(self) -> bool:
+        """Check if session is valid (active and not expired)."""
+        if self.status != SessionStatus.ACTIVE:
+            return False
+
+        return not (self.expires_at and datetime.now(timezone.utc) > self.expires_at)
+
+    def is_expired(self) -> bool:
+        """Check if session has expired."""
+        if self.expires_at is None:
+            return False
+        return datetime.now(timezone.utc) > self.expires_at
+
+    def update_last_accessed(self) -> None:
+        """Update the last accessed timestamp."""
+        self.last_accessed = datetime.now(timezone.utc)
+        logger.debug("Session last_accessed updated; id=%s", self.session_id)
+
+    def renew(self, ttl: int) -> None:
+        """Renew session expiry time.
+
+        Args:
+            ttl: Time-to-live in seconds
+        """
+        self.expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl)
+        self.update_last_accessed()
+        logger.debug("Session renewed; id=%s ttl=%s", self.session_id, ttl)
+
+    def invalidate(self) -> None:
+        """Mark session as invalidated."""
+        self.status = SessionStatus.INVALIDATED
+        logger.debug("Session invalidated; id=%s", self.session_id)
+
+    def regenerate_id(self) -> str:
+        """Regenerate session ID (for security after login).
+
+        Returns:
+            The new session ID
+        """
+        old_id = self.session_id
+        self.session_id = str(uuid4())
+        logger.debug(
+            "Session ID regenerated; old_id=%s new_id=%s", old_id, self.session_id
+        )
+        return self.session_id
+
+    def add_flash_message(self, message: str, category: str = "info") -> None:
+        """Add a flash message.
+
+        Args:
+            message: The message content
+            category: Message category (info, success, warning, error)
+        """
+        self.flash_messages.append(
+            {
+                "message": message,
+                "category": category,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+        )
+        logger.debug(
+            "Flash message added; id=%s category=%s", self.session_id, category
+        )
+
+    def get_flash_messages(self, clear: bool = True) -> list[dict[str, Any]]:
+        """Get and optionally clear flash messages.
+
+        Args:
+            clear: Whether to clear messages after retrieving
+
+        Returns:
+            List of flash messages
+        """
+        messages = self.flash_messages.copy()
+        if clear:
+            self.flash_messages.clear()
+            logger.debug(
+                "Flash messages cleared; id=%s count=%s", self.session_id, len(messages)
+            )
+        return messages
+
+
+class SessionToken(BaseModel):
+    """Session token containing signed data."""
+
+    session_id: str
+    signature: str
+    issued_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_string(self) -> str:
+        """Convert token to string format.
+
+        Format: {session_id}.{signature}.{timestamp}
+        """
+        timestamp = int(self.issued_at.timestamp())
+
+        logger.debug("SessionToken to_string called; id=%s", self.session_id)
+        return f"{self.session_id}.{self.signature}.{timestamp}"
+
+    @classmethod
+    def from_string(cls, token_str: str) -> "SessionToken":
+        """Parse token from string format.
+
+        Args:
+            token_str: Token string in format {session_id}.{signature}.{timestamp}
+
+        Returns:
+            SessionToken instance
+
+        Raises:
+            ValueError: If token format is invalid
+        """
+        parts = token_str.split(".")
+        if len(parts) != TOKEN_PARTS_COUNT:
+            msg = "Invalid token format"
+            raise ValueError(msg)
+
+        session_id, signature, timestamp = parts
+        try:
+            issued_at = datetime.fromtimestamp(int(timestamp), tz=timezone.utc)
+        except (ValueError, OSError) as e:
+            msg = f"Invalid timestamp in token: {e}"
+            raise ValueError(msg) from e
+
+        logger.debug("SessionToken parsed from string; id=%s", session_id)
+        return cls(session_id=session_id, signature=signature, issued_at=issued_at)

fastapi_cachex/session/security.py

@@ -0,0 +1,111 @@
+"""Security utilities for session management."""
+
+import hashlib
+import hmac
+import logging
+
+from .models import Session
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityManager:
+    """Handles session security operations."""
+
+    def __init__(self, secret_key: str) -> None:
+        """Initialize security manager.
+
+        Args:
+            secret_key: Secret key for signing tokens
+        """
+        if len(secret_key) < 32:  # noqa: PLR2004
+            msg = "Secret key must be at least 32 characters"
+            raise ValueError(msg)
+        self.secret_key = secret_key.encode("utf-8")
+
+        logger.debug(
+            "SecurityManager initialized with secret length=%s", len(secret_key)
+        )
+
+    def sign_session_id(self, session_id: str) -> str:
+        """Sign a session ID using HMAC-SHA256.
+
+        Args:
+            session_id: The session ID to sign
+
+        Returns:
+            The signature as a hex string
+        """
+        return hmac.new(
+            self.secret_key,
+            session_id.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    def verify_signature(self, session_id: str, signature: str) -> bool:
+        """Verify a session signature.
+
+        Args:
+            session_id: The session ID
+            signature: The signature to verify
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        expected_signature = self.sign_session_id(session_id)
+        # Use constant-time comparison to prevent timing attacks
+        valid = hmac.compare_digest(expected_signature, signature)
+
+        if not valid:
+            logger.debug("Signature verification failed; id=%s", session_id)
+        return valid
+
+    def check_ip_match(self, session: Session, current_ip: str | None) -> bool:
+        """Check if session IP matches current request IP.
+
+        Args:
+            session: The session to check
+            current_ip: Current request IP address
+
+        Returns:
+            True if IPs match or session has no IP binding
+        """
+        if session.ip_address is None:
+            return True
+        if current_ip is None:
+            return False
+        return session.ip_address == current_ip
+
+    def check_user_agent_match(
+        self,
+        session: Session,
+        current_user_agent: str | None,
+    ) -> bool:
+        """Check if session User-Agent matches current request.
+
+        Args:
+            session: The session to check
+            current_user_agent: Current request User-Agent
+
+        Returns:
+            True if User-Agents match or session has no UA binding
+        """
+        if session.user_agent is None:
+            return True
+        if current_user_agent is None:
+            return False
+        return session.user_agent == current_user_agent
+
+    def hash_data(self, data: str) -> str:
+        """Hash data using SHA-256.
+
+        Args:
+            data: Data to hash
+
+        Returns:
+            Hex digest of the hash
+        """
+        digest = hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+        logger.debug("Data hashed for session operations")
+        return digest

fastapi_cachex/state/__init__.py

@@ -0,0 +1,8 @@
+"""State management extension for FastAPI-CacheX."""
+
+from .exceptions import InvalidStateError as InvalidStateError
+from .exceptions import StateDataError as StateDataError
+from .exceptions import StateError as StateError
+from .exceptions import StateExpiredError as StateExpiredError
+from .manager import StateManager as StateManager
+from .models import StateData as StateData

fastapi_cachex/state/exceptions.py

@@ -0,0 +1,19 @@
+"""Custom exception classes for state management."""
+
+from fastapi_cachex.exceptions import CacheXError
+
+
+class StateError(CacheXError):
+    """Base exception for state-related errors."""
+
+
+class InvalidStateError(StateError):
+    """Raised when a state is invalid or not found."""
+
+
+class StateExpiredError(StateError):
+    """Raised when a state has expired."""
+
+
+class StateDataError(StateError):
+    """Raised when state data parsing or format is invalid."""

fastapi_cachex/state/manager.py

@@ -0,0 +1,258 @@
+"""State manager for OAuth and session state handling."""
+
+import hashlib
+import json
+import logging
+import secrets
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+from typing import Any
+
+from fastapi_cachex.proxy import BackendProxy
+from fastapi_cachex.types import ETagContent
+
+from .exceptions import InvalidStateError
+from .exceptions import StateDataError
+from .exceptions import StateExpiredError
+from .models import StateData
+
+logger = logging.getLogger(__name__)
+
+# Default TTL for OAuth state (10 minutes)
+DEFAULT_STATE_TTL = 600
+
+
+class StateManager:
+    """Manages OAuth state and session state lifecycle and storage."""
+
+    def __init__(
+        self, key_prefix: str = "oauth_state:", default_ttl: int = DEFAULT_STATE_TTL
+    ) -> None:
+        """Initialize StateManager.
+
+        Args:
+            key_prefix: Prefix for state keys in cache backend
+            default_ttl: Default time-to-live in seconds for state
+        """
+        self.backend = BackendProxy.get_backend()
+        self.key_prefix = key_prefix
+        self.default_ttl = default_ttl
+
+    async def create_state(
+        self,
+        ttl: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Create a new random OAuth state and store it with metadata.
+
+        Args:
+            ttl: Time-to-live in seconds (uses default_ttl if not provided)
+            metadata: Additional metadata to store with the state (e.g., callback_url, user_info)
+
+        Returns:
+            The generated state string
+
+        Raises:
+            StateDataError: If backend storage fails
+        """
+        # Generate a random state string (32 bytes = 256 bits of entropy)
+        state = secrets.token_urlsafe(32)
+
+        # Use provided TTL or default
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+
+        # Create state data model
+        state_data = StateData(
+            state=state,
+            expires_at=datetime.now(timezone.utc) + timedelta(seconds=effective_ttl),
+            metadata=metadata or {},
+        )
+
+        # Serialize to JSON
+        json_content = json.dumps(state_data.model_dump(mode="json"))
+
+        # Create ETag from hash of state data
+        etag = hashlib.sha256(json_content.encode()).hexdigest()
+
+        # Store in backend with TTL using ETagContent
+        cache_key = f"{self.key_prefix}{state}"
+        etag_content = ETagContent(etag=etag, content=json_content)
+        await self.backend.set(cache_key, etag_content, ttl=effective_ttl)
+
+        logger.debug("OAuth state created; state=%s ttl=%s", state, effective_ttl)
+        return state
+
+    async def consume_state(self, state: str) -> StateData:
+        """Consume and validate an OAuth state, removing it from storage.
+
+        Args:
+            state: The state string to validate and consume
+
+        Returns:
+            StateData object containing state data and metadata
+
+        Raises:
+            InvalidStateError: If state is invalid or not found
+            StateExpiredError: If state has expired
+            StateDataError: If state data format is invalid
+        """
+        cache_key = f"{self.key_prefix}{state}"
+
+        # Retrieve state data from backend
+        cached_etag_content = await self.backend.get(cache_key)
+        if cached_etag_content is None:
+            logger.warning("OAuth state not found or expired; state=%s", state)
+            msg = "Invalid or expired state"
+            raise InvalidStateError(msg)
+
+        # Extract content from ETagContent
+        json_content = cached_etag_content.content
+        if not isinstance(json_content, str):
+            msg = "Unexpected state data format"
+            logger.error(
+                "Unexpected content type in state; state=%s type=%s",
+                state,
+                type(json_content),
+            )
+            raise StateDataError(msg)
+
+        # Parse the stored state data
+        try:
+            state_dict: dict[str, Any] = json.loads(json_content)
+        except json.JSONDecodeError as e:
+            msg = f"Failed to parse state data: {e}"
+            logger.exception("Failed to parse state data; state=%s", state)
+            raise StateDataError(msg) from e
+
+        # Validate and create StateData model
+        try:
+            state_data = StateData(**state_dict)
+        except ValueError as e:
+            msg = f"Invalid state data structure: {e}"
+            logger.exception("Failed to create StateData model; state=%s", state)
+            raise StateDataError(msg) from e
+
+        # Verify expiry
+        if datetime.now(timezone.utc) > state_data.expires_at:
+            logger.warning("OAuth state expired; state=%s", state)
+            msg = "State has expired"
+            raise StateExpiredError(msg)
+
+        # Delete the state from backend to prevent reuse
+        await self.backend.delete(cache_key)
+        logger.debug("OAuth state consumed and deleted; state=%s", state)
+
+        return state_data
+
+    async def validate_state(self, state: str) -> bool:
+        """Validate if a state exists and is not expired (without consuming it).
+
+        Args:
+            state: The state string to validate
+
+        Returns:
+            True if state is valid and not expired, False otherwise
+        """
+        cache_key = f"{self.key_prefix}{state}"
+
+        # Try to retrieve state data from backend
+        cached_etag_content = await self.backend.get(cache_key)
+        if cached_etag_content is None:
+            logger.debug("State validation failed - not found; state=%s", state)
+            return False
+
+        # Extract content from ETagContent
+        json_content = cached_etag_content.content
+        if not isinstance(json_content, str):
+            logger.error(
+                "Unexpected content type in state; state=%s type=%s",
+                state,
+                type(json_content),
+            )
+            return False
+
+        try:
+            state_dict: dict[str, Any] = json.loads(json_content)
+        except json.JSONDecodeError:
+            logger.exception(
+                "Failed to parse state data during validation; state=%s",
+                state,
+            )
+            return False
+
+        # Validate and create StateData model
+        try:
+            state_data = StateData(**state_dict)
+        except ValueError:
+            logger.exception(
+                "Failed to create StateData model during validation; state=%s",
+                state,
+            )
+            return False
+
+        # Check expiry
+        if datetime.now(timezone.utc) > state_data.expires_at:
+            logger.debug("State validation failed - expired; state=%s", state)
+            return False
+
+        logger.debug("State validation succeeded; state=%s", state)
+        return True
+
+    async def get_state_metadata(self, state: str) -> dict[str, Any] | None:
+        """Retrieve metadata for a state without consuming it.
+
+        Args:
+            state: The state string
+
+        Returns:
+            Metadata dictionary if state exists and is valid, None otherwise
+        """
+        cache_key = f"{self.key_prefix}{state}"
+
+        cached_etag_content = await self.backend.get(cache_key)
+        if cached_etag_content is None:
+            return None
+
+        # Extract content from ETagContent
+        json_content = cached_etag_content.content
+        if not isinstance(json_content, str):
+            logger.error(
+                "Unexpected content type in state; state=%s type=%s",
+                state,
+                type(json_content),
+            )
+            return None
+
+        try:
+            state_dict: dict[str, Any] = json.loads(json_content)
+        except json.JSONDecodeError:
+            logger.exception("Failed to parse state data; state=%s", state)
+            return None
+
+        # Validate and create StateData model
+        try:
+            state_data = StateData(**state_dict)
+        except ValueError:
+            logger.exception("Failed to create StateData model; state=%s", state)
+            return None
+
+        # Check expiry
+        if datetime.now(timezone.utc) > state_data.expires_at:
+            return None
+
+        return state_data.metadata
+
+    async def delete_state(self, state: str) -> bool:
+        """Manually delete a state from storage.
+
+        Args:
+            state: The state string to delete
+
+        Returns:
+            True if state was deleted, False if it didn't exist
+        """
+        cache_key = f"{self.key_prefix}{state}"
+        await self.backend.delete(cache_key)
+        logger.debug("OAuth state deleted; state=%s", state)
+        return True

fastapi_cachex/state/models.py

@@ -0,0 +1,31 @@
+"""Data models for state management."""
+
+from datetime import datetime
+from datetime import timezone
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import field_serializer
+
+
+class StateData(BaseModel):
+    """OAuth state data model."""
+
+    model_config = ConfigDict()
+
+    state: str = Field(..., description="The unique state identifier")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the state was created",
+    )
+    expires_at: datetime = Field(..., description="When the state expires")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata associated with state"
+    )
+
+    @field_serializer("created_at", "expires_at", when_used="json")
+    def serialize_datetime(self, value: datetime) -> str:
+        """Serialize datetime to ISO format string for JSON."""
+        return value.isoformat()

fastapi_cachex/types.py

@@ -1,8 +1,17 @@
 """Type definitions and type aliases for FastAPI-CacheX."""
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
 
+from fastapi import Request
+
+# Cache key separator - using ||| to avoid conflicts with port numbers in host (e.g., 127.0.0.1:8000)
+CACHE_KEY_SEPARATOR = "|||"
+
+# Type for custom cache key builder function
+CacheKeyBuilder = Callable[[Request], str]
+
 
 @dataclass
 class ETagContent: