roleflow 0.1.1__tar.gz

roleflow-0.1.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: roleflow
+Version: 0.1.1
+Summary: A lightweight, hassle-free and production-ready RBAC (Role-Based Access Control) library.
+Project-URL: Homepage, https://github.com/developer/easy-rbac
+Author-email: sougata <sougatachongder8@gmail.com>
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: test
+Requires-Dist: fastapi; extra == 'test'
+Requires-Dist: httpx; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Easy RBAC
+
+A lightweight, production-ready Role-Based Access Control (RBAC) package for Python, designed to be simple, fast, and framework-agnostic, while featuring seamless integration out-of-the-box for FastAPI.
+
+## Features
+- **Generic RBAC Engine**: Easily verify permissions using wildcards (`*`, `table.*`) or exact matches.
+- **Pydantic Validation**: Strong typing and validation for your Role and Permission schemas.
+- **FastAPI Integration**: Native `RBACGuard` dependency injection for secure and hassle-free route protection.
+
+## Installation
+
+```bash
+pip install easy-rbac
+```
+
+To install with FastAPI dependencies:
+```bash
+pip install easy-rbac[fastapi]
+```
+
+## Quick Start
+
+### 1. Define your Roles
+```python
+from easy_rbac import Role, RBACEngine
+
+roles = [
+    Role(id=1, name="ROLE_ADMIN", permissions=["*"]),
+    Role(id=2, name="ROLE_STUDENT", permissions=["profile.read", "profile.edit", "course.read"]),
+    Role(id=3, name="ROLE_HOD", permissions=["course.*", "leave.approve"])
+]
+
+engine = RBACEngine(roles=roles)
+```
+
+### 2. Fetch Roles from a Database (Dynamic Loading)
+You don't have to provide all roles upfront. You can hook into your Database ORM by passing a `role_loader` callback function to the engine:
+
+```python
+from easy_rbac import Role, RBACEngine
+
+# Simulated database fetch function (e.g. using SQLAlchemy)
+def db_role_loader(role_name: str) -> Role:
+    # 1. Query your database here using SQLAlchemy
+    # db_record = session.query(DbRole).filter(DbRole.name == role_name).first()
+    # 2. Convert database result into the generic easy_rbac.Role schema
+    # return Role(id=db_record.id, name=db_record.name, permissions=db_record.permissions)
+    pass
+
+# Initialize engine without static roles
+engine = RBACEngine(role_loader=db_role_loader)
+
+# The engine will automatically call db_role_loader("ROLE_ADMIN") and cache it!
+engine.is_granted("ROLE_ADMIN", "table1.read")
+```
+
+### 3. Check Permissions
+```python
+# Returns True
+engine.is_granted("ROLE_ADMIN", "anything.you.want") 
+engine.is_granted("ROLE_STUDENT", "profile.read")
+engine.is_granted("ROLE_HOD", "course.create")
+
+# Returns False
+engine.is_granted("ROLE_STUDENT", "course.create")
+```
+
+### 4. FastAPI Integration
+```python
+from fastapi import FastAPI, Depends
+from easy_rbac.fastapi import RBACGuard
+
+app = FastAPI()
+
+# A mock function to get the current user's role
+def get_current_user_role() -> str:
+    return "ROLE_STUDENT"
+
+guard = RBACGuard(engine=engine, role_provider=get_current_user_role)
+
+@app.get("/courses", dependencies=[Depends(guard("course.read"))])
+def list_courses():
+    return {"message": "You can read courses!"}
+```

roleflow-0.1.1/README.md

