MIMI Policy Envelope

Introduction The primary objective for the More Instant Messaging Interoperability (MIMI) working group is to specify the needed protocols to achieve interoperability among modern messaging providers. The protocols which make up the "MIMI stack" are described by . In the stack are a policy control protocol and a participation control protocol. These two control protocols are described by this document, supported by TODO(TR): Link to I-D.ralston-mimi-signaling. Policy control is handled through permissions, while participation is managed primarily through the rules governing m.room.user. Together, these control protocols create this policy document. When an action is impossible for a server to enforce, such as when a client operated by a user sends an encrypted instant message, the receiving clients are responsible for enforcing the remainder of the policy. This may mean, for example, decrypting a message but not rendering it due to a policy violation. The concepts of permissions and participation state for a user are deliberately separated in this policy document. A user's participation state might affect which permissions they can use, but a user's permissions do not change their participation in a room.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Terms from and are used throughout this document. takes precedence where there's conflict. Terms from TODO(TR): Link to I-D.ralston-mimi-signaling are used throughout this document. Other terms include: Rejected: The action being performed ceases to continue through the remainder of the send/rendering steps. For a hub server, this means the event being sent is not added to the room and is not sent to any other server. For a client, this equates to not rendering or respecting the action. Allowed: The opposite of Rejected. The action is expressly permitted to occur. "Engaging with the room": The user is able to take some actions and send messages in the room, provided the remainder of the policy allows them to do that. The encryption/security layer MAY further restrict a user's ability to take action. For example, the user might need 1 or more clients to be able to successfully send a message.

Permissions Definitions Action: Something a user does in the context of a room. For example, invite another user or send a message to the room. Permission: A flag which allows (or rejects) execution of an action. Role: A user-defined set of permissions. Users are added to roles to gain the included permissions.

Participation Definitions Target: The user affected by a participation state. Sender: The user affecting a target user with a participation state. Invited: The target is given the choice to accept the invite (join the room) or decline (leave the room). Joined: The target is capable of engaging with the room. Left: The target has either voluntarily chosen to leave the room, or has been removed with a kick. Banned: The target is kicked and cannot be invited, joined, or knock on the room until unbanned. Knocking: The sender is requesting an invite into the room. They can either be welcomed in (invited) or declined (kicked). Kicked: Involuntary leave. The target and sender are not the same user.

Event Authorization When a hub server receives an event, and before it adds it to the room, it MUST ensure the event passes the policy for the room. In the case of this document, the server MUST ensure the following checks are performed:

The event is correctly signed and hashed.
The event's authEvents include the appropriate event types ().
The sender has permission () to send the event.
Any event type-specific checks are performed, as described throughout this document.

Auth Events Selection When a server is populating authEvents, it MUST include the event IDs for the following event types. These SHOULD be the most recent event IDs for the event types. Note: m.room.create MUST always have an empty authEvents array.

The m.room.create event.
The m.room.user event for the sender, if applicable.
The m.room.role_map event (), if set.
The m.room.role events () assigned to the user sender, if any.
If the event type is m.room.user:
- The target user's m.room.user event, if any.
- If the participation state is join or invite, the m.room.join_rules event (), if any.

TODO(TR): Restricted joins join_authorised_via_users_server? (GH issue) If an event is missing from authEvents but should have been included with the above selection algorithm, the event is rejected. If events not intended to be selected using the above algorithm above are included in authEvents, the event is rejected. This extends to events which aren't known or are malformed in authEvents. If an event uses non-current events in its authEvents, it is rejected.

Types of Senders TODO(TR): Do we want to send as not-users? (GH issue) Currently this document only supports sender being a user ID.

Permissions Rooms are capable of defining their own roles for grouping permissions to apply to users. These roles do not currently have aesthetic characteristics, such as a display name, badge color, or avatar. Roles are described by an m.room.role state event. The state key for the event is the "role ID", and is not intended to be human readable. The content for the event has the following structure in TLS presentation language format (): Users are assigned to roles using an m.room.role_map state event, with empty string for a state key. The content being as follows: Each role ID MUST only appear once in MRoomRoleMapEventContent.roles. Each RoleConfig.order MUST be distinct from all other entries. If either of these checks fail when a server receives the event, the event is rejected.

Calculating Permissions A user's permissions is the sum of the permissions described by their assigned roles. When two roles define the same permission (but with different values), the higher order role takes precedence. For example, if given the following role structure...

