...

This specification outlines how to achieve “channel moderation” feature in Mattermost. Channel moderation provides system administrators with admins—and in future channel admins—with toggles to enable and disable various channel-level features including:

• Making a channel read-only to everyone except channel admins

• Disallowing adding a removing members by everyone except channel admins

• Disabling “read-only” (or the inverse, enabling posting) for members and guests

• Allowing/disallowing members and guest from adding and removing other members

• Allowing/disallowing members and guests from using channel-mentions (@all, @channel, @here for everyone except channel admins)

GOALS

1. Describe the backend architecture and required changes.

2. Describe the (general) webapp changes required.

3. Describe the mobile changes required.

SCOPE

This document will describe describes the backend approach including , new API endpoints required and the changes that will occur in the database.

It will generally describe the webapp changes required.

It will not outline mobile (React Native) , database changes, webapp changes, and mobile app changes.

BACKGROUND READING

...

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119

• “higher-scoped scheme”: the system scheme or team scheme from which the channel derives all of its permissions in the absence of a channel scheme.

SPECIFICATIONS

High-level Architecture

The Channel Moderation feature leverages the existing permissions system to create a “Channel Override Scheme” channel scheme for each channel for which channel moderation is enabled. 

Enabling moderation for a given channel creates a record in the Schemes table with a Scope of “channel” and value channel. It also creates two new Roles records. The new Roles records initially copy their Permissions value from the higher-scoped scheme (system scheme or team scheme). 

Permissions A set of the permissions associated to the new channel scheme’s Guest guest and Member roles member can subsequently be edited to affect the given channel, allowing for custom permission for the given channelprovide users with those roles in that channel different permissions—in the context of the channel—than the configured on the higher-scoped schemes.

If moderation is turned off for a given disabled, the channel the Schemes record is deleted and the channel members automatically go back to using and guests automatically revert having the permissions as configured on the higher-scoped scheme.Any

Pseudo-relationship between channel schemes its higher-scoped scheme

Per the permissions system design a channel scheme completely overrides all channel-scoped permissions for the given channel. This means that if there are permissions that are not exposed in by channel moderation, admins will expect those permissions to be configured as per the higher-scoped scheme—lest permissions be overridden behind the scenes on the channel scheme without the knowledge of admins. Since there is no “inheritance” as such between the schemes, all channel-scoped permissions that are not modified by the channel moderation UI but are configurable in the system schemes and team schemes UI must be kept in sync with the channel scheme, namely:use_slash_commandsmust be updated on the channel scheme upon each change to the higher-scoped scheme.

Channel-scoped permissions are the only type of permissions that can be used by channel-scoped schemes and thus they’re the only ones modifiable by channel moderation settings and also the only ones that must be updated per changes to the higher-scoped scheme.

Actions that trigger synchronization of permissions from high-scoped schemes to channel schemes:

Updates to all channel schemes:

• add a channel-scoped permission to the system scheme

• remove a channel-scoped permission from the system scheme

Updates to all of the channel schemes for a given team:

• add a channel-scoped permission to a team scheme with an associated team

• remove a channel-scoped permissions from a team scheme with an associated team

• add a team to a team scheme

• remove a team from a team scheme

Permissions

New permission:

A new permission named use_channel_mentions has been created, without which users are not able to use @all, @channel, and @here.

Guest role permissions modified by channel moderation:

edit_post
delete_post
add_reaction/remove_reaction
create_post
use_channel_mentions

Member role permissions modified by channel moderation:

manage_public_channel_members/manage_private_channel_members
edit_post
edit_others_posts
delete_post
delete_others_posts
add_reaction/remove_reaction
create_post
use_channel_mentions

All other channel-scoped permissions on channel schemes' associated Rolesrecords are kept synchronized with their higher-scoped scheme (some are not exposed via the UI but they will be synchronized none-the-less to maintain parity with the API rather than a single client’s UI):

manage_public_channel_properties
manage_private_channel_properties… (TODO)
delete_public_channel
delete_private_channel
remove_others_reactions
upload_file
create_post_public
create_post_ephemeral
manage_channel_roles
read_channel

Question: Do we need to expose create_post and use_channel_mentions in the system and team schemes UI?

Schema

There are no schema changes.

REST API

When the “enable channel moderation” toggle is flipped on (wording as per design) is toggled on, a POST request is made to the existing API endpoint /api/v4/schemes (existing) to create the channel scheme.

The new roles Roles records that are created will be updated to match the permissions Permissions value from the higher-scoped scheme. Note that this may already be existing behaviour.Question: Can the DefaultChannelAdminRole id be set to the value of the higher-scoped scheme’s role? Is that feasible and helpful because it decreases the number of permissions that need to be updated or does it add complexity?When the “enable channel moderation” toggle is flipped off does it already copy the permissions from the previous scheme? If so then no update is required. If not can we consider making that a permanent part of the create team and channel scheme API behaviour, avoiding a separate update?

When “enable channel moderation” toggled off, a DELETE request is made to /api/v4/schemes/:scheme_id. 

Question: Does the delete scheme API endpoint cleanup orphaned Roles records? If not does it make sense to make that a permanent part of the API behaviour?

CLI

TBDOut of scope.

Configuration

None needed.

Frontend

A new toggle UI element must be added to the channel details view to create the channel scheme. UI still pending.

UI also still pending for the actual channel moderation block that is displayed once channel moderation is enabled.

Performance

...

TBD

Performance

If the synchronization of permissions (triggered by the events listed above in “Actions that trigger synchronization of permissions from high-scoped schemes to channel schemes”) occur synchronously then those actions will incur a performance degradation.

If the actions occur asynchronously in a background job then the actions will not incur a performance degradation.

Plugins

TBD

CREDITS

Give credit here to anyone who helped you write the spec or provided feedback to improve it.