keyrunes-python-sdk 0.0.1__py3-none-any.whl

keyrunes_sdk/config.py

@@ -0,0 +1,203 @@
+"""Global configuration and client management for Keyrunes SDK."""
+
+from threading import Lock
+from typing import Optional
+
+from keyrunes_sdk.client import KeyrunesClient
+
+
+class _GlobalConfig:
+    """
+    Thread-safe global configuration for Keyrunes SDK.
+
+    This class manages a global KeyrunesClient instance that can be configured
+    once and used throughout the application without passing it explicitly
+    to decorators and functions.
+
+    Example:
+        >>> from keyrunes_sdk import configure, require_group
+        >>>
+        >>> # Configure once at application startup
+        >>> configure(base_url="https://keyrunes.example.com")
+        >>>
+        >>> # Use decorators without passing client
+        >>> @require_group("admins")
+        ... def delete_user(user_id: str):
+        ...     pass
+    """
+
+    def __init__(self) -> None:
+        """Initialize global configuration."""
+        self._client: Optional[KeyrunesClient] = None
+        self._lock = Lock()
+
+    def set_client(self, client: KeyrunesClient) -> None:
+        """
+        Set the global client instance.
+
+        Args:
+            client: KeyrunesClient instance to use globally
+
+        Example:
+            >>> from keyrunes_sdk import get_config
+            >>> from keyrunes_sdk.client import KeyrunesClient
+            >>>
+            >>> client = KeyrunesClient("https://keyrunes.example.com")
+            >>> get_config().set_client(client)
+        """
+        with self._lock:
+            self._client = client
+
+    def get_client(self) -> Optional[KeyrunesClient]:
+        """
+        Get the global client instance.
+
+        Returns:
+            Global KeyrunesClient instance or None if not configured
+
+        Example:
+            >>> from keyrunes_sdk import get_config
+            >>>
+            >>> client = get_config().get_client()
+            >>> if client:
+            ...     user = client.get_current_user()
+        """
+        with self._lock:
+            return self._client
+
+    def configure(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        timeout: int = 30,
+    ) -> KeyrunesClient:
+        """
+        Configure and create global client instance.
+
+        Args:
+            base_url: Base URL of the Keyrunes API
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds (default: 30)
+
+        Returns:
+            Configured KeyrunesClient instance
+
+        Example:
+            >>> from keyrunes_sdk import get_config
+            >>>
+            >>> client = get_config().configure(
+            ...     base_url="https://keyrunes.example.com",
+            ...     api_key="my-api-key"
+            ... )
+        """
+        client = KeyrunesClient(
+            base_url=base_url, api_key=api_key, timeout=timeout
+        )
+        self.set_client(client)
+        return client
+
+    def clear(self) -> None:
+        """
+        Clear the global client instance.
+
+        Example:
+            >>> from keyrunes_sdk import get_config
+            >>>
+            >>> get_config().clear()
+        """
+        with self._lock:
+            if self._client:
+                self._client.close()
+            self._client = None
+
+
+_config = _GlobalConfig()
+
+
+def get_config() -> _GlobalConfig:
+    """
+    Get the global configuration instance.
+
+    Returns:
+        Global configuration instance
+
+    Example:
+        >>> from keyrunes_sdk import get_config
+        >>>
+        >>> config = get_config()
+        >>> config.configure(base_url="https://keyrunes.example.com")
+    """
+    return _config
+
+
+def configure(
+    base_url: str,
+    api_key: Optional[str] = None,
+    timeout: int = 30,
+) -> KeyrunesClient:
+    """
+    Configure the global Keyrunes client.
+
+    This is a convenience function that configures the global client instance.
+    After calling this function, decorators will automatically use this client
+    without needing to pass it explicitly.
+
+    Args:
+        base_url: Base URL of the Keyrunes API
+        api_key: Optional API key for authentication
+        timeout: Request timeout in seconds (default: 30)
+
+    Returns:
+        Configured KeyrunesClient instance
+
+    Example:
+        >>> from keyrunes_sdk import configure, require_group
+        >>>
+        >>> # Configure once at app startup
+        >>> client = configure("https://keyrunes.example.com")
+        >>> client.login("user@example.com", "password")
+        >>>
+        >>> # Now decorators work without passing client
+        >>> @require_group("admins")
+        ... def admin_only_function(user_id: str):
+        ...     print(f"Admin function for {user_id}")
+        >>>
+        >>> admin_only_function(user_id="user123")
+    """
+    return _config.configure(
+        base_url=base_url,
+        api_key=api_key,
+        timeout=timeout,
+    )
+
+
+def get_global_client() -> Optional[KeyrunesClient]:
+    """
+    Get the global client instance.
+
+    Returns:
+        Global KeyrunesClient instance or None if not configured
+
+    Raises:
+        RuntimeError: If client is not configured
+
+    Example:
+        >>> from keyrunes_sdk import configure, get_global_client
+        >>>
+        >>> configure("https://keyrunes.example.com")
+        >>> client = get_global_client()
+        >>> user = client.get_current_user()
+    """
+    return _config.get_client()
+
+
+def clear_global_client() -> None:
+    """
+    Clear the global client instance.
+
+    Example:
+        >>> from keyrunes_sdk import clear_global_client
+        >>>
+        >>> clear_global_client()
+    """
+    _config.clear()

