More Instant Messaging Interoperability (MIMI) using HTTPS and MLS

3.1. Event Schema

Events are authenticated against their TLS presentation language format (Section 3 of [RFC8446]):¶

// See the "MIMI Event Types" IANA registry for values.
// Example: "m.room.create"
opaque EventType;

struct {
   // The room where the event is sent to.
   opaque roomId;

   // The event type.
   EventType type;

   // If present, the event is a state event.
   opaque [[stateKey]];

   // Who or what sent this event.
   opaque sender;

   // The origin server's content hash of the event.
   // See the "Content Hashes" section for information.
   uint8 contentHash[32];

   // The origin server's signature over the event.
   // See the "Signatures" section for information.
   opaque signature<V>;

   // The event IDs which authorize this event to be sent in the room,
   // as defined by the policy.
   // See the "[Event] Authentication" section for information.
   opaque authEventIds[];

   // The event ID of the parent event. This will be an empty string if
   // the `type` is `m.room.create`.
   opaque prevEventId;

   // Additional fields may be present as dependent on event type.
} Event;

Note an "event ID" is not specified on the object. The event ID for an event is the sigil $ followed by the URL-Safe Unpadded Base64-encoded reference hash (Section 3.2.1) of the event.¶

The "origin server" of an event is the server implied by the sender field.¶

Events are immutable once sent, but may be redacted (Section 3.2) to remove non-critical information.¶

3.2. Authentication

Events simultaneously carry information which is critical for the protocol to operate, and other information which is less essential. The less essential information is often user-supplied, and ideally can be removed without "breaking" the room. MIMI supports removing non-critical information from events through redaction.¶

Redaction creates a consistent representation of an event suitable for signing. It is not an approach for "deleting" an event. Deletions are instead handled by the content format for application messages in MIMI.¶

There are two scenarios where a redaction is applied:¶

1. When a mismatched content hash (Section 3.2.2) for an event is received.¶

2. When an m.room.redaction (Section 3.6) message event is received, targeting an event.¶

When applying a redaction, all fields described by Section 3.1 MUST NOT be removed. Individual event types MAY describe additional fields to retain. All other fields MUST be removed.¶

Events are authenticated against their redacted form. If an event fails authentication, it is rejected. Rejected events are dropped and not forwarded any further. For example, a hub rejecting an event would not send it to follower servers. A follower server rejecting an event sent by a hub would not forward it to local clients.¶

The redacted event is signed (Section 3.2.3) to verify that the event was sent by the referenced originating server. If the signature verification fails, the event is rejected.¶

Each event references a set of "auth events" which permit the event to be sent. This field is populated by the hub server upon receipt of a partial event to send. The specific event types required to be referenced in this field are described by the room policy, but are typically the m.room.create (Section 3.3.1), and m.room.user (Section 4.6) state events at a minimum. If an event is missing a required auth event, or contains a reference to an unknown/rejected event, the event is rejected.¶

If the event's content hash does not match the calculated content hash, the event is redacted before being sent any further. Note that if an event is already manually redacted with a redaction event, it will in most cases fail a content hash check.¶

Individual event types MAY specify additional authentication requirements, such as field validation or ordering requirements.¶

3.3. Creation

Rooms (and therefore MLS groups) are first created within the provider, out of scope from MIMI. When the room is exposed to another server over the MIMI protocol, such as with an explicit invite to another user, the creating server MUST produce the following details:¶

• An m.room.create (Section 3.3.1) state event describing the encryption and policy details for the room.¶

• A universally unique room ID (represented by the create event).¶

• An m.room.user (Section 4.6) state event which points to the create event as a parent for the create event's sender.¶

• An MLS group with a group ID matching the room ID, and contains a device belonging to the create event's sender.¶

This is the minimum state required by a MIMI room. Room creators MAY wish to include additional details in the initial state, such as configuration of the room's policy, adding the creator's other clients to the MLS group state, etc.¶

struct {
   // TODO
} CreateEvent;

3.4. Hub Server Selection

The hub server for a room is the origin server of the m.room.create (Section 3.3.1) event.¶

• TODO: More sophisticated selection, and possibly transfer of responsibility.¶

3.5. ReInitialization

• TODO: This topic requires further discussion around policy and lifecycle. See also: Section 3.11 and Section 10.15 of [I-D.robert-mimi-delivery-service].¶

3.6. m.room.redaction

Event type: m.room.redaction¶

State key: Not present.¶

Additional event fields:¶

struct {
   // The event ID to redact.
   opaque redactedEventId;
} RedactionEvent;

Additional authentication rules:¶

• The redactedEventId MUST be an event in the room.¶

• The affected redactedEventId is redacted (Section 3.2) by the server upon receipt.¶

Redaction events are sent to the hub server for fanout with Section 6.3.1.¶

4.1. Invites

