refactor: wrap namespace into attrs classes

Author: mariajgrimaldi

openedx_authz/api/data.py

@@ -26,20 +26,80 @@ class PolicyIndex(Enum):
 
 
 @define
-class Permission:  # TODO: change to policy?
+class UserData:
+    """A user is a subject that can be assigned roles and permissions.
+
+    Attributes:
+        username: The username. Automatically prefixed with 'user:' if not present.
+    """
+
+    username: str
+
+    def __attrs_post_init__(self):
+        """Ensure username has 'user:' namespace prefix."""
+        if not self.username.startswith("user:"):
+            object.__setattr__(self, "username", f"user:{self.username}")
+
+
+@define
+class ScopeData:
+    """A scope is a context in which roles and permissions are assigned.
+
+    Attributes:
+        scope_id: The scope identifier (e.g., 'course-v1:edX+DemoX+2021_T1').
+
+    This class assumes that the scope is already namespaced appropriately
+    before being passed in, as scopes can vary widely (e.g., courses, organizations).
+    """
+
+    scope_id: str
+
+
+@define
+class SubjectData:
+    """A subject is an entity that can be assigned roles and permissions.
+
+    Attributes:
+        subject_id: The subject identifier namespaced (e.g., 'user:john_doe').
+
+    This class assumes that the subject was already namespaced by their own
+    type (e.g., 'user:', 'group:') before being passed in since subjects can be
+    users, groups, or other entities.
+    """
+
+    subject_id: str
+
+
+@define
+class ActionData:
+    """An action is an operation that can be performed in a specific scope.
+
+    Attributes:
+        action: The action name. Automatically prefixed with 'act:' if not present.
+    """
+
+    action_id: str
+
+    def __attrs_post_init__(self):
+        """Ensure action name has 'act:' namespace prefix."""
+        if not self.action_id.startswith("act:"):
+            object.__setattr__(self, "action_id", f"act:{self.action_id}")
+
+
+@define
+class PermissionData:  # TODO: change to policy?
     """A permission is an action that can be performed under certain conditions.
 
     Attributes:
         name: The name of the permission.
     """
 
-    # TODO: what other attributes should a permission have?
-    name: str
+    action: ActionData
     effect: Literal["allow", "deny"] = "allow"
 
 
 @define
-class RoleMetadata:
+class RoleMetadataData:
     """Metadata for a role.
 
     Attributes:
@@ -54,25 +114,29 @@ class RoleMetadata:
 
 
 @define
-class Role:
+class RoleData:
     """A role is a named group of permissions.
 
     Attributes:
-        name: The name of the role.
+        name: The name of the role. Must have 'role:' namespace prefix.
         permissions: A list of permissions assigned to the role.
         scopes: A list of scopes assigned to the role.
         metadata: A dictionary of metadata assigned to the role. This can include
             information such as the description of the role, creation date, etc.
     """
 
     name: str
-    scopes: list[str]
-    permissions: list[Permission] = None
-    metadata: RoleMetadata = None
+    permissions: list[PermissionData] = None
+    metadata: RoleMetadataData = None
+
+    def __attrs_post_init__(self):
+        """Ensure role name has 'role:' namespace prefix."""
+        if not self.name.startswith("role:"):
+            object.__setattr__(self, "name", f"role:{self.name}")
 
 
 @define
-class RoleAssignment:
+class RoleAssignmentData:
     """A role assignment is the assignment of a role to a subject in a specific scope.
 
     Attributes:
@@ -82,5 +146,6 @@ class RoleAssignment:
         scope: The scope in which the role is assigned.
     """
 
-    subject: str  # TODO: I think here it makes sense to sanitize the subject so it's the username?
-    role: Role
+    subject: UserData
+    role: RoleData
+    scope: ScopeData

openedx_authz/api/permissions.py

@@ -5,39 +5,60 @@
 are not explicitly defined, but are inferred from the policy rules.
 """
 
-from typing import Literal
-
-from openedx_authz.api.data import Permission, PolicyIndex
+from openedx_authz.api.data import ActionData, PermissionData, PolicyIndex, ScopeData, SubjectData
 from openedx_authz.engine.enforcer import enforcer
 
-__all__ = ["get_permission_from_policy", "get_all_permissions_in_scope"]
+__all__ = [
+    "get_permission_from_policy",
+    "get_all_permissions_in_scope",
+    "has_permission",
+]
 
 
-def get_permission_from_policy(policy: list[str]) -> Permission:
-    """Convert a Casbin policy list to a Permission object.
+def get_permission_from_policy(policy: list[str]) -> PermissionData:
+    """Convert a Casbin policy list to a PermissionData object.
 
     Args:
         policy: A list representing a Casbin policy.
 
     Returns:
-        Permission: The corresponding Permission object or an empty Permission if the policy is invalid.
+        PermissionData: The corresponding PermissionData object or an empty PermissionData if the policy is invalid.
     """
     if len(policy) < 4:  # Do not count ptype
-        return Permission(name="", effect="")
+        return PermissionData(action=ActionData(action_id=""), effect="allow")
 
-    return Permission(
-        name=policy[PolicyIndex.ACT.value], effect=policy[PolicyIndex.EFFECT.value]
+    return PermissionData(
+        action=ActionData(action_id=policy[PolicyIndex.ACT.value]),
+        effect=policy[PolicyIndex.EFFECT.value],
     )
 
 
-def get_all_permissions_in_scope(scope: str) -> list[Permission]:
+def get_all_permissions_in_scope(scope: ScopeData) -> list[PermissionData]:
     """Retrieve all permissions associated with a specific scope.
 
     Args:
         scope: The scope to filter permissions by.
 
     Returns:
-        list of Permission: A list of Permission objects associated with the given scope.
+        list of PermissionData: A list of PermissionData objects associated with the given scope.
     """
-    actions = enforcer.get_filtered_policy(PolicyIndex.SCOPE.value, scope)
+    actions = enforcer.get_filtered_policy(PolicyIndex.SCOPE.value, scope.scope_id)
     return [get_permission_from_policy(action) for action in actions]
+
+
+def has_permission(
+    subject: SubjectData,
+    action: ActionData,
+    scope: ScopeData,
+) -> bool:
+    """Check if a subject has a specific permission in a given scope.
+
+    Args:
+        subject: The subject to check (e.g., user or service).
+        action: The action to check (e.g., 'view_course').
+        scope: The scope in which to check the permission (e.g., 'course-v1:edX+DemoX+2021_T1').
+
+    Returns:
+        bool: True if the subject has the specified permission in the scope, False otherwise.
+    """
+    return enforcer.enforce(subject.subject_id, action.action_id, scope.scope_id)