casbin-fastapi-decorator 0.1.0__tar.gz

casbin_fastapi_decorator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neko1313
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

casbin_fastapi_decorator-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.3
+Name: casbin-fastapi-decorator
+Version: 0.1.0
+Summary: Casbin authorization decorator factory for FastAPI
+Author: Neko1313
+Author-email: Neko1313 <nikita.ribalchencko@yandex.ru>
+License: MIT License
+         
+         Copyright (c) 2026 Neko1313
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastapi-decorators>=0.5.0
+Requires-Dist: casbin>=1.36.0
+Requires-Dist: casbin-fastapi-decorator-db ; extra == 'db'
+Requires-Dist: casbin-fastapi-decorator-jwt ; extra == 'jwt'
+Requires-Python: >=3.10
+Provides-Extra: db
+Provides-Extra: jwt
+Description-Content-Type: text/markdown
+
+# casbin-fastapi-decorator
+
+Authorization decorator factory for FastAPI based on [Casbin](https://casbin.org/) and [fastapi-decorators](https://pypi.org/project/fastapi-decorators/).
+
+Decorators are applied to routes — no middleware or dependencies in the endpoint signature.
+
+## Installation
+
+```bash
+pip install casbin-fastapi-decorator
+```
+
+Additional providers:
+
+```bash
+pip install "casbin-fastapi-decorator[jwt]"   # JWT authentication
+pip install "casbin-fastapi-decorator[db]"    # Policies from DB (SQLAlchemy)
+```
+
+## Quick start
+
+```python
+import casbin
+from fastapi import FastAPI, HTTPException
+from casbin_fastapi_decorator import AccessSubject, PermissionGuard
+
+# 1. Providers — regular FastAPI dependencies
+async def get_current_user() -> dict:
+    return {"sub": "alice", "role": "admin"}
+
+async def get_enforcer() -> casbin.Enforcer:
+    return casbin.Enforcer("model.conf", "policy.csv")
+
+# 2. Decorator factory
+guard = PermissionGuard(
+    user_provider=get_current_user,
+    enforcer_provider=get_enforcer,
+    error_factory=lambda user, *rv: HTTPException(403, "Forbidden"),
+)
+
+app = FastAPI()
+
+# 3. Authentication only
+@app.get("/me")
+@guard.auth_required()
+async def me():
+    return {"ok": True}
+
+# 4. Static permission check
+@app.get("/articles")
+@guard.require_permission("articles", "read")
+async def list_articles():
+    return []
+
+# 5. Dynamic check — value from request
+async def get_article(article_id: int) -> dict:
+    return {"id": article_id, "owner": "alice"}
+
+@app.get("/articles/{article_id}")
+@guard.require_permission(
+    AccessSubject(val=get_article, selector=lambda a: a["owner"]),
+    "read",
+)
+async def read_article(article_id: int):
+    return {"article_id": article_id}
+```
+
+Arguments of `require_permission` are passed to `enforcer.enforce(user, *args)` in the same order. `AccessSubject` is resolved via FastAPI DI, then transformed by the `selector`.
+
+## API
+
+### `PermissionGuard`
+
+```python
+PermissionGuard(
+    user_provider=...,       # FastAPI dependency that returns the current user
+    enforcer_provider=...,   # FastAPI dependency that returns a casbin.Enforcer
+    error_factory=...,       # callable(user, *rvals) -> Exception
+)
+```
+
+| Method | Description |
+|---|---|
+| `auth_required()` | Decorator: authentication only (user_provider must not raise an exception) |
+| `require_permission(*args)` | Decorator: permission check via `enforcer.enforce(user, *args)` |
+
+### `AccessSubject`
+
+```python
+AccessSubject(
+    val=get_item,                        # FastAPI dependency
+    selector=lambda item: item["name"],  # transformation before enforce
+)
+```
+
+Wraps a dependency whose value needs to be obtained from the request and passed to the enforcer. By default, `selector` is identity (`lambda x: x`).
+
+## JWT provider
+
+```python
+from casbin_fastapi_decorator_jwt import JWTUserProvider
+
+user_provider = JWTUserProvider(
+    secret_key="your-secret",
+    algorithm="HS256",             # default
+    cookie_name="access_token",    # optional, enables reading from cookie
+    user_model=UserSchema,         # optional, Pydantic model for payload validation
+)
+```
+
+Extracts JWT from the Bearer header and/or cookie. If `user_model` is specified, validates the payload via `model_validate()`.
+
+## DB provider
+
+```python
+from casbin_fastapi_decorator_db import DatabaseEnforcerProvider
+
+enforcer_provider = DatabaseEnforcerProvider(
+    model_path="model.conf",
+    session_factory=get_async_session,
+    policy_model=PolicyORM,
+    policy_mapper=lambda p: (p.sub, p.obj, p.act),
+    default_policies=[("admin", "*", "*")],  # optional
+)
+```
+
+Loads policies from a SQLAlchemy async session and creates a `casbin.Enforcer` per request. `default_policies` are added on top of the DB policies.
+
+## Examples
+
+| Example | Description |
+|---|---|
+| [`examples/core`](examples/core) | Bearer token auth, file-based Casbin policies |
+| [`examples/core-jwt`](examples/core-jwt) | JWT auth via `JWTUserProvider`, file-based policies |
+| [`examples/core-db`](examples/core-db) | Bearer token auth, policies from SQLite via `DatabaseEnforcerProvider` |
+
+## Development
+
+Requires Python 3.10+, [uv](https://docs.astral.sh/uv/), [task](https://taskfile.dev/).
+
+```bash
+task install           # uv sync --all-groups + install extras (jwt, db)
+task lint              # ruff + ty + bandit for all packages
+task tests             # all tests (core + jwt + db)
+```
+
+Individual package tasks:
+
+```bash
+task core:lint         # lint core only
+task core:test         # test core only
+task jwt:lint          # lint JWT package
+task jwt:test          # test JWT package
+task db:lint           # lint DB package
+task db:test           # test DB package (requires Docker for testcontainers)
+```
+
+## License
+
+MIT

casbin_fastapi_decorator-0.1.0/README.md

@@ -0,0 +1,160 @@
+# casbin-fastapi-decorator
+
+Authorization decorator factory for FastAPI based on [Casbin](https://casbin.org/) and [fastapi-decorators](https://pypi.org/project/fastapi-decorators/).
+
+Decorators are applied to routes — no middleware or dependencies in the endpoint signature.
+
+## Installation
+
+```bash
+pip install casbin-fastapi-decorator
+```
+
+Additional providers:
+
+```bash
+pip install "casbin-fastapi-decorator[jwt]"   # JWT authentication
+pip install "casbin-fastapi-decorator[db]"    # Policies from DB (SQLAlchemy)
+```
+
+## Quick start
+
+```python
+import casbin
+from fastapi import FastAPI, HTTPException
+from casbin_fastapi_decorator import AccessSubject, PermissionGuard
+
+# 1. Providers — regular FastAPI dependencies
+async def get_current_user() -> dict:
+    return {"sub": "alice", "role": "admin"}
+
+async def get_enforcer() -> casbin.Enforcer:
+    return casbin.Enforcer("model.conf", "policy.csv")
+
+# 2. Decorator factory
+guard = PermissionGuard(
+    user_provider=get_current_user,
+    enforcer_provider=get_enforcer,
+    error_factory=lambda user, *rv: HTTPException(403, "Forbidden"),
+)
+
+app = FastAPI()
+
+# 3. Authentication only
+@app.get("/me")
+@guard.auth_required()
+async def me():
+    return {"ok": True}
+
+# 4. Static permission check
+@app.get("/articles")
+@guard.require_permission("articles", "read")
+async def list_articles():
+    return []
+
+# 5. Dynamic check — value from request
+async def get_article(article_id: int) -> dict:
+    return {"id": article_id, "owner": "alice"}
+
+@app.get("/articles/{article_id}")
+@guard.require_permission(
+    AccessSubject(val=get_article, selector=lambda a: a["owner"]),
+    "read",
+)
+async def read_article(article_id: int):
+    return {"article_id": article_id}
+```
+
+Arguments of `require_permission` are passed to `enforcer.enforce(user, *args)` in the same order. `AccessSubject` is resolved via FastAPI DI, then transformed by the `selector`.
+
+## API
+
+### `PermissionGuard`
+
+```python
+PermissionGuard(
+    user_provider=...,       # FastAPI dependency that returns the current user
+    enforcer_provider=...,   # FastAPI dependency that returns a casbin.Enforcer
+    error_factory=...,       # callable(user, *rvals) -> Exception
+)
+```
+
+| Method | Description |
+|---|---|
+| `auth_required()` | Decorator: authentication only (user_provider must not raise an exception) |
+| `require_permission(*args)` | Decorator: permission check via `enforcer.enforce(user, *args)` |
+
+### `AccessSubject`
+
+```python
+AccessSubject(
+    val=get_item,                        # FastAPI dependency
+    selector=lambda item: item["name"],  # transformation before enforce
+)
+```
+
+Wraps a dependency whose value needs to be obtained from the request and passed to the enforcer. By default, `selector` is identity (`lambda x: x`).
+
+## JWT provider
+
+```python
+from casbin_fastapi_decorator_jwt import JWTUserProvider
+
+user_provider = JWTUserProvider(
+    secret_key="your-secret",
+    algorithm="HS256",             # default
+    cookie_name="access_token",    # optional, enables reading from cookie
+    user_model=UserSchema,         # optional, Pydantic model for payload validation
+)
+```
+
+Extracts JWT from the Bearer header and/or cookie. If `user_model` is specified, validates the payload via `model_validate()`.
+
+## DB provider
+
+```python
+from casbin_fastapi_decorator_db import DatabaseEnforcerProvider
+
+enforcer_provider = DatabaseEnforcerProvider(
+    model_path="model.conf",
+    session_factory=get_async_session,
+    policy_model=PolicyORM,
+    policy_mapper=lambda p: (p.sub, p.obj, p.act),
+    default_policies=[("admin", "*", "*")],  # optional
+)
+```
+
+Loads policies from a SQLAlchemy async session and creates a `casbin.Enforcer` per request. `default_policies` are added on top of the DB policies.
+
+## Examples
+
+| Example | Description |
+|---|---|
+| [`examples/core`](examples/core) | Bearer token auth, file-based Casbin policies |
+| [`examples/core-jwt`](examples/core-jwt) | JWT auth via `JWTUserProvider`, file-based policies |
+| [`examples/core-db`](examples/core-db) | Bearer token auth, policies from SQLite via `DatabaseEnforcerProvider` |
+
+## Development
+
+Requires Python 3.10+, [uv](https://docs.astral.sh/uv/), [task](https://taskfile.dev/).
+
+```bash
+task install           # uv sync --all-groups + install extras (jwt, db)
+task lint              # ruff + ty + bandit for all packages
+task tests             # all tests (core + jwt + db)
+```
+
+Individual package tasks:
+
+```bash
+task core:lint         # lint core only
+task core:test         # test core only
+task jwt:lint          # lint JWT package
+task jwt:test          # test JWT package
+task db:lint           # lint DB package
+task db:test           # test DB package (requires Docker for testcontainers)
+```
+
+## License
+
+MIT

casbin_fastapi_decorator-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "casbin-fastapi-decorator"
+version = "0.1.0"
+description = "Casbin authorization decorator factory for FastAPI"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Neko1313", email = "nikita.ribalchencko@yandex.ru" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115.0",
+    "fastapi-decorators>=0.5.0",
+    "casbin>=1.36.0",
+]
+
+[project.optional-dependencies]
+jwt = [
+    "casbin-fastapi-decorator-jwt"
+]
+db = [
+    "casbin-fastapi-decorator-db"
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = [
+    "packages/*",
+    "examples/core",
+    "examples/core-jwt",
+    "examples/core-db",
+]
+
+[tool.uv.sources]
+casbin-fastapi-decorator-jwt = { workspace = true }
+casbin-fastapi-decorator-db = { workspace = true }
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+python_files = ["test_*.py", "*_test.py", "act.py", "error.py"]
+markers = [
+    "integration: integration tests (real I/O, HTTP)",
+    "unit: unit tests (no real I/O)",
+    "permission_guard: PermissionGuard component tests",
+    "access_subject: AccessSubject component tests",
+]
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+
+[dependency-groups]
+lint = [
+    "bandit>=1.9.3",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
+]
+test = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "httpx>=0.28.0",
+]

casbin_fastapi_decorator-0.1.0/src/casbin_fastapi_decorator/__init__.py

@@ -0,0 +1,6 @@
+"""Casbin authorization decorator factory for FastAPI."""
+
+from casbin_fastapi_decorator._guard import PermissionGuard
+from casbin_fastapi_decorator._types import AccessSubject
+
+__all__ = ["AccessSubject", "PermissionGuard"]

casbin_fastapi_decorator-0.1.0/src/casbin_fastapi_decorator/_builder.py

@@ -0,0 +1,64 @@
+from collections.abc import Callable
+from functools import wraps
+from inspect import isawaitable
+from typing import Any
+
+from fastapi import Depends
+from fastapi_decorators import depends
+
+from casbin_fastapi_decorator._types import AccessSubject
+
+
+def build_auth_decorator(user_provider: "Callable[..., Any]") -> Callable:
+    """Build an authentication-only decorator."""
+    return depends(Depends(user_provider))
+
+
+def build_permission_decorator(
+    *,
+    user_provider: "Callable[..., Any]",
+    enforcer_provider: "Callable[..., Any]",
+    error_factory: "Callable[..., Exception]",
+    args: tuple[AccessSubject | Any, ...],
+) -> "Callable":
+    """
+    Build a permission-check decorator via casbin enforcer.
+
+    Resolved values are passed to
+    ``enforcer.enforce(user, *rvals)``
+    in the same order as *args*.
+    """
+    depends_kwargs: dict[str, Any] = {
+        "__fguard_user__": Depends(user_provider),
+        "__fguard_enforcer__": Depends(enforcer_provider),
+    }
+    for i, arg in enumerate(args):
+        if isinstance(arg, AccessSubject):
+            depends_kwargs[f"__fguard_{i}__"] = Depends(arg.val)
+
+    def decorator(func: "Callable") -> "Callable":
+        @depends(**depends_kwargs)
+        @wraps(func)
+        async def wrapper(*fn_args: Any, **kw: Any) -> Any:
+            user = kw.pop("__fguard_user__")
+            enforcer = kw.pop("__fguard_enforcer__")
+
+            rvals: list[Any] = []
+            for i, arg in enumerate(args):
+                if isinstance(arg, AccessSubject):
+                    raw = kw.pop(f"__fguard_{i}__")
+                    rvals.append(arg.selector(raw))
+                else:
+                    rvals.append(arg)
+
+            result = enforcer.enforce(user, *rvals)
+            if isawaitable(result):
+                result = await result
+            if not result:
+                raise error_factory(user, *rvals)
+
+            return await func(*fn_args, **kw)
+
+        return wrapper
+
+    return decorator

casbin_fastapi_decorator-0.1.0/src/casbin_fastapi_decorator/_guard.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from casbin_fastapi_decorator._builder import (
+    build_auth_decorator,
+    build_permission_decorator,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from casbin_fastapi_decorator._types import AccessSubject
+
+
+class PermissionGuard:
+    """
+    Factory for authorization decorators.
+
+    Args:
+        user_provider: FastAPI dependency returning
+            the current user.
+        enforcer_provider: FastAPI dependency returning
+            a casbin Enforcer (``.enforce()``).
+        error_factory: Callable that creates an exception
+            on access denial. Receives ``(user, *rvals)``.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        user_provider: Callable[..., Any],
+        enforcer_provider: Callable[..., Any],
+        error_factory: Callable[..., Exception],
+    ) -> None:
+        self._user_provider = user_provider
+        self._enforcer_provider = enforcer_provider
+        self._error_factory = error_factory
+
+    def auth_required(self) -> Callable:
+        """Return an authentication-only decorator."""
+        return build_auth_decorator(self._user_provider)
+
+    def require_permission(self, *args: AccessSubject | Any) -> Callable:
+        """
+        Return a permission-check decorator.
+
+        Positional arguments are passed to
+        ``enforcer.enforce(user, *resolved_values)``
+        in the same order. ``AccessSubject`` values are
+        resolved via FastAPI DI and transformed with
+        their selector. Other values are passed as-is.
+        """
+        return build_permission_decorator(
+            user_provider=self._user_provider,
+            enforcer_provider=self._enforcer_provider,
+            error_factory=self._error_factory,
+            args=args,
+        )

casbin_fastapi_decorator-0.1.0/src/casbin_fastapi_decorator/_types.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@dataclass(frozen=True, slots=True)
+class AccessSubject:
+    """
+    Wrapper around a FastAPI dependency with a selector.
+
+    val: callable — FastAPI dep, wrapped in Depends()
+    selector: transforms the resolved value before enforce
+    """
+
+    val: Callable[..., Any]
+    selector: Callable[[Any], Any] = field(default=lambda x: x)