MIMI Policy Envelope

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 26 March 2024.¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. 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 [I-D.barnes-mimi-arch].¶

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.¶

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Terms from [I-D.barnes-mimi-arch] and [I-D.ralston-mimi-terminology] are used throughout this document. [I-D.barnes-mimi-arch] 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.¶

3. 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:¶

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

4. 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.¶

5. 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 (Section 3 of [RFC8446]):¶

enum {
   // Iterated later in the document.
} Permission;

struct {
   select (Permission) {
      // cases defined later in the document.
   } permission;
} PermissionValue;

struct {
   PermissionValue permissions[];
} MRoomRoleEventContent;

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:¶

struct {
   // The role's ID.
   opaque roleId;

   // The user IDs who are assigned this role.
   opaque userIds[];

   // The power level for the role. This is used in cases of tiebreak and to
   // override permissions from another role.
   uint32 order;
} RoleConfig;

struct {
   RoleConfig roles[];
} MRoomRoleMapEventContent;

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.¶

enum {
   // Whether other users can be invited to the room by the role.
   // Default: false.
   invite(1),

   // Whether other users can be kicked from the room by the role.
   // Default: false.
   kick(2),

   // Whether other users can be banned from the room by the role.
   // Default: false.
   ban(3),

   // Whether another user's events can be redacted by the role.
   // Senders can always redact their own events regardless of this permission.
   // Default: false.
   redact(4), // TODO(TR): Do we need this one?

   // The event types the role is able to send.
   // Default: None.
   events(5),

   // The actions this role can take against roles. For example, adding or
   // removing permissions.
   // Default: None.
   roles(6),
} Permission;

struct {
   select (Permission) {
      case invite: BooleanPermission;
      case kick: BooleanPermission;
      case ban: BooleanPermission;
      case redact: BooleanPermission;
      case events: EventTypePermission;
      case roles: RolePermission;
   } permission;
} PermissionValue;

struct {
   // When false, the permission is explicitly not granted.
   byte granted;
} BooleanPermission;

struct {
   // The event type being gated by a permission.
   opaque eventType;

   // When false, the permission to send the event is explicitly not granted.
   byte granted;
} EventTypePermissionRecord;

struct {
   // The event type restrictions. If there are duplicates, the lastmost entry
   // takes priority.
   EventTypePermissionRecord eventTypes[];
} EventTypePermission;

struct {
   // The role IDs that can be affected by this role. This includes adding,
   // removing, and changing permissions.
   // TODO(TR): We might want something more comprehensive.
   opaque affectRoleId[];
} RolePermission;

6. 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 (Section 3 of [RFC8446]):¶

enum {
   invite,  // "Invited" state.
   join,    // "Joined" state.
   leave,   // "Left" state (including Kicked).
   ban,     // "Banned" state.
   knock    // "Knocking" state.
} ParticipationState;

struct {
   ParticipationState participation;
   opaque reason;  // optional reason for the participation state
} MRoomUserEventContent;

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.¶

enum {
   invite,
   knock,
   public,
} JoinRule;

struct {
  // The current join rule for the room. Defaults to `invite` if no join rules
  // event is in the room.
  JoinRule rule;
} MRoomJoinRulesEventContent;

7. 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 (Section 7.1), 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.¶

enum {
   invited,
   joined,
   shared,
   world,
} Visibility;

struct {
  // The current join rule for the room. Defaults to `shared` if no history
  // visibility event is present in the room.
  Visibility visibility;
} MRoomHistoryVisibilityEventContent;

8. 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 (Section 5)¶
• m.room.role_map (Section 5)¶
• m.room.join_rules (Section 6.7)¶
• m.room.history_visibility (Section 7.1)¶

Authors' Addresses