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

fastapi_admin_kit/api/__init__.py

@@ -0,0 +1,44 @@
+"""Admin JSON API — provides REST endpoints for external frontend apps."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+
+from fastapi_admin_kit.api.auth import router as auth_router
+from fastapi_admin_kit.api.crud import build_api_router
+from fastapi_admin_kit.api.roles import router as roles_router
+
+
+class AdminAPIRouter:
+    """Builds and mounts the admin JSON API router.
+
+    Shares the same RBAC system as the HTML admin, providing
+    token-based authentication for external frontend apps.
+    """
+
+    def __init__(
+        self,
+        registry: Any = None,
+        prefix: str = "/api",
+    ):
+        self.registry = registry
+        self.prefix = prefix
+
+    def build_router(self) -> APIRouter:
+        """Build the complete API router with auth and CRUD endpoints."""
+        router = APIRouter(prefix=self.prefix)
+
+        # Auth routes (token obtain, refresh, logout, me)
+        router.include_router(auth_router)
+
+        # Role management routes (superuser only)
+        router.include_router(roles_router)
+
+        # CRUD routes for all registered models
+        if self.registry is not None:
+            crud_router = build_api_router(self.registry)
+            router.include_router(crud_router)
+
+        return router

fastapi_admin_kit/api/auth.py

@@ -0,0 +1,342 @@
+"""Token-based authentication for the Admin JSON API."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+from fastapi import APIRouter, HTTPException, Request
+
+from fastapi_admin_kit.api.schemas import (
+    RefreshRequest,
+    RefreshResponse,
+    TokenRequest,
+    TokenResponse,
+)
+from fastapi_admin_kit.auth.ratelimit import RateLimiter, check_rate_limit
+from fastapi_admin_kit.db import get_db_session
+
+router = APIRouter(prefix="/auth", tags=["api-auth"])
+
+_api_rate_limiter = RateLimiter(max_attempts=10, window_seconds=900)
+
+
+def _get_secret_key(request: Request) -> str:
+    """Get the JWT signing key from the unified signing-key source.
+
+    Reads ``app.state.admin_secret_key`` (the same key the signed-cookie
+    sessions and CSRF use). Fails closed with 500 if unset or too short —
+    JWT signing must never silently fall back to a known constant.
+    """
+    secret_key = getattr(request.app.state, "admin_secret_key", "")
+    if not secret_key:
+        raise HTTPException(
+            status_code=500,
+            detail="JWT signing key not configured — admin secret_key not set.",
+        )
+    if len(secret_key) < 32:
+        raise HTTPException(
+            status_code=500,
+            detail="JWT signing key too short — must be at least 32 characters.",
+        )
+    return secret_key
+
+
+def _get_token_ttl(request: Request) -> int:
+    """Get access token TTL in seconds from admin config."""
+    config = getattr(request.app.state, "admin_config", {})
+    return config.get("session_ttl", 1800)
+
+
+def _get_refresh_ttl() -> int:
+    """Refresh token TTL: 7 days."""
+    return 7 * 24 * 3600
+
+
+async def _build_user_permissions(
+    user: Any, db_session: Any
+) -> dict[str, list[str]]:
+    """Build permissions dict from user's roles and direct overrides."""
+    permissions: dict[str, list[str]] = {}
+    if getattr(user, "is_superuser", False):
+        return permissions
+
+    from sqlalchemy import select
+
+    from fastapi_admin_kit.auth.models import AdminPermission, AdminUserPermission
+
+    # Collect permissions from all assigned roles (OR merge)
+    role_ids = getattr(user, "role_ids", [])
+    if role_ids:
+        result = await db_session.execute(
+            select(AdminPermission).where(AdminPermission.role_id.in_(role_ids))
+        )
+        for perm in result.scalars():
+            actions = []
+            if perm.can_view:
+                actions.append("view")
+            if perm.can_create:
+                actions.append("create")
+            if perm.can_edit:
+                actions.append("edit")
+            if perm.can_delete:
+                actions.append("delete")
+            if actions:
+                permissions[perm.table_name] = actions
+
+    # Merge direct user permission overrides (OR on top)
+    user_id = getattr(user, "id", None)
+    if user_id is not None:
+        result = await db_session.execute(
+            select(AdminUserPermission).where(
+                AdminUserPermission.user_id == user_id
+            )
+        )
+        for perm in result.scalars():
+            actions = []
+            if perm.can_view:
+                actions.append("view")
+            if perm.can_create:
+                actions.append("create")
+            if perm.can_edit:
+                actions.append("edit")
+            if perm.can_delete:
+                actions.append("delete")
+            if actions:
+                existing = permissions.get(perm.table_name, [])
+                permissions[perm.table_name] = list(
+                    set(existing) | set(actions)
+                )
+
+    return permissions
+
+
+def create_access_token(
+    user: Any,
+    secret_key: str,
+    permissions: dict[str, list[str]] | None = None,
+    expires_delta: timedelta | None = None,
+) -> str:
+    """Create a JWT access token with embedded roles and permissions."""
+    now = datetime.now(UTC)
+    expire = now + (expires_delta or timedelta(minutes=30))
+    jti = str(uuid.uuid4())
+
+    role_names = []
+    roles = getattr(user, "roles", [])
+    for r in roles:
+        role_name = getattr(r, "name", None)
+        if role_name:
+            role_names.append(role_name)
+
+    payload = {
+        "sub": str(user.id),
+        "roles": role_names,
+        "permissions": permissions or {},
+        "is_superuser": getattr(user, "is_superuser", False),
+        "email": getattr(user, "email", ""),
+        "full_name": getattr(user, "full_name", ""),
+        "exp": expire,
+        "iat": now,
+        "jti": jti,
+    }
+    return jwt.encode(payload, secret_key, algorithm="HS256")
+
+
+def decode_access_token(token: str, secret_key: str) -> dict[str, Any] | None:
+    """Decode and validate a JWT access token. Returns payload or None."""
+    try:
+        return jwt.decode(token, secret_key, algorithms=["HS256"])
+    except jwt.PyJWTError:
+        return None
+
+
+def _hash_token(token: str) -> str:
+    """SHA256 hash of a token for storage."""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+@router.post("/token", response_model=TokenResponse)
+async def obtain_token(
+    request: Request,
+    body: TokenRequest,
+) -> TokenResponse:
+    """POST /api/auth/token — obtain JWT access + refresh tokens."""
+    check_rate_limit(_api_rate_limiter, body.email)
+
+    auth_backend = getattr(request.app.state, "admin_auth_backend", None)
+    if auth_backend is None:
+        raise HTTPException(
+            status_code=500, detail="Auth backend not configured."
+        )
+
+    db_session = get_db_session(request)
+    if db_session is None:
+        raise HTTPException(
+            status_code=500, detail="Database session not available."
+        )
+
+    user = await auth_backend.authenticate(
+        body.email, body.password, db_session
+    )
+    if user is None:
+        _api_rate_limiter.record_attempt(body.email)
+        raise HTTPException(status_code=401, detail="Invalid credentials.")
+
+    _api_rate_limiter.reset(body.email)
+
+    secret_key = _get_secret_key(request)
+    ttl = _get_token_ttl(request)
+    permissions = await _build_user_permissions(user, db_session)
+    access_token = create_access_token(
+        user, secret_key, permissions, expires_delta=timedelta(seconds=ttl)
+    )
+
+    # Create refresh token
+    from fastapi_admin_kit.auth.models import AdminRefreshToken
+
+    refresh_jti = str(uuid.uuid4())
+    refresh_hash = _hash_token(refresh_jti)
+    refresh_expires = datetime.now(UTC) + timedelta(seconds=_get_refresh_ttl())
+
+    refresh_record = AdminRefreshToken(
+        user_id=user.id,
+        token_hash=refresh_hash,
+        expires_at=refresh_expires,
+    )
+    db_session.add(refresh_record)
+    await db_session.flush()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_jti,
+        expires_in=ttl,
+    )
+
+
+@router.post("/refresh", response_model=RefreshResponse)
+async def refresh_token(
+    request: Request,
+    body: RefreshRequest,
+) -> RefreshResponse:
+    """POST /api/auth/refresh — exchange refresh token for new access token."""
+    db_session = get_db_session(request)
+    if db_session is None:
+        raise HTTPException(
+            status_code=500, detail="Database session not available."
+        )
+
+    from sqlalchemy import select
+
+    from fastapi_admin_kit.auth.models import AdminRefreshToken, AdminUser
+
+    refresh_hash = _hash_token(body.refresh_token)
+    result = await db_session.execute(
+        select(AdminRefreshToken).where(
+            AdminRefreshToken.token_hash == refresh_hash,
+            AdminRefreshToken.revoked_at.is_(None),
+        )
+    )
+    refresh_record = result.scalar_one_or_none()
+
+    if refresh_record is None:
+        raise HTTPException(status_code=401, detail="Invalid refresh token.")
+
+    if refresh_record.expires_at < datetime.now(UTC):
+        raise HTTPException(status_code=401, detail="Refresh token expired.")
+
+    # Load user
+    user_result = await db_session.execute(
+        select(AdminUser).where(
+            AdminUser.id == refresh_record.user_id,
+            AdminUser.is_active,
+        )
+    )
+    user = user_result.scalar_one_or_none()
+    if user is None:
+        raise HTTPException(
+            status_code=401, detail="User not found or inactive."
+        )
+
+    # Rotate refresh token
+    refresh_record.revoked_at = datetime.now(UTC)
+
+    secret_key = _get_secret_key(request)
+    ttl = _get_token_ttl(request)
+    permissions = await _build_user_permissions(user, db_session)
+    new_access_token = create_access_token(
+        user, secret_key, permissions, expires_delta=timedelta(seconds=ttl)
+    )
+
+    new_refresh_jti = str(uuid.uuid4())
+    new_refresh_hash = _hash_token(new_refresh_jti)
+    new_refresh_record = AdminRefreshToken(
+        user_id=user.id,
+        token_hash=new_refresh_hash,
+        expires_at=datetime.now(UTC) + timedelta(seconds=_get_refresh_ttl()),
+    )
+    db_session.add(new_refresh_record)
+    await db_session.flush()
+
+    return RefreshResponse(
+        access_token=new_access_token,
+        refresh_token=new_refresh_jti,
+        expires_in=ttl,
+    )
+
+
+@router.post("/logout")
+async def api_logout(
+    request: Request,
+    body: RefreshRequest | None = None,
+) -> dict[str, str]:
+    """POST /api/auth/logout — revoke refresh token."""
+    if body and body.refresh_token:
+        db_session = get_db_session(request)
+        if db_session:
+            from sqlalchemy import select
+
+            from fastapi_admin_kit.auth.models import AdminRefreshToken
+
+            refresh_hash = _hash_token(body.refresh_token)
+            result = await db_session.execute(
+                select(AdminRefreshToken).where(
+                    AdminRefreshToken.token_hash == refresh_hash,
+                    AdminRefreshToken.revoked_at.is_(None),
+                )
+            )
+            refresh_record = result.scalar_one_or_none()
+            if refresh_record:
+                refresh_record.revoked_at = datetime.now(UTC)
+                await db_session.flush()
+
+    return {"detail": "Logged out successfully."}
+
+
+@router.get("/me")
+async def get_current_user_info(
+    request: Request,
+) -> dict[str, Any]:
+    """GET /api/auth/me — return current user info from JWT (no DB hit)."""
+    auth_header = request.headers.get("Authorization", "")
+    if not auth_header.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401, detail="Missing or invalid Authorization header."
+        )
+
+    token = auth_header[7:]
+    secret_key = _get_secret_key(request)
+    payload = decode_access_token(token, secret_key)
+    if payload is None:
+        raise HTTPException(status_code=401, detail="Invalid or expired token.")
+
+    return {
+        "user_id": payload.get("sub"),
+        "email": payload.get("email"),
+        "full_name": payload.get("full_name"),
+        "roles": payload.get("roles", []),
+        "is_superuser": payload.get("is_superuser", False),
+    }

