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

fastapi_rbac/__init__.py

@@ -0,0 +1,35 @@
+"""FastAPI RBAC Authorization - Role-based access control with contextual authorization."""
+
+__version__ = "0.1.0"
+
+from fastapi_rbac.context import ContextualAuthz
+from fastapi_rbac.core import RBACAuthz
+from fastapi_rbac.dependencies import (
+    RBACUser,
+    create_auth_dependency,
+    create_authz_dependency,
+    evaluate_permissions,
+)
+from fastapi_rbac.exceptions import Forbidden
+from fastapi_rbac.permissions import (
+    Contextual,
+    Global,
+    PermissionGrant,
+    PermissionScope,
+)
+from fastapi_rbac.router import RBACRouter
+
+__all__ = [
+    "RBACAuthz",
+    "RBACRouter",
+    "RBACUser",
+    "ContextualAuthz",
+    "Global",
+    "Contextual",
+    "PermissionGrant",
+    "PermissionScope",
+    "Forbidden",
+    "create_auth_dependency",
+    "create_authz_dependency",
+    "evaluate_permissions",
+]

fastapi_rbac/context.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+UserT = TypeVar("UserT")
+
+
+class ContextualAuthz(ABC, Generic[UserT]):
+    """Base class for contextual authorization checks.
+
+    Subclasses are FastAPI dependencies - use standard Depends() for
+    additional dependencies like database sessions.
+
+    Example:
+        class MyContext(ContextualAuthz[User]):
+            def __init__(
+                self,
+                user: User,
+                request: Request,
+                db: AsyncSession = Depends(get_db),
+            ):
+                self.user = user
+                self.request = request
+                self.db = db
+
+            async def has_permissions(self) -> bool:
+                # Check access using self.user, self.request, self.db
+                return True
+    """
+
+    user: UserT
+
+    @abstractmethod
+    async def has_permissions(self) -> bool:
+        """Check if the user has permission in this context.
+
+        Returns:
+            True if access should be granted, False otherwise.
+        """
+        ...

fastapi_rbac/core.py

@@ -0,0 +1,111 @@
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from fastapi import APIRouter, FastAPI
+
+from fastapi_rbac.dependencies import _rbac_user_dependency_placeholder
+from fastapi_rbac.permissions import PermissionGrant
+
+if TYPE_CHECKING:
+    pass
+
+UserT = TypeVar("UserT")
+
+
+def _wrap_include_router(app: FastAPI, original_include_router: Callable[..., None]) -> Callable[..., None]:
+    """Wrap FastAPI's include_router to track RBACRouters."""
+
+    def wrapped_include_router(
+        router: APIRouter,
+        *,
+        prefix: str = "",
+        **kwargs: Any,
+    ) -> None:
+        # Import here to avoid circular import
+        from fastapi_rbac.router import RBACRouter
+
+        # Track RBAC routers in app state
+        if isinstance(router, RBACRouter):
+            if not hasattr(app.state, "_rbac_routers_"):
+                app.state._rbac_routers_ = []
+            app.state._rbac_routers_.append((prefix, router))
+
+        # Call original method
+        return original_include_router(router, prefix=prefix, **kwargs)
+
+    return wrapped_include_router
+
+
+class RBACAuthz(Generic[UserT]):
+    """Main RBAC authorization configuration.
+
+    Attaches to a FastAPI application and provides authorization
+    configuration for RBACRouter endpoints.
+
+    Args:
+        app: The FastAPI application instance.
+        get_roles: Callable that extracts role strings from a user object.
+        permissions: Mapping of role names to sets of permission grants.
+        user_dependency: Optional FastAPI dependency that returns the authenticated user.
+            When provided, RBAC-protected endpoints will automatically run this dependency
+            and store the result in request.state.user before authorization checks.
+        ui_path: Optional path to mount the authorization UI (e.g., "/_rbac").
+        ui_permissions: Optional set of permissions required to access the UI.
+    """
+
+    def __init__(
+        self,
+        app: FastAPI,
+        get_roles: Callable[[UserT], set[str]],
+        permissions: dict[str, set[PermissionGrant]],
+        user_dependency: Callable[..., UserT] | Callable[..., Awaitable[UserT]] | None = None,
+        ui_path: str | None = None,
+        ui_permissions: set[str] | None = None,
+    ) -> None:
+        self.app = app
+        self.get_roles = get_roles
+        self.permissions = permissions
+        self.user_dependency = user_dependency
+        self.ui_path = ui_path
+        self.ui_permissions = ui_permissions
+
+        # Initialize router tracking list
+        if not hasattr(app.state, "_rbac_routers_"):
+            app.state._rbac_routers_ = []
+
+        # Attach to app state for access from routers
+        app.state.rbac = self
+
+        # If user_dependency is provided, override the placeholder dependency
+        # This allows the user's auth dependency to be injected into all
+        # RBAC-protected endpoints with proper FastAPI dependency resolution
+        if user_dependency is not None:
+            app.dependency_overrides[_rbac_user_dependency_placeholder] = user_dependency
+
+        # Wrap include_router to track RBAC routers
+        self._wrap_app_include_router()
+
+        # Mount UI if path specified
+        if ui_path:
+            self._mount_ui()
+
+    def _wrap_app_include_router(self) -> None:
+        """Wrap the app's include_router method to track RBACRouters."""
+        # Only wrap if not already wrapped
+        if hasattr(self.app, "_rbac_include_router_wrapped_"):
+            return
+
+        original_include_router = self.app.include_router
+        self.app.include_router = _wrap_include_router(self.app, original_include_router)  # type: ignore[method-assign]
+        self.app._rbac_include_router_wrapped_ = True  # type: ignore[attr-defined]
+
+    def _mount_ui(self) -> None:
+        """Mount the authorization visualization UI."""
+        if not self.ui_path:
+            return
+
+        # Import here to avoid circular import
+        from fastapi_rbac.ui.routes import create_ui_router
+
+        ui_router = create_ui_router(self.ui_path)
+        self.app.include_router(ui_router, prefix=self.ui_path)

