permissions2fast-fastapi 0.1.0__py3-none-any.whl

permissions2fast_fastapi/__init__.py

@@ -0,0 +1,26 @@
+"""
+permissions2fast-fastapi
+
+Complete RBAC (Role-Based Access Control) system for FastAPI applications.
+Provides role management, permission checking, and user-role assignments.
+"""
+
+__version__ = "0.1.0"
+
+from .models.role_model import Role
+from .models.permission_model import Permission
+from .models.permission_category_model import PermissionCategory
+from .models.route_model import Route
+from .models.user_role_model import UserRole
+from .models.permission_assignment_model import PermissionAssignment
+from .models.permission_route_model import PermissionRoute
+
+__all__ = [
+    "Role",
+    "Permission",
+    "PermissionCategory",
+    "Route",
+    "UserRole",
+    "PermissionAssignment",
+    "PermissionRoute",
+]

permissions2fast_fastapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

permissions2fast_fastapi/dependencies.py

@@ -0,0 +1,123 @@
+"""
+FastAPI Dependencies
+
+Dependencies for protecting routes based on roles and permissions.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# Import from oauth2fast-fastapi directly
+from oauth2fast_fastapi.dependencies import get_current_verified_user, get_auth_session
+from oauth2fast_fastapi import User
+
+from .services import access_service, role_service
+
+
+def has_role(
+    role_name: str,
+):
+    """
+    Dependency to require a specific role.
+    
+    Usage:
+        @app.get("/admin")
+        def admin_route(user: User = Depends(has_role("admin"))):
+            ...
+    """
+    async def _has_role(
+        request: Request,
+        user: Annotated[User, Depends(get_current_verified_user)],
+        session: Annotated[AsyncSession, Depends(get_auth_session)],
+    ) -> User:
+        tenant_id = get_tenant_id(request)
+        user_roles = await role_service.list_user_roles(user.id, session, tenant_id=tenant_id)
+        
+        has_required = any(r.name == role_name for r in user_roles)
+        
+        if not has_required:
+             raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Missing required role: {role_name}",
+            )
+        
+        return user
+
+    return _has_role
+
+
+def get_tenant_id(request: Request) -> int | None:
+    """
+    Extract tenant_id from request.
+    Priority:
+    1. request.state.tenant_id (injected by external middleware)
+    2. X-Tenant-ID header
+    """
+    from .settings import settings
+    if not settings.enable_tenancy:
+        return None
+
+    # First check state (injected by middleware)
+    if hasattr(request.state, "tenant_id") and request.state.tenant_id:
+        try:
+            return int(request.state.tenant_id)
+        except ValueError:
+            pass
+
+    # Fallback to header
+    header_tenant = request.headers.get("X-Tenant-ID")
+    if header_tenant:
+         try:
+             return int(header_tenant)
+         except ValueError:
+             pass
+             
+    return None
+
+
+def has_permission(
+    permission_route: str | None = None,
+    method: str | None = None,
+):
+    """
+    Dependency to require permission for a route.
+    
+    If params are None, verifies access to the *current* request path and method.
+    
+    Usage:
+        @app.get("/items")
+        def items(user: User = Depends(has_permission())): 
+            # Checks if user can GET /items
+            ...
+            
+        @app.get("/items")
+        def items(user: User = Depends(has_permission(permission_route="/api/items", method="GET"))):
+            ...
+    """
+    async def _has_permission(
+        request: Request,
+        user: Annotated[User, Depends(get_current_verified_user)],
+        session: Annotated[AsyncSession, Depends(get_auth_session)],
+    ) -> User:
+        # Determine what to check
+        route_to_check = permission_route or request.url.path
+        method_to_check = method or request.method
+        
+        # Extract tenant context
+        tenant_id = get_tenant_id(request)
+        
+        is_allowed = await access_service.check_user_access(
+            user.id, route_to_check, method_to_check, session, tenant_id=tenant_id
+        )
+        
+        if not is_allowed:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not enough permissions to access this resource",
+            )
+            
+        return user
+
+    return _has_permission

permissions2fast_fastapi/models/__init__.py

@@ -0,0 +1,21 @@
+from .role_model import Role
+from .permission_model import Permission
+from .permission_category_model import PermissionCategory
+from .route_model import Route
+from .user_role_model import UserRole
+from .permission_assignment_model import PermissionAssignment
+from .permission_route_model import PermissionRoute
+from .tenant_model import Tenant
+from .user_tenant_role_model import UserTenantRole
+
+__all__ = [
+    "Role",
+    "Permission",
+    "PermissionCategory",
+    "Route",
+    "UserRole",
+    "PermissionAssignment",
+    "PermissionRoute",
+    "Tenant",
+    "UserTenantRole",
+]

permissions2fast_fastapi/models/permission_assignment_model.py

@@ -0,0 +1,13 @@
+from sqlmodel import Field, SQLModel
+from oauth2fast_fastapi.models import AuthModel
+
+class PermissionAssignment(AuthModel, table=True):
+    """
+    Polymorphic Permission Assignment for RBAC.
+    Description: Assigns a permission directly to an entity (e.g. User or Role).
+    """
+    __tablename__ = "permission_assignments"
+
+    permission_id: int = Field(primary_key=True, foreign_key="permissions.id")
+    entity_type: str = Field(primary_key=True, index=True) # e.g., "User", "Team"
+    entity_id: int = Field(primary_key=True, index=True)

permissions2fast_fastapi/models/permission_category_model.py

@@ -0,0 +1,18 @@
+from sqlmodel import Field, SQLModel, Relationship
+from typing import Optional, List
+
+# Forward reference for relationship
+from oauth2fast_fastapi.models import AuthModel
+
+class PermissionCategory(AuthModel, table=True):
+    """
+    Permission Category definition for RBAC.
+    Description: Groups related permissions together.
+    """
+    __tablename__ = "permission_categories"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True, unique=True)
+    
+    # Relationships
+    # permissions: List["Permission"] = Relationship(back_populates="category")

permissions2fast_fastapi/models/permission_model.py

@@ -0,0 +1,17 @@
+from sqlmodel import Field, SQLModel, Relationship
+from typing import Optional
+from oauth2fast_fastapi.models import AuthModel
+
+class Permission(AuthModel, table=True):
+    """
+    Permission definition for RBAC.
+    Description: Represents a specific action or access right.
+    """
+    __tablename__ = "permissions"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True, unique=True)
+    permission_category_id: int = Field(foreign_key="permission_categories.id")
+    
+    # Relationships
+    # category: "PermissionCategory" = Relationship(back_populates="permissions")

permissions2fast_fastapi/models/permission_route_model.py

@@ -0,0 +1,13 @@
+from sqlmodel import Field, SQLModel
+from oauth2fast_fastapi.models import AuthModel
+
+class PermissionRoute(AuthModel, table=True):
+    """
+    Permission Route mapping for RBAC.
+    Description: Maps permissions to specific API routes.
+    """
+    __tablename__ = "permission_routes"
+
+    id: int | None = Field(default=None, primary_key=True)
+    permission_id: int = Field(foreign_key="permissions.id")
+    route_id: int = Field(foreign_key="routes.id")

permissions2fast_fastapi/models/role_model.py

@@ -0,0 +1,21 @@
+from sqlmodel import BigInteger, Column, Field
+from sqlmodel import BigInteger, Column, Field, SQLModel
+
+from oauth2fast_fastapi.models import AuthModel
+
+
+class Role(AuthModel, table=True):
+    """
+    Role definition for RBAC.
+    Description: Role model
+    """
+
+    __tablename__ = "roles"
+
+    id: int = Field(
+        default=None, sa_column=Column(BigInteger, index=True, primary_key=True)
+    )
+    name: str = Field(index=True, unique=True)
+    description: str | None = Field(default=None)
+    is_active: bool = Field(default=True)
+

permissions2fast_fastapi/models/route_model.py

@@ -0,0 +1,14 @@
+from sqlmodel import Field, SQLModel
+from typing import Optional
+from oauth2fast_fastapi.models import AuthModel
+
+class Route(AuthModel, table=True):
+    """
+    Route definition for RBAC.
+    Description: Represents an API endpoint or accessible resource path.
+    """
+    __tablename__ = "routes"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True, unique=True) # The path
+    is_active: bool = Field(default=True)

permissions2fast_fastapi/models/tenant_model.py

@@ -0,0 +1,16 @@
+from sqlmodel import Field, SQLModel
+from oauth2fast_fastapi.models import AuthModel
+
+
+class Tenant(AuthModel, table=True):
+    """
+    Tenant definition for Multi-tenant RBAC.
+    Description: Represents an isolated organization or tenant.
+    """
+    __tablename__ = "tenants"
+
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    schema_name: str | None = Field(default=None, description="DB Schema name if applicable")
+    db_url: str | None = Field(default=None, description="External DB URL if applicable")
+    is_active: bool = Field(default=True)

permissions2fast_fastapi/models/user_role_model.py

@@ -0,0 +1,12 @@
+from sqlmodel import Field, SQLModel
+from oauth2fast_fastapi.models import AuthModel
+
+class UserRole(AuthModel, table=True):
+    """
+    User Role mapping for RBAC.
+    Description: Maps users to their assigned roles.
+    """
+    __tablename__ = "user_role"
+
+    role_id: int = Field(primary_key=True, foreign_key="roles.id")
+    user_id: int = Field(primary_key=True, index=True, foreign_key="users.id")

permissions2fast_fastapi/models/user_tenant_role_model.py

@@ -0,0 +1,15 @@
+from sqlmodel import Field, SQLModel
+from oauth2fast_fastapi.models import AuthModel
+
+
+class UserTenantRole(AuthModel, table=True):
+    """
+    Tenant-specific Role mapping for RBAC.
+    Description: Maps users to roles within a specific tenant context.
+    """
+    __tablename__ = "user_tenant_roles"
+
+    id: int | None = Field(default=None, primary_key=True)
+    user_id: int = Field(index=True, foreign_key="users.id")
+    tenant_id: int = Field(foreign_key="tenants.id", index=True)
+    role_id: int = Field(foreign_key="roles.id", index=True)

permissions2fast_fastapi/routers/__init__.py

@@ -0,0 +1,5 @@
+from .permissions_router import router as permissions_router
+from .roles_router import router as roles_router
+from .routes_router import router as routes_router
+
+__all__ = ["permissions_router", "roles_router", "routes_router"]

permissions2fast_fastapi/routers/permissions_router.py

@@ -0,0 +1,191 @@
+"""
+Permission Management Router
+
+Endpoints for managing permissions, categories, and assignments.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..schemas.permission_schema import (
+    PermissionCreate,
+    PermissionRead,
+    PermissionUpdate,
+    UserPermissionCreate,
+    UserPermissionRead,
+    PermissionRouteCreate
+)
+from ..schemas.permission_category_schema import (
+    PermissionCategoryCreate,
+    PermissionCategoryRead
+)
+from ..services import permission_service
+from oauth2fast_fastapi.dependencies import get_auth_session
+
+router = APIRouter(
+    prefix="/permissions",
+    tags=["Permissions"],
+)
+
+
+# Categories
+
+
+@router.post("/categories", response_model=PermissionCategoryRead)
+async def create_category(
+    category_data: PermissionCategoryCreate,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Create a new permission category."""
+    try:
+        category = await permission_service.create_category(category_data, session)
+        return PermissionCategoryRead.model_validate(category)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/categories", response_model=list[PermissionCategoryRead])
+async def list_categories(
+    session: AsyncSession = Depends(get_auth_session),
+    skip: int = 0,
+    limit: int = 100,
+):
+    """List all categories."""
+    categories = await permission_service.list_categories(session, skip, limit)
+    return [PermissionCategoryRead.model_validate(c) for c in categories]
+
+
+# Permissions CRUD
+
+
+@router.post("/", response_model=PermissionRead)
+async def create_permission(
+    permission_data: PermissionCreate,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Create a new permission."""
+    try:
+        permission = await permission_service.create_permission(
+            permission_data, session
+        )
+        return PermissionRead.model_validate(permission)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/", response_model=list[PermissionRead])
+async def list_permissions(
+    session: AsyncSession = Depends(get_auth_session),
+    skip: int = 0,
+    limit: int = 100,
+):
+    """List all permissions."""
+    permissions = await permission_service.list_permissions(session, skip, limit)
+    return [PermissionRead.model_validate(p) for p in permissions]
+
+
+@router.get("/{permission_id}", response_model=PermissionRead)
+async def get_permission(
+    permission_id: int,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Get permission by ID."""
+    permission = await permission_service.get_permission(permission_id, session)
+    if not permission:
+        raise HTTPException(status_code=404, detail="Permission not found")
+    return PermissionRead.model_validate(permission)
+
+
+@router.put("/{permission_id}", response_model=PermissionRead)
+async def update_permission(
+    permission_id: int,
+    permission_data: PermissionUpdate,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Update a permission."""
+    permission = await permission_service.update_permission(
+        permission_id, permission_data, session
+    )
+    if not permission:
+        raise HTTPException(status_code=404, detail="Permission not found")
+    return PermissionRead.model_validate(permission)
+
+
+@router.delete("/{permission_id}")
+async def delete_permission(
+    permission_id: int,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Delete a permission."""
+    success = await permission_service.delete_permission(permission_id, session)
+    if not success:
+        raise HTTPException(status_code=404, detail="Permission not found")
+    return {"message": "Permission deleted successfully"}
+
+
+# Permission Routes (Link)
+
+
+@router.post("/{permission_id}/routes")
+async def add_permission_route(
+    permission_id: int,
+    route_data: PermissionRouteCreate,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Link a permission to a route."""
+    # Ensure permission_id matches URL
+    if route_data.permission_id != permission_id:
+         route_data.permission_id = permission_id
+    
+    try:
+        await permission_service.add_permission_route(
+            permission_id, route_data.route_id, session
+        )
+        return {"message": "Route linked to permission successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# User Permissions (Direct Assignment)
+
+
+@router.post("/assign", response_model=UserPermissionRead)
+async def assign_user_permission(
+    assignment_data: UserPermissionCreate,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Assign a permission directly to a user."""
+    try:
+        user_perm = await permission_service.assign_user_permission(
+            assignment_data.user_id, assignment_data.permission_id, session
+        )
+        return UserPermissionRead(
+            permission_id=user_perm.permission_id,
+            entity_type=user_perm.entity_type,
+            entity_id=user_perm.entity_id
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/user/{user_id}", response_model=list[PermissionRead])
+async def list_user_permissions(
+    user_id: int,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """List all permissions assigned directly to a user."""
+    permissions = await permission_service.list_user_permissions(user_id, session)
+    return [PermissionRead.model_validate(p) for p in permissions]
+
+
+@router.delete("/user/{user_id}/permission/{permission_id}")
+async def remove_user_permission(
+    user_id: int,
+    permission_id: int,
+    session: AsyncSession = Depends(get_auth_session),
+):
+    """Remove a direct permission from a user."""
+    success = await permission_service.remove_user_permission(user_id, permission_id, session)
+    if not success:
+        raise HTTPException(status_code=404, detail="User permission assignment not found")
+    return {"message": "Permission removed from user successfully"}