[FC-0099] feat: add public API to interact with roles and permissions

.gitignore

@@ -64,5 +64,6 @@ docs/openedx_authz.*.rst
 requirements/private.in
 requirements/private.txt
 
-# Sqlite Database
+# Persistent database files
+*.sqlite3
 *.db

openedx_authz/api/__init__.py

@@ -0,0 +1,11 @@
+"""Public API for the Open edX AuthZ framework.
+
+This module provides a public API as part of the Open edX AuthZ framework. This
+is part of the Open edX Layer used to abstract the authorization engine and
+provide a simpler interface for other services in the Open edX ecosystem.
+"""
+
+from openedx_authz.api.data import *
+from openedx_authz.api.permissions import *
+from openedx_authz.api.roles import *
+from openedx_authz.api.users import *

openedx_authz/api/data.py

@@ -0,0 +1,151 @@
+"""Data classes and enums for representing roles, permissions, and policies."""
+
+from enum import Enum
+from typing import Literal
+
+from attrs import define
+
+
+class GroupingPolicyIndex(Enum):
+    """Index of fields in a grouping policy."""
+
+    SUBJECT = 0
+    ROLE = 1
+    SCOPE = 2
+    # The rest of the fields are optional and can be ignored for now
+
+
+class PolicyIndex(Enum):
+    """Index of fields in a policy."""
+
+    ROLE = 0
+    ACT = 1
+    SCOPE = 2
+    EFFECT = 3
+    # The rest of the fields are optional and can be ignored for now
+
+
+@define
+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.
+    """
+
+    action: ActionData
+    effect: Literal["allow", "deny"] = "allow"
+
+
+@define
+class RoleMetadataData:
+    """Metadata for a role.
+
+    Attributes:
+        description: A description of the role.
+        created_at: The date and time the role was created.
+        created_by: The ID of the subject who created the role.
+    """
+
+    description: str = None
+    created_at: str = None
+    created_by: str = None
+
+
+@define
+class RoleData:
+    """A role is a named group of permissions.
+
+    Attributes:
+        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
+    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 RoleAssignmentData:
+    """A role assignment is the assignment of a role to a subject in a specific scope.
+
+    Attributes:
+        subject: The ID of the user namespaced (e.g., 'user:john_doe').
+        email: The email of the user.
+        role_name: The name of the role.
+        scope: The scope in which the role is assigned.
+    """
+
+    subject: UserData
+    role: RoleData
+    scope: ScopeData

openedx_authz/api/permissions.py

@@ -0,0 +1,64 @@
+"""Public API for permissions management.
+
+A permission is the authorization granted by a policy. It represents the
+allowed actions(s) a subject can perform on an object. In Casbin, permissions
+are not explicitly defined, but are inferred from the policy rules.
+"""
+
+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",
+    "has_permission",
+]
+
+
+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:
+        PermissionData: The corresponding PermissionData object or an empty PermissionData if the policy is invalid.
+    """
+    if len(policy) < 4:  # Do not count ptype
+        return PermissionData(action=ActionData(action_id=""), effect="allow")
+
+    return PermissionData(
+        action=ActionData(action_id=policy[PolicyIndex.ACT.value]),
+        effect=policy[PolicyIndex.EFFECT.value],
+    )
+
+
+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 PermissionData: A list of PermissionData objects associated with the given 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)