fastapi-rbac-authz 0.2.0__tar.gz

fastapi_rbac_authz-0.2.0/.github/workflows/checks.yaml

@@ -0,0 +1,30 @@
+name: Checks
+
+on: workflow_call
+
+jobs:
+  checks:
+    name: Style & Types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install poetry
+        run: pip install "poetry<3"
+
+      - name: Install dependencies
+        run: poetry install --with dev
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+
+      - name: Run tests
+        run: poetry run pytest -v tests/

fastapi_rbac_authz-0.2.0/.github/workflows/pypi-minor-deployment.yaml

@@ -0,0 +1,59 @@
+name: PyPi Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+
+  checks:
+    uses: ./.github/workflows/checks.yaml
+
+  deploy:
+
+    name: PyPi Deploy
+    runs-on: ubuntu-latest
+    needs: ["checks"]
+
+    env:
+      PYPI_USER: ${{ secrets.PYPI_USER }}
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.13
+
+      - name: Install poetry
+        run: pip install "poetry<3"
+
+      - name: Skip virtualenv creation
+        run: poetry config virtualenvs.create false
+
+      - name: Configure PyPi credentials
+        run: poetry config pypi-token.pypi ${{ env.PYPI_PASSWORD }}
+
+      - name: Bump Version
+        run: poetry version minor
+
+      - name: Git set email
+        run: git config --global user.email "github.bot@pypi.org"
+
+      - name: Git set name
+        run: git config --global user.name "GitHub Bot"
+
+      - name: Commit
+        run: git commit -m "[skip ci] auto-bump-version" -a
+
+      - name: Push
+        run: git push
+
+      - name: Deploy to PyPi
+        run: poetry --build publish

fastapi_rbac_authz-0.2.0/.gitignore

@@ -0,0 +1,245 @@
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+docs
+docs/

