Mimi J. Rosenberg Internet-Draft Five9 Intended status: Standards Track C. Jennings Expires: 14 September 2023 S. Nandakumar Cisco 13 March 2023 More Instant Messaging Interop (MIMI) Transport Protocol draft-rosenberg-mimi-protocol-00 Abstract This document specifies the More Instant Messaging Interop (mimi) Transport Protocol (MTP)- a protocol for inter-provider persistent group chat. MIMI utilizes Messaging Layer Security (MLS) for end-to- end encryption of content. The MIMI Transport Protocol plays the role of the Delivery Service (DS) defined by the MLS protocol. MTP is meant to represent the minimal protocol required to enable provider to provider federation for messaging exchange using MLS. It is not suitable for client to provider communications. MTP is based on a pull architecture, wherein message delivery from provider A to provider B is accomplished by having provider B pull messages from provider A. This provides better scalability and reliability and is amenable to implementation in modern cloud software architectures, while also reducing spam risk. MTP serves as a transfer protocol for opaque message content, the format of which is specified in a separate document. MTP is also designed to prevent spam, and does so by introducing a layer of authorization for the establishment of connections and addition to group chats. 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 14 September 2023. Rosenberg, et al. Expires 14 September 2023 [Page 1] Internet-Draft MIMI Protocol March 2023 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Identity . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Reference Architecture . . . . . . . . . . . . . . . . . . . 8 5. 1-1 Chats . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. MIMI URI Syntax . . . . . . . . . . . . . . . . . . . . . . . 11 7. Connections . . . . . . . . . . . . . . . . . . . . . . . . . 12 7.1. Group-Chat Independent Connection . . . . . . . . . . . . 12 7.2. Group Chat Dependent Connection . . . . . . . . . . . . . 18 7.3. Guest Connections . . . . . . . . . . . . . . . . . . . . 21 7.4. Mobile Centric UI . . . . . . . . . . . . . . . . . . . . 22 8. REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.1. Authentication and Authorization . . . . . . . . . . . . 24 8.2. General Request Guidelines . . . . . . . . . . . . . . . 24 8.3. Connection Information . . . . . . . . . . . . . . . . . 25 8.4. Connection Acceptance or Rejection . . . . . . . . . . . 26 8.5. Join Request . . . . . . . . . . . . . . . . . . . . . . 27 8.6. Leave Request . . . . . . . . . . . . . . . . . . . . . . 28 8.7. Guest Addition . . . . . . . . . . . . . . . . . . . . . 29 8.8. Add Message . . . . . . . . . . . . . . . . . . . . . . . 29 8.9. Retrieve Membership . . . . . . . . . . . . . . . . . . . 30 8.10. Retrieve Group Chat Information . . . . . . . . . . . . . 31 8.11. Set Group Property . . . . . . . . . . . . . . . . . . . 32 8.12. Commit . . . . . . . . . . . . . . . . . . . . . . . . . 33 9. Synchronization . . . . . . . . . . . . . . . . . . . . . . . 33 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 10.1. Spam Prevention . . . . . . . . . . . . . . . . . . . . 35 10.1.1. Consent Based Protection . . . . . . . . . . . . . . 35 10.1.2. Leave the Group . . . . . . . . . . . . . . . . . . 36 10.1.3. Malicious Sender Traceability . . . . . . . . . . . 37 10.1.4. Provider Authorization . . . . . . . . . . . . . . . 37 10.2. Malicious Providers Manipulating other Users . . . . . . 37 Rosenberg, et al. Expires 14 September 2023 [Page 2] Internet-Draft MIMI Protocol March 2023 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 11.1. URI Scheme Registration . . . . . . . . . . . . . . . . 38 11.2. Well-Known URI Registration . . . . . . . . . . . . . . 38 11.3. MIMI Property Registry . . . . . . . . . . . . . . . . . 38 12. Normative References . . . . . . . . . . . . . . . . . . . . 39 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 1. Introduction The MIMI Transport Protocol (MTP) specifies inter-provider persistent group chat. It assumes the existence of chat providers, each of which provides both client applications (often mobile apps) along with a service backend. Many of these providers allow multiple simultaneous active clients per user. Examples of chat providers as of time of writing include WhatsApp, iMessage, Facebook Messenger, Signal and Telegram in the consumer space; and Slack, Microsoft Teams, Wire and Element in the enterprise space. MTP further assumes that the foundational unit of communications within each provider is a group chat. A group chat is a virtual place wherein a set of users can share content, including text messages, images, videos, and so on. A group chat has a membership, which represents a set of users who are permitted to participate in the group chat. These group chats are persistent, in that, a user that is a member of a group chat can see past history of the group chat. Furthermore, a user can send and receive messages into the group chat independently of whether other users in the group chat are currently logged into their client application. This persistent group chat model is different from the session-based real-time chat provided by protocols such as SIMPLE [RFC6914] and XMPP [RFC6120] [RFC6121]. For any given group chat, a single provider is said to be the owning provider for that group chat. The owning provider is the source of truth for the properties (including membership) and message content of that group chat. If the owning provider decides, for example, to close a group chat, it will no longer be possible for participants to post to it, no matter what provider those participants belong to. Typically, if a user is a customer of provider A, and creates a new group chat, provider A ends up being the owner of that group chat. Rosenberg, et al. Expires 14 September 2023 [Page 3] Internet-Draft MIMI Protocol March 2023 Mimi enables a group chat to have participants that exist in multiple providers. There will typically be participants in a group chat in the owning provider, but this is not a strict requirement of the mimi protocol. A participant in a group chat that doesnt reside in the same provider as the owning provider, is called a guest participant. Their provider, is called a guest provider. The roles of owning provider, guest participant and guest provider are scoped per group chat. Meaning, in one group chat, a particular provider might be the owning provider. But, for a different group chat, they would be a guest provider. MTP provides several functions. First, it enables a user in one provider to establish a connection with a user in another provider. A connection is the baseline unit of authorization in MTP. It represents authorization from the inviting user, towards the invited user, for the inviting user to add the invited user to one or more group chats in the inviting user's provider. A connection is fundamentally asymmetric. The connection establishment processes allows the owning provider to obtain this authorization, and to also discovery the identity by which the invited user is known in its provider. MTP supports two distinct flavors of connection establishment - one where the connection is created separately from usage of that connection to add the user to a group chat, and a second in which the connection is concurrent with the addition of that user to a group chat. Connection establishment makes use of an out of band communications from the inviting user, to the invited user, using a new URI - the mimi URI - that is conveyed out of band. This out of band communications can be via email or text, or even by written or verbal communications. This process is key to ensuring that mimi doesnt become a vehicle for spam and unwanted communications. Because the out of band communications is user to user, not provider to provider, it takes advantage of address books already in place and anti-spam tools already present in the global SMS and email networks. The out of band communications would also include personalized content crafted by the inviting user to help convey context, to help the invited user decide on whether to accept the connection. The MIMI URI, defined in this specification, contains a short lived connection ID. The MIMI URI is used by the guest provider to obtain the context of the connection request - the identity of the inviting user, and optionally the name of the group chat to which they have been invited. With this context, the invited user can decide to accept the connection or not. This acceptance is communicated back to the owning provider. Rosenberg, et al. Expires 14 September 2023 [Page 4] Internet-Draft MIMI Protocol March 2023 The second main function of MTP is to allow, for a given group chat, the set of guest providers to synchronize the state of the group chat with the owning provider, and to add messages into the group chat. In this regards, MTP is strictly a provider to provider protocol. We use the words provider to provider, and not server to server, because it is anticipated that MTP between a pair of providers would typically run across a multiplicity of servers utilized by each respective provider in order to achieve scale. Enabling this is an explicit design goal of MTP. MTP is fundamentally an asymmetric protocol. For any given group chat, transmission of a message from one provider to another provider depends on their roles - owning or guest. Sending a message from a guest provider to an owning provider is accomplished using a RESTful style POST operation using HTTP. In this direction, the guest participant - and thus the provider acting on their behalf - is adding a message into the group chat. That operation must be authorized by the owning provider, and assuming it is allowed, the message is accepted. In the reverse direction, when a message is to be sent from the owning provider to a guest provider, the message is already part of the group chat, and the message delivery is performed using a synchronization technique that utilizes an HTTP long poll. MTP protocol operations for the purposes of content delivery always take place from the guest provider, towards the owning provider. In other words, the guest provider always acts as an HTTP client. There is no way for the owning provider to send messages to any other provider - guest providers must explicitly retrieve them, and retrieve them for specific, named group chats. This part of the protocol design is also meant to ensure that mimi does not become a vector for spam. It is simply impossible for messages to be pushed into a guest provider using MTP. The guest provider has to ask for them, and to ask for them using a specific group chat. The only way a guest provider can even know to ask for messages in a group chat, is because one of its users learned a group chat ID via a mimi URI and asked their provider to retrieve messages for that group. This technique also means that, the default failsafe for mimi is non- delivery of messages. Meaning, if the guest user or their provider decide to no longer participate in a group chat, messages will not be delivered to the guest provider. It takes active effort on behalf of the guest provider to pull messages. MTP makes use of Messaging Layer Security (MLS) for end-to-end (e2e) encryption of message content [I-D.ietf-mls-protocol] [I-D.ietf-mls-architecture]. In that regards, MTP plays the role of the Delivery Service (DS) as defined in that specification. It includes the needed primitives for retrieving key packages, transmitting proposal and commit messages, delivery of welcome Rosenberg, et al. Expires 14 September 2023 [Page 5] Internet-Draft MIMI Protocol March 2023 messages, and sequencing of commits. MLS is an end-to-end protocol which occurs between client applications. Consequently, the MIMI protocol assumes that providers merely collect those messages from clients and send them across via MIMI when needed, and transmit them to clients when delivered by MIMI. MTP provides additional security measures ontop of MLS. Specifically, it authorizes provider access to a group chat. Note that MTP does not offer directory services of any kind, and does not allowing an owning provider to determine whether an invited user - as identified by an email address or phone number - is a user of any particular provider. This decision is an explicit one, in order to avoid the significant privacy considerations that would arise from a central directory. In a similar way, mimi does not provide any form of interprovider search. The mimi invitation process assumes that the inviting user has a unique identifer for the invited user, obtained out of bands of the protocol. 2. Definitions Provider: A provider is an entity which is capable of providing persistent group chat capabilities to a set of users that have signed up to their service. A provider offers its users both a client application and a backend cloud service that powers its client application. A provider is also capable of authenticating its users. Group Chat: A group chat is a named resource that has properties, most notably the membership of the group, and has a sequence of messages. Owning Provider: For a given group chat, the owning provider is the provider which acts as the source of truth for the membership, messages, and policy. A request to post a message or change a property must be processed at the owning provider. [TODO: the owning provider is not the DS/AS. Both providers and the client play part of those abstract roles]. In MLS terminology, the owning provider acts as the DS and AS for a particular group chat. Participant: A user of a group chat. Guest Provider: For a given group chat, a participant can be a user of the owning provider, or they can be part of a different provider. A provider associated with a user that is not a user of the owning provider, is called a guest provider. Rosenberg, et al. Expires 14 September 2023 [Page 6] Internet-Draft MIMI Protocol March 2023 Connection: A unit of authorization between a user in a guest provider (the invited user) and one in an owning provider (calling the inviting user), which grants permission for the inviting user to add the invited user to one or more group chats. Inviting User: A user that seeks to create a connection with a user in a different provider, or add a user in a different provider to a group chat. Invited User: A user that has received a request for a connection, or has received a request to be added to a group chat. 3. Identity Identity is central to the operation of mimi. The mimi identity model is shown in the figure below. +----------------------+ +------------+1 n | Routable Addresses | | Human User |------| (e.g., +17325551212, | +------------+ | joe@example.com) | 1 | +----------------------+ | n | +-----------------+ ------| Participant ID | --| | +-----------------+ | | | | | Provider Name | (e.g. provider.com) | |---------- | +-----------++----------------------++-------------------+ | Handle || Email || E.164 | |(e.g. @joe)||(e.g. joe@example.com)||(e.g. +17325551212)| +-----------++----------------------++-------------------+ The center of this identity model is a human user (though nothing in mimi requires that it be a human per se). A given human user has a set of routable addresses which can be used to reach them through communications channels outside of group chat. Specifically, they include phone numbers and email addresses over which texts and emails can respectively be received. These routable addresses exist outside of the mimi protocol, but are used to deliver a mimi invitation, which is discussed below. Rosenberg, et al. Expires 14 September 2023 [Page 7] Internet-Draft MIMI Protocol March 2023 Within mimi, we have participants, each of which has a unique ID. A participant ID is composed of two parts. The first is the provider name. In mimi, this MUST be a valid DNS name that identifies the provider. Furthermore, the provider entity MUST be the owner of that DNS name, and MUST be capable of obtaining TLS certificates usable with HTTPS for this domain name. The second is the user ID. The user ID takes one of three forms. First, it can be an E.164 number. Secondly, it can be an email address. Thirdly, it can be a handle. When it is a handle, it is unique only within the context of the provider. A phone number or email address is globally unique. The partipant ID can be written by taking the provider name, followed by a colon, and then the userID. The following are some examples of valid participant IDs: provider.com:joe@example.com foo.com:+1732551212 twitter.com:@joe TODO: add formal ABNF It is extremely important to note that the domain portion of the email address need not (and most often, will not) match the provider name. As a real world example, the provider could be Facebook Messenger, whose provider name is messenger.com. A user within this provider could be Joe Smith, and they have a user ID of joe.smith@gmail.com. In this case, their email is provided by Gmail (gmail.com), but Google/Gmail is not their messaging provider. Of course, a given human user may have accounts in multiple providers, and perhaps even have multiple accounts within the same provider. Each of these would correspond to a unique participant ID, and thus be viewed as unique participants within the mimi protocol. 4. Reference Architecture The figure below is the reference architecture for mimi operations. Rosenberg, et al. Expires 14 September 2023 [Page 8] Internet-Draft MIMI Protocol March 2023 +------------+ mimi rest +------------+ | Owning |<----------- | Guest | | Provider | | Provider | | | mimi sync | | | |<----------- | | +------------+ +------------+ | | | | | | | | +--------+ +--------+ | User A | | User B | +--------+ +--------+ ^ | | V +---------------------------------------+ | Out of Band Comms | | Email, SMS, etc. | +---------------------------------------+ MTP operations are defined within the context of a particular group chat, or a particular connection. For different group chats or connections, the roles may change. In other words, a particular provider might act as owning provider for some group chats and connections, and guest provider for others. The owning provider for a group chat is the one that acts as the source of truth for a group chat, and acts as the MLS DS for that group chat. The guest provider is the provider for a user that is a guest member of the group chat. In this picture, user A is a participant in the group chat, and is a user of the owning provider. User B is a participant of the group chat, but is a user of the guest provider. There is a connection between user A and user B, and for this connection, user A's provider is the owning provider, and user B's provider is the guest provider. For purposes of establishing connections, MTP assumes the usage of an out of band conveyance technique. The mimi protocol has two distinct components, which are referred to as mimi rest and mimi sync. The mimi rest component are a sequence of REST APIs which are implemented by the Owning provider, and consumed by the guest provider. The mimi rest component of the protocol includes RESTful resources for retrieving membership, retrieving properties (such as group name), and adding messages into a group chat. It also provides REST endpoints to support MLS operations - specifically, publishing a KeyPackage, retrieving KeyPackages, and sending commit messages which increment the epoch. The second part of the protocol is used to enable real-time synchronization. The guest provider opens an HTTP long poll onnection to the owning provider, and subscribes to a set of group Rosenberg, et al. Expires 14 September 2023 [Page 9] Internet-Draft MIMI Protocol March 2023 chats and connections. This subscription specifies the start timestamp for the subscription. The owning provider will authorize and accept the subscription, and then deliver past and future messages. Through this synchronization protocol, the guest provider receives actual messages (text, images, emails, threads, reactions and so on) that have been posted into the group chat. When subscribing to a connection, it receives group addition requests, which must be authorized by the invited user. It will also receive MLS Proposal, Commit, and Welcome messages, and change notifications of group membership and group properties. The out of band communications modality facilitates the operation of creating a connection. From a mimi perspective, the owning provider generates a mimi URI for the connection, which is then delivered to the inviting user. The inviting user delivers this URI through an out-of-band technique, not specified. The invited user passes this to the guest provider, which then acts on it. The guest provider can then utilize the URI to invoke mimi REST APIs on the owning provider. 5. 1-1 Chats The atomic unit of communication in MIMI is a group chat, which is a conversation between 1 or more participants. Mimi imposes no restrictions on the number of group chats that can exist with identical membership. A group chat is identified by a UUID, not the identities of its participants. This introduces some complications in the handling of 1-1 communications, for two reasons. First, many modern messaging systems only show the user a single chat space associated with the target, and do not permit any other users to be added to that 1-1 chat. A second consideration is a complication unique to mimi. Consider two users in different providers. Which provider would act as the owning provider for the 1-1 chat? Mimi chooses to solve this problem outside of the protocol itself, through the following recommendations. Firstly, a user has symmetrical group chats - where both have the same pair of users, but differ only in their owning provider, each provider SHOULD merge the contents of these chats when rendering them to the user. This hides the fact that the content may in fact be split across two different group chats under the hood. Secondly, if the chat provider distinguishes, within its UI, 1-1 vs. group chats, and the user creates a 1-1 chat with a user in a different provider, the inviting provider should treat this group chat as a 1-1 chat, and not permit its user to add additional Rosenberg, et al. Expires 14 September 2023 [Page 10] Internet-Draft MIMI Protocol March 2023 parties. This does not prevent the other provider (or its user) from adding participants however, and thus there is some risk that this might happen. [OPEN ISSUE: we can solve this, by adding another property to the group chat to indicate that this meant to be a 1-1 chat. That could then be honored by the other side such that they are not able to add users to it]. 6. MIMI URI Syntax This specification defines a new URI, called the mimi URI. A mimi URI is a URL as defined by [RFC2396]. This specification officially registers the mimi URL using the registration procedures defined in [RFC2717]. The syntax of the mimi URI is as follows, using ABNF [RFC5234]: MIMI-URI = "mimi" ":" "//" provider [ ":" port ] "/" connectionId port = 1*5DIGIT provider = host connectionId = UUID An example of a valid MIMI URI is: mimi://provider.com/2afae6d3-0b55-4c2d-9dae-3f199d51f83f The first portion of the mimi URI is the scheme, which MUST be "mimi". What follows is a colon and double slash, present because the MIMI URI is a URL. What follows is a subset of valid authorities as defined by RFC2396. Specifically, it MUST be a valid host. This is followed by an optional port number. Though the MIMI URI doesnt refer to a distinct protocol - it makes use of HTTP - when the port is present, it means that the HTTP request generated for this connection MUST utilize the port number specificed. This is followed by a path separator "/" and then a connectionId. The connectionId MUST be formatted as a UUID. This specification does not require a specific technique for generating UUID, by they MUST be cryptorandom. The cryptograndomness is one dimension of the overall security offered by the mimi protocol. In particular, it prevents malicious guest users and malicious guest providers from trying to forge connection requests. The MIMI URI is formally registered with IANA using the registration in section {#iana}. Rosenberg, et al. Expires 14 September 2023 [Page 11] Internet-Draft MIMI Protocol March 2023 7. Connections This section specifies the connection process defined for MTP. MTP supports two distinct variations on the connection process - group- chat dependent, or group-chat independent. In the group-chat independent process, the inviting user first creates the connection to the invited user by specifying their userID. This triggers an out-of-band authorization process, and may take some time for the invited user to accept. Once they accept, the inviting user is notified. At that point, the inviting user can add the invited user to group chats. These subequent additions may be subject to authorized by the invited user as well. Those authorizations do not make use of any out-of-band communications. In the group-chat dependent process, the inviting user goes to a group chat, and adds the invited user by specifying their userID. This then triggers the out-of-band process, which may take some time for the invited user to accept. Once they accept, they are added to the group chat. Any any point in the future, the inviting user can add the invited user to other group chats. Those new additions may be subject to authorization by the invited user as well. Those authorizations do not make use of any out-of-band communications. 7.1. Group-Chat Independent Connection The group-chat independent connection process flows as follows: Rosenberg, et al. Expires 14 September 2023 [Page 12] Internet-Draft MIMI Protocol March 2023 +-----+ +-+ +-+ +---+ +---+ |Alice| |A| |B| |Bob| |OOB| +-----+ +-+ +-+ +---+ +---+ | | |store KeyPackages | | | | |<-----------------| | | | | | | |Connect | | | | |bob@example.com | | | | |--------------->| | | | | | | | | | mimi URI | | | | |<---------------| | | | | | | | | | | mimi URI | | |---------------------------------------------------------------->| | | | | | | | | | mimi URI | | | | |<-------------| | | | | | | | | mimi URI | | | | |<-----------------| | | | | | | | |Fetch context | | | | |cxnID | | | | |<-------------| | | | | | | | | | context | | | | |------------->| | | | | | | | | | | context | | | | |----------------->| | | | | | | | | | Authorize | | | | |<-----------------| | | | | | | | | Authorize | | | | | cxnID | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | Cxn Approved | | | | |<---------------| | | | | | | | | Continuing: Rosenberg, et al. Expires 14 September 2023 [Page 13] Internet-Draft MIMI Protocol March 2023 | | subscribe | | | | | cxnID | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | add Bob | | | | | chat ID | | | | | groupName | | | | |--------------->| | | | | | | | | | | notify | | | | | chatID | | | | | groupName | | | | |------------->| | | | | | | | | | | ask permission | | | | | groupName | | | | |----------------->| | | | | | | | | | grant | | | | |<-----------------| | | | | | | | |join request | | | | |chatID | | | | |cxnID | | | | |KeyPackages | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | JoinRequest | | | | | KeyPackages | | | | |<---------------| | | | | | | | | | | subscribe | | | | | groupID | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | Welcome | | | | | Commit | | | | |--------------->| | | | | | | | | Rosenberg, et al. Expires 14 September 2023 [Page 14] Internet-Draft MIMI Protocol March 2023 | | notify | | | | | Welcome | | | | |------------->| | | | | | | | | | | Welcome | | | | |----------------->| | When Bob first logs into a client, which causes him to upload KeyPackages to his provider B for usage in the connection process which follows. Each client used by Bob will trigger an upload of KeyPackages. It is a matter of local policy on how many KeyPackages Bob provides. KeyPackage exhaustion attacks are mitigated by MTP, this is discussed below. The connection process starts when Alice decides to create a connection to Bob. She requests to her provider to establish the connection, and provides an identifier for Bob. This identifier can be an email address, phone number or handle at a provider. The provider generates a connectionId, which MUST be unique in space and time. The provider MUST store this ID for a mimimum of 24 hours. The provider MUST store, associated with that ID, the identity of the user requesting the connection - userID and display name (Alice Doe, alice@gmail.com in this example), the identity of the user being invited (bob@example.com in this example), and the time at which the connection was requested. It then returns a MIMI URI to Alice's client, and instructs her to communicate this MIMI URI to Bob through some out of band means. Alice then sends the MIMI URI to Bob, through email, text or other means. This communication is directly from Alice to Bob, and does not utilize their respective providers chat services. In the case of texting for example, the SMS would be sent from Alice's mobile number to Bob's mobile number. In the case of email, it would be sent using one of Alice's email addresses from whatever email provider she uses, and be delivered to Bob's inbox. If Bob has Alice is his address book, or has received prior emails or texts from Alice, this will help him confirm that the connection request is truly from Alice. Typically, Alice would include additional information to help Bob decide whether to accept the request or not. For example, "Hi Bob - lets chat together, you can use whatever chat client you want - click here to accept. I want to discuss the new MIMI working group content with you.". Rosenberg, et al. Expires 14 September 2023 [Page 15] Internet-Draft MIMI Protocol March 2023 When Bob clicks on this link, it launches his preferred MIMI-enabled client, and the connection ID is passed to his client application. His client application would pass that to his provider. To gain more information about this connection request, Bob's provider utilizes MTP, and initiates a GET request to the owning provider, using the provider name extracted from the MIMI URI. Provider B specifically invokes the following REST API call: GET https://{provider-name}/.well-known/mimi/ connections/{connectionId} This request will contain an HTTP Authorization header field, containing a bearer token obtained out of bands from MTP. This is described further below. Using this bearer token, provider B will know that this is provider A, and can authorize the request. Once the GET request is authorized, Alice's provider A looks up the connection ID and retrieves Alice's name, Bob's userID and the time of the invitation. This information is passed back to provider B. Provider B MUST verify that the userID provided for Bob matches an identity by which Bob is known in the system. This is to prevent against copy-paste attacks, wherein the MIMI URI or connection ID is forwarded to a different user. Note that, there is no cryptographic verification of Bob's userID here. This component of the authorization process depends on mutual trust between the owning and guest providers. This context for the connection ID can then be shown to Bob in his client UI. He might see something like, "Alice Doe (alice@gmail.com) wants to add you to one or more group chats she's hosting on her provider. Do you want to allow that?". If Bob approves, he informs his provider. The guest provider MUST obtain explicit permission from the end user before accepting the connection request. Note that, this requirement is not enforced through e2e cryptographic means, and depends on a well-behaved guest provider. Once Bob's provider has obtained this permission, it MUST inform the owning provider as follows: POST https://{provider-name}/.well-known/mimi/ connections/{connectionId}?accept The connection request can also be rejected, as specified in the REST API details below. The response to this HTTP POST will be a JSON object, described below, which includes a connection ID resource that lives on the owning provider, along with a URI for it. This URI allows the guest provider to create a subscription to the connection. This subscription, accomplished via a long poll, allows the guest provider to request a stream of events for the connection. The Rosenberg, et al. Expires 14 September 2023 [Page 16] Internet-Draft MIMI Protocol March 2023 events include actions by the inviting user in the owning provider - Alice here - to add Bob to group chats. Should Alice decide to de- authorize the connection, this would also be delivered as an event over the subscription. Alice's provider will also inform her that Bob has accepted the connection. This may only get delivered next time Alice logs in, as she may be offline when Bob approved the connection. At some point in the future, Alice does log in, sees that the connection was approved, and now is capable of adding Bob to a group chat, which she does. To allow Bob to make a useful decision on whether to join this group - the name of the group, which will not be e2e encrypted with MLS - can be provided by Alice to her provider along with the request to add Bob (alternatively, the provider may already have it through some other means). Her provider, provider A, then requests permission from Bob to be added to the group chat. This is done by adding an event to the connection, which is a "group chat addition request". This event will get delivered via an event over the subscription to the connection to provider B. It always includes the groupID. Had Alice, or her provider, had access to the group name, this would be included as well. Details on the syntax of this event are described below. With this event in hand, provider B - based on its policies - can either request Bob's permission for that specific group, or take Bob's prior authorization as blanket approval for addition to all groups. This is a matter of local policy at provider B. In this example flow, provider B does request permission, and passes the groupName to Bob to make a decision. For example, he may see something like, "Alice wants to add you to the group 'MIMI Discussion'. Do you want to be added"? Bob informs his provider that he approves the addition to the group. His provider, provider B, takes all the previously stored KeyPackages from all of Bob's clients, and uses them to send a join REST API call to provider A. That is done using the following REST API: POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants?connect={connectionId} This request contains a single URI parameter - the connectionID - which is used for authorization purposes. The owning provider MUST verify that this connectionID exists and is currently valid, and that the particular group chat ID has been authorized for that connection (which, in this flow, it is). The body of this request will contain a multi-part MIME body, each of which contains an MLS KeyPackage. Provider B stores these key packages for delivery to Alice's client. It informs provider A of Rosenberg, et al. Expires 14 September 2023 [Page 17] Internet-Draft MIMI Protocol March 2023 the success. The response contains a JSON blob that includes a timestamp (used for synchronization). Now, provider B can create a subscription to receive events for this group chat. It does so using the following long-poll URI: POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/subscriptions?connect={connectionId}&from={timestamp} The connectionID is used by the owning provider once again to authorize the subcription, using the same logic as for the join request. The subscription includes a from URI parameter, which indicates the timestamp of the earliest set of events that the provider requires. This timestamp MUST be no larger than the value returned in the response to the join, to avoid race conditions where it misses the Welcome message. Provider B delivers these keypackages to Alice next time one of her clients comes online [OPEN ISSUE: the provider could also deliver them to any other user, not just ALice. Doing that however introduces an attack wherein a malicious owning provider can trick clients into adding users they didnt intend to. So, this seems like a bad idea. ] Once Alice gets these KeyPackages, she generates the MLS Welcome and Commit messages and sends them to her provider. The provider then sends the Welcome message over the long poll connection, and this too is delivered to Bob. 7.2. Group Chat Dependent Connection The group chat dependent process flows as follows: +-----+ +-+ +-+ +---+ +---+ |Alice| |A| |B| |Bob| |OOB| +-----+ +-+ +-+ +---+ +---+ | | |store KeyPackages | | | | |<-----------------| | | | | | | |Connect | | | | |bob@example.com | | | | |groupId | | | | |groupName | | | | |--------------->| | | | | | | | | | mimi URI | | | | |<---------------| | | | | | | | | | | mimi URI | | |---------------------------------------------------------------->| | | | | | Rosenberg, et al. Expires 14 September 2023 [Page 18] Internet-Draft MIMI Protocol March 2023 | | | | mimi URI | | | | |<-------------| | | | | | | | | mimi URI | | | | |<-----------------| | | | | | | | |Fetch context | | | | |cxn token | | | | |<-------------| | | | | | | | | | context | | | | |------------->| | | | | | | | | | | context | | | | |----------------->| | | | | | | | | | Authorize | | | | |<-----------------| | | | | | | | | Authorize | | | | | cxn token | | | | |<-------------| | | | | | | | | |success | | | | |connection ID | | | | |------------->| | | | | | | | | Cxn Approved | | | | |<---------------| | | | | | | | | | |subscribe | | | | |connection ID | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | |join request | | | | |chatID | | | | |cxnID | | | | |KeyPackages | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | JoinRequest | | | | | KeyPackages | | | | Rosenberg, et al. Expires 14 September 2023 [Page 19] Internet-Draft MIMI Protocol March 2023 |<---------------| | | | | | | | | | | subscribe | | | | | groupID | | | | |<-------------| | | | | | | | | | success | | | | |------------->| | | | | | | | | Welcome | | | | | Commit | | | | |--------------->| | | | | | | | | | | notify | | | | | Welcome | | | | |------------->| | | | | | | | | | | Welcome | | | | |----------------->| | +-----+ +-+ +-+ +---+ +---+ |Alice| |A| |B| |Bob| |OOB| +-----+ +-+ +-+ +---+ +---+ The significant difference from the connection independent flow is that this connection request is made coincident with adding the user Bob to the group chat. Alice's provider, in this case, offers her the ability to go to a group chat she is in, hit the 'add' button, and enter a userID for a user in another provider. She does so, entering a userID for Bob and passes this to her provider. Alice's provider generates a connectionID and MIMI URI as in the use case above. However, in this flow, it associates the groupName and groupId to the connectionID in addition to the timestamp, Alice's display name and userID and Bob's userID. This MIMI URI is delivered out of band to Bob. Bob's provider fetches the context for the connection ID. As with the other flow, the context includes Alice's email address and display name. However, it also includes the groupName and groupID. To avoid risks of spamming users with content delivered via these connection requests, the provider B SHOULD first prompt Bob with just Alice's email address, and if Bob confirms, only then prompt Bob with the group name. Rosenberg, et al. Expires 14 September 2023 [Page 20] Internet-Draft MIMI Protocol March 2023 Once Bob authorizes - he is authorizing the connection and the addition to the group chat concurrently. His provider, provider B, will authorize the connection using the connection ID. It subscribes to the connection, as above. In this case, it can immediately turn around and request a join to the group. This join is identical to the case above, and will include the groupID, connectionID and KeyPackages. The remainder of the flow is identical to the use case above. 7.3. Guest Connections Another use case supported by MTP, is that a guest user has already been added to a group chat, and that guest user wishes to add someone else to the group chat. We call this a guest addition. The flow for that works as follows: +-----+ +-+ +-+ +---+ |Alice| |A| |B| |Bob| +-----+ +-+ +-+ +---+ | | |add Charlie | | | |<------------| | | | | | |guest add | | | |charlie userID | | | |groupID | | | |<--------------| | | | | | | connection | | | | request | | | | Charlie userID | | | | groupID | | | |<----------------| | | | | | | |add Charlie flow | | | |---------------->| | | +-----+ +-+ +-+ +---+ |Alice| |A| |B| |Bob| +-----+ +-+ +-+ +---+ In this case, we have a group chat owned by owning provider A. Alice is one of the members of the group chat, also in the owning provider. Bob is a guest participant, and his provider is provider B. Charlie is also a user of provider B. Bob uses his client application and adds Charlie to the group chat. His provider would have a directory of users in this use case (since Charlie is in the same provider). Once Charlie has been selected, provider B then sends a request to the owning provider, provider A, to add Charlie to the group. This is done using the guest addition REST API: Rosenberg, et al. Expires 14 September 2023 [Page 21] Internet-Draft MIMI Protocol March 2023 POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{userId}?connect={connectionId} In this case, because the userID to be added is different than the one bound to the connection, the owning provider knows this is a guest addition. There will be no KeyPackages in this POST of course. This is treated like a request to the owning provider, for someone in the owning provider to create a connection to Bob in order for him to be added. The owning provider can send this to all participants in the group that are within the owning provider, or just some. One might imagine they get a message like "Bob wants to add Charlie to this group. To do that, you need to reach out to Charlie and add him in. OK?". If the user accepts, this would trigger a connection request flow - either group dependent or group independent, based on the policy of the provider. [OPEN ISSUE: this is definitely clunky - what if Alice doesnt know Charlie at all? We could support the ability for Bob to get a MIMI URI directly as well. That would allow Bob to communicate to CHarlie directly, but now imposes a greater security risk because A must trust that Bob isnt going to generate a lot of spam invites. The solution here optimizes for spam reduction at the expense of user experience.] 7.4. Mobile Centric UI This section describes a suggestion user interface implementation for mobile apps, and a mobile number centric invitation process. It also suggests an enhancement to mobile OS's for formal support for the mimi URI. In one possible implementation of a UI, a provider may elect to allow its users to add other users by entering their mobile phone numbers, perhaps by allowing the user to select from an address book. The provider would likely check its internal databases to determine whether the selected phone number is already a user of the system, and if not, offer the user the ability to invite them to join the conversation on whatever is their preferred provider. The mobile app of the owning provider would then cross-launch the native texting application on the mobile phone, and prepopulate a text message along the lines of, "Hi! I'd like to chat with you, you can do so using your favorite chat app - click here to join me and others: [link]". The link in the text message would be the mimi URI created by the owning domain. Assuming the inviting user already has some kind of SMS chat in progress with the invited user, this new message would appear within that context. The inviting user can press send, and this is Rosenberg, et al. Expires 14 September 2023 [Page 22] Internet-Draft MIMI Protocol March 2023 delivered via text to the invited user. This provides a form of forward routability, so that the invitation is only delivered to a user that owns that phone number. The invited user can, at their discretion, send additional text messages to provide context. This text would be received on the mobile phone of the receiving user. Note that it is a new URI scheme - the mimi URI. As of writing, both iOS and Android allow applications to register custom URI handlers. When an application supports mimi, it would register itself as a handler for the mimi URI. Furthermore, it would provide a setting in its settings menu, to say whether that particular app is the default application for handling inter-app messaging. If a user were to have multiple mimi-enabled apps on their phone, it would be at the discretion of the user to select only one as their default. When an app is unselected as default, it would unregister itself as a handler for the mimi URI. When the user clicks on the mimi URI, it would cross-launch their selected mobile app and pass it the URI parameters. The mobile application would prompt the user with something like, "Accept invitation to join chat room?" and if they say yes, it would initiate the acceptance procedures defined above. If mimi were to be adopted by the mobile OS vendors, an even better experience could be provided. The mobile OS vendors would explciitly recognize the mimi URI scheme, and allow multiple apps to register as handlers. The OS itself would have a setting for the default, which is perhaps the first one to register. When the second mobile app registers as a handler, the OS could ask the user if they wish to switch to that app as the default, or keep it. Similarly, there would be a setting in the mobile OS, which allows the user to pick their preferred app. This would show a dropdown list of all vendors whose apps are currently installed, but have registered themselves as handlers for the mimi URI. This is a (relatively) small change in functionality and thus not a big change. It is important to note that mimi is designed to work without any mobile OS support - it only requires implementation within the providers. Mobile OS support improves the experience by making management of the default messaging app much better. 8. REST APIs This section defines the REST endpoints for mimi. All mimi REST calls are from the guest provider to the owning provider. As a result, mimi only specifies behaviors for these endpoints on the owning provider. [TODO: add rest from owning to guest for claiming keypackages.] Rosenberg, et al. Expires 14 September 2023 [Page 23] Internet-Draft MIMI Protocol March 2023 8.1. Authentication and Authorization The owning provider MUST provide a mechanism, outside the scope of this specification, for a guest provider to obtain an OAuth access token that can be used as a bearer token in all HTTP requests. [@cullen: suggestions for additional wording here please]. This allows the owning provider to make decisions about which guest providers it will permit. Mimi does not require any specific authorization policy, and leaves this to the discretion of an owning provider, on which guest providers it will enable to connect. [OPEN ISSUE: an alternative is mutual TLS. Which do we want, or both?] 8.2. General Request Guidelines All mimi REST API operations MUST occur over HTTPS. All requests MUST include an Authorization header field containing the access token obtained by the provider out of band. All URI endpoints exist within the .well-known path, in order to avoid any possible namespace collisions with existing HTTP URIs hosted on the provider [RFC5785]. This specification registers a new well-known URI, "mimi". REST endpoints which return collections of resources support pagination. Pagination makes use of a page cursor technique. Paginated results do not guarantee that an item appears in only one page - the client must be prepared for duplication. A client can request an upper bound on elements per page with an optional pageLimit URI query parameter. For any paginated results, the server MUST include a pageLimit URI parameter in the response body, whose value is equal to or less than any pageLimit specified in the request URI. Each response will contain a "next" URI that includes a link to the next page, if present. That request will contain a "pageCursor" value, which is a string generated by the server and opaque to the client. This can be used by the server to support pagination and contain whatever content it likes. THe server MUST NOT send a pageCursor longer than 1023 characters. The body of any response that provides pagination looks like this: { "items": [ ... ], "paging": { "next": "{uri}&pageCursor={pageCursor}", "limit": {pageLimit} } } Rosenberg, et al. Expires 14 September 2023 [Page 24] Internet-Draft MIMI Protocol March 2023 Where the items property contains the array of items, and a paging property contains the information need for pagination. Where {variable} is substituted with the value of that variable. 8.3. Connection Information This REST endpoint allows a guest provider to obtain the meta-data associated with a connection. This is used to render the information to its user, to allow the user to make a decision on whether to accept the connection. The syntax for this endpoint is: GET https://{provider-name}/.well-known/mimi/ connections/{connectionId} The owning provider MUST authorize that this is a valid guest provider. The owning provider MUST validate that the connection ID is valid. Owning providers MUST maintain a minimum validity period of 24 hours for connection IDs in the PENDING state. Once authorized, the server returns the following payload in the 200 OK response, which represents the state of the connection resource: { "id" : "{connectionId}", "uri" : "https://{provider-name}/.well-known/mimi/ connections/{connectionID}", "createdAt" : "{timestamp}" "state" : "{state}", "source" : { "userID" : "{userId}", "provider" : "{provider-name}" }, "target" : { "userId" : "{userId}" "provider" : "{provider-name}" }, "groupChat" : { "id" : "{groupChatId}", "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/" } } Rosenberg, et al. Expires 14 September 2023 [Page 25] Internet-Draft MIMI Protocol March 2023 The id, uri, createdAt, source and target properties are mandatory. The source property refers to the user that is requesting the connection, and will be a user of the owning provider. The target represents the user whose connection is requested. Initially, the provider for this user is unknown. Consequently, only the userID property of the target will be present. The state property indicates the state of the connection, and is either PENDING or ACTIVE. When first created, its state is PENDING. Once confirmed, its state moves to ACTIVE. In the ACTIVE state, the provider-name for the target MUST be present. The groupChat property is present only when the connection was requested in the context of a specific group chat. [OPEN ISSUE: should this be a list, so as more group chats are authorized this grows?]. In the case of a group chat independent connection request, it would be absent. 8.4. Connection Acceptance or Rejection This REST endpoint allows a guest provider to accept a connection request on behalf of one of its users. The syntax for this endpoint is: POST https://{provider-name}/.well-known/mimi/ connections/{connectionID} The request can take either take the "accept" URI parameter, which indicates acceptance, or the "reject" URI parameter, which indicates rejection. Only one of the two can be present; a request with both is rejected with a 400. The owning provider MUST authorize that this is a valid guest provider. The owning provider MUST validate that the connection ID is valid. Owning providers MUST maintain a minimum validity period of 24 hours for connection IDs in the PENDING state. If the prior state of the connection was either PENDING or ACTIVE, and the accept parameter was present, the new state is ACTIVE. If the reject parameter is present, this is equivalent to deletion of the connection and the resource would no longer exist [OPEN ISSUE: Should we just do DELETE instead of a reject URI param] If the guest provider has accepted the connection, the response is a 200 OK containing a JSON payload in the same syntax as above. However, in this case, the STATE would be active and the target will include the provider-name. The owning provider knows the guest provider name, as a consequence of the authentication process used to authenticate the guest provider. Rosenberg, et al. Expires 14 September 2023 [Page 26] Internet-Draft MIMI Protocol March 2023 8.5. Join Request This REST endpoint allows a guest provider to request that their user join a group chat. This is always in response to a prior request from a user in the owning provider to add them, followed by an authorization decision by the invited user to proceed with the addition. The syntax for this endpoint is: POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants?connect={connectionId} From an MLS perspective, the user is not yet joined to the group - this method is delivering the key packages to the inviting user, so the inviting user in the owning provider can complete the addition of this user to the group. The only valid method against this endpoint is POST, which performs the join request operation by creating this participant in the group. The request has a single mandatory URI parameter, "connect", which contains the connectionID associated with this join request. The server MUST validate that the groupChatId is valid, and represents an active group chat. The server MUST validate that the connectionID in the connect parameter is valid, and represents a valid connection whose state is ACTIVE. If any one of these steps fails, the request MUST be rejected with a 403. Otherwise, the server proceeds to the next step. The body of the request MUST be of type multipart MIME. Each part MUST be of type message/mls, and MUST correspond to a KeyPackage. There SHOULD be a KeyPackage for each client that the guest currently has, and for each, include a KeyPackage for each ciphersuite supported by each client. The response to a successful request is a 201 created, which contains a URI for the participant resource that was just created. This URI will be of the form: https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{participantUUID} Note that this is a UUID for the participant, distinct from its more human readable participantID. This allows the URIs to contain a UUID without needing to worry about URI encoding of the participantID. The body contains a JSON representation of the participant. This JSON object is structured as follows: Rosenberg, et al. Expires 14 September 2023 [Page 27] Internet-Draft MIMI Protocol March 2023 { "id" : "{participantUUID}", "participantID" : "{participantId}, "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/ {groupChatId}/participants/ {participantUUID}", "joinedAt" : "{timestamp}" "provider" : "{provider-name}" "groupChat" : { "id" : "{groupChatId}", "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/" } } The timestamp MUST be formatted as a string in JSON, and be no longer than 16 characters. Its content MUST be valid timestamp, a positive integer measuring the number of milliseconds since Unix epoch time. That allows the timestamp to be monotonically increasing at the owning provider, and valid across different backend servers that may process the request. 8.6. Leave Request If a guest participant wishes to leave, its provider can invoke the following API: DELETE https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{participantUUID} The server MUST authorize that the request comes from a valid guest provider, and that the guest provider name matches the one associated with the user that is being removed. The server MUST validate that the groupID exists and is valid, and that the participant in question is part of the group chat at this time. Assuming all checks pass, the user is removed from the group at the MTP layer. The abouve REST endpoint will not longer be valid. This operation has no effect yet on the MLS of course. To do that, the owning domain SHOULD request a user in the owning domain to remove the participant. A user, upon accepting this request to be removed, will generate a new Commit message and sent it to the owning provider. This new Commit, with this user removed, will be distributed via the event stream to all other remaining participants. Rosenberg, et al. Expires 14 September 2023 [Page 28] Internet-Draft MIMI Protocol March 2023 [OPEN ISSUE: Do we want to allow non-owning members to process leave requests?] The DELETE request will generate an immediate 200 OK response and not await the MLS Commit message which removes the member from the group. 8.7. Guest Addition POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{userId}?connect={connectionId} Details to be filled in. 8.8. Add Message If a guest user wishes to add a message to a group chat, their provider invokes the following API: POST https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{participantUUID}/messages The body of the request has the media type message/mls. It contains the end-to-end encrypted application message. The server MUST validate that the groupChatId exists and is valid, the user with userId is a member of the group, has permissions to post messages, and that their provider is the same as the provider making the request (based on the Authorization header field). If any of these checks fail, the server MUST return a 403. If the message addition is successful, the server returns a 200 OK that includes the following JSON payload. This is not strictly needed for synchronization but reflects best practice in REST APIs to return a copy of the resource that was created. In this case, the meta-data of the message. { "id" : "{messageTimestamp}", "uri" : "https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{userId}/messages/ {messageTimestamp}", "groupChat" : { "id" : "{groupChatId}", "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/" } } Rosenberg, et al. Expires 14 September 2023 [Page 29] Internet-Draft MIMI Protocol March 2023 It is very important to note that the ID of this messages is not a UUID, but rather is a timestamp that represents the number of milliseconds since the Unix epoch time. This makes each message uniquely identified by the group chat ID and the timestamp. The server MUST enforce a rule that no two messages posted ever have the same timestamp, in order for the timestamps to serve as unique IDs. The timestamp is generated by the owning provider. 8.9. Retrieve Membership When a user intially joins the group, their UI will need to show the list of group members, including display names. Display names are not part of the MLS messages, and thus this endpoint is provided to allow a guest to retrieve them in paginated form for rendering purposes [OPEN ISSUE: This is contentious, do we need this]. This list is maintained by the owning provider. The following REST endpoint allows the guest provider to retrieve the current group membership: GET https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/ The server MUST validate that the groupChatId exists and is valid, and that at least one participant in the group is in a guest provider, and the guest provider name matches the provider name associated with the access token in the Authorization header field. If these checks do not pass, a 403 Forbidden response is returned. Otherwise, the server returns the group membership as a pagination. This follows the guidelines defined above for pagination. Each element of the item array is formatted as following: { "id" : "{userId}", "uri" : "https://{provider-name}/.well-known/mimi/group-chats/ {groupChatId}/participants/{participantUUID}", "name" : "{displayname}, "properties" { "provider" : "provider-name" }, "groupChat" : { "id" : "{groupChatId}", "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/" } } Rosenberg, et al. Expires 14 September 2023 [Page 30] Internet-Draft MIMI Protocol March 2023 The displayname is for display purposes, and can be set by the user at any time. It is however RECOMMENDED that mimi implementations on mobile devices which have access to the address book, instead utilize the display name from the address book instead of ones conveyed by mimi. Each user resource also contains a set of user properties. This set is extensible, either through an extension through a standards body, or through private registration. Initially, this specification has only a single property defined - provider - which contains the provider-name for that user. This would allow user interfaces to indicate when users are "guests" and which app they are using to access the chat. Additional properties which could be considered for future extension include whether or not a user is a moderator of the group, whether they have permission to post or delete messages, and so on. The owning provider includes the list of all properties it supports; any properties not understood by the client are just ignored. The group membership will include members that joined the group through the join REST API above, but for whom the MLS rekeying has not yet completed. Similarly, the membership will omit members that left the group using the REST API above, but for whom the MLS rekeying has not yet completed. 8.10. Retrieve Group Chat Information To retrieve information about the group: GET https://{provider-name}/.well-known/mimi/group-chats/{groupChatId} The server MUST validate that the groupChatId exists and is valid, and that at least one participant in the group is in a guest provider, and the guest provider name matches the provider name associated with the access token in the Authorization header field. If these checks do not pass, a 403 Forbidden response is returned. Mimi allows groups to have properties. [OPEN ISSUE: should we have default properties to handle things like moderation or make this extensible] Properties represent information about the group, distinct from its membership and messages. This specification defines a single property - groupName. Mimi allows for these to be extended to provide additional properties in the future. These extensions can be through IETF consensus or private registrations. Examples of functionality which can be introduced through new properties in the future include broadcast or read-only groups, moderated groups, and so on. If an owning domain is providing a property which is not registered with IANA, it MUST use a property Rosenberg, et al. Expires 14 September 2023 [Page 31] Internet-Draft MIMI Protocol March 2023 name that contains a reverse DNS version of its provider name, i.e., "com.messenger.newprop" would be used for a property called newprop that is proprietary to Facebook Messenger. These properties, including the group name, are returned in the response: { "id" : "{groupId}", "uri" : "https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}", "properties" { "groupName" : "{groupName}" }, } 8.11. Set Group Property To set a property of the group, including the group name, the following API is used: POST https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId} This requires has a mandatory URI parameter, userID, which contains the user that is performing this request. This request requires a second URI parameter, which is the property. This specification defines only one - groupname, whose value is a URI encoded version of the group name to use for the group. Any other properties known to the server, can be accepted in the request and saved. The server MUST validate that the groupChatId exists and is valid, that user userID in the userID parameter is valid and a member of the group, and their guest provider name matches the provider name associated with the access token in the Authorization header field. If these checks do not pass, a 403 Forbidden response is returned. The server then executes the property change. For the name, this name is set as a property of the group. Note that, the group name and associated properties are not e2e encrypted with MLS, since they may affect server side processing. [OPEN ISSUE: Im sure we need to discuss this one, including display name]. Rosenberg, et al. Expires 14 September 2023 [Page 32] Internet-Draft MIMI Protocol March 2023 8.12. Commit This REST endpoint is used to support the MLS protoocl, and allows users in guest providers to push a Commit message into the system, to be delivered to all other participants. [OPEN ISSUE: renaming this "handshake" to allow bare proposals as well.] POST https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/commits This requires has a mandatory URI parameter, participantUUID, which contains the participant that is performing this request. The server MUST validate that the groupChatId exists and is valid, that participantUUID is valid and a member of the group, and their guest provider name matches the provider name associated with the access token in the Authorization header field. If these checks do not pass, a 403 Forbidden response is returned. When receiving this request, the server MUST increase the epoch. [TODO: The _server_ doesn't increase the epoch. The Commit caused the group to enter a new epoch. The owning provider agrees that the new Commit is valid and therefore allows it to be sent to other clients.] It MUST ensure that all Commits are accepted and forwarded strictly in-order within an MLS group. [TODO: add reference to the language in section 4.2.1 of mls-architecture saying that this protocol requires Strongly Consistent ordering.] The response is a 200 OK with no body. [Question: does the epoch need to be returned?? No, the Commit contained the epoch.] [TODO: you need a response code which clearly indicates that the Commit had the wrong epoch.] Beyond that, the commit message is then distributed to participants using the synchronization protocol to drive MLS operations. 9. Synchronization The second major piece of functionality provided by mimi is a synchronization function. This function allows a guest domain to receive changes to the group chats and connections in real time, so it can handle them and process accordingly. Rosenberg, et al. Expires 14 September 2023 [Page 33] Internet-Draft MIMI Protocol March 2023 A guest domain MUST maintain a list of the group chats and connections for which its users have an active membership, which are in a different owning provider. This list is potentially very long - millions of group chats might exist. To subscribe to changes, the domain utilizes a set of subscriptions using an HTTP long poll. Each subscription is to one or more group chats or one or more connections. To subscribe to events for a group chat: POST https://{provider-name}/.well-known/mimi/ group-chats/{groupChatId}/events and for connections: POST https://{provider-name}/.well-known/mimi/ connections/{ConnectionId}/events Both requests take two optional parameters - "from" and "to" which contain timestamps. If the "to" parameter is absent, it means that the subscription should continue to deliver new events as they happen. If the "from" is absent. it means taht the subscription is from the beginning of time, and thus generate all historical events. The body of the response is a streaming JSON, representing an array of events. This naming introduces an important concept - that of an event. An event often is associated with the posting of a message, and this will be the most common event. But, it is not the only event. There are also events for changes in group membership, changes in group properties, changes in user properties, MLS Welcome and Commit messages. Each event has a unique timestamp, different from all other events. This means that all events form an ordered stream, which can be subscribed to. When a guest provider has missed events, it can also subscribe to events within a range of time, to fill in missing parts of the event stream. Each event in the stream is formatted as a JSON payload, with the following common format: { "eventTimestamp" : "{timestamp}", "type" : "{eventType}", } Rosenberg, et al. Expires 14 September 2023 [Page 34] Internet-Draft MIMI Protocol March 2023 The type conveys the type of event. Defined types are "message", "mls", "groupPropertyChange" and "userPropertyChange", "groupChatAddRequest", and so on. Depending on the type, there will be additional JSON properties, unique to that specific type. Details TBD. 10. Security Considerations Security is an essential part of this specification. The following subsections consider different threat vectors and how they are countered by mimi. 10.1. Spam Prevention The single most important consideration in the design of mimi, is ensuring that it doesnt become a vector for spam. In traditional email, it is possible for a malicious organization to send unwanted messages to any user, at very low cost. MIMI layers in several layers of protections to help prevent this. Of course, no technology can completely block all spam. 10.1.1. Consent Based Protection The first line of defense against this is the consent-based model used in mimi. Consider a malicious provider that acts as an owning provider for a particular group chat. In order for that provider to deliver messages to a target user with a given email address or mobile phone number, they cannot just send a message. This is because the guest provider associated with that user needs to actively pull messages for that group chat. To entice the target user to ask their guest provider to pull messages for this group chat, all of the following must happen: 1. A message, such as an email or text, must be sent to the target user with a mimi URI, 2. The target must click on the mimi URI, 3. The target must have a messaging app installed on their device, registered as a mimi handler If all three conditions are met, it would be possible for a malicious provider to cause unwanted chat messages to appear to the target. Clearly, it is possible for the malicious provider to send an email or text to the target with a mimi URI. In mimi, valid emails are sent by the email address and/or mobile number of the actual user, Rosenberg, et al. Expires 14 September 2023 [Page 35] Internet-Draft MIMI Protocol March 2023 not a system address. Emails from malicious providers are likely to come from a system address. As such, they are likely to be caught by normal email spam filters and by SMS filtering techniques used by mobile operators. In essence, MIMI "inherits" the existing network of anti-spam and SMS filtering techniques in place today. This helps reduce the likelihood of the malicious email getting through. Assuming it does get through, the target must be enticed to click on the MIMI URL. This is important. In mimi, it takes an active action on behalf of the recipient, to receive messages as part of a group chat. This is unlike spam emails or texts, where no action is required for the recipient to receive the unwanted message. Mimi allows users to differentiate a legiminate email or tet with a mimi URL, from an unwanted one. The main differentiator is the source of the message. In mimi, the text or email messages will be delivered using the mobile number or email address of the user generating the invite. Often, this will be someone known to the recipient, and thus match an entry in the user's mobile or email address book. In those cases, it is easy for the user to confirm that the request is legitimate. In cases where the inviting user is not known to the recipient, the email address or mobile number may not match an address book entry. In those cases, the invited user can respond and request further information before accepting the invitation. It is also the case that, over the past many years, many users have been trained to not click on links in unsolicited communications. As a result, one would expect the click rates on these links to be low, reducing the chance of the user accepting the invitation. As a final protection (albeit a small one), the receiving user must have a messaging app installed on their device that is compliant to mimi. If they do not, the invitation to chat will not be accepted. 10.1.2. Leave the Group In the case where a user is tricked into joining a group chat that delivers them unwanted actions - the user has a recourse - they can always leave the group. [NOTE: This is actually really hard in MLS.] This is in contrast to email, where a user has no way to opt-out of communications. With persistent group chat, they can always leave. Beacuse mimi is based on a pull architecture, once a user leaves a group by asking their guest provider to do so, the guest provider ceases to synchronize (and thus receive) messages for that group. Rosenberg, et al. Expires 14 September 2023 [Page 36] Internet-Draft MIMI Protocol March 2023 10.1.3. Malicious Sender Traceability Owing to the usage of MLS, all senders of chat messages are authenticated. This means the sender's original email address or mobile phone number will be signed. If the signature is provided by the malicious provider themselves, this is perhaps small consolation. However, should mimi make use of identities verified with a different, trusted third party identity source, this will provide good identification of the originator of the unwanted communications. 10.1.4. Provider Authorization In email, any domain is allowed to send email to any other domain. This has allowed email to be a global messaging fabric. But, its completely open nature have made it trivial for a malicious entity to spin up as many domains as it wants, and send email from any domain. In mimi, we do not expect this to be the case. In mimi, each provider needs to explicitly opt-in to the set of other providers whose mimi connections they will accept, or connect to. We anticipate that the larger providers in particular will implement quite strict policies on which other providers they connect to. Such connections are likely to be accompanied by significant offline vetting of the providers, to ensure they are legitimate, and provide human contact information that can be used to trace back in case malicious messages start to be sent from that provider. 10.2. Malicious Providers Manipulating other Users Consider a group chat with owning provider A, and guest providers B and C. The group chat consists of users A1, B1 and C1 from their respective providers. In this configuration, malicious provider C might attempt to manipulate the state of the group chat, by removing users A1 or B1. This attack is prevented by mimi. As part of the authorization checks performed by owning provider A, a provider is only permitted to request that a user leave the chat, if the user in question is a member of that provider. This check is done explicitly to prevent this attack. There are other similar attacks, wherein provider C tries to post a message as if it came from user B1 or A1. These attacks are prevented in mimi with this same mechanism, but are also prevented by MLS. This provides two layers of security for those kinds of attacks. Rosenberg, et al. Expires 14 September 2023 [Page 37] Internet-Draft MIMI Protocol March 2023 11. IANA Considerations 11.1. URI Scheme Registration This specification registers the mimi URI syntax as required by [RFC7595]. Scheme Name: mimi Status: Permanent Applications/protocols that use this scheme name: (NOTE TO RFC- EDITOR: Replace with the RFC number for this specification) Contact: Jonathan Rosenberg, jdrosen@jdrosen.net (mailto:jdrosen@jdrosen.net) Change Controller: IETF References: (NOTE TO RFC-EDITOR: Replace with the RFC number for this specification) 11.2. Well-Known URI Registration This specification registers the mimi well-known URI as required by [RFC5785]. URI Suffix: "mimi" Change Controller: "IETF" Specification Document: (NOTE TO RFC-EDITOR: Replace with the RFC number for this specification) 11.3. MIMI Property Registry [TODO: can you please provide an existence proof of a property that shows we needs this?] This specification establishes a new registry with IANA for MIMI properties. This registry contains the following parameters: Property Name: the name of the property being registered Context: The context is "user" for properties that apply to users only, "groupchat" for properties that apply to the group chat only, or "both" for properties which are defined for both. Rosenberg, et al. Expires 14 September 2023 [Page 38] Internet-Draft MIMI Protocol March 2023 Type: The syntax for the property. This must be one of string, enumerated string, boolean, or integer. [OPEN ISSUE: should we just make these all string and require the spec to define the type] Governing Authority: This can either be a recognized standards body, such as the IETF, or a private registration. Governing Specification: A link to the document defining the property. This can either be an IETF RFC, a specification from another standards body, or a document published somewhere on the Internet that contains information on the property. Contact: Name and email address of the contact for the registration {backmatter} This document instructs IANA to accept all registrations coming through the IETF standards process, for which an RFC performs the registration. For all others, expert review is required. 12. Normative References [I-D.ietf-mls-architecture] Beurdouche, B., Rescorla, E., Omara, E., Inguva, S., and A. Duric, "The Messaging Layer Security (MLS) Architecture", Work in Progress, Internet-Draft, draft- ietf-mls-architecture-10, 16 December 2022, . [I-D.ietf-mls-protocol] Barnes, R., Beurdouche, B., Robert, R., Millican, J., Omara, E., and K. Cohn-Gordon, "The Messaging Layer Security (MLS) Protocol", Work in Progress, Internet- Draft, draft-ietf-mls-protocol-17, 19 December 2022, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, DOI 10.17487/RFC2396, August 1998, . Rosenberg, et al. Expires 14 September 2023 [Page 39] Internet-Draft MIMI Protocol March 2023 [RFC2717] Petke, R. and I. King, "Registration Procedures for URL Scheme Names", RFC 2717, DOI 10.17487/RFC2717, November 1999, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010, . [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, DOI 10.17487/RFC6120, March 2011, . [RFC6121] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence", RFC 6121, DOI 10.17487/RFC6121, March 2011, . [RFC6914] Rosenberg, J., "SIMPLE Made Simple: An Overview of the IETF Specifications for Instant Messaging and Presence Using the Session Initiation Protocol (SIP)", RFC 6914, DOI 10.17487/RFC6914, April 2013, . [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015, . Authors' Addresses Jonathan Rosenberg Five9 Email: jdrosen@jdrosen.net Cullen Jennings Cisco Email: fluffy@iii.ca Suhas Nandakumar Cisco Rosenberg, et al. Expires 14 September 2023 [Page 40] Internet-Draft MIMI Protocol March 2023 Email: snandaku@cisco.com Rosenberg, et al. Expires 14 September 2023 [Page 41]