skrift 0.1.0a1__py3-none-any.whl

skrift/auth/guards.py

@@ -0,0 +1,130 @@
+"""Permission and Role guards for Litestar routes."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from litestar.connection import ASGIConnection
+from litestar.exceptions import NotAuthorizedException
+from litestar.handlers import BaseRouteHandler
+
+if TYPE_CHECKING:
+    from skrift.auth.services import UserPermissions
+
+
+ADMINISTRATOR_PERMISSION = "administrator"
+
+
+class AuthRequirement(ABC):
+    """Base class for authorization requirements with operator overloading."""
+
+    @abstractmethod
+    async def check(self, permissions: "UserPermissions") -> bool:
+        """Check if the requirement is satisfied."""
+        ...
+
+    def __or__(self, other: "AuthRequirement") -> "OrRequirement":
+        """Combine requirements with OR logic."""
+        return OrRequirement(self, other)
+
+    def __and__(self, other: "AuthRequirement") -> "AndRequirement":
+        """Combine requirements with AND logic."""
+        return AndRequirement(self, other)
+
+    def __call__(
+        self, connection: ASGIConnection, _: BaseRouteHandler
+    ) -> None:
+        """Guard function for use with Litestar guards parameter.
+
+        This is a synchronous wrapper - actual checking happens in the async guard.
+        """
+        pass
+
+
+class OrRequirement(AuthRequirement):
+    """Combines two requirements with OR logic."""
+
+    def __init__(self, left: AuthRequirement, right: AuthRequirement):
+        self.left = left
+        self.right = right
+
+    async def check(self, permissions: "UserPermissions") -> bool:
+        """Return True if either requirement is satisfied."""
+        return await self.left.check(permissions) or await self.right.check(permissions)
+
+
+class AndRequirement(AuthRequirement):
+    """Combines two requirements with AND logic."""
+
+    def __init__(self, left: AuthRequirement, right: AuthRequirement):
+        self.left = left
+        self.right = right
+
+    async def check(self, permissions: "UserPermissions") -> bool:
+        """Return True if both requirements are satisfied."""
+        return await self.left.check(permissions) and await self.right.check(permissions)
+
+
+class Permission(AuthRequirement):
+    """Permission requirement for route guards."""
+
+    def __init__(self, permission: str):
+        self.permission = permission
+
+    async def check(self, permissions: "UserPermissions") -> bool:
+        """Check if user has the required permission or administrator permission."""
+        # Administrator permission bypasses all checks
+        if ADMINISTRATOR_PERMISSION in permissions.permissions:
+            return True
+        return self.permission in permissions.permissions
+
+
+class Role(AuthRequirement):
+    """Role requirement for route guards."""
+
+    def __init__(self, role: str):
+        self.role = role
+
+    async def check(self, permissions: "UserPermissions") -> bool:
+        """Check if user has the required role or administrator permission."""
+        # Administrator permission bypasses all checks
+        if ADMINISTRATOR_PERMISSION in permissions.permissions:
+            return True
+        return self.role in permissions.roles
+
+
+async def auth_guard(
+    connection: ASGIConnection, route_handler: BaseRouteHandler
+) -> None:
+    """Litestar guard that checks authentication and authorization requirements.
+
+    This guard checks the guards parameter of route handlers for AuthRequirement
+    instances and validates them against the user's permissions and roles.
+    """
+    from skrift.auth.services import get_user_permissions
+
+    # Get user_id from session
+    user_id = connection.session.get("user_id") if connection.session else None
+
+    if not user_id:
+        raise NotAuthorizedException("Authentication required")
+
+    # Get the guards from the route handler
+    guards = route_handler.guards or []
+
+    # Find AuthRequirement guards
+    auth_requirements = [g for g in guards if isinstance(g, AuthRequirement)]
+
+    if not auth_requirements:
+        return  # No auth requirements, just needs to be logged in
+
+    # Get user's permissions and roles
+    session_maker = connection.app.state.session_maker_class
+    async with session_maker() as session:
+        permissions = await get_user_permissions(session, user_id)
+
+    # Check all requirements
+    for requirement in auth_requirements:
+        if not await requirement.check(permissions):
+            raise NotAuthorizedException("Insufficient permissions")

skrift/auth/roles.py

@@ -0,0 +1,94 @@
+"""Role definitions for the application."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RoleDefinition:
+    """Definition of a role with its permissions."""
+
+    name: str
+    permissions: set[str] = field(default_factory=set)
+    display_name: str | None = None
+    description: str | None = None
+
+
+def create_role(
+    name: str,
+    *permissions: str,
+    display_name: str | None = None,
+    description: str | None = None,
+) -> RoleDefinition:
+    """Create a role definition with the given permissions.
+
+    Args:
+        name: The unique identifier for the role
+        *permissions: Permission strings granted by this role
+        display_name: Human-readable name for the role
+        description: Description of the role's purpose
+
+    Returns:
+        A RoleDefinition instance
+    """
+    return RoleDefinition(
+        name=name,
+        permissions=set(permissions),
+        display_name=display_name or name.title(),
+        description=description,
+    )
+
+
+# Default role definitions
+# The "administrator" permission is special - it bypasses all permission checks
+
+ADMIN = create_role(
+    "admin",
+    "administrator",
+    "manage-users",
+    "manage-pages",
+    "modify-site",
+    display_name="Administrator",
+    description="Full system access with all permissions",
+)
+
+AUTHOR = create_role(
+    "author",
+    "view-drafts",
+    display_name="Author",
+    description="Can view draft content",
+)
+
+EDITOR = create_role(
+    "editor",
+    "view-drafts",
+    "manage-pages",
+    display_name="Editor",
+    description="Can manage pages and view drafts",
+)
+
+MODERATOR = create_role(
+    "moderator",
+    "view-drafts",
+    display_name="Moderator",
+    description="Can moderate content",
+)
+
+# Registry of all role definitions
+ROLE_DEFINITIONS: dict[str, RoleDefinition] = {
+    role.name: role for role in [ADMIN, AUTHOR, EDITOR, MODERATOR]
+}
+
+
+def get_role_definition(name: str) -> RoleDefinition | None:
+    """Get a role definition by name."""
+    return ROLE_DEFINITIONS.get(name)
+
+
+def register_role(role: RoleDefinition) -> None:
+    """Register a custom role definition.
+
+    This allows applications to add custom roles beyond the defaults.
+    """
+    ROLE_DEFINITIONS[role.name] = role