fastapi_admin_kit/api/crud.py

@@ -0,0 +1,128 @@
+"""JSON CRUD handlers for the Admin API.
+
+Uses view classes' api_response() to eliminate duplicate logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import JSONResponse
+
+from fastapi_admin_kit.api.schema_generator import get_or_build_schemas
+from fastapi_admin_kit.views.class_views import (
+    CreateView,
+    DeleteView,
+    EditView,
+    ListView,
+    _resolve_view_class,
+)
+
+
+async def _get_current_user(request: Request) -> dict[str, Any]:
+    """Extract and validate the current user from a Bearer token."""
+    from fastapi_admin_kit.api.deps import get_api_current_user
+
+    return await get_api_current_user(request)
+
+
+async def _check_permission(
+    request: Request, user: dict[str, Any], table_name: str, action: str
+) -> None:
+    """Check if user has permission from JWT payload."""
+    if user.get("is_superuser"):
+        return
+
+    permissions = user.get("permissions", {})
+    table_perms = permissions.get(table_name, [])
+    if action not in table_perms:
+        raise HTTPException(
+            status_code=403,
+            detail=f"You do not have permission to {action} {table_name}.",
+        )
+
+
+def build_api_router(registry: Any) -> APIRouter:
+    """Build the CRUD API router for all registered models."""
+    router = APIRouter(tags=["api-crud"])
+
+    for registered in registry.all():
+        _register_model_routes(router, registered)
+
+    return router
+
+
+def _register_model_routes(router: APIRouter, registered: Any) -> None:
+    """Register CRUD routes for a single model using view classes."""
+    table_name = registered.table_name
+    prefix = f"/{table_name}"
+
+    # DIP: resolve view classes from ModelAdmin config
+    admin = registered.admin
+    list_v = _resolve_view_class(admin, "list_view_class", ListView)(registered)
+    create_v = _resolve_view_class(admin, "create_view_class", CreateView)(
+        registered
+    )
+    edit_v = _resolve_view_class(admin, "edit_view_class", EditView)(registered)
+    delete_v = _resolve_view_class(admin, "delete_view_class", DeleteView)(
+        registered
+    )
+
+    # Generate dynamic schemas for OpenAPI docs
+    schemas = get_or_build_schemas(registered)
+    response_schema = schemas["response"]
+    list_response_schema = schemas["list_response"]
+
+    @router.get(prefix, response_model=list_response_schema)
+    async def list_items(
+        request: Request,
+        page: int = Query(1, ge=1),
+        per_page: int = Query(25, ge=1, le=100),
+        q: str = Query(""),
+        order: str = Query(""),
+        after: str | None = Query(None),
+        before: str | None = Query(None),
+    ):
+        user = await _get_current_user(request)
+        await _check_permission(request, user, table_name, "view")
+        result = await list_v.api_response(
+            request, page=page, per_page=per_page, q=q, order=order,
+            after=after, before=before,
+        )
+        if isinstance(result, JSONResponse):
+            return result
+        return result
+
+    @router.post(prefix, response_model=response_schema, status_code=201)
+    async def create_item(request: Request):
+        user = await _get_current_user(request)
+        await _check_permission(request, user, table_name, "create")
+        result = await create_v.api_response(request)
+        if isinstance(result, JSONResponse):
+            return result
+        return result
+
+    @router.get(f"{prefix}/{{item_id}}", response_model=response_schema)
+    async def retrieve_item(request: Request, item_id: str):
+        user = await _get_current_user(request)
+        await _check_permission(request, user, table_name, "view")
+        result = await edit_v.api_response(request, item_id=item_id)
+        if isinstance(result, JSONResponse):
+            return result
+        return result
+
+    @router.put(f"{prefix}/{{item_id}}", response_model=response_schema)
+    async def update_item(request: Request, item_id: str):
+        user = await _get_current_user(request)
+        await _check_permission(request, user, table_name, "edit")
+        result = await edit_v.api_response(request, item_id=item_id)
+        if isinstance(result, JSONResponse):
+            return result
+        return result
+
+    @router.delete(f"{prefix}/{{item_id}}", status_code=204)
+    async def delete_item(request: Request, item_id: str):
+        user = await _get_current_user(request)
+        await _check_permission(request, user, table_name, "delete")
+        return await delete_v.api_response(request, item_id=item_id)

fastapi_admin_kit/api/deps.py

@@ -0,0 +1,79 @@
+"""API dependencies — JWT-based permission checking without DB hits."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+from fastapi_admin_kit.api.auth import _get_secret_key, decode_access_token
+
+
+async def get_api_current_user(request: Request) -> dict[str, Any]:
+    """Decode JWT and return user payload (no DB hit).
+
+    Raises 401 if token is missing or invalid.
+    """
+    auth_header = request.headers.get("Authorization", "")
+    if not auth_header.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401, detail="Missing or invalid Authorization header."
+        )
+
+    token = auth_header[7:]
+    secret_key = _get_secret_key(request)
+    payload = decode_access_token(token, secret_key)
+    if payload is None:
+        raise HTTPException(status_code=401, detail="Invalid or expired token.")
+    return payload
+
+
+def require_api_permission(table_name: str, action: str):
+    """Return a dependency that checks JWT-embedded permissions.
+
+    Usage::
+
+        @router.get("/")
+        async def list_view(user=Depends(require_api_permission("products", "view"))):
+            ...
+    """
+
+    async def _check(
+        user: dict[str, Any] = None,
+        request: Request = None,
+    ) -> dict[str, Any]:
+        if user is None:
+            user = await get_api_current_user(request)
+
+        if user.get("is_superuser"):
+            return user
+
+        permissions = user.get("permissions", {})
+        table_perms = permissions.get(table_name, [])
+        if action not in table_perms:
+            raise HTTPException(
+                status_code=403,
+                detail=f"You do not have permission to {action} {table_name}.",
+            )
+        return user
+
+    return _check
+
+
+def require_api_superuser():
+    """Return a dependency that enforces superuser access from JWT."""
+
+    async def _check(
+        user: dict[str, Any] = None,
+        request: Request = None,
+    ) -> dict[str, Any]:
+        if user is None:
+            user = await get_api_current_user(request)
+
+        if not user.get("is_superuser"):
+            raise HTTPException(
+                status_code=403, detail="Superuser access required."
+            )
+        return user
+
+    return _check