keyrunes_sdk/decorators.py

@@ -0,0 +1,248 @@
+"""Decorators for Keyrunes authorization."""
+
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from keyrunes_sdk.client import KeyrunesClient
+from keyrunes_sdk.exceptions import AuthorizationError, UserNotFoundError
+
+
+def _get_client(
+    client: Optional[KeyrunesClient], kwargs: dict
+) -> KeyrunesClient:
+    """
+    Get client from decorator, kwargs, or global config.
+
+    Args:
+        client: Client passed to decorator
+        kwargs: Function kwargs that might contain 'client'
+
+    Returns:
+        KeyrunesClient instance
+
+    Raises:
+        ValueError: If no client is available
+    """
+    if client:
+        return client
+
+    if "client" in kwargs:
+        client_from_kwargs = kwargs["client"]
+        if isinstance(client_from_kwargs, KeyrunesClient):
+            return client_from_kwargs
+
+    from keyrunes_sdk.config import get_global_client
+
+    global_client = get_global_client()
+    if global_client is not None:
+        return global_client
+
+    raise ValueError(
+        "KeyrunesClient not provided. Either:\n"
+        "1. Pass 'client' parameter to decorator: "
+        "@require_group('admins', client=client)\n"
+        "2. Pass 'client' in function kwargs: "
+        "func(user_id='123', client=client)\n"
+        "3. Configure global client: "
+        "configure('https://keyrunes.example.com')"
+    )
+
+
+def require_group(
+    *group_ids: str,
+    client: Optional[KeyrunesClient] = None,
+    user_id_param: str = "user_id",
+    all_groups: bool = False,
+) -> Callable:
+    """
+    Decorator to require user membership in one or more groups.
+
+    This decorator checks if a user belongs to the specified group(s) before
+    executing the decorated function. If the user doesn't have the required
+    group membership, an AuthorizationError is raised.
+
+    Args:
+        *group_ids: One or more group IDs to check
+        client: KeyrunesClient instance
+            (if None, expects 'client' in kwargs)
+        user_id_param: Name of the parameter containing user_id
+            (default: 'user_id')
+        all_groups: If True, user must belong to ALL groups;
+            if False, ANY group (default: False)
+
+    Returns:
+        Decorated function
+
+    Raises:
+        AuthorizationError: If user doesn't have required group membership
+        ValueError: If client is not provided
+
+    Example:
+        >>> @require_group("admins")
+        ... def delete_user(user_id: str, client: KeyrunesClient):
+        ...     # This function only executes if user is in 'admins' group
+        ...     pass
+
+        >>> @require_group("admins", "moderators", all_groups=False)
+        ... def moderate_content(user_id: str, client: KeyrunesClient):
+        ...     # User needs to be in 'admins' OR 'moderators'
+        ...     pass
+
+        >>> @require_group("admins", "verified", all_groups=True)
+        ... def sensitive_operation(user_id: str, client: KeyrunesClient):
+        ...     # User needs to be in BOTH 'admins' AND 'verified'
+        ...     pass
+
+        >>> # Using with a custom client
+        >>> my_client = KeyrunesClient("https://keyrunes.example.com")
+        >>> my_client.login("admin@example.com", "password")
+        >>>
+        >>> @require_group("admins", client=my_client)
+        ... def admin_only_function(user_id: str):
+        ...     print(f"Admin function for user {user_id}")
+        >>>
+        >>> admin_only_function(user_id="user123")
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            keyrunes_client = _get_client(client, kwargs)
+
+            user_id = kwargs.get(user_id_param)
+
+            if not user_id:
+                import inspect
+
+                sig = inspect.signature(func)
+                param_names = list(sig.parameters.keys())
+
+                if user_id_param in param_names:
+                    param_index = param_names.index(user_id_param)
+                    if param_index < len(args):
+                        user_id = args[param_index]
+
+            if not user_id:
+                raise ValueError(
+                    f"User ID not found. Expected parameter "
+                    f"'{user_id_param}' in function arguments."
+                )
+
+            if all_groups:
+                for group_id in group_ids:
+                    if not keyrunes_client.has_group(user_id, group_id):
+                        raise AuthorizationError(
+                            f"User '{user_id}' does not have required "
+                            f"group '{group_id}'. All groups required: "
+                            f"{group_ids}"
+                        )
+            else:
+                has_any_group = False
+                for group_id in group_ids:
+                    if keyrunes_client.has_group(user_id, group_id):
+                        has_any_group = True
+                        break
+
+                if not has_any_group:
+                    raise AuthorizationError(
+                        f"User '{user_id}' does not belong to any of "
+                        f"the required groups: {group_ids}"
+                    )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def require_admin(
+    client: Optional[KeyrunesClient] = None,
+    user_id_param: str = "user_id",
+) -> Callable:
+    """
+    Decorator to require admin privileges.
+
+    Convenience decorator that checks if user has admin flag set.
+
+    Args:
+        client: KeyrunesClient instance
+            (if None, expects 'client' in kwargs)
+        user_id_param: Name of the parameter containing user_id
+            (default: 'user_id')
+
+    Returns:
+        Decorated function
+
+    Raises:
+        AuthorizationError: If user doesn't have admin privileges
+
+    Example:
+        >>> @require_admin()
+        ... def system_config(user_id: str, client: KeyrunesClient):
+        ...     # Only admins can execute this
+        ...     pass
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            keyrunes_client = _get_client(client, kwargs)
+
+            user_id = kwargs.get(user_id_param)
+            if not user_id:
+                import inspect
+
+                sig = inspect.signature(func)
+                param_names = list(sig.parameters.keys())
+
+                if user_id_param in param_names:
+                    param_index = param_names.index(user_id_param)
+                    if param_index < len(args):
+                        user_id = args[param_index]
+
+            if not user_id:
+                raise ValueError(
+                    f"User ID not found in parameter '{user_id_param}'"
+                )
+
+            token_user_id = (
+                str(keyrunes_client._token_data.get("sub", ""))
+                if keyrunes_client._token_data
+                else None
+            )
+
+            if token_user_id and str(user_id) == token_user_id:
+                groups = (
+                    keyrunes_client._token_data.get("groups", [])
+                    if keyrunes_client._token_data
+                    else []
+                )
+                is_admin = (
+                    "admins" in groups
+                    or "superadmin" in groups
+                    or any("admin" in str(g).lower() for g in groups)
+                )
+                if not is_admin:
+                    raise AuthorizationError(
+                        f"User '{user_id}' does not have admin privileges."
+                    )
+            else:
+                try:
+                    user = keyrunes_client.get_user(user_id)
+                    if not user.is_admin:
+                        raise AuthorizationError(
+                            f"User '{user_id}' does not have admin "
+                            f"privileges."
+                        )
+                except UserNotFoundError:
+                    raise AuthorizationError(
+                        f"User '{user_id}' not found or does not have "
+                        f"admin privileges."
+                    )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

