skrift 0.1.0a12__py3-none-any.whl

skrift/auth/__init__.py

@@ -0,0 +1,58 @@
+"""Authentication and authorization module."""
+
+from skrift.auth.guards import (
+    ADMINISTRATOR_PERMISSION,
+    AndRequirement,
+    AuthRequirement,
+    OrRequirement,
+    Permission,
+    Role,
+    auth_guard,
+)
+from skrift.auth.roles import (
+    ADMIN,
+    AUTHOR,
+    EDITOR,
+    MODERATOR,
+    ROLE_DEFINITIONS,
+    RoleDefinition,
+    create_role,
+    get_role_definition,
+    register_role,
+)
+from skrift.auth.services import (
+    UserPermissions,
+    assign_role_to_user,
+    get_user_permissions,
+    invalidate_user_permissions_cache,
+    remove_role_from_user,
+    sync_roles_to_database,
+)
+
+__all__ = [
+    # Guards
+    "ADMINISTRATOR_PERMISSION",
+    "AndRequirement",
+    "AuthRequirement",
+    "OrRequirement",
+    "Permission",
+    "Role",
+    "auth_guard",
+    # Roles
+    "ADMIN",
+    "AUTHOR",
+    "EDITOR",
+    "MODERATOR",
+    "ROLE_DEFINITIONS",
+    "RoleDefinition",
+    "create_role",
+    "get_role_definition",
+    "register_role",
+    # Services
+    "UserPermissions",
+    "assign_role_to_user",
+    "get_user_permissions",
+    "invalidate_user_permissions_cache",
+    "remove_role_from_user",
+    "sync_roles_to_database",
+]

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,129 @@
+"""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(
+    name: str,
+    *permissions: str,
+    display_name: str | None = None,
+    description: str | None = None,
+) -> RoleDefinition:
+    """Register a custom role definition.
+
+    This allows applications to add custom roles beyond the defaults.
+    Call this during application startup (e.g., in a custom controller module
+    or app initialization) before the database sync occurs.
+
+    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:
+        The registered RoleDefinition instance
+
+    Example:
+        from skrift.auth.roles import register_role
+
+        # Register a custom role with permissions
+        register_role(
+            "support",
+            "view-tickets",
+            "respond-tickets",
+            display_name="Support Agent",
+            description="Can view and respond to support tickets",
+        )
+    """
+    role = create_role(
+        name,
+        *permissions,
+        display_name=display_name,
+        description=description,
+    )
+    ROLE_DEFINITIONS[role.name] = role
+    return 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,143 @@
+"""CLI commands for Skrift."""
+
+import base64
+import os
+import re
+import secrets
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group()
+@click.version_option(package_name="skrift")
+def cli():
+    """Skrift - A lightweight async Python CMS."""
+    pass
+
+
+@cli.command()
+@click.option("--host", default="127.0.0.1", help="Host to bind to")
+@click.option("--port", default=8080, type=int, help="Port to bind to")
+@click.option("--reload", is_flag=True, help="Enable auto-reload for development")
+@click.option("--workers", default=1, type=int, help="Number of worker processes")
+@click.option(
+    "--log-level",
+    default="info",
+    type=click.Choice(["debug", "info", "warning", "error"]),
+    help="Logging level",
+)
+def serve(host, port, reload, workers, log_level):
+    """Run the Skrift server."""
+    import uvicorn
+
+    uvicorn.run(
+        "skrift.asgi:app",
+        host=host,
+        port=port,
+        reload=reload,
+        workers=workers if not reload else 1,
+        log_level=log_level,
+    )
+
+
+@cli.command()
+@click.option(
+    "--write",
+    type=click.Path(),
+    default=None,
+    help="Write SECRET_KEY to a .env file",
+)
+@click.option(
+    "--format",
+    "fmt",
+    default="urlsafe",
+    type=click.Choice(["urlsafe", "hex", "base64"]),
+    help="Output format for the secret key",
+)
+@click.option("--length", default=32, type=int, help="Number of random bytes")
+def secret(write, fmt, length):
+    """Generate a secure secret key."""
+    # Generate key based on format
+    if fmt == "urlsafe":
+        key = secrets.token_urlsafe(length)
+    elif fmt == "hex":
+        key = secrets.token_hex(length)
+    else:  # base64
+        key = base64.b64encode(secrets.token_bytes(length)).decode("ascii")
+
+    if write:
+        env_path = Path(write)
+        env_content = ""
+
+        # Read existing content if file exists
+        if env_path.exists():
+            env_content = env_path.read_text()
+
+        # Update or add SECRET_KEY
+        secret_key_pattern = re.compile(r"^SECRET_KEY=.*$", re.MULTILINE)
+        new_line = f"SECRET_KEY={key}"
+
+        if secret_key_pattern.search(env_content):
+            # Replace existing SECRET_KEY
+            env_content = secret_key_pattern.sub(new_line, env_content)
+        else:
+            # Add SECRET_KEY at the end
+            if env_content and not env_content.endswith("\n"):
+                env_content += "\n"
+            env_content += new_line + "\n"
+
+        env_path.write_text(env_content)
+        click.echo(f"SECRET_KEY written to {env_path}")
+    else:
+        click.echo(key)
+
+
+@cli.command(
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    )
+)
+@click.pass_context
+def db(ctx):
+    """Run database migrations via Alembic.
+
+    \b
+    Examples:
+        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
+
+    # Always run from the project root (where app.yaml and .env are)
+    # This ensures database paths like ./app.db resolve correctly
+    project_root = Path.cwd()
+    if not (project_root / "app.yaml").exists():
+        # If not in project root, try parent directory
+        project_root = Path(__file__).parent.parent
+    os.chdir(project_root)
+
+    # Find alembic.ini - check project root first, then skrift package directory
+    alembic_ini = project_root / "alembic.ini"
+    if not alembic_ini.exists():
+        skrift_dir = Path(__file__).parent
+        alembic_ini = skrift_dir / "alembic.ini"
+
+        if not alembic_ini.exists():
+            click.echo("Error: Could not find alembic.ini", err=True)
+            click.echo("Make sure you're running from the project root directory.", err=True)
+            sys.exit(1)
+
+    # Build argv for alembic: ['-c', '/path/to/alembic.ini', ...extra_args]
+    alembic_argv = ["-c", str(alembic_ini)] + ctx.args
+
+    sys.exit(alembic_main(alembic_argv))
+
+
+if __name__ == "__main__":
+    cli()