@@ -0,0 +1,84 @@
+# Easy RBAC
+
+A lightweight, production-ready Role-Based Access Control (RBAC) package for Python, designed to be simple, fast, and framework-agnostic, while featuring seamless integration out-of-the-box for FastAPI.
+
+## Features
+- **Generic RBAC Engine**: Easily verify permissions using wildcards (`*`, `table.*`) or exact matches.
+- **Pydantic Validation**: Strong typing and validation for your Role and Permission schemas.
+- **FastAPI Integration**: Native `RBACGuard` dependency injection for secure and hassle-free route protection.
+
+## Installation
+
+```bash
+pip install easy-rbac
+```
+
+To install with FastAPI dependencies:
+```bash
+pip install easy-rbac[fastapi]
+```
+
+## Quick Start
+
+### 1. Define your Roles
+```python
+from easy_rbac import Role, RBACEngine
+
+roles = [
+    Role(id=1, name="ROLE_ADMIN", permissions=["*"]),
+    Role(id=2, name="ROLE_STUDENT", permissions=["profile.read", "profile.edit", "course.read"]),
+    Role(id=3, name="ROLE_HOD", permissions=["course.*", "leave.approve"])
+]
+
+engine = RBACEngine(roles=roles)
+```
+
+### 2. Fetch Roles from a Database (Dynamic Loading)
+You don't have to provide all roles upfront. You can hook into your Database ORM by passing a `role_loader` callback function to the engine:
+
+```python
+from easy_rbac import Role, RBACEngine
+
+# Simulated database fetch function (e.g. using SQLAlchemy)
+def db_role_loader(role_name: str) -> Role:
+    # 1. Query your database here using SQLAlchemy
+    # db_record = session.query(DbRole).filter(DbRole.name == role_name).first()
+    # 2. Convert database result into the generic easy_rbac.Role schema
+    # return Role(id=db_record.id, name=db_record.name, permissions=db_record.permissions)
+    pass
+
+# Initialize engine without static roles
+engine = RBACEngine(role_loader=db_role_loader)
+
+# The engine will automatically call db_role_loader("ROLE_ADMIN") and cache it!
+engine.is_granted("ROLE_ADMIN", "table1.read")
+```
+
+### 3. Check Permissions
+```python
+# Returns True
+engine.is_granted("ROLE_ADMIN", "anything.you.want") 
+engine.is_granted("ROLE_STUDENT", "profile.read")
+engine.is_granted("ROLE_HOD", "course.create")
+
+# Returns False
+engine.is_granted("ROLE_STUDENT", "course.create")
+```
+
+### 4. FastAPI Integration
+```python
+from fastapi import FastAPI, Depends
+from easy_rbac.fastapi import RBACGuard
+
+app = FastAPI()
+
+# A mock function to get the current user's role
+def get_current_user_role() -> str:
+    return "ROLE_STUDENT"
+
+guard = RBACGuard(engine=engine, role_provider=get_current_user_role)
+
+@app.get("/courses", dependencies=[Depends(guard("course.read"))])
+def list_courses():
+    return {"message": "You can read courses!"}
+```

roleflow-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roleflow"
+version = "0.1.1"
+description = "A lightweight, hassle-free and production-ready RBAC (Role-Based Access Control) library."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "sougata", email = "sougatachongder8@gmail.com" }
+]
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0"]
+test = ["pytest", "pytest-asyncio", "fastapi", "httpx"]
+
+[project.urls]
+Homepage = "https://github.com/developer/easy-rbac"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easy_rbac"]

roleflow-0.1.1/src/easy_rbac/__init__.py

@@ -0,0 +1,4 @@
+from .models import Role
+from .core import RBACEngine
+
+__all__ = ["Role", "RBACEngine"]

roleflow-0.1.1/src/easy_rbac/core.py