fastapi_rbac/dependencies.py

@@ -0,0 +1,254 @@
+import inspect
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import TYPE_CHECKING, Annotated, Any, TypeVar
+
+from fastapi import Depends, Request
+
+from fastapi_rbac.context import ContextualAuthz
+from fastapi_rbac.exceptions import Forbidden
+from fastapi_rbac.permissions import (
+    has_global_permission,
+    has_permission,
+    resolve_grants,
+)
+
+if TYPE_CHECKING:
+    from fastapi_rbac.core import RBACAuthz
+
+UserT = TypeVar("UserT")
+
+# Type alias for context classes
+ContextClass = type[ContextualAuthz[Any]]
+
+
+def RBACUser(request: Request) -> Any:
+    """Get the current authenticated user for use in context classes.
+
+    This dependency reads the user from request.state.user, which is set
+    by the auth dependency created via create_auth_dependency().
+
+    Usage in context classes:
+        class MyContext(ContextualAuthz[User]):
+            def __init__(
+                self,
+                user: Annotated[User, Depends(RBACUser)],
+                request: Request,
+            ):
+                self.user = user
+                self.request = request
+
+            async def has_permissions(self) -> bool:
+                # Check permissions based on user and request context
+                return self.user.id in allowed_users
+
+    Returns:
+        The authenticated user object from request.state.user.
+
+    Raises:
+        Forbidden: If no user is found in request state.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        raise Forbidden("User not authenticated")
+    return user
+
+
+def create_auth_dependency(
+    rbac: "RBACAuthz[UserT]",  # noqa: ARG001 - kept for API consistency with RBACRouter
+    user_dependency: Callable[..., UserT] | Callable[..., Awaitable[UserT]],
+) -> Callable[..., Coroutine[Any, Any, UserT]]:
+    """Create a typed auth dependency for use in endpoints.
+
+    Args:
+        rbac: The RBACAuthz configuration instance. Currently unused but kept for
+            API consistency - RBACRouter stores the rbac reference for permission
+            evaluation.
+        user_dependency: A FastAPI dependency that returns the authenticated user.
+
+    Returns:
+        A dependency that can be used with Depends() in endpoint signatures.
+    """
+
+    async def auth_dependency(
+        request: Request,
+        user: Annotated[UserT, Depends(user_dependency)],
+    ) -> UserT:
+        # Store user in request state for authz dependency
+        request.state.user = user
+        return user
+
+    return auth_dependency
+
+
+async def _rbac_user_dependency_placeholder(request: Request) -> Any:
+    """Placeholder dependency for user authentication.
+
+    This placeholder is used in the authz_dependency signature and gets replaced
+    at runtime via FastAPI's dependency_overrides mechanism when RBACAuthz is
+    initialized with a user_dependency.
+
+    If no user_dependency is configured, this falls back to reading from
+    request.state.user (which must be set by the user's own auth mechanism).
+    """
+    return getattr(request.state, "user", None)
+
+
+def create_authz_dependency(
+    required_permissions: set[str],
+    context_classes: list[ContextClass],
+) -> Callable[..., Coroutine[Any, Any, None]]:
+    """Create an authorization dependency that uses FastAPI's full DI for contexts.
+
+    This function creates a FastAPI dependency that:
+    1. Resolves user via the injected user_dependency (or placeholder fallback)
+    2. Gets RBAC config from app.state.rbac
+    3. Uses FastAPI's Depends(context_class) to instantiate each context
+       - Context classes can use ANY FastAPI dependency patterns in __init__:
+         - user: AuthUser (resolved via Depends)
+         - request: Request (built-in)
+         - org_id: str (from path parameter)
+         - body: SomeModel (from request body)
+         - db: Db (via Depends)
+    4. Calls has_permissions() on each resolved context
+
+    The user_dependency is injected via FastAPI's dependency_overrides mechanism.
+    When RBACAuthz is initialized with a user_dependency, it overrides the
+    _rbac_user_dependency_placeholder with the provided dependency.
+
+    Args:
+        required_permissions: Set of permission strings required for access.
+        context_classes: List of ContextualAuthz subclasses to check.
+
+    Returns:
+        An async dependency function for use with FastAPI's Depends().
+    """
+    # Build context parameters - each context class becomes a Depends(context_class)
+    # FastAPI will resolve all __init__ parameters automatically
+    context_params: list[inspect.Parameter] = []
+    for i, ctx_class in enumerate(context_classes):
+        param = inspect.Parameter(
+            f"_rbac_ctx_{i}_",
+            inspect.Parameter.KEYWORD_ONLY,
+            default=None,
+            annotation=Annotated[ctx_class, Depends(ctx_class)],
+        )
+        context_params.append(param)
+
+    async def authz_dependency(
+        request: Request,
+        _rbac_user_: Annotated[Any, Depends(_rbac_user_dependency_placeholder)],
+        **kwargs: Any,
+    ) -> None:
+        """Authorization dependency that checks permissions and contexts."""
+        # Get RBAC config from app state
+        rbac = getattr(request.app.state, "rbac", None)
+        if rbac is None:
+            raise RuntimeError("RBACAuthz not configured. Make sure to create an RBACAuthz instance with your app.")
+
+        # User is resolved by the injected user_dependency (or placeholder)
+        user = _rbac_user_
+        if user is None:
+            raise Forbidden("User not authenticated")
+
+        # Check permissions first
+        if not required_permissions and not context_classes:
+            raise RuntimeError("Endpoint must be protected with permissions or contexts")
+
+        roles = rbac.get_roles(user)
+        grants = resolve_grants(roles, rbac.permissions)
+
+        if not grants:
+            raise Forbidden()
+
+        need_contextual_check = not required_permissions
+
+        for required in required_permissions:
+            if has_global_permission(grants, required):
+                # Global permission - no need for contextual check for this permission
+                continue
+
+            need_contextual_check = True
+            if not has_permission(grants, required):
+                raise Forbidden()
+
+        # Run contextual checks if needed
+        # Context instances are already resolved by FastAPI via Depends(context_class)
+        if need_contextual_check:
+            for i in range(len(context_classes)):
+                context = kwargs.get(f"_rbac_ctx_{i}_")
+                if context is not None and not await context.has_permissions():
+                    raise Forbidden()
+
+    # Build the final signature with context params
+    base_params = [
+        inspect.Parameter(
+            "request",
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=Request,
+        ),
+        inspect.Parameter(
+            "_rbac_user_",
+            inspect.Parameter.KEYWORD_ONLY,
+            default=None,
+            annotation=Annotated[Any, Depends(_rbac_user_dependency_placeholder)],
+        ),
+    ]
+
+    new_sig = inspect.Signature(parameters=base_params + context_params)
+    authz_dependency.__signature__ = new_sig  # type: ignore[attr-defined]
+
+    return authz_dependency
+
+
+async def evaluate_permissions(
+    user: Any,
+    request: Request,
+    rbac: "RBACAuthz[Any]",
+    required_permissions: set[str],
+    context_classes: list[ContextClass],
+) -> None:
+    """Directly evaluate permissions without FastAPI dependency injection.
+
+    This function is useful for testing or when you need to check permissions
+    outside of a FastAPI endpoint context. Unlike create_authz_dependency(),
+    this function instantiates context classes directly with user and request.
+
+    Args:
+        user: The authenticated user object.
+        request: The current HTTP request.
+        rbac: The RBACAuthz configuration instance.
+        required_permissions: Set of permission strings required for access.
+        context_classes: List of ContextualAuthz subclasses to check.
+
+    Raises:
+        Forbidden: If the user does not have the required permissions.
+        RuntimeError: If no permissions or contexts are specified.
+    """
+    if not required_permissions and not context_classes:
+        raise RuntimeError("Endpoint must be protected with permissions or contexts")
+
+    roles = rbac.get_roles(user)
+    grants = resolve_grants(roles, rbac.permissions)
+
+    if not grants:
+        raise Forbidden()
+
+    need_contextual_check = not required_permissions
+
+    for required in required_permissions:
+        if has_global_permission(grants, required):
+            # Global permission - no need for contextual check for this permission
+            continue
+
+        need_contextual_check = True
+        if not has_permission(grants, required):
+            raise Forbidden()
+
+    # Run contextual checks if needed
+    # Instantiate context classes directly with user and request
+    if need_contextual_check:
+        for ctx_class in context_classes:
+            # Context classes are expected to accept user and request in their __init__
+            context = ctx_class(user=user, request=request)  # type: ignore[call-arg]
+            if not await context.has_permissions():
+                raise Forbidden()

fastapi_rbac/exceptions.py

@@ -0,0 +1,8 @@
+from fastapi import HTTPException
+
+
+class Forbidden(HTTPException):
+    """403 Forbidden - user lacks required permissions."""
+
+    def __init__(self, detail: str = "Forbidden") -> None:
+        super().__init__(status_code=403, detail=detail)

fastapi_rbac/permissions.py

@@ -0,0 +1,87 @@
+from enum import StrEnum
+
+
+class PermissionScope(StrEnum):
+    GLOBAL = "global"
+    CONTEXTUAL = "contextual"
+
+
+class PermissionGrant:
+    """A permission grant with a scope (global or contextual)."""
+
+    __slots__ = ("permission", "scope")
+
+    def __init__(self, permission: str, scope: PermissionScope) -> None:
+        self.permission = permission
+        self.scope = scope
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, PermissionGrant):
+            return NotImplemented
+        return self.permission == other.permission and self.scope == other.scope
+
+    def __hash__(self) -> int:
+        return hash((self.permission, self.scope))
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.permission!r})"
+
+
+class Global(PermissionGrant):
+    """A global permission grant - bypasses contextual checks."""
+
+    def __init__(self, permission: str) -> None:
+        super().__init__(permission, PermissionScope.GLOBAL)
+
+
+class Contextual(PermissionGrant):
+    """A contextual permission grant - requires context checks to pass."""
+
+    def __init__(self, permission: str) -> None:
+        super().__init__(permission, PermissionScope.CONTEXTUAL)
+
+
+WILDCARD = "*"
+SEPARATOR = ":"
+
+
+def implies(held: str, required: str) -> bool:
+    """Check if a held permission implies (grants) a required permission.
+
+    Supports wildcards: 'report:*' implies 'report:read', 'report:delete', etc.
+    Global wildcard '*' implies everything.
+    """
+    held_parts = held.split(SEPARATOR)
+    required_parts = required.split(SEPARATOR)
+
+    for i, held_part in enumerate(held_parts):
+        if held_part == WILDCARD:
+            return True
+        if i >= len(required_parts):
+            return False
+        if held_part != required_parts[i]:
+            return False
+
+    return len(held_parts) == len(required_parts)
+
+
+def resolve_grants(
+    roles: set[str],
+    permissions_map: dict[str, set[PermissionGrant]],
+) -> list[PermissionGrant]:
+    """Resolve all permission grants for a set of roles."""
+    grants: list[PermissionGrant] = []
+    for role in roles:
+        for grant in permissions_map.get(role, set()):
+            grants.append(grant)
+    return grants
+
+
+def has_permission(grants: list[PermissionGrant], required: str) -> bool:
+    """Check if any grant satisfies the required permission."""
+    return any(implies(grant.permission, required) for grant in grants)
+
+
+def has_global_permission(grants: list[PermissionGrant], required: str) -> bool:
+    """Check if any GLOBAL grant satisfies the required permission."""
+    return any(grant.scope == PermissionScope.GLOBAL and implies(grant.permission, required) for grant in grants)

fastapi_rbac/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561