Linearized Matrix

Linearized Matrix The Matrix.org Foundation C.I.C.

travisr@matrix.org

The Matrix.org Foundation C.I.C.

matthew@matrix.org

Applications and Real-Time More Instant Messaging Interoperability matrix linearized interoperability messaging mimi decentralized This document specifies Linearized Matrix (LM). LM is an extensible protocol for interoperability between messaging providers, using Matrix's (matrix.org) decentralized room model. LM simplifies the Directed Acyclic Graph (DAG) persistence of Matrix while maintaining compatibility with non-linearized servers within a room. It does this by using a doubly-linked list of events/messages per room with hub and spoke fanout. LM's extensibility enables a wide range of transport protocol and end-to-end encryption possibilities. This document uses Matrix's room access control semantics supported by Messaging Layer Security (MLS), transported via HTTPS and JSON. The details of which server-to-server transport to use and what a is put over MLS are replaceable. The threat model of LM does not place trust in a central owning server for each conversation. Instead, it defines a hub server which handles maintaining linearized room history for other servers in the room. This model permits transparent interconnection between LM servers and Matrix servers, in the same room. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the More Instant Messaging Interoperability Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Linearized Matrix derives from Matrix (matrix.org). Matrix is an interoperable decentralized communications protocol with an open specification. Matrix uses a Directed Acyclic Graph (DAG) to persist rooms, synchronizing the DAG between servers. Linearized Matrix uses an append-only doubly-linked list. A hub server is present in each room to persist the linked list, and to handle linearization of events (user/application messages, as well as room configuration changes) from other servers. The hub server in a room does not act as an owner for the room. All rooms support the doubly-linked list and a DAG at the same time. The precise details of DAG and linked list interconnection are not covered by this document; they are out of scope for the More Instant Messaging Interoperability (MIMI) working group. Full details are available within the Matrix specification process as . Where applicable, this document covers the mandatory components. As rooms support these two representations, this permits a variable threat model. Messaging providers who want to deliver all their messages/don't trust other servers to deliver their messages would choose the DAG representation, at the cost of implementation complexity. Providers using the Linearized Matrix representation place trust in the hub server to deliver the messages. Those providers attach verifiable hashes and signatures to each event as a safeguard against the hub server modifying the events. The primary exports of Linearized Matrix are the room model and the rules which govern how a room accepts events. This document specifies a server-centric approach, where one or more servers perform access control. With some changes, it can become client-centric too. This document also specifies a transport for synchronizing the doubly-linked list to other servers. More efficient and scalable transport methods should replace this example. In a similar fashion, this document specifies how Messaging Layer Security (MLS) could run over a Linearized Matrix room. User messages use MLS, while state events (room configuration information) are plain-text in this iteration of the document. Clients synchronize room and MLS group membership, while servers verify those memberships. This ensures that users who are not in the room are unable to gain access to encrypted messages. A key component for interoperability is consistent access control semantics. Where a single server 'owns' a room, it can establish arbitrary measures. For example, an owning provider might decide that a different kind of password is required to join a room. This diminishes the user experience on providers who do not (or can not) support those custom measures. With decentralization, all participating servers must use the same consistent set of access controls. Linearized Matrix uses a decentralized room model for this reason, with linear room history for ease of implementation. Linearized Matrix also supports transferring a hub to a different server in the room. This enables two major features: a hub server that wishes to leave the room can do so, as it is no longer responsible for handling events for the room, and because the hub could change at any time, access control semantics must remain consistent. As a bonus, hub transfers make it possible for a (non-linearized) Matrix server to take hub status. When it becomes the hub, it takes responsibility for linearizing the room's DAG for other Linearized Matrix servers in the room. The DAG linearization algorithm is not specified in this document; it is out of scope for the MIMI working group.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses for the majority of terminology. This document additionally defines: Rejection: An event which is "rejected" is not relayed to any local clients and is not appended to the room in any way. Soft Failure: An event which is "soft-failed" SHOULD NOT be relayed to any local clients, nor be used as in auth_events if possible. The event is otherwise appended to the room as per usual. Further terms are introduced in-context within this document. TODO: We should move/copy those definitions up here anyways.

Architecture For a given conversation/room: | | | Provider/Server | | Provider/Server | | A |<---------( events )--------+ B | +-----+------------+ Server-Server Protocol +------------------+ | ^ | | +------------------+ | +----( events )--------+ | | | Provider/Server | +----------( events )------->| C | +------------+-----+ ^ | | | | V .--+---------. | Client C | '------------' ]]> In this diagram, events () are objects which carry information about the room as well as messages between users within that room. Server A is acting as a hub for the other two servers in the diagram. Servers B and C do not converse directly when sending events to the room: those events are instead sent to the hub which then distributes them back out to all participating servers. Servers communicate with each other using the API surface described by . Clients are shown in the diagram here for demonstrative purposes only. No Client-Server API or other requirements of clients are specified in this document. This leads to two distinct roles:

Hub server: the server responsible for holding conversation history on behalf of other servers in the room.
Participant server: any non-hub server. This server MAY persist conversation history or rely on the hub server instead.

