fastapi-admin-kit 0.1.0__py3-none-any.whl

fastapi_admin_kit/auth/totp.py

@@ -0,0 +1,83 @@
+"""TOTP-based two-factor authentication."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+import struct
+import time
+
+
+def generate_secret() -> str:
+    """Generate a TOTP secret key (base32 encoded)."""
+    return base64.b32encode(secrets.token_bytes(20)).decode("utf-8").rstrip("=")
+
+
+def get_totp_uri(secret: str, email: str, issuer: str = "FastAPI Admin Kit") -> str:
+    """Generate an otpauth:// URI for QR code generation."""
+    import urllib.parse
+    params = urllib.parse.urlencode({
+        "secret": secret,
+        "issuer": issuer,
+        "digits": 6,
+        "period": 30,
+    })
+    return f"otpauth://totp/{urllib.parse.quote(issuer)}:{urllib.parse.quote(email)}?{params}"
+
+
+def _generate_hotp(secret: str, counter: int) -> str:
+    """Generate a HOTP code for a given counter value."""
+    key = base64.b32decode(secret + "=" * ((8 - len(secret) % 8) % 8))
+    counter_bytes = struct.pack(">Q", counter)
+    hmac_digest = hmac.new(key, counter_bytes, hashlib.sha1).digest()
+    offset = hmac_digest[-1] & 0x0F
+    code_int = struct.unpack(">I", hmac_digest[offset:offset + 4])[0] & 0x7FFFFFFF
+    return str(code_int % 1000000).zfill(6)
+
+
+def verify_totp(secret: str, code: str, window: int = 1) -> bool:
+    """Verify a TOTP code with a ±window tolerance.
+
+    Args:
+        secret: Base32-encoded TOTP secret
+        code: 6-digit code to verify
+        window: Number of time steps to check in each direction (default 1 = ±30s)
+    """
+    if not code or len(code) != 6 or not code.isdigit():
+        return False
+
+    current_counter = int(time.time()) // 30
+    for offset in range(-window, window + 1):
+        expected = _generate_hotp(secret, current_counter + offset)
+        if hmac.compare_digest(code, expected):
+            return True
+    return False
+
+
+def generate_backup_codes(count: int = 10) -> list[str]:
+    """Generate one-time-use backup codes (8 alphanumeric chars each)."""
+    codes = []
+    for _ in range(count):
+        code = secrets.token_urlsafe(6)[:8]
+        codes.append(code.upper())
+    return codes
+
+
+def hash_backup_code(code: str) -> str:
+    """Hash a backup code for storage."""
+    return hashlib.sha256(code.encode()).hexdigest()
+
+
+def verify_backup_code(code: str, hashed_codes: list[str]) -> bool:
+    """Verify a backup code against a list of hashed codes.
+
+    Returns True if the code matches and removes it from the list (in-place).
+    """
+    code_hash = hash_backup_code(code)
+    for i, h in enumerate(hashed_codes):
+        if hmac.compare_digest(code_hash, h):
+            hashed_codes.pop(i)
+            return True
+    return False

fastapi_admin_kit/auth/views.py

