Chore: consolidate direct grant lookups into get_permission_grantees

Six places listed who holds a permission on an object, each with its own
query and result shape, and one had already drifted into expanding group
members.

src/documents/tests/test_permission_filtering_security.py

@@ -15,9 +15,11 @@ from documents.matching import match_document_types
 from documents.matching import match_storage_paths
 from documents.matching import match_tags
 from documents.models import Correspondent
+from documents.models import Document
 from documents.models import DocumentType
 from documents.models import StoragePath
 from documents.models import Tag
+from documents.permissions import get_permission_grantees
 from documents.permissions import has_perms_owner_aware
 from documents.permissions import permitted_document_ids
 from documents.permissions import permitted_object_ids
@@ -1372,3 +1374,101 @@ class TestRestrictQuerysetToVisible:
 
         assert own.pk in visible_ids
         assert hidden.pk not in visible_ids
+
+
+@pytest.mark.django_db
+class TestGetPermissionGrantees:
+    def test_lists_direct_grants_per_object_and_action(self) -> None:
+        """
+        GIVEN:
+            - Two documents, the first with view and change granted to a user
+              and a group, the second with only view granted to another user
+            - A user who is a member of the granted group
+        WHEN:
+            - get_permission_grantees() is called for both documents
+        THEN:
+            - Each document and action lists exactly its direct grants
+            - The group member is not listed as a user
+        """
+        direct = UserFactory()
+        other = UserFactory()
+        member = UserFactory()
+        group = Group.objects.create(name="grantees")
+        member.groups.add(group)
+        first = DocumentFactory()
+        second = DocumentFactory()
+        grant_object(direct, first, "view_document", "change_document")
+        grant_object(group, first, "view_document", "change_document")
+        grant_object(other, second, "view_document")
+
+        grantees = get_permission_grantees(Document, [first.pk, second.pk])
+
+        assert grantees == {
+            first.pk: {
+                "view": {"users": [direct.pk], "groups": [group.pk]},
+                "change": {"users": [direct.pk], "groups": [group.pk]},
+            },
+            second.pk: {
+                "view": {"users": [other.pk], "groups": []},
+                "change": {"users": [], "groups": []},
+            },
+        }
+
+    def test_ids_are_sorted(self) -> None:
+        """
+        GIVEN:
+            - A tag with view granted to three users in reverse creation order
+        WHEN:
+            - get_permission_grantees() is called for the tag
+        THEN:
+            - The user ids come back in ascending order
+        """
+        users = [UserFactory() for _ in range(3)]
+        tag = TagFactory()
+        for user in reversed(users):
+            grant_object(user, tag, "view_tag")
+
+        grantees = get_permission_grantees(Tag, [tag.pk], actions=("view",))
+
+        assert grantees[tag.pk]["view"]["users"] == sorted(user.pk for user in users)
+
+    def test_only_requested_actions_are_returned(self) -> None:
+        """
+        GIVEN:
+            - A tag with view and change granted to a user
+        WHEN:
+            - get_permission_grantees() is called for the view action only
+        THEN:
+            - Only the view action is returned
+        """
+        user = UserFactory()
+        tag = TagFactory()
+        grant_object(user, tag, "view_tag", "change_tag")
+
+        grantees = get_permission_grantees(Tag, [tag.pk], actions=("view",))
+
+        assert grantees == {tag.pk: {"view": {"users": [user.pk], "groups": []}}}
+
+    def test_grants_on_another_model_with_the_same_pk_are_ignored(self) -> None:
+        """
+        GIVEN:
+            - A tag and a correspondent sharing a primary key, with view
+              granted to a user on the tag only
+        WHEN:
+            - get_permission_grantees() is called for the correspondent
+        THEN:
+            - No grants are returned
+        """
+        user = UserFactory()
+        tag = TagFactory()
+        correspondent = CorrespondentFactory(pk=tag.pk)
+        grant_object(user, tag, "view_tag")
+
+        grantees = get_permission_grantees(Correspondent, [correspondent.pk])
+
+        assert grantees == {
+            correspondent.pk: {
+                "view": {"users": [], "groups": []},
+                "change": {"users": [], "groups": []},
+            },
+        }