OPEN QUESTION: Should we support having multiple hubs for increased trust between participant and hub? (participant can pick the hub it wants to use rather than being forced to use a single hub) OPEN QUESTION: Should we instead require that each server persist events they create, with the hub being responsible for purely distribution/fetching? It'd be in the hub's best interest to store all history, but equally if it can rebuild the room by reaching out to origin servers then it might be fine enough (it'd only be storing event IDs rather than whole events).

Server Names Each messaging provider is referred to as a "server" and has a "domain name" or "server name" to uniquely identify it. This server name is then used to namespace user IDs, room IDs/aliases, etc. A server name MUST be compliant with . Improper server names MUST be considered "uncontactable" by a server. A server MUST NOT use a literal IPv4 or IPv6 address as a server name. Doing so reduces the ability for the server to move to another internet address later, and IP addresses are generally difficult to acquire a certificate for (required in ). Additionally, servers SHOULD NOT use an explicit port in their server name for similar portability reasons. The approximate ABNF grammar for a server name is: Server names MUST be treated as case sensitive (eXaMpLe.OrG, example.org, and EXAMPLE.ORG are 3 different servers). Server names SHOULD be lower case (example.org) and SHOULD NOT exceed 230 characters for ease of use. The 230 characters specifically gives room for a suitably long localpart while being within the 255 allowable characters from . Examples:

example.org (DNS host name)
example.org:5678 (DNS host name with explicit port)

Rooms Rooms hold the same definition under : a conceptual place where users send and receive events. All users with sufficient access to the room receive events sent to that room. The different chat types are represented by rooms through state events (), which ultimately change how the different algorithms in the room version () behave. Rooms have a single internal "Room ID" to identify them from another room. The ABNF grammar for a room ID is: server_name is inherited from . room_id MUST NOT exceed 255 characters and MUST be treated as case sensitive. Example: !abc:example.org. The server_name for a room ID does NOT indicate the room is "hosted" or served by that domain. The domain is used as a namespace to prevent another server from maliciously taking over a room. The server represented by that domain may no longer be participating in the room. The entire room ID after the ! sigil MUST be treated as opaque. No part of the room ID should be parsed, and cannot be assumed to be human-readable.

Room Versions TODO: We should consider naming this something else. Each room declares which room version it's using, and each room version (identified by a single string) describes the specific algorithms a server needs to follow in order to particpate in rooms with that version. Room versions are immutable once specified, as otherwise a change in algorithms could cause a split-brain between servers participating in affected rooms. Room versions prefixed with I. MUST only be used within the IETF specification process. Room versions consisting solely of 0-9 and . MUST only be used by the Matrix protocol. This document as a whole describes I.1 as a room version. Servers MUST implement support for I.1 at a minimum. Servers SHOULD use I.1 when creating new rooms. Implementation note: Currently I.1 is not a real thing. Use org.matrix.i-d.ralston-mimi-linearized-matrix.02 when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. Implementation note: org.matrix.i-d.ralston-mimi-linearized-matrix.00 also exists in the wild, defining a set of algorithms which exist in a prior version of this document (00 and 01). TODO: Remove implementation notes. There is no implicit ordering or hierarchy to room versions. Future room versions, such as an I.2, can choose to build upon I.1's algorithms or start completely from scratch if they prefer. A room version has the following algorithms defined:

Event authorization - Rules which govern when events are accepted, rejected, or soft-failed by a server. For I.1, this is .
Redaction - Description of which fields to keep on an event during redaction. Redaction is used by the signing and hash algorithms, meaning they need to be consistent across implementations. For I.1, this is .
Event format - Which fields are expected to be present on an event, and the schema for each. For I.1, this is .
Canonical JSON - Specific details about how to canonicalize an event as JSON. This is used by the signing algorithm and must be consistent between implementations. For I.1, this is .
Hub selection - Rules around picking the hub server and transferring to a new hub. For I.1, this is .
Identifier grammar - All identifiers (room IDs, user IDs, event IDs, etc) can change grammar within a room version. As such, they SHOULD generally be treated as opaque as possible over a transport. For I.1, these details are described in , , , , and .

The transport between servers is decoupled from the algorithms above. For example, events are treated as blobs with no specific format over the wire but have strict schema in the context of a room or room version. Endpoints MUST be designed with this distinction in mind. Each room version has a "stable" or "unstable" designation. Stable room versions SHOULD be used in production by messaging providers. Unstable room versions might contain bugs or are not yet fully specified and SHOULD NOT be used in production by messaging providers. I.1 shall be considered "stable". Implementation note: org.matrix.i-d.ralston-mimi-linearized-matrix.02 is considered "unstable". TODO: Remove implementation notes. TODO: Matrix considers a version as stable once accepted through FCP. When would be the process equivalent for the IETF? The ABNF grammar for a room version is: Examples:

1
I.1
org.example.my-room-version

Room versions not formally specified SHOULD be prefixed using reverse domain name notation, creating a sort of namespace. org.example.my-room-version is an example of this.

Users As described by , a user is typically a human which operates a client. Each user has a distinct user ID. The ABNF grammar for a user ID is: server_name is inherited from . user_id MUST NOT exceed 255 characters and MUST be treated as case sensitive. Examples:

@alice:example.org
@watch/for/slashes:example.org

user_id_localpart SHOULD be human-readable and notably MUST NOT contain uppercase letters. server_name denotes the domain name () which allocated the ID, or would allocate the ID if the user doesn't exist yet. Identity systems and messaging providers SHOULD NOT use a phone number in a localpart. Using a phone number would mean that when a human operator's changes their phone number then they'd lose access to their existing chats and potentially gain access to any chats the new number is participating in. Providers which use phone numbers SHOULD ensure the new user ID is not in chats belonging to a different logical user. To prevent this case, a GUID (scoped to the allocating server) or an account ID is recommended as a localpart, allowing users to change their phone number without losing chats. This document does not define how a user ID is acquired. It is expected that an identity specification under MIMI will handle resolving email addresses, phone numbers, names, and other common queries to user IDs. User IDs are sometimes informally referenced as "MXIDs", short for "Matrix User IDs".

Devices Each user can have zero or more devices/active clients. These devices are intended to be members of the MLS group and thus have their own key package material associated with them. Because device IDs are used as "key versions" in a key ID (), they have a compatible ABNF grammar:

Events All data exchanged over Linearized Matrix is expressed as an "event". Each client action (such as sending a message) correlates with exactly one event. All events have a type to distinguish them, and use reverse domain name notation to namespace custom events (for example, org.example.appname.eventname). Event types using m. as a prefix MUST only be used by the protocol. When events are traversing a transport to another server they are referred to as a Persistent Data Unit or PDU. Structurally, an event and PDU are the same. An event has the following minimum fields:

room_id (string; required) - The room ID for where the event is being sent. This MUST be a valid room ID ().
type (string; required) - A UTF-8 string to distinguish different data types being carried by events. Event types are case sensitive. This MUST NOT exceed 255 characters.
state_key (string; optional) - A UTF-8 string to further distinguish an event as a state event (see ). Can be an empty string. This MUST NOT exceed 255 characters. Each event type specifies its own state key requirements. For m.room.member (), the state key is the user ID () for which the membership applies to. For m.room.join_rules (), this is an empty string. For a custom event type this may be an opaque string such as a UUID or randomly generated string.
sender (string; required) - The user ID which is sending this event. This MUST be a valid user ID ().
origin_server_ts (64-bit integer; required) - The milliseconds since the unix epoch for when this event was created.
hub_server (string; optional) - When a hub server is converting an LPDU () to a formal event, it MUST specify its own server name () here. The value MUST be a valid server name. To support interconnection with non-linearized Matrix, as discussed in , events created outside of a hub server MUST NOT populate this field.
content (object; required) - The event content. The specific schema depends on the event type. Clients and servers processing an event MUST NOT assume the content is safe or accurately represented. Malicious clients and servers are able to send payloads which don't comply with a given schema, which may cause unexpected behaviour on the receiving side. For example, a field marked as "required" might be missing.
hashes (object; required) - The content hashes () for the event. There is a special lpdu key to contain the LPDU (partial PDU schema; see ) hashes, which is itself keyed by hash algorithm and has the encoded hash as the value. The hashes object, outside of lpdu, similarly is keyed by hash algorithm with encoded hash values. Events which specify a hub_server MUST additionally contain an lpdu hash. All other events MUST NOT contain lpdu hashes. This is to support interconnection with non-linearized Matrix, as discussed in .
signatures (object; required) - Keyed first by domain name then by key ID, the signatures for the event.
auth_events (array of strings; required) - The event IDs which prove the sender is able to send this event in the room. Which specific events are put here are defined by the auth events selection algorithm ().
prev_events (array of strings; required) - This field is to support interconnection with non-linearized Matrix, discussed in . Events which specify a hub_server are expected to have exactly 1 entry in this array, while other events MAY have 1 or more entries.

Note that an event ID is not specified on the schema. Event IDs are calculated to ensure accuracy and consistency between servers. To determine the ID for an event, calculate the reference hash () then encode it using URL-safe Unpadded Base64 () and prefix that with the event ID sigil, $. For example, $nKHVqt3iyLA_HEE8lT1yUaaVjjBRR-fAqpN4t7opadc. Using a reference hash in the event ID prevents other servers from changing what that event ID represents. If an event ID was just a UUID (or similar), any server along the send or receive path could swap the actual event payload out for a different event. The hashes and signatures in this case do nothing to protect the actual event, as a malicious server can simply generate legal hashes/signatures as part of their modification. If we add a namespace condition where the event ID must reference the same server name as the sender ($uuid:example.org) then the sending server is free to re-assign the event ID to a different payload during the sending of that event, though all other servers along the send/receive path cannot change the event. This is particularly problematic if the event's sender is the hub for the room: the hub can send one copy of an event to half the room, and a very different copy to the other half while still maintaining the same event ID for both halves. To fix this, a hash of the event itself would need to become part of the event ID such that any modification or reassignment of the event ID is made obvious to receipient servers. This could be a tuple of (uuid, hash), though for simplicity this document uses just the reference hash on its own. With event IDs containing hashes of the events it's theoretically possible for a sufficiently motivated person to build a database of event IDs. With that database, they could eventually determine enough information to identify parts of the event payload itself. There is not enough anchoring information on an event (or sent over the transport) for this to be efficient or effective, however. The ABNF for an event ID is: If both the sender and receiver are implementing the algorithms correctly, the event ID will be the same. When different, the receiver will have issues accepting the event (none of the auth_events will make sense, for example). The sender and receiver will need to review that their implementation matches the specification in this case. Events are treated as JSON within the protocol, but can be encoded and represented by any binary-compatible format. Additional overhead may be introduced when converting between formats, however. An example event is: " }, "sha256": "" }, "signatures": { "first.example.org": { "ed25519:1": "" }, "second.example.org": { "ed25519:1": "" } }, "auth_events": ["$first", "$second"], "prev_events": ["$parent"] } ]]> An event/PDU MUST NOT exceed 65536 bytes when formatted using Canonical JSON (). Note that this includes all signatures on the event. Fields have no size limit unless specified above, other than the maximum 65536 bytes for the whole event.

Linearized PDU All events generated by participant servers are routed through the hub, but the participant servers themselves are unable to populate fields like prev_events because they can't guarantee order and those fields contribute to the event ID, signatures, and overall validity. To fix this, participant servers send the hub server a "Linearized PDU" or "LPDU" which does not include the fields they cannot set while still ensuring integrity of the event contents themselves. The participant server MUST NOT populate the following fields on events (LPDUs) they are sending to the hub:

auth_events - the participant cannot reliably determine what allows it to send the event.
prev_events - the participant cannot reliably know what event precedes theirs.
hashes (except hashes.lpdu) - top-level hashes cover the above two fields.

The participant server MUST populate the hashes.lpdu object, covering a content hash () of the partial event, giving authenticity to the sender's contents. The participant server additionally signs this partial event before sending it to the hub. The participant server will receive an echo of the fully-formed event from the hub once appended to the room.

State Events State events track metadata for the room, such as name, topic, and members. State is keyed by a tuple of type and state_key. The state "at" an event is the set of state events which have the most recent (in terms of event ordering, not timestamp) state tuple. For example, consider the following (simplified) room history: The state at index 2 consists of Alice's m.room.member event () and the m.room.create event () from the room. The m.room.encrypted event itself is not a state event and therefore does not get appended to the state "at" any particular event. The state at index 4 would have Alice's new m.room.member event, Bob's m.room.member event, and the m.room.create event from before. Alice's old membership event is overridden due to having the same type and state_key as the previous event. Note however that the state at index 3 still contains the older membership event, as the new event happens later with respect to event ordering. "Current state" is the state at the most recent event in the room. Calculating the state at a given event is needed for the authorization rules () and event visibility () algorithms. Clients additionally need to know current state to show accurate room names, topics, avatars, etc.

Stripped State Stripped state event are extremely simplified state events to provide context to a user for an invite () or knock (). Servers and clients have no ability to verify the events outside of the context for a room, so all such fields are removed. Servers and clients MUST NOT rely on the events being accurate because they cannot independently verify them. When generating stripped state for an invite or knock, the following events SHOULD be included if present in the current room state itself:

m.room.create ()
m.room.name (TODO: Link)
m.room.avatar (TODO: Link)
m.room.topic (TODO: Link)
m.room.join_rules ()
m.room.canonical_alias (TODO: Link)

Servers MAY include other event types/state keys. The above set gives users enough context to determine if they'd like to knock/join the room, as features such as the name and avatar are generally key pieces of information for a user. Stripped state events MUST only have sender, type, state_key, and content from the event schema (). Example:

Event Types Linearized Matrix defines the following event types. The section headers are the event type.

m.room.create The very first event in the room. It MUST NOT have any auth_events or prev_events, and the domain of the sender MUST be the same as the domain in the room_id. The state_key MUST be an empty string. The content for a create event MUST have at least a room_version field to denote what set of algorithms the room is using. These conditions are checked as part of the event authorization rules ().

m.room.join_rules Defines whether users can join without an invite and other similar conditions. The state_key MUST be an empty string. Any other state key, including lack thereof, serve no meaning and are treated as though they were a custom event. The content for a join rules event MUST have at least a join_rule field to denote the join policy for the room. Allowable values are:

public - anyone can join without an invite.
knock - users must receive an invite to join, and can request an invite (knock) too.
invite - users must receive an invite to join.

TODO: Describe restricted (and knock_restricted) rooms? TODO: What's the default?

m.room.member Defines the membership for a user in the room. If the user does not have a membership event then they are presumed to be in the leave state. The state_key MUST be a non-empty string denotating the user ID the membership is affecting. The content for a membership event MUST have at least a membership field to denote the membership state for the user. Allowable values are:

leave - not participating in the room. If the state_key and sender do not match, this was a kick rather than voluntary leave.
join - participating in the room.
knock - requesting an invite to the room.
invite - invited to participate in the room.
ban - implies kicked/not participating. Cannot be invited or join the room without being unbanned first (moderator sends a kick, essentially).

These conditions are checked as part of the event authorization rules (), as are the rules for moving between membership states. The content for a membership event MAY additionally have a reason field containing a human-readable (and usually human-supplied) description for why the membership change happened. For example, the reason why a user was kicked/banned or why they are requesting an invite by knocking.

m.room.power_levels Defines what given users can and can't do, as well as which event types they are able to send. The enforcement of these power levels is determined by the event authorization rules (). The state_key MUST be an empty string. The content for a power levels event SHOULD have at least the following:

ban (integer) - the level required to ban a user. Defaults to 50 if unspecified.
kick (integer) - the level required to kick a user. Defaults to 50 if unspecified.
invite (integer) - the level required to invite a user. Defaults to 0 if unspecified.
redact (integer) - the level required to redact an event sent by another user. Defaults to 50 if unspecified.
events (map) - keyed by event type string, the level required to send that event type to the room. Defaults to an empty map if unspecified.
events_default (integer) - the level required to send events in the room. Overridden by the events map. Defaults to 0 if unspecified.
state_default (integer) - the level required to send state events in the room. Overridden by the events map. Defaults to 50 if unspecified.
users (map) - keyed by user ID, the level of that user. Defaults to an empty map if unspecified.
users_default (integer) - the level for users. Overridden by the users map. Defaults to 0 if unspecified.

TODO: Include notifications for at-room here too? Note that if no power levels event is specified in the room then the room creator (sender of the m.room.create state event) has a default power level of 100. These conditions are checked as part of the event authorization rules ().

m.room.history_visibility TODO: Describe.

Calculating Event Visibility TODO: Describe. (when can a server see an event?). Mention that m.mls.commit is exempt. TODO: This section feels like it's in the wrong place. Bring it closer to on-receive-event sections.

TODO: Other events TODO: m.room.name, m.room.topic, m.room.avatar, m.room.canonical_alias

MLS Considerations TODO: We should consider running over LM instead. Using something like would be good for more of a client-side representation of the LM room model. The MIMI working group is chartered to use Messaging Layer Security (MLS) for encryption in chats, and this document specifies no different. Each room has a single MLS Group associated with it, both identified by the room ID (). Rooms additionally track membership at a per-user level while MLS tracks group membership at a per-device level. With this consideration, commits to the MLS Group MUST use PublicMessage, giving the hub server an ability to inspect MLS group membership changes for illegal joins and leaves. Encryption can only be enabled at the time the room is created. This prevents the room having encryption disabled or downgraded without an entirely new room being created. The exact ciphersuite and other algorithmic details are contained in the content for the m.room.create event (): algorithm denotes which specific algorithm clients MUST use for sending and receiving encrypted events in the room. If a received event is encrypted using a different algorith, it MUST be treated as undecryptable (even if the client has sufficient key information to decrypt it). m.mls.v1. as a prefix describes the behaviour for encrypted clients, with the remainder of the algorithm string covering the exact ciphersuite. This document uses the same mandatory ciphersuite as MLS: MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519. Thus, this is encoded as m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519. Other ciphersuites can be represented similarly, though are considered to be entirely new encryption algorithms for the purposes of this document. Custom or non-standard encryption algorithms are possible with this approach, however out of scope for MIMI. If such an algorithm is used, it SHOULD be prefixed using reverse domain name notation. For example, org.example.my-encryption. Mentioned in the introduction (), this document does not explore the details for what is needed to interconnect Linearized Matrix and Matrix's existing room model. However, for interconnection to be successful, extensions to MLS are needed to support decentralization. One possible extension is "Decentralised MLS" .

Device Credentials Under Section 5.3 of , each MLS group member (a device, ) has a "credential" or signing key associated with it. These are published to each client's local server and available over federation (). This document relies upon out-of-band verification and therefore uses basic credentials. The format for the credential is: ; opaque device_id; opaque signature_key; } BasicCredential; ]]> user_id is as described by , and device_id is as described by . signature_key is from MLS. The device then constructs the following object, signs it using each of the listed keys, and publishes it through its local server (): " }, "signatures": { "@alice:example.org": { "m.mls.v1.credential.ed25519:ABCDEF": "" } } } ]]> device_id is the client's device ID (). user_id is the user ID () to which the device ID belongs. algorithms are the encryption algorithms the device supports, and SHOULD contain at least m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519. When a device supports m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519, it MUST specify its basic credential with the m.mls.v1.credential.ed25519 key algorithm. keys is an object containing each algorithm-specific key (or keys) for the device. The fields for the object form a key ID, with the device ID representing the "key version", as per . All top-level fields in the object above MUST be supplied. For each of the device's keys, a valid signature MUST be produced. If there is a missing signature from any of the keys, or from the user_id, the device information is considered invalid. Invalid devices MUST NOT be members of the MLS group, and are removed if already members prior to the device information becoming invalid.

Group Creation After the m.room.create event and other initial state events for the room are sent, the room creator MUST establish the appropriate MLS group. This is sent as an m.mls.commit event (). Afterwards, the remaining devices are added as normal (). Ideally, the m.room.create event would also contain the initial public group state, however doing so would mean either tracking an independent MLS group ID or allowing the client to specify the room ID. While servers MAY allow the client to specify the room ID, servers usually have better context for which localparts (see ) are already claimed by other rooms. Having independent group IDs and room IDs can lead to confusion and a similar sort of namespacing issue (a room creator can create a conflicting group ID). Instead, the server (usually) creates the room on behalf of the client, allowing the client to then send the initial public group state to the room for other MLS members.

Updating Group State This document does not provide a way to send proposals to the MLS group, meaning all commits MUST only contain proposals which are sent by the same member (see ). All commits are encoded as m.mls.commit events () and are sent to the room. These commits are additionally encoded using PublicMessage, giving servers visibility on the contents of the commits. Upon receiving the event (see ), the hub server MUST additionally validate that any membership changes match what is possible with the room membership:

Devices can only be added to the group if they belong to a user which is joined to the room, or if the room is "world readable" (). It is generally not enough to be invited, knocking, etc on the room - the user ID must usually be in the join state.
Devices can be removed in two ways:
- A device can remove another device if they both belong to the same user ID.
- A device can be removed by anyone if the user ID to which it belongs is no longer in the join state. This condition is required to satisy a case in MLS where a device cannot self-remove itself from the group.

If this validation fails, the hub server MUST reject the request if it's shaped as an LPDU () and soft-fail the event if it's a PDU (). Welcome messages are sent to devices over to-device messaging (). The message_type for the message is m.room.encrypted [TODO: Rename to avoid confusion with room event?] and message of: ", "commit_event_id": "" } ]]> algorithm is the ciphersuite, dhkemx25519-aes128gcm-sha256-ed25519, prefixed with m.mls.v1.welcome. The remaining fields are as described in the example. See for "unpadded base64". All fields MUST be supplied. Note that the sender's user ID and device ID are made available over the to-device messaging endpoints (). In all cases, a device remembers the event ID (either from the m.mls.commit event or commit_event_id from a to-device message) after decryption to associate it with the MLS epoch. The device can then do a reverse lookup of epoch to event ID to MLS group state. Note that a client always has access to m.mls.commit events, even when hidden by history visibility (). TODO: Is it correct to say all commits are visible as "shared"? TODO: We may need to store the group state in the media repo if it gets to be too big, or otherwise allow oversized events. TODO: The server also likely needs to prevent devices being added to the group which don't support the ciphersuite/algorithm.

Key Packages Clients "claim" another device's key package through their server (). Clients will typically generate several key packages and upload them to their server, making them available even if the client goes offline. The algorithm for a key package is m.mls.v1.key_package.dhkemx25519-aes128gcm-sha256-ed25519 and is combined with a device-generated key version, forming a key ID described by . The key version SHOULD be generated based upon the key package itself rather than using an unrelated string, such as a hash or the public key of the key package.

Room Event Types TODO: Should these be defined with the other event types rather than here? This document describes the following event types for use with MLS-encrypted rooms. The section headers are the event type. See for more information on events. These event types are non-state events, also called "room events".

m.mls.commit Represents an MLS commit, which may be rejected by the hub server. content for the event MUST contain at least the following example: ", "public_group_state": "" } ]]> As mentioned, message is a PublicMessage from MLS. public_group_state is to enable external joins. An optional field, prev_commit_event_id, SHOULD be specified when a parent commit exists. This is to enable clients to find the commit they have keys for upon joining the room, as the most recent one may not be decryptable to them. The client can then work forwards from where they can decrypt the message. TODO: Should we use the RatchetTree extension? It might make the group state massive... TODO: Which fields from this need to be protected by ?

m.room.encrypted Represents an encrypted MLS application message. The sender first encrypts the message per the content format then MUST send an event with content matching: ", "commit_event_id": "" } ]]> Within this document, algorithm will be m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519. The other fields are as described in the example. Clients SHOULD treat m.room.encrypted events which are improperly structured as undecryptable events. TODO: Which fields from this need to be protected by ?

Processing Events An event has several authenticity properties:

Content hashes () to cover the LPDU () and event () contents.
Reference hashes () which double as the event ID, covering the redacted event.
Signatures from the direct senders (server name of the sender and the hub_server if present), ensuring the entities did actually produce that event.

TODO: Does the hub's signature actually guard anything? These properties are validated throughout this document. Each property has different behaviour when violated. For example, a difference in content hash ultimately causes the event to be stored as a redacted copy.

Receiving Events/PDUs TODO: This section conflates sending and receiving a bit more than it should. Split sending out to its own section. When a hub receives an LPDU from a participant it MUST add the missing fields to create a fully formed PDU then MUST send that PDU back out to all participants, including the original sender. A server is considered to have "received" an event when it does not recognize the event ID. This may be because the event has not yet been persisted, or the server is not persisting anything (in the case of a participant server). This includes when the server asks another server for an event it might be missing. When a server (hub or participant) receives an event, it MUST:

Verify the event matches the schema for the room version (), without considering type-specific schemas applied to content. If an event fails to meet this requirement, it is dropped/ignored.
Ensure the required signatures are present and that they are valid (). If the event has a hub_server field, the event MUST be signed by that server. The event MUST also be signed by the server implied by the sender, noting that this will be an LPDU if hub_server is present. All other signatures MUST NOT be considered for signature validation, regardless of their individual validity. If the event fails to meet this requirement, it is dropped/ignored.
Ensure the event has a valid content hashes (). If the event has a hub_server field, it MUST have a content hash which covers the LPDU. If either the LPDU or PDU content hash doesn't match what the receiving server calculations, the event is redacted before further processing. The server will ultimately persist the redacted copy.

Additionally, a hub server MUST complete the following checks. Participant servers SHOULD also perform the following checks to validate that the hub server is acting in a compliant manner. If the hub is not acting appropriately (for example, by sending the participant an event which never should have been accepted), the participant server MAY choose to warn its local users that the room history may have been tampered with.

The constraints described by validated, if the room is encrypted.

Authorization Rules These are the rules which govern whether an event is accepted into the room, depending on the state events surrounding that event. A given event is checked against multiple different sets of state.

Auth Events Selection The auth_events on an event MUST consist of the following state events, with the exception of an m.room.create event which has no auth_events.

The m.room.create state event.
The current m.room.power_levels state event, if any.
The sender's current m.room.member state event, if any.
If the type is m.room.member:
1. The target's (state_key) current m.room.member state event, if any.
2. If content.membership is join or invite, the current m.room.join_rules state event, if any.

TODO: Talk about restricted room joins here?

Calculating Power Levels A requirement of the authorization rules is being able to determine the current/future "power level" for a user. All power levels are calculated with reference to the content of an m.room.power_levels state event (). To calculate a user's current power level:

If users is present, use the power level for the user ID, if present.
If users is not present, or the user ID is not present in users, use users_default.
If users_default is not present, use 0.

To calculate the required power level to do an action:

If the action (kick, ban, invite, or redact) is present, use that power level.
If not present, use the default for the action (50 for kick, ban, and redact, 0 for invite).

To calculate the required power level to send an event:

If events is present, use the power level for the event type, if present.
If events is not present, or the event type is not present in events:
1. If state_key is present (including empty), use state_default.
  1. If state_default is not specified, use 50.
2. If state_key is not present, use events_default.
  1. If events_default is not specified, use 0.

Auth Rules Algorithm With consideration for default/calculated power levels (), each event MUST pass the following rules. "Current state" (and "current membership", etc) are the state of the room before the event being checked is applied. TODO: should we reference m.federate?

Events must be signed () by the server denoted by the sender field. Note that this may be an LPDU if the hub_server is specified and not the same server. If the event is improperly signed, reject the event.
If hub_server is present on the event, the event must be signed () by that server. If it is improperly signed, reject the event.
If the event's type is m.room.create:
1. If it has any prev_events, reject the event.
2. If the domain of the room_id is not the same domain as the sender, reject the event.
3. If content.room_version is not I.1, reject the event.
4. Otherwise, allow the event.
Considering the event's auth_events: TODO: Does this check make sense for Linearized Matrix? We already removed what was #3 because it talked about rejecting events which reference rejected events.
1. If there are duplicate entries for a given type and state_key pair, reject the event.
2. If there are entries whose type and state_key do not match those specified by the auth events selection algorithm (), reject the event.
3. If there is no m.room.create event among the entries, reject.
If the event's type is m.room.member:
1. If there is no state_key property, or no membership in content, reject the event.
2. If the event content's membership field is join:
  1. If the previous event is an m.room.create event and the state_key is the creator, allow the event.
  2. If sender does not match state_key, reject the event.
  3. If the sender is banned, reject the event.
  4. If the join_rule for m.room.join_rules is invite or knock, then allow the event if the current membership state is invite or join.
  5. If the join_rule for m.room.join_rules is public, allow the event.
  6. Otherwise, reject the event.
3. If the event content's membership field is invite:
  1. If the sender's current membership state is not join, reject the event.
  2. If the target user's (state_key) membership is join or ban, reject the event.
  3. If the sender's power level is greater than or equal to the power level needed to send invites, allow the event.
  4. Otherwise, reject the event.
4. If the event content's membership field is leave:
  1. If the sender matches the state_key, allow the event if and only if that user's current membership state is knock, join, or invite.
  2. If the sender's current membership state is not join, reject the event.
  3. If the target user's (state_key) current membership state is ban, and the sender's power level is less than the power level needed to ban other users, reject the event.
  4. If the sender's power level is greater than or equal to the power level needed to kick users, and the target user's (state_key) power level is less than the sender's, allow the event.
  5. Otherwise, reject the event.
5. If the event content's membership field is ban:
  1. If the sender's current membership state is not join, reject the event.
  2. If the sender's power level is greater than or equal to the power level needed to ban users, and the target user's (state_key) power level is less than the sender's power level, allow the event.
  3. Otherwise, reject the event.
6. If the event content's membership field is knock:
  1. If the join_rule for m.room.join_rules is anything other than knock, reject the event.
  2. If the sender does not match the state_key, reject the event.
  3. If the sender's current membership state is not ban or join, allow the event.
  4. Otherwise, reject the event.
7. Otherwise, the membership is unknown. reject the event.
If the sender's current membership state is not join, reject the event.
If the event type's required power level to send it is greater than the sender's power level, reject the event.
If the event has a state_key which starts with an @ and does not match the sender, reject the event. TODO: Do we care? This is theoretically to allow for owned state events, but in practice nothing which uses this concept makes it this far into the auth rules (membership events are validated above).
If the event's type is m.room.power_levels:
1. If any of the fields users_default, events_default, state_default, ban, redact, kick, or invite in content are present and not an integer, reject the event.
2. If events in content is present and not an object with values that are integers, reject the event.
3. If the users in content is present and not an object with valid user IDs as keys and integers as values, reject the event.
4. If there is no previous m.room.power_levels event in the room, allow the event.
5. For the fields users_default, events_default, state_default, ban, redact, kick, and invite, check if they were added, changed, or removed. For each found alteration:
  1. If the current value is higher than the sender's current power level, reject the event.
  2. If the new value is higher than the sender's current power level, reject the event.
6. For each entry being changed in or removed from events:
  1. If the current value is higher than the sender's current power level, reject the event.
7. For each entry being added to or changed in events:
  1. If the new value is greater than the sender's current power level, reject the event.
8. For each entry being changed in or removed from users, other than the sender's own entry:
  1. If the current value is higher than the sender's current power level, reject the event.
9. For each entry being added to or changed in users:
  1. If the new value is greater than the sender's current power level, reject the event.
10. Otherwise, allow the event.
Otherwise, allow the event.

There are some consequences to these rules:

Unless you are already a member of the room, the only permitted operations (aside from the initial create/join) are being able to join public rooms, accept invites to rooms, and reject invites to rooms.
To unban another user, the sender must have a power level greater than or equal to both the kick and ban power levels, and greater than the target user's power level.

TODO: If we want to enforce a single hub in a room, we'd do so here with auth rules.

Signing All servers, including hubs and participants, publish an ed25519 signing key to be used by other servers when verifying signatures. These keys can then be fetched over the transport as needed (). TODO: Verify RFC reference. We might be using a slightly different ed25519 key today? See https://hdevalence.ca/blog/2020-10-04-its-25519am Each key ID consists of an algorithm name and version. Signing keys MUST use an algorithm of ed25519 (and therefore MUST be an ed25519 key). The key version MUST be valid under the following ABNF : An algorithm and version combined is a "key ID", deliminated by : as per the following ABNF : Additional key algorithms may be supported by future documents.

Signing Events To sign an event:

Redact it ().
Sign the result as an arbitrary object ().

Signing Arbitrary Objects To sign an object:

Remove signatures if present.
Encode the result with Canonical JSON ().
Using the relevant ed25519 signing key (usually the server's), sign the object.
Encode that signature under signatures using unpadded base64 ().

Note that signatures is an object with keys being the entity which did the signing and value being the key ID to encoded signature pair. See for details on the signatures structure for events specifically.

Checking Signatures If the signatures field is missing, doesn't contain the entity that is expected to have done the signing (usually a server name), doesn't have a known key ID, or is otherwise structurally invalid then the signature check fails. If decoding the base64 fails, the check fails. If the object is an event, redact () it before continuing. If removing the signatures property, canonicalizing the JSON (), and verifying the signature fails, the check fails. Note that to verify the signature the server may need to fetch another server's key first (). Otherwise, the check passes. TODO: Which specific signatures are required? If a server has multiple signing keys, possibly a combination of new and old, do we require all or some of them to sign?

Canonical JSON When signing a JSON object, such as an event, it is important that the bytes be ordered in the same way for everyone. Otherwise, the signatures will never match. To canonicalize a JSON object, use . TODO: Matrix currently doesn't use RFC8785, but it should (or similar).

Event Redactions All fields at the top level except the following are stripped from the event:

type
room_id
sender
state_key
content
origin_server_ts
hashes
signatures
prev_events
auth_events
hub_server

Additionally, some event types retain specific fields under the event's content. All other fields are stripped.

m.room.create retains all fields in content.
m.room.member retains membership.
m.room.join_rules retains join_rule.
m.room.power_levels retains ban, events, events_default, kick, redact, state_default, users, users_default, and invite.
m.room.history_visibility retains history_visibility.

Hashes An event is covered by two hashes: a content hash and a reference hash. The content hash covers the unredacted event to ensure it was not modified in transit. The reference hash covers the essential fields of the event, including content hashes, and serves as the event's ID.

Content Hash Calculation TODO: Describe what this protects, and why it matters.

Remove any existing signatures field.
1. If calculating an LPDU's () content hash, remove any existing hashes field as well.
2. If not calculating an LPDU's content hash, remove any existing fields under hashes except for lpdu.
Encode the object using canonical JSON.
Hash the resulting bytes with SHA-256 .
Encode the hash using unpadded base64 ().

Reference Hash Calculation TODO: Describe what this protects, and why it matters.

Redact the event.
Remove signatures field.
Encode the object using canonical JSON.
Hash the resulting bytes with SHA-256 .
Encode the hash using URL-safe unpadded base64 ().

Unpadded Base64 Throughout this document, "unpadded base64" is used to represent binary values as strings. Base64 is as specified by , and "unpadded base64" simply removes any = padding from the resulting string. Implementations SHOULD accept input with or without padding on base64 values, where possible. describes URL-safe base64. The same changes are adopted here. Namely, the 62nd and 63rd characters are replaced with - and _ respectively. The unpadded behaviour is as described above.

Hub Selection TODO: Describe impacts of hub transfers The hub server for a room is the server denoted by the sender of the m.room.create event (). Note that this is effectively the same as the server name contained in the room ID () currently, however is deliberately not defined as such. In a future scenario where hub transfers are possible, the room ID does not change when the hub server does.

Hub Transfers TODO: This section, if we want a single canonical hub in the room. Some expected problems in this area are: who signs the transfer event? who sends the transfer event? how does a transfer start? TODO: Likely to be done with an m.room.hub state event in the room, where the "current hub" is either the sender of m.room.hub or m.room.create if no hub state event is present. Auth rules would govern what makes for a legal m.room.hub event. TODO: may be of help here.

Transport This document specifies a wire transport which uses JSON over HTTPS . Servers MUST support a minimum of HTTP/2 and TLS 1.3 . TODO: This transport doesn't scale, and doesn't use RESTful endpoints. This example transport is heavily inspired by Matrix's existing Server-Server API, largely acting as a starting point for testing interoperability of the access control semantics. A better option might be gRPC, which might change how events are structured but keep the overall semantics the same. might have ideas here as well for REST APIs.

TLS Certificates Servers MUST provide a TLS certificate signed by a known Certificate Authority. Requesting servers are ultimately responsible for the Certificate Authorities they place trust in, however servers SHOULD trust authorities which would commonly be trusted by an operating system or web browser.

API Standards

Requests and Responses All HTTP POST and PUT endpoints require the sending server to supply a (potentially empty) JSON object as the request body. Requesting servers SHOULD supply a Content-Type header of application/json for such requests. All endpoints which require a server to respond with a JSON object MUST include a Content-Type header of application/json. All JSON data, in requests or responses, MUST be encoded using UTF-8 . All endpoints in this document do not support trailing slashes on them. When such a request is encountered, it MUST be handled as an unknown endpoint (). Examples include:

https://example.org/_matrix/path - valid.
https://example.org/_matrix/path/ - unknown/invalid.
https://example.org//_matrix/path - unknown/invalid (domain also can't have a trailing slash).
https://example.org//_matrix/path/ - doubly unknown/invalid.

Servers (both hub and participants) MUST implement all endpoints unless otherwise specified. Most endpoints have a version number as part of the path. This version number is that endpoint's version, allowing for breaking changes to be made to the schema of that endpoint. For clarity, the version number is not representative of an API version.

Errors All errors are represented by an error code defined by this document and an accompanied HTTP status code. It is possible for a HTTP status code to map to multiple error codes, and it's possible for an error code to map to multiple HTTP status codes. When a server is returning an error to a caller, it MUST use the most appropriate error response defined by the endpoint. If no appropriate error response is specified, the server SHOULD use M_UNKNOWN as the error code and 500 Internal Server Error as the HTTP status code. Errors are represented as JSON objects, requiring a Content-Type: application/json response header: errcode is required and denotes the error code. error is an optional human-readable description of the error. error can be as precise or vague as the responding server desires - the strings in this document are suggestions. Some common error codes are:

M_UNKNOWN - An unknown error has occurred.
M_FORBIDDEN - The caller is not permitted to access the resource. For example, trying to join a room the user does not have an invite for.
M_NOT_JSON - The request did not contain valid JSON. Must be accompanied by a 400 Bad Request HTTP status code.
M_BAD_JSON - The request did contain valid JSON, but it was missing required keys or was malformed in another way. Must be accompanied by a 400 Bad Request HTTP status code.
M_LIMIT_EXCEEDED - Too many requests have been sent. The caller should wait before trying the request again.
M_TOO_LARGE - The request was too large for the receiver to handle.

Unsupported Endpoints If a server receives a request for an unsupported or otherwise unknown endpoint, the server MUST respond with an HTTP 404 Not Found status code and M_UNRECOGNIZED error code. If the request was for a known endpoint, but wrong HTTP method, a 405 Method Not Allowed HTTP status code and M_UNRECOGNIZED error code ().

Malformed Requests If a server is expecting JSON in the request body but receives something else, it MUST respond with an HTTP status code of 400 Bad Request and error code M_NOT_JSON (). If the request contains JSON, and is for a known endpoint, but otherwise missing required keys or is malformed, the server MUST respond with an HTTP status code of 400 Bad Request and error code M_BAD_JSON (). Where possible, error for M_BAD_JSON should describe the missing keys or other parsing error.

Transaction Identifiers Where endpoints use HTTP PUT, it is typical for a "transaction ID" to be specified in the path parameters. This transaction ID MUST ONLY be used for making requests idempotent - if a server receives two (or more) requests with the same transaction ID, it MUST return the same response for each and only process the request body once. It is assumed that requests using the same transaction ID also contain the same request body between calls. A transaction ID only needs to be unique per-endpoint and per-sending server. A server's transaction IDs do not affect requests made by other servers or made to other endpoints by the same server.

Rate Limiting Servers SHOULD implement rate limiting semantics to reduce the risk of being overloaded. Endpoints which support being rate limited are annotated in this document. If a rate limit is encountered, the server MUST respond with an HTTP 429 Too Many Requests status code and M_LIMIT_EXCEEDED error code (). If applicable, the server should additionally include a retry_after_ms integer field on the error response to denote how long the caller should wait before retrying, in milliseconds. The exact rate limit mechanics are left as an implementation detail. A potential approach may be to prevent repeated requests for the same resource at a high rate and ensuring a remote server does not request more than a defined number of resources at a time.

Resolving Server Names Before making an API request, the caller MUST resolve a server name () to an IP address and port, suitable for HTTPS traffic. A server MAY change the IP/port combination used for API endpoints using SRV DNS records . Servers MAY additionally change which TLS certificate is presented by using .well-known delegation. .well-known delegation (step 3 below) is recommended for its ease of configuration over SRV DNS records. The target server MUST present a valid TLS certificate () for the name described in each step. Similarly, the requesting server MUST use an HTTP Host header matching the description in each step. Server developers should note that many of the DNS requirements for the steps below are typically handled by the software language or library implicitly. It is rare that a DNS A record needs to be resolved manually, for example. Per , a server name consists of <hostname>[:<port>]. The steps to convert that server name to an IP address and port are:

If <hostname> has an explicit <port> is present, resolve <hostname> to an IP address using CNAME , AAAA , or A DNS records. Requests are made to the resolved IP address and port number. TLS certificate: <hostname> (always without port) Host header: <hostname>:<port>
A regular (non-Matrix) HTTPS request is made to https://<hostname>/.well-known/matrix/server, expecting the schema defined by . If the response is invalid (bad/not JSON, missing properties, non-200 response, etc), skip to Step 4. If the response is valid, the m.server property is parsed as <delegated_hostname>[:<delegated_port>].
1. If <delegated_hostname> has an explicit <delegated_port> is present, resolve <delegated_hostname> to an IP address using CNAME, AAAA, or A DNS records. Requests are made to the resolved IP address and port number. TLS certificate: <delegated_hostname> (always without port) Host header: <delegated_hostname>:<delegated_port>
2. An SRV DNS record is resolved for _matrix._tcp.<delegated_hostname>. This may result in another hostname and port to be resolved using AAAA or A DNS records. Requests are made to the resolved IP address and port number. TLS certificate: <delegated_hostname> Host header: <delegated_hostname> (without port)
3. If no SRV record is found, an IP address is resolved for <delegated_hostname> is resolved using CNAME, AAAA, or A DNS records. Requests are made to the resolved IP address with port number 8448. TLS certificate: <delegated_hostname> Host header: <delegated_hostname> (without port)
If the .well-known call from Step 3 resulted in an invalid response, an SRV DNS record is resolved for _matrix._tcp.<hostname>. This may result in another hostname and port to be resolved using AAAA or A DNS records. Requests are made to the resolved IP address and port number. TLS certificate: <hostname> (always without port) Host header: <hostname> (without port)
If the .well-known call from Step 3 resulted in an invalid response, and the SRV record from Step 4 was not found, and IP address is resolved using CNAME, AAAA, or A DNS records. Requests are made to the resolved IP address and port 8448. TLS certificate: <hostname> (always without port) Host header: <hostname> (without port)

We require <[delegated_]hostname> rather than <srv_hostname> in Steps 3.3 and 4 for the following reasons:

DNS is largely insecure (not all domains use DNSSEC ), so the target of the SRV record must prove it is a valid delegate/target for <[delegated_]hostname> via TLS.
recommends this approach, and is consistent with other applications which use SRV records (such as /XMPP).

Server implementations and owners should additionally note that the target of a SRV record MUST NOT be a CNAME, as per RFC 2782 :

the name MUST NOT be an alias (in the sense of RFC 1034 or RFC 2181)

GET /.well-known/matrix/server Used by the server name resolution approach to determine a delegated hostname for a given server. 30x HTTP redirection MUST be followed, though loops SHOULD be avoided. Normal X.509 certificate validation is applied to this endpoint (not the specific validation required by the server name resolution steps) . This endpoint MAY be implemented by servers (it is optional). Rate-limited: No. Authentication required: No. This HTTP endpoint does not specify any request parameters or body. 200 OK response: m.server is a required response field. Responses SHOULD have a Content-Type HTTP header of application/json, however servers parsing the response should assume that the body is JSON regardless of Content-Type header. Failures in parsing the JSON or otherwise invalid data that prevents parsing MUST NOT result in discovery failure. Instead, the caller is expected to move on to the next step of the name resolution approach. Cache control headers SHOULD be respected on a 200 OK response. Callers SHOULD impose a maximum cache time of 48 hours, regardless of cache control headers. A default of 24 hours SHOULD be used when no cache control headers are present. Error responses (non-200) SHOULD be cached for no longer than 1 hour. Callers SHOULD exponentially back off (to a defined limit) upon receiving repeated error responses.

Request Authentication Most endpoints in this document require authentication to prove which server is making the request. This is done using public key digital signatures. The request method, target, and body are represented as a JSON object, signed, and appended as an HTTP Authorization header with an auth scheme of X-Matrix. The object to be signed is: method is the HTTP request method, capitalized. uri is the full request path, beginning with the leading slash and containing the query string (if present). uri does not contain the https: scheme or hostname. TODO: Define an ordering algorithm for the query string (if we need to?). origin and destination are the sender and receiver server names (), respectively. content is the JSON-encoded request body. When a request doesn't contain a body, such as in GET requests, use an empty JSON object. That object is then signed () by the requesting server. The resulting signature is appended as an Authentication HTTP header on the request: " Content-Type: application/json {"json_request_body": true} ]]> Linebreaks within Authorization are for clarity and are non-normative. The format of the Authorization header matches . The header begins with an authorization scheme of X-Matrix, followed by one or more spaces, followed by an (unordered) comma-separated list of parameters written as name=value pairs. The names are case insensitive, though the values are. The values must be enclosed in quotes if they contain characters which are not allowed in a token, as defined by . If a value is a valid token it may not be enclosed in quotes. Quoted values MAY contain backslash-escaped characters. When parsing the header, the recipient must unescape the characters. The exact parameters are:

origin - The name of the sending server. MUST match the origin in the signed JSON.
destination - The name of the receiving server. MUST match the destination in the signed JSON.
key - The ID, including algorithm name, of the sending server's signing key used to sign the request.
signature - The unpadded base64 () encoded signature from step 2.

Unknown parameters are ignored and MUST NOT result in authentication errors. A receiving server validates the Authorization header by composing the JSON object represented above and checking the sender's signature (). Note that to comply with the receiver may need to append a signatures field to the JSON object manually. All signatures MUST use an unexpired key at the time of the request (). A server with multiple signing keys SHOULD include an Authorization header for each signing key. If an endpoint requires authentication, servers MUST:

Validate all presented Authorization headers.
Ensure at least one Authorization header is present.

If either fails (lack of headers, or any of the headers fail validation), the request MUST be rejected with an HTTP 401 Unauthorized status code and M_FORBIDDEN error code (): If an endpoint does not require authentication, Authorization headers are ignored entirely. Responses from a server are authenticated using TLS and do not have additional signing requirements.

Retrieving Server Keys TODO: Explain what notaries are and what they do, if we keep this section at all. A server's signing keys are published under /_matrix/key/v2/server () and can be queried through notary servers in two ways: and . Notary servers implicitly call /_matrix/key/v2/server when queried, signing and caching the response for some time. This allows the target server to offline without affecting their previously sent events. The approach used here is borrowed from the Perspectives Project , modified to cover the server's ed25519 keys and to use JSON instead of XML. The advantage of this system is it allows each server to pick which notaries it trusts, and can contact multiple notaries to corroborate the keys returned by any given notary. Servers SHOULD attempt to contact the target server directly before using a notary server. Note that these endpoints operate outside the context of a room: a server does not need to participate in any shared rooms to be used as a notary by another server, and does not need to use the hub as a notary.

Validity A server's keys are only valid for a short time, denoted by valid_until_ts. Around the valid_until_ts timestamp, a server would re-fetch the server's keys to discover any changes. In the vast majority of cases, only valid_until_ts changes between requests (keys are long-lived, but validated frequently). valid_until_ts MUST be handled as the lesser of valid_until_ts and 7 days into the future, preventing attackers from publishing long-lived keys that are unable to be revoked. Servers SHOULD use a timestamp approximately 12 hours into the future when responding with their keys. TODO: What does it mean to require events have an origin_server_ts which is less than that of valid_until_ts? Do we reject the event, soft-fail it, or do something else? Do we only do this on the hub?

GET /_matrix/key/v2/server Retrieves the server's signing keys. The server can have any number of active or inactive keys at a time, but SHOULD have at least 1 active key at all times. Rate-limited: No. Authentication required: No. This HTTP endpoint does not specify any request parameters or body. 200 OK response: " } }, "old_verify_keys": { "ed25519:bad": { "expired_ts": 1586776437176, "key": "" } }, "signatures": { "example.org": { "ed25519:0": "" } } } ]]> server_name MUST be the name of the server () which is returning the keys. valid_until_ts is the integer timestamp (milliseconds since Unix epoch) for when the server's keys should be re-fetched. See . m.linearized is an optional boolean, but SHOULD be set to true. Semantics for false and not being present apply to contexts outside of this document. verify_keys are the current signing keys for the server, keyed by key ID (). The object value for each key ID under verify_keys is simply the key, consisting of the unpadded base64 encoded public key matching that algorithm and version. old_verify_keys are similar to verify_keys, but have an additional required expired_ts property to denote when the key ceased usage. This overrides valid_until_ts for the purposes of at an individual key level. TODO: What about events sent with old_verify_keys? For request authentication (), only keys listed under verify_keys are honoured. If another key is referenced by the Authorization headers, the request fails authentication. Notaries SHOULD cache a 200 OK response for half of its lifetime to avoid serving stale values. Responding servers SHOULD avoid returning responses which expire in less than an hour to avoid repeated requests. Requesting servers SHOULD limit how frequently they query for keys to avoid flooding a server with requests. If the server fails to respond to this request, notaries SHOULD continue to return the last response they received from the server so that the signatures of old events can still be checked, even if that response is no longer considered valid (). Servers are capable of rotating their keys without populating old_verify_keys, though this can cause reliability issues if other servers don't see both keys. Notaries SHOULD cache responses with distinct key IDs indefinitely. For example, if a server has ed25519:0 and ed25519:1 on its first response, and a later response returns ed25519:1 and ed25519:2, the notary should cache both responses. This gives servers an ability to validate ed25519:0 for old events in a room.

GET /_matrix/key/v2/query/:serverName This is one of two endpoints for querying a server's keys through another server. The notary (receiving) server will attempt to refresh its cached copy of the target server's keys through /_matrix/key/v2/server, falling back to any cached values if needed. Rate-limited: No. Authentication required: No. Path parameters:

:serverName - the target server's name () to retrieve keys for.

Query parameters:

minimum_valid_until_ts (integer; optional) - The time in milliseconds since the Unix epoch the target server's keys will need to be valid until to be useful to the caller. If not specified the notary server's current time will be used.

Request body: None applicable. 200 OK response: server_keys is the array of keys (see response format) for the target server. If the target server could not be reached and the notary has no cached keys, this array is empty. If the keys do not meet minimum_valid_until_ts per , they are not included. The notary server MUST sign each key returned in server_keys by at least one of its own signing keys. The calling server MUST validate all signatures on the objects.

POST /_matrix/key/v2/query A bulk version of /_matrix/key/v2/query/:serverName (). The same behaviour applies to this endpoint. Rate-limited: No. Authentication required: No. Path parameters: None applicable. Query parameters: None applicable. Request body: server_keys is required and is the search criteria. The object value is first keyed by server name which maps to another object keyed by Key ID, mapping to the specific criteria. If no key IDs are given in the request, all of the server's known keys are queried. If no servers are given in the request, the response MUST contain an empty server_keys array. minimum_valid_until_ts holds the same meaning as in . 200 OK response: Same as with the following added detail: Responding servers SHOULD only return signed key objects for the key IDs requested by the caller, however servers MAY respond with more keys than requested. The caller is expected to filter the response if needed.

Sending Events Events accepted into the room by a hub server must be sent to all other servers in that room. Similarly, participant servers need a way to send partial events through the hub server, as mentioned by . A single endpoint is used for all rooms on either server, and can contain both fully-formed PDUs () or Linearized PDUs (partial events; ) depending on the server's role in the applicable room. A typical event send path will be: | | | | | | PUT /send/:txnId | | +------------------------------------------------>| | | | ]]> PUT /send/:txnId is shorthand for . Hubs which generate events would skip to the point where they create a fully-formed PDU and send it out to all other participants. When a hub is broadcasting events to participant servers, it MUST include the following targets:

The server implied by the sender for a kick or ban m.room.member () event, up to the point of that kick or ban.
All servers which have at least 1 user which is joined to the room.

PUT /_matrix/federation/v2/send/:txnId Sends (L)PDUs (, ) to another server. The sending server MUST wait for a 200 OK response from the receiver before sending another request with a different :txnId. Implementation note: Currently this endpoint doesn't actually exist. Use PUT /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: No. Authentication required: Yes. Path parameters:

:txnId - the transaction ID () for the request.

Query parameters: None applicable. Request body: edus are the Ephemeral Data Units () to send. If no EDUs are being sent, this field MAY be excluded from the request body. There MUST NOT be more than 100 entries in edus. pdus are the events/PDUs () and LPDUs () to send to the server. Whether it's an LPDU or PDU depends on the sending server's role in that room: if they are a non-hub server, it will be an LPDU. There MUST NOT be more than 50 entries in pdus. Each event in the pdus array gets processed as such:

Identify the room ID for the event. The exact format of the event can differ between room versions, however currently this would be done by extracting the room_id property.
1. If that room ID is invalid/not found, the event is rejected.
2. If the server is not participating in the room, the event is dropped/skipped.
If the event is an LPDU and the receiving server is the hub, the additional PDU fields are appended before continuing.
If the event is an LPDU and the receiving server is not the hub, the event is dropped/skipped.
The checks defined by are performed.
If the event still hasn't been dropped/rejected, it is appended to the room. For participant servers, this may mean it's queued for sending to local clients.

Server implementation authors should note that these steps can be condensed, but are expanded here for specification purposes. For example, an LPDU's signature can/will fail without ever needing to append the PDU fields first - the server can skip some extra work this way. 200 OK response: The receiving server MUST NOT send a 200 OK response until all events have been processed. Servers SHOULD NOT block responding to this endpoint on sending accepted events to local clients or other participant servers, as doing so could lead to a lengthy backlog of events waiting to be sent. Sending servers SHOULD apply/expect a timeout and retry the exact same request with the same transaction ID until they see a 200 OK response. If the sending server attempts to send a different transaction ID from the one already in flight, the receiving server MUST respond with a 400 Bad Request HTTP status code and M_BAD_STATE error code (). Receiving servers SHOULD continue processing requests to this endpoint event after the sender has disconnected/timed out, but SHOULD NOT process the request multiple times due to the transaction ID (). failed_pdus is an object mapping event ID () to error string. Event IDs are based upon the received object, not the final/complete object. For example, if an LPDU is sent, gets its PDU fields appended, and fails event authorization, then the error would be for the event ID of the LPDU, not the fully-formed PDU. This is to allow the sender to correlate what they sent with errors. The object for each event ID MUST contain an error string field, representing the human-readable reason for an event being rejected. Events which are dropped/ignored or accepted do not appear in failed_pdus. TODO: Should we also return fully-formed PDUs for the LPDUs we received?

Event and State APIs When a participant in the room is missing an event, or otherwise needs a new copy of it, it can retrieve that event from the hub server. Similar mechanics apply for getting state events, current state of a room, and backfilling scrollback in a room. All servers are required to implement all endpoints (), however only hub servers are guaranteed to have the full history/state for a room. While other participant servers might have history, they SHOULD NOT be contacted due to the high likelihood of a Not Found-style error.

GET /_matrix/federation/v2/event/:eventId Retrieves a single event. Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/event/:eventId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:eventId - the event ID () to retrieve. Note that event IDs are typically reference hashes () of the event itself, which includes the room ID. This makes event IDs globally unique.

Query parameters: None applicable. Request body: None applicable. 200 OK response: The response body is simply the event () itself, if the requesting server has reasonable visibility of the event (). When the server can see an event but not the contents, the event is served redacted () instead. If the event isn't known to the server, or the requesting server has no reason to know that the event even exists, a 404 Not Found HTTP status code and M_NOT_FOUND error code () is returned. The returned event MUST be checked before being used by the requesting server (). This endpoint MUST NOT return LPDUs (), instead treating such events as though they didn't exist.

GET /_matrix/federation/v1/state/:roomId Retrieves a snapshot of the room state () at the given event. This is typically most useful when a participant server prefers to store minimal information about the room, but still needs to offer context to its clients. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to retrieve state in.

Query parameters:

event_id (string; required) - The event ID () to retrieve state at.

Request body: None applicable. 200 OK response: The returned room state is in two parts: the pdus, consisting of the events which represent "current state" () prior to considering state changes induced by the event in the original request, and auth_chain, consisting of the events which make up the auth_events () for the pdus and the auth_events of those events, recursively. The auth_chain will eventually stop recursing when it reaches the m.room.create event, as it cannot have any auth_events. TODO: Do we actually need to recurse auth events to get the full auth chain here? What are participant servers expected to do with this information? (Do they even care about it?) For example, if the requested event ID was an m.room.power_levels event, the returned state would be as if the new power levels were not applied. Both auth_chain and pdus contain event objects (). If the requesting server does not have reasonable visibility on the room (), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code () is returned. The same error is returned if the event ID doesn't exist in the requested room ID. Note that the requesting server will generally always have visibility of the auth_chain and pdu events, but may not be able to see their contents. In this case, they are redacted () before being served. The returned events MUST be checked before being used by the requesting server (). This endpoint MUST NOT return LPDUs (), instead treating such events as though they didn't exist. If the receiving server is not the hub server for the room ID, an HTTP status code of 400 Bad Request and error code M_WRONG_SERVER () is returned.

GET /_matrix/federation/v1/state_ids/:roomId This performs the same function as but returns just the event IDs instead. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to retrieve state in.

Query parameters:

event_id (string; required) - The event ID () to retrieve state at.

Request body: None applicable. 200 OK response: See for behaviour. Note that auth_chain becomes auth_chain_ids when using this endpoint, and pdus becomes pdu_ids.

GET /_matrix/federation/v2/backfill/:roomId Retrieves a sliding window history of previous events in a given room. Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/backfill/:roomId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to retrieve events from.

Query parameters:

v (string; required) - The event ID () to start backfilling from.
limit (integer; required) - The maximum number of events to return, including v.

Request body: None applicable. 200 OK response: The number of returned pdus MUST NOT exceed the limit provided by the caller. limit SHOULD have a maximum value imposed by the receiving server. pdus contains the events () preceeding the requested event ID (v), including v. pdus is ordered from oldest to newest. If the requesting server does not have reasonable visibility on the room (), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code () is returned. The same error is returned if the event ID doesn't exist in the requested room ID. If the requesting server does have visibility on the returned events, but not their contents, they are redacted () before being served. The returned events MUST be checked before being used by the requesting server (). This endpoint MUST NOT return LPDUs (), instead treating such events as though they didn't exist.

Room Membership When a server is already participating in a room, it can simply send m.room.member () events with the /send API () to other servers/the hub directly. When a server is not already participating however, it needs to be welcomed in by the hub server. A typical invite flow would be: | | | | | | | POST /invite (PDU) | | +----------------------->| | | | | | Decide to process the | | | invite. Can reject due | | | to spam, or send it to | | | the recipient user. | | | +----------------------+ | | | | | | +--------------------->| | | | | | Finish POST /invite | | |<-----------------------+ | | | | Finish POST /invite | | |<----------------------+ | | | | -------------------- User decides to accept invite --------------------- | | | | | GET /make_join | | |<-----------------------+ | | | | | Finish GET /make_join | | +----------------------->| | | | | | Fill event template | | | +-------------------+ | | | | | | +------------------>| | | | | | POST /send_join | | |<-----------------------+ | | | | | Finish POST /send_join | | +----------------------->| | | | ]]> POST /invite is shorthand for . Similarly, GET /make_join is and POST /send_join is . If the user decided to reject the invite, the TargetServer would use GET /make_leave () and POST /send_leave () instead of make/send_join.

