feat: add decorator to manage policy lifecycle for low-level APIs

Author: mariajgrimaldi

openedx_authz/api/data.py

@@ -203,6 +203,8 @@ class ScopeData(AuthZData, metaclass=ScopeMeta):
     """
 
     NAMESPACE: ClassVar[str] = "sc"
+    POLICY_POSITION = 2  # Position of scope in Casbin policy rules (p = sub, act, obj)
+    GROUPING_POLICY_POSITION = 2  # Position of scope in Casbin grouping policy rules (g = sub, role, scope)
 
     @classmethod
     def validate_external_key(cls, _: str) -> bool:
@@ -220,6 +222,15 @@ def validate_external_key(cls, _: str) -> bool:
         """
         return True
 
+    @property
+    def policy_template(self) -> str:
+        """Get the policy template for the scope.
+
+        Returns:
+            str: The policy template string.
+        """
+        return f"{self.NAMESPACE}{self.SEPARATOR}*"
+
 
 @define
 class ContentLibraryData(ScopeData):

openedx_authz/api/decorators.py

@@ -0,0 +1,79 @@
+"""Decorators for the authorization public API."""
+from functools import wraps
+
+from openedx_authz.api.data import ScopeData
+from openedx_authz.engine.enforcer import enforcer
+from openedx_authz.engine.filter import Filter
+
+
+def manage_policy_lifecycle(filter_on: str = ""):
+    """Decorator to manage policy lifecycle around API calls.
+
+    This decorator ensures proper policy loading and clearing around API function calls.
+    It loads relevant policies before execution and clears them afterward to prevent
+    stale policy issues in long-running processes.
+
+    Can be used in two ways:
+        @manage_policy_lifecycle()                   -> Loads full policy
+        @manage_policy_lifecycle(filter_on="scope")  -> Loads filtered policy by scope
+
+    Args:
+        filter_on (str): The type of data class to filter on (e.g., "scope").
+            If empty, loads full policy.
+
+    Returns:
+        callable: The decorated function or decorator.
+
+    Examples:
+        # Without filtering (loads all policies):
+        @manage_policy_lifecycle()
+        def get_all_roles():
+            return enforcer.get_all_roles()
+
+        # With scope filtering (loads only relevant policies):
+        @manage_policy_lifecycle(filter_on="scope")
+        def get_roles_in_scope(scope: ScopeData):
+            return enforcer.get_filtered_roles(scope.namespaced_key)
+    """
+    FILTER_DATA_CLASSES = {
+        "scope": ScopeData,
+    }
+
+    def build_filter_from_args(args) -> Filter:
+        """Build a Filter object from function arguments based on the filter_on parameter.
+
+        Args:
+            args (tuple): Positional arguments passed to the decorated function.
+
+        Returns:
+            Filter: A Filter object populated with relevant filter values.
+        """
+        filter_obj = Filter()
+        if filter_on and filter_on in FILTER_DATA_CLASSES:
+            for arg in args:
+                if isinstance(arg, FILTER_DATA_CLASSES[filter_on]):
+                    filter_value = getattr(filter_obj, f"v{arg.POLICY_POSITION}")
+                    filter_value.append(arg.policy_template)  # Used to load p type policies as well. E.g., lib^*
+                    filter_value.append(arg.namespaced_key)  # E.g., lib^lib:DemoX:CSPROB
+        return filter_obj
+
+    def decorator(f):
+        """Inner decorator that wraps the function with policy lifecycle management."""
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            """Wrapper that handles policy loading, execution, and cleanup."""
+            filter_obj = build_filter_from_args(args)
+
+            if any([filter_obj.ptype, filter_obj.v0, filter_obj.v1, filter_obj.v2]):
+                enforcer.load_filtered_policy(filter_obj)
+            else:
+                enforcer.load_policy()
+
+            try:
+                return f(*args, **kwargs)
+            finally:
+                enforcer.clear_policy()
+
+        return wrapper
+
+    return decorator

openedx_authz/api/permissions.py