@@ -0,0 +1,65 @@
+from typing import List, Optional, Dict, Callable
+from easy_rbac.models import Role
+
+class RBACEngine:
+    """
+    Core engine for Role-Based Access Control verification.
+    """
+    def __init__(self, roles: Optional[List[Role]] = None, role_loader: Optional[Callable[[str], Optional[Role]]] = None):
+        """
+        Initialize the RBAC engine.
+        :param roles: Optional list of Role models.
+        :param role_loader: Optional callback to dynamically fetch a role (e.g., from a database) if it's not found in memory.
+        """
+        self._roles: Dict[str, Role] = {}
+        self.role_loader = role_loader
+        if roles:
+            for role in roles:
+                self.add_role(role)
+
+    def add_role(self, role: Role) -> None:
+        """Register a new role in the engine."""
+        self._roles[role.name] = role
+
+    def get_role(self, role_name: str) -> Optional[Role]:
+        """Retrieve a registered role by its name. Falls back to role_loader if configured."""
+        if role_name in self._roles:
+            return self._roles[role_name]
+        
+        # If not cached and we have a database/dynamic loader configured
+        if self.role_loader:
+            role = self.role_loader(role_name)
+            if role:
+                self.add_role(role)  # Cache it for future queries
+                return role
+                
+        return None
+
+    def is_granted(self, role_name: str, required_permission: str) -> bool:
+        """
+        Verify if a role has the required permission.
+        
+        :param role_name: The name of the role trying to access the resource.
+        :param required_permission: The permission string required for access (e.g. 'table1.read').
+        :return: True if access is granted, False otherwise.
+        """
+        role = self.get_role(role_name)
+        if not role:
+            return False
+
+        for permit in role.permissions:
+            # 1. Root wildcard match
+            if permit == "*":
+                return True
+            
+            # 2. Exact match
+            if permit == required_permission:
+                return True
+            
+            # 3. Domain wildcard match (e.g., "table1.*" matches "table1.read")
+            if permit.endswith(".*"):
+                domain = permit[:-2]  # remove the '.*'
+                if required_permission.startswith(f"{domain}."):
+                    return True
+
+        return False

roleflow-0.1.1/src/easy_rbac/fastapi.py

@@ -0,0 +1,39 @@
+from typing import Callable, Optional, Any
+from easy_rbac.core import RBACEngine
+
+try:
+    from fastapi import HTTPException, status
+    from fastapi.requests import Request
+    HAS_FASTAPI = True
+except ImportError:
+    HAS_FASTAPI = False
+
+class RBACGuard:
+    """
+    A dependency injection factory for FastAPI to secure routes using Role-Based Access Control.
+    """
+    def __init__(self, engine: RBACEngine, role_provider: Callable[..., str]):
+        """
+        Initialize the RBACGuard.
+        
+        :param engine: An instance of RBACEngine.
+        :param role_provider: A FastAPI dependency (callable) that resolves and returns the current user's role name as a string.
+        """
+        if not HAS_FASTAPI:
+            raise ImportError("FastAPI is not installed. Please install easy-rbac[fastapi] to use RBACGuard.")
+        
+        self.engine = engine
+        self.role_provider = role_provider
+
+    def __call__(self, required_permission: str):
+        """
+        Returns a FastAPI dependency function to check for a specific permission.
+        """
+        def dependency(role_name: str = __import__("fastapi").Depends(self.role_provider)):
+            if not self.engine.is_granted(role_name, required_permission):
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Access denied: Requires permission '{required_permission}'"
+                )
+            return role_name
+        return dependency

roleflow-0.1.1/src/easy_rbac/models.py

@@ -0,0 +1,17 @@
+from typing import List, Union
+from pydantic import BaseModel, Field
+
+class Role(BaseModel):
+    """
+    Data model representing an RBAC Role.
+    """
+    id: Union[int, str] = Field(..., description="Unique identifier for the role.")
+    name: str = Field(..., description="Unique name of the role (e.g., 'ROLE_ADMIN').")
+    permissions: List[str] = Field(
+        default_factory=list, 
+        description="List of permission strings. Supports exact match and wildcards (e.g. '*' or 'domain.*')."
+    )
+
+    model_config = {
+        "frozen": True
+    }

roleflow-0.1.1/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for easy-rbac

roleflow-0.1.1/tests/test_core.py