Make and Send Handshake When a server is already participating in a room, it can use m.room.member () events and the /send API () to directly change membership. When the server is not already involved in the room, such as when being invited for the first time, the server needs to "make" an event and "send" it through the hub server to append it to the room. The different processes which use this handshake are:

Rejecting Invites ()
Joins ()
Knocks ()

The "make" portion of the endpoints take the shape of GET /_matrix/federation/v1/make_CHANGE/:roomId/:userId, where CHANGE is leave, join, or knock (respective to the list above). This endpoint will return a partial LPDU () which needs to be turned into a full LPDU and signed before being sent using POST /_matrix/federation/v3/send_CHANGE/:txnId. The flow for this handshake appears as such: | | | | Reject if event future event | | would not be allowed by auth rules | |<--------------------------------------------------------+ | | | Respond with partial LPDU | |<--------------------------------------------------------+ | | | Populate LPDU and sign it | +-------------------------+ | | | | |<------------------------+ | | | | POST /_matrix/federation/v3/send_CHANGE/:txnId | +-------------------------------------------------------->| | | | Validate event and append to the room | | +-------------------------------------+ | | | | +------------------------------------>| | | | Reject if event not allowed by auth rules | |<--------------------------------------------------------+ | | | Send new event to all other | | participants in the room (async) | | +-------------------------------------+ | | | | +------------------------------------>| | | | 200 OK | |<--------------------------------------------------------+ | | ]]> Note that the send_CHANGE step re-checks the event against the auth rules: any amount of time could have passed between the make_CHANGE and send_CHANGE calls. TODO: Describe how the external server is meant to find the hub. Invites work by (usually) trying to contact the server which sent the invite, but knocking is a guess.

