GeneralManager 0.20.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

general_manager/permission/base_permission.py

@@ -3,11 +3,16 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias
 
-from django.contrib.auth.models import AbstractBaseUser, AbstractUser, AnonymousUser
+from django.contrib.auth.models import AbstractBaseUser, AnonymousUser
 
 from general_manager.logging import get_logger
+from general_manager.permission.audit import (
+    PermissionAuditEvent,
+    audit_logging_enabled,
+    emit_permission_audit_event,
+)
 from general_manager.permission.permission_checks import permission_functions
 from general_manager.permission.permission_data_manager import PermissionDataManager
 from general_manager.permission.utils import (
@@ -64,6 +69,18 @@ class BasePermission(ABC):
         """Return the user being evaluated for permission checks."""
         return self._request_user
 
+    def describe_permissions(
+        self,
+        action: Literal["create", "read", "update", "delete"],
+        attribute: str,
+    ) -> tuple[str, ...]:
+        """Return permission expressions associated with an action/attribute pair."""
+        return ()
+
+    def _is_superuser(self) -> bool:
+        """Return True when the current request user bypasses permission checks."""
+        return bool(getattr(self.request_user, "is_superuser", False))
+
     @classmethod
     def check_create_permission(
         cls,
@@ -85,17 +102,45 @@ class BasePermission(ABC):
             PermissionCheckError: If one or more attributes in `data` are denied for the resolved `request_user`.
         """
         request_user = cls.get_user_with_id(request_user)
-        errors = []
         permission_data = PermissionDataManager(permission_data=data, manager=manager)
         Permission = cls(permission_data, request_user)
+        manager_name = manager.__name__ if manager is not None else None
+        if Permission._is_superuser():
+            if audit_logging_enabled():
+                for key in data.keys():
+                    emit_permission_audit_event(
+                        PermissionAuditEvent(
+                            action="create",
+                            attributes=(key,),
+                            granted=True,
+                            user=request_user,
+                            manager=manager_name,
+                            permissions=Permission.describe_permissions("create", key),
+                            bypassed=True,
+                        )
+                    )
+            return
+
+        errors: list[str] = []
         user_identifier = getattr(request_user, "id", None)
         for key in data.keys():
             is_allowed = Permission.check_permission("create", key)
+            if audit_logging_enabled():
+                emit_permission_audit_event(
+                    PermissionAuditEvent(
+                        action="create",
+                        attributes=(key,),
+                        granted=is_allowed,
+                        user=request_user,
+                        manager=manager_name,
+                        permissions=Permission.describe_permissions("create", key),
+                    )
+                )
             if not is_allowed:
                 logger.info(
                     "permission denied",
                     context={
-                        "manager": manager.__name__,
+                        "manager": manager_name,
                         "action": "create",
                         "attribute": key,
                         "user_id": user_identifier,
@@ -124,20 +169,47 @@ class BasePermission(ABC):
             PermissionCheckError: Raised with a list of error messages when one or more fields are not permitted to be updated.
         """
         request_user = cls.get_user_with_id(request_user)
-
-        errors = []
         permission_data = PermissionDataManager.for_update(
             base_data=old_manager_instance, update_data=data
         )
         Permission = cls(permission_data, request_user)
+        manager_name = old_manager_instance.__class__.__name__
+        if Permission._is_superuser():
+            if audit_logging_enabled():
+                for key in data.keys():
+                    emit_permission_audit_event(
+                        PermissionAuditEvent(
+                            action="update",
+                            attributes=(key,),
+                            granted=True,
+                            user=request_user,
+                            manager=manager_name,
+                            permissions=Permission.describe_permissions("update", key),
+                            bypassed=True,
+                        )
+                    )
+            return
+
+        errors: list[str] = []
         user_identifier = getattr(request_user, "id", None)
         for key in data.keys():
             is_allowed = Permission.check_permission("update", key)
+            if audit_logging_enabled():
+                emit_permission_audit_event(
+                    PermissionAuditEvent(
+                        action="update",
+                        attributes=(key,),
+                        granted=is_allowed,
+                        user=request_user,
+                        manager=manager_name,
+                        permissions=Permission.describe_permissions("update", key),
+                    )
+                )
             if not is_allowed:
                 logger.info(
                     "permission denied",
                     context={
-                        "manager": old_manager_instance.__class__.__name__,
+                        "manager": manager_name,
                         "action": "update",
                         "attribute": key,
                         "user_id": user_identifier,
@@ -166,18 +238,45 @@ class BasePermission(ABC):
             PermissionCheckError: If one or more attributes are not permitted for deletion by request_user. The exception carries the user and the list of denial messages.
         """
         request_user = cls.get_user_with_id(request_user)
-
-        errors = []
         permission_data = PermissionDataManager(manager_instance)
         Permission = cls(permission_data, request_user)
+        manager_name = manager_instance.__class__.__name__
+        if Permission._is_superuser():
+            if audit_logging_enabled():
+                for key in manager_instance.__dict__.keys():
+                    emit_permission_audit_event(
+                        PermissionAuditEvent(
+                            action="delete",
+                            attributes=(key,),
+                            granted=True,
+                            user=request_user,
+                            manager=manager_name,
+                            permissions=Permission.describe_permissions("delete", key),
+                            bypassed=True,
+                        )
+                    )
+            return
+
+        errors: list[str] = []
         user_identifier = getattr(request_user, "id", None)
         for key in manager_instance.__dict__.keys():
             is_allowed = Permission.check_permission("delete", key)
+            if audit_logging_enabled():
+                emit_permission_audit_event(
+                    PermissionAuditEvent(
+                        action="delete",
+                        attributes=(key,),
+                        granted=is_allowed,
+                        user=request_user,
+                        manager=manager_name,
+                        permissions=Permission.describe_permissions("delete", key),
+                    )
+                )
             if not is_allowed:
                 logger.info(
                     "permission denied",
                     context={
-                        "manager": manager_instance.__class__.__name__,
+                        "manager": manager_name,
                         "action": "delete",
                         "attribute": key,
                         "user_id": user_identifier,
@@ -251,15 +350,14 @@ class BasePermission(ABC):
         Raises:
             PermissionNotFoundError: If no permission function matches the leading name in `permission`.
         """
+        if self._is_superuser():
+            return {"filter": {}, "exclude": {}}
         permission_function, *config = permission.split(":")
         if permission_function not in permission_functions:
             raise PermissionNotFoundError(permission)
         permission_filter = permission_functions[permission_function][
             "permission_filter"
-        ](
-            cast(AbstractUser | AnonymousUser, self.request_user),
-            config,
-        )
+        ](self.request_user, config)
         if permission_filter is None:
             return {"filter": {}, "exclude": {}}
         return permission_filter
@@ -277,8 +375,6 @@ class BasePermission(ABC):
         Returns:
             bool: True when every sub-permission evaluates to True for the current user.
         """
-        return validate_permission_string(
-            permission,
-            self.instance,
-            cast(AbstractUser | AnonymousUser, self.request_user),
-        )
+        if self._is_superuser():
+            return True
+        return validate_permission_string(permission, self.instance, self.request_user)

general_manager/permission/manager_based_permission.py

@@ -2,14 +2,13 @@
 
 from __future__ import annotations
 from typing import TYPE_CHECKING, Literal, Optional, Dict
-from general_manager.permission.base_permission import BasePermission
+from general_manager.permission.base_permission import BasePermission, UserLike
 
 if TYPE_CHECKING:
     from general_manager.permission.permission_data_manager import (
         PermissionDataManager,
     )
     from general_manager.manager.general_manager import GeneralManager
-    from django.contrib.auth.models import AbstractUser
 
 type permission_type = Literal[
     "create",
@@ -76,14 +75,14 @@ class ManagerBasedPermission(BasePermission):
     def __init__(
         self,
         instance: PermissionDataManager | GeneralManager,
-        request_user: AbstractUser,
+        request_user: UserLike,
     ) -> None:
         """
         Initialise the permission object and gather default and attribute-level rules.
 
         Parameters:
             instance (PermissionDataManager | GeneralManager): Target data used for permission evaluation.
-            request_user (AbstractUser): User whose permissions are being checked.
+            request_user (UserLike): User whose permissions are being checked.
         """
         super().__init__(instance, request_user)
         self.__set_permissions()
@@ -182,6 +181,9 @@ class ManagerBasedPermission(BasePermission):
         Raises:
             UnknownPermissionActionError: If `action` is not one of "create", "read", "update", or "delete".
         """
+        if self._is_superuser():
+            self.__overall_results[action] = True
+            return True
         if (
             self.__based_on_permission
             and not self.__based_on_permission.check_permission(action, attribute)
@@ -241,6 +243,8 @@ class ManagerBasedPermission(BasePermission):
         Returns:
             list[dict[Literal["filter", "exclude"], dict[str, str]]]: A list of dictionaries each containing "filter" and "exclude" mappings where keys are queryset lookups and values are lookup values.
         """
+        if self._is_superuser():
+            return [{"filter": {}, "exclude": {}}]
         __based_on__ = self.__based_on__
         filters: list[dict[Literal["filter", "exclude"], dict[str, str]]] = []
 
@@ -266,3 +270,32 @@ class ManagerBasedPermission(BasePermission):
             filters.append(self._get_permission_filter(permission))
 
         return filters
+
+    def describe_permissions(
+        self,
+        action: permission_type,
+        attribute: str,
+    ) -> tuple[str, ...]:
+        """Return permission expressions considered for the given action/attribute."""
+        if action == "create":
+            base_permissions: tuple[str, ...] = tuple(self.__create__)
+        elif action == "read":
+            base_permissions = tuple(self.__read__)
+        elif action == "update":
+            base_permissions = tuple(self.__update__)
+        elif action == "delete":
+            base_permissions = tuple(self.__delete__)
+        else:
+            raise UnknownPermissionActionError(action)
+
+        attribute_source = self.__attribute_permissions.get(attribute)
+        if isinstance(attribute_source, dict):
+            attribute_permissions = tuple(attribute_source.get(action, []))
+        else:
+            attribute_permissions = tuple()
+        combined = base_permissions + attribute_permissions
+        if self.__based_on_permission is not None:
+            combined += self.__based_on_permission.describe_permissions(
+                action, attribute
+            )
+        return combined

general_manager/permission/mutation_permission.py

@@ -1,15 +1,26 @@
 """Permission helper for GraphQL mutations."""
 
 from __future__ import annotations
-from django.contrib.auth.models import AbstractUser, AnonymousUser
+
 from typing import Any
+
+from django.contrib.auth.models import AbstractBaseUser, AnonymousUser
+
+from general_manager.permission.audit import (
+    PermissionAuditEvent,
+    audit_logging_enabled,
+    emit_permission_audit_event,
+)
 from general_manager.permission.base_permission import (
     BasePermission,
     PermissionCheckError,
 )
-
 from general_manager.permission.permission_data_manager import PermissionDataManager
 from general_manager.permission.utils import validate_permission_string
+from general_manager.logging import get_logger
+
+
+logger = get_logger("permission.mutation")
 
 
 class MutationPermission:
@@ -18,18 +29,19 @@ class MutationPermission:
     __mutate__: list[str]
 
     def __init__(
-        self, data: dict[str, Any], request_user: AbstractUser | AnonymousUser
+        self, data: dict[str, Any], request_user: AbstractBaseUser | AnonymousUser
     ) -> None:
         """
         Create a mutation permission context for the given data and user.
 
         Parameters:
             data (dict[str, Any]): Input payload for the mutation.
-            request_user (AbstractUser | AnonymousUser): User attempting the mutation.
+            request_user (AbstractBaseUser | AnonymousUser): User attempting the mutation.
         """
         self._data: PermissionDataManager = PermissionDataManager(data)
         self._request_user = request_user
         self.__attribute_permissions = self.__get_attribute_permissions()
+        self._mutate_permissions: list[str] = getattr(self.__class__, "__mutate__", [])
 
         self.__overall_result: bool | None = None
 
@@ -39,7 +51,7 @@ class MutationPermission:
         return self._data
 
     @property
-    def request_user(self) -> AbstractUser | AnonymousUser:
+    def request_user(self) -> AbstractBaseUser | AnonymousUser:
         """Return the user whose permissions are being evaluated."""
         return self._request_user
 
@@ -53,31 +65,74 @@ class MutationPermission:
                 attribute_permissions[attribute] = getattr(self.__class__, attribute)
         return attribute_permissions
 
+    def describe_permissions(self, attribute: str) -> tuple[str, ...]:
+        """Return mutate-level and attribute-specific permissions for the field."""
+        base_permissions = tuple(self._mutate_permissions)
+        attribute_permissions = tuple(self.__attribute_permissions.get(attribute, []))
+        return base_permissions + attribute_permissions
+
     @classmethod
     def check(
         cls,
         data: dict[str, Any],
-        request_user: AbstractUser | AnonymousUser | Any,
+        request_user: AbstractBaseUser | AnonymousUser | Any,
     ) -> None:
         """
         Validate that the given user is authorized to perform the mutation described by `data`.
 
         Parameters:
             data (dict[str, Any]): Mutation payload mapping field names to values.
-            request_user (AbstractUser | AnonymousUser | Any): A user object or a user identifier; if an identifier is provided it will be resolved to a user.
+            request_user (AbstractBaseUser | AnonymousUser | Any): A user object or a user identifier; if an identifier is provided it will be resolved to a user.
 
         Raises:
             PermissionCheckError: Raised with the `request_user` and a list of field-level error messages when one or more fields fail their permission checks.
         """
-        errors = []
-        if not isinstance(request_user, (AbstractUser, AnonymousUser)):
+        errors: list[str] = []
+        if not isinstance(request_user, (AbstractBaseUser, AnonymousUser)):
             request_user = BasePermission.get_user_with_id(request_user)
         Permission = cls(data, request_user)
+        class_name = cls.__name__
+        is_audit_enabled = audit_logging_enabled()
+        if getattr(request_user, "is_superuser", False):
+            if is_audit_enabled:
+                for key in data:
+                    emit_permission_audit_event(
+                        PermissionAuditEvent(
+                            action="mutation",
+                            attributes=(key,),
+                            granted=True,
+                            user=request_user,
+                            manager=class_name,
+                            permissions=Permission.describe_permissions(key),
+                            bypassed=True,
+                        )
+                    )
+            return
         for key in data:
-            if not Permission.check_permission(key):
-                errors.append(
-                    f"Permission denied for {key} with value {data[key]} for user {request_user}"
+            is_allowed = Permission.check_permission(key)
+            if is_audit_enabled:
+                emit_permission_audit_event(
+                    PermissionAuditEvent(
+                        action="mutation",
+                        attributes=(key,),
+                        granted=is_allowed,
+                        user=request_user,
+                        manager=class_name,
+                        permissions=Permission.describe_permissions(key),
+                    )
+                )
+            if not is_allowed:
+                user_identifier = getattr(request_user, "id", None)
+                logger.info(
+                    "permission denied",
+                    context={
+                        "mutation": class_name,
+                        "action": "mutation",
+                        "attribute": key,
+                        "user_id": user_identifier,
+                    },
                 )
+                errors.append(f"Mutation permission denied for attribute '{key}'")
         if errors:
             raise PermissionCheckError(request_user, errors)
 
@@ -109,7 +164,7 @@ class MutationPermission:
                 self.__attribute_permissions[attribute]
             )
 
-        permission = self.__check_specific_permission(self.__mutate__)
+        permission = self.__check_specific_permission(self._mutate_permissions)
         self.__overall_result = permission
         return permission and attribute_permission