Enhancement: add view_global_statistics and view_system_status permissions (#12530)

src/documents/permissions.py

@@ -56,6 +56,26 @@ class PaperlessAdminPermissions(BasePermission):
         return request.user.is_staff
 
 
+def has_global_statistics_permission(user: User | None) -> bool:
+    if user is None or not getattr(user, "is_authenticated", False):
+        return False
+
+    return getattr(user, "is_superuser", False) or user.has_perm(
+        "paperless.view_global_statistics",
+    )
+
+
+def has_system_status_permission(user: User | None) -> bool:
+    if user is None or not getattr(user, "is_authenticated", False):
+        return False
+
+    return (
+        getattr(user, "is_superuser", False)
+        or getattr(user, "is_staff", False)
+        or user.has_perm("paperless.view_system_status")
+    )
+
+
 def get_groups_with_only_permission(obj, codename):
     ctype = ContentType.objects.get_for_model(obj)
     permission = Permission.objects.get(content_type=ctype, codename=codename)

src/documents/tests/test_api_custom_fields.py

@@ -1309,7 +1309,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         # Test as user without access to the document
         non_superuser = User.objects.create_user(username="non_superuser")
         non_superuser.user_permissions.add(
-            *Permission.objects.all(),
+            *Permission.objects.exclude(codename="view_global_statistics"),
         )
         non_superuser.save()
         self.client.force_authenticate(user=non_superuser)

src/documents/tests/test_api_documents.py

@@ -1314,6 +1314,41 @@ class TestDocumentApi(DirectoriesMixin, DocumentConsumeDelayMixin, APITestCase):
         self.assertEqual(response.status_code, status.HTTP_200_OK)
         self.assertEqual(response.data["documents_inbox"], 0)
 
+    def test_statistics_with_statistics_permission(self) -> None:
+        owner = User.objects.create_user("owner")
+        stats_user = User.objects.create_user("stats-user")
+        stats_user.user_permissions.add(
+            Permission.objects.get(codename="view_global_statistics"),
+        )
+
+        inbox_tag = Tag.objects.create(
+            name="stats_inbox",
+            is_inbox_tag=True,
+            owner=owner,
+        )
+        Document.objects.create(
+            title="owned-doc",
+            checksum="stats-A",
+            mime_type="application/pdf",
+            content="abcdef",
+            owner=owner,
+        ).tags.add(inbox_tag)
+        Correspondent.objects.create(name="stats-correspondent", owner=owner)
+        DocumentType.objects.create(name="stats-type", owner=owner)
+        StoragePath.objects.create(name="stats-path", path="archive", owner=owner)
+
+        self.client.force_authenticate(user=stats_user)
+        response = self.client.get("/api/statistics/")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["documents_total"], 1)
+        self.assertEqual(response.data["documents_inbox"], 1)
+        self.assertEqual(response.data["inbox_tags"], [inbox_tag.pk])
+        self.assertEqual(response.data["character_count"], 6)
+        self.assertEqual(response.data["correspondent_count"], 1)
+        self.assertEqual(response.data["document_type_count"], 1)
+        self.assertEqual(response.data["storage_path_count"], 1)
+
     def test_upload(self) -> None:
         self.consume_file_mock.return_value = celery.result.AsyncResult(
             id=str(uuid.uuid4()),

src/documents/tests/test_api_status.py

@@ -5,12 +5,14 @@ from pathlib import Path
 from unittest import mock
 
 from celery import states
+from django.contrib.auth.models import Permission
 from django.contrib.auth.models import User
 from django.test import override_settings
 from rest_framework import status
 from rest_framework.test import APITestCase
 
 from documents.models import PaperlessTask
+from documents.permissions import has_system_status_permission
 from paperless import version
 
 
@@ -91,6 +93,22 @@ class TestSystemStatus(APITestCase):
         self.client.force_login(normal_user)
         response = self.client.get(self.ENDPOINT)
         self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+        # test the permission helper function directly for good measure
+        self.assertFalse(has_system_status_permission(None))
+
+    def test_system_status_with_system_status_permission(self) -> None:
+        response = self.client.get(self.ENDPOINT)
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+        user = User.objects.create_user(username="status_user")
+        user.user_permissions.add(
+            Permission.objects.get(codename="view_system_status"),
+        )
+
+        self.client.force_login(user)
+        response = self.client.get(self.ENDPOINT)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
 
     def test_system_status_with_bad_basic_auth_challenges(self) -> None:
         self.client.credentials(HTTP_AUTHORIZATION="Basic invalid")

src/documents/views.py

@@ -165,7 +165,9 @@ from documents.permissions import ViewDocumentsPermissions
 from documents.permissions import annotate_document_count_for_related_queryset
 from documents.permissions import get_document_count_filter_for_user
 from documents.permissions import get_objects_for_user_owner_aware
+from documents.permissions import has_global_statistics_permission
 from documents.permissions import has_perms_owner_aware
+from documents.permissions import has_system_status_permission
 from documents.permissions import set_permissions_for_object
 from documents.plugins.date_parsing import get_date_parser
 from documents.schema import generate_object_with_permissions_schema
@@ -3265,10 +3267,11 @@ class StatisticsView(GenericAPIView):
 
     def get(self, request, format=None):
         user = request.user if request.user is not None else None
+        can_view_global_stats = has_global_statistics_permission(user) or user is None
 
         documents = (
             Document.objects.all()
-            if user is None
+            if can_view_global_stats
             else get_objects_for_user_owner_aware(
                 user,
                 "documents.view_document",
@@ -3277,12 +3280,12 @@ class StatisticsView(GenericAPIView):
         )
         tags = (
             Tag.objects.all()
-            if user is None
+            if can_view_global_stats
             else get_objects_for_user_owner_aware(user, "documents.view_tag", Tag)
         ).only("id", "is_inbox_tag")
         correspondent_count = (
             Correspondent.objects.count()
-            if user is None
+            if can_view_global_stats
             else get_objects_for_user_owner_aware(
                 user,
                 "documents.view_correspondent",
@@ -3291,7 +3294,7 @@ class StatisticsView(GenericAPIView):
         )
         document_type_count = (
             DocumentType.objects.count()
-            if user is None
+            if can_view_global_stats
             else get_objects_for_user_owner_aware(
                 user,
                 "documents.view_documenttype",
@@ -3300,7 +3303,7 @@ class StatisticsView(GenericAPIView):
         )
         storage_path_count = (
             StoragePath.objects.count()
-            if user is None
+            if can_view_global_stats
             else get_objects_for_user_owner_aware(
                 user,
                 "documents.view_storagepath",
@@ -4257,7 +4260,7 @@ class SystemStatusView(PassUserMixin):
     permission_classes = (IsAuthenticated,)
 
     def get(self, request, format=None):
-        if not request.user.is_staff:
+        if not has_system_status_permission(request.user):
             return HttpResponseForbidden("Insufficient permissions")
 
         current_version = version.__full_version_str__

src/paperless/migrations/0009_alter_applicationconfiguration_options.py

@@ -0,0 +1,22 @@
+# Generated by Django 5.2.12 on 2026-04-07 23:13
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("paperless", "0008_replace_skip_archive_file"),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name="applicationconfiguration",
+            options={
+                "permissions": [
+                    ("view_global_statistics", "Can view global object counts"),
+                    ("view_system_status", "Can view system status information"),
+                ],
+                "verbose_name": "paperless application settings",
+            },
+        ),
+    ]

src/paperless/models.py

@@ -341,6 +341,10 @@ class ApplicationConfiguration(AbstractSingletonModel):
 
     class Meta:
         verbose_name = _("paperless application settings")
+        permissions = [
+            ("view_global_statistics", "Can view global object counts"),
+            ("view_system_status", "Can view system status information"),
+        ]
 
     def __str__(self) -> str:  # pragma: no cover
         return "ApplicationConfiguration"