[FC-0099] feat: add model to be used as backreference to maintain rules consistent

CHANGELOG.rst

@@ -14,15 +14,24 @@ Change Log
 Unreleased
 **********
 
-0.14.0 - 2025-11-10
+0.15.0 - 2025-11-11
+********************
+
+Added
+=====
+
+* `ExtendedCasbinRule` model to extend the base CasbinRule model for additional metadata, and cascade delete
+  support.
+
+0.14.0 - 2025-11-11
 ********************
 
 Added
 =====
 
 * Implement custom matcher to check for staff and superuser status.
 
-0.13.1 - 2025-11-10
+0.13.1 - 2025-11-11
 ********************
 
 Fixed

Makefile

@@ -59,8 +59,8 @@ quality: ## check coding style with pycodestyle and pylint
 	tox -e quality
 
 format: ## format code with black and isort. Enable ruff to fix E (pycodestyle) and I (isort) issues
-	ruff format openedx_authz tests test_utils manage.py setup.py
-	ruff check --fix openedx_authz tests test_utils manage.py setup.py
+	ruff format openedx_authz tests manage.py setup.py
+	ruff check --fix openedx_authz tests manage.py setup.py
 
 pii_check: ## check for PII annotations on all Django models
 	tox -e pii_check

openedx_authz/__init__.py

@@ -4,6 +4,6 @@
 
 import os
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 ROOT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))

openedx_authz/api/roles.py

@@ -10,6 +10,8 @@
 
 from collections import defaultdict
 
+from django.db import transaction
+
 from openedx_authz.api.data import (
     GroupingPolicyIndex,
     PermissionData,
@@ -21,6 +23,7 @@
 )
 from openedx_authz.api.permissions import get_permission_from_policy
 from openedx_authz.engine.enforcer import AuthzEnforcer
