Add Admin API endpoints to manage user reports (#19657)

Adds [Admin
API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html)
endpoints to list, fetch and delete user reports from the homeserver.
Follows on from #18120, which added the endpoints to report users.

Author: H-Shay

changelog.d/19657.feature

@@ -0,0 +1,2 @@
+Adds [Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) endpoints to
+list, fetch and delete user reports.

synapse/rest/admin/__init__.py

@@ -96,6 +96,10 @@
     LargestRoomsStatistics,
     UserMediaStatisticsRestServlet,
 )
+from synapse.rest.admin.user_reports import (
+    UserReportDetailRestServlet,
+    UserReportsRestServlet,
+)
 from synapse.rest.admin.username_available import UsernameAvailableRestServlet
 from synapse.rest.admin.users import (
     AccountDataRestServlet,
@@ -312,6 +316,8 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
     LargestRoomsStatistics(hs).register(http_server)
     EventReportDetailRestServlet(hs).register(http_server)
     EventReportsRestServlet(hs).register(http_server)
+    UserReportsRestServlet(hs).register(http_server)
+    UserReportDetailRestServlet(hs).register(http_server)
     AccountDataRestServlet(hs).register(http_server)
     PushersRestServlet(hs).register(http_server)
     MakeRoomAdminRestServlet(hs).register(http_server)

synapse/rest/admin/user_reports.py

@@ -0,0 +1,173 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2026 Element Creations, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+
+
+import logging
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+from synapse.api.constants import Direction
+from synapse.api.errors import Codes, NotFoundError, SynapseError
+from synapse.http.servlet import RestServlet, parse_enum, parse_integer, parse_string
+from synapse.http.site import SynapseRequest
+from synapse.rest.admin._base import admin_patterns, assert_requester_is_admin
+from synapse.types import JsonDict
+
+if TYPE_CHECKING:
+    from synapse.server import HomeServer
+
+logger = logging.getLogger(__name__)
+
+
+class UserReportsRestServlet(RestServlet):
+    """
+    List all reported users that are known to the homeserver. Results are returned
+    in a dictionary containing report information. Supports pagination.
+    The requester must have administrator access in Synapse.
+
+    GET /_synapse/admin/v1/user_reports
+    returns:
+        200 OK with list of reports if success otherwise an error.
+
+    Args:
+        The parameters `from` and `limit` are required only for pagination.
+        By default, a `limit` of 100 is used.
+        The parameter `dir` can be used to define the order of results.
+        The `user_id` query parameter filters by the user ID of the reporter of the target user.
+        The `target_user_id` query parameter filters by user id of the target user.
+    Returns:
+        A list of user reprots and an integer representing the total number of user
+        reports that exist given this query
+    """
+
+    PATTERNS = admin_patterns("/user_reports$")
+
+    def __init__(self, hs: "HomeServer"):
+        self._auth = hs.get_auth()
+        self._store = hs.get_datastores().main
+
+    async def on_GET(self, request: SynapseRequest) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        start = parse_integer(request, "from", default=0)
+        limit = parse_integer(request, "limit", default=100)
+        direction = parse_enum(request, "dir", Direction, Direction.BACKWARDS)
+        user_id = parse_string(request, "user_id")
+        target_user_id = parse_string(request, "target_user_id")
+
+        if start < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST,
+                "The start parameter must be a positive integer.",
+                errcode=Codes.INVALID_PARAM,
+            )
+
+        if limit < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST,
+                "The limit parameter must be a positive integer.",
+                errcode=Codes.INVALID_PARAM,
+            )
+
+        user_reports, total = await self._store.get_user_reports_paginate(
+            start, limit, direction, user_id, target_user_id
+        )
+        ret = {"user_reports": user_reports, "total": total}
+        if (start + limit) < total:
+            ret["next_token"] = start + len(user_reports)
+
+        return HTTPStatus.OK, ret
+
+
+class UserReportDetailRestServlet(RestServlet):
+    """
+    Get a specific user report that is known to the homeserver. Results are returned
+    in a dictionary containing report information.
+    The requester must have administrator access in Synapse.
+
+    GET /_synapse/admin/v1/user_reports/<report_id>
+    returns:
+        200 OK with details report if success otherwise an error.
+
+    Args:
+        The parameter `report_id` is the ID of the user report in the database.
+    Returns:
+        JSON blob of information about the user report
+    """
+
+    PATTERNS = admin_patterns("/user_reports/(?P<report_id>[^/]*)$")
+
+    def __init__(self, hs: "HomeServer"):
+        self._auth = hs.get_auth()
+        self._store = hs.get_datastores().main
+
+    async def on_GET(
+        self, request: SynapseRequest, report_id: str
+    ) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        message = (
+            "The report_id parameter must be a string representing a positive integer."
+        )
+        try:
+            resolved_report_id = int(report_id)
+        except ValueError:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        if resolved_report_id < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        ret = await self._store.get_user_report(resolved_report_id)
+        if not ret:
+            raise NotFoundError("User report not found")
+
+        id, received_ts, target_user_id, user_id, reason = ret
+        response = {
+            "id": id,
+            "received_ts": received_ts,
+            "target_user_id": target_user_id,
+            "user_id": user_id,
+            "reason": reason,
+        }
+
+        return HTTPStatus.OK, response
+
+    async def on_DELETE(
+        self, request: SynapseRequest, report_id: str
+    ) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        message = (
+            "The report_id parameter must be a string representing a positive integer."
+        )
+        try:
+            resolved_report_id = int(report_id)
+        except ValueError:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        if resolved_report_id < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        if await self._store.delete_user_report(resolved_report_id):
+            return HTTPStatus.OK, {}
+
+        raise NotFoundError("User report not found")