skrift/auth/services.py

@@ -0,0 +1,184 @@
+"""Authentication and authorization services."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import delete, select
+from sqlalchemy.orm import selectinload
+
+from skrift.db.models.role import Role, RolePermission
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+
+# Cache for user permissions with TTL
+_permission_cache: dict[str, tuple[datetime, "UserPermissions"]] = {}
+CACHE_TTL = timedelta(minutes=5)
+
+
+@dataclass
+class UserPermissions:
+    """Container for a user's permissions and roles."""
+
+    user_id: str
+    roles: set[str] = field(default_factory=set)
+    permissions: set[str] = field(default_factory=set)
+
+
+async def get_user_permissions(
+    session: "AsyncSession", user_id: str | UUID
+) -> UserPermissions:
+    """Get all permissions and roles for a user.
+
+    Results are cached with a TTL for performance.
+    """
+    user_id_str = str(user_id)
+
+    # Check cache
+    if user_id_str in _permission_cache:
+        cached_time, cached_perms = _permission_cache[user_id_str]
+        if datetime.now() - cached_time < CACHE_TTL:
+            return cached_perms
+
+    # Query user with roles and permissions
+    from skrift.db.models.user import User
+
+    result = await session.execute(
+        select(User)
+        .where(User.id == (UUID(user_id_str) if isinstance(user_id, str) else user_id))
+        .options(selectinload(User.roles).selectinload(Role.permissions))
+    )
+    user = result.scalar_one_or_none()
+
+    permissions = UserPermissions(user_id=user_id_str)
+
+    if user:
+        for role in user.roles:
+            permissions.roles.add(role.name)
+            for role_perm in role.permissions:
+                permissions.permissions.add(role_perm.permission)
+
+    # Update cache
+    _permission_cache[user_id_str] = (datetime.now(), permissions)
+
+    return permissions
+
+
+def invalidate_user_permissions_cache(user_id: str | UUID | None = None) -> None:
+    """Invalidate cached permissions for a user or all users.
+
+    Args:
+        user_id: Specific user to invalidate, or None to clear all cache
+    """
+    if user_id is None:
+        _permission_cache.clear()
+    else:
+        _permission_cache.pop(str(user_id), None)
+
+
+async def assign_role_to_user(
+    session: "AsyncSession", user_id: str | UUID, role_name: str
+) -> bool:
+    """Assign a role to a user.
+
+    Returns True if the role was assigned, False if role not found.
+    """
+    from skrift.db.models.user import User
+
+    user_id_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+
+    # Get user and role
+    user_result = await session.execute(
+        select(User).where(User.id == user_id_uuid).options(selectinload(User.roles))
+    )
+    user = user_result.scalar_one_or_none()
+
+    role_result = await session.execute(select(Role).where(Role.name == role_name))
+    role = role_result.scalar_one_or_none()
+
+    if not user or not role:
+        return False
+
+    # Check if already assigned
+    if role not in user.roles:
+        user.roles.append(role)
+        await session.commit()
+        invalidate_user_permissions_cache(user_id)
+
+    return True
+
+
+async def remove_role_from_user(
+    session: "AsyncSession", user_id: str | UUID, role_name: str
+) -> bool:
+    """Remove a role from a user.
+
+    Returns True if the role was removed, False if not found.
+    """
+    from skrift.db.models.user import User
+
+    user_id_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+
+    # Get user with roles
+    user_result = await session.execute(
+        select(User).where(User.id == user_id_uuid).options(selectinload(User.roles))
+    )
+    user = user_result.scalar_one_or_none()
+
+    if not user:
+        return False
+
+    # Find and remove the role
+    for role in user.roles:
+        if role.name == role_name:
+            user.roles.remove(role)
+            await session.commit()
+            invalidate_user_permissions_cache(user_id)
+            return True
+
+    return False
+
+
+async def sync_roles_to_database(session: "AsyncSession") -> None:
+    """Sync role definitions from code to the database.
+
+    This creates or updates roles based on the definitions in roles.py.
+    """
+    from skrift.auth.roles import ROLE_DEFINITIONS
+
+    for role_def in ROLE_DEFINITIONS.values():
+        # Check if role exists
+        result = await session.execute(select(Role).where(Role.name == role_def.name))
+        role = result.scalar_one_or_none()
+
+        if role:
+            # Update existing role
+            role.display_name = role_def.display_name
+            role.description = role_def.description
+
+            # Remove old permissions
+            await session.execute(
+                delete(RolePermission).where(RolePermission.role_id == role.id)
+            )
+        else:
+            # Create new role
+            role = Role(
+                name=role_def.name,
+                display_name=role_def.display_name,
+                description=role_def.description,
+            )
+            session.add(role)
+            await session.flush()  # Get the role ID
+
+        # Add permissions
+        for permission in role_def.permissions:
+            role_permission = RolePermission(role_id=role.id, permission=permission)
+            session.add(role_permission)
+
+    await session.commit()
+    invalidate_user_permissions_cache()

