matrix-spec-proposals/specification/rooms/v3.rst

.. Copyright 2018-2019 New Vector Ltd
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
..     http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

Room Version 3
==============

This room version builds on `version 2 <v2.html>`_ with an improved event format.

.. note:
   All requirements listed in this room version specification are scoped to rooms
   which actually use this room version. For example, a requirement of "all APIs must
   accept the new event format" does in fact apply to all APIs, but only so much as
   where the contextual room of the request is using this room version. Rooms using
   other room versions should not be affected by these sweeping requirements.


Client considerations
---------------------

This room version changes the format for event IDs sent to clients. Clients should be
aware that these event IDs may contain slashes and other potentially problematic
characters. Clients should be treating event IDs as opaque identifiers and should not
be attempting to parse them into a usable form, just like with other room versions.

Clients should expect to see event IDs changed from the format of ``$randomstring:example.org``
to something like ``$acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk`` (note the lack of
domain and the potentially problematic slash).


Server implementation components
--------------------------------

.. WARNING::
   The information contained in this section is strictly for server implementors.
   Applications which use the Client-Server API are generally unaffected by the
   intricacies contained here. The section above regarding client considerations
   is the resource that Client-Server API use cases should reference.


Room version 3 uses the state resolution algorithm defined in `room version 2 <v2.html>`_,
and the event format defined here.

Event IDs
~~~~~~~~~

.. admonition:: Rationale

   In other room versions (namely version 1 and 2) the event ID is a distinct field
   from the remainder of the event, which must be tracked as such. This leads to
   complications where servers receive multiple events with the same ID in either the
   same or different rooms where the server cannot easily keep track of which event it
   should be using. By removing the use of a dedicated event ID, servers are required
   to track the hashes on an event to determine its ID.

The event ID is calculated using the following algorithm. Note that the hashing
algorithm used is the same as in previous room versions.

1. Redact the event.
2. Remove the `signatures` field from the event.
3. Serialize the event into `Canonical JSON`_.
4. Compute the hash of the JSON bytes.
5. Encode the sha256 hash using `Unpadded Base64`_.
6. Use the resulting string as the event ID prefixed with ``$``.

A resulting event ID using this approach should look similar to
``$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o``.

Event IDs should not be sent over federation to servers when the room uses
this room version. On the receiving end of an event, the server should compute
the relevant event ID for itself.

Additionally, the ``auth_events`` and ``prev_events`` have had a format change
compared to other room versions to make it easier to handle. Instead of a tuple
of values, they are now plain lists of events.

{{definition_ss_pdu_v3}}

Changes to APIs
~~~~~~~~~~~~~~~

Due to the event ID being removed from the event, some APIs need to change. All
APIs which currently accept an event ID must do so with the new format. Servers
must append the calculated event ID to all events sent to clients where an event
ID would normally be expected.

Because the format of events has changed, servers must be aware of the room version
where the event resides so that the server may parse and handle the event. The
federation API has taken this concern into consideration by ensuring that servers
are aware of (or can find) the room version during a request.

Authorization rules for events
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The authorization rules for a given event have changed in this room version due
to the change in event format:

* The event no longer needs to be signed by the domain of the event ID (as there
  is no domain in the event ID), but still needs to be signed by the sender's
  domain.

* Previously, redactions were allowed if the sender's domain matched the domain
  in the event ID it was redacting, allowing self redaction. Due to changes in
  the event format, this check is now impossible to do. Instead, servers should
  allow redactions from servers of the same origin to redact other events as a
  self-redaction mechanism. The rules for allowing other servers to redact events
  (as done by moderators) is unchanged. Redaction events only take effect when
  the original event is received, and the domain of the each event matches.
  Servers should not send redactions down to clients until the redaction has
  taken effect.

The remaining rules are the same as room version 1.


.. _`Unpadded Base64`:  ../../appendices.html#unpadded-base64
.. _`Canonical JSON`: ../../appendices.html#canonical-json
.. _`Signing Events`: ../../server_server/unstable.html#signing-events