MSC1929: Homeserver Admin Contact and Support page

proposals/1929-admin-contact.md

@@ -0,0 +1,71 @@
+# MSC1929 Homeserver Admin Contact and Support page
+
+Currently, contacting a homeserver admin is difficult because you need to have insider knowledge
+of who the admin actually is. This proposal aims to fix that by specifying 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 proposal aims to fix https://github.com/matrix-org/matrix-doc/issues/484
+
+## Proposal
+
+The proposal suggests adding a new endpoint: `https://{hostname}/.well-known/matrix/support`,
+where `hostname` is the server name, without the port number.  This is the same as what is used
+when performing server discovery.
+
+The response format should be:
+
+```json5
+{
+    "contacts": [
+        {
+            "matrix_id": "@admin:domain.tld",
+            "email_address": "[email protected]",
+            "role": "m.role.admin"
+        },
+        {
+            "email_address": "[email protected]",
+            "role": "m.role.security"
+        }
+    ],
+    "support_page": "https://domain.tld/support.html"
+}
+```
+
+The `contacts` array is optional, but recommended.
+
+The `matrix_id` and `email_address` do NOT need to have the same domain as the homeserver. It is expected that
+an admin will have a "backup" contact address if the server is down, like an email or alternative mxid on a different homeserver.
+
+Entries may have a `matrix_id` OR an `email_address`, but at least one MUST be specified.
+
+`role` is an informal description of what the address(es) are used for. The only two specified in this
+proposal are `m.role.admin` and `m.role.security`. 
+
+ - `m.role.admin` is a catch-all user for any queries.
+ - `m.role.security` is intended for sensitive requests
+
+Implementors may use custom values for role for other purposes, but it's suggested
+that the value be namespaced to prevent collisions. A value for `role` MUST be specified.
+
+`support_page` is an optional property to specify a affiliated page of the homserver to give users help
+specific to the homeserver, like extra login/registration steps.
+
+At least one valid key should be provided. This means `contacts` should have at least one entry, or the `support_page` should be defined. An empty object is not considered valid, however both `contacts `and `support_page` may be specified together. 
+
+## Alternative solutions
+
+Hardcode a given user localpart that should be used as an admin address.
+ - The account would need to either internally redirect messages intended for @admin:domain.tld to another account(s)
+ - OR require an admin to regularly sign into this special account to check for messages. Neither of which is useful.
+
+Specify the same content inside a homeserver endpoint, rather than use `.well-known`.
+ - This requires the homeserver to be up or responsive, which might be not very useful if trying to report issues with
+   connectivity.
+
+Use vCards.
+ - vCards would add bloat, as the vast majority of a vcards contents is not useful for contacting an admin.
+
+## Security considerations
+
+If the host is compromised, any information could be specified in the well known file which may direct users to send
+sensitive information to a malicious user.