Invites When inviting a user belonging to a server already in the room, senders SHOULD use m.room.member () events and the /send API (). This section's endpoints SHOULD only be used when the target server is not participating in the room already. Note that being invited does not count as the server "participating" in the room. This can mean that while a server has a user with a pending invite in the room, this section's endpoints are needed to send additional invites to other users on the same server. The full invite sequence is: | | | | | | Reject if sender | | | cannot invite other | | | users | | |<---------------------+ | | | | | | Otherwise, append | | | PDU fields | | +------------------+ | | | | | | |<-----------------+ | | | | | | POST /invite | | +----------------------->| | | | | | Reject if room | | | version not supported | | |<-----------------------+ | | | | | Reject if target user | | | is ineligible for | | | invites | | |<-----------------------+ | | | | Proxy TargetServer | | | rejection | | |<---------------------+ | | | | | | Otherwise, queue | | | sending the invite to | | | target user | | | +---------------------+ | | | | | | +-------------------->| | | | | | 200 OK | | |<-----------------------+ | | | | 200 OK | | |<---------------------+ | | | | ]]> POST /invite is shorthand for . What causes a user to be considered "ineligible" for an invite is left as an implementation detail. See and for suggestions on handling user-level privacy controls and spam invites.

POST /_matrix/federation/v3/invite/:txnId Sends an invite event to a server. If the sender is a participant server, the receiving server (the hub) will convert the contained LPDU () to a fully-formed event () before sending that event to the intended server. Implementation note: Currently this endpoint doesn't actually exist. Use POST /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/invite/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:txnId - the transaction ID () for the request. The event ID () of the contained event may be a good option as a readily-available transaction ID.

