simple-module-permissions 0.0.1__tar.gz

simple_module_permissions-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_permissions-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+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.

simple_module_permissions-0.0.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: simple_module_permissions
+Version: 0.0.1
+Summary: RBAC primitives — roles, permissions, @require_permission decorator, admin UI for simple_module
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorization,permissions,rbac,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Requires-Dist: simple-module-users==0.0.1
+Description-Content-Type: text/markdown
+
+# simple_module_permissions
+
+Role-based access control (RBAC) for [simple_module](https://github.com/antosubash/simple_module_python) apps. Users get roles, roles carry permissions, and route handlers declare required permissions at the decorator or dependency layer.
+
+Pre-wired into any app scaffolded with `simple-module new`.
+
+## Install
+
+```bash
+pip install simple_module_permissions
+```
+
+## What it provides
+
+- `Role` and `Permission` SQLModel tables, seeded from module-registered defaults.
+- `@require_permission("orders.read")` route decorator and `HasPermission("...")` dependency.
+- Admin UI at `/permissions/admin` for assigning roles to users.
+- `register_permissions()` hook — every module declares its permission strings at boot, the registry dedupes and persists them.
+
+## Usage
+
+Declare permissions at module boot:
+
+```python
+# modules/orders/orders/module.py
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders")
+
+    def register_permissions(self):
+        return ["orders.read", "orders.write"]
+```
+
+Guard a route:
+
+```python
+from fastapi import APIRouter, Depends
+from permissions.deps import HasPermission   # type: ignore[import-not-found]
+
+router = APIRouter()
+
+
+@router.get("/orders", dependencies=[Depends(HasPermission("orders.read"))])
+async def list_orders(): ...
+```
+
+Admin flow: navigate to `/permissions/admin`, create a role, assign permissions, assign the role to users.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_users`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_permissions-0.0.1/README.md

@@ -0,0 +1,54 @@
+# simple_module_permissions
+
+Role-based access control (RBAC) for [simple_module](https://github.com/antosubash/simple_module_python) apps. Users get roles, roles carry permissions, and route handlers declare required permissions at the decorator or dependency layer.
+
+Pre-wired into any app scaffolded with `simple-module new`.
+
+## Install
+
+```bash
+pip install simple_module_permissions
+```
+
+## What it provides
+
+- `Role` and `Permission` SQLModel tables, seeded from module-registered defaults.
+- `@require_permission("orders.read")` route decorator and `HasPermission("...")` dependency.
+- Admin UI at `/permissions/admin` for assigning roles to users.
+- `register_permissions()` hook — every module declares its permission strings at boot, the registry dedupes and persists them.
+
+## Usage
+
+Declare permissions at module boot:
+
+```python
+# modules/orders/orders/module.py
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders")
+
+    def register_permissions(self):
+        return ["orders.read", "orders.write"]
+```
+
+Guard a route:
+
+```python
+from fastapi import APIRouter, Depends
+from permissions.deps import HasPermission   # type: ignore[import-not-found]
+
+router = APIRouter()
+
+
+@router.get("/orders", dependencies=[Depends(HasPermission("orders.read"))])
+async def list_orders(): ...
+```
+
+Admin flow: navigate to `/permissions/admin`, create a role, assign permissions, assign the role to users.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_users`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_permissions-0.0.1/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/permissions",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Permissions module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

simple_module_permissions-0.0.1/permissions/__init__.py

@@ -0,0 +1 @@
+"""Permissions module."""

simple_module_permissions-0.0.1/permissions/constants.py

@@ -0,0 +1,13 @@
+"""Permission keys declared by this module.
+
+Centralised so `register_permissions`, endpoint guards, and tests all
+reference the same literal. Other modules that need to check one of these
+permissions should import the constant rather than duplicating the string.
+"""
+
+from __future__ import annotations
+
+PERMISSION_GROUP = "Permissions"
+
+PERM_VIEW = "permissions.view"
+PERM_MANAGE = "permissions.manage"

simple_module_permissions-0.0.1/permissions/contracts/__init__.py

@@ -0,0 +1,21 @@
+"""Permissions contracts — public interface for other modules."""
+
+from permissions.contracts.schemas import (
+    PermissionGroupOut,
+    RoleOut,
+    RolePermissionsOut,
+    RolePermissionsUpdate,
+    UserOut,
+    UserPermissionsOut,
+    UserPermissionsUpdate,
+)
+
+__all__ = [
+    "PermissionGroupOut",
+    "RoleOut",
+    "RolePermissionsOut",
+    "RolePermissionsUpdate",
+    "UserOut",
+    "UserPermissionsOut",
+    "UserPermissionsUpdate",
+]

simple_module_permissions-0.0.1/permissions/contracts/schemas.py

@@ -0,0 +1,65 @@
+"""SQLModel DTOs for the Permissions module."""
+
+from __future__ import annotations
+
+import uuid
+
+from pydantic import ConfigDict
+from sqlmodel import Field, SQLModel
+
+
+class PermissionGroupOut(SQLModel):
+    """A named group of related permission keys (one per module)."""
+
+    name: str
+    permissions: list[str]
+
+
+class RoleOut(SQLModel):
+    """A role as surfaced by the permissions admin UI."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    description: str | None = None
+
+
+class RolePermissionsOut(SQLModel):
+    """A role together with its currently assigned permission keys."""
+
+    role: RoleOut
+    permissions: list[str]
+
+
+class RolePermissionsUpdate(SQLModel):
+    """Replace the full set of permission keys assigned to a role."""
+
+    permissions: list[str] = Field(default_factory=list)
+
+
+class UserOut(SQLModel):
+    """A user as surfaced by the permissions admin UI."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    email: str
+    full_name: str | None = None
+
+
+class UserPermissionsOut(SQLModel):
+    """A user together with their direct and role-inherited permission keys."""
+
+    user: UserOut
+    roles: list[str]
+    direct: list[str]
+    """Keys granted directly to this user."""
+    inherited: list[str]
+    """Keys the user holds via any of their roles (excluding duplicates of ``direct``)."""
+
+
+class UserPermissionsUpdate(SQLModel):
+    """Replace the full set of permission keys granted directly to a user."""
+
+    permissions: list[str] = Field(default_factory=list)

simple_module_permissions-0.0.1/permissions/deps.py

@@ -0,0 +1,72 @@
+"""FastAPI dependencies for the Permissions module.
+
+In addition to the standard service wiring this module exports a
+:class:`RequiresPermission` dependency that honours *both* role-based
+and direct user grants — the framework's own
+:class:`simple_module_hosting.permissions.RequiresPermission` checks
+only roles, because the framework has no concept of user-direct grants.
+Endpoints that want users to be able to hold individual permissions on
+top of their roles should depend on this version instead.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import Depends, HTTPException, Request
+from simple_module_core.permissions import WILDCARD, PermissionRegistry
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from permissions.service import PermissionService
+
+
+def get_permission_registry(request: Request) -> PermissionRegistry:
+    return request.app.state.sm.permissions
+
+
+async def get_permission_service(
+    db: AsyncSession = Depends(get_db),
+    registry: PermissionRegistry = Depends(get_permission_registry),
+) -> PermissionService:
+    return PermissionService(db, registry)
+
+
+def assigned_by(request: Request) -> str | None:
+    """Authenticated user id string, for audit columns."""
+    user = getattr(request.state, "user", None)
+    return str(user.id) if user is not None else None
+
+
+class RequiresPermission:
+    """FastAPI dependency enforcing a permission across roles *and* user grants.
+
+    Behaves like the framework's ``simple_module_hosting.RequiresPermission``
+    but additionally consults the ``permissions_user_permission`` table, so
+    a direct grant on a single user takes effect without inventing a role.
+    """
+
+    def __init__(self, permission: str) -> None:
+        self.permission = permission
+
+    async def __call__(
+        self,
+        request: Request,
+        service: PermissionService = Depends(get_permission_service),
+    ) -> None:
+        user = getattr(request.state, "user", None)
+        if user is None:
+            raise HTTPException(status_code=401, detail="Authentication required")
+
+        role_perms: set[str] = getattr(request.state, "resolved_permissions", set()) or set()
+        if WILDCARD in role_perms or self.permission in role_perms:
+            return
+
+        direct = await service.get_user_direct_keys(uuid.UUID(str(user.id)))
+        if self.permission in direct:
+            return
+
+        raise HTTPException(
+            status_code=403,
+            detail=f"Permission required: {self.permission}",
+        )

simple_module_permissions-0.0.1/permissions/endpoints/api.py

@@ -0,0 +1,102 @@
+"""REST API endpoints for Permissions administration."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from permissions.constants import PERM_MANAGE, PERM_VIEW
+from permissions.contracts.schemas import (
+    PermissionGroupOut,
+    RolePermissionsOut,
+    RolePermissionsUpdate,
+    UserPermissionsOut,
+    UserPermissionsUpdate,
+)
+from permissions.deps import RequiresPermission, assigned_by, get_permission_service
+from permissions.service import PermissionService
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=list[PermissionGroupOut],
+    dependencies=[Depends(RequiresPermission(PERM_VIEW))],
+)
+async def list_registered(
+    service: PermissionService = Depends(get_permission_service),
+) -> list[PermissionGroupOut]:
+    """All permission keys auto-discovered from installed modules, grouped."""
+    return service.list_registered_groups()
+
+
+# ── Role-scoped endpoints ──────────────────────────────────────
+
+
+@router.get(
+    "/roles/{role_id}",
+    response_model=RolePermissionsOut,
+    dependencies=[Depends(RequiresPermission(PERM_VIEW))],
+)
+async def get_role_permissions(
+    role_id: uuid.UUID,
+    service: PermissionService = Depends(get_permission_service),
+) -> RolePermissionsOut:
+    result = await service.get_role_permissions(role_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail="Role not found")
+    return result
+
+
+@router.put(
+    "/roles/{role_id}",
+    response_model=RolePermissionsOut,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def set_role_permissions(
+    role_id: uuid.UUID,
+    data: RolePermissionsUpdate,
+    request: Request,
+    service: PermissionService = Depends(get_permission_service),
+) -> RolePermissionsOut:
+    result = await service.set_role_permissions(role_id, data.permissions, assigned_by(request))
+    if result is None:
+        raise HTTPException(status_code=404, detail="Role not found")
+    return result
+
+
+# ── User-scoped endpoints ──────────────────────────────────────
+
+
+@router.get(
+    "/users/{user_id}",
+    response_model=UserPermissionsOut,
+    dependencies=[Depends(RequiresPermission(PERM_VIEW))],
+)
+async def get_user_permissions(
+    user_id: uuid.UUID,
+    service: PermissionService = Depends(get_permission_service),
+) -> UserPermissionsOut:
+    result = await service.get_user_permissions(user_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return result
+
+
+@router.put(
+    "/users/{user_id}",
+    response_model=UserPermissionsOut,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def set_user_permissions(
+    user_id: uuid.UUID,
+    data: UserPermissionsUpdate,
+    request: Request,
+    service: PermissionService = Depends(get_permission_service),
+) -> UserPermissionsOut:
+    result = await service.set_user_permissions(user_id, data.permissions, assigned_by(request))
+    if result is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return result

simple_module_permissions-0.0.1/permissions/endpoints/views.py

@@ -0,0 +1,123 @@
+"""Inertia view endpoints for Permissions."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Request
+from inertia import InertiaResponse
+from pydantic import ValidationError
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.inertia_utils import (
+    redirect_back_with_errors,
+    validation_errors_to_dict,
+)
+from starlette.responses import RedirectResponse
+
+from permissions.constants import PERM_MANAGE
+from permissions.contracts.schemas import RolePermissionsUpdate, UserPermissionsUpdate
+from permissions.deps import RequiresPermission, assigned_by, get_permission_service
+from permissions.service import PermissionService
+
+router = APIRouter()
+
+_ADMIN_URL = "/users/admin"
+
+
+@router.get("/", response_model=None)
+async def browse() -> RedirectResponse:
+    return RedirectResponse(_ADMIN_URL, status_code=307)
+
+
+# ── Role edit ──────────────────────────────────────────────────
+
+
+@router.get(
+    "/roles/{role_id}/edit",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def edit_role(
+    role_id: uuid.UUID,
+    inertia: InertiaDep,
+    service: PermissionService = Depends(get_permission_service),
+) -> InertiaResponse | RedirectResponse:
+    assignment = await service.get_role_permissions(role_id)
+    if assignment is None:
+        return RedirectResponse(_ADMIN_URL, status_code=303)
+    groups = service.list_registered_groups()
+    return await inertia.render(
+        "Permissions/RoleEdit",
+        {
+            "role": assignment.role.model_dump(mode="json"),
+            "assigned": assignment.permissions,
+            "groups": [g.model_dump(mode="json") for g in groups],
+        },
+    )
+
+
+@router.put(
+    "/roles/{role_id}",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def update_role(
+    role_id: uuid.UUID,
+    request: Request,
+    service: PermissionService = Depends(get_permission_service),
+) -> RedirectResponse:
+    body = await request.json()
+    try:
+        data = RolePermissionsUpdate(**body)
+    except ValidationError as exc:
+        return redirect_back_with_errors(request, validation_errors_to_dict(exc))
+    await service.set_role_permissions(role_id, data.permissions, assigned_by(request))
+    return RedirectResponse(_ADMIN_URL, status_code=303)
+
+
+# ── User edit ──────────────────────────────────────────────────
+
+
+@router.get(
+    "/users/{user_id}/edit",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def edit_user(
+    user_id: uuid.UUID,
+    inertia: InertiaDep,
+    service: PermissionService = Depends(get_permission_service),
+) -> InertiaResponse | RedirectResponse:
+    assignment = await service.get_user_permissions(user_id)
+    if assignment is None:
+        return RedirectResponse(_ADMIN_URL, status_code=303)
+    groups = service.list_registered_groups()
+    return await inertia.render(
+        "Permissions/UserEdit",
+        {
+            "user": assignment.user.model_dump(mode="json"),
+            "roles": assignment.roles,
+            "direct": assignment.direct,
+            "inherited": assignment.inherited,
+            "groups": [g.model_dump(mode="json") for g in groups],
+        },
+    )
+
+
+@router.put(
+    "/users/{user_id}",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def update_user(
+    user_id: uuid.UUID,
+    request: Request,
+    service: PermissionService = Depends(get_permission_service),
+) -> RedirectResponse:
+    body = await request.json()
+    try:
+        data = UserPermissionsUpdate(**body)
+    except ValidationError as exc:
+        return redirect_back_with_errors(request, validation_errors_to_dict(exc))
+    await service.set_user_permissions(user_id, data.permissions, assigned_by(request))
+    return RedirectResponse(_ADMIN_URL, status_code=303)