fastapi-rbac-authz 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

fastapi_rbac/__init__.py

@@ -4,13 +4,8 @@ __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.dependencies import create_authz_dependency
+from fastapi_rbac.errors import Forbidden
 from fastapi_rbac.permissions import (
     Contextual,
     Global,
@@ -22,14 +17,11 @@ 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

@@ -1,34 +1,29 @@
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar
 
-UserT = TypeVar("UserT")
 
-
-class ContextualAuthz(ABC, Generic[UserT]):
+class ContextualAuthz(ABC):
     """Base class for contextual authorization checks.
 
-    Subclasses are FastAPI dependencies - use standard Depends() for
-    additional dependencies like database sessions.
+    Subclasses can use FastAPI dependencies in the __init__ method.
 
     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
+    >>> class MyContext(ContextualAuthz):
+    >>>     def __init__(
+    >>>         self,
+    >>>         user: Annotated[User, Depends(get_current_user)],  # your auth dep
+    >>>         request: Request,  # fastapi dep
+    >>>         db: AsyncSession = Depends(get_db),  # your database dep
+    >>>     ):
+    >>>         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.
@@ -36,4 +31,4 @@ class ContextualAuthz(ABC, Generic[UserT]):
         Returns:
             True if access should be granted, False otherwise.
         """
-        ...
+        raise NotImplementedError()

fastapi_rbac/core.py

@@ -1,42 +1,15 @@
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import Any
 
 from fastapi import APIRouter, FastAPI
 
-from fastapi_rbac.dependencies import _rbac_user_dependency_placeholder
+from fastapi_rbac.dependencies import _rbac_roles_dependency_placeholder
 from fastapi_rbac.permissions import PermissionGrant
+from fastapi_rbac.router import RBACRouter
+from fastapi_rbac.ui.routes import create_ui_router
 
-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]):
+class RBACAuthz:
     """Main RBAC authorization configuration.
 
     Attaches to a FastAPI application and provides authorization
@@ -44,68 +17,69 @@ class RBACAuthz(Generic[UserT]):
 
     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.
+        roles_dependency: FastAPI dependency that returns the user's roles as set[str].
+            This dependency is injected into all RBAC-protected endpoints via
+            FastAPI's dependency_overrides mechanism, and will be evaluated before RBAC 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,
+        roles_dependency: Callable[..., set[str]] | Callable[..., Awaitable[set[str]]],
         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.roles_dependency = roles_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_ = []
+        # Instance attributes for state management
+        self.routers: list[tuple[str, RBACRouter]] = []
+        self._include_router_wrapped: bool = False
 
         # 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
+        # Override the placeholder dependency with user's roles dependency
+        # This allows the roles 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
+        app.dependency_overrides[_rbac_roles_dependency_placeholder] = roles_dependency
         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_"):
+        if self._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]
+        self.app.include_router = self._create_wrapped_include_router(original_include_router)  # type: ignore[method-assign]
+        self._include_router_wrapped = True
+
+    def _create_wrapped_include_router(self, original_include_router: Callable[..., None]) -> Callable[..., None]:
+        """Create a wrapped include_router that tracks RBACRouters."""
+
+        def wrapped_include_router(
+            router: APIRouter,
+            *,
+            prefix: str = "",
+            **kwargs: Any,
+        ) -> None:
+            if isinstance(router, RBACRouter):
+                self.routers.append((prefix, router))
+            return original_include_router(router, prefix=prefix, **kwargs)
+
+        return wrapped_include_router
 
     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

@@ -1,96 +1,29 @@
 import inspect
-from collections.abc import Awaitable, Callable, Coroutine
-from typing import TYPE_CHECKING, Annotated, Any, TypeVar
+from collections.abc import Callable, Coroutine
+from typing import Annotated, Any
 
 from fastapi import Depends, Request
 
 from fastapi_rbac.context import ContextualAuthz
-from fastapi_rbac.exceptions import Forbidden
+from fastapi_rbac.errors 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
+ContextClass = type[ContextualAuthz]
 
-            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.
+async def _rbac_roles_dependency_placeholder(request: Request) -> set[str]:  # noqa: ARG001
+    """Placeholder dependency for user roles.
 
-    Raises:
-        Forbidden: If no user is found in request state.
+    This placeholder is replaced at runtime via FastAPI's dependency_overrides
+    mechanism when RBACAuthz is initialized. The roles_dependency provided to
+    RBACAuthz will be used instead of this placeholder.
     """
-    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)
+    raise RuntimeError("RBACAuthz not configured with roles_dependency")
 
 
 def create_authz_dependency(
@@ -100,7 +33,7 @@ def create_authz_dependency(
     """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)