Query parameters: None applicable. Request body: invite_room_state are the stripped state events () for the room's current state. invite_room_state MAY be excluded from the request body. room_version is the room version identifier () the room is currently using. This will be retrieved from the m.room.create () state event. event is the event (LPDU or PDU; ) representing the invite for the user. It MUST meet the following criteria, in addition to the requirements of an event:

type MUST be m.room.member.
membership in content MUST be invite.

When the hub server receives a request from a participant server, it MUST populate the event fields before sending the event to the intended recipient. This means running the event through the normal event authorization steps (). If the invite is not allowed under the auth rules, the server responds with a 403 Forbidden HTTP status code and M_FORBIDDEN error code (). The intended recipient of the invite can be identified by the state_key on the event. If the invite event is valid, the hub server sends its own POST /_matrix/federation/v3/invite/:txnId request to the target server (if the target server is not itself) with the fully-formed event. The transaction ID does not need to be the same as the original inbound request. All responses from the target server SHOULD be proxied verbatim to the original requesting server through the hub. The hub SHOULD discard what appears to be excess data before sending a response to the requesting server, such as extra or large fields. If the target server does not respond with JSON, an error response () SHOULD be sent by the hub instead. The target server then ensures it can support the room version. If it can't, it responds with an HTTP status code of 400 Bad Request and error code of M_INCOMPATIBLE_ROOM_VERSION (). Then, the target server runs any implementation-specific checks as needed, such as those implied by and , rejecting/erroring the request as needed. Finally, the target server signs the event and returns it to the hub. The hub server appends this signed event to the room and sends it out to all participants in the room. The signed event is additionally returned to the originating participant server, though it also receives the event through the /send API (). 200 OK response: Note that by the time a response is received, the event is signed 2-3 times:

