✨(backend) add user abilities system for mail domain permissions

- Add get_abilities() method to User model to determine user permissions
- Add abilities field to UserSerializer to expose permissions via API
- Implement permission logic for create_maildomains and view_maildomains
- Add comprehensive tests for User model abilities method
- Add integration tests for abilities field in users/me endpoint
- Support superuser+staff, mail domain access, and regular user scenarios

The abilities system provides granular permission control for mail domain
operations, allowing the frontend to adapt UI based on user capabilities.

Author: sdemagny

src/backend/core/api/serializers.py

@@ -12,10 +12,19 @@
 class UserSerializer(serializers.ModelSerializer):
     """Serialize users."""
 
+    abilities = serializers.SerializerMethodField(read_only=True)
+
+    def get_abilities(self, user) -> dict:
+        """Return abilities of the logged-in user on the mail domain."""
+        request = self.context.get("request")
+        if request:
+            return user.get_abilities()
+        return {}
+
     class Meta:
         model = models.User
-        fields = ["id", "email", "full_name", "short_name"]
-        read_only_fields = ["id", "email", "full_name", "short_name"]
+        fields = ["id", "email", "full_name", "short_name", "abilities"]
+        read_only_fields = ["id", "email", "full_name", "short_name", "abilities"]
 
 
 class MailboxAvailableSerializer(serializers.ModelSerializer):

src/backend/core/models.py

@@ -185,6 +185,16 @@ class Meta:
     def __str__(self):
         return self.email or self.admin_email or str(self.id)
 
+    def get_abilities(self):
+        """Return abilities of the logged-in user."""
+        # if user as access to any maildomain, he can view them
+        has_access = self.maildomain_accesses.exists()
+        is_super_admin = self.is_superuser and self.is_staff
+        return {
+            "create_maildomains": is_super_admin,
+            "view_maildomains": has_access or is_super_admin,
+        }
+
 
 class MailDomain(BaseModel):
     """Mail domain model to store mail domain information."""

src/backend/core/tests/api/test_users.py

@@ -5,7 +5,7 @@
 import pytest
 from rest_framework.test import APIClient
 
-from core import factories
+from core import factories, models
 
 pytestmark = pytest.mark.django_db
 
@@ -34,9 +34,126 @@ def test_api_users_retrieve_me_authenticated():
     )
 
     assert response.status_code == 200
