Refactor to separate core permissions from app permissions

chriscarrollsmith · chriscarrollsmith · commit 71d835a88446 · 2026-03-14T12:22:59.000-04:00
diff --git a/docs/customization.qmd b/docs/customization.qmd
@@ -247,6 +247,17 @@ graph.write_png('static/schema.png')
 
 To extend the database schema, define your own models in `utils/app/models.py` and import them in `utils/core/db.py` to make sure they are included in the `metadata` object in the `create_all` function.
 
+### Example application data model
+
+The template ships with an illustrative data model, `OrganizationResource`, in `utils/app/models.py`. This model demonstrates how to create an organization-scoped database table and is used by the dashboard to display example resources. It is **meant to be replaced** with your own application-specific models.
+
+To replace it:
+
+1. Edit `utils/app/models.py` — remove `OrganizationResource` and define your own SQLModel table classes. Any table class defined in this file will be automatically created in the database on startup.
+2. Update `routers/core/dashboard.py` — replace the `OrganizationResource` query and template context with your own data.
+3. Update `templates/dashboard/index.html` — replace the example resource list with your own application UI.
+4. Optionally add new permission values to `AppPermissions` in `utils/app/enums.py` if your models need custom permission checks. These are automatically registered alongside the core `ValidPermissions` during database setup.
+
 ### Database helpers
 
 Database operations are facilitated by helper functions in `utils/core/db.py` (for core logic) and `utils/app/` (for app-specific helpers). Key functions in the core utils include:
@@ -266,16 +277,20 @@ async def get_users(session: Session = Depends(get_session)):
 
 The session automatically handles transaction management, ensuring that database operations are atomic and consistent.
 