@@ -0,0 +1,40 @@
+import pytest
+from easy_rbac.models import Role
+from easy_rbac.core import RBACEngine
+
+@pytest.fixture
+def rbac_engine():
+    roles = [
+        Role(id=1, name="ROLE_ADMIN", permissions=["*"]),
+        Role(id=2, name="ROLE_STUDENT", permissions=["profile.read", "profile.edit", "course.read"]),
+        Role(id=3, name="ROLE_HOD", permissions=["course.*", "leave.approve"])
+    ]
+    return RBACEngine(roles=roles)
+
+def test_admin_root_access(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_ADMIN", "anything") is True
+    assert rbac_engine.is_granted("ROLE_ADMIN", "table.read") is True
+
+def test_student_exact_match(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_STUDENT", "profile.read") is True
+    assert rbac_engine.is_granted("ROLE_STUDENT", "profile.edit") is True
+    assert rbac_engine.is_granted("ROLE_STUDENT", "course.read") is True
+
+def test_student_denied_access(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_STUDENT", "course.create") is False
+    assert rbac_engine.is_granted("ROLE_STUDENT", "leave.approve") is False
+
+def test_hod_wildcard_domain_access(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_HOD", "course.create") is True
+    assert rbac_engine.is_granted("ROLE_HOD", "course.delete") is True
+    assert rbac_engine.is_granted("ROLE_HOD", "course.anything") is True
+
+def test_hod_exact_match(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_HOD", "leave.approve") is True
+
+def test_hod_denied_access(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_HOD", "profile.read") is False
+    assert rbac_engine.is_granted("ROLE_HOD", "leave.reject") is False
+
+def test_unknown_role(rbac_engine):
+    assert rbac_engine.is_granted("ROLE_UNKNOWN", "anything") is False

roleflow-0.1.1/tests/test_fastapi.py

@@ -0,0 +1,54 @@
+import pytest
+from fastapi import FastAPI, Depends
+from fastapi.testclient import TestClient
+from easy_rbac.models import Role
+from easy_rbac.core import RBACEngine
+from easy_rbac.fastapi import RBACGuard
+
+# Setup simple roles
+roles = [
+    Role(id=1, name="ROLE_STUDENT", permissions=["profile.read"]),
+    Role(id=2, name="ROLE_ADMIN", permissions=["*"])
+]
+engine = RBACEngine(roles=roles)
+
+# Mocked state
+current_user_role = "ROLE_STUDENT"
+
+def get_current_role() -> str:
+    return current_user_role
+
+guard = RBACGuard(engine=engine, role_provider=get_current_role)
+
+app = FastAPI()
+
+@app.get("/profile", dependencies=[Depends(guard("profile.read"))])
+def get_profile():
+    return {"status": "ok"}
+
+@app.get("/admin/settings", dependencies=[Depends(guard("settings.edit"))])
+def edit_settings():
+    return {"status": "ok"}
+
+client = TestClient(app)
+
+def test_fastapi_allowed_access():
+    global current_user_role
+    current_user_role = "ROLE_STUDENT"
+    response = client.get("/profile")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+def test_fastapi_denied_access():
+    global current_user_role
+    current_user_role = "ROLE_STUDENT"
+    response = client.get("/admin/settings")
+    assert response.status_code == 403
+    assert response.json() == {"detail": "Access denied: Requires permission 'settings.edit'"}
+
+def test_fastapi_admin_access():
+    global current_user_role
+    current_user_role = "ROLE_ADMIN"
+    response = client.get("/admin/settings")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

roleflow-0.1.1/tests/test_loader.py

@@ -0,0 +1,33 @@
+import pytest
+from easy_rbac.models import Role
+from easy_rbac.core import RBACEngine
+
+# Simulated Database
+MOCK_DB = {
+    "ROLE_SUPER_ADMIN": {"id": 99, "name": "ROLE_SUPER_ADMIN", "permissions": ["*"]},
+    "ROLE_GUEST": {"id": 100, "name": "ROLE_GUEST", "permissions": ["guest.read"]}
+}
+
+def db_role_loader(role_name: str) -> Role | None:
+    """Mock DB loader that fetches the role by name."""
+    record = MOCK_DB.get(role_name)
+    if record:
+        return Role(**record)
+    return None
+
+def test_dynamic_role_loading():
+    # We init without passing any static roles
+    engine = RBACEngine(role_loader=db_role_loader)
+    
+    # It should dynamically fetch ROLE_SUPER_ADMIN from MOCK_DB
+    assert engine.is_granted("ROLE_SUPER_ADMIN", "anything.you.want") is True
+    
+    # It should cache the role after the first load
+    assert "ROLE_SUPER_ADMIN" in engine._roles
+    
+    # Test Guest
+    assert engine.is_granted("ROLE_GUEST", "guest.read") is True
+    assert engine.is_granted("ROLE_GUEST", "admin.write") is False
+    
+    # Test unknown role
+    assert engine.is_granted("ROLE_UNKNOWN", "anything") is False