102 lines
4.4 KiB
ReStructuredText
102 lines
4.4 KiB
ReStructuredText
.. Copyright 2016 OpenMarket 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 History Visibility
|
|
=======================
|
|
|
|
.. _module:history-visibility:
|
|
|
|
This module adds support for controlling the visibility of previous events in a
|
|
room.
|
|
|
|
In all cases except ``world_readable``, a user needs to join a room to view events in that room. Once they
|
|
have joined a room, they will gain access to a subset of events in the room. How
|
|
this subset is chosen is controlled by the ``m.room.history_visibility`` event
|
|
outlined below. After a user has left a room, they may see any events which they
|
|
were allowed to see before they left the room, but no events received after they
|
|
left.
|
|
|
|
The four options for the ``m.room.history_visibility`` event are:
|
|
|
|
- ``world_readable`` - All events while this is the
|
|
``m.room.history_visibility`` value may be shared by any participating
|
|
homeserver with anyone, regardless of whether they have ever joined the room.
|
|
- ``shared`` - Previous events are always accessible to newly joined members. All
|
|
events in the room are accessible, even those sent when the member was not a part
|
|
of the room.
|
|
- ``invited`` - Events are accessible to newly joined members from the point
|
|
they were invited onwards. Events stop being accessible when the member's state
|
|
changes to something other than ``invite`` or ``join``.
|
|
- ``joined`` - Events are accessible to newly joined members from the point
|
|
they joined the room onwards. Events stop being accessible when the member's state
|
|
changes to something other than ``join``.
|
|
|
|
.. WARNING::
|
|
These options are applied at the point an event is *sent*. Checks are
|
|
performed with the state of the ``m.room.history_visibility`` event when the
|
|
event in question is added to the DAG. This means clients cannot
|
|
retrospectively choose to show or hide history to new users if the setting at
|
|
that time was more restrictive.
|
|
|
|
Events
|
|
------
|
|
|
|
{{m_room_history_visibility_event}}
|
|
|
|
Client behaviour
|
|
----------------
|
|
|
|
Clients that implement this module MUST present to the user the possible options
|
|
for setting history visibility when creating a room.
|
|
|
|
Clients may want to display a notice that their events may be read by non-joined
|
|
people if the value is set to ``world_readable``.
|
|
|
|
Server behaviour
|
|
----------------
|
|
|
|
By default if no ``history_visibility`` is set, or if the value is not understood, the visibility is assumed to be
|
|
``shared``. The rules governing whether a user is allowed to see an event depend
|
|
on the state of the room *at that event*.
|
|
|
|
1. If the ``history_visibility`` was set to ``world_readable``, allow.
|
|
2. If the user's ``membership`` was ``join``, allow.
|
|
3. If ``history_visibility`` was set to ``shared``, and the user joined the
|
|
room at any point after the event was sent, allow.
|
|
4. If the user's ``membership`` was ``invite``, and the ``history_visibility``
|
|
was set to ``invited``, allow.
|
|
5. Otherwise, deny.
|
|
|
|
For ``m.room.history_visibility`` events themselves, the user should be allowed
|
|
to see the event if the ``history_visibility`` before *or* after the event
|
|
would allow them to see it. (For example, a user should be able to see
|
|
``m.room.history_visibility`` events which change the ``history_visibility``
|
|
from ``world_readable`` to ``joined`` *or* from ``joined`` to
|
|
``world_readable``, even if that user was not a member of the room.)
|
|
|
|
Likewise, for the user's own ``m.room.member`` events, the user should be
|
|
allowed to see the event if their ``membership`` before *or* after the event
|
|
would allow them to see it. (For example, a user can always see
|
|
``m.room.member`` events which set their membership to ``join``, or which
|
|
change their membership from ``join`` to any other value, even if
|
|
``history_visibility`` is ``joined``.)
|
|
|
|
Security considerations
|
|
-----------------------
|
|
|
|
The default value for ``history_visibility`` is ``shared`` for
|
|
backwards-compatibility reasons. Clients need to be aware that by not setting
|
|
this event they are exposing all of their room history to anyone in the room.
|
|
|