+ +

Spam checker callbacks

Spam checker callbacks allow module developers to implement spam mitigation actions for +Synapse instances. Spam checker callbacks can be registered using the module API's +register_spam_checker_callbacks method.

Callbacks

The available spam checker callbacks are:

`check_event_for_spam`

First introduced in Synapse v1.37.0

async def check_event_for_spam(event: "synapse.events.EventBase") -> Union[bool, str]
+

Called when receiving an event from a client or via federation. The module can return +either a bool to indicate whether the event must be rejected because of spam, or a str +to indicate the event must be rejected because of spam and to give a rejection reason to +forward to clients.

If multiple modules implement this callback, they will be considered in order. If a +callback returns False, Synapse falls through to the next one. The value of the first +callback that does not return False will be used. If this happens, Synapse will not call +any of the subsequent implementations of this callback.

`user_may_join_room`

First introduced in Synapse v1.37.0

async def user_may_join_room(user: str, room: str, is_invited: bool) -> bool
+

Called when a user is trying to join a room. The module must return a bool to indicate +whether the user can join the room. The user is represented by their Matrix user ID (e.g. +@alice:example.com) and the room is represented by its Matrix ID (e.g. +!room:example.com). The module is also given a boolean to indicate whether the user +currently has a pending invite in the room.

This callback isn't called if the join is performed by a server administrator, or in the +context of a room creation.

If multiple modules implement this callback, they will be considered in order. If a +callback returns True, Synapse falls through to the next one. The value of the first +callback that does not return True will be used. If this happens, Synapse will not call +any of the subsequent implementations of this callback.

`user_may_invite`

First introduced in Synapse v1.37.0

async def user_may_invite(inviter: str, invitee: str, room_id: str) -> bool
+

Called when processing an invitation. The module must return a bool indicating whether +the inviter can invite the invitee to the given room. Both inviter and invitee are +represented by their Matrix user ID (e.g. @alice:example.com).

`user_may_send_3pid_invite`

First introduced in Synapse v1.45.0

async def user_may_send_3pid_invite(
+    inviter: str,
+    medium: str,
+    address: str,
+    room_id: str,
+) -> bool
+

Called when processing an invitation using a third-party identifier (also called a 3PID, +e.g. an email address or a phone number). The module must return a bool indicating +whether the inviter can invite the invitee to the given room.

The inviter is represented by their Matrix user ID (e.g. @alice:example.com), and the +invitee is represented by its medium (e.g. "email") and its address +(e.g. alice@example.com). See the Matrix specification +for more information regarding third-party identifiers.

For example, a call to this callback to send an invitation to the email address +alice@example.com would look like this:

await user_may_send_3pid_invite(
+    "@bob:example.com",  # The inviter's user ID
+    "email",  # The medium of the 3PID to invite
+    "alice@example.com",  # The address of the 3PID to invite
+    "!some_room:example.com",  # The ID of the room to send the invite into
+)
+

Note: If the third-party identifier is already associated with a matrix user ID, +user_may_invite will be used instead.

`user_may_create_room`

First introduced in Synapse v1.37.0

async def user_may_create_room(user: str) -> bool
+

Called when processing a room creation request. The module must return a bool indicating +whether the given user (represented by their Matrix user ID) is allowed to create a room.

`user_may_create_room_alias`

First introduced in Synapse v1.37.0

async def user_may_create_room_alias(user: str, room_alias: "synapse.types.RoomAlias") -> bool
+

Called when trying to associate an alias with an existing room. The module must return a +bool indicating whether the given user (represented by their Matrix user ID) is allowed +to set the given alias.

`user_may_publish_room`

First introduced in Synapse v1.37.0

async def user_may_publish_room(user: str, room_id: str) -> bool
+

Called when trying to publish a room to the homeserver's public rooms directory. The +module must return a bool indicating whether the given user (represented by their +Matrix user ID) is allowed to publish the given room.

`check_username_for_spam`

First introduced in Synapse v1.37.0

async def check_username_for_spam(user_profile: Dict[str, str]) -> bool
+

Called when computing search results in the user directory. The module must return a +bool indicating whether the given user profile can appear in search results. The profile +is represented as a dictionary with the following keys:

