fastapi-rbac-authz 0.2.0__py3-none-any.whl

fastapi_rbac/router.py

@@ -0,0 +1,319 @@
+"""RBACRouter - FastAPI router with RBAC authorization."""
+
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends
+
+from fastapi_rbac.context import ContextualAuthz
+from fastapi_rbac.dependencies import create_authz_dependency
+from fastapi_rbac.permissions import WILDCARD
+
+# Type alias for context classes
+ContextClass = type[ContextualAuthz[Any]]
+
+
+def _contains_wildcard(permission: str) -> bool:
+    """Check if a permission contains a wildcard."""
+    return WILDCARD in permission
+
+
+def _validate_permissions(permissions: set[str] | None, location: str) -> None:
+    """Validate that permissions don't contain wildcards.
+
+    Args:
+        permissions: Set of permission strings to validate.
+        location: Description of where the permissions are defined (for error message).
+
+    Raises:
+        RuntimeError: If any permission contains a wildcard.
+    """
+    if permissions is None:
+        return
+    for perm in permissions:
+        if _contains_wildcard(perm):
+            raise RuntimeError(
+                f"Wildcard permissions are not allowed in {location}. "
+                f"Found '{perm}'. Wildcards should only be used in role grants."
+            )
+
+
+class RBACRouter(APIRouter):
+    """FastAPI router with RBAC authorization support.
+
+    Extends APIRouter to automatically inject authorization checks into endpoints.
+
+    Args:
+        permissions: Default permissions required for all endpoints on this router.
+        contexts: Default contextual authorization classes for all endpoints.
+        **kwargs: Additional arguments passed to APIRouter.
+
+    Example:
+        router = RBACRouter(
+            permissions={"report:read"},
+            contexts=[OrganizationMemberContext],
+        )
+
+        @router.get("/reports")
+        async def get_reports(user: User = Depends(AuthUser)):
+            return {"reports": [...]}
+
+        # Override permissions for specific endpoint
+        @router.post("/reports", permissions={"report:create"})
+        async def create_report(user: User = Depends(AuthUser)):
+            return {"id": "new-report"}
+    """
+
+    def __init__(
+        self,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Validate no wildcards in router-level permissions
+        _validate_permissions(permissions, "router permissions")
+
+        super().__init__(**kwargs)
+        self.default_permissions: set[str] = permissions or set()
+        self.default_contexts: list[ContextClass] = contexts or []
+        self.endpoint_metadata: dict[tuple[str, str], dict[str, Any]] = {}
+
+    def _create_authz_dependency(
+        self,
+        permissions: set[str],
+        contexts: list[ContextClass],
+    ) -> Callable[..., Any]:
+        """Create an authorization dependency for an endpoint.
+
+        This dependency will be injected into the endpoint and will check
+        permissions before the endpoint handler is called.
+
+        Uses create_authz_dependency from dependencies.py which supports
+        resolving Depends() parameters in context classes.
+        """
+        return create_authz_dependency(
+            required_permissions=permissions,
+            context_classes=contexts,
+        )
+
+    def _resolve_permissions_and_contexts(
+        self,
+        path: str,
+        method: str,
+        permissions: set[str] | None,
+        contexts: list[ContextClass] | None,
+    ) -> tuple[set[str], list[ContextClass]]:
+        """Resolve final permissions and contexts for an endpoint.
+
+        Args:
+            path: The endpoint path.
+            method: The HTTP method (GET, POST, etc.).
+            permissions: Endpoint-specific permissions (overrides router default).
+            contexts: Endpoint-specific contexts (merges with router default).
+
+        Returns:
+            Tuple of (final_permissions, final_contexts).
+        """
+        # Validate no wildcards in endpoint-level permissions
+        _validate_permissions(permissions, "endpoint permissions")
+
+        # Resolve final permissions: endpoint overrides router
+        final_permissions = permissions if permissions is not None else self.default_permissions
+
+        # Resolve final contexts: endpoint merges with router
+        final_contexts = list(self.default_contexts)
+        if contexts:
+            final_contexts.extend(contexts)
+
+        # Store metadata for UI introspection
+        self.endpoint_metadata[(path, method)] = {
+            "permissions": final_permissions,
+            "contexts": final_contexts,
+        }
+
+        return final_permissions, final_contexts
+
+    def _wrap_endpoint_with_authz(
+        self,
+        endpoint: Callable[..., Any],
+        authz_dep: Callable[..., Any],
+    ) -> Callable[..., Any]:
+        """Wrap an endpoint to add authz check after other dependencies.
+
+        Creates a new function signature that includes the authz dependency
+        as an annotated parameter, ensuring it runs after user auth dependencies.
+        """
+        # Get the original function's signature
+        sig = inspect.signature(endpoint)
+        params = list(sig.parameters.values())
+
+        # Create authz dependency parameter - place it last so it runs after user deps
+        authz_param = inspect.Parameter(
+            "_rbac_authz_check_",
+            inspect.Parameter.KEYWORD_ONLY,
+            default=None,
+            annotation=Annotated[None, Depends(authz_dep)],
+        )
+
+        # Build new parameters: original params + authz param
+        new_params = params + [authz_param]
+        new_sig = sig.replace(parameters=new_params)
+
+        # Determine if endpoint is async
+        is_async = inspect.iscoroutinefunction(endpoint)
+
+        if is_async:
+
+            @wraps(endpoint)
+            async def wrapped_async(
+                *args: Any,
+                _rbac_authz_check_: Annotated[None, Depends(authz_dep)] = None,
+                **kwargs: Any,
+            ) -> Any:
+                return await endpoint(*args, **kwargs)
+
+            wrapped_async.__signature__ = new_sig  # type: ignore[attr-defined]
+            return wrapped_async
+        else:
+
+            @wraps(endpoint)
+            def wrapped_sync(
+                *args: Any,
+                _rbac_authz_check_: Annotated[None, Depends(authz_dep)] = None,
+                **kwargs: Any,
+            ) -> Any:
+                return endpoint(*args, **kwargs)
+
+            wrapped_sync.__signature__ = new_sig  # type: ignore[attr-defined]
+            return wrapped_sync
+
+    def _add_route_with_authz(
+        self,
+        path: str,
+        method: str,
+        endpoint: Callable[..., Any],
+        permissions: set[str] | None,
+        contexts: list[ContextClass] | None,
+        parent_method: Callable[..., Any],
+        **kwargs: Any,
+    ) -> Callable[..., Any]:
+        """Add a route with authorization dependency.
+
+        Args:
+            path: The endpoint path.
+            method: The HTTP method name (GET, POST, etc.).
+            endpoint: The original endpoint function.
+            permissions: Endpoint-specific permissions (overrides router default).
+            contexts: Endpoint-specific contexts (merges with router default).
+            parent_method: The parent APIRouter method to call.
+            **kwargs: Additional route kwargs.
+
+        Returns:
+            The decorated endpoint.
+        """
+        final_permissions, final_contexts = self._resolve_permissions_and_contexts(path, method, permissions, contexts)
+
+        # If there are permissions or contexts, wrap the endpoint
+        if final_permissions or final_contexts:
+            authz_dep = self._create_authz_dependency(final_permissions, final_contexts)
+            endpoint = self._wrap_endpoint_with_authz(endpoint, authz_dep)
+
+        # Attach RBAC metadata to endpoint for later introspection
+        # This allows schema building to work even if router was included
+        # before RBACAuthz was initialized (bypassing _rbac_routers_ tracking)
+        endpoint._rbac_metadata_ = {  # type: ignore[attr-defined]
+            "permissions": final_permissions,
+            "contexts": final_contexts,
+        }
+
+        # Register the route
+        result: Callable[..., Any] = parent_method(path, **kwargs)(endpoint)
+        return result
+
+    def get(  # type: ignore[override]
+        self,
+        path: str,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a GET endpoint with optional permission overrides."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            return self._add_route_with_authz(
+                path, "GET", func, permissions, contexts, super(RBACRouter, self).get, **kwargs
+            )
+
+        return decorator
+
+    def post(  # type: ignore[override]
+        self,
+        path: str,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a POST endpoint with optional permission overrides."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            return self._add_route_with_authz(
+                path, "POST", func, permissions, contexts, super(RBACRouter, self).post, **kwargs
+            )
+
+        return decorator
+
+    def put(  # type: ignore[override]
+        self,
+        path: str,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a PUT endpoint with optional permission overrides."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            return self._add_route_with_authz(
+                path, "PUT", func, permissions, contexts, super(RBACRouter, self).put, **kwargs
+            )
+
+        return decorator
+
+    def patch(  # type: ignore[override]
+        self,
+        path: str,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a PATCH endpoint with optional permission overrides."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            return self._add_route_with_authz(
+                path, "PATCH", func, permissions, contexts, super(RBACRouter, self).patch, **kwargs
+            )
+
+        return decorator
+
+    def delete(  # type: ignore[override]
+        self,
+        path: str,
+        *,
+        permissions: set[str] | None = None,
+        contexts: list[ContextClass] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a DELETE endpoint with optional permission overrides."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            return self._add_route_with_authz(
+                path, "DELETE", func, permissions, contexts, super(RBACRouter, self).delete, **kwargs
+            )
+
+        return decorator

fastapi_rbac/ui/__init__.py

@@ -0,0 +1,9 @@
+"""UI module for RBAC authorization visualization."""
+
+from fastapi_rbac.ui.routes import create_ui_router
+from fastapi_rbac.ui.schema import build_ui_schema
+
+__all__ = [
+    "create_ui_router",
+    "build_ui_schema",
+]

fastapi_rbac/ui/routes.py

@@ -0,0 +1,67 @@
+"""Routes for RBAC UI visualization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from fastapi_rbac.ui.schema import build_ui_schema
+
+if TYPE_CHECKING:
+    from fastapi_rbac.core import RBACAuthz
+
+# Path to static files
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def create_ui_router(ui_path: str) -> APIRouter:
+    """Create a router for the RBAC UI visualization.
+
+    Args:
+        ui_path: The base path for the UI (e.g., "/_rbac").
+
+    Returns:
+        An APIRouter with routes for the UI HTML and schema JSON.
+    """
+    router = APIRouter(tags=["rbac-ui"])
+
+    @router.get(
+        "",
+        response_class=HTMLResponse,
+        summary="RBAC Visualization UI",
+        description="Interactive visualization of roles, permissions, and endpoints.",
+        include_in_schema=False,
+    )
+    async def get_ui(request: Request) -> HTMLResponse:
+        """Serve the RBAC visualization HTML page."""
+        html_file = STATIC_DIR / "index.html"
+        if not html_file.exists():
+            return HTMLResponse(
+                content="<html><body><h1>UI not found</h1></body></html>",
+                status_code=500,
+            )
+
+        content = html_file.read_text()
+        # Replace placeholder with actual schema endpoint path
+        schema_url = f"{ui_path}/schema"
+        content = content.replace("{{SCHEMA_URL}}", schema_url)
+
+        return HTMLResponse(content=content)
+
+    @router.get(
+        "/schema",
+        response_class=JSONResponse,
+        summary="RBAC Schema",
+        description="JSON schema of all roles, permissions, endpoints, and contexts.",
+        include_in_schema=False,
+    )
+    async def get_schema(request: Request) -> JSONResponse:
+        """Return the RBAC schema as JSON."""
+        rbac: RBACAuthz[Any] = request.app.state.rbac
+        schema = build_ui_schema(request.app, rbac)
+        return JSONResponse(content=schema.model_dump())
+
+    return router

fastapi_rbac/ui/schema.py

@@ -0,0 +1,253 @@
+"""Schema introspection for RBAC UI visualization."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from fastapi_rbac.permissions import PermissionGrant
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from starlette.routing import BaseRoute
+
+    from fastapi_rbac.core import RBACAuthz
+
+
+class RoleSchema(BaseModel):
+    """Schema for a role in the RBAC system."""
+
+    name: str
+    permissions: list[PermissionGrantSchema]
+
+
+class PermissionGrantSchema(BaseModel):
+    """Schema for a permission grant."""
+
+    permission: str
+    scope: str  # "global" or "contextual"
+
+
+class PermissionSchema(BaseModel):
+    """Schema for a permission with information about which roles grant it."""
+
+    name: str
+    granted_by: list[GrantedBySchema]
+
+
+class GrantedBySchema(BaseModel):
+    """Schema for role-to-permission grant relationship."""
+
+    role: str
+    scope: str  # "global" or "contextual"
+
+
+class ContextSchema(BaseModel):
+    """Schema for a context class."""
+
+    name: str
+    description: str | None
+    used_by: list[str]  # List of endpoint identifiers (e.g., "GET /reports")
+
+
+class EndpointSchema(BaseModel):
+    """Schema for an endpoint with RBAC configuration."""
+
+    path: str
+    method: str
+    summary: str | None
+    description: str | None
+    tags: list[str]
+    permissions: list[str]
+    contexts: list[str]
+
+
+class UISchema(BaseModel):
+    """Complete schema for RBAC UI visualization."""
+
+    roles: list[RoleSchema]
+    permissions: list[PermissionSchema]
+    endpoints: list[EndpointSchema]
+    contexts: list[ContextSchema]
+
+
+def _extract_grants_from_role(
+    role_name: str,
+    grants: set[PermissionGrant],
+) -> list[PermissionGrantSchema]:
+    """Extract permission grant schemas from a role's grants."""
+    return [
+        PermissionGrantSchema(
+            permission=grant.permission,
+            scope=grant.scope.value,
+        )
+        for grant in grants
+    ]
+
+
+def _build_roles_schema(
+    permissions_map: dict[str, set[PermissionGrant]],
+) -> list[RoleSchema]:
+    """Build role schemas from the permissions map."""
+    roles = []
+    for role_name, grants in sorted(permissions_map.items()):
+        role = RoleSchema(
+            name=role_name,
+            permissions=_extract_grants_from_role(role_name, grants),
+        )
+        roles.append(role)
+    return roles
+
+
+def _build_permissions_schema(
+    permissions_map: dict[str, set[PermissionGrant]],
+) -> list[PermissionSchema]:
+    """Build permission schemas showing which roles grant each permission."""
+    # Collect all unique permissions and their granting roles
+    permission_grants: dict[str, list[GrantedBySchema]] = {}
+
+    for role_name, grants in permissions_map.items():
+        for grant in grants:
+            if grant.permission not in permission_grants:
+                permission_grants[grant.permission] = []
+            permission_grants[grant.permission].append(
+                GrantedBySchema(
+                    role=role_name,
+                    scope=grant.scope.value,
+                )
+            )
+
+    return [
+        PermissionSchema(name=perm, granted_by=granted_by) for perm, granted_by in sorted(permission_grants.items())
+    ]
+
+
+def _get_rbac_metadata_from_route(route: BaseRoute) -> dict[str, Any] | None:
+    """Extract RBAC metadata from a route's endpoint function.
+
+    RBACRouter stores metadata in the endpoint's _rbac_metadata_ attribute.
+    """
+    endpoint = getattr(route, "endpoint", None)
+    if endpoint is None:
+        return None
+
+    # Check if the endpoint has RBAC metadata attached
+    return getattr(endpoint, "_rbac_metadata_", None)
+
+
+def _build_endpoints_schema(app: FastAPI) -> tuple[list[EndpointSchema], dict[str, type]]:
+    """Build endpoint schemas from the app's routes.
+
+    Returns:
+        Tuple of (endpoints, context_classes_map) where context_classes_map
+        maps context class names to their actual class objects.
+    """
+    endpoints: list[EndpointSchema] = []
+    context_classes: dict[str, type] = {}
+    seen_endpoints: set[tuple[str, str]] = set()
+
+    # Get all registered RBAC routers from app state
+    rbac_routers: list[tuple[str, Any]] = getattr(app.state, "_rbac_routers_", [])
+
+    # Build metadata map from all registered routers
+    metadata_map: dict[tuple[str, str], dict[str, Any]] = {}
+    for prefix, router in rbac_routers:
+        for (path, method), meta in router.endpoint_metadata.items():
+            full_path = prefix + path
+            metadata_map[(full_path, method)] = meta
+
+    # Iterate through all app routes
+    for route in app.routes:
+        if not hasattr(route, "methods") or not hasattr(route, "path"):
+            continue
+
+        route_path = route.path
+        methods = route.methods or {"GET"}
+
+        for method in methods:
+            if method == "HEAD":
+                continue
+
+            key = (route_path, method)
+            if key in seen_endpoints:
+                continue
+            seen_endpoints.add(key)
+
+            # Get metadata from router registry OR from endpoint directly
+            # This fallback ensures endpoints work even if router was included
+            # before RBACAuthz was initialized (bypassing _rbac_routers_ tracking)
+            meta = metadata_map.get(key)
+            if meta is None:
+                # Fall back to checking endpoint metadata directly
+                meta = _get_rbac_metadata_from_route(route)
+            if not meta:
+                meta = {}
+            permissions = meta.get("permissions", set())
+            contexts = meta.get("contexts", [])
+
+            # Skip non-RBAC endpoints
+            if not permissions and not contexts:
+                continue
+
+            # Track context classes for docstring extraction
+            for ctx_class in contexts:
+                context_classes[ctx_class.__name__] = ctx_class
+
+            endpoint_schema = EndpointSchema(
+                path=route_path,
+                method=method,
+                summary=getattr(route, "summary", None),
+                description=getattr(route, "description", None),
+                tags=list(getattr(route, "tags", []) or []),
+                permissions=sorted(permissions),
+                contexts=[ctx.__name__ for ctx in contexts],
+            )
+            endpoints.append(endpoint_schema)
+
+    return endpoints, context_classes
+
+
+def _build_contexts_schema(
+    endpoints: list[EndpointSchema],
+    context_classes: dict[str, type],
+) -> list[ContextSchema]:
+    """Build context schemas showing which endpoints use each context."""
+    context_usage: dict[str, list[str]] = {}
+
+    for endpoint in endpoints:
+        endpoint_id = f"{endpoint.method} {endpoint.path}"
+        for context_name in endpoint.contexts:
+            if context_name not in context_usage:
+                context_usage[context_name] = []
+            context_usage[context_name].append(endpoint_id)
+
+    return [
+        ContextSchema(
+            name=name,
+            description=context_classes.get(name).__doc__ if name in context_classes else None,
+            used_by=sorted(used_by),
+        )
+        for name, used_by in sorted(context_usage.items())
+    ]
+
+
+def build_ui_schema(app: FastAPI, rbac: RBACAuthz[Any]) -> UISchema:
+    """Build the complete UI schema for RBAC visualization.
+
+    Args:
+        app: The FastAPI application instance.
+        rbac: The RBACAuthz configuration.
+
+    Returns:
+        UISchema containing roles, permissions, endpoints, and contexts.
+    """
+    # Build endpoints first (we need them for context schema)
+    endpoints, context_classes = _build_endpoints_schema(app)
+
+    return UISchema(
+        roles=_build_roles_schema(rbac.permissions),
+        permissions=_build_permissions_schema(rbac.permissions),
+        endpoints=endpoints,
+        contexts=_build_contexts_schema(endpoints, context_classes),
+    )