simple-module-permissions 0.0.1__py3-none-any.whl

permissions/__init__.py

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

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"

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",
+]

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)

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}",
+        )

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

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)

permissions/locales/en.json

@@ -0,0 +1,64 @@
+{
+  "browse": {
+    "title": "Permissions",
+    "description": "Permissions are auto-discovered from every installed module. Assign them to roles, or grant them directly to individual users.",
+    "roles_heading": "Roles",
+    "no_roles": "No roles exist yet.",
+    "users_heading": "Users",
+    "no_users": "No users match.",
+    "search_placeholder": "Search users by email or name",
+    "count_label": "{count} assigned",
+    "count_label_one": "{count} assigned",
+    "count_label_other": "{count} assigned",
+    "direct_count_label": "{count} direct",
+    "direct_count_label_one": "{count} direct",
+    "direct_count_label_other": "{count} direct",
+    "edit_link": "Edit",
+    "registry_heading": "Registry",
+    "registry_hint": "Modules declare these via ModuleBase.register_permissions — this list is rebuilt from code at every boot.",
+    "group_description": "Registered keys",
+    "no_permissions": "No modules have registered any permissions."
+  },
+  "table": {
+    "role": "Role",
+    "user": "User",
+    "name": "Name",
+    "description": "Description",
+    "assigned": "Assigned",
+    "direct": "Direct",
+    "actions": "Actions"
+  },
+  "toasts": {
+    "saved": "Permissions saved",
+    "save_failed": "Could not save permissions"
+  },
+  "edit": {
+    "title": "Edit permissions for {role}",
+    "description": "Toggle the permissions granted to every user holding this role.",
+    "empty": "No permissions have been registered by any installed module.",
+    "submit_button": "Save changes",
+    "reset_button": "Discard",
+    "cancel_link": "Back",
+    "selected_summary": "Selected",
+    "select_all_group": "Select all",
+    "clear_group": "Clear"
+  },
+  "user_edit": {
+    "title": "Permissions for {email}",
+    "description": "Grant permissions directly to this user. Inherited permissions come from the roles they hold.",
+    "roles_label": "Roles",
+    "no_roles": "No roles assigned",
+    "empty": "No permissions have been registered by any installed module.",
+    "inherited_badge": "inherited",
+    "inherited_hint": "Already granted via a role the user holds.",
+    "submit_button": "Save changes",
+    "reset_button": "Discard",
+    "cancel_link": "Back",
+    "direct_summary": "Direct",
+    "effective_summary": "Effective"
+  },
+  "errors": {
+    "role_not_found": "Role not found.",
+    "user_not_found": "User not found."
+  }
+}

permissions/models.py

@@ -0,0 +1,70 @@
+"""SQLModel tables for the Permissions module.
+
+The *set* of available permission keys lives in the in-memory
+:class:`simple_module_core.permissions.PermissionRegistry` — each module
+declares them via :meth:`ModuleBase.register_permissions`, and they are
+auto-discovered at boot. What needs persistence is the mutable mapping
+of those keys onto the principals that receive them:
+
+* :class:`RolePermission` — keys granted to every user in a named role.
+* :class:`UserPermission` — keys granted directly to a single user, on
+  top of (or independent of) any role they happen to hold.
+
+Both junction rows are keyed on plain strings rather than FKs into the
+``users`` schema — per-module :class:`MetaData` cannot express a
+cross-module foreign key, and this keeps the permissions module
+independent of ``users``' table layout.
+"""
+
+# NOTE: intentionally no ``from __future__ import annotations`` — SQLModel
+# Relationship resolution requires runtime annotations.
+
+import uuid
+from datetime import datetime
+
+from fastapi_users_db_sqlalchemy.generics import GUID, now_utc
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import DateTime, Index
+from sqlmodel import Field
+
+# Provider is auto-detected from SM_DATABASE_URL (falls back to SQLite).
+# On PostgreSQL this gives the module its own `permissions` schema; on SQLite
+# all modules share one schema, so __tablename__ is prefixed for isolation.
+Base = create_module_base("permissions")
+
+
+class RolePermission(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Assignment of a registered permission key to a role."""
+
+    __tablename__ = "permissions_role_permission"
+
+    role_name: str = Field(max_length=64, primary_key=True)
+    permission_key: str = Field(max_length=128, primary_key=True)
+    assigned_at: datetime = Field(
+        default_factory=now_utc,
+        sa_type=DateTime(timezone=True),
+    )
+    assigned_by: str | None = Field(default=None, max_length=255)
+
+    # The composite PK covers role-first lookups; this index supports
+    # reverse lookups ("which roles hold permission X?") — PostgreSQL
+    # does not auto-index non-leading PK columns.
+    __table_args__ = (Index("ix_permissions_role_permission_key", "permission_key"),)
+
+
+class UserPermission(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Direct assignment of a registered permission key to a single user."""
+
+    __tablename__ = "permissions_user_permission"
+
+    user_id: uuid.UUID = Field(sa_type=GUID, primary_key=True)
+    permission_key: str = Field(max_length=128, primary_key=True)
+    assigned_at: datetime = Field(
+        default_factory=now_utc,
+        sa_type=DateTime(timezone=True),
+    )
+    assigned_by: str | None = Field(default=None, max_length=255)
+
+    # Reverse lookups ("who has this permission directly?") are rare but cheap.
+    __table_args__ = (Index("ix_permissions_user_permission_key", "permission_key"),)

permissions/module.py

@@ -0,0 +1,54 @@
+"""Permissions module definition."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+class PermissionsModule(ModuleBase):
+    meta = ModuleMeta(
+        name="Permissions",
+        route_prefix="/api/permissions",
+        view_prefix="/permissions",
+        depends_on=["Auth", "Users"],
+    )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from permissions.endpoints.api import router as api
+        from permissions.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        from permissions.constants import PERM_MANAGE, PERM_VIEW, PERMISSION_GROUP
+
+        registry.add_group(
+            PERMISSION_GROUP,
+            [PERM_VIEW, PERM_MANAGE],
+        )
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {"permissions": base}
+
+    async def on_startup(self, app: FastAPI) -> None:
+        """Replay persisted role→permission rows into the live registry."""
+        from permissions.service import PermissionService
+
+        db_state = app.state.sm.db
+        registry = app.state.sm.permissions
+        async with db_state.session_factory() as db:
+            service = PermissionService(db, registry)
+            await service.load_all_into_registry()
+            await service.sync_admin_all_permissions()
+            await db.commit()

permissions/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": {}
+}