From b532607e8a7584b28d6798dc3d5dc5fa3dc84149 Mon Sep 17 00:00:00 2001
From: teutat3s <10206665+teutat3s@users.noreply.github.com>
Date: Wed, 13 Jul 2022 18:40:03 +0200
Subject: [PATCH] Implement MSC 1929 Homeserver Admin Contact Fixes #1612

For details to the proposed (not accepted yet) MSC, see:
https://github.com/matrix-org/matrix-spec-proposals/blob/hs/proposal-admin-contact-1/proposals/1929-admin-contact.md
---
 docs/configuring-well-known.md                | 36 +++++++++++++++++++
 roles/matrix-base/defaults/main.yml           | 24 +++++++++++++
 roles/matrix-base/tasks/setup_well_known.yml  |  8 +++++
 .../static-files/well-known/matrix-support.j2 |  9 +++++
 .../tasks/setup_well_known.yml                |  8 +++++
 5 files changed, 85 insertions(+)
 create mode 100644 roles/matrix-base/templates/static-files/well-known/matrix-support.j2

diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md
index 36e53996b..35b969319 100644
--- a/docs/configuring-well-known.md
+++ b/docs/configuring-well-known.md
@@ -36,6 +36,41 @@ However, this playbook installs your Matrix server on another domain (e.g. `matr
 To learn how to set it up, read the Installing section below.
 
 
+## (Optional) Introduction to Homeserver Admin Contact and Support page
+
+[MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service.
+
+This MSC did not get accepted yet, but we think it might already be useful to Homeserver admins who wish to provide this information to end-users.
+
+The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_homeserver_admin_contacts` and `matrix_homeserver_support_url`.
+
+Example snippet for `vars.yml`:
+```
+# Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929
+matrix_homeserver_admin_contacts: |
+  [
+    {
+      "matrix_id": "@admin1:domain.tld",
+      "email_address": "admin@domain.tld",
+      "role": "admin"
+    },
+    {
+      "matrix_id": "@admin2:domain.tld",
+      "email_address": "admin@domain.tld",
+      "role": "admin"
+    },
+    {
+      "email_address": "security@domain.tld",
+      "role": "security"
+    }
+  ]
+
+matrix_homeserver_support_url: "https://example.domain.tld/support"
+```
+
+To learn how to set up `/.well-known/matrix/support` for the base domain, read the Installing section below.
+
+
 ## Installing well-known files on the base domain's server
 
 To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.
@@ -185,5 +220,6 @@ No matter which method you've used to set up the well-known files, if you've don
 
 - `https://<domain>/.well-known/matrix/server`
 - `https://<domain>/.well-known/matrix/client`
+- `https://<domain>/.well-known/matrix/support`
 
 You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).
diff --git a/roles/matrix-base/defaults/main.yml b/roles/matrix-base/defaults/main.yml
index 9b6d45f84..244b4916f 100644
--- a/roles/matrix-base/defaults/main.yml
+++ b/roles/matrix-base/defaults/main.yml
@@ -12,6 +12,18 @@ matrix_domain: ~
 # Example value: "@someone:{{ matrix_domain }}"
 matrix_admin: ''
 
+# Homeserver admin contacts and support page as per MSC 1929
+# See: https://github.com/matrix-org/matrix-spec-proposals/pull/1929
+#
+# Users in form:
+# [
+#   { "matrix_id": "@admin:domain.tld", "email_address": "admin@domain.tld", "role": "admin" },
+#   { "email_address": "security@domain.tld", "role": "security" }
+# ]
+matrix_homeserver_admin_contacts: []
+# Url string like https://domain.tld/support.html
+matrix_homeserver_support_url: ''
+
 # This will contain the homeserver implementation that is in use.
 # Valid values: synapse, dendrite
 #
@@ -225,6 +237,18 @@ matrix_well_known_matrix_server_configuration_extension: "{{ matrix_well_known_m
 # You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_server_configuration_default` and `matrix_well_known_matrix_server_configuration_extension_json`.
 matrix_well_known_matrix_server_configuration: "{{ matrix_well_known_matrix_server_configuration_default|combine(matrix_well_known_matrix_server_configuration_extension, recursive=True) }}"
 
+# The side-effect of this lookup is that Ansible would even parse the JSON for us, returning a dict.
+# This is unlike what it does when looking up YAML template files (no automatic parsing there).
+matrix_well_known_matrix_support_configuration_default: "{{ lookup('template', 'templates/static-files/well-known/matrix-support.j2') }}"
+
+matrix_well_known_matrix_support_configuration_extension_json: '{}'
+
+matrix_well_known_matrix_support_configuration_extension: "{{ matrix_well_known_matrix_support_configuration_extension_json|from_json if matrix_well_known_matrix_support_configuration_extension_json|from_json is mapping else {} }}"
+
+# Holds the final `/.well-known/matrix/support` configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_support_configuration_default` and `matrix_well_known_matrix_support_configuration_extension_json`.
+matrix_well_known_matrix_support_configuration: "{{ matrix_well_known_matrix_support_configuration_default|combine(matrix_well_known_matrix_support_configuration_extension, recursive=True) }}"
+
 # The Docker network that all services would be put into
 matrix_docker_network: "matrix"
 
diff --git a/roles/matrix-base/tasks/setup_well_known.yml b/roles/matrix-base/tasks/setup_well_known.yml
index 3f475950b..44ef3d28a 100644
--- a/roles/matrix-base/tasks/setup_well_known.yml
+++ b/roles/matrix-base/tasks/setup_well_known.yml
@@ -35,3 +35,11 @@
     path: "{{ matrix_static_files_base_path }}/.well-known/matrix/server"
     state: absent
   when: "not matrix_well_known_matrix_server_enabled|bool"
+
+- name: Ensure Matrix /.well-known/matrix/support file configured
+  copy:
+    content: "{{ matrix_well_known_matrix_support_configuration|to_nice_json }}"
+    dest: "{{ matrix_static_files_base_path }}/.well-known/matrix/support"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
diff --git a/roles/matrix-base/templates/static-files/well-known/matrix-support.j2 b/roles/matrix-base/templates/static-files/well-known/matrix-support.j2
new file mode 100644
index 000000000..b22c40aaf
--- /dev/null
+++ b/roles/matrix-base/templates/static-files/well-known/matrix-support.j2
@@ -0,0 +1,9 @@
+#jinja2: lstrip_blocks: "True"
+{
+	{% if matrix_homeserver_admin_contacts %}
+    "admins": {{ matrix_homeserver_admin_contacts }}
+	{% endif %}
+	{% if matrix_homeserver_support_url %},
+    "support_page": "{{ matrix_homeserver_support_url }}"
+	{% endif %}
+}
diff --git a/roles/matrix-nginx-proxy/tasks/setup_well_known.yml b/roles/matrix-nginx-proxy/tasks/setup_well_known.yml
index 1c85552c3..48727725a 100644
--- a/roles/matrix-nginx-proxy/tasks/setup_well_known.yml
+++ b/roles/matrix-nginx-proxy/tasks/setup_well_known.yml
@@ -23,3 +23,11 @@
     mode: 0644
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
+
+- name: Ensure Matrix /.well-known/matrix/support configured
+  template:
+    src: "{{ role_path }}/templates/well-known/matrix-support.j2"
+    dest: "{{ matrix_static_files_base_path }}/.well-known/matrix"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"