Skip to content

msc1929.md

Latest commit

 

History

History
106 lines (69 loc) · 5.76 KB

msc1929.md

File metadata and controls

106 lines (69 loc) · 5.76 KB

MSC1929 — Homeserver Admin Contact and Support Page

Along with creating indexes and providing a human-friendly interface for vast Matrix Federation, Matrix Rooms Search integrates MSC1929 natively, in order to help homeserver administrators to combat unlawful actions like sharing illegal material on their server.

By integrating MSC1929, MRS enables the homeserver administrators (and/or room administrators) to be notified in case a room on the homeserver was reported via the UI.

Technical description

MRS supports /.well-known/matrix/support endpoint, thanks to github.com/etkecc/go-msc1929 library integration.

MRS parses MSC1929 contacts automatically during the discovery phase and store them into database. When a room is reported with the /mod/report/{room_id} endpoint, MRS will check whether the room's server has MSC1929 contact details. If email address(-es) are found, the report will be sent to the address to notify its homeserver's administrator.

MRS recognizes contact details of not only homeserver administrators on the /.well-known/matrix/support file but also room administrators on the room's topic. You can check this section below for details.

Email address priority

At first, MRS tries to find moderator email addresses. If none was found, it then tries to find administrator's email address (whose role is m.role.admin) on the MSC1929 file. If neither of them was found, it will at last try to find any other addresses in the file.

How to opt-in

There are two ways to make the contact details discoverable.

Add contact details to /.well-known/matrix/support file

You can add /.well-known/matrix/support file with the following structure:

{
  "contacts": [
    {
      "email_address": "your@email.here",
      "matrix_id": "@your:mxid.here",
      "role": "m.role.admin"
    }
  ]
}

File must be served on the homeserver name domain (@you:example.com -> https://example.com/.well-known/matrix/support)

Notes:

  • The file must be served on the homeserver name domain. If your MXID is @you:example.com, the file needs to be hosted at https://example.com/.well-known/matrix/support.
  • At this moment, MRS recognizes email addresses on the file only.

Add the file with "matrix-docker-ansible-deploy" Ansible playbook

If you use etke.cc/ansible and matrix-docker-ansible-deploy to manage your Matrix homeserver, you can create the file by adding the following to your vars.yml configuration file and running the playbook:

matrix_static_files_file_matrix_support_enabled: true
matrix_static_files_file_matrix_support_property_m_contacts:
  - matrix_id: "@you:example.com" # optional, remove if not needed
    email_address: "you@example.com" # required for MRS MSC1929 integration
    role: "m.role.admin"
matrix_homeserver_support_url: "https://example.com/help" # optional, remove if not needed

Add contact details to the room topic

If you are not homeserver's administrator but a room's administrator/moderator, you can still indicate that you want to be contacted in case the room is reported by adding special string to the room topic as below. The string will be recognized alongside the MSC1929 contacts (if any).

(MRS-email:your@email.address-MRS)

More details about room configuration

💡 Hint: the recommended place to add it is the end of the room topic, as MRS removes it from the room's topic when processing it and displaying the topic on the UI. This is technical information and not used for searching the room.

How to opt-out

You can opt-out by simply removing your email address from the MSC1929 file and/or the string from the room topic.

FAQ

Why MRS doesn't notify me when a room is reported?

Because the /.well-known/matrix/support file does not include an email address or the room topic does not contain the string for specifying contact details.

Please make sure that the file is served properly and includes more than one email address, and the contact detail on the room topic is correct if it is specified there.

How to check if the MSC1929 file is valid?

You can use the POST /discover/msc1929/{server_name} endpoint which MRS provides in order to check if the MSC1929 file is valid.

It will return 204 No Content if the file is valid, or 400 Bad Request if the file is invalid.

Here are possible error codes:

  • CC.ETKE.MSC1929_ERROR — something is entirely wrong, request to the MSC1929 file failed
  • CC.ETKE.MSC1929_EMPTY — the MSC1929 file is missing or empty (i.e., does not contain any actual data)
  • CC.ETKE.MSC1929_OUTDATED — the MSC1929 file uses old format (i.e., admins instead of contacts key)
  • CC.ETKE.MSC1929_NO_MXIDS — the MSC1929 file does not contain any Matrix IDs (i.e., matrix_id key inside contacts is missing)
  • CC.ETKE.MSC1929_NO_EMAILS — the MSC1929 file does not contain any emails (i.e., email_address key inside contacts is missing)
  • CC.ETKE.MSC1929_MISSING_ROLE — the MSC1929 file contains a contact without a role (i.e., role key inside contacts is missing)
  • CC.ETKE.MSC1929_UNSUPPORTED_ROLE — the MSC1929 file contains a contact with an unsupported role (i.e., role key inside contacts is not one of the supported roles)