Role A, order 1.
- Permission A = true
- Permission B = false
Role B, order 2.
- Permission A = false
- Permission C = false
Role C, order 3.
- Permission B = true
- Permission C = false

... and a user assigned all three roles, the user's resolved set of permissions would be:

Permission A = false (takes Role B's value)
Permission B = true (takes Role C's value)
Permission C = false (defined by Role B, no conflict with Role C)

These permissions are then used to define whether a user can "send" the event.

Effective Power Level In some cases it is required to know the "power level" for a user to solve tiebreaks. The power level of a user is the highest order role they are assigned with the desired permission set, regardless of value for that permission. Using the example from , a user with all three roles would have the following effective power levels for each permission in question:

Permission A = 2
Permission B = 3
Permission C = 3

List of Permissions The full definitions for Permission and PermissionValue in is:

Event Sending Permissions The sender for an event MUST have permission () to send that event type, unless the event type is m.room.user. User participation events are handled specifically in . The sender MUST also be in the joined state to send such events.

Role Changes TODO(TR): I believe we need words to describe how to use the role permissions described above. Probably something using effective power levels and talking about what "add", "remove", and "change" actually mean. TODO(TR): We also need to specify that the creator has superuser permissions until a role is defined/assigned.

User Participation User participation is tracked as m.room.user state events. The content for such an event has the following structure in TLS presentation language format (): A user is considered to be "joined" to a room if they have a participation state of join. All servers with users in the joined state are considered to be "in" the room. Servers which are in the room can send events for their users directly. The signaling protocol is able to assist servers (and therefore users) in sending the appropriate participation events until they are able complete the join process.

General Conditions TODO(TR): This is where we'd put server ACLs. (GH issue)

Invite Conditions The target user for an invite MUST:

NOT already be in the banned state.
NOT already be in the joined state.

The sender for an invite MUST:

Already be in the joined state.
Have permission () to invite users.

Otherwise, reject.

Join Conditions The target and sender of a join MUST be the same. Whether a user can join without invite is dependent on the join rules (). If the join rule is invite or knock, the user MUST already be in the joined or invite state. If the join rule is public, the user MUST NOT already be in the banned state. Otherwise, reject.

Knock Conditions The target and sender of a knock MUST be the same. If the current join rule () for the room is knock, the user MUST NOT already be in the banned or joined state. Otherwise, reject.

Ban Conditions The sender for a ban MUST:

Already be in the joined state.
Have permission () to ban users.

Otherwise, reject. Note that a ban implies kick.

Leave Conditions Leaves in a room come in two varieties: voluntary and kicks. Voluntary leaves are when the user no longer wishes to be an active participant in the room. A kick is done to remove a user forcefully. When the target and sender of a leave is the same, it is a voluntary leave.

Voluntary The user MUST be in the invited, joined, or knocking state. Otherwise, reject.

Kicks The target user for a kick MUST:

Already be in the joined state.

The sender for a kick MUST:

Already be in the joined state.
Have permission () to kick users.
Have a higher (and NOT equal to) effective power level with respect to the kick permission () than the target user.

If the target user is in the banned state, the sender requires permission to ban users instead (as to ban means to unban as well). This additionally extends to the effective power level check. Otherwise, reject.

m.room.join_rules State key: Empty string. Content: Redaction considerations: rule under content is protected from redaction.

Event/History Visibility Unless otherwise specified by the event type, non-state events MUST NOT be sent to a user's client if the history visibility rules prohibit it. State events are always visible to clients. When a server is fetching events it is missing to build history, the returned events are redacted unless the server has at least one user which is able to see the event under the history visibility rules. The server must then further filter the events before sending them to clients. History visibility rules are defined by m.room.history_visibility (), and can only affect future events. Events sent before the history visibility rule change are not retroactively affected. Taking into consideration the m.room.history_visibility event that is current at the time an event was sent, a user's visibility of a that event is described as:

If the visibility rule was world, show.
If the user was in the joined state, show.
If the visibility rule was shared and the user was in the joined state at any point after the event was sent, show.
If the user was in the invited state, and the visibility rule was invited, show.
Otherwise, don't show.

m.room.history_visibility State key: Empty string. Content: Redaction considerations: visibility under content is protected from redaction.

IANA Considerations This document as a whole makes up the m.0 policy ID, as per TODO(TR): Link to I-D.ralston-mimi-signaling. This document's descriptions for the following event types are registered to the event types registry in TODO(TR): Link to I-D.ralston-mimi-signaling:

m.room.role ()
m.room.role_map ()
m.room.join_rules ()
m.room.history_visibility ()