+from openedx_authz.models import ExtendedCasbinRule
 
 __all__ = [
     "get_permissions_for_single_role",
@@ -197,11 +200,25 @@ def assign_role_to_subject_in_scope(subject: SubjectData, role: RoleData, scope:
         bool: True if the role was assigned successfully, False otherwise.
     """
     enforcer = AuthzEnforcer.get_enforcer()
-    return enforcer.add_role_for_user_in_domain(
-        subject.namespaced_key,
-        role.namespaced_key,
-        scope.namespaced_key,
-    )
+    adapter = AuthzEnforcer.get_adapter()
+
+    with transaction.atomic():
+        role_assignment = enforcer.add_role_for_user_in_domain(
+            subject.namespaced_key,
+            role.namespaced_key,
+            scope.namespaced_key,
+        )
+        if not role_assignment:
+            return False
+        extended_rule = ExtendedCasbinRule.create_based_on_policy(
+            subject,
+            role,
+            scope,
+            adapter,
+        )
+        if not extended_rule:
+            raise Exception("Failed to create ExtendedCasbinRule for the assignment")
+    return True
 
 
 def batch_assign_role_to_subjects_in_scope(subjects: list[SubjectData], role: RoleData, scope: ScopeData) -> None:

openedx_authz/apps.py

@@ -13,6 +13,7 @@ class OpenedxAuthzConfig(AppConfig):
     name = "openedx_authz"
     verbose_name = "Open edX AuthZ"
     default_auto_field = "django.db.models.BigAutoField"
+
     plugin_app = {
         "url_config": {
             "lms.djangoapp": {
@@ -39,3 +40,7 @@ class OpenedxAuthzConfig(AppConfig):
             },
         },
     }
+
+    def ready(self):
+        """Import signal handlers when Django starts."""
+        import openedx_authz.handlers  # pylint: disable=import-outside-toplevel,unused-import

openedx_authz/engine/adapter.py

@@ -129,3 +129,21 @@ def filter_query(
                 filter_kwargs = {f"{attr.value}__in": filter_values}
                 queryset = queryset.filter(**filter_kwargs)
         return queryset.order_by("id")
+
+    def query_policy(self, filter: Filter) -> QuerySet:  # pylint: disable=redefined-builtin
+        """
+        Retrieve policy rules from the database based on filter criteria.
+
+        This method constructs a Django queryset to fetch CasbinRule objects
+        that match the specified filter attributes. It supports filtering by
+        policy type (ptype) and policy values (v0-v5).
+
+        Args:
+            filter (Filter): Filter object with attributes (ptype, v0, v1, v2, v3, v4, v5)
+                   containing lists of values to filter by. Empty lists are ignored.
+
+        Returns:
+            QuerySet: Queryset of CasbinRule objects matching the filter criteria.
+        """
+        queryset = CasbinRule.objects.using(self.db_alias)
+        return self.filter_query(queryset, filter)

openedx_authz/engine/enforcer.py

@@ -61,9 +61,14 @@ class AuthzEnforcer:
         allowed = enforcer.get_enforcer().enforce(user, resource, action)
 
     Any of the two approaches will yield the same singleton enforcer instance.
+
+    Attributes:
+        _enforcer (SyncedEnforcer): The singleton enforcer instance.
+        _adapter (ExtendedAdapter): The singleton adapter instance.
     """
 
     _enforcer = None
+    _adapter = None
 
     def __new__(cls):
         """Singleton pattern to ensure a single enforcer instance."""
@@ -171,6 +176,19 @@ def get_enforcer(cls) -> SyncedEnforcer:
 
         return cls._enforcer
 
+    @classmethod
+    def get_adapter(cls) -> ExtendedAdapter:
+        """Get the adapter instance, getting it from the enforcer if needed.
+
+        Returns:
+            ExtendedAdapter: The singleton adapter instance.
+        """
+        if cls._adapter is None:
+            # We need to access the protected member _e to get the adapter from the base enforcer
+            # which the SyncedEnforcer wraps.
+            cls._adapter = cls.get_enforcer()._e.adapter  # pylint: disable=protected-access
+        return cls._adapter
+
     @classmethod
     def _initialize_enforcer(cls) -> SyncedEnforcer:
         """

openedx_authz/handlers.py

@@ -0,0 +1,50 @@
+"""
+Signal handlers for the authorization framework.
+
+These handlers ensure proper cleanup and consistency when models are deleted.
+"""
+
+import logging
+
+from casbin_adapter.models import CasbinRule
+from django.db.models.signals import post_delete
+from django.dispatch import receiver
+
+from openedx_authz.models.core import ExtendedCasbinRule
+
+logger = logging.getLogger(__name__)
+
+
+@receiver(post_delete, sender=ExtendedCasbinRule)
+def delete_casbin_rule_on_extended_rule_deletion(sender, instance, **kwargs):  # pylint: disable=unused-argument
+    """
+    Delete the companion CasbinRule after its ExtendedCasbinRule disappears.
+
+    The handler keeps authorization data symmetric with three common flows:
+
+    - Direct ExtendedCasbinRule deletes (API/UI) trigger removal of the linked CasbinRule.
+    - Cascades from `Scope` or `Subject` deletions clear their ExtendedCasbinRule rows and,
+      via this handler, the matching CasbinRule entries.
+    - Cascades initiated from the CasbinRule side (enforcer cleanups) leave the query as a
+      no-op because the row is already gone.
+
+    Running on ``post_delete`` ensures database cascades complete before the cleanup runs, so
+    enforcer-driven deletions no longer raise false errors.
+
+    Args:
+        sender: The model class (ExtendedCasbinRule).
+        instance: The ExtendedCasbinRule instance being deleted.
+        **kwargs: Additional keyword arguments from the signal.
+    """
+    try:
+        # Rely on delete() being idempotent; returns 0 rows if the CasbinRule was
+        # already removed (for example, because it triggered this signal).
+        CasbinRule.objects.filter(id=instance.casbin_rule_id).delete()
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # Log but don't raise - we don't want to break the deletion of
+        # ExtendedCasbinRule if something goes wrong while deleting the CasbinRule.
+        logger.exception(
+            "Error deleting CasbinRule %s during ExtendedCasbinRule cleanup",
+            instance.casbin_rule_id,
+            exc_info=exc,
+        )

openedx_authz/migrations/0002_initial.py

@@ -0,0 +1,78 @@
+# Generated by Django 4.2.24 on 2025-10-24 11:19
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("casbin_adapter", "0001_initial"),
+        ("openedx_authz", "0001_add_casbin_dependency"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Scope",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.CreateModel(
+            name="Subject",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.CreateModel(
+            name="ExtendedCasbinRule",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("casbin_rule_key", models.CharField(max_length=255, unique=True)),
+                ("description", models.TextField(blank=True, null=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("metadata", models.JSONField(blank=True, null=True)),
+                (
+                    "casbin_rule",
+                    models.OneToOneField(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="extended_rule",
+                        to="casbin_adapter.casbinrule",
+                    ),
+                ),
+                (
+                    "scope",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="casbin_rules",
+                        to="openedx_authz.scope",
+                    ),
+                ),
+                (
+                    "subject",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="casbin_rules",
+                        to="openedx_authz.subject",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Extended Casbin Rule",
+                "verbose_name_plural": "Extended Casbin Rules",
+            },
+        ),
+    ]

openedx_authz/migrations/0003_usersubject.py

@@ -0,0 +1,42 @@
+# Generated by Django 4.2.24 on 2025-10-24 11:19
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("openedx_authz", "0002_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="UserSubject",
+            fields=[
+                (
+                    "subject_ptr",
+                    models.OneToOneField(
+                        auto_created=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        parent_link=True,
+                        primary_key=True,
+                        serialize=False,
+                        to="openedx_authz.subject",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="authz_subjects",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            bases=("openedx_authz.subject",),
+        ),
+    ]

openedx_authz/migrations/0004_contentlibraryscope.py

@@ -0,0 +1,43 @@
+# Generated by Django 4.2.24 on 2025-10-24 11:19
+# Custom migration - DO NOT REGENERATE
+# This migration conditionally depends on the content library model based on settings
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("openedx_authz", "0003_usersubject"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ContentLibraryScope",
+            fields=[
+                (
+                    "scope_ptr",
+                    models.OneToOneField(
+                        auto_created=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        parent_link=True,
+                        primary_key=True,
+                        serialize=False,
+                        to="openedx_authz.scope",
+                    ),
+                ),
+                (
+                    "content_library",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="authz_scopes",
+                        to=settings.OPENEDX_AUTHZ_CONTENT_LIBRARY_MODEL,
+                    ),
+                ),
+            ],
+            bases=("openedx_authz.scope",),
+        ),
+    ]