The LPDU signature from the participant server ().
The hub's signature on the PDU ().
The target server's signature on the PDU.

These signatures are to satisfy the auth rules (). TODO: Do we ever validate the target server's signature? Do we need to?

Rejecting Invites and Leaves Rejecting an invite is done by making a membership transition of invite to leave through the user's m.room.member () event. The membership event SHOULD be sent directly when it can and use the "make and send" handshake () described here otherwise. This same approach is additionally used to retract a knock ().

GET /_matrix/federation/v1/make_leave/:roomId/:userId Requests an event template from the hub server for a room. The requesting server will have already been checked to ensure it supports the room version as part of the invite process prior to making a call to this endpoint. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to get a template for.
:userId - the user ID () attempting to leave.

Query parameters: None applicable. Request body: None applicable. 200 OK response: The response body's event MUST be a partial LPDU () with at least the following fields:

type of m.room.member.
state_key of :userId from the path parameters.
sender of :userId from the path parameters.
content of {"membership": "leave"}.

The sending server SHOULD remove all other fields before using the event in a send_leave (). If the receiving server is not the hub server for the room ID, an HTTP status code of 400 Bad Request and error code M_WRONG_SERVER () is returned. If the room ID is not known, 404 Not Found is used as an HTTP status code and M_NOT_FOUND as an error code (). If the user does not have permission to leave under the auth rules (), a 403 Forbidden HTTP status code is returned alongside an error code of M_FORBIDDEN (). For example, if the user does not have a pending invite, is not a member of the room, or is banned. If the sending server does not recognize the returned room_version, it SHOULD NOT attempt to populate the template or use the send_leave () endpoint.

