Spec moderation policy rooms (MSC2313)

MSC: https://github.com/matrix-org/matrix-doc/pull/2313

event-schemas/examples/m.policy.rule.room

@@ -0,0 +1,10 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.policy.rule.room",
+  "state_key": "rule:#*:example.org",
+  "content": {
+    "entity": "#*:example.org",
+    "recommendation": "m.ban",
+    "reason": "undesirable content"
+  }
+}

event-schemas/examples/m.policy.rule.server

@@ -0,0 +1,10 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.policy.rule.server",
+  "state_key": "rule:*.example.org",
+  "content": {
+    "entity": "*.example.org",
+    "recommendation": "m.ban",
+    "reason": "undesirable engagement"
+  }
+}

event-schemas/examples/m.policy.rule.user

@@ -0,0 +1,10 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.policy.rule.user",
+  "state_key": "rule:@alice*:example.org",
+  "content": {
+    "entity": "@alice*:example.org",
+    "recommendation": "m.ban",
+    "reason": "undesirable behaviour"
+  }
+}

event-schemas/moderation_policy_rule.yaml

@@ -0,0 +1,30 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+properties:
+  entity:
+    description: |-
+      The entity affected by this rule. Glob characters ``*`` and ``?`` can be used
+      to match zero or more and one or more characters respectively.
+    type: string
+  recommendation:
+    description: The suggested action to take. Currently only ``m.ban`` is specified.
+    type: string
+  reason:
+    description: The human-readable description for the ``recommendation``.
+    type: string
+type: object
+required:
+  - entity
+  - recommendation
+  - reason

event-schemas/schema/m.policy.rule.room

@@ -0,0 +1,15 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: A moderation policy rule which affects room IDs and room aliases.
+properties:
+  content:
+    $ref: "../moderation_policy_rule.yaml"
+  state_key:
+    description: An arbitrary string decided upon by the sender.
+    type: string
+  type:
+    enum:
+      - m.policy.rule.room
+    type: string
+type: object

event-schemas/schema/m.policy.rule.server

@@ -0,0 +1,15 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: A moderation policy rule which affects servers.
+properties:
+  content:
+    $ref: "../moderation_policy_rule.yaml"
+  state_key:
+    description: An arbitrary string decided upon by the sender.
+    type: string
+  type:
+    enum:
+      - m.policy.rule.server
+    type: string
+type: object

event-schemas/schema/m.policy.rule.user

@@ -0,0 +1,15 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: A moderation policy rule which affects users.
+properties:
+  content:
+    $ref: "../moderation_policy_rule.yaml"
+  state_key:
+    description: An arbitrary string decided upon by the sender.
+    type: string
+  type:
+    enum:
+      - m.policy.rule.user
+    type: string
+type: object

specification/feature_profiles.rst

@@ -61,6 +61,7 @@ Summary
  `Stickers`_                           Optional   Optional   Optional   Optional   Optional
  `Server ACLs`_                        Optional   Optional   Optional   Optional   Optional
  `Server Notices`_                     Optional   Optional   Optional   Optional   Optional
+ `Moderation policies`_                Optional   Optional   Optional   Optional   Optional
 ===================================== ========== ========== ========== ========== ==========
 
 *Please see each module for more details on what clients need to implement.*
@@ -94,6 +95,7 @@ Summary
 .. _Stickers: `module:stickers`_
 .. _Server ACLs: `module:server-acls`_
 .. Server Notices already has a link elsewhere.
+.. _Moderation Policies: `module:moderation-policies`_
 
 Clients
 -------

specification/modules/moderation_policies.rst