fastapi_rbac_authz-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff
+        args: [fastapi_rbac, tests, --fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: bash -lc 'poetry run mypy fastapi_rbac tests'
+        language: system
+        types: [python]
+        pass_filenames: false
+

fastapi_rbac_authz-0.2.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+FastAPI RBAC Authorization library providing role-based access control with contextual authorization for FastAPI applications. The package name is `fastapi-rbac` (import as `fastapi_rbac`).
+
+## Development Commands
+
+```bash
+# Install dependencies
+poetry install --with dev
+
+# Run all tests
+pytest -v tests/
+
+# Run specific test file
+pytest -v tests/test_integration.py
+
+# Run specific test
+pytest -k "test_name"
+
+# Type checking (strict mode)
+mypy fastapi_rbac
+
+# Build package
+poetry build
+```
+
+**IMPORTANT:** Always run pre-commit after making any code changes:
+```bash
+pre-commit run --all-files
+```
+This runs ruff (linting + formatting) and mypy (type checking on fastapi_rbac).
+
+## Architecture
+
+### Core Components
+
+**RBACAuthz[UserT]** (`core.py`) - Main configuration class that attaches to FastAPI app. Configures role-to-permission mappings, user dependency injection, and optional visualization UI.
+
+**RBACRouter** (`router.py`) - Extended APIRouter with permission decorators (`@router.get(permissions=..., contexts=...)`). Supports default permissions at router level with per-endpoint overrides. Stores endpoint metadata for UI introspection.
+
+**Permission System** (`permissions.py`) - Two scopes: `Global` (bypasses context checks) and `Contextual` (requires context validation). Supports wildcard matching (`resource:*` matches `resource:read`). Wildcards only allowed in role grants, not endpoint requirements.
+
+**ContextualAuthz[UserT]** (`context.py`) - Abstract base class for context-specific authorization. Subclasses are FastAPI dependencies that implement `async has_permissions() -> bool`. Supports full FastAPI DI in `__init__`. Context classes should use `Annotated[User, Depends(RBACUser)]` for the user parameter.
+
+**Dependencies** (`dependencies.py`) - Creates FastAPI dependencies for auth and authz. Uses `dependency_overrides` pattern for user dependency injection. Manipulates function signatures dynamically via `inspect.Signature`.
+
+**UI System** (`ui/`) - Cytoscape.js visualization mounted at configurable path. Introspects RBAC configuration to display role → permission → endpoint ← context relationships.
+
+### Key Patterns
+
+- **Request State**: User stored in `request.state.user`, RBAC config in `app.state.rbac`, routers in `app.state._rbac_routers_`
+- **Metadata Tracking**: Endpoints store `_rbac_metadata_` attribute; routers track `endpoint_metadata[(path, method)]`
+- **Permission Resolution**: Extract roles → resolve grants → check global permissions first → run contextual checks only if needed
+- **Type Safety**: Strict mypy with full generics (`RBACAuthz[UserT]`, `ContextualAuthz[UserT]`)
+
+### Public API (from `__init__.py`)
+
+```python
+RBACAuthz, RBACRouter, RBACUser, ContextualAuthz
+Global, Contextual, PermissionGrant, PermissionScope
+Forbidden, create_auth_dependency, create_authz_dependency, evaluate_permissions
+```

fastapi_rbac_authz-0.2.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: fastapi-rbac-authz
+Version: 0.2.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>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.12
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: starlette>=0.27.0
+Description-Content-Type: text/markdown
+
+# fastapi-rbac-authz
+
+Role-based access control with contextual authorization for FastAPI.
+
+## Installation
+
+```bash
+pip install fastapi-rbac-authz
+```
+
+## Quick Start
+
+```python
+from typing import Annotated
+from fastapi import Depends, FastAPI
+from fastapi_rbac import (
+    RBACAuthz, RBACRouter, Global, Contextual, ContextualAuthz, RBACUser
+)
+
+# 1. Define your user model
+class User:
+    def __init__(self, user_id: str, roles: set[str]):
+        self.user_id = user_id
+        self.roles = roles
+
+# 2. Define role permissions
+PERMISSIONS = {
+    "admin": {
+        Global("report:*"),         # Admin can do anything with reports
+    },
+    "viewer": {
+        Contextual("report:read"),  # Viewer needs context check
+    },
+}
+
+# 3. Create a context check (for contextual permissions)
+# All __init__ params are injected by FastAPI's DI system
+class ReportAccessContext(ContextualAuthz[User]):
+    def __init__(
+        self,
+        report_id: int,  # <-- Injected from path parameter
+        user: Annotated[User, Depends(RBACUser)],
+    ):
+        self.user = user
+        self.report_id = report_id
+
+    async def has_permissions(self) -> bool:
+        # Your logic: check if user can access this specific report
+        allowed_reports = {1, 2, 3}  # e.g., query from database
+        return self.report_id in allowed_reports
+
+# 4. Create your app and 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,
+    ui_path="/_rbac",  # Optional: mount visualization UI
+)
+
+# 5. Create protected routes
+router = RBACRouter(permissions={"report:read"}, contexts=[ReportAccessContext])
+
+@router.get("/reports/{report_id}")
+async def get_report(report_id: int):
+    return {"report_id": report_id}
+
+@router.post("/reports", permissions={"report:create"})  # Override permissions
+async def create_report():
+    return {"id": "new-report"}
+
+app.include_router(router, prefix="/api")
+```
+
+## Permission Scopes
+
+Permissions can be granted with two scopes:
+
+### Global Scope
+
+```python
+Global("report:read")
+```
+
+Global permissions **bypass context checks entirely**. If a user has a global permission, they can access the resource without any additional validation. Use this for admin roles or service accounts that need unrestricted access.
+
+### Contextual Scope
+
+```python
+Contextual("report:read")
+```
+
+Contextual permissions **require context checks to pass**. The user must have the permission AND the context check must return `True`. Use this for regular users who should only access resources they own or are members of.
+
+### Example
+
+```python
+PERMISSIONS = {
+    "admin": {
+        Global("report:*"),         # Can access ALL reports, no questions asked
+    },
+    "user": {
+        Contextual("report:read"),  # Can only read reports they have access to
+        Contextual("report:create"),
+    },
+}
+```
+
+## 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.).
+
+```python
+class ReportAccessContext(ContextualAuthz[User]):
+    def __init__(
+        self,
+        report_id: int,  # Injected from path parameter
+        user: Annotated[User, Depends(RBACUser)],
+        db: Annotated[AsyncSession, Depends(get_db)],  # Database session
+    ):
+        self.user = user
+        self.report_id = report_id
+        self.db = db
+
+    async def has_permissions(self) -> bool:
+        # Query database to check if user can access this report
+        report = await self.db.get(Report, self.report_id)
+        return report is not None and report.owner_id == self.user.user_id
+```
+
+## Authorization Flow
+
+When a request hits an RBAC-protected endpoint:
+
+```
+1. Authentication
+   └── user_dependency runs → User object available
+
+2. Permission Check
+   └── Does user have ANY grant (global or contextual) for required permission?
+       ├── No  → 403 Forbidden
+       └── Yes → Continue
+
+3. Scope Evaluation
+   └── Is the grant Global?
+       ├── Yes → Access granted (skip context checks)
+       └── No  → Continue to context checks
+
+4. Context Checks (only for Contextual grants)
+   └── Run all context classes via FastAPI DI
+       └── Do ALL contexts return True?
+           ├── No  → 403 Forbidden
+           └── Yes → Access granted
+
+5. Endpoint Handler Executes
+```
+
+## Wildcard Permissions
+
+Use wildcards to grant multiple permissions at once:
+
+| Grant | Implies |
+|-------|---------|
+| `*` | Everything |
+| `report:*` | `report:read`, `report:create`, `report:delete`, etc. |
+| `report:metrics:*` | `report:metrics:view`, `report:metrics:export`, etc. |
+
+```python
+PERMISSIONS = {
+    "admin": {Global("*")},              # Full access to everything
+    "reporter": {Global("report:*")},    # Full access to reports only
+}
+```
+
+## Running the Example
+
+A complete runnable example is included in the `examples/` directory:
+
+```bash
+# Install dependencies
+pip install fastapi-rbac-authz uvicorn
+
+# Run the example
+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
+
+### Test with different users
+
+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
+
+# 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)
+
+# 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)
+```
+
+## Visualization UI
+
+Mount the built-in visualization UI to explore your authorization schema:
+
+```python
+RBACAuthz(
+    app,
+    # ...
+    ui_path="/_rbac",
+)
+```
+
+Visit `/_rbac` to see an interactive graph showing:
+- **Roles** and their permission grants
+- **Permissions** with scope indicators (global/contextual)
+- **Endpoints** and their required permissions
+- **Context checks** and which endpoints use them
+
+Double-click any node to isolate and explore its relationships.
+
+### Screenshots
+
+**Full authorization graph**
+
+![Full Graph](https://github.com/user-attachments/assets/912826a4-63a6-4865-8ac7-707ce2746033)
+
+**Role isolation view** - double-click a role to see what it can access
+
+![Role Isolation](https://github.com/user-attachments/assets/392b8d06-aa10-433a-a7bf-bce1af02d9df)
+
+**Endpoint isolation view** - double-click an endpoint to see who can access it
+
+![Endpoint Isolation](https://github.com/user-attachments/assets/b0357fe1-d265-4aed-a4e3-ee439a370c46)