POST /_matrix/federation/v3/send_leave/:txnId Sends a leave membership event to the room through a hub server. Implementation note: Currently this endpoint doesn't actually exist. Use POST /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send_leave/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:txnId - the transaction ID () for the request. The event ID () of the contained event may be a good option as a readily-available transaction ID.

Query parameters: None applicable. Request body: 200 OK response: The errors responses from /make_leave () are copied here. Servers should note that room state MAY change between a /make_leave and /send_leave, potentially in a way which prevents the user from leaving the room suddenly. For example, the invited user may have been banned from the room.

Joins Joins for users SHOULD be sent directly whenever possible, and otherwise use the "make and send" handshake () approach described here.

GET /_matrix/federation/v1/make_join/:roomId/:userId Requests an event template from the hub server for a room. This is done to ensure the requesting server supports the room's version (), as well as hint at the event format needed to participate. Note that this endpoint is extremely similar to /make_leave (). Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to get a template for.
:userId - the user ID () attempting to join.

Query parameters:

ver (string; required; repeated) - The room versions () the sending server supports.

Request body: None applicable. 200 OK response: The response body MUST be a partial LPDU () with at least the following fields:

type of m.room.member.
state_key of :userId from the path parameters.
sender of :userId from the path parameters.
content of {"membership": "join"}.

The sending server SHOULD remove all other fields before using the event in a send_join (). If the receiving server is not the hub server for the room ID, an HTTP status code of 400 Bad Request and error code M_WRONG_SERVER () is returned. If the room ID is not known, 404 Not Found is used as an HTTP status code and M_NOT_FOUND as an error code (). If the user does not have permission to join under the auth rules (), a 403 Forbidden HTTP status code is returned alongside an error code of M_FORBIDDEN (). If the room version is not one of the ver strings the sender supplied, a 400 Bad Request HTTP status code is returned alongside M_INCOMPATIBLE_ROOM_VERSION error code ().

POST /_matrix/federation/v3/send_join/:txnId Sends a join membership event to the room through a hub server. Note that this endpoint is extremely similar to /send_leave (). Implementation note: Currently this endpoint doesn't actually exist. Use POST /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send_join/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:txnId - the transaction ID () for the request. The event ID () of the contained event may be a good option as a readily-available transaction ID.

Query parameters: None applicable. TODO: Incorporate faster joins work. Request body: 200 OK response: state is the current room state, consisting of the events which represent "current state" () prior to considering the membership state change. auth_chain consists of the events which make up the auth_events () for the state events, and the auth_events of those events, recursively. event will be the fully-formed PDU () that is sent by the hub to all other participants in the room. The errors responses from /make_join () are copied here (with the exception of M_INCOMPATIBLE_ROOM_VERSION, as the server already checked for support). Servers should note that room state MAY change between a /make_join and /send_join, potentially in a way which prevents the user from joining the room suddenly.

Knocks To knock on a room is to request an invite to that room. It is not a join, nor is it an invite itself. "Approving" the knock is done by inviting the user, which is typically only allowed by moderators in these rooms. "Denying" the knock is done through kicking (sending a leave membership) or banning the user. If the user is kicked, they may re-send their knock. Senders should note the reason field on m.room.member events () to provide context for their knock. To retract a knock, the sending server uses the same APIs as rejecting an invite (). Where possible, knocks from users SHOULD be sent directly, otherwise using the "make and send" handshake () approach described here.

GET /_matrix/federation/v1/make_knock/:roomId/:userId Requests an event template from the hub server for a room. This is done to ensure the requesting server supports the room's version (), as well as hint at the event format needed to participate. Note that this endpoint is almost exactly the same as /make_join (). TODO: It's so similar to make_join that we should probably just combine the two endpoints. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:roomId - the room ID () to get a template for.
:userId - the user ID () attempting to knock.

Query parameters:

ver (string; required; repeated) - The room versions () the sending server supports.

Request body: None applicable. 200 OK response: The response body MUST be a partial LPDU () with at least the following fields:

type of m.room.member.
state_key of :userId from the path parameters.
sender of :userId from the path parameters.
content of {"membership": "knock"}.

The sending server SHOULD remove all other fields before using the event in a send_knock (). If the receiving server is not the hub server for the room ID, an HTTP status code of 400 Bad Request and error code M_WRONG_SERVER () is returned. If the room ID is not known, 404 Not Found is used as an HTTP status code and M_NOT_FOUND as an error code (). If the user does not have permission to knock under the auth rules (), a 403 Forbidden HTTP status code is returned alongside an error code of M_FORBIDDEN (). If the room version is not one of the ver strings the sender supplied, a 400 Bad Request HTTP status code is returned alongside M_INCOMPATIBLE_ROOM_VERSION error code ().

POST /_matrix/federation/v3/send_knock/:txnId Sends a knock membership event to the room through a hub server. Implementation note: Currently this endpoint doesn't actually exist. Use POST /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send_knock/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:txnId - the transaction ID () for the request. The event ID () of the contained event may be a good option as a readily-available transaction ID.

Query parameters: None applicable. Request body: 200 OK response: stripped_state are the stripped state events () for the room. The errors responses from /make_knock () are copied here (with the exception of M_INCOMPATIBLE_ROOM_VERSION, as the server already checked for support). Servers should note that room state MAY change between a /make_knock and /send_knock, potentially in a way which prevents the user from knocking upon the room suddenly.

Content Repository The content repository, sometimes called the "media repo", is where user-generated content is stored for referencing within an encrypted message. TODO: Complete this section. We want auth/event linking from MSC3911 and MSC3916. TODO: Spell out that content is images, videos, files, etc.

Ephemeral Data Units (EDUs) EDUs are sent out of band from rooms and are only persisted for exactly as long as they are needed. For example, once a to-device () message is delivered to a client, the server may easily be able to delete its copy of the message. EDUs contain the following mandatory fields: The type is similar to an event type () and ultimately describes the schema for the content. sender_id is the user ID () which is sending the EDU. Typically, clients will not generate EDUs directly. Instead, the server will convert a client's request into an EDU for sending to a remote server, where that server then unpacks the EDU before delivering it to local devices. Because EDUs are not sent in the context of a room, even if an MLS Welcome message is being sent for a room, servers MUST send the EDUs directly to the target server with the send API (). In this document, EDUs are only used for to-device messages () and device list changes (), but could be used for read/delivery receipts, typing notifications, and more in future. This may necessitate routing EDUs through the hub rather than using full-mesh fanout. TODO: Address EDU fanout; Document the implied missing features (receipts, typing notifs).

MLS TODO: This section. Talk about to-device messaging, device management/querying/key claiming, etc. There are several endpoints required by this document's MLS implementation (), largely around device management for each device's signing key, claiming key packages for those devices, and sending messages (Welcome in particular) after using a key package.

Device Info Publishing When a user creates a new encryption-capable device, or removes one, a "device list update" is sent to all servers the user shares a room with. The receiving servers then determine which local clients need to be made aware of the device list change and sends the information to them. This is primarily used by this document's MLS implementation () to indicate to other devices that either a new possible device has come online or that another needs to be removed from some MLS groups due to being deleted. Typically, a device is created by a user when they log in to a new session. Similarly, a device is deleted/removed when they log out of that client. The device list update takes the shape of an EDU (), as such: The device objects are the same as in the response for /user/:userId/device/:deviceId (), indicating that either a new device was created or that information about a previous device has changed. TODO: Matrix's m.device_list_update EDU is very different from this, and relatively complicated. Do we actually need a stream_id, like in Matrix? Do we then need the /devices endpoint?

