...

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

...

Making a channel “read-only” (or the inverse, enabling posting) for members and guests

...

Allowing or disallowing members and guest from adding and removing other members

...

members and/or guest of a given channel from performing the following:

• creating posts

• adding and removing members

• using channel mentions

GOALS

...

• exposing channel moderation in the system console in the channel details view

• updates to the UI (webapp and mobile) to apply the create_post permission

• updates to the UI (webapp and mobile) to apply the new usemention_channel_mentions permission

Out:

• CLI changes

• chat-facing administration of channel moderation settings

• plugin changes

• feature tracking

BACKGROUND READING

1. Channel Moderation Settings feature specification

2. High fidelity designs

...

“channel scheme”: a Schemes record with a Type value of channel. It overrides the permissions for given channels much like a team scheme overrides the permissions for a given team.

“moderated permissions”: permissions listed in the document overview that may be restricted on the channel level.

SPECIFICATIONS

High-level Architecture

The channel moderation feature leverages the existing permissions system to create a channel scheme for each channel for which moderation is enabled. Channel moderation is considered enabled if the channel has been configured to have any of the moderated permissions be more restrictive at the channel level than is configured on the channel’s higher-scoped scheme.

The channel scheme causes permissions to be overridden and configurable for the channel. More technically, a record is created in the Schemes table with a Scope value channel. Three new Roles records are also created and their Id Name values used to set the new Schemes record’s DefaultChannelAdminRole, DefaultChannelUserRole, and DefaultChannelGuestRoles. The new Roles records initially copy their Permissions value from the higher-scoped scheme’s associated Roles records.

Guest and member Roles records Permissions values ' moderated permissions are then updated as desired to change removed from the Permissions fields to further limit the permissions of the specific channel associated to the channel scheme.

If moderation is disabled for a channel, none of the moderated permissions are more restrictive than the higher-scoped scheme then the channel’s associated Schemes record is deleted and the channel members and guests automatically revert to using the permissions as configured on the higher-scoped scheme.

...

For example, say the higher-scoped scheme removes the “Archive Channels” permission (technically the delete_public_channel and delete_private_channel permissions). That permission is not configurable on the channel scheme given the current UI, so the system admin would not expect that permission to remain present for all channel that have moderation enabled, in spite of the fact that the permissions architecture would leave it present on the channel scheme by default. So we must have code that removes that permission from the channel scheme for all affected channels.

...

[vvv TBD vvv]

Since there is no “inheritance” as such between schemes, all channel-scoped permissions that are not modified by the channel moderation UI are 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 schemes, thus they’re the only permissions modifiable by channel moderation settings, and the only permissions that must be updated per changes to the higher-scoped scheme.

Question for dev: Instead of keeping the non-channel-moderated channel-scoped permissions synchronized between the higher-scoped scheme and the channel schemes could we change the core way the permissions system works to use the channel scheme for a set of permissions and the higher-scoped scheme for the rest?

The following actions trigger synchronization of permissions from high-scoped schemes to channel schemes:

...

• add a channel-scoped permission to a team scheme (if it has an associated team)

• remove a channel-scoped permissions from a team scheme (if it has an associated team)

• add a team to a team scheme

• remove a team from a team scheme

• delete a team scheme

• create a team scheme (if it has an associated team)

Question for Platform team: Is this synchronization compatible with the plan for the future custom roles?

[^^^ TBD ^^^]

...

Permissions

New permission:

A new permission named use_channel_mentions is created, without which users are not able to use channel mentions.mention_channel

Guest role permissions modified by channel moderation:edit_post
delete_post

add_reaction/remove_reaction
create_post
usemention_channel_mentions

Member role permissions modified by channel moderation:

add_reaction/remove_reaction
create_post
manage_public_channel_members/manage_private_channel_members
edit_post
edit_others_posts
mention_channel

Guest, member, and channel admin role channel-scoped permissions that must be read from (or replicated from) the higher-scoped scheme:

create_post_public
create_post_ephemeral
delete_post
/delete_others_posts
addedit_reactionpost/removeedit_reaction
createothers_postposts
usemanage_channel_mentionsGuest, member, and channel admin role permissions that are kept synchronized with the higher-scoped scheme:roles
manage_public_channel_properties
/manage_private_channel_properties
delete_public_channel
/delete_private_channel
read_channel
remove_others_reactions
upload_file
create_post_public
create_post_ephemeral
manage_channel_rolesread_channel

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

Schema

No schema changes.

REST API

• When “enable channel moderation” (see design for exact wording) is toggled on, a POST request is made to the existing API endpoint /api/v4/schemes to create the channel scheme.

The new Roles records that are created will be updated to match the Permissions value from the higher-scoped scheme (as described in the high-level architecture above).

• When “enable channel moderation” is toggled off, a DELETE request is made to /api/v4/schemes/:scheme_id. A new endpoint to get the channel moderation matrix. For example, to display the matrix as shown in the configuration from the high-fidelity mockups, the API endpoint GET /api/v4/channels/:channel_id/moderations returns the following:

[{
        "name": "create_post",
        "roles": {
            "guests": {
                "value": false,
                "enabled": true
            },
            "members": {
                "value": false,
                "enabled": true
            }
        }
    },
    {
        "name": "post_reactions",
        "roles": {
            "guests": {
                "value": false,
                "enabled": false
            },
            "members": {
                "value": true,
                "enabled": true
            }
        }
    },
    {
        "name": "manage_members",
        "roles": {
            "members": {
                "value": true,
                "enabled": true
            }
        }
    }, {
        "name": "mention_channel",
        "roles": {
            "guests": {
                "value": false,
                "enabled": true
            },
            "members": {
                "value": true,
                "enabled": true
            }
        }
    }
]

• A new endpoint to update the channel moderation configuration. For example, to re-add the ability for only members to create posts the API endpoint POST /api/v4/channels/:channel_id/moderations would receive:

[{
    "name": "create_post",
    "roles": {
        "members": true
    }
}]

• Update the create post flow (for example in mattermost-server/app/notifications.go) to restrict access to channel mention notifications to those with the usemention_channel_mentions permission.

CLI

Out of scope.

Configuration

None needed unless channel moderation is experimental.Question for PM: will channel moderation be experimental?

Webapp only

• TBD. Designs for the channel moderation UI A new “Channel Moderation” widget containing the matrix of permissions, roles, and checkboxes in the Channel Configuration details view in the system console is pending(as seen in the design specification).

Mobile and Webapp

• Preventing Prevent posting based on permissions (rather than it currently being done with the “experimental read-only town square” feature) must be implemented throughout the UIthe create_post permissions.

• Preventing access to channel mentions must be controlled by the new based on the use_channel_mentions permission.

Performance

...

...

[vvv TBD vvv]

The synchronization of permissions (as described above) occur synchronously then those actions will incur cause a performance degradation. If the actions occur asynchronously—say in a background job—then the actions will not incur a performance degradation, but at the cost of added complexity.performance degradation when updating channel-scoped permissions on the system scheme or on team schemes.

[^^^ TBD ^^^]

...

Plugins

Out of scope.

CREDITS

...