Pass room_config argument to user_may_create_room spam checker module callback

Author: hughns

docs/modules/spam_checker_callbacks.md

@@ -159,12 +159,19 @@ _First introduced in Synapse v1.37.0_
 
 _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean is now deprecated._ 
 
+_Changed in Synapse v1.x.x: Added the `room_config` argument. Callbacks that only expect a single `user_id` argument are still supported._
+
 ```python
-async def user_may_create_room(user_id: str) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_create_room(user_id: str, room_config: synapse.module_api.JsonDict) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when processing a room creation request.
 
+The arguments passed to this callback are:
+
+* `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`).
+* `room_config`: The contents of the body of a [/createRoom request](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3createroom) as a dictionary.
+
 The callback must return one of:
   - `synapse.module_api.NOT_SPAM`, to allow the operation. Other callbacks may still 
     decide to reject it.

docs/spam_checker.md

@@ -63,7 +63,7 @@ class ExampleSpamChecker:
     async def user_may_invite(self, inviter_userid, invitee_userid, room_id):
         return True  # allow all invites
 
-    async def user_may_create_room(self, userid):
+    async def user_may_create_room(self, userid, room_config):
         return True  # allow all room creations
 
     async def user_may_create_room_alias(self, userid, room_alias):

synapse/handlers/room.py

@@ -786,7 +786,7 @@ async def create_room(
 
         if not is_requester_admin:
             spam_check = await self._spam_checker_module_callbacks.user_may_create_room(
-                user_id
+                user_id, config
             )
             if spam_check != self._spam_checker_module_callbacks.NOT_SPAM:
                 raise SynapseError(

synapse/module_api/callbacks/spamchecker_callbacks.py

@@ -120,20 +120,24 @@
         ]
     ],
 ]
-USER_MAY_CREATE_ROOM_CALLBACK = Callable[
-    [str],
-    Awaitable[
-        Union[
-            Literal["NOT_SPAM"],
-            Codes,
-            # Highly experimental, not officially part of the spamchecker API, may
-            # disappear without warning depending on the results of ongoing
-            # experiments.
-            # Use this to return additional information as part of an error.
-            Tuple[Codes, JsonDict],
-            # Deprecated
-            bool,
-        ]
+USER_MAY_CREATE_ROOM_CALLBACK_RETURN_VALUE = Union[
+    Literal["NOT_SPAM"],
+    Codes,
+    # Highly experimental, not officially part of the spamchecker API, may
+    # disappear without warning depending on the results of ongoing
+    # experiments.
+    # Use this to return additional information as part of an error.
+    Tuple[Codes, JsonDict],
+    # Deprecated
+    bool,
+]
+USER_MAY_CREATE_ROOM_CALLBACK = Union[
+    Callable[
+        [str, JsonDict],
+        Awaitable[USER_MAY_CREATE_ROOM_CALLBACK_RETURN_VALUE],
+    ],
+    Callable[  # Single argument variant for backwards compatibility
+        [str], Awaitable[USER_MAY_CREATE_ROOM_CALLBACK_RETURN_VALUE]
     ],
 ]
 USER_MAY_CREATE_ROOM_ALIAS_CALLBACK = Callable[
@@ -622,16 +626,41 @@ async def user_may_send_3pid_invite(
         return self.NOT_SPAM
 
     async def user_may_create_room(
-        self, userid: str
+        self, userid: str, room_config: JsonDict
     ) -> Union[Tuple[Codes, dict], Literal["NOT_SPAM"]]:
         """Checks if a given user may create a room
 
         Args:
             userid: The ID of the user attempting to create a room
+            room_config: The room creation configuration which is the body of the /createRoom request
         """
         for callback in self._user_may_create_room_callbacks:
             with Measure(self.clock, f"{callback.__module__}.{callback.__qualname__}"):
-                res = await delay_cancellation(callback(userid))
+                checker_args = inspect.signature(callback)
+                # Also ensure backwards compatibility with spam checker callbacks
+                # that don't expect the room_config argument.
+                if len(checker_args.parameters) == 2:
+                    callback_with_requester_id = cast(
+                        Callable[
+                            [str, JsonDict],
+                            Awaitable[USER_MAY_CREATE_ROOM_CALLBACK_RETURN_VALUE],
+                        ],
+                        callback,
+                    )
+                    # We make a copy of the config to ensure the spam checker cannot modify it.
+                    res = await delay_cancellation(
+                        callback_with_requester_id(userid, room_config.copy())
+                    )
+                else:
+                    callback_without_requester_id = cast(
+                        Callable[
+                            [str], Awaitable[USER_MAY_CREATE_ROOM_CALLBACK_RETURN_VALUE]
+                        ],
+                        callback,
+                    )
+                    res = await delay_cancellation(
+                        callback_without_requester_id(userid)
+                    )
                 if res is True or res is self.NOT_SPAM:
                     continue
                 elif res is False:

tests/module_api/test_spamchecker.py

@@ -0,0 +1,112 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2025 New Vector, 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>.
+#
+#
+from typing import Literal, Union
+
+from twisted.test.proto_helpers import MemoryReactor
+
+from synapse.rest import admin, login, room
+from synapse.server import HomeServer
+from synapse.types import Codes, JsonDict
+from synapse.util import Clock
+
+from tests.server import FakeChannel
+from tests.unittest import HomeserverTestCase
+
+
+class SpamCheckerTestCase(HomeserverTestCase):
+    servlets = [
+        room.register_servlets,
+        admin.register_servlets,
+        login.register_servlets,
+    ]
+
+    def prepare(
+        self, reactor: MemoryReactor, clock: Clock, homeserver: HomeServer
+    ) -> None:
+        self._module_api = homeserver.get_module_api()
+        self.user_id = self.register_user("user", "password")
+        self.token = self.login("user", "password")
+
+    def create_room(self, content: JsonDict) -> FakeChannel:
+        channel = self.make_request(
+            "POST",
+            "/_matrix/client/r0/createRoom",
+            content,
+            access_token=self.token,
+        )
+
+        return channel
+
+    def test_may_user_create_room(self) -> None:
+        """Test that the may_user_create_room callback is called when a user
+        creates a room, and that it receives the correct parameters.
+        """
+
+        async def user_may_create_room(
+            user_id: str, room_config: JsonDict
+        ) -> Union[Literal["NOT_SPAM"], Codes]:
+            self.last_room_config = room_config
+            self.last_user_id = user_id
+            return "NOT_SPAM"
+
+        self._module_api.register_spam_checker_callbacks(
+            user_may_create_room=user_may_create_room
+        )
+
+        channel = self.create_room({"foo": "baa"})
+        self.assertEqual(channel.code, 200)
+        self.assertEqual(self.last_user_id, self.user_id)
+        self.assertEqual(self.last_room_config["foo"], "baa")
+
+    def test_may_user_create_room_disallowed(self) -> None:
+        """Test that the codes response from may_user_create_room callback is respected
+        and returned via the API.
+        """
+
+        async def user_may_create_room(
+            user_id: str, room_config: JsonDict
+        ) -> Union[Literal["NOT_SPAM"], Codes]:
+            self.last_room_config = room_config
+            self.last_user_id = user_id
+            return Codes.UNAUTHORIZED
+
+        self._module_api.register_spam_checker_callbacks(
+            user_may_create_room=user_may_create_room
+        )
+
+        channel = self.create_room({"foo": "baa"})
+        self.assertEqual(channel.code, 403)
+        self.assertEqual(channel.json_body["errcode"], Codes.UNAUTHORIZED)
+        self.assertEqual(self.last_user_id, self.user_id)
+        self.assertEqual(self.last_room_config["foo"], "baa")
+
+    def test_may_user_create_room_compatibility(self) -> None:
+        """Test that the may_user_create_room callback is called when a user
+        creates a room for a module that uses the old callback signature
+        (without the `room_config` parameter)
+        """
+
+        async def user_may_create_room(
+            user_id: str,
+        ) -> Union[Literal["NOT_SPAM"], Codes]:
+            self.last_user_id = user_id
+            return "NOT_SPAM"
+
+        self._module_api.register_spam_checker_callbacks(
+            user_may_create_room=user_may_create_room
+        )
+
+        channel = self.create_room({"foo": "baa"})
+        self.assertEqual(channel.code, 200)