skrift/cli.py

@@ -0,0 +1,45 @@
+"""CLI commands for Skrift database management."""
+
+import sys
+from pathlib import Path
+
+
+def db() -> None:
+    """Run Alembic database migrations.
+
+    This is a thin wrapper around Alembic that sets up the correct working
+    directory and passes through all arguments.
+
+    Usage:
+        skrift-db upgrade head     # Apply all migrations
+        skrift-db downgrade -1     # Rollback one migration
+        skrift-db current          # Show current revision
+        skrift-db history          # Show migration history
+        skrift-db revision -m "description" --autogenerate  # Create new migration
+    """
+    from alembic.config import main as alembic_main
+
+    # Ensure we're running from the project root where alembic.ini is located
+    # If alembic.ini is not in cwd, check common locations
+    alembic_ini = Path.cwd() / "alembic.ini"
+
+    if not alembic_ini.exists():
+        # Try to find alembic.ini relative to this module
+        module_dir = Path(__file__).parent.parent
+        alembic_ini = module_dir / "alembic.ini"
+
+        if alembic_ini.exists():
+            # Change to the directory containing alembic.ini
+            import os
+            os.chdir(module_dir)
+        else:
+            print("Error: Could not find alembic.ini", file=sys.stderr)
+            print("Make sure you're running from the project root directory.", file=sys.stderr)
+            sys.exit(1)
+
+    # Pass through all CLI arguments to Alembic
+    sys.exit(alembic_main(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    db()

skrift/config.py

@@ -0,0 +1,192 @@
+import os
+import re
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Load .env file early so env vars are available for YAML interpolation
+# Use explicit path to handle subprocess spawning (uvicorn workers)
+_env_file = Path(__file__).parent.parent / ".env"
+load_dotenv(_env_file)
+
+# Pattern to match $VAR_NAME environment variable references
+ENV_VAR_PATTERN = re.compile(r"\$([A-Z_][A-Z0-9_]*)")
+
+
+def interpolate_env_vars(value, strict: bool = True):
+    """Recursively replace $VAR_NAME with os.environ values.
+
+    Args:
+        value: The value to interpolate
+        strict: If True, raise an error when env var is not set.
+                If False, return the original $VAR_NAME reference.
+    """
+    if isinstance(value, str):
+
+        def replace(match):
+            var = match.group(1)
+            val = os.environ.get(var)
+            if val is None:
+                if strict:
+                    raise ValueError(f"Environment variable ${var} not set")
+                return match.group(0)  # Return original $VAR_NAME
+            return val
+
+        return ENV_VAR_PATTERN.sub(replace, value)
+    elif isinstance(value, dict):
+        return {k: interpolate_env_vars(v, strict) for k, v in value.items()}
+    elif isinstance(value, list):
+        return [interpolate_env_vars(item, strict) for item in value]
+    return value
+
+
+def load_app_config(interpolate: bool = True, strict: bool = True) -> dict:
+    """Load and parse app.yaml with optional environment variable interpolation.
+
+    Args:
+        interpolate: Whether to interpolate environment variables
+        strict: If interpolating, whether to raise errors for missing env vars
+
+    Returns:
+        Parsed configuration dictionary
+    """
+    config_path = Path.cwd() / "app.yaml"
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"app.yaml not found at {config_path}")
+
+    with open(config_path, "r") as f:
+        config = yaml.safe_load(f)
+
+    if interpolate:
+        return interpolate_env_vars(config, strict=strict)
+    return config
+
+
+def load_raw_app_config() -> dict | None:
+    """Load app.yaml without any processing. Returns None if file doesn't exist."""
+    config_path = Path.cwd() / "app.yaml"
+
+    if not config_path.exists():
+        return None
+
+    with open(config_path, "r") as f:
+        return yaml.safe_load(f)
+
+
+class DatabaseConfig(BaseModel):
+    """Database connection configuration."""
+
+    url: str = "sqlite+aiosqlite:///./app.db"
+    pool_size: int = 5
+    pool_overflow: int = 10
+    pool_timeout: int = 30
+    echo: bool = False
+
+
+class OAuthProviderConfig(BaseModel):
+    """OAuth provider configuration."""
+
+    client_id: str
+    client_secret: str
+    scopes: list[str] = ["openid", "email", "profile"]
+    # Optional tenant ID for Microsoft/Azure AD
+    tenant_id: str | None = None
+
+
+class AuthConfig(BaseModel):
+    """Authentication configuration."""
+
+    redirect_base_url: str = "http://localhost:8000"
+    providers: dict[str, OAuthProviderConfig] = {}
+
+    def get_redirect_uri(self, provider: str) -> str:
+        """Get the OAuth callback URL for a provider."""
+        return f"{self.redirect_base_url}/auth/{provider}/callback"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    # Application
+    debug: bool = False
+    secret_key: str
+
+    # Database config (loaded from app.yaml)
+    db: DatabaseConfig = DatabaseConfig()
+
+    # Auth config (loaded from app.yaml)
+    auth: AuthConfig = AuthConfig()
+
+
+def clear_settings_cache() -> None:
+    """Clear the settings cache to force reload."""
+    get_settings.cache_clear()
+
+
+def is_config_valid() -> tuple[bool, str | None]:
+    """Check if the current configuration is valid and complete.
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    try:
+        config = load_raw_app_config()
+        if config is None:
+            return False, "app.yaml not found"
+
+        # Check database URL
+        db_config = config.get("db", {})
+        db_url = db_config.get("url")
+        if not db_url:
+            return False, "Database URL not configured"
+
+        # If it's an env var reference, check if env var is set
+        if isinstance(db_url, str) and db_url.startswith("$"):
+            env_var = db_url[1:]
+            if not os.environ.get(env_var):
+                return False, f"Database environment variable ${env_var} not set"
+
+        # Check auth providers
+        auth_config = config.get("auth", {})
+        providers = auth_config.get("providers", {})
+        if not providers:
+            return False, "No authentication providers configured"
+
+        return True, None
+    except Exception as e:
+        return False, str(e)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Load settings from .env and app.yaml."""
+    # First create base settings from .env
+    base_settings = Settings()
+
+    # Load app.yaml config
+    try:
+        app_config = load_app_config()
+    except FileNotFoundError:
+        return base_settings
+    except ValueError:
+        # Missing environment variables - return base settings
+        return base_settings
+
+    # Merge YAML config with settings
+    updates = {}
+
+    if "db" in app_config:
+        updates["db"] = DatabaseConfig(**app_config["db"])
+
+    if "auth" in app_config:
+        updates["auth"] = AuthConfig(**app_config["auth"])
+
+    if updates:
+        return base_settings.model_copy(update=updates)
+
+    return base_settings

skrift/controllers/__init__.py

@@ -0,0 +1,4 @@
+from skrift.controllers.auth import AuthController
+from skrift.controllers.web import WebController
+
+__all__ = ["AuthController", "WebController"]