@@ -6,6 +6,7 @@
 """
 
 from openedx_authz.api.data import ActionData, PermissionData, PolicyIndex, ScopeData, SubjectData
+from openedx_authz.api.decorators import manage_policy_lifecycle
 from openedx_authz.engine.enforcer import enforcer
 
 __all__ = [
@@ -48,6 +49,7 @@ def get_all_permissions_in_scope(scope: ScopeData) -> list[PermissionData]:
     return [get_permission_from_policy(action) for action in actions]
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def is_subject_allowed(
     subject: SubjectData,
     action: ActionData,

openedx_authz/api/roles.py

@@ -21,6 +21,7 @@
 )
 from openedx_authz.api.permissions import get_permission_from_policy
 from openedx_authz.engine.enforcer import enforcer
+from openedx_authz.api.decorators import manage_policy_lifecycle
 
 __all__ = [
     "get_permissions_for_single_role",
@@ -48,6 +49,7 @@
 # in this case, ALL the policies, but that might not be the case
 
 
+@manage_policy_lifecycle()
 def get_permissions_for_single_role(
     role: RoleData,
 ) -> list[PermissionData]:
@@ -63,6 +65,7 @@ def get_permissions_for_single_role(
     return [get_permission_from_policy(policy) for policy in policies]
 
 
+@manage_policy_lifecycle()
 def get_permissions_for_roles(
     roles: list[RoleData],
 ) -> dict[str, dict[str, list[PermissionData | str]]]:
@@ -84,6 +87,7 @@ def get_permissions_for_roles(
     return permissions_by_role
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_permissions_for_active_roles_in_scope(
     scope: ScopeData, role: RoleData | None = None
 ) -> dict[str, dict[str, list[PermissionData | str]]]:
@@ -133,6 +137,7 @@ def get_permissions_for_active_roles_in_scope(
     )
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_role_definitions_in_scope(scope: ScopeData) -> list[RoleData]:
     """Get all role definitions available in a specific scope.
 
@@ -171,7 +176,7 @@ def get_role_definitions_in_scope(scope: ScopeData) -> list[RoleData]:
         for role, permissions in permissions_per_role.items()
     ]
 
-
+@manage_policy_lifecycle()
 def get_all_roles_names() -> list[str]:
     """Get all the available roles names in the current environment.
 
@@ -181,6 +186,7 @@ def get_all_roles_names() -> list[str]:
     return enforcer.get_all_subjects()
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_all_roles_in_scope(scope: ScopeData) -> list[list[str]]:
     """Get all the available role grouping policies in a specific scope.
 
@@ -195,6 +201,7 @@ def get_all_roles_in_scope(scope: ScopeData) -> list[list[str]]:
     )
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def assign_role_to_subject_in_scope(
     subject: SubjectData, role: RoleData, scope: ScopeData
 ) -> None:
@@ -211,6 +218,7 @@ def assign_role_to_subject_in_scope(
     )
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def batch_assign_role_to_subjects_in_scope(
     subjects: list[SubjectData], role: RoleData, scope: ScopeData
 ) -> None:
@@ -224,6 +232,7 @@ def batch_assign_role_to_subjects_in_scope(
         assign_role_to_subject_in_scope(subject, role, scope)
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def unassign_role_from_subject_in_scope(
     subject: SubjectData, role: RoleData, scope: ScopeData
 ) -> None:
@@ -239,6 +248,7 @@ def unassign_role_from_subject_in_scope(
     )
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def batch_unassign_role_from_subjects_in_scope(
     subjects: list[SubjectData], role: RoleData, scope: ScopeData
 ) -> None:
@@ -253,6 +263,7 @@ def batch_unassign_role_from_subjects_in_scope(
         unassign_role_from_subject_in_scope(subject, role, scope)
 
 
+@manage_policy_lifecycle()
 def get_subject_role_assignments(subject: SubjectData) -> list[RoleAssignmentData]:
     """Get all the roles for a subject across all scopes.
 
@@ -279,6 +290,7 @@ def get_subject_role_assignments(subject: SubjectData) -> list[RoleAssignmentDat
     return role_assignments
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_subject_role_assignments_in_scope(
     subject: SubjectData, scope: ScopeData
 ) -> list[RoleAssignmentData]:
@@ -310,6 +322,7 @@ def get_subject_role_assignments_in_scope(
     return role_assignments
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_subject_role_assignments_for_role_in_scope(
     role: RoleData, scope: ScopeData
 ) -> list[RoleAssignmentData]:
@@ -344,6 +357,7 @@ def get_subject_role_assignments_for_role_in_scope(
     return role_assignments
 
 
+@manage_policy_lifecycle(filter_on="scope")
 def get_all_subject_role_assignments_in_scope(scope: ScopeData) -> list[RoleAssignmentData]:
     """Get all the subjects assigned to any role in a specific scope.
 

openedx_authz/engine/adapter.py

@@ -18,7 +18,7 @@
 from casbin.persist import FilteredAdapter
 from casbin_adapter.adapter import Adapter
 from casbin_adapter.models import CasbinRule
-from django.db.models import QuerySet
+from django.db.models import QuerySet, Q
 
 from openedx_authz.engine.filter import Filter