An invite is when a user (or more specifically, a user's client) is attempting to introduce all of another user's clients to the room and MLS group. This is first done by updating the target user's participation state through the hub server for the room.¶

Updating the target user's participation state is done using the following steps, and is visualized in Figure 1.¶

1. The inviter's server generates an m.room.user (Section 4.6) state event to invite the target user. Typically this begins with a client-initiated request to the server using the provider-specific API.¶

2. The inviter's server sends (Section 6.3.1) the m.room.user event to the hub server. If the inviter's server is the hub server, it does the steps described in Section 6.3.1 to complete the event.¶

3. The hub server validates the event to ensure the following:¶

   • The target user of the invite MUST NOT already be in the banned or joined states.¶

   • The sender of the invite MUST already be in the joined state.¶

4. If the event is invalid, it is rejected. Otherwise, it is forwarded by the hub to the target user's server to give it the opportunity to reject the invite early in the process. This is described by Section 6.3.2.¶

5. If the target server rejected the event, the event is rejected by the hub as well. Otherwise, the event is fanned out (Section 6.3.1.1) to all participating servers, plus the target server if not already participating.¶

At this stage, the user is now invited but their clients are not members of the MLS group. The invite is delivered to the target's clients through relevant provider-specific API where the user can then accept or decline the invite.¶

If the user declines the invite, they are transitioned to the leave state described by Section 4.3. Accepting is done by joining (Section 4.2) the room.¶

4.2. Joins

A user can join a room in two ways:¶

1. Using an external commit to Add themselves to the MLS group.¶

2. Receiving a Welcome message from a joined member of the MLS group.¶

In both cases, a join m.room.user (Section 4.6) state event is also sent.¶

Typically, a client will use the first option when joining a public room or responding to an invite because the hub server can assist them in the join. Option 2 is generally used as a form of invite, though skipping the explicit m.room.user invite described by Section 4.1.¶

The hub server MUST allow proposals and commits to add a user's own clients if they're in the joined participation state. Similarly, the hub server MUST NOT allow proposals or commits to add clients which are not in the joined participation state. These conditions permit the user to add their own clients after joining without issue, which may involve an external commit.¶

4.3. Leaves/Kicks

Leaving a room can signal a user declining an invite, voluntarily leaving the room, or being kicked (removed) from the room. When the sender and target of an m.room.user (Section 4.6) leave event are different, the target user is being kicked. Otherwise the event represents a voluntary leave or declined invite (if the previous participation state was "invited").¶

Like with other participation/membership operations, a user's leave is initiated by updating their participation state first. This is done by sending (Section 6.3.1) the relevant m.room.user (Section 4.6) state event to the hub, which validates it as follows:¶

• If the target and sender are the same, the user MUST be in the invited, joined, or knocking participation state.¶

• Otherwise:¶

  • The target user of the kick MUST be in the joined participation state.¶

  • The sender for a kick MUST be in the joined participation state.¶

• TODO: Include special case permissions constraints.¶

If the event is valid, it is fanned out (Section 6.3.1.1) to all particpating servers, plus the target user's server.¶

The next commit in the MLS group MUST remove all of the target user's clients. If there are multiple users in the leave participation state, all of their clients MUST be removed in the same commit. Other proposals MAY be committed alongside the removals, however the commit MUST at a minimum remove the affected clients.¶

• TODO: Describe how hub server generates proposals? Or do we just require some member in the group to do it? See also: Section 3.5 of [I-D.robert-mimi-delivery-service].¶

Prior to a voluntary m.room.user leave event, the sender SHOULD send proposals to remove their own clients from the MLS group. Where possible, those clients SHOULD commit their removal prior to updating their participation state as well.¶

Clients can propose to remove themselves from the MLS group at any time. The hub server MUST allow commits at any time to honor those proposals. The hub server MUST NOT allow a commit which contains an inline proposal to remove another client, unless that client belongs to a user in the leave participation state.¶

4.4. Bans

Bans imply kick, and are operated the same way as Section 4.3, though with the m.room.user (Section 4.6) state event using a ban participation state.¶

An added exception on the validation is also applied to permit preemptive bans: the target user is not required to be in the joined state to allow the participation state change.¶

Unbans can be performed by transitioning a user from the banned participation state to leave with Section 4.3.¶

4.5. Knocks

In this state, the sender of a knock is requesting an invite (Section 4.1) to the room. They do not have access to the MLS group.¶

• TODO: Discuss if this participation state is desirable, and figure out details for how it works. It'd likely just be an m.room.user state event with no MLS interaction, like invites are.¶

4.6. m.room.user

Event type: m.room.user¶

State key: ID of target user.¶

Additional event fields:¶

struct {
   // The new participation state for the target user.
   ParticipationState state;

   // Optional human-readable reason for the change. Typically most
   // useful on bans and knocks.
   opaque [[reason]];
} UserEvent;

Additional authentication rules:¶

• The event's authEventIds MUST include a reference to the sender's most recent m.room.user event, if one exists, and the room's m.room.create event.¶

• Rules described by Section 4.1, Section 4.2, Section 4.3, Section 4.4, Section 4.5.¶

• TODO: Include auth rules for permissions.¶

• TODO: Somehow link the event to a client identity? (or several clients) See also: Section 3.8 of [I-D.robert-mimi-delivery-service].¶

5.1. m.room.encrypted

Event type: m.room.encrypted¶

State key: Not present.¶

Additional event fields:¶

struct {
   // The PrivateMessage
   MLSMessage message;
} EncryptedEvent;

Additional authentication rules:¶

• message MUST be an MLS PrivateMessage.¶

6.1. Authentication

All endpoints, with the exception of .well-known endpoints use the mutually authenticated mode of TLS [RFC5246]. This provides guarantees that each server is speaking to an expected party.¶

• TODO: More information specific to how TLS should be used, i.e. mandate best practices that make sense in a mutually authenticated scenario that involves two WebPKI based certificates.¶

Individual events may transit between multiple servers. TLS provides point-to-point security properties while Section 3.2 provides event security guarantees when transiting over multiple servers.¶

6.2. Endpoint Discovery

A messaging provider that wants to query the endpoint of another messaging provider first has to discover the fully qualified domain name it can use to communicate with that provider. It does so by performing a GET request to https://example.org/.well-known/mimi/domain. example.org could, for example, answer by providing the domain mimi.example.org (assuming that this is where it responds to the REST endpoints defined in Section 6.3).¶

The expected response format is simply a text/plain body containing the fully qualified domain name.¶

GET https://example.org/.well-known/mimi/domain

Response
mimi.example.org

6.3. REST Endpoints

The following REST endpoints can be used to communicate with a MIMI server.¶

All operations rely on TLS-encoded structs and therefore requests and responses SHOULD use a Content-Type of application/octet-stream.¶

struct {
   // The resulting event ID that is about to be fanned out by the hub server.
   // Not included if the called server is a follower server.
   opaque [[eventId]];
} SendEndpointResponse;

POST /v1/send
Content-Type: application/octet-stream

Body
TLS-serialized Event (including additional fields, such as CreateEvent)

Response
TLS-serialized SendEndpointResponse

struct {
   // The `m.room.user` invite event.
   UserEvent invite;

   // The `m.room.create` event for the room.
   CreateEvent roomCreate;
} CheckInviteRequest;

POST /v1/check-invite
Content-Type: application/octet-stream

Body
TLS-serialized CheckInviteRequest

Response
Any meaningful information. The pass/fail is identified by the HTTP response
status code, not the response body.

struct {
   // The user ID to retrieve KeyPackages for. This will download 1 KeyPackage
   // for each of the user's clients.
   opaque userId;

   // The user ID requesting the KeyPackages for `userId`.
   opaque requestingUserId;

   // The room (group) ID where the KeyPackages are valid for.
   opaque roomId;
} GetKeyPackagesRequest;

struct {
   // One KeyPackage for each of the requested user's clients.
   KeyPackage keyPackages<V>;
} GetKeyPackagesResponse;

POST /v1/key_packages
Content-Type: application/octet-stream

Body
TLS-serialized GetKeyPackagesRequest

Response
TLS-serialized GetKeyPackagesResponse

struct {
   Extension group_info_extensions<V>;
   opaque Signature<V>;
} PartialGroupInfo;

struct {
   MLSMessage commit;
   PartialGroupInfo partial_group_info;
} MLSGroupUpdate;

POST /v1/external_join
Content-Type: application/octet-stream

Body
TLS-serialized MLSGroupUpdate

Response
Any meaningful information. The pass/fail is identified by the HTTP response
status code, not the response body.

struct {
   // MUST be a PublicMessage with a commit that only contains Add proposals
   // for a joined user's clients.
   //
   // MUST NOT change the sending client's credential.
   MLSGroupUpdate group_update;
   MLSMessage welcome_messages<V>;
} AddClientsRequest;

struct {
   // MUST NOT change the sending client's credential.
   MLSGroupUpdate group_update;
} RemoveClientsRequest;

struct {
   // MUST contain a PublicMessage which contains a commit with an UpdatePath,
   // but not other proposals by value.
   MLSGroupUpdate group_update;
} UpdateClientRequest;

enum {
   add,
   remove,
   update,
} MLSOperation;

struct {
   MLSOperation operation;

   select (GroupUpdateRequest.operation) {
      case add:
         AddClientsRequest request;
      case remove:
         RemoveClientsRequest request;
      case update:
         UpdateClientRequest request;
   }
} GroupUpdateRequest;

POST /v1/group_update
Content-Type: application/octet-stream

Body
TLS-serialized GroupUpdateRequest

Response
Any meaningful information. The pass/fail is identified by the HTTP response
status code, not the response body.

8.1. MIMI Event Types

An event type denotes the nature of a payload contained in an event, in the context of the MIMI protocol. The event type is a string composed of substrings separated by dots.¶

The first substring is "m", followed by the logical container being affected (typically just "room"), then a number of descriptor strings.¶

Example: m.room.create¶

• TODO: Does IANA need any other information for legal event types?¶