-There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `ValidPermissions` enum value (from `utils/core/models.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
+There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `StrEnum` value (either from `ValidPermissions` in `utils/core/enums.py` or `AppPermissions` in `utils/app/enums.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
 
 ```python
-permission = ValidPermissions.CREATE_ROLE
-organization = session.exec(select(Organization).where(Organization.name == "Acme Inc.")).first()
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
+
+# Check a core permission
+user.has_permission(ValidPermissions.CREATE_ROLE, organization)
 
-user.has_permission(permission, organization)
+# Check an app-specific permission
+user.has_permission(AppPermissions.READ_ORGANIZATION_RESOURCES, organization)
 ```
 
-You can add custom permission enum values to the `ValidPermissions` enum in `utils/core/enums.py` (below the core permissions section) and validate that users have the necessary permissions before allowing them to modify organization data resources.
+Core permissions used by the template's built-in features are defined in `ValidPermissions` (`utils/core/enums.py`). To add your own app-specific permissions, define them in `AppPermissions` (`utils/app/enums.py`). Both enum types are automatically registered in the database during setup and work interchangeably with `User.has_permission()`.
 
 ### Cascade deletes
 
diff --git a/routers/core/dashboard.py b/routers/core/dashboard.py
@@ -4,7 +4,7 @@
 from sqlmodel import Session, select
 from utils.core.dependencies import get_user_with_relations, get_session
 from utils.core.models import User, Organization
-from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from utils.app.models import OrganizationResource
 
 router = APIRouter(prefix="/dashboard", tags=["dashboard"])
@@ -50,13 +50,13 @@ async def read_dashboard(
                 .order_by(OrganizationResource.created_at.desc())  # type: ignore[union-attr]
             ).all())
             can_read = user.has_permission(
-                ValidPermissions.READ_ORGANIZATION_RESOURCES, selected_org
+                AppPermissions.READ_ORGANIZATION_RESOURCES, selected_org
             )
             can_write = user.has_permission(
-                ValidPermissions.WRITE_ORGANIZATION_RESOURCES, selected_org
+                AppPermissions.WRITE_ORGANIZATION_RESOURCES, selected_org
             )
             can_delete = user.has_permission(
-                ValidPermissions.DELETE_ORGANIZATION_RESOURCES, selected_org
+                AppPermissions.DELETE_ORGANIZATION_RESOURCES, selected_org
             )
 
     return templates.TemplateResponse(
diff --git a/routers/core/invitation.py b/routers/core/invitation.py
@@ -9,7 +9,8 @@
 from logging import getLogger
 
 from utils.core.dependencies import get_authenticated_user, get_optional_user, get_session
-from utils.core.models import User, Role, Account, Invitation, ValidPermissions, Organization
+from utils.core.models import User, Role, Account, Invitation, Organization
+from utils.core.enums import ValidPermissions
 from utils.core.invitations import send_invitation_email, process_invitation
 from exceptions.http_exceptions import (
     UserIsAlreadyMemberError,
diff --git a/routers/core/organization.py b/routers/core/organization.py
@@ -9,6 +9,7 @@
 from utils.core.dependencies import get_authenticated_user, get_user_with_relations, get_session
 from utils.core.models import Organization, User, Role, Account, utc_now, Invitation
 from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import (
     OrganizationNotFoundError, OrganizationNameTakenError,
     InsufficientPermissionsError, OrganizationSetupError,
@@ -71,6 +72,7 @@ async def read_organization(
             "user": user,
             "user_permissions": user_permissions,
             "ValidPermissions": ValidPermissions,
+            "all_permissions": list(ValidPermissions) + list(AppPermissions),
             "active_invitations": active_invitations
         }
     )
diff --git a/routers/core/role.py b/routers/core/role.py
@@ -9,7 +9,9 @@
 from sqlalchemy.orm import selectinload
 from sqlalchemy.exc import IntegrityError
 from utils.core.dependencies import get_authenticated_user, get_session
-from utils.core.models import Role, Permission, ValidPermissions, utc_now, User, DataIntegrityError, Organization
+from utils.core.models import Role, Permission, utc_now, User, DataIntegrityError, Organization
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import InsufficientPermissionsError, InvalidPermissionError, RoleAlreadyExistsError, RoleNotFoundError, RoleHasUsersError, CannotModifyDefaultRoleError
 from routers.core.organization import router as organization_router
 from utils.core.htmx import is_htmx_request, append_toast
@@ -45,7 +47,7 @@ def create_role(
     request: Request,
     name: Annotated[str, Form(min_length=1, strip_whitespace=True, title="Role name", description="Name for the new role")],
     organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
-    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="List of permissions to assign to this role"),
+    permissions: List[str] = Form(default=[], title="Permissions", description="List of permissions to assign to this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -94,6 +96,7 @@ def create_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -110,7 +113,7 @@ def update_role(
     id: int = Form(..., title="Role ID", description="ID of the role to update"),
     name: str = Form(..., min_length=1, strip_whitespace=True, title="Role name", description="Updated name for the role"),
     organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
-    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="Updated list of permissions for this role"),
+    permissions: List[str] = Form(default=[], title="Permissions", description="Updated list of permissions for this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -132,8 +135,9 @@ def update_role(
         raise CannotModifyDefaultRoleError(action="update")
 
     # If any user-selected permissions are not valid, raise an error
+    all_valid = {str(p) for p in ValidPermissions} | {str(p) for p in AppPermissions}
     for permission in permissions:
-        if permission not in ValidPermissions:
+        if permission not in all_valid:
             raise InvalidPermissionError(permission)
 
     # Add any user-selected permissions that are not already associated with the role
@@ -184,6 +188,7 @@ def update_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -238,6 +243,7 @@ def delete_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         return append_toast(response, request, templates, "Role deleted successfully.")
diff --git a/routers/core/user.py b/routers/core/user.py
@@ -8,6 +8,7 @@
 from utils.core.dependencies import get_authenticated_user, get_user_with_relations, get_session
 from utils.core.images import validate_and_process_image, MAX_FILE_SIZE, MIN_DIMENSION, MAX_DIMENSION, ALLOWED_CONTENT_TYPES
 from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import (
     InsufficientPermissionsError,
     UserNotFoundError,
@@ -192,6 +193,7 @@ def update_user_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -259,6 +261,7 @@ def remove_user_from_organization(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         return append_toast(response, request, templates, "User removed from organization.")
diff --git a/templates/organization/modals/roles_card.html b/templates/organization/modals/roles_card.html
@@ -96,7 +96,7 @@ <h5 class="modal-title" id="createRoleModalLabel">Create New Role</h5>
           <div class="mb-3">
             <label class="form-label">Permissions</label>
             <div class="row">
-              {% for permission in ValidPermissions %}
+              {% for permission in all_permissions %}
                 <div class="col-md-6 mb-2">
                   <div class="form-check">
                     <input class="form-check-input" type="checkbox" name="permissions" value="{{ permission.value }}" id="perm_{{ permission.value | replace(' ', '_') }}">
@@ -144,7 +144,7 @@ <h5 class="modal-title" id="editRoleModalLabel{{ role.id }}">Edit Role: {{ role.
                 <label class="form-label">Permissions</label>
                 <div class="row">
                   {% set role_permission_names = role.permissions | map(attribute='name') | list %}
-                  {% for permission in ValidPermissions %}
+                  {% for permission in all_permissions %}
                     <div class="col-md-6 mb-2">
                       <div class="form-check">
                         <input class="form-check-input" type="checkbox" name="permissions" value="{{ permission.value }}"
diff --git a/templates/organization/partials/roles_table.html b/templates/organization/partials/roles_table.html
@@ -80,7 +80,7 @@ <h5 class="modal-title" id="editRoleModalLabel{{ role.id }}">Edit Role: {{ role.
                 <label class="form-label">Permissions</label>
                 <div class="row">
                   {% set role_permission_names = role.permissions | map(attribute='name') | list %}
-                  {% for permission in ValidPermissions %}
+                  {% for permission in all_permissions %}
                     <div class="col-md-6 mb-2">
                       <div class="form-check">
                         <input class="form-check-input" type="checkbox" name="permissions" value="{{ permission.value }}"
diff --git a/tests/routers/core/test_invitation.py b/tests/routers/core/test_invitation.py
@@ -3,7 +3,8 @@
 from unittest.mock import MagicMock
 from sqlmodel import Session, select
 from tests.conftest import SetupError
-from utils.core.models import Role, Permission, ValidPermissions, User, Invitation, Organization, Account
+from utils.core.models import Role, Permission, User, Invitation, Organization, Account
+from utils.core.enums import ValidPermissions
 from main import app
 from utils.core.invitations import generate_invitation_link
 
@@ -15,7 +16,7 @@ def invite_user_permission(session: Session) -> Permission:
     ).first()
     if permission is None:
         # Attempt to create it if missing. Permissions are global.
-        permission = Permission(name=ValidPermissions.INVITE_USER)
+        permission = Permission(name=str(ValidPermissions.INVITE_USER))
         session.add(permission)
         session.commit()
         session.refresh(permission)
diff --git a/tests/routers/core/test_organization.py b/tests/routers/core/test_organization.py
@@ -1,4 +1,5 @@
-from utils.core.models import Organization, Role, Permission, ValidPermissions, User
+from utils.core.models import Organization, Role, Permission, User
+from utils.core.enums import ValidPermissions
 from utils.core.db import create_default_roles
 from main import app
 from sqlmodel import select
diff --git a/tests/routers/core/test_role.py b/tests/routers/core/test_role.py
@@ -2,7 +2,9 @@
 
 import pytest
 from tests.conftest import SetupError
-from utils.core.models import Role, Permission, ValidPermissions, User
+from utils.core.models import Role, Permission, User
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from sqlmodel import Session, select, col
 import re
 from main import app
@@ -291,7 +293,7 @@ def test_update_role_invalid_permission(auth_client, editor_user, test_organizat
         follow_redirects=True
     )
 
-    assert response.status_code == 422
+    assert response.status_code == 400
 
 
 def test_update_role_unauthenticated(unauth_client, test_organization, session: Session):
@@ -736,7 +738,7 @@ def test_create_role_form_modal(auth_client_owner, test_organization):
     assert f'value="{test_organization.id}"' in response.text
     
     # Check for permission checkboxes
-    for permission in ValidPermissions:
+    for permission in list(ValidPermissions) + list(AppPermissions):
         assert permission.value in response.text
 
 
@@ -784,7 +786,7 @@ def test_edit_role_form_modal(auth_client_owner, session, test_organization):
     assert f'value="{test_organization.id}"' in response.text
 
     # Check for permission checkboxes with correct checked state
-    for permission in ValidPermissions:
+    for permission in list(ValidPermissions) + list(AppPermissions):
         assert f'value="{permission.value}"' in response.text
 
     # These should be checked - use regex for robustness
diff --git a/tests/utils/test_db.py b/tests/utils/test_db.py
@@ -9,7 +9,9 @@
     tear_down_db,
     set_up_db,
 )
-from utils.core.models import Role, Permission, Organization, RolePermissionLink, ValidPermissions
+from utils.core.models import Role, Permission, Organization, RolePermissionLink
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from tests.conftest import SetupError
 
 
@@ -111,8 +113,9 @@ def test_create_permissions(session: Session):
 
     # Check all permissions were created
     db_permissions = session.exec(select(Permission)).all()
-    assert len(db_permissions) == len(ValidPermissions)
-    assert {p.name for p in db_permissions} == {p for p in ValidPermissions}
+    all_perms = list(ValidPermissions) + list(AppPermissions)
+    assert len(db_permissions) == len(all_perms)
+    assert {p.name for p in db_permissions} == {str(p) for p in all_perms}
 
 
 def test_create_default_roles(session: Session, test_organization: Organization):
@@ -139,7 +142,8 @@ def test_create_default_roles(session: Session, test_organization: Organization)
         .join(RolePermissionLink)
         .where(RolePermissionLink.role_id == owner_role.id)
     ).all()
-    assert len(owner_permissions) == len(ValidPermissions)
+    all_perms = list(ValidPermissions) + list(AppPermissions)
+    assert len(owner_permissions) == len(all_perms)
 
     # Check Administrator role permissions
     admin_role = next(r for r in roles if r.name == "Administrator")
@@ -149,8 +153,8 @@ def test_create_default_roles(session: Session, test_organization: Organization)
         .where(RolePermissionLink.role_id == admin_role.id)
     ).all()
     # Admin should have all permissions except DELETE_ORGANIZATION
-    assert len(admin_permissions) == len(ValidPermissions) - 1
-    assert ValidPermissions.DELETE_ORGANIZATION not in {
+    assert len(admin_permissions) == len(all_perms) - 1
+    assert str(ValidPermissions.DELETE_ORGANIZATION) not in {
         p.name for p in admin_permissions}
 
 
@@ -159,14 +163,17 @@ def test_assign_permissions_to_role(session: Session, test_organization: Organiz
     # Create a test role with the organization from fixture
     role = Role(name="Test Role", organization_id=test_organization.id)
     session.add(role)
-
-    # Create test permissions
-    perm1 = Permission(name=ValidPermissions.CREATE_ROLE)
-    perm2 = Permission(name=ValidPermissions.DELETE_ROLE)
-    session.add(perm1)
-    session.add(perm2)
     session.commit()
 
+    # Get existing permissions
+    perm1 = session.exec(
+        select(Permission).where(Permission.name == str(ValidPermissions.CREATE_ROLE))
+    ).first()
+    perm2 = session.exec(
+        select(Permission).where(Permission.name == str(ValidPermissions.DELETE_ROLE))
+    ).first()
+    assert perm1 is not None and perm2 is not None
+
     # Assign permissions
     permissions = [perm1, perm2]
     assign_permissions_to_role(session, role, permissions)
@@ -181,18 +188,21 @@ def test_assign_permissions_to_role(session: Session, test_organization: Organiz
 
     assert len(db_permissions) == 2
     assert {p.name for p in db_permissions} == {
-        ValidPermissions.CREATE_ROLE, ValidPermissions.DELETE_ROLE}
+        str(ValidPermissions.CREATE_ROLE), str(ValidPermissions.DELETE_ROLE)}
 
 
 def test_assign_permissions_to_role_duplicate_check(session: Session, test_organization: Organization):
     """Test that assign_permissions_to_role doesn't create duplicates"""
     # Create a test role with the organization from fixture
     role = Role(name="Test Role", organization_id=test_organization.id)
-    perm = Permission(name=ValidPermissions.CREATE_ROLE)
     session.add(role)
-    session.add(perm)
     session.commit()
 
+    perm = session.exec(
+        select(Permission).where(Permission.name == str(ValidPermissions.CREATE_ROLE))
+    ).first()
+    assert perm is not None
+
     # Assign same permission twice
     assign_permissions_to_role(session, role, [perm], check_first=True)
     assign_permissions_to_role(session, role, [perm], check_first=True)
@@ -243,7 +253,7 @@ def test_set_up_db_creates_tables(engine: Engine, session: Session):
 
     # Verify permissions were created
     permissions = session.exec(select(Permission)).all()
-    assert len(permissions) == len(ValidPermissions)
+    assert len(permissions) == len(ValidPermissions) + len(AppPermissions)
 
 
 def test_private_schema_exists_after_setup(engine: Engine):
@@ -278,7 +288,7 @@ def test_set_up_db_drop_flag(engine: Engine, session: Session):
 
     # Verify valid permissions exist
     permissions = session.exec(select(Permission)).all()
-    assert len(permissions) == len(ValidPermissions)
+    assert len(permissions) == len(ValidPermissions) + len(AppPermissions)
 
     # Create an organization
     org = Organization(name="Test Organization")
diff --git a/tests/utils/test_models.py b/tests/utils/test_models.py
diff --git a/utils/app/enums.py b/utils/app/enums.py
diff --git a/utils/core/db.py b/utils/core/db.py
diff --git a/utils/core/enums.py b/utils/core/enums.py
diff --git a/utils/core/models.py b/utils/core/models.py