synapse/storage/databases/main/room.py

@@ -2277,6 +2277,132 @@ async def delete_event_report(self, report_id: int) -> bool:
 
         return True
 
+    async def get_user_report(
+        self, report_id: int
+    ) -> tuple[int, int, str, str, str] | None:
+        """Retrieve a user report
+
+        Args:
+            report_id: ID of user report in database
+        Returns:
+            JSON dict of information from a user report or None if the
+            report does not exist.
+        """
+
+        return await self.db_pool.simple_select_one(
+            table="user_reports",
+            keyvalues={"id": report_id},
+            retcols=("id", "received_ts", "target_user_id", "user_id", "reason"),
+            allow_none=True,
+            desc="get_user_report",
+        )
+
+    async def get_user_reports_paginate(
+        self,
+        start: int,
+        limit: int,
+        direction: Direction = Direction.BACKWARDS,
+        user_id: str | None = None,
+        target_user_id: str | None = None,
+    ) -> tuple[list[JsonDict], int]:
+        """Retrieve a paginated list of user reports
+
+        Args:
+            start: event offset to begin the query from
+            limit: number of rows to retrieve
+            direction: Whether to fetch the most recent first (backwards) or the
+                oldest first (forwards)
+            user_id: search for user_id of the reporter. Ignored if user_id is None
+            target_user_id: search for user_id of the target. Ignored if target_user_id is None
+        Returns:
+            Tuple of:
+                json list of user reports
+                total number of user reports matching the filter criteria
+        """
+
+        def _get_user_reports_paginate_txn(
+            txn: LoggingTransaction,
+        ) -> tuple[list[dict[str, Any]], int]:
+            filters = []
+            args: list[object] = []
+
+            if user_id:
+                filters.append("user_id LIKE ?")
+                args.extend(["%" + user_id + "%"])
+            if target_user_id:
+                filters.append("target_user_id LIKE ?")
+                args.extend(["%" + target_user_id + "%"])
+
+            if direction == Direction.BACKWARDS:
+                order = "DESC"
+            else:
+                order = "ASC"
+
+            where_clause = "WHERE " + " AND ".join(filters) if len(filters) > 0 else ""
+
+            sql = f"""
+                SELECT COUNT(*) as total_user_reports
+                FROM user_reports {where_clause}
+            """
+            txn.execute(sql, args)
+            count = cast(tuple[int], txn.fetchone())[0]
+
+            sql = f"""
+                SELECT
+                    id,
+                    received_ts,
+                    target_user_id,
+                    user_id,
+                    reason
+                FROM user_reports
+                {where_clause}
+                ORDER BY received_ts {order}
+                LIMIT ?
+                OFFSET ?
+            """
+
+            args += [limit, start]
+            txn.execute(sql, args)
+
+            user_reports = []
+            for row in txn:
+                user_reports.append(
+                    {
+                        "id": row[0],
+                        "received_ts": row[1],
+                        "target_user_id": row[2],
+                        "user_id": row[3],
+                        "reason": row[4],
+                    }
+                )
+
+            return user_reports, count
+
+        return await self.db_pool.runInteraction(
+            "get_user_reports_paginate", _get_user_reports_paginate_txn
+        )
+
+    async def delete_user_report(self, report_id: int) -> bool:
+        """Remove a user report from database.
+
+        Args:
+            report_id: Report to delete
+
+        Returns:
+            Whether the report was successfully deleted or not.
+        """
+        try:
+            await self.db_pool.simple_delete_one(
+                table="user_reports",
+                keyvalues={"id": report_id},
+                desc="delete_user_report",
+            )
+        except StoreError:
+            # Deletion failed because report does not exist
+            return False
+
+        return True
+
     async def set_room_is_public(self, room_id: str, is_public: bool) -> None:
         await self.db_pool.simple_update_one(
             table="rooms",