-    assert response.json() == {
+    data = response.json()
+    assert data == {
         "id": str(user.id),
         "email": user.email,
         "full_name": user.full_name,
         "short_name": user.short_name,
+        "abilities": {
+            "create_maildomains": False,
+            "view_maildomains": False,
+        },
     }
+
+
+def test_api_users_retrieve_me_with_abilities_regular_user():
+    """Test abilities for regular user without mail domain access."""
+    user = factories.UserFactory()
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is False
+    assert abilities["view_maildomains"] is False
+
+
+def test_api_users_retrieve_me_with_abilities_user_with_access():
+    """Test abilities for user with mail domain access."""
+    user = factories.UserFactory()
+    maildomain = factories.MailDomainFactory()
+
+    # Give user access to a mail domain
+    models.MailDomainAccess.objects.create(
+        maildomain=maildomain,
+        user=user,
+        role=models.MailDomainAccessRoleChoices.ADMIN,
+    )
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is False
+    assert abilities["view_maildomains"] is True
+
+
+def test_api_users_retrieve_me_with_abilities_superuser_staff():
+    """Test abilities for superuser and staff user."""
+    user = factories.UserFactory(is_superuser=True, is_staff=True)
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is True
+    assert abilities["view_maildomains"] is True
+
+
+def test_api_users_retrieve_me_with_abilities_superuser_not_staff():
+    """Test abilities for superuser without staff status."""
+    user = factories.UserFactory(is_superuser=True, is_staff=False)
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is False
+    assert abilities["view_maildomains"] is False
+
+
+def test_api_users_retrieve_me_with_abilities_staff_not_superuser():
+    """Test abilities for staff user without superuser status."""
+    user = factories.UserFactory(is_superuser=False, is_staff=True)
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is False
+    assert abilities["view_maildomains"] is False
+
+
+def test_api_users_retrieve_me_with_abilities_superuser_staff_with_access():
+    """Test abilities for superuser/staff with mail domain access."""
+    user = factories.UserFactory(is_superuser=True, is_staff=True)
+    maildomain = factories.MailDomainFactory()
+
+    # Give user access to a mail domain
+    models.MailDomainAccess.objects.create(
+        maildomain=maildomain,
+        user=user,
+        role=models.MailDomainAccessRoleChoices.ADMIN,
+    )
+
+    client = APIClient()
+    client.force_login(user)
+
+    response = client.get("/api/v1.0/users/me/")
+
+    assert response.status_code == 200
+    data = response.json()
+    abilities = data["abilities"]
+    assert abilities["create_maildomains"] is True
+    assert abilities["view_maildomains"] is True

src/backend/core/tests/models/test_user_abilities.py

@@ -0,0 +1,88 @@
+"""Tests for User model get_abilities method."""
+
+import pytest
+
+from core import models
+from core.factories import MailDomainFactory, UserFactory
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.mark.django_db
+class TestUserGetAbilities:
+    """Test the get_abilities method on User model."""
+
+    def test_abilities_superuser_staff(self):
+        """Test abilities when user is superuser and staff."""
+        user = UserFactory(is_superuser=True, is_staff=True)
+
+        abilities = user.get_abilities()
+
+        assert abilities["create_maildomains"] is True
+        assert abilities["view_maildomains"] is True
+
+    def test_abilities_superuser_not_staff(self):
+        """Test abilities when user is superuser but not staff."""
+        user = UserFactory(is_superuser=True, is_staff=False)
+
+        abilities = user.get_abilities()
+
+        assert abilities["create_maildomains"] is False
+        assert abilities["view_maildomains"] is False
+
+    def test_abilities_staff_not_superuser(self):
+        """Test abilities when user is staff but not superuser."""
+        user = UserFactory(is_superuser=False, is_staff=True)
+
+        abilities = user.get_abilities()
+
+        assert abilities["create_maildomains"] is False
+        assert abilities["view_maildomains"] is False
+
+    def test_abilities_staff_not_superuser_with_maildomain_access(self):
+        """Test abilities when user is staff but not superuser and has mail domain access."""
+        user = UserFactory(is_superuser=False, is_staff=True)
+        maildomain = MailDomainFactory()
+        models.MailDomainAccess.objects.create(
+            maildomain=maildomain,
+            user=user,
+            role=models.MailDomainAccessRoleChoices.ADMIN,
+        )
+
+        abilities = user.get_abilities()
+        assert abilities["create_maildomains"] is False
+        assert abilities["view_maildomains"] is True
+
+    def test_abilities_regular_user(self):
+        """Test abilities when user is regular user."""
+        user = UserFactory(is_superuser=False, is_staff=False)
+
+        abilities = user.get_abilities()
+
+        assert abilities["create_maildomains"] is False
+        assert abilities["view_maildomains"] is False
+
+    def test_abilities_with_maildomain_access(self):
+        """Test abilities when user has mail domain access."""
+        user = UserFactory()
+        maildomain = MailDomainFactory()
+
+        # Give user access to a mail domain
+        models.MailDomainAccess.objects.create(
+            maildomain=maildomain,
+            user=user,
+            role=models.MailDomainAccessRoleChoices.ADMIN,
+        )
+
+        abilities = user.get_abilities()
+
+        assert abilities["view_maildomains"] is True
+        assert abilities["create_maildomains"] is False
+
+    def test_abilities_without_maildomain_access(self):
+        """Test abilities when user has no mail domain access."""
+        user = UserFactory()
+        abilities = user.get_abilities()
+
+        assert abilities["view_maildomains"] is False
+        assert abilities["create_maildomains"] is False