user_id: The Matrix ID for this user.
display_name: The user's display name.
avatar_url: The mxc:// URL to the user's avatar.

The module is given a copy of the original dictionary, so modifying it from within the +module cannot modify a user's profile when included in user directory search results.

`check_registration_for_spam`

First introduced in Synapse v1.37.0

async def check_registration_for_spam(
+    email_threepid: Optional[dict],
+    username: Optional[str],
+    request_info: Collection[Tuple[str, str]],
+    auth_provider_id: Optional[str] = None,
+) -> "synapse.spam_checker_api.RegistrationBehaviour"
+

Called when registering a new user. The module must return a RegistrationBehaviour +indicating whether the registration can go through or must be denied, or whether the user +may be allowed to register but will be shadow banned.

The arguments passed to this callback are:

email_threepid: The email address used for registering, if any.
username: The username the user would like to register. Can be None, meaning that +Synapse will generate one later.
request_info: A collection of tuples, which first item is a user agent, and which +second item is an IP address. These user agents and IP addresses are the ones that were +used during the registration process.
auth_provider_id: The identifier of the SSO authentication provider, if any.

If multiple modules implement this callback, they will be considered in order. If a +callback returns RegistrationBehaviour.ALLOW, Synapse falls through to the next one. +The value of the first callback that does not return RegistrationBehaviour.ALLOW will +be used. If this happens, Synapse will not call any of the subsequent implementations of +this callback.

`check_media_file_for_spam`

First introduced in Synapse v1.37.0

async def check_media_file_for_spam(
+    file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper",
+    file_info: "synapse.rest.media.v1._base.FileInfo",
+) -> bool
+

Called when storing a local or remote file. The module must return a boolean indicating +whether the given file can be stored in the homeserver's media store.

Example

The example below is a module that implements the spam checker callback +check_event_for_spam to deny any message sent by users whose Matrix user IDs are +mentioned in a configured list, and registers a web resource to the path +/_synapse/client/list_spam_checker/is_evil that returns a JSON object indicating +whether the provided user appears in that list.

import json
+from typing import Union
+
+from twisted.web.resource import Resource
+from twisted.web.server import Request
+
+from synapse.module_api import ModuleApi
+
+
+class IsUserEvilResource(Resource):
+    def __init__(self, config):
+        super(IsUserEvilResource, self).__init__()
+        self.evil_users = config.get("evil_users") or []
+
+    def render_GET(self, request: Request):
+        user = request.args.get(b"user")[0].decode()
+        request.setHeader(b"Content-Type", b"application/json")
+        return json.dumps({"evil": user in self.evil_users}).encode()
+
+
+class ListSpamChecker:
+    def __init__(self, config: dict, api: ModuleApi):
+        self.api = api
+        self.evil_users = config.get("evil_users") or []
+
+        self.api.register_spam_checker_callbacks(
+            check_event_for_spam=self.check_event_for_spam,
+        )
+
+        self.api.register_web_resource(
+            path="/_synapse/client/list_spam_checker/is_evil",
+            resource=IsUserEvilResource(config),
+        )
+
+    async def check_event_for_spam(self, event: "synapse.events.EventBase") -> Union[bool, str]:
+        return event.sender not in self.evil_users
+

+ +

Third party rules callbacks

Third party rules callbacks allow module developers to add extra checks to verify the +validity of incoming events. Third party event rules callbacks can be registered using +the module API's register_third_party_rules_callbacks method.

Callbacks

The available third party rules callbacks are:

`check_event_allowed`

First introduced in Synapse v1.39.0

async def check_event_allowed(
+    event: "synapse.events.EventBase",
+    state_events: "synapse.types.StateMap",
+) -> Tuple[bool, Optional[dict]]
+

+This callback is very experimental and can and will break without notice. Module developers +are encouraged to implement check_event_for_spam from the spam checker category instead. +

Called when processing any incoming event, with the event and a StateMap +representing the current state of the room the event is being sent into. A StateMap is +a dictionary that maps tuples containing an event type and a state key to the +corresponding state event. For example retrieving the room's m.room.create event from +the state_events argument would look like this: state_events.get(("m.room.create", "")). +The module must return a boolean indicating whether the event can be allowed.