+    1. Resolves a list of user roles via the injected roles_dependency
     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__:
@@ -111,9 +44,9 @@ def create_authz_dependency(
          - 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.
+    The roles_dependency is injected via FastAPI's dependency_overrides mechanism.
+    When RBACAuthz is initialized with a roles_dependency, it overrides the
+    _rbac_roles_dependency_placeholder with the provided dependency.
 
     Args:
         required_permissions: Set of permission strings required for access.
@@ -124,10 +57,13 @@ def create_authz_dependency(
     """
     # Build context parameters - each context class becomes a Depends(context_class)
     # FastAPI will resolve all __init__ parameters automatically
+    if not required_permissions and not context_classes:
+        raise RuntimeError("Endpoint must be protected with either permissions or contexts")
+
     context_params: list[inspect.Parameter] = []
     for i, ctx_class in enumerate(context_classes):
         param = inspect.Parameter(
-            f"_rbac_ctx_{i}_",
+            f"_fastapi_rbac_authz_ctx_{i}_",
             inspect.Parameter.KEYWORD_ONLY,
             default=None,
             annotation=Annotated[ctx_class, Depends(ctx_class)],
@@ -136,25 +72,18 @@ def create_authz_dependency(
 
     async def authz_dependency(
         request: Request,
-        _rbac_user_: Annotated[Any, Depends(_rbac_user_dependency_placeholder)],
+        _rbac_roles_: Annotated[set[str], Depends(_rbac_roles_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_roles_
+        if not roles:
+            raise Forbidden("User has no roles")
 
-        roles = rbac.get_roles(user)
         grants = resolve_grants(roles, rbac.permissions)
 
         if not grants:
@@ -175,7 +104,7 @@ def create_authz_dependency(
         # 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}_")
+                context = kwargs.get(f"_fastapi_rbac_authz_ctx_{i}_")
                 if context is not None and not await context.has_permissions():
                     raise Forbidden()
 
@@ -187,68 +116,13 @@ def create_authz_dependency(
             annotation=Request,
         ),
         inspect.Parameter(
-            "_rbac_user_",
+            "_rbac_roles_",
             inspect.Parameter.KEYWORD_ONLY,
             default=None,
-            annotation=Annotated[Any, Depends(_rbac_user_dependency_placeholder)],
+            annotation=Annotated[set[str], Depends(_rbac_roles_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 → errors.py}

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

fastapi_rbac/permissions.py

@@ -23,9 +23,11 @@ class PermissionGrant:
     def __hash__(self) -> int:
         return hash((self.permission, self.scope))
 
-    def __repr__(self) -> str:
+    def __str__(self) -> str:
         return f"{self.__class__.__name__}({self.permission!r})"
 
+    __repr__ = __str__
+
 
 class Global(PermissionGrant):
     """A global permission grant - bypasses contextual checks."""

fastapi_rbac/router.py

@@ -9,35 +9,30 @@ 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
+from fastapi_rbac.permissions import SEPARATOR, WILDCARD
 
-# Type alias for context classes
-ContextClass = type[ContextualAuthz[Any]]
+ContextClass = type[ContextualAuthz]  # alias
 
 
-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.
-    """
+def _validate_permissions(
+    permissions: set[str] | None,
+    location: str,
+) -> None:
+    """Various startup permissions validations"""
     if permissions is None:
         return
     for perm in permissions:
-        if _contains_wildcard(perm):
+        if WILDCARD in perm:
             raise RuntimeError(
                 f"Wildcard permissions are not allowed in {location}. "
                 f"Found '{perm}'. Wildcards should only be used in role grants."
             )
+        if SEPARATOR not in perm:
+            raise RuntimeError(
+                f"Each permission must decline at least one resource and one action. Found '{perm}' at {location}"
+            )
+        if perm.startswith(SEPARATOR) or perm.startswith(WILDCARD):
+            raise RuntimeError(f"Permission must explicitly define resource. Found '{perm}' at {location}")
 
 
 class RBACRouter(APIRouter):
@@ -73,7 +68,6 @@ class RBACRouter(APIRouter):
         contexts: list[ContextClass] | None = None,
         **kwargs: Any,
     ) -> None:
-        # Validate no wildcards in router-level permissions
         _validate_permissions(permissions, "router permissions")
 
         super().__init__(**kwargs)
@@ -81,24 +75,6 @@ class RBACRouter(APIRouter):
         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,
@@ -117,13 +93,8 @@ class RBACRouter(APIRouter):
         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)
