archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2434 from matrix-org/travis/spec/2313-moderation-policies

Browse Source 
Spec moderation policy rooms (MSC2313)
pull/977/head
Travis Ralston 5 years ago committed by GitHub
parent 7a878bb6c3 6d475ebd57
commit f823118a69
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 237 additions and 0 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/client_server/newsfragments/2434.feature
Unescape Escape View File

@ -0,0 +1 @@
Added data structures for defining moderation policies in rooms per `MSC2313 <https://github.com/matrix-org/matrix-doc/pull/2313>`_.

10
event-schemas/examples/m.policy.rule.room
Unescape Escape View File

@ -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"
}
}

10
event-schemas/examples/m.policy.rule.server
Unescape Escape View File

@ -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"
}
}

10
event-schemas/examples/m.policy.rule.user
Unescape Escape View File

@ -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"
}
}

30
event-schemas/moderation_policy_rule.yaml
Unescape Escape View File

@ -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

15
event-schemas/schema/m.policy.rule.room
Unescape Escape View File

@ -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

15
event-schemas/schema/m.policy.rule.server
Unescape Escape View File

@ -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

15
event-schemas/schema/m.policy.rule.user
Unescape Escape View File

@ -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

2
specification/feature_profiles.rst
Unescape Escape View File

@ -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
-------

128
specification/modules/moderation_policies.rst
Unescape Escape View File

@ -0,0 +1,128 @@
.. 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.

1
specification/targets.yaml
Unescape Escape View File

@ -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: ["=", "-", "~", "+", "^", "`", "@", ":"]

Write Preview
Loading…
Cancel
Save