[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,235 @@
+"""Data classes and enums for representing roles, permissions, and policies."""
+
+from enum import Enum
+from typing import ClassVar, Literal, Type
+
+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
+
+
+class AuthzBaseClass:
+    """Base class for all authz classes.
+
+    Attributes:
+        SEPARATOR: The separator between the namespace and the identifier (e.g., ':', '@').
+        NAMESPACE: The namespace prefix for the data type (e.g., 'user', 'role').
+    """
+
+    SEPARATOR: ClassVar[str] = "^"
+    NAMESPACE: ClassVar[str] = None
+
+@define
+class AuthZData(AuthzBaseClass):
+    """Base class for all authz data classes.
+
+    Attributes:
+        NAMESPACE: The namespace prefix for the data type (e.g., 'user', 'role').
+        SEPARATOR: The separator between the namespace and the identifier (e.g., ':', '@').
+        external_key: The ID for the object outside of the authz system (e.g., username).
+            Could also be used for human-readable names (e.g., role or action name).
+        namespaced_key: The ID for the object within the authz system (e.g., 'user@john_doe').
+    """
+
+    external_key: str = ""
+    namespaced_key: str = ""
+
+    def __attrs_post_init__(self):
+        """Post-initialization processing for attributes.
+
+        This method ensures that either external_key or namespaced_key is provided,
+        and derives the other attribute based on the NAMESPACE and SEPARATOR.
+
+        Note:
+        I will always instantiate with either external_key or namespaced_key, never both.
+        So we need to derive the other one based on the NAMESPACE.
+        """
+        if self.NAMESPACE and not self.namespaced_key:
+            self.namespaced_key = f"{self.NAMESPACE}{self.SEPARATOR}{self.external_key}"
+
+        if self.NAMESPACE and not self.external_key and self.namespaced_key:
+            self.external_key = self.namespaced_key.split(self.SEPARATOR, 1)[1]
+
+
+@define
+class ScopeData(AuthZData):
+    """A scope is a context in which roles and permissions are assigned.
+
+    Attributes:
+        namespaced_key: The scope identifier (e.g., 'org@Demo').
+    """
+
+    NAMESPACE: ClassVar[str] = "sc"
+
+
+@define
+class ContentLibraryData(ScopeData):
+    """A content library is a collection of content items.
+
+    Attributes:
+        library_id: The content library identifier (e.g., 'library-v1:edX+DemoX+2021_T1').
+        namespaced_key: Inherited from ScopeData, auto-generated from name if not provided.
+    """
+
+    NAMESPACE: ClassVar[str] = "lib"
+    library_id: str = ""
+
+    @property
+    def library_id(self) -> str:
+        """The library identifier as used in Open edX (e.g., 'math_101', 'library-v1:edX+DemoX').
+
+        This is an alias for external_key that represents the library ID without the namespace prefix.
+
+        Returns:
+            str: The library identifier without namespace.
+        """
+        return self.external_key
+
+
+@define
+class SubjectData(AuthZData):
+    """A subject is an entity that can be assigned roles and permissions.
+
+    Attributes:
+        namespaced_key: The subject identifier namespaced (e.g., 'sub@generic').
+    """
+
+    NAMESPACE: ClassVar[str] = "sub"
+
+@define
+class UserData(SubjectData):
+    """A user is a subject that can be assigned roles and permissions.
+
+    Attributes:
+        username: The username for the user (e.g., 'john_doe').
+        namespaced_key: Inherited from SubjectData, auto-generated from username if not provided.
+
+    This class automatically adds the 'user@' namespace prefix to the subject ID.
+    Can be initialized with either external_key= or namespaced_key= parameter.
+    """
+
+    NAMESPACE: ClassVar[str] = "user"
+
+    @property
+    def username(self) -> str:
+        """The username for the user (e.g., 'john_doe').
+
+        This is an alias for external_key that represents the username without the namespace prefix.
+
+        Returns:
+            str: The username without namespace.
+        """
+        return self.external_key
+
+
+@define
+class ActionData(AuthZData):
+    """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.
+    """
+
+    NAMESPACE: ClassVar[str] = "act"
+    name: str = ""
+
+    @property
+    def name(self) -> str:
+        """The human-readable name of the action (e.g., 'Delete Library', 'Edit Content').
+
+        This property transforms the external_key into a human-readable display name
+        by replacing underscores with spaces and capitalizing each word.
+
+        Returns:
+            str: The human-readable action name (e.g., 'Delete Library').
+        """
+        return self.external_key.replace("_", " ").title()
+
+
+@define
+class PermissionData(AuthZData):
+    """A permission is an action that can be performed under certain conditions.
+
+    Attributes:
+        name: The name of the permission.
+    """
+
+    action: ActionData = None
+    effect: Literal["allow", "deny"] = "allow"
+
+
+@define
+class RoleMetadataData(AuthZData):
+    """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(AuthZData):
+    """A role is a named group of permissions.
+
+    Attributes:
+        name: The name of the role. Must have 'role@' namespace prefix.
+        role_id: The role identifier namespaced (e.g., 'role@instructor').
+        permissions: A list of permissions 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.
+    """
+
+    NAMESPACE: ClassVar[str] = "role"
+    permissions: list[PermissionData] = None
+    metadata: RoleMetadataData = None
+
+    @property
+    def name(self) -> str:
+        """The human-readable name of the role (e.g., 'Library Admin', 'Course Instructor').
+
+        This property transforms the external_key into a human-readable display name
+        by replacing underscores with spaces and capitalizing each word.
+
+        Returns:
+            str: The human-readable role name (e.g., 'Library Admin').
+        """
+        return self.external_key.replace("_", " ").title()
+
+
+@define
+class RoleAssignmentData(AuthZData):
+    """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: SubjectData = None
+    role: RoleData = None
+    scope: ScopeData = None

openedx_authz/api/permissions.py

@@ -0,0 +1,70 @@
+"""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(namespaced_key=""), effect="allow")
+
+    return PermissionData(
+        action=ActionData(namespaced_key=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.namespaced_key)
+    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.namespaced_key, action.namespaced_key, scope.namespaced_key)