@@ -0,0 +1,129 @@
+.. Copyright 2020 The Matrix.org Foundation C.I.C.
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Moderation policy lists
+=======================
+
+.. _module:moderation-policies:
+
+With Matrix being an open network where anyone can participate, a very wide
+range of content exists and it is important that users are empowered to select
+which content they wish to see, and which content they wish to block. By
+extension, room moderators and server admins should also be able to select
+which content they do not wish to host in their rooms and servers.
+
+The protocol's position on this is one of neutrality: it should not be deciding
+what content is undesirable for any particular entity and should instead be
+empowering those entities to make their own decisions. As such, a generic
+framework for communicating "moderation policy lists" or "moderation policy rooms"
+is described. Note that this module only describes the data structures and not
+how they should be interpreting: the entity making the decisions on filtering
+is best positioned to interpret the rules how it sees fit.
+
+Moderation policy lists are stored as room state events. There are no restrictions
+on how the rooms can be configured (they could be public, private, encrypted, etc).
+
+There are currently 3 kinds of entities which can be affected by rules: ``user``,
+``server``, and ``room``. All 3 are described with ``m.policy.rule.<kind>`` state
+events. The ``state_key`` for a policy rule is an arbitrary string decided by the
+sender of the rule.
+
+Rules contain recommendations and reasons for the rule existing. The ``reason``
+is a human-readable string which describes the ``recommendation``. Currently only
+one recommendation, ``m.ban``, is specified.
+
+``m.ban`` recommendation
+------------------------
+
+When this recommendation is used, the entities affected by the rule should be
+banned from participation where possible. The enforcement of this is deliberately
+left as an implementation detail to avoid the protocol imposing its opinion on how
+the policy list is to be interpreted. However, a suggestion for a simple implementation
+is as follows:
+
+* Is a ``user`` rule...
+
+  * Applied to a user: The user should be added to the subscriber's ignore list.
+  * Applied to a room: The user should be banned from the room (either on sight or immediately).
+  * Applied to a server: The user should not be allowed to send invites to users on the server.
+
+* Is a ``room`` rule...
+
+  * Applied to a user: The user should leave the room and not join it
+    (`MSC2270 <https://github.com/matrix-org/matrix-doc/pull/2270>`_-style ignore).
+  * Applied to a room: No-op because a room cannot ban itself.
+  * Applied to a server: The server should prevent users from joining the room and from receiving
+    invites to it.
+
+* Is a ``server`` rule...
+
+  * Applied to a user: The user should not receive events or invites from the server.
+  * Applied to a room: The server is added as a denied server in the ACLs.
+  * Applied to a server: The subscriber should avoid federating with the server as much as
+    possible by blocking invites from the server and not sending traffic unless strictly
+    required (no outbound invites).
+
+Subscribing to policy lists
+---------------------------
+
+This is deliberatly left as an implementation detail. For implementations using the
+Client-Server API, this could be as easy as joining or peeking the room. Joining or peeking
+is not required, however: an implementation could poll for updates or use a different
+technique for receiving updates to the policy's rules.
+
+Sharing
+-------
+
+In addition to sharing a direct reference to the room which contains the policy's rules,
+plain http or https URLs can be used to share links to the list. When the URL is approached
+with a ``Accept: application/json`` header or has ``.json`` appended to the end of the URL, it
+should return a JSON object containing a ``room_uri`` property which references the room.
+Currently this would be a ``matrix.to`` URI, however in future it could be a Matrix-schemed
+URI instead. When not approached with the intent of JSON, the service could return a
+user-friendly page describing what is included in the ban list.
+
+Events
+------
+
+The ``entity`` described by the state events can contain ``*`` and ``?`` to match zero or more
+and one or more characters respectively. Note that rules against rooms can describe a room ID
+or room alias - the subscriber is responsible for resolving the alias to a room ID if desired.
+
+{{m_policy_rule_user_event}}
+
+{{m_policy_rule_room_event}}
+
+{{m_policy_rule_server_event}}
+
+Client behaviour
+----------------
+As described above, the client behaviour is deliberatly left undefined.
+
+Server behaviour
+----------------
+Servers have no additional requirements placed on them by this module.
+
+
+Security considerations
+-----------------------
+This module could be used to build a system of shared blacklists, which may create
+a divide within established communities if not carefully deployed. This may well not
+be a suitable solution for all communities.
+
+Depending on how implementations handle subscriptions, user IDs may be linked to
+policy lists and therefore expose the views of that user. For example, a client implementation
+which joins the user to the policy room would expose the user's ID to observers of the
+policy room. In future, `MSC1228 <https://github.com/matrix-org/matrix-doc/pulls/1228>`_
+and `MSC1777 <https://github.com/matrix-org/matrix-doc/pulls/1777>`_ (or similar) could
+help solve this concern.

specification/targets.yaml

@@ -91,6 +91,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/mentions.rst
     - modules/room_upgrades.rst
     - modules/server_notices.rst
+    - modules/moderation_policies.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]