@@ -0,0 +1,165 @@
+"""Auth views — login, logout."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import urlparse
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    Form,
+    Request,
+    status,
+)
+from fastapi.responses import HTMLResponse, RedirectResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from fastapi_admin_kit.auth.csrf import CSRF_COOKIE_NAME, require_csrf_token
+from fastapi_admin_kit.auth.dependencies import _get_db_session, get_session
+from fastapi_admin_kit.auth.ratelimit import (
+    RateLimiter,
+    _client_ip,
+    check_rate_limit,
+)
+
+router = APIRouter()
+
+_login_rate_limiter = RateLimiter(max_attempts=5, window_seconds=900)
+
+
+def _is_safe_url(url: str | None) -> bool:
+    """Return True if the URL is relative (no scheme or netloc)."""
+    if not url:
+        return False
+    parsed = urlparse(url)
+    return not (parsed.scheme or parsed.netloc)
+
+
+@router.get("/login", response_class=HTMLResponse)
+async def login_get(
+    request: Request,
+    next: str | None = None,
+    session_payload: dict[str, Any] | None = Depends(get_session),
+) -> HTMLResponse:
+    """GET /admin/login — show login page, redirect if already logged in."""
+    if session_payload is not None:
+        target = next if _is_safe_url(next) else "/admin/"
+        return RedirectResponse(url=target, status_code=status.HTTP_302_FOUND)
+
+    jinja_env = request.app.state.admin_jinja_env
+    template = jinja_env.get_template("pages/login.html")
+    csrf_token = getattr(request.state, "csrf_token", "")
+    return HTMLResponse(
+        template.render(
+            {
+                "request": request,
+                "csrf_token": csrf_token,
+            }
+        )
+    )
+
+
+@router.post("/login", response_model=None)
+async def login_post(
+    request: Request,
+    email: str = Form(...),
+    password: str = Form(...),
+    next: str | None = Form(None),
+    session: AsyncSession = Depends(_get_db_session),
+    _csrf: bool = Depends(require_csrf_token),
+) -> HTMLResponse | RedirectResponse:
+    """POST /admin/login — process login form."""
+    client_ip = _client_ip(request)
+    check_rate_limit(_login_rate_limiter, client_ip)
+
+    auth_backend = request.app.state.admin_auth_backend
+    user = await auth_backend.authenticate(email, password, session)
+
+    if user is not None:
+        _login_rate_limiter.reset(client_ip)
+        user.last_login = datetime.now(UTC)
+        await session.merge(user)
+        await session.flush()
+
+        session_backend = request.app.state.admin_session_backend
+        session_data = {"user_id": user.id}
+        token = session_backend.encode(session_data)
+
+        if next and _is_safe_url(next):
+            redirect_url = next
+        else:
+            redirect_url = "/admin/"
+
+        samesite = getattr(
+            request.app.state.admin_state, "session_samesite", "strict"
+        )
+        response = RedirectResponse(
+            url=redirect_url, status_code=status.HTTP_302_FOUND
+        )
+        response.set_cookie(
+            key=session_backend.cookie_name,
+            value=token,
+            max_age=session_backend._session_ttl,
+            path="/",
+            secure=session_backend.secure,
+            httponly=True,
+            samesite=samesite,
+        )
+        return response
+
+    _login_rate_limiter.record_attempt(client_ip)
+
+    jinja_env = request.app.state.admin_jinja_env
+    template = jinja_env.get_template("pages/login.html")
+    csrf_token = getattr(request.state, "csrf_token", "")
+    remaining = _login_rate_limiter.remaining_seconds(client_ip)
+    error_msg = "Invalid email or password. Please try again."
+    if _login_rate_limiter.is_rate_limited(client_ip):
+        error_msg = (
+            f"Too many failed attempts. Try again in {remaining} seconds."
+        )
+    return HTMLResponse(
+        template.render(
+            {
+                "request": request,
+                "error": error_msg,
+                "csrf_token": csrf_token,
+            }
+        ),
+        status_code=status.HTTP_200_OK,
+    )
+
+
+@router.post("/logout")
+async def logout_post(
+    request: Request,
+    session_payload: dict[str, Any] | None = Depends(get_session),
+    _csrf: bool = Depends(require_csrf_token),
+) -> RedirectResponse:
+    """POST /admin/logout — clear session and redirect to login."""
+    if session_payload is not None:
+        auth_backend = request.app.state.admin_auth_backend
+        if hasattr(auth_backend, "on_logout"):
+            await auth_backend.on_logout(session_payload.get("user_id"))
+
+    session_backend = request.app.state.admin_session_backend
+    samesite = getattr(
+        request.app.state.admin_state, "session_samesite", "strict"
+    )
+    response = RedirectResponse(
+        url="/admin/login", status_code=status.HTTP_302_FOUND
+    )
+    response.delete_cookie(
+        key=session_backend.cookie_name,
+        path="/",
+        secure=session_backend.secure,
+        httponly=True,
+        samesite=samesite,
+    )
+    response.delete_cookie(
+        key=CSRF_COOKIE_NAME,
+        path="/",
+    )
+    return response

fastapi_admin_kit/cli.py

@@ -0,0 +1,229 @@
+"""CLI commands for FastAPI Admin Kit."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+
+def _resolve_database_url(url: str | None = None) -> str:
+    """Resolve database URL from argument, env var, or default."""
+    if url:
+        return url
+    env_url = os.getenv("DATABASE_URL")
+    if env_url:
+        return env_url
+    print(
+        "Error: --database-url not specified and DATABASE_URL env var not set."
+    )
+    sys.exit(1)
+
+
+async def _create_superuser(args: argparse.Namespace) -> None:
+    """Create a superuser."""
+    from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+    from sqlalchemy.orm import sessionmaker
+
+    from fastapi_admin_kit.auth.backend import pwd_context
+    from fastapi_admin_kit.auth.models import AdminUser
+    from fastapi_admin_kit.models.base import Base
+
+    database_url = _resolve_database_url(args.database_url)
+    engine = create_async_engine(database_url)
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async_session = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+
+    async with async_session() as session:
+        from sqlalchemy import select
+
+        result = await session.execute(
+            select(AdminUser).where(AdminUser.email == args.email)
+        )
+        existing = result.scalar_one_or_none()
+        if existing:
+            print(f"Error: User with email '{args.email}' already exists.")
+            await engine.dispose()
+            sys.exit(1)
+
+        hashed_password = pwd_context.hash(args.password)
+        user = AdminUser(
+            email=args.email,
+            hashed_password=hashed_password,
+            full_name=args.name or "",
+            is_superuser=True,
+            is_active=True,
+        )
+        session.add(user)
+        await session.commit()
+        await session.refresh(user)
+
+        print("Superuser created successfully!")
+        print(f"  Email: {user.email}")
+        print(f"  Name:  {user.full_name or '(none)'}")
+        print(f"  ID:    {user.id}")
+
+    await engine.dispose()
+
+
+async def _list_users(args: argparse.Namespace) -> None:
+    """List all admin users."""
+    from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+    from sqlalchemy.orm import sessionmaker
+
+    from fastapi_admin_kit.auth.models import AdminUser
+    from fastapi_admin_kit.models.base import Base
+    database_url = _resolve_database_url(args.database_url)
+    engine = create_async_engine(database_url)
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async_session = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+
+    async with async_session() as session:
+        from sqlalchemy import select
+
+        result = await session.execute(select(AdminUser))
+        users = result.scalars().all()
+
+        if not users:
+            print("No admin users found.")
+            await engine.dispose()
+            return
+
+        print(
+            f"{'ID':<6} {'Email':<30} {'Name':<20} {'Superuser':<10} {'Active':<8}"
+        )
+        print("-" * 74)
+        for user in users:
+            print(
+                f"{user.id:<6} {user.email:<30} {(user.full_name or ''):<20} "
+                f"{'Yes' if user.is_superuser else 'No':<10} "
+                f"{'Yes' if user.is_active else 'No':<8}"
+            )
+
+    await engine.dispose()
+
+
+async def _change_password(args: argparse.Namespace) -> None:
+    """Change password for an existing user."""
+    from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+    from sqlalchemy.orm import sessionmaker
+
+    from fastapi_admin_kit.auth.backend import pwd_context
+    from fastapi_admin_kit.auth.models import AdminUser
+    from fastapi_admin_kit.models.base import Base
+
+    database_url = _resolve_database_url(args.database_url)
+    engine = create_async_engine(database_url)
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async_session = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+
+    async with async_session() as session:
+        from sqlalchemy import select
+
+        result = await session.execute(
+            select(AdminUser).where(AdminUser.email == args.email)
+        )
+        user = result.scalar_one_or_none()
+
+        if not user:
+            print(f"Error: User with email '{args.email}' not found.")
+            await engine.dispose()
+            sys.exit(1)
+
+        user.hashed_password = pwd_context.hash(args.password)
+        await session.commit()
+
+        print(f"Password changed successfully for '{user.email}'!")
+
+    await engine.dispose()
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="FastAPI Admin Kit CLI — manage admin users and database.",
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", help="Available commands"
+    )
+
+    # create-superuser
+    create_parser = subparsers.add_parser(
+        "createsuperuser", help="Create a new superuser"
+    )
+    create_parser.add_argument(
+        "-e", "--email", required=True, help="Email address for the superuser"
+    )
+    create_parser.add_argument(
+        "-p", "--password", required=True, help="Password for the superuser"
+    )
+    create_parser.add_argument(
+        "-n", "--name", default="", help="Full name for the superuser"
+    )
+    create_parser.add_argument(
+        "-d",
+        "--database-url",
+        default=None,
+        help="Database URL (or set DATABASE_URL env var)",
+    )
+
+    # list-users
+    list_parser = subparsers.add_parser(
+        "users", help="List all admin users"
+    )
+    list_parser.add_argument(
+        "-d",
+        "--database-url",
+        default=None,
+        help="Database URL (or set DATABASE_URL env var)",
+    )
+
+    # changepassword
+    pw_parser = subparsers.add_parser(
+        "changepassword", help="Change password for an existing user"
+    )
+    pw_parser.add_argument(
+        "-e", "--email", required=True, help="Email of the user"
+    )
+    pw_parser.add_argument(
+        "-p", "--password", required=True, help="New password"
+    )
+    pw_parser.add_argument(
+        "-d",
+        "--database-url",
+        default=None,
+        help="Database URL (or set DATABASE_URL env var)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "createsuperuser":
+        asyncio.run(_create_superuser(args))
+    elif args.command == "users":
+        asyncio.run(_list_users(args))
+    elif args.command == "changepassword":
+        asyncio.run(_change_password(args))
+
+
+if __name__ == "__main__":
+    main()

fastapi_admin_kit/config/__init__.py

@@ -0,0 +1,19 @@
+"""Configuration classes for FastAPI Admin Kit."""
+
+from fastapi_admin_kit.config.audit import AuditConfig
+from fastapi_admin_kit.config.auth import AuthConfig
+from fastapi_admin_kit.config.behavior import BehaviorConfig
+from fastapi_admin_kit.config.nav import NavConfig
+from fastapi_admin_kit.config.storage import StorageConfig
+from fastapi_admin_kit.config.theme import ThemeConfig
+from fastapi_admin_kit.config.ui import UIConfig
+
+__all__ = [
+    "AuthConfig",
+    "AuditConfig",
+    "UIConfig",
+    "BehaviorConfig",
+    "StorageConfig",
+    "NavConfig",
+    "ThemeConfig",
+]

fastapi_admin_kit/config/audit.py

@@ -0,0 +1,18 @@
+"""Audit configuration."""
+
+from fastapi_admin_kit.exceptions import ConfigError
+
+
+class AuditConfig:
+    """Audit configuration."""
+
+    def __init__(
+        self,
+        audit_retention_days: int = 365,
+    ):
+        self.audit_retention_days = audit_retention_days
+
+    def validate_audit_config(self) -> None:
+        """Validate audit configuration."""
+        if self.audit_retention_days < 0:
+            raise ConfigError("audit_retention_days must be non-negative")

fastapi_admin_kit/config/auth.py

@@ -0,0 +1,54 @@
+"""Authentication configuration."""
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi_admin_kit.exceptions import ConfigError
+
+if TYPE_CHECKING:
+    pass
+
+
+class AuthConfig:
+    """Authentication configuration."""
+
+    def __init__(
+        self,
+        auth_model: type | None = None,
+        auth_backend: Any | None = None,
+        session_ttl: int = 28800,
+        session_cookie_name: str = "admin_session",
+        session_secure: bool = False,
+        superuser_emails: list[str] | None = None,
+        password_min_length: int = 12,
+        password_require_uppercase: bool = True,
+        password_require_lowercase: bool = True,
+        password_require_digit: bool = True,
+        password_require_special: bool = True,
+        session_samesite: str = "strict",
+    ):
+        self.auth_model = auth_model
+        self.auth_backend = auth_backend
+        self.session_ttl = session_ttl
+        self.session_cookie_name = session_cookie_name
+        self.session_secure = session_secure
+        self.superuser_emails = superuser_emails or []
+        self.password_min_length = password_min_length
+        self.password_require_uppercase = password_require_uppercase
+        self.password_require_lowercase = password_require_lowercase
+        self.password_require_digit = password_require_digit
+        self.password_require_special = password_require_special
+        self.session_samesite = session_samesite
+
+    def validate_auth_model(self) -> None:
+        """Validate that auth_model satisfies AdminUserProtocol."""
+        model = self.auth_model
+        if model is None:
+            return
+
+        required_attrs = ["id", "email", "is_active", "is_superuser", "roles"]
+        missing = [attr for attr in required_attrs if not hasattr(model, attr)]
+        if missing:
+            raise ConfigError(
+                f"auth_model {model.__name__!r} does not satisfy AdminUserProtocol. "
+                f"Missing attributes: {', '.join(missing)}"
+            )

fastapi_admin_kit/config/behavior.py

@@ -0,0 +1,27 @@
+"""Behavior configuration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class BehaviorConfig:
+    """Behavior configuration."""
+
+    def __init__(
+        self,
+        auto_discover: bool = True,
+        dashboard_stats: list[str] | None = None,
+        dashboard_charts: bool = True,
+        dashboard_callback: str | None = None,
+        dashboard_components: list[Any] | None = None,
+    ):
+        self.auto_discover = auto_discover
+        self.dashboard_stats = dashboard_stats or []
+        self.dashboard_charts = dashboard_charts
+        self.dashboard_callback = dashboard_callback
+        self.dashboard_components = dashboard_components or []
+
+    def validate_behavior_config(self) -> None:
+        """Validate behavior configuration."""
+        pass

fastapi_admin_kit/config/nav.py

@@ -0,0 +1,32 @@
+"""Navigation configuration."""
+
+from typing import Any
+
+from fastapi_admin_kit.exceptions import ConfigError
+
+
+class NavConfig:
+    """Navigation configuration."""
+
+    def __init__(
+        self,
+        nav_groups: list[Any] | None = None,
+        sidebar_builder: Any | None = None,
+        require_tags: bool = False,
+        site_dropdown: list[dict[str, str]] | None = None,
+        dashboard_permission: str | None = None,
+        settings_permission: str | None = None,
+    ):
+        self.nav_groups = nav_groups or []
+        self.sidebar_builder = sidebar_builder
+        self.require_tags = require_tags
+        self.site_dropdown = site_dropdown or []
+        self.dashboard_permission = dashboard_permission
+        self.settings_permission = settings_permission
+
+    def validate_nav_config(self) -> None:
+        """Validate navigation configuration."""
+        if self.require_tags and not self.nav_groups:
+            raise ConfigError(
+                "require_tags=True requires nav_groups to be configured"
+            )

fastapi_admin_kit/config/storage.py

@@ -0,0 +1,22 @@
+"""Storage configuration."""
+
+from typing import Any
+
+from fastapi_admin_kit.exceptions import ConfigError
+
+
+class StorageConfig:
+    """Storage configuration."""
+
+    def __init__(
+        self,
+        storage: Any | None = None,
+        uploads_url: str = "/uploads",
+    ):
+        self.storage = storage
+        self.uploads_url = uploads_url
+
+    def validate_storage_config(self) -> None:
+        """Validate storage configuration."""
+        if self.uploads_url and not self.uploads_url.startswith("/"):
+            raise ConfigError("uploads_url must start with '/' or be empty")