@@ -162,33 +133,16 @@ class RBACRouter(APIRouter):
         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)
+        @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_sync.__signature__ = new_sig  # type: ignore[attr-defined]
-            return wrapped_sync
+        wrapped_async.__signature__ = new_sig  # type: ignore[attr-defined]
+        return wrapped_async
 
     def _add_route_with_authz(
         self,
@@ -218,7 +172,7 @@ class RBACRouter(APIRouter):
 
         # 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)
+            authz_dep = create_authz_dependency(final_permissions, final_contexts)
             endpoint = self._wrap_endpoint_with_authz(endpoint, authz_dep)
 
         # Attach RBAC metadata to endpoint for later introspection

fastapi_rbac/ui/routes.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from fastapi import APIRouter, Request
 from fastapi.responses import HTMLResponse, JSONResponse
@@ -59,8 +59,7 @@ def create_ui_router(ui_path: str) -> APIRouter:
         include_in_schema=False,
     )
     async def get_schema(request: Request) -> JSONResponse:
-        """Return the RBAC schema as JSON."""
-        rbac: RBACAuthz[Any] = request.app.state.rbac
+        rbac: RBACAuthz = request.app.state.rbac
         schema = build_ui_schema(request.app, rbac)
         return JSONResponse(content=schema.model_dump())
 

fastapi_rbac/ui/schema.py

@@ -147,8 +147,8 @@ def _build_endpoints_schema(app: FastAPI) -> tuple[list[EndpointSchema], dict[st
     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_", [])
+    # Get all registered RBAC routers from RBACAuthz instance
+    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]] = {}
@@ -232,7 +232,7 @@ def _build_contexts_schema(
     ]
 
 
