From 56e00ca85e502247112a95ab8c452c83ab5fc4b0 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Fri, 18 Dec 2020 11:01:57 -0500
Subject: [PATCH] Send the location of the web client to the IS when inviting
 via 3PIDs. (#8930)

Adds a new setting `email.invite_client_location` which, if defined, is
passed to the identity server during invites.
---
 changelog.d/8930.feature      |  1 +
 docs/sample_config.yaml       |  6 ++++++
 synapse/config/emailconfig.py | 22 ++++++++++++++++++++++
 synapse/handlers/identity.py  |  5 +++++
 4 files changed, 34 insertions(+)
 create mode 100644 changelog.d/8930.feature

diff --git a/changelog.d/8930.feature b/changelog.d/8930.feature
new file mode 100644
index 000000000..cb305b526
--- /dev/null
+++ b/changelog.d/8930.feature
@@ -0,0 +1 @@
+Add an `email.invite_client_location` configuration option to send a web client location to the invite endpoint on the identity server which allows customisation of the email template.
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 077cb619c..0b4dd115f 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -2149,6 +2149,12 @@ email:
   #
   #validation_token_lifetime: 15m
 
+  # The web client location to direct users to during an invite. This is passed
+  # to the identity server as the org.matrix.web_client_location key. Defaults
+  # to unset, giving no guidance to the identity server.
+  #
+  #invite_client_location: https://app.element.io
+
   # Directory in which Synapse will try to find the template files below.
   # If not set, or the files named below are not found within the template
   # directory, default templates from within the Synapse package will be used.
diff --git a/synapse/config/emailconfig.py b/synapse/config/emailconfig.py
index 7c8b64d84..d4328c46b 100644
--- a/synapse/config/emailconfig.py
+++ b/synapse/config/emailconfig.py
@@ -322,6 +322,22 @@ class EmailConfig(Config):
 
         self.email_subjects = EmailSubjectConfig(**subjects)
 
+        # The invite client location should be a HTTP(S) URL or None.
+        self.invite_client_location = email_config.get("invite_client_location") or None
+        if self.invite_client_location:
+            if not isinstance(self.invite_client_location, str):
+                raise ConfigError(
+                    "Config option email.invite_client_location must be type str"
+                )
+            if not (
+                self.invite_client_location.startswith("http://")
+                or self.invite_client_location.startswith("https://")
+            ):
+                raise ConfigError(
+                    "Config option email.invite_client_location must be a http or https URL",
+                    path=("email", "invite_client_location"),
+                )
+
     def generate_config_section(self, config_dir_path, server_name, **kwargs):
         return (
             """\
@@ -389,6 +405,12 @@ class EmailConfig(Config):
           #
           #validation_token_lifetime: 15m
 
+          # The web client location to direct users to during an invite. This is passed
+          # to the identity server as the org.matrix.web_client_location key. Defaults
+          # to unset, giving no guidance to the identity server.
+          #
+          #invite_client_location: https://app.element.io
+
           # Directory in which Synapse will try to find the template files below.
           # If not set, or the files named below are not found within the template
           # directory, default templates from within the Synapse package will be used.
diff --git a/synapse/handlers/identity.py b/synapse/handlers/identity.py
index 7301c2471..c05036ad1 100644
--- a/synapse/handlers/identity.py
+++ b/synapse/handlers/identity.py
@@ -55,6 +55,8 @@ class IdentityHandler(BaseHandler):
         self.federation_http_client = hs.get_federation_http_client()
         self.hs = hs
 
+        self._web_client_location = hs.config.invite_client_location
+
     async def threepid_from_creds(
         self, id_server: str, creds: Dict[str, str]
     ) -> Optional[JsonDict]:
@@ -803,6 +805,9 @@ class IdentityHandler(BaseHandler):
             "sender_display_name": inviter_display_name,
             "sender_avatar_url": inviter_avatar_url,
         }
+        # If a custom web client location is available, include it in the request.
+        if self._web_client_location:
+            invite_config["org.matrix.web_client_location"] = self._web_client_location
 
         # Add the identity service access token to the JSON body and use the v2
         # Identity Service endpoints if id_access_token is present