keyrunes_sdk/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for Keyrunes SDK."""
+
+
+class KeyrunesError(Exception):
+    """Base exception for all Keyrunes SDK errors."""
+
+    pass
+
+
+class AuthenticationError(KeyrunesError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class AuthorizationError(KeyrunesError):
+    """Raised when authorization fails."""
+
+    pass
+
+
+class GroupNotFoundError(KeyrunesError):
+    """Raised when a group is not found."""
+
+    pass
+
+
+class UserNotFoundError(KeyrunesError):
+    """Raised when a user is not found."""
+
+    pass
+
+
+class InvalidTokenError(KeyrunesError):
+    """Raised when token is invalid or expired."""
+
+    pass
+
+
+class NetworkError(KeyrunesError):
+    """Raised when network request fails."""
+
+    pass

keyrunes_sdk/models.py

@@ -0,0 +1,100 @@
+"""Data models for Keyrunes SDK."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class User(BaseModel):
+    """User model."""
+
+    id: str = Field(..., description="User ID")
+    username: str = Field(..., description="Username")
+    email: EmailStr = Field(..., description="User email")
+    groups: List[str] = Field(
+        default_factory=list, description="List of group IDs"
+    )
+    attributes: Dict[str, Any] = Field(
+        default_factory=dict, description="User attributes"
+    )
+    created_at: Optional[datetime] = Field(
+        None, description="Creation timestamp"
+    )
+    updated_at: Optional[datetime] = Field(
+        None, description="Last update timestamp"
+    )
+    is_active: bool = Field(True, description="Whether user is active")
+    is_admin: bool = Field(
+        False, description="Whether user has admin privileges"
+    )
+
+
+class Group(BaseModel):
+    """Group model."""
+
+    id: str = Field(..., description="Group ID")
+    name: str = Field(..., description="Group name")
+    description: Optional[str] = Field(None, description="Group description")
+    permissions: List[str] = Field(
+        default_factory=list, description="List of permissions"
+    )
+    created_at: Optional[datetime] = Field(
+        None, description="Creation timestamp"
+    )
+
+
+class Token(BaseModel):
+    """Authentication token model."""
+
+    access_token: str = Field(..., description="JWT access token")
+    token_type: str = Field("bearer", description="Token type")
+    expires_in: Optional[int] = Field(
+        None, description="Token expiration in seconds"
+    )
+    refresh_token: Optional[str] = Field(None, description="Refresh token")
+    user: Optional[User] = Field(None, description="User information")
+
+
+class UserRegistration(BaseModel):
+    """User registration data."""
+
+    username: str = Field(
+        ..., min_length=3, max_length=50, description="Username"
+    )
+    email: EmailStr = Field(..., description="User email")
+    password: str = Field(..., min_length=8, description="Password")
+    attributes: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional attributes"
+    )
+
+
+class AdminRegistration(UserRegistration):
+    """Admin registration data (extends UserRegistration)."""
+
+    admin_key: str = Field(..., description="Admin registration key")
+
+
+class LoginCredentials(BaseModel):
+    """Login credentials."""
+
+    identity: str = Field(..., description="Username or email")
+    password: str = Field(..., description="Password")
+
+    @classmethod
+    def from_username(cls, username: str, password: str) -> "LoginCredentials":
+        """Create from username parameter (for backward compatibility)."""
+        return cls(identity=username, password=password)
+
+
+class GroupCheck(BaseModel):
+    """Group membership check result."""
+
+    user_id: str = Field(..., description="User ID")
+    group_id: str = Field(..., description="Group ID")
+    has_access: bool = Field(
+        ..., description="Whether user has access to group"
+    )
+    checked_at: datetime = Field(
+        default_factory=datetime.utcnow, description="Check timestamp"
+    )