GET /_matrix/federation/v1/user/:userId/device/:deviceId Retrieves information about a specific device for a user. This request does not go via a hub, instead going directly to the server which owns the :userId. Implementation note: Currently this endpoint doesn't actually exist. Use PUT /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/user/:userId/device/:deviceId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes. TODO: Remove implementation notes. Rate-limited: Yes. Authentication required: Yes. Path parameters:

:userId - the user ID () who owns the device.
:deviceId - the device ID () to get information about.

Query parameters: None applicable. Request body: None applicable. 200 OK response: " }, "signatures": { "@alice:example.org": { "m.mls.v1.credential.ed25519:ABCDEF": "" } } } ]]> Note that the response is the same object the device itself signed/created in . If the user ID does not belong the receiving server, a 404 Not Found HTTP status code is returned with error code M_NOT_FOUND (). The same applies if the user ID does not exist, or the user does not have the device ID requested.

To-Device Messaging To-device messaging is an ability to send information directly to another device, typically to carry MLS Welcome messages and similar. They are sent as EDUs (), one per receipient device and payload: target and target_device denote the destination user ID () and device ID () for that user. This EDU MUST be sent to the server denoted by the target user ID. If the target user doesn't exist or doesn't have a device with the ID described, the receiving server drops/ignores the EDU. See for an example of a to-device message being used.

One Time Key Claiming To enable two devices to communicate, they need to claim a key package () for the other device. These key packages are also called "one time keys". This is done through the following endpoint.

POST /_matrix/federation/v1/user/keys/claim Claims one time keys for devices. This request does not go via a hub, instead going directly to the server which owns the given user IDs. Rate-limited: Yes. Authentication required: Yes. Path parameters: None applicable. Query parameters: None applicable. Request body: one_time_keys MUST be specified and is a map of user ID () to device ID () to algorithm for the key package to claim. Currently the only expected algorithm is defined by . Any user IDs which don't belong to the receiving server, or which don't exist, are ignored. The same applies for device IDs for which the user doesn't have. 200 OK response: " } } } } ]]> Like the request body, one_time_keys MUST be specified (but MAY be empty) and is a map of requested user ID to requested device ID to algorithm name. The value for the algorithm name is dependent on the algorithm itself. For m.mls.v1.key_package.dhkemx25519-aes128gcm-sha256-ed25519, this is an unpadded base64 () string representing the key package itself. Servers MUST NOT reuse a device's one time key, unless that key permits it. For example, MLS's "last resort" key MAY be used multiple times, but SHOULD only be used if no other one time keys remain for the device. Servers MUST NOT use an expired key. Typically, the server will inform the device that a key was used so the device can upload additional keys. See for further implementation-related concerns.

TODO: Remainder of Transport TODO: This section. Topics:

More EDUs (typing notifications, receipts, presence)
Query APIs (alias resolution, profiles)
Other Encryption APIs??
Server ACLs? (this probably should become part of the auth rules)

Notably/deliberately missing APIs are:

get_missing_events - this is used by DAG servers only
Public room directory
Timestamp-to-event API
All of 3rd party invites
All of Spaces
OpenID API

Open Questions

Should we include /_matrix/federation/v1/version in here? It's used by federation testers, but not really anything else.

User Privacy TODO: Fully complete this section. Messaging providers may have user-level settings to prevent unexpected or unwarranted invites, such as automatically blocking invites from non-contacts. This setting can be upheld by returning an error on POST /_matrix/federation/v3/invite/:txnId (), and by having the server (optionally) auto-decline any invites received directly through PUT /_matrix/federation/v2/send/:txnId (). See for more information on rejecting invites.

Spam Prevention TODO: Fully complete this section. TODO: Talk about how to deal with spammy/unwanted invites. Servers MAY temporarily or permanently block a room entirely by using the room ID. Typically, when a room becomes blocked, all local users will be removed from the room using m.room.member events with membership of leave (). Then, any time the server receives a request for that room ID it can reject it with an error response (). Blocking a room does not block it from all servers, but does prevent users on a server from accessing the content within. This is primarily useful to remove a server from rooms where abusive/illegal content is shared.

Security Considerations TODO: Expand upon this section. With the combined use of MLS and server-side enforcement, the server theoretically has an ability to add a malicious device to the MLS group and receive decryptable messages. Authenticity of devices needs to be established to ensure a user's devices are actually a user's devices. TODO: Should we bring Matrix's cross-signing here? Servers retain the ability to control/puppet their own users due to no strong cryptographic link between the sending device and the event which gets emitted.

IANA Considerations The m.* namespace likely needs formal registration in some capacity. The I.* namespace likely needs formal registration in some capacity. Port 8448 may need formal registration. The SRV service name matrix may need re-registering, or a new service name assigned. The .well-known/matrix namespace is already registered for use by The Matrix.org Foundation C.I.C.

References Normative References Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS) Many application technologies enable secure communication between two entities by means of Internet Public Key Infrastructure Using X.509 (PKIX) certificates in the context of Transport Layer Security (TLS). This document specifies procedures for representing and verifying the identity of application services in such interactions. [STANDARDS-TRACK] The Base16, Base32, and Base64 Data Encodings This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] Requirements for Internet Hosts - Application and Support This RFC is an official specification for the Internet community. It incorporates by reference, amends, corrects, and supplements the primary protocol standards documents relating to hosts. [STANDARDS-TRACK] The Messaging Layer Security (MLS) Protocol Cisco Inria & Mozilla Phoenix R&D Meta Platforms Google University of Oxford Messaging applications are increasingly making use of end-to-end security mechanisms to ensure that messages are only accessible to the communicating endpoints, and not to any servers involved in delivering messages. Establishing keys to provide such protections is challenging for group chat settings, in which more than two clients need to agree on a key but may not be online at the same time. In this document, we specify a key establishment protocol that provides efficient asynchronous group key establishment with forward secrecy and post-compromise security for groups in size ranging from two to thousands. The Messaging Layer Security (MLS) Architecture Inria & Mozilla Mozilla Google Twitter Wire The Messaging Layer Security (MLS) protocol (I-D.ietf-mls-protocol) specification has the role of defining a Group Key Agreement protocol, including all the cryptographic operations and serialization/deserialization functions necessary for scalable and secure group messaging. The MLS protocol is meant to protect against eavesdropping, tampering, message forgery, and provide further properties such as Forward Secrecy (FS) and Post-Compromise Security (PCS) in the case of past or future device compromises. This document describes a general secure group messaging infrastructure and its security goals. It provides guidance on building a group messaging system and discusses security and privacy tradeoffs offered by multiple security mechanisms that are part of the MLS protocol (e.g., frequency of public encryption key rotation). The document also provides guidance for parts of the infrastructure that are not standardized by the MLS Protocol document and left to the application or the infrastructure architects to design. While the recommendations of this document are not mandatory to follow in order to interoperate at the protocol level, they affect the overall security guarantees that are achieved by a messaging application. This is especially true in case of active adversaries that are able to compromise clients, the delivery service, or the authentication service. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. MIMI Terminology The Matrix.org Foundation C.I.C. This document introduces a set of terminology to use when discussing or describing concepts within MIMI. Augmented BNF for Syntax Specifications: ABNF Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] UTF-8, a transformation format of ISO 10646 ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279. The JavaScript Object Notation (JSON) Data Interchange Format JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. Edwards-Curve Digital Signature Algorithm (EdDSA) This document describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided. JSON Canonicalization Scheme (JCS) Cryptographic operations like hashing and signing need the data to be expressed in an invariant format so that the operations are reliably repeatable. One way to address this is to create a canonical representation of the data. Canonicalization also permits data to be exchanged in its original form on the "wire" while cryptographic operations performed on the canonicalized counterpart of the data in the producer and consumer endpoints generate consistent results. This document describes the JSON Canonicalization Scheme (JCS). This specification defines how to create a canonical representation of JSON data by building on the strict serialization methods for JSON primitives defined by ECMAScript, constraining JSON data to the Internet JSON (I-JSON) subset, and by using deterministic property sorting. US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF) Federal Information Processing Standard, FIPS HTTP Semantics The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. HTTP/2 This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. The Transport Layer Security (TLS) Protocol Version 1.3 This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. A DNS RR for specifying the location of services (DNS SRV) This document describes a DNS RR which specifies the location of the server(s) for a specific protocol and domain. [STANDARDS-TRACK] Domain names - concepts and facilities This RFC is the revised basic definition of The Domain Name System. It obsoletes RFC-882. This memo describes the domain style names and their used for host address look up and electronic mail forwarding. It discusses the clients and servers in the domain name system and the protocol used between them. Clarifications to the DNS Specification This document considers some areas that have been identified as problems with the specification of the Domain Name System, and proposes remedies for the defects identified. [STANDARDS-TRACK] DNS Extensions to Support IP Version 6 This document defines the changes that need to be made to the Domain Name System (DNS) to support hosts running IP version 6 (IPv6). The changes include a resource record type to store an IPv6 address, a domain to support lookups based on an IPv6 address, and updated definitions of existing query types that return Internet addresses as part of additional section processing. The extensions are designed to be compatible with existing applications and, in particular, DNS implementations themselves. [STANDARDS-TRACK] Domain names - implementation and specification This RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication. Informative References Extensible Messaging and Presence Protocol (XMPP): Core The Extensible Messaging and Presence Protocol (XMPP) is an application profile of the Extensible Markup Language (XML) that enables the near-real-time exchange of structured yet extensible data between any two or more network entities. This document defines XMPP's core protocol methods: setup and teardown of XML streams, channel encryption, authentication, error handling, and communication primitives for messaging, network availability ("presence"), and request-response interactions. This document obsoletes RFC 3920. [STANDARDS-TRACK] MSC3995: [WIP] Linearized Matrix The Matrix.org Foundation C.I.C. Decentralised MLS The Matrix.org Foundation C.I.C. Perspectives Project MIMI Delivery Service Phoenix R&D Phoenix R&D This document describes the MIMI Delivery Service. Group Chat Framework for More Instant Messaging Interoperability (MIMI) Wire This document describes a group instant messaging ("group chat") semantic framework for the More Instant Messaging Interoperability (MIMI) Working Group. It describes several properties and policy options which can be combined to model a wide range of chat and multimedia conference types. It also describes how to build these options as an overlay to Messaging Layer Security (MLS) groups and to authorize MLS primitives. MIMI Portability Phoenix R&D Phoenix R&D This document describes MIMI Portability mechanisms. More Instant Messaging Interop (MIMI) Transport Protocol Five9 Cisco Cisco 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. DNS Security Extensions (DNSSEC) This document describes the DNS Security Extensions (commonly called "DNSSEC") that are specified in RFCs 4033, 4034, and 4035, as well as a handful of others. One purpose is to introduce all of the RFCs in one place so that the reader can understand the many aspects of DNSSEC. This document does not update any of those RFCs. A second purpose is to state that using DNSSEC for origin authentication of DNS data is the best current practice. A third purpose is to provide a single reference for other documents that want to refer to DNSSEC. Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK]

Acknowledgments Thanks to the Matrix Spec Core Team (SCT) for exploring methods of linearizing Matrix's DAG room model, especially Richard van der Hoff and Erik Johnston. Additional thanks to the Matrix core team as a whole for general review and input on this document, especially Patrick Cloke and Jim Mackenzie. Matrix's crypto team graciously allowed their work-in-progress MLS considerations to be incorporated in this document. Thanks to Hubert Chathi for reviewing the MLS work for plausibility. Thanks are also extended to the wider MIMI working group for continous review and input on this document.