Note that this callback function processes incoming events coming via federation +traffic (on top of client traffic). This means denying an event might cause the local +copy of the room's history to diverge from that of remote servers. This may cause +federation issues in the room. It is strongly recommended to only deny events using this +callback function if the sender is a local user, or in a private federation in which all +servers are using the same module, with the same configuration.

If the boolean returned by the module is True, it may also tell Synapse to replace the +event with new data by returning the new event's data as a dictionary. In order to do +that, it is recommended the module calls event.get_dict() to get the current event as a +dictionary, and modify the returned dictionary accordingly.

If check_event_allowed raises an exception, the module is assumed to have failed. +The event will not be accepted but is not treated as explicitly rejected, either. +An HTTP request causing the module check will likely result in a 500 Internal +Server Error.

When the boolean returned by the module is False, the event is rejected. +(Module developers should not use exceptions for rejection.)

Note that replacing the event only works for events sent by local users, not for events +received over federation.

`on_create_room`

First introduced in Synapse v1.39.0

async def on_create_room(
+    requester: "synapse.types.Requester",
+    request_content: dict,
+    is_requester_admin: bool,
+) -> None
+

Called when processing a room creation request, with the Requester object for the user +performing the request, a dictionary representing the room creation request's JSON body +(see the spec +for a list of possible parameters), and a boolean indicating whether the user performing +the request is a server admin.

Modules can modify the request_content (by e.g. adding events to its initial_state), +or deny the room's creation by raising a module_api.errors.SynapseError.

If multiple modules implement this callback, they will be considered in order. If a +callback returns without raising an exception, Synapse falls through to the next one. The +room creation will be forbidden as soon as one of the callbacks raises an exception. If +this happens, Synapse will not call any of the subsequent implementations of this +callback.

`check_threepid_can_be_invited`

First introduced in Synapse v1.39.0

async def check_threepid_can_be_invited(
+    medium: str,
+    address: str,
+    state_events: "synapse.types.StateMap",
+) -> bool:
+

Called when processing an invite via a third-party identifier (i.e. email or phone number). +The module must return a boolean indicating whether the invite can go through.

`check_visibility_can_be_modified`

First introduced in Synapse v1.39.0

async def check_visibility_can_be_modified(
+    room_id: str,
+    state_events: "synapse.types.StateMap",
+    new_visibility: str,
+) -> bool:
+

Called when changing the visibility of a room in the local public room directory. The +visibility is a string that's either "public" or "private". The module must return a +boolean indicating whether the change can go through.

`on_new_event`

First introduced in Synapse v1.47.0

async def on_new_event(
+    event: "synapse.events.EventBase",
+    state_events: "synapse.types.StateMap",
+) -> None:
+

Called after sending an event into a room. The module is passed the event, as well +as the state of the room after the event. This means that if the event is a state event, +it will be included in this state.

Note that this callback is called when the event has already been processed and stored +into the room, which means this callback cannot be used to deny persisting the event. To +deny an incoming event, see check_event_for_spam instead.

If multiple modules implement this callback, Synapse runs them all in order.

Example

The example below is a module that implements the third-party rules callback +check_event_allowed to censor incoming messages as dictated by a third-party service.

from typing import Optional, Tuple
+
+from synapse.module_api import ModuleApi
+
+_DEFAULT_CENSOR_ENDPOINT = "https://my-internal-service.local/censor-event"
+
+class EventCensorer:
+    def __init__(self, config: dict, api: ModuleApi):
+        self.api = api
+        self._endpoint = config.get("endpoint", _DEFAULT_CENSOR_ENDPOINT)
+
+        self.api.register_third_party_rules_callbacks(
+            check_event_allowed=self.check_event_allowed,
+        )
+
+    async def check_event_allowed(
+        self,
+        event: "synapse.events.EventBase",
+        state_events: "synapse.types.StateMap",
+    ) -> Tuple[bool, Optional[dict]]:
+        event_dict = event.get_dict()
+        new_event_content = await self.api.http_client.post_json_get_json(
+            uri=self._endpoint, post_json=event_dict,
+        )
+        event_dict["content"] = new_event_content
+        return event_dict
+

+ +