From e378de8379abcb85db8048b7dbd80b3851b4ac51 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 9 Oct 2015 11:04:11 +0100 Subject: [PATCH 1/4] Shuffle history visibility module to be in the module format --- specification/0-events.rst | 2 - specification/modules/history_visibility.rst | 44 +++++++++++++++----- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/specification/0-events.rst b/specification/0-events.rst index 16948462..e2373f96 100644 --- a/specification/0-events.rst +++ b/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}} diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 371282bd..4f0c8976 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -1,21 +1,36 @@ 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. 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 ``m.room.history_visibility`` +event outlined below. Visibility can take the form of one of three options: -- ``shared`` -- ``invited`` -- ``joined`` +- ``shared`` - Previous events are always shown to newly joined members. +- ``invited`` - Previous events are shown to newly joined members from the point + they were invited onwards. +- ``joined`` - Previous events are shown to newly joined members from the point + they joined the room onwards. -By default if no ``history_visibility`` is set it is assumed to be ``shared``. +Events +------ -The rules governing whether a user is allowed to see an event depend solely on -the state of the room at that event: +{{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. + +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 +39,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. + From 173d00cea04e3c607992396b7395741971578e35 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 13 Oct 2015 11:08:19 +0100 Subject: [PATCH 2/4] Review comments --- specification/modules/history_visibility.rst | 22 ++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 4f0c8976..12ea7b22 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -6,13 +6,27 @@ Room History Visibility This module adds support for controlling the visibility of previous events in a room. 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 ``m.room.history_visibility`` -event outlined below. Visibility can take the form of one of three options: +event outlined below. In all cases, the member still needs to be joined to the +room to receive events for that room. The visibility option simply determines +which subset of events in the room are presented to the client. Visibility can +take the form of one of three options: -- ``shared`` - Previous events are always shown to newly joined members. +- ``shared`` - Previous events are always shown to newly joined members. All + events in the room are shown, even those sent when the member was not a part + of the room. - ``invited`` - Previous events are shown to newly joined members from the point - they were invited onwards. + they were invited onwards. Events stop being shown when the member's state + changes to something other than ``invite`` or ``join``. - ``joined`` - Previous events are shown to newly joined members from the point - they joined the room onwards. + they joined the room onwards. Events stop being shown when the members 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 ------ From 507cb29e39c0dec1f0ad51095f350d4e5f37e4e7 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 15 Oct 2015 10:37:15 +0100 Subject: [PATCH 3/4] Review comments round deux --- specification/modules/history_visibility.rst | 28 +++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 12ea7b22..0405b3f1 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -4,21 +4,25 @@ Room History Visibility .. _module:history-visibility: This module adds support for controlling the visibility of previous events in a -room. 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 ``m.room.history_visibility`` -event outlined below. In all cases, the member still needs to be joined to the -room to receive events for that room. The visibility option simply determines -which subset of events in the room are presented to the client. Visibility can -take the form of one of three options: +room. -- ``shared`` - Previous events are always shown to newly joined members. All - events in the room are shown, even those sent when the member was not a part +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 this 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 shown to newly joined members from the point - they were invited onwards. Events stop being shown when the member's state +- ``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 shown to newly joined members from the point - they joined the room onwards. Events stop being shown when the members state +- ``joined`` - Previous events are accessible to newly joined members from the point + they joined the room onwards. Events stop being accessible when the members state changes to something other than ``join``. .. WARNING:: From 5aad67f74d7fe611981aa75c3b42d7c17726b4de Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 15 Oct 2015 11:01:11 +0100 Subject: [PATCH 4/4] Review comments round III --- specification/modules/history_visibility.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 0405b3f1..f26d1b59 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -13,7 +13,7 @@ outlined below. After a user has left a room, they may seen any events which the were allowed to see before they left the room, but no events received after they left. -The three options for this event are: +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 @@ -22,7 +22,7 @@ The three options for this event are: 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 members state + they joined the room onwards. Events stop being accessible when the member's state changes to something other than ``join``. .. WARNING::