...

Status:

OVERVIEW

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

...

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

• creating posts

• adding and removing members

• using channel mentions

GOALS

1. Describe the backend architecture and required changes.

2. Describe the webapp changes required.

3. Describe the mobile app changes required.

SCOPE

...

This document describes the backend approach, new API endpoints, database changes, webapp changes, and mobile app changes.

In:

• 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

• creating the new use_channel_mentions permission

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

Out:

• CLI changes

• chat-facing administration of channel moderation settings

• plugin changes

• feature tracking (in scope for the feature but not covered by this document, see https://mattermost.atlassian.net/browse/MM-22153 for the specification)

• exposing create_post and use_channel_mentions in the system and team schemes UI

BACKGROUND READING

1. Channel Moderation Settings feature specifcationspecification

2. High fidelity designs

TERMINOLOGY

...

• “channel moderation”: although this term is used throughout this document it may not end up being the customer-facing terminology as some find it confusing compared to an alternative that describes that permissions are being overridden.

• “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. This is a newly necessary term/concept because previously there was no ongoing inheritance-style relationship between schemes.

• “channel mentions”: the at-mentions “@all”, “@here”, and “@channel”.

• “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 channel moderation feature leverages the existing permissions system to create a channel scheme for each channel for which channel moderation is enabled. Enabling moderation for a given channel creates a record 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. It also creates two Three new Roles records are also created and their 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 schemescheme’s associated Roles records. A set of the permissions

Guest and member Roles records' moderated permissions are then removed from the Permissions fields to further limit the permissions of the specific channel associated to the new channel scheme’s guest and member can subsequently be edited to provide 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 disabled, the channel the channel scheme.

If 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 having to using the permissions as configured on the higher-scoped scheme.

...

Bots continue to function the same as usual, namely bots can be configured to use either the member or system admin. If a bot is configured to be a member the bot could have its touse_channel_mentions and create_post permissions restricted on specific channels. However, to lose the create_post permission the bot would also have to have post:all and post:channels disabled.

...

Relationship between a channel scheme and its higher-scoped scheme

Per the permissions system design, a channel scheme completely overrides all channel-scoped permissions for on the given associated channel(s). This means that if there are permissions that are not exposed 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 must 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

Question: Is updating permissions from higher-scoped schemes' roles to channel schemes' roles compatible and feasible with the future custom roles feature?

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.

If a channel has a scheme, the set of moderated permissions on that channel scheme will completely override the permission of the higher scoped scheme. However, non-moderated permissions will be ignored on the channel scheme and instead be read from the higher-scoped 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:

add_reaction/remove_reaction
create_post
manage_public_channel_members/manage_private_channel_members
edit_post
edit_others_posts
use_channel_mentions

Guest, member, and channel admin role channel-scoped permissions that must be replicated to the channel scheme roles from the higher-scoped scheme:

create_post_public
create_post_ephemeral
delete_post
/delete_others_posts
add_reaction/remove_reaction
create_post
use_channel_mentionsAll 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): (exposed in schemes UI)
edit_post/edit_others_posts (exposed in schemes UI)
manage_channel_roles
manage_public_channel_properties
/manage_private_channel_properties (exposed in schemes UI)
delete_public_channel
/delete_private_channel (exposed in schemes UI)
read_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 “enable channel moderation” (wording as per design) 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. Question: 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

Schema

No schema changes.

REST API

• 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": "create_reactions",
        "roles": {
            "guests": {
                "value": false,
                "enabled": false
            },
            "members": {
                "value": true,
                "enabled": true
            }
        }
    },
    {
        "name": "manage_members",
        "roles": {
            "members": {
                "value": true,
                "enabled": true
            }
        }
    }, 
    {
        "name": "use_channel_mentions",
        "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 PUT /api/v4/channels/:channel_id/moderations/patch 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 use_channel_mentions permission.

• Update the PUT /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?

...

• /patch endpoint to validate that the requested permission change is permitted if it is attempted against a role that is used by a channel-scoped scheme. The role can only be less permissive than the permissions on the higher-scoped scheme.

CLI

Out of scope.

Configuration

None needed. Question: will channel moderation be experimental?

Frontend

...

Webapp only

• A new “Channel Moderation” widget containing the matrix of permissions, roles, and checkboxes in the Channel Configuration details view in the system console TBD.

• Preventing posting based on permissions (rather than it currently being prevented based on the experimental read-only town square feature) must be implemented throughout the UI.

• Preventing access to @here, @all, @channel must be controlled by the new use_channel_mentions permission.

Mobile

• Preventing posting based on permissions (rather than it currently being prevented based on the experimental read-only town square feature) must be implemented throughout the UI.

• Preventing access to @here, @all, @channel must be controlled by the new (as seen in the design specification).

Mobile and Webapp

• Prevent posting based on the create_post permissions.

• Preventing access to channel mentions based on the use_channel_mentions permission.

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 itThere may be a performance degradation when querying the presence of non-moderated, channel-scoped permissions.

Plugins

Out of scope.

CREDITS

Thanks to Catalin, Dennis, George, Scott, Hossein, and Farhan for bouncing some of these ideas around with me.