Merge pull request #91 from matrix-org/module-history-vis

History visibility module

specification/0-events.rst

@@ -26,8 +26,6 @@ prefixed with ``m.``
 
 {{m_room_create_event}}
 
-{{m_room_history_visibility_event}}
-
 {{m_room_join_rules_event}}
 
 {{m_room_member_event}}

specification/modules/history_visibility.rst

@@ -1,21 +1,54 @@
 Room History Visibility
------------------------
+=======================
 
 .. _module:history-visibility:
 
-Whether a member of a room can see the events that happened in a room from
-before they joined the room is controlled by the ``history_visibility`` key
-of the ``m.room.history_visibility`` state event. The valid values for
-``history_visibility`` are:
+This module adds support for controlling the visibility of previous events in a
+room.
+
+In all cases, 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 seen any events which they
+were allowed to see before they left the room, but no events received after they
+left.
+
+The three options for the ``m.room.history_visibility`` event are:
+
+- ``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`` - Previous 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`` - Previous 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
+------
 
-- ``shared``
-- ``invited``
-- ``joined``
+{{m_room_history_visibility_event}}
 
-By default if no ``history_visibility`` is set it is assumed to be ``shared``.
+Client behaviour
+----------------
 
-The rules governing whether a user is allowed to see an event depend solely on
-the state of the room at that event:
+Clients that implement this module MUST present to the user the possible options
+for setting history visibility when creating a room. 
+
+Server behaviour
+----------------
+
+By default if no ``history_visibility`` is set the visibility is assumed to be
+``shared``. The rules governing whether a user is allowed to see an event depend
+solely on the state of the room *at that event*:
 
 1. If the user was joined, allow.
 2. If the user was invited and the ``history_visibility`` was set to
@@ -24,3 +57,10 @@ the state of the room at that event:
    was set to ``shared``, allow.
 4. Otherwise, deny.
 
+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.
+