-def build_ui_schema(app: FastAPI, rbac: RBACAuthz[Any]) -> UISchema:
+def build_ui_schema(app: FastAPI, rbac: RBACAuthz) -> UISchema:
     """Build the complete UI schema for RBAC visualization.
 
     Args:

{fastapi_rbac_authz-0.3.0.dist-info → fastapi_rbac_authz-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-rbac-authz
-Version: 0.3.0
+Version: 0.5.0
 Summary: Role-based access control with contextual authorization for FastAPI
 Project-URL: Homepage, https://github.com/parikls/fastapi-rbac
 Author-email: Dmytro Smyk <porovozls@gmail.com>
@@ -24,6 +24,14 @@ Description-Content-Type: text/markdown
 
 Role-based access control with contextual authorization for FastAPI.
 
+Library IS NOT responsible for authentication. You can use any authentication mechanism you want.
+
+  What you need to provide:
+  - A dependency that returns the authenticated user's roles as `set[str]`
+  - Permission definitions per role
+  - Use `RBACRouter` instead of `APIRouter` for protected routes
+  - Define permissions and context checks per endpoint
+
 ## Installation
 
 ```bash
@@ -36,16 +44,26 @@ pip install fastapi-rbac-authz
 from typing import Annotated
 from fastapi import Depends, FastAPI
 from fastapi_rbac import (
-    RBACAuthz, RBACRouter, Global, Contextual, ContextualAuthz, RBACUser
+    RBACAuthz, RBACRouter, Global, Contextual, ContextualAuthz
 )
 
-# 1. Define your user model
+# 1. You might have your user model (or you may not, we don't care)
 class User:
     def __init__(self, user_id: str, roles: set[str]):
         self.user_id = user_id
         self.roles = roles
 
-# 2. Define role permissions
+# 2. Assuming you have your own dependency that returns a user instance
+async def get_current_user() -> User:
+    # Your authentication logic here
+    return User(user_id="user-1", roles={"viewer"})
+
+# 3. Dependency that library **REQUIRES**. **MUST** return a set of user roles
+async def get_current_user_roles() -> set[str]:
+    user = await get_current_user()
+    return user.roles
+
+# 4. Define your roles permissions
 PERMISSIONS = {
     "admin": {
         Global("report:*"),         # Admin can do anything with reports
@@ -55,13 +73,12 @@ PERMISSIONS = {
     },
 }
 
-# 3. Create a context check (for contextual permissions)
-# All __init__ params are injected by FastAPI's DI system
-class ReportAccessContext(ContextualAuthz[User]):
+# 5. Create context authorization checks
+class ReportAccessContext(ContextualAuthz):
     def __init__(
         self,
         report_id: int,  # <-- Injected from path parameter
-        user: Annotated[User, Depends(RBACUser)],
+        user: Annotated[User, Depends(get_current_user)],  # Your own way how to get the user if you need it
     ):
         self.user = user
         self.report_id = report_id
@@ -71,22 +88,17 @@ class ReportAccessContext(ContextualAuthz[User]):
         allowed_reports = {1, 2, 3}  # e.g., query from database
         return self.report_id in allowed_reports
 
-# 4. Create your app and configure RBAC
+# 6. Configure RBAC
 app = FastAPI()
 
-async def get_current_user() -> User:
-    # Your authentication logic here
-    return User(user_id="user-1", roles={"viewer"})
-
 RBACAuthz(
     app,
-    get_roles=lambda u: u.roles,
     permissions=PERMISSIONS,
-    user_dependency=get_current_user,
+    roles_dependency=get_current_user_roles,  # Returns set[str]
     ui_path="/_rbac",  # Optional: mount visualization UI
 )
 
-# 5. Create protected routes
+# 7. Create protected routes
 router = RBACRouter(permissions={"report:read"}, contexts=[ReportAccessContext])
 
 @router.get("/reports/{report_id}")
@@ -136,14 +148,14 @@ PERMISSIONS = {
 
 ## Context Checks
 
-Context checks are classes that implement fine-grained authorization logic. They're regular FastAPI dependencies, so you can inject any parameters (path params, query params, request body, database sessions, etc.).
+Context checks are classes that implement fine-grained authorization logic. They're regular FastAPI dependencies, so you can inject any parameters (path params, query params, request body, database sessions, etc.). Each context class is responsible for its own authentication via FastAPI's dependency injection.
 
 ```python
-class ReportAccessContext(ContextualAuthz[User]):
+class ReportAccessContext(ContextualAuthz):
     def __init__(
         self,
         report_id: int,  # Injected from path parameter
-        user: Annotated[User, Depends(RBACUser)],
+        user: Annotated[User, Depends(get_current_user)],  # Your auth dependency
         db: Annotated[AsyncSession, Depends(get_db)],  # Database session
     ):
         self.user = user
@@ -161,11 +173,11 @@ class ReportAccessContext(ContextualAuthz[User]):
 When a request hits an RBAC-protected endpoint:
 
 ```
-1. Authentication
-   └── user_dependency runs → User object available
+1. Role Resolution
+   └── roles_dependency runs → User's roles (set[str]) available
 
 2. Permission Check
-   └── Does user have ANY grant (global or contextual) for required permission?
+   └── Does user have ANY grant (scoped or wildcard) for required permission?
        ├── No  → 403 Forbidden
        └── Yes → Continue
 
@@ -175,7 +187,7 @@ When a request hits an RBAC-protected endpoint:
        └── No  → Continue to context checks
 
 4. Context Checks (only for Contextual grants)
-   └── Run all context classes via FastAPI DI
+   └── Run all context classes via FastAPI DI (each gets its own user via Depends)
        └── Do ALL contexts return True?
            ├── No  → 403 Forbidden
            └── Yes → Access granted
@@ -214,8 +226,8 @@ uvicorn examples.basic_app:app --reload
 
 Then open your browser:
 
-- **http://localhost:8000/docs** - OpenAPI docs to test the API
-- **http://localhost:8000/_rbac** - Authorization visualization UI
+- **http://localhost:18000/docs** - OpenAPI docs to test the API
+- **http://localhost:18000/_rbac** - Authorization visualization UI
 
 ### Test with different users
 
@@ -223,15 +235,15 @@ The example uses `X-Token` header for authentication:
 
 ```bash
 # As admin (has Global("*") - full access)
-curl -H "X-Token: admin-token" http://localhost:8000/reports
-curl -H "X-Token: admin-token" http://localhost:8000/reports/1
+curl -H "X-Token: admin-token" http://localhost:18000/reports
+curl -H "X-Token: admin-token" http://localhost:18000/reports/1
 
 # As user (has Contextual permissions - can only access own reports)
-curl -H "X-Token: user-token" http://localhost:8000/reports/1  # OK (owns report 1)
-curl -H "X-Token: user-token" http://localhost:8000/reports/3  # 403 (doesn't own report 3)
+curl -H "X-Token: user-token" http://localhost:18000/reports/1  # OK (owns report 1)
+curl -H "X-Token: user-token" http://localhost:18000/reports/3  # 403 (doesn't own report 3)
 
 # As viewer (has Contextual read - can only read own reports)
-curl -H "X-Token: viewer-token" http://localhost:8000/reports/1  # 403 (doesn't own any)
+curl -H "X-Token: viewer-token" http://localhost:18000/reports/1  # 403 (doesn't own any)
 ```
 
 ## Visualization UI

fastapi_rbac_authz-0.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+fastapi_rbac/__init__.py,sha256=CqpNJ54-bMbUF-LrQUAGX9pfTBYXR6x13kG1EDm5odY,662
+fastapi_rbac/context.py,sha256=7lFQotJU4Wn-_BcHi3A8bAB7ftzVKJRJoXzs3q-I4tY,1039
+fastapi_rbac/core.py,sha256=pY8UjpSxf1xV5ODp2b15_fU16sUfxv32_5vipQIX4XU,3246
+fastapi_rbac/dependencies.py,sha256=zukBpbvB9586Lz_df7t1F-CA-cnhDy6R4aJo1FlSpr4,4916
+fastapi_rbac/errors.py,sha256=Df2zWPe-Kd54bKTB4w40wUTuNnppfCkZ33cJqnylIgo,247
+fastapi_rbac/permissions.py,sha256=lU1K2rHYqkxjYrnkG1Rk2FKEmgw0py62bNkOgSmznA8,2728
+fastapi_rbac/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+fastapi_rbac/router.py,sha256=4BeKXAEqcdFh4kX9AJaUuCmpVXJXU07Afubhb20Z7B8,9943
+fastapi_rbac/ui/__init__.py,sha256=u2enI_c9k1d0T0z1kBuGI4lpR0wifqFzkfaEUEnuLXg,220
+fastapi_rbac/ui/routes.py,sha256=UbJcMo6mMNNtzlSAdrp1S79wppkO4hFC018POzlsq-k,2025
+fastapi_rbac/ui/schema.py,sha256=Q7diGVuNuGHEGn_uq7OH5Cx2dE9QHfAEdLt70_BzpYE,7919
+fastapi_rbac/ui/static/index.html,sha256=HUxI7eO84duCxxOi9GqP4yybA6QrxQAbNcc6lYkjM30,73455
+fastapi_rbac_authz-0.5.0.dist-info/METADATA,sha256=qavdtMVBkWcB5Zc-2h9WBDSi_rLBrKCmZ8kS-bp-zVw,8770
+fastapi_rbac_authz-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fastapi_rbac_authz-0.5.0.dist-info/RECORD,,

fastapi_rbac_authz-0.3.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-fastapi_rbac/__init__.py,sha256=pmId7xpntLKSwaQaFmBwJa443-FyfGOFwl_pf8t04sE,817
-fastapi_rbac/context.py,sha256=txZqnw8xGPHsE3DQi75Q7ny_VifT0O2etcz5E8sm2wE,1070
-fastapi_rbac/core.py,sha256=smTSbxCQYyMBYvkzOavPurIMWKXrp1ZHWXOs7WVwVvY,4154
-fastapi_rbac/dependencies.py,sha256=2475jW8QPRUWubA__M48D-EY8GbL2SJH8mLaaEMoLfg,9325
-fastapi_rbac/exceptions.py,sha256=tSFbes6yzAygWXXl9NLdZ5K2_iISiJ6ZGJCD6077i94,244
-fastapi_rbac/permissions.py,sha256=VReUjewdFehkDpA_rowSAV2qFoAfoDhrLvoU2gGSxww,2705
-fastapi_rbac/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
-fastapi_rbac/router.py,sha256=kLUmWmBZKqNoGvoD44g-Un9tCIO_dP3psQYrNBm5QFI,11405
-fastapi_rbac/ui/__init__.py,sha256=u2enI_c9k1d0T0z1kBuGI4lpR0wifqFzkfaEUEnuLXg,220
-fastapi_rbac/ui/routes.py,sha256=d57_bPsrpFePzumqcHIU3Okf8TfXKkqf8KLhkrvCg_I,2081
-fastapi_rbac/ui/schema.py,sha256=p3mWgkpA20jYI_g7KiIdULXCFzSeNXBMIL9c7Pe7Zgg,7917
-fastapi_rbac/ui/static/index.html,sha256=HUxI7eO84duCxxOi9GqP4yybA6QrxQAbNcc6lYkjM30,73455
-fastapi_rbac_authz-0.3.0.dist-info/METADATA,sha256=zi4SKBP5vjZfNamnLuFmxNVXArBJ25Xy763RuRQfeck,7985
-fastapi_rbac_authz-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fastapi_rbac_authz-0.3.0.dist-info/RECORD,,