Add support for synapse-http-antispam and integrate it with Draupnir

Supersedes https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/4284

docs/configuring-playbook-bot-draupnir.md

@@ -145,6 +145,20 @@ The bot can intercept the report API endpoint of the client-server API, which re
 matrix_bot_draupnir_config_web_abuseReporting: true
 ```
 
+### Enabling synapse-http-antispam support
+
+Certain protections in Draupnir require the [synapse-http-antispam](https://github.com/maunium/synapse-http-antispam) module and a Synapse homeserver plus homeserver admin status to function. This module can be enabled in the playbook via setting `matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled` to `true` and making sure that Draupnir admin API access is enabled.
+
+```yaml
+# Enables the integration between Draupnir and synapse-http-antispam module.
+matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled: true
+
+# Enables draupnir to access Synapse admin APIs. This is required for the module functionality to take full effect.
+matrix_bot_draupnir_admin_api_enabled: true
+```
+
+These protections need to be manually activated and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
+
 <!--
 NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
 

group_vars/matrix_servers

@@ -3202,6 +3202,9 @@ matrix_bot_draupnir_container_labels_traefik_docker_network: "{{ matrix_playbook
 matrix_bot_draupnir_container_labels_web_abuseReporting_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_bot_draupnir_container_labels_web_abuseReporting_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
 
+#The salt is size restricted here as a maximum salt size of 16 characters exists due to the functions used.
+matrix_bot_draupnir_config_web_synapseHTTPAntispam_authorization: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'draupnir.httpmod', rounds=655555) | to_uuid }}" # noqa var-naming
+
 ######################################################################
 #
 # /matrix-bot-draupnir
@@ -4835,6 +4838,8 @@ matrix_synapse_container_additional_networks_auto: |
       ([exim_relay_container_network] if (exim_relay_enabled and matrix_synapse_email_enabled and matrix_synapse_email_smtp_host == exim_relay_identifier and matrix_synapse_container_network != exim_relay_container_network) else [])
       +
       ([matrix_ma1sd_container_network] if (matrix_ma1sd_enabled and matrix_synapse_account_threepid_delegates_msisdn == matrix_synapse_account_threepid_delegates_msisdn_mas1sd_url and matrix_synapse_container_network != matrix_ma1sd_container_network) else [])
+      +
+      ([matrix_bot_draupnir_container_network] if (matrix_synapse_ext_synapse_http_antispam_enabled and matrix_synapse_ext_synapse_http_antispam_config_base_url == matrix_bot_draupnir_synapse_http_antispam_config_base_url and matrix_bot_draupnir_container_network != matrix_synapse_container_network) else [])
     ) | unique
   }}
 
@@ -4930,6 +4935,13 @@ matrix_synapse_app_service_config_files_auto: "{{ matrix_homeserver_app_service_
 # Disable creation of media repository Synapse worker when using media-repo
 matrix_synapse_ext_media_repo_enabled: "{{ matrix_media_repo_enabled }}"
 
+matrix_synapse_ext_synapse_http_antispam_enabled: "{{ matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled }}"
+matrix_synapse_ext_synapse_http_antispam_config_base_url: "{{ matrix_bot_draupnir_synapse_http_antispam_config_base_url if matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled else '' }}"
+matrix_synapse_ext_synapse_http_antispam_config_authorization: "{{ matrix_bot_draupnir_config_web_synapseHTTPAntispam_authorization if matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled else '' }}"
+matrix_synapse_ext_synapse_http_antispam_config_enabled_callbacks: "{{ matrix_bot_draupnir_synapse_http_antispam_config_enabled_callbacks if matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled else [] }}"
+matrix_synapse_ext_synapse_http_antispam_config_fail_open: "{{ matrix_bot_draupnir_synapse_http_antispam_config_fail_open if matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled else {} }}"
+matrix_synapse_ext_synapse_http_antispam_config_async: "{{ matrix_bot_draupnir_synapse_http_antispam_config_async if matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled else {} }}"
+
 # Enable Synapse statistics reporting when using synapse-usage-exporter
 matrix_synapse_report_stats: "{{ matrix_synapse_usage_exporter_enabled }}"
 matrix_synapse_report_stats_endpoint: "{{ (('http://' + matrix_synapse_usage_exporter_identifier + ':' + matrix_synapse_usage_exporter_container_port | string + '/report-usage-stats/push') if matrix_synapse_usage_exporter_enabled else '') }}"

roles/custom/matrix-bot-draupnir/defaults/main.yml

@@ -28,8 +28,18 @@ matrix_bot_draupnir_config_path: "{{ matrix_bot_draupnir_base_path }}/config"
 matrix_bot_draupnir_data_path: "{{ matrix_bot_draupnir_base_path }}/data"
 matrix_bot_draupnir_docker_src_files_path: "{{ matrix_bot_draupnir_base_path }}/docker-src"
 
+matrix_bot_draupnir_config_web_enabled: "{{ matrix_bot_draupnir_config_web_abuseReporting or matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled }}"  # noqa var-naming
+
 matrix_bot_draupnir_config_web_abuseReporting: false  # noqa var-naming
-matrix_bot_draupnir_config_web_enabled: "{{ matrix_bot_draupnir_config_web_abuseReporting }}"  # noqa var-naming
+
+matrix_bot_draupnir_config_web_port: 8080
+
+# These variables are used for turning on the integration between the synapseHTTPAntispam module and Draupnir.
+# Authorisation is a shared secret between Draupnir and the module just like is used by Appservices and the homeserver
+# therefore the same creation mechanism is used here too.
+matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled: false  # noqa var-naming
+matrix_bot_draupnir_config_web_synapseHTTPAntispam_authorization: ''  # noqa var-naming
+
 matrix_bot_draupnir_config_displayReports: "{{ matrix_bot_draupnir_config_web_abuseReporting }}"  # noqa var-naming
 
 matrix_bot_draupnir_container_network: ""
@@ -129,6 +139,27 @@ matrix_bot_draupnir_config_admin_enableMakeRoomAdminCommand: false  # noqa var-n
 # This config option has diminished improvements for bots on extremely fast homeservers or very very small bots on fast homeservers.
 matrix_bot_draupnir_config_roomStateBackingStore_enabled: true  # noqa var-naming
 
+matrix_bot_draupnir_web_url: 'http://matrix-bot-draupnir'
+
+# This controls the URL that the module targets in Draupnir.
+matrix_bot_draupnir_synapse_http_antispam_config_base_url: "{{ matrix_bot_draupnir_web_url }}:{{ matrix_bot_draupnir_config_web_port }}/api/1/spam_check"
+
+# These variables control the configuration of the Synapse module as the configuration is highly consumer dependent.
+# Therefore the module is configured from Draupnir because the consumer of the module determines what settings are relevant.
+
+matrix_bot_draupnir_synapse_http_antispam_config_enabled_callbacks:
+   - check_event_for_spam: true
+   - user_may_invite: true
+   - user_may_join_room: true
+
+matrix_bot_draupnir_synapse_http_antispam_config_fail_open:
+  check_event_for_spam: true
+  user_may_invite: true
+  user_may_join_room: true
+
+matrix_bot_draupnir_synapse_http_antispam_config_async:
+  check_event_for_spam: true
+
 # Default configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
 #

roles/custom/matrix-bot-draupnir/templates/labels.j2

@@ -12,7 +12,7 @@ traefik.enable=true
 traefik.docker.network={{ matrix_bot_draupnir_container_labels_traefik_docker_network }}
 {% endif %}
 
-traefik.http.services.matrix-bot-draupnir.loadbalancer.server.port=8080
+traefik.http.services.matrix-bot-draupnir.loadbalancer.server.port={{ matrix_bot_draupnir_config_web_port }}
 
 {% if matrix_bot_draupnir_config_web_abuseReporting %}
 ############################################################

roles/custom/matrix-bot-draupnir/templates/production.yaml.j2

@@ -266,7 +266,7 @@ web:
   enabled: true
 
   # The port to expose the webserver on. Defaults to 8080.
-  port: 8080
+  port: {{ matrix_bot_draupnir_config_web_port | to_json }}
 
   # The address to listen for requests on. Defaults to only the current
   # computer.
@@ -286,6 +286,18 @@ web:
   abuseReporting:
     # Whether to enable this feature.
     enabled: {{ matrix_bot_draupnir_config_web_abuseReporting | to_json }}
+  # Whether to setup a endpoints for synapse-http-antispam
+  # https://github.com/maunium/synapse-http-antispam
+  # this is required for some features of Draupnir,
+  # such as support for room takedown policies.
+  #
+  # Please FOLLOW the instructions here:
+  # https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse-http-antispam
+  synapseHTTPAntispam:
+    enabled: {{ matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled | to_json }}
+    # This is a secret that you must place into your synapse module config
+    # https://github.com/maunium/synapse-http-antispam?tab=readme-ov-file#configuration
+    authorization: {{ matrix_bot_draupnir_config_web_synapseHTTPAntispam_authorization | to_json }}
 {% endif %}
 
 # FIXME: This configuration option is currently broken in the playbook as admin APIs cannot

roles/custom/matrix-bot-draupnir/templates/systemd/matrix-bot-draupnir.service.j2

@@ -25,7 +25,7 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			--read-only \
 			--network={{ matrix_bot_draupnir_container_network }} \
 			{% if matrix_bot_draupnir_container_http_host_bind_port %}
-			-p {{ matrix_bot_draupnir_container_http_host_bind_port }}:8080 \
+			-p {{ matrix_bot_draupnir_container_http_host_bind_port }}:{{ matrix_bot_draupnir_config_web_port }} \
 			{% endif %}
 			--label-file={{ matrix_bot_draupnir_base_path }}/labels \
 			--mount type=bind,src={{ matrix_bot_draupnir_config_path }},dst=/data/config,ro \

roles/custom/matrix-synapse/defaults/main.yml

@@ -1412,6 +1412,38 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config:
   ban_lists: "{{ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists }}"
   message_max_length: "{{ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_message_max_length }}"
 
+# Enable this to activate the synapse-http-antispam module.
+# See: github.com/maunium/synapse-http-antispam
+matrix_synapse_ext_synapse_http_antispam_enabled: false
+matrix_synapse_ext_synapse_http_antispam_git_repository_url: "https://github.com/maunium/synapse-http-antispam"
+# renovate: datasource=github-releases depName=maunium/synapse-http-antispam
+matrix_synapse_ext_synapse_http_antispam_git_version: "v0.3.0"
+# Where Synapse can locate the consumer of the antispam API. Currently
+# Draupnir is the only consumer of this API that is playbook supported.
+# But https://github.com/maunium/meowlnir also supports the API.
+matrix_synapse_ext_synapse_http_antispam_config_base_url: ''
+# This is a shared secret that is established between the consumer and the
+# homeserver a lot like how AS authentication is done. This is fully managed
+# the same way AS authentication is by the playbook.
+matrix_synapse_ext_synapse_http_antispam_config_authorization: ''
+# This controls what callbacks are activated. This list is fully dependent on what consumer is in play.
+# And what capabilities said consumer should or shouldn't have. There are also performance implications
+# to these choices.
+matrix_synapse_ext_synapse_http_antispam_config_enabled_callbacks: []
+# Controls if a loss of connectivity to the consumer results in fail open or closed.
+# As in if failure results in events getting flagged automatically as spam or not.
+matrix_synapse_ext_synapse_http_antispam_config_fail_open: {}
+# Controls if the checking is blocking or not. This allows the homeserver to skip waiting for a consumer response.
+matrix_synapse_ext_synapse_http_antispam_config_async: {}
+# Actual configuration passed to the synapse-http-antispam module
+matrix_synapse_ext_synapse_http_antispam_config: "{{ matrix_synapse_ext_synapse_http_antispam_config_yaml | from_yaml }}"
+matrix_synapse_ext_synapse_http_antispam_config_yaml: |
+  base_url: {{ matrix_synapse_ext_synapse_http_antispam_config_base_url | to_json }}
+  authorization: {{ matrix_synapse_ext_synapse_http_antispam_config_authorization | to_json }}
+  enabled_callbacks: {{ matrix_synapse_ext_synapse_http_antispam_config_enabled_callbacks | to_json }}
+  fail_open: {{ matrix_synapse_ext_synapse_http_antispam_config_fail_open | to_json }}
+  async: {{ matrix_synapse_ext_synapse_http_antispam_config_async | to_json }}
+
 # Enable this to activate the E2EE disabling Synapse module.
 # See: https://github.com/digitalentity/matrix_encryption_disabler
 matrix_synapse_ext_encryption_disabler_enabled: false

roles/custom/matrix-synapse/tasks/ext/setup_install.yml

@@ -66,6 +66,19 @@
     - when: matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled | bool
       ansible.builtin.include_tasks: "{{ role_path }}/tasks/ext/mjolnir-antispam/setup_install.yml"
 
+# synapse-http-antispam
+- tags:
+    - setup-all
+    - setup-synapse
+    - install-all
+    - install-synapse
+  block:
+    - when: matrix_synapse_ext_synapse_http_antispam_enabled  | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/ext/synapse-http-antispam/validate_config.yml"
+
+    - when: matrix_synapse_ext_synapse_http_antispam_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/ext/synapse-http-antispam/setup_install.yml"
+
 # s3-storage-provider
 - tags:
     - setup-all

roles/custom/matrix-synapse/tasks/ext/synapse-http-antispam/setup_install.yml

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2025 MDAD project contributors
+# SPDX-FileCopyrightText: 2025 Catalan Lover <catalanlover@protonmail.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure git installed
+  ansible.builtin.package:
+    name: git
+    state: present
+
+- name: Clone synapse-http-antispam git repository
+  ansible.builtin.git:
+    repo: "{{ matrix_synapse_ext_synapse_http_antispam_git_repository_url }}"
+    version: "{{ matrix_synapse_ext_synapse_http_antispam_git_version }}"
+    dest: "{{ matrix_synapse_ext_path }}/synapse-http-antispam"
+  become: true
+  become_user: "{{ matrix_synapse_username }}"
+
+- ansible.builtin.set_fact:
+    matrix_synapse_modules: >
+      {{
+        matrix_synapse_modules | default([])
+        +
+        [{
+          "module": "synapse_http_antispam.HTTPAntispam",
+          "config": matrix_synapse_ext_synapse_http_antispam_config,
+        }]
+      }}
+
+    matrix_synapse_container_extra_arguments: >
+      {{
+        matrix_synapse_container_extra_arguments | default([])
+        +
+        ["--mount type=bind,src={{ matrix_synapse_ext_path }}/synapse-http-antispam/synapse_http_antispam.py,dst={{ matrix_synapse_in_container_python_packages_path }}/synapse_http_antispam.py,ro"]
+      }}

roles/custom/matrix-synapse/tasks/ext/synapse-http-antispam/setup_uninstall.yml

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2025 MDAD project contributors
+# SPDX-FileCopyrightText: 2025 Catalan Lover <catalanlover@protonmail.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure synapse-http-antispam doesn't exist
+  ansible.builtin.file:
+    path: "{{ matrix_synapse_ext_path }}/synapse-http-antispam"
+    state: absent

roles/custom/matrix-synapse/tasks/ext/synapse-http-antispam/validate_config.yml

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 MDAD project contributors
+# SPDX-FileCopyrightText: 2025 Catalan Lover <catalanlover@protonmail.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+- name: Fail if required synapse-http-antispam settings not defined
+  ansible.builtin.fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) for using synapse-http-antispam.
+  when: "vars[item] == ''"
+  with_items:
+    - "matrix_synapse_ext_synapse_http_antispam_enabled"
+    - "matrix_synapse_ext_synapse_http_antispam_config_base_url"
+    - "matrix_synapse_ext_synapse_http_antispam_config_authorization"
+
+- name: Fail if required matrix_synapse_ext_synapse_http_antispam_config_base_url looks invalid
+  ansible.builtin.fail:
+    msg: >-
+      `matrix_synapse_ext_synapse_http_antispam_config_base_url` needs to look like a URL (`http://` or `https://` prefix).
+  when: "not matrix_synapse_ext_synapse_http_antispam_config_base_url.startswith('http')"