Add user_may_send_state_event callback to spam checker module API

Author: hughns

changelog.d/18455.feature

@@ -0,0 +1 @@
+Add user_may_send_state_event callback to spam checker module API.

docs/modules/spam_checker_callbacks.md

@@ -239,6 +239,36 @@ be used. If this happens, Synapse will not call any of the subsequent implementa
 this callback.
 
 
+### `user_may_send_state_event`
+
+_First introduced in Synapse vX.X.X_
+
+```python
+async def user_may_send_state_event(user_id: str, room_id: str, event_type: str, state_key: str, content: JsonDict) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]
+```
+
+Called when processing a request to [send state events](https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) to a room.
+
+The arguments passed to this callback are:
+
+* `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) sending the state event.
+* `room_id`: The ID of the room that the requested state event is being sent to.
+* `event_type`: The requested type of event.
+* `state_key`: The requested state key.
+* `content`: The requested event contents.
+
+The callback must return one of:
+  - `synapse.module_api.NOT_SPAM`, to allow the operation. Other callbacks may still 
+    decide to reject it.
+  - `synapse.module_api.errors.Codes` to reject the operation with an error code. In case
+    of doubt, `synapse.module_api.errors.Codes.FORBIDDEN` is a good error code.
+
+If multiple modules implement this callback, they will be considered in order. If a
+callback returns `synapse.module_api.NOT_SPAM`, Synapse falls through to the next one.
+The value of the first callback that does not return `synapse.module_api.NOT_SPAM` will
+be used. If this happens, Synapse will not call any of the subsequent implementations of
+this callback.
+
 
 ### `check_username_for_spam`
 

synapse/module_api/__init__.py

@@ -99,6 +99,7 @@
     SHOULD_DROP_FEDERATED_EVENT_CALLBACK,
     USER_MAY_CREATE_ROOM_ALIAS_CALLBACK,
     USER_MAY_CREATE_ROOM_CALLBACK,
+    USER_MAY_SEND_STATE_EVENT_CALLBACK,
     USER_MAY_INVITE_CALLBACK,
     USER_MAY_JOIN_ROOM_CALLBACK,
     USER_MAY_PUBLISH_ROOM_CALLBACK,
@@ -311,6 +312,9 @@ def register_spam_checker_callbacks(
             USER_MAY_CREATE_ROOM_ALIAS_CALLBACK
         ] = None,
         user_may_publish_room: Optional[USER_MAY_PUBLISH_ROOM_CALLBACK] = None,
+        user_may_send_state_event: Optional[
+            USER_MAY_SEND_STATE_EVENT_CALLBACK
+        ] = None,
         check_username_for_spam: Optional[CHECK_USERNAME_FOR_SPAM_CALLBACK] = None,
         check_registration_for_spam: Optional[
             CHECK_REGISTRATION_FOR_SPAM_CALLBACK
@@ -335,6 +339,7 @@ def register_spam_checker_callbacks(
             check_registration_for_spam=check_registration_for_spam,
             check_media_file_for_spam=check_media_file_for_spam,
             check_login_for_spam=check_login_for_spam,
+            user_may_send_state_event=user_may_send_state_event,
         )
 
     def register_account_validity_callbacks(

synapse/module_api/callbacks/spamchecker_callbacks.py

@@ -168,6 +168,20 @@
         ]
     ],
 ]
+USER_MAY_SEND_STATE_EVENT_CALLBACK = Callable[
+    [str, str, str, str, JsonDict],
+    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],
+        ]
+    ],
+]
 CHECK_USERNAME_FOR_SPAM_CALLBACK = Union[
     Callable[[UserProfile], Awaitable[bool]],
     Callable[[UserProfile, str], Awaitable[bool]],
@@ -332,6 +346,9 @@ def __init__(self, hs: "synapse.server.HomeServer") -> None:
             USER_MAY_SEND_3PID_INVITE_CALLBACK
         ] = []
         self._user_may_create_room_callbacks: List[USER_MAY_CREATE_ROOM_CALLBACK] = []
+        self._user_may_send_state_event_callbacks: List[
+            USER_MAY_SEND_STATE_EVENT_CALLBACK
+        ] = []
         self._user_may_create_room_alias_callbacks: List[
             USER_MAY_CREATE_ROOM_ALIAS_CALLBACK
         ] = []
@@ -367,6 +384,9 @@ def register_callbacks(
         ] = None,
         check_media_file_for_spam: Optional[CHECK_MEDIA_FILE_FOR_SPAM_CALLBACK] = None,
         check_login_for_spam: Optional[CHECK_LOGIN_FOR_SPAM_CALLBACK] = None,
+        user_may_send_state_event: Optional[
+            USER_MAY_SEND_STATE_EVENT_CALLBACK
+        ] = None,
     ) -> None:
         """Register callbacks from module for each hook."""
         if check_event_for_spam is not None:
@@ -391,6 +411,11 @@ def register_callbacks(
         if user_may_create_room is not None:
             self._user_may_create_room_callbacks.append(user_may_create_room)
 
+        if user_may_send_state_event is not None:
+            self._user_may_send_state_event_callbacks.append(
+                user_may_send_state_event,
+            )
+
         if user_may_create_room_alias is not None:
             self._user_may_create_room_alias_callbacks.append(
                 user_may_create_room_alias,
@@ -653,6 +678,30 @@ async def user_may_create_room(
 
         return self.NOT_SPAM
 
+    async def user_may_send_state_event(
+        self, userid: str, room_id: str, event_type: str, state_key: str, content: JsonDict
+    ) -> Union[Tuple[Codes, dict], Literal["NOT_SPAM"]]:
+        """Checks if a given user may create a room with a given visibility
+        Args:
+            userid: The ID of the user attempting to create a room
+            visibility: The visibility of the room to be created
+        """
+        for callback in self._user_may_send_state_event_callbacks:
+            with Measure(self.clock, f"{callback.__module__}.{callback.__qualname__}"):
+                # We make a copy of the content to ensure that the spam checker cannot modify it.
+                res = await delay_cancellation(callback(userid, room_id, event_type, state_key, content.copy()))
+                if res is self.NOT_SPAM:
+                    continue
+                elif isinstance(res, synapse.api.errors.Codes):
+                    return res, {}
+                else:
+                    logger.warning(
+                        "Module returned invalid value, rejecting room creation as spam"
+                    )
+                    return synapse.api.errors.Codes.FORBIDDEN, {}
+
+        return self.NOT_SPAM
+
     async def user_may_create_room_alias(
         self, userid: str, room_alias: RoomAlias
     ) -> Union[Tuple[Codes, dict], Literal["NOT_SPAM"]]:

synapse/rest/client/room.py

@@ -198,6 +198,7 @@ def __init__(self, hs: "HomeServer"):
         self.delayed_events_handler = hs.get_delayed_events_handler()
         self.auth = hs.get_auth()
         self._max_event_delay_ms = hs.config.server.max_event_delay_ms
+        self._spam_checker_module_callbacks = hs.get_module_api_callbacks().spam_checker
 
     def register(self, http_server: HttpServer) -> None:
         # /rooms/$roomid/state/$eventtype
@@ -289,6 +290,23 @@ async def on_PUT(
 
         content = parse_json_object_from_request(request)
 
+        is_requester_admin = await self.auth.is_server_admin(requester)
+        if not is_requester_admin:
+            spam_check = await self._spam_checker_module_callbacks.user_may_send_state_event(
+                userid=requester.user.to_string(),
+                room_id=room_id,
+                event_type=event_type,
+                state_key=state_key,
+                content=content,
+            )
+            if spam_check != self._spam_checker_module_callbacks.NOT_SPAM:
+                raise SynapseError(
+                    403,
+                    "You are not permitted to send the state event",
+                    errcode=spam_check[0],
+                    additional_fields=spam_check[1],
+                )
+
         origin_server_ts = None
         if requester.app_service:
             origin_server_ts = parse_integer(request, "ts")