From c7942d1cecda30511a10d5b971cb58bb30fa9be3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Feb 2020 21:58:57 -0700 Subject: [PATCH] Spec moderation policy rooms (MSC2313) MSC: https://github.com/matrix-org/matrix-doc/pull/2313 --- event-schemas/examples/m.policy.rule.room | 10 ++ event-schemas/examples/m.policy.rule.server | 10 ++ event-schemas/examples/m.policy.rule.user | 10 ++ event-schemas/moderation_policy_rule.yaml | 30 ++++ event-schemas/schema/m.policy.rule.room | 15 ++ event-schemas/schema/m.policy.rule.server | 15 ++ event-schemas/schema/m.policy.rule.user | 15 ++ specification/feature_profiles.rst | 2 + specification/modules/moderation_policies.rst | 129 ++++++++++++++++++ specification/targets.yaml | 1 + 10 files changed, 237 insertions(+) create mode 100644 event-schemas/examples/m.policy.rule.room create mode 100644 event-schemas/examples/m.policy.rule.server create mode 100644 event-schemas/examples/m.policy.rule.user create mode 100644 event-schemas/moderation_policy_rule.yaml create mode 100644 event-schemas/schema/m.policy.rule.room create mode 100644 event-schemas/schema/m.policy.rule.server create mode 100644 event-schemas/schema/m.policy.rule.user create mode 100644 specification/modules/moderation_policies.rst diff --git a/event-schemas/examples/m.policy.rule.room b/event-schemas/examples/m.policy.rule.room new file mode 100644 index 00000000..5a532cb5 --- /dev/null +++ b/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" + } +} diff --git a/event-schemas/examples/m.policy.rule.server b/event-schemas/examples/m.policy.rule.server new file mode 100644 index 00000000..3d740a28 --- /dev/null +++ b/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" + } +} diff --git a/event-schemas/examples/m.policy.rule.user b/event-schemas/examples/m.policy.rule.user new file mode 100644 index 00000000..eb3832da --- /dev/null +++ b/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" + } +} diff --git a/event-schemas/moderation_policy_rule.yaml b/event-schemas/moderation_policy_rule.yaml new file mode 100644 index 00000000..34ad4d9a --- /dev/null +++ b/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 diff --git a/event-schemas/schema/m.policy.rule.room b/event-schemas/schema/m.policy.rule.room new file mode 100644 index 00000000..ff81543e --- /dev/null +++ b/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 diff --git a/event-schemas/schema/m.policy.rule.server b/event-schemas/schema/m.policy.rule.server new file mode 100644 index 00000000..ca37e8ff --- /dev/null +++ b/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 diff --git a/event-schemas/schema/m.policy.rule.user b/event-schemas/schema/m.policy.rule.user new file mode 100644 index 00000000..4fa65ad8 --- /dev/null +++ b/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 diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index bb638380..8a3caf87 100644 --- a/specification/feature_profiles.rst +++ b/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 ------- diff --git a/specification/modules/moderation_policies.rst b/specification/modules/moderation_policies.rst new file mode 100644 index 00000000..8992ceb1 --- /dev/null +++ b/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.`` 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 `_-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 `_ +and `MSC1777 `_ (or similar) could +help solve this concern. diff --git a/specification/targets.yaml b/specification/targets.yaml index 2cd911ba..4e0b068d 100644 --- a/specification/targets.yaml +++ b/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: ["=", "-", "~", "+", "^", "`", "@", ":"]