From 3d913b36f8acf03b598e7056f4bbb3007f85c411 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 12:47:44 -0400 Subject: [PATCH 01/19] Add current proposals. --- proposals/xxxx-stripped-state-events.md | 93 +++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 proposals/xxxx-stripped-state-events.md diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/xxxx-stripped-state-events.md new file mode 100644 index 00000000000..002492ba6b6 --- /dev/null +++ b/proposals/xxxx-stripped-state-events.md @@ -0,0 +1,93 @@ +# MSCXXXX: Exposing stripped state events to any potential joiner + +It is currently possible to inspect the state of rooms in some circumstances: + +* If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). +* Rooms in the room directory expose some of their state publicly. +* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. + +This MSC proposes exposing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It also consolidates the recommendation on which states events are available to potential joiners. + +## Background + +When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) to include stripped state events which are useful for displaying the invite to a user: + +> An optional list of simplified events to help the receiver of the invite identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. + +The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) as part of the `/sync` response: + +> The state of a room that the user has been invited to. These state events may only have the `sender`, `type`, `state_key` and `content` keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. + +These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) containing the invite. + +[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) extends this concept to also include the stripped state events in the `/sync` response for knocking users: + +> It is proposed to add a fourth possible key to rooms, called `knock`. Its value is a mapping from room ID to room information. The room information is a mapping from a key `knock_state` to another mapping with key events being a list of `StrippedStateEvent`. + +It is also provides an extended rationale of why this is useful: + +> These stripped state events contain information about the room, most notably the room's name and avatar. A client will need this information to show a nice representation of pending knocked rooms. The recommended events to include are the join rules, canonical alias, avatar, name and encryption state of the room, rather than all room state. This behaviour matches the information sent to remote homeservers when remote users are invited to a room. + +[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: + +> Join rules, invites and 3PID invites work as for a normal room, with the exception that `invite_state` sent along with invites should be amended to include the `m.room.create` event, to allow clients to discern whether an invite is to a space-room or not. + +## Proposal + +Any user who is able to join a room can access the stripped state events of that room. + +Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: + +* A room that has `join_rules` set to `public` or `knock`.[1](#f1) +* A room that the user is in possession of an invite to (regardless of the `join_rules`). + +Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: + +* [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). + +Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: + +* Create event (`m.room.create`)[2](#f2) +* Join rules (`m.room.join_rules`) +* Canonical alias (`m.room.canonical_alias`) +* Room avatar (`m.room.avatar`) +* Room name (`m.room.name`) +* Encrypted status (`m.room.encryption`)[3](#f3) + +This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. + +## Potential issues + +This is a generalization of current behavior and shouldn't introduce any new issues. + +## Alternatives + +A different approach to this would be to separately specify each situation in which a user is allowed to see stripped state events, as we do currently for invites and knocking. + +## Security considerations + +The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) does not know the user who is requesting a summary of the space, but should divulge the above information if any member of a server could see it. It is up to the calling server to properly filter this information. + +Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice or Bob (and hence whether it should share details of private rooms within that space). + +Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. + +(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) + +This does not decrease security since a server could lie and make a request on behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. + +## Future extensions + +Dedicated client-server and server-server APIs could be added to request the stripped state events, but that is considered out-of-scope for the current proposal. + +## Unstable prefix + +N/A + +## Footnotes + +[1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) + +[2]: As suggested in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) + +[3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) From ce8650837be3a5499383468f749b58139297f218 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:35:29 -0400 Subject: [PATCH 02/19] Wording. --- proposals/xxxx-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/xxxx-stripped-state-events.md index 002492ba6b6..c2408f08054 100644 --- a/proposals/xxxx-stripped-state-events.md +++ b/proposals/xxxx-stripped-state-events.md @@ -88,6 +88,6 @@ N/A [1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) -[2]: As suggested in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) +[2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) [3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) From b6cba644591edbb7aa5b7496fdb7379a1d553b55 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:37:04 -0400 Subject: [PATCH 03/19] Update MSC number. --- ...ped-state-events.md => 3173-expose-stripped-state-events.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-stripped-state-events.md => 3173-expose-stripped-state-events.md} (99%) diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md similarity index 99% rename from proposals/xxxx-stripped-state-events.md rename to proposals/3173-expose-stripped-state-events.md index c2408f08054..f2b04096e98 100644 --- a/proposals/xxxx-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,4 +1,4 @@ -# MSCXXXX: Exposing stripped state events to any potential joiner +# MSC3173: Expose stripped state events to any potential joiner It is currently possible to inspect the state of rooms in some circumstances: From 1cfbf7620af6bc2a155f2326d74f1ce3c096a9c0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:49:17 -0400 Subject: [PATCH 04/19] Wrapping. --- .../3173-expose-stripped-state-events.md | 98 ++++++++++++++----- 1 file changed, 74 insertions(+), 24 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index f2b04096e98..8439519b8ef 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -6,46 +6,74 @@ It is currently possible to inspect the state of rooms in some circumstances: * Rooms in the room directory expose some of their state publicly. * [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. -This MSC proposes exposing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It also consolidates the recommendation on which states events are available to potential joiners. +This MSC proposes exposing the stripped state events that are currently available +to invited and knocking users to any user who could potentially join a room. It +also consolidates the recommendation on which states events are available to +potential joiners. ## Background -When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) to include stripped state events which are useful for displaying the invite to a user: +When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) +to include stripped state events which are useful for displaying the invite to a user: -> An optional list of simplified events to help the receiver of the invite identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. +> An optional list of simplified events to help the receiver of the invite identify +> the room. The recommended events to include are the join rules, canonical alias, +> avatar, and name of the room. -The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) as part of the `/sync` response: +The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) +as part of the `/sync` response: -> The state of a room that the user has been invited to. These state events may only have the `sender`, `type`, `state_key` and `content` keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. +> The state of a room that the user has been invited to. These state events may +> only have the `sender`, `type`, `state_key` and `content` keys present. These +> events do not replace any state that the client already has for the room, for +> example if the client has archived the room. -These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) containing the invite. +These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) +containing the invite. -[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) extends this concept to also include the stripped state events in the `/sync` response for knocking users: +[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) +extends this concept to also include the stripped state events in the `/sync` response +for knocking users: -> It is proposed to add a fourth possible key to rooms, called `knock`. Its value is a mapping from room ID to room information. The room information is a mapping from a key `knock_state` to another mapping with key events being a list of `StrippedStateEvent`. +> It is proposed to add a fourth possible key to rooms, called `knock`. Its value +> is a mapping from room ID to room information. The room information is a mapping +> from a key `knock_state` to another mapping with key events being a list of +> `StrippedStateEvent`. It is also provides an extended rationale of why this is useful: -> These stripped state events contain information about the room, most notably the room's name and avatar. A client will need this information to show a nice representation of pending knocked rooms. The recommended events to include are the join rules, canonical alias, avatar, name and encryption state of the room, rather than all room state. This behaviour matches the information sent to remote homeservers when remote users are invited to a room. +> These stripped state events contain information about the room, most notably the +> room's name and avatar. A client will need this information to show a nice +> representation of pending knocked rooms. The recommended events to include are the +> join rules, canonical alias, avatar, name and encryption state of the room, rather +> than all room state. This behaviour matches the information sent to remote +> homeservers when remote users are invited to a room. -[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: +[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally +recommends including the `m.room.create` event as one of the stripped state events: -> Join rules, invites and 3PID invites work as for a normal room, with the exception that `invite_state` sent along with invites should be amended to include the `m.room.create` event, to allow clients to discern whether an invite is to a space-room or not. +> Join rules, invites and 3PID invites work as for a normal room, with the exception +> that `invite_state` sent along with invites should be amended to include the +> `m.room.create` event, to allow clients to discern whether an invite is to a +> space-room or not. ## Proposal Any user who is able to join a room can access the stripped state events of that room. -Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: +Potential ways that a user might be able to join include, but are not limited to, +the following mechanisms: * A room that has `join_rules` set to `public` or `knock`.[1](#f1) * A room that the user is in possession of an invite to (regardless of the `join_rules`). -Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: +Future MSCs might include additional mechanism for a user to join a room and +should consider this MSC, for example: * [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). -Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: +Additionally, it is recommended, but not required, that homeserver implementations +include the following as stripped state events: * Create event (`m.room.create`)[2](#f2) * Join rules (`m.room.join_rules`) @@ -54,7 +82,10 @@ Additionally, it is recommended, but not required, that homeserver implementatio * Room name (`m.room.name`) * Encrypted status (`m.room.encryption`)[3](#f3) -This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. +This also implies that the above information is available to any potential joiner +in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). +I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) +can expose the information available in stripped state events. ## Potential issues @@ -62,23 +93,40 @@ This is a generalization of current behavior and shouldn't introduce any new iss ## Alternatives -A different approach to this would be to separately specify each situation in which a user is allowed to see stripped state events, as we do currently for invites and knocking. +A different approach to this would be to separately specify each situation in which +a user is allowed to see stripped state events, as we do currently for invites and +knocking. ## Security considerations -The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) does not know the user who is requesting a summary of the space, but should divulge the above information if any member of a server could see it. It is up to the calling server to properly filter this information. +The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +does not know the user who is requesting a summary of the space, but should divulge +the above information if any member of a server could see it. It is up to the +calling server to properly filter this information. -Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice or Bob (and hence whether it should share details of private rooms within that space). +Consider that Alice and Bob share a server; Alice is a member of a space, but Bob +is not. The remote server will not know whether the request is on behalf of Alice +or Bob (and hence whether it should share details of private rooms within that +space). -Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. +Trust is placed in the calling server: if there are any users on the calling +server in the correct space, that calling server has a right to know about the +rooms in that space and should return the relevant summaries, along with enough +information that the calling server can then do some filtering. -(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) +(The alternative, where the calling server sends the requesting `user_id`, and +the target server does the filtering, is unattractive because it rules out a +future world where the calling server can cache the result.) -This does not decrease security since a server could lie and make a request on behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. +This does not decrease security since a server could lie and make a request on +behalf of a user in the proper space to see the given information. I.e. the +calling server must be trusted anyway. ## Future extensions -Dedicated client-server and server-server APIs could be added to request the stripped state events, but that is considered out-of-scope for the current proposal. +Dedicated client-server and server-server APIs could be added to request the +stripped state events, but that is considered out-of-scope for the current +proposal. ## Unstable prefix @@ -86,8 +134,10 @@ N/A ## Footnotes -[1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) +[1]: The rationale for including `knock` is that the user can +trivially get this state already by knocking on the room.[↩](#a1) [2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) -[3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) +[3]: This is already sent from Synapse and generally seems useful for +a user to know before joining a room.[↩](#a3) From 45bcd86dcb2718ff311dd37c25f7bf5ad9bdd9c1 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 08:56:38 -0400 Subject: [PATCH 05/19] Strip whitespace. --- .../3173-expose-stripped-state-events.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 8439519b8ef..0a6609269fd 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -43,7 +43,7 @@ for knocking users: It is also provides an extended rationale of why this is useful: > These stripped state events contain information about the room, most notably the -> room's name and avatar. A client will need this information to show a nice +> room's name and avatar. A client will need this information to show a nice > representation of pending knocked rooms. The recommended events to include are the > join rules, canonical alias, avatar, name and encryption state of the room, rather > than all room state. This behaviour matches the information sent to remote @@ -52,9 +52,9 @@ It is also provides an extended rationale of why this is useful: [MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: -> Join rules, invites and 3PID invites work as for a normal room, with the exception +> Join rules, invites and 3PID invites work as for a normal room, with the exception > that `invite_state` sent along with invites should be amended to include the -> `m.room.create` event, to allow clients to discern whether an invite is to a +> `m.room.create` event, to allow clients to discern whether an invite is to a > space-room or not. ## Proposal @@ -67,7 +67,7 @@ the following mechanisms: * A room that has `join_rules` set to `public` or `knock`.[1](#f1) * A room that the user is in possession of an invite to (regardless of the `join_rules`). -Future MSCs might include additional mechanism for a user to join a room and +Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: * [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). @@ -82,8 +82,8 @@ include the following as stripped state events: * Room name (`m.room.name`) * Encrypted status (`m.room.encryption`)[3](#f3) -This also implies that the above information is available to any potential joiner -in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). +This also implies that the above information is available to any potential joiner +in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. @@ -106,20 +106,20 @@ calling server to properly filter this information. Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of private rooms within that +or Bob (and hence whether it should share details of private rooms within that space). Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the -rooms in that space and should return the relevant summaries, along with enough +rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. -(The alternative, where the calling server sends the requesting `user_id`, and +(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) -This does not decrease security since a server could lie and make a request on -behalf of a user in the proper space to see the given information. I.e. the +This does not decrease security since a server could lie and make a request on +behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. ## Future extensions From 62e94c5fe4293550201fb730cf4c574bc7b3a40c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:14:02 -0400 Subject: [PATCH 06/19] Remove security considerations (moved to MSC3083). --- .../3173-expose-stripped-state-events.md | 25 +------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 0a6609269fd..e35e0816e71 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -84,7 +84,7 @@ include the following as stripped state events: This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). -I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) +E.g. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. ## Potential issues @@ -99,29 +99,6 @@ knocking. ## Security considerations -The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) -does not know the user who is requesting a summary of the space, but should divulge -the above information if any member of a server could see it. It is up to the -calling server to properly filter this information. - -Consider that Alice and Bob share a server; Alice is a member of a space, but Bob -is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of private rooms within that -space). - -Trust is placed in the calling server: if there are any users on the calling -server in the correct space, that calling server has a right to know about the -rooms in that space and should return the relevant summaries, along with enough -information that the calling server can then do some filtering. - -(The alternative, where the calling server sends the requesting `user_id`, and -the target server does the filtering, is unattractive because it rules out a -future world where the calling server can cache the result.) - -This does not decrease security since a server could lie and make a request on -behalf of a user in the proper space to see the given information. I.e. the -calling server must be trusted anyway. - ## Future extensions Dedicated client-server and server-server APIs could be added to request the From 84331fc3b6527602e7c34777f6bbd419f4337f79 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:30:40 -0400 Subject: [PATCH 07/19] Re-arrange security impact of knocking. --- .../3173-expose-stripped-state-events.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index e35e0816e71..5087b4b8c40 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -64,7 +64,7 @@ Any user who is able to join a room can access the stripped state events of that Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: -* A room that has `join_rules` set to `public` or `knock`.[1](#f1) +* A room that has `join_rules` set to `public` or `knock`. * A room that the user is in possession of an invite to (regardless of the `join_rules`). Future MSCs might include additional mechanism for a user to join a room and @@ -75,12 +75,12 @@ should consider this MSC, for example: Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: -* Create event (`m.room.create`)[2](#f2) +* Create event (`m.room.create`)[2](#f1) * Join rules (`m.room.join_rules`) * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encrypted status (`m.room.encryption`)[3](#f3) +* Encrypted status (`m.room.encryption`)[3](#f2) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). @@ -99,6 +99,11 @@ knocking. ## Security considerations +This would allow for invisibly accessing the stripped state of a room with `knock` +join rules. This is already trivially accessible by knocking on the room, but +currently users in the room would know that the knock occurred. This does not +seem to be a major weakening of the security. + ## Future extensions Dedicated client-server and server-server APIs could be added to request the @@ -111,10 +116,7 @@ N/A ## Footnotes -[1]: The rationale for including `knock` is that the user can -trivially get this state already by knocking on the room.[↩](#a1) - -[2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) +[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a1) -[3]: This is already sent from Synapse and generally seems useful for -a user to know before joining a room.[↩](#a3) +[2]: This is already sent from Synapse and generally seems useful for +a user to know before joining a room.[↩](#a2) From d879eb6e009d7efcf6570ba5bbc47acf97e3da9a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 10:10:16 -0400 Subject: [PATCH 08/19] Rename encrypted status to encryption information. Co-authored-by: Travis Ralston --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 5087b4b8c40..bcf2b86357d 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -80,7 +80,7 @@ include the following as stripped state events: * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encrypted status (`m.room.encryption`)[3](#f2) +* Encryption information (`m.room.encryption`)[3](#f2) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). From 3fe5ca96b3506b0bf39e9bcba3da3a23171752a7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 10:53:16 -0400 Subject: [PATCH 09/19] Wrap text. --- proposals/3173-expose-stripped-state-events.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index bcf2b86357d..4d7ed78b068 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -2,9 +2,12 @@ It is currently possible to inspect the state of rooms in some circumstances: -* If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). +* If the room has `history_visibility: world_readable`, then anyone can inspect + it (by calling `/state` on it). * Rooms in the room directory expose some of their state publicly. -* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. +* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) + (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) + receive stripped state events. This MSC proposes exposing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It @@ -70,7 +73,9 @@ the following mechanisms: Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: -* [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). +* [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) + proposes allowing users to join a room based on their membership in a space (as defined in + [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: From d069ca285495846378a9aa2b7066c6a6d5c3dde0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:14:29 -0400 Subject: [PATCH 10/19] Also include the room topic. --- proposals/3173-expose-stripped-state-events.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 4d7ed78b068..b80f6256abd 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -80,12 +80,13 @@ should consider this MSC, for example: Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: -* Create event (`m.room.create`)[2](#f1) +* Create event (`m.room.create`)[1](#f1) * Join rules (`m.room.join_rules`) * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encryption information (`m.room.encryption`)[3](#f2) +* Encryption information (`m.room.encryption`)[2](#f2) +* Room topic (`m.room.topic`)[3](#f3) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). @@ -121,7 +122,13 @@ N/A ## Footnotes -[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a1) +[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1) -[2]: This is already sent from Synapse and generally seems useful for -a user to know before joining a room.[↩](#a2) +[2]: The encryption information (`m.room.encryption`) is already sent +from Synapse and generally seems useful for a user to know before joining a room. +[↩](#a2) + +[3]: The room topic (`m.room.topic`) is included as part of the +[room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) +response for public rooms. It is additional to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +in the spaces summary response. [↩](#a3) From b1051e42cb664ec209204982c8e7dd8415d32db0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:30:26 -0400 Subject: [PATCH 11/19] Various clarifications based on feedback. --- .../3173-expose-stripped-state-events.md | 51 +++++++++++++------ 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index b80f6256abd..ac88305b7f7 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,15 +1,17 @@ # MSC3173: Expose stripped state events to any potential joiner -It is currently possible to inspect the state of rooms in some circumstances: +The current design of Matrix somtimes allows for inspecting part of the room state +without being joined to the room: * If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). -* Rooms in the room directory expose some of their state publicly. +* Rooms in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) + expose some of their state publicly. * [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) - (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) - receive stripped state events. + and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403) + receive stripped state events to display metadata to users. -This MSC proposes exposing the stripped state events that are currently available +This MSC proposes allowing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It also consolidates the recommendation on which states events are available to potential joiners. @@ -62,10 +64,13 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal -Any user who is able to join a room can access the stripped state events of that room. +Any user who is able to join a room shall be allowed to have access the stripped +state events of that room. No changes are proposed to the mechanics of how the +users may get those state events, e.g. the `invite_state` of an invite or the +roomd irectory. -Potential ways that a user might be able to join include, but are not limited to, -the following mechanisms: +Potential ways that a user might be able to join a room include, but are not +limited to, the following mechanisms: * A room that has `join_rules` set to `public` or `knock`. * A room that the user is in possession of an invite to (regardless of the `join_rules`). @@ -77,8 +82,10 @@ should consider this MSC, for example: proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). -Additionally, it is recommended, but not required, that homeserver implementations -include the following as stripped state events: +It is also proposed to create a single definition for what stripped state events +should be provided to be potential joiners. Thus, it is recommended (although not +required[0](#f0)) that homeserver implementations include the +following as stripped state events: * Create event (`m.room.create`)[1](#f1) * Join rules (`m.room.join_rules`) @@ -88,11 +95,6 @@ include the following as stripped state events: * Encryption information (`m.room.encryption`)[2](#f2) * Room topic (`m.room.topic`)[3](#f3) -This also implies that the above information is available to any potential joiner -in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). -E.g. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) -can expose the information available in stripped state events. - ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -112,16 +114,35 @@ seem to be a major weakening of the security. ## Future extensions +### Dedicated APIs + Dedicated client-server and server-server APIs could be added to request the stripped state events, but that is considered out-of-scope for the current proposal. +### Revisions to the room directory + +A future MSC could include additional information from the stripped state events +in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms). +This seems to mostly be the encryption information, but there may also be other +pieces of information to include. + +### Additional ways to join a room + +[MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) leverages this to +expose the information available in stripped state events via the spaces summary +for potential joiners due to membership in a space. + ## Unstable prefix N/A ## Footnotes +[0]: Privacy conscious deployments may wish to limit the metadata +available to users who are not in a room as the trade-off against user experience. +There seems to be no reason to not allow this. [↩](#a0) + [1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1) [2]: The encryption information (`m.room.encryption`) is already sent From c44998cb6695f99e9419a8a3ec1160bdadc8cd0c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:37:11 -0400 Subject: [PATCH 12/19] Fix awkward wording. --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index ac88305b7f7..2a15dbe7abb 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -151,5 +151,5 @@ from Synapse and generally seems useful for a user to know before joining a roo [3]: The room topic (`m.room.topic`) is included as part of the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) -response for public rooms. It is additional to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +response for public rooms. It is also planned to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) in the spaces summary response. [↩](#a3) From 29e4006f3c2c2161f2bf854cf8a301336dfa7253 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 18 May 2021 12:38:29 -0400 Subject: [PATCH 13/19] Fix typo. Co-authored-by: Travis Ralston --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 2a15dbe7abb..f59368144ee 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -67,7 +67,7 @@ recommends including the `m.room.create` event as one of the stripped state even Any user who is able to join a room shall be allowed to have access the stripped state events of that room. No changes are proposed to the mechanics of how the users may get those state events, e.g. the `invite_state` of an invite or the -roomd irectory. +room directory. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: From 6923606e437240c0a901349c32853c81817b416e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 18 May 2021 13:22:33 -0400 Subject: [PATCH 14/19] Clarify what changes are being proposed. --- proposals/3173-expose-stripped-state-events.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index f59368144ee..37f7107c0cb 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -13,8 +13,8 @@ without being joined to the room: This MSC proposes allowing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It -also consolidates the recommendation on which states events are available to -potential joiners. +also consolidates the recommendation on which events to include as stripped state +for potential joiners. ## Background @@ -64,10 +64,16 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal +This proposal includes two aspects which are dealt with separately: + +1. Generalizing when a user is allowed to view the stripped state of a room. +2. A consistent recommendation for which events to include in the stripped state. + +### Accessing the stripped state of a room + Any user who is able to join a room shall be allowed to have access the stripped state events of that room. No changes are proposed to the mechanics of how the -users may get those state events, e.g. the `invite_state` of an invite or the -room directory. +users may get those state events. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: @@ -82,6 +88,8 @@ should consider this MSC, for example: proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). +### Events to include in the stripped state + It is also proposed to create a single definition for what stripped state events should be provided to be potential joiners. Thus, it is recommended (although not required[0](#f0)) that homeserver implementations include the From 4b7dc17fbe8e01a7a867b2c3d42a7c4488fb3137 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 25 May 2021 15:25:50 -0400 Subject: [PATCH 15/19] Include an API endpoint. --- .../3173-expose-stripped-state-events.md | 111 +++++++++++++++--- 1 file changed, 94 insertions(+), 17 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 37f7107c0cb..d54589b612d 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,7 +1,11 @@ # MSC3173: Expose stripped state events to any potential joiner -The current design of Matrix somtimes allows for inspecting part of the room state -without being joined to the room: +It can be useful to view the partial state of a room before joining to allow a user +to know *what* they're joining. For example, it improves the user experience to +show the user the room name and avatar before joining. + +It is already allowed to partially view the room state without being joined to +the room in some situations: * If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). @@ -14,7 +18,13 @@ without being joined to the room: This MSC proposes allowing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It also consolidates the recommendation on which events to include as stripped state -for potential joiners. +for potential joiners and provides a way to query for the stripped state directly. + +This will allow for improved future use cases, such as: + +* Improved user experience for more complicated access controls (e.g. + [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083)). +* More information available to platforms like matrix.to. ## Background @@ -64,16 +74,18 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal -This proposal includes two aspects which are dealt with separately: +This proposal includes a few aspects which are dealt with separately: 1. Generalizing when a user is allowed to view the stripped state of a room. 2. A consistent recommendation for which events to include in the stripped state. +3. Providing a dedicated API for accessing the stripped state of the room. ### Accessing the stripped state of a room Any user who is able to join a room shall be allowed to have access the stripped -state events of that room. No changes are proposed to the mechanics of how the -users may get those state events. +state events of that room. Additionally, any user who could access the state of +a room may access the stripped state of a room, as it is a strict subset of +information. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: @@ -103,6 +115,67 @@ following as stripped state events: * Encryption information (`m.room.encryption`)[2](#f2) * Room topic (`m.room.topic`)[3](#f3) +### Stripped state API + +`GET /_matrix/client/r0/rooms/{roomId}/stripped_state` + +A dedicated API is provided to query for the stripped state of a room. As +described above, any potential joiner may access the stripped state of a room +(and in the case of a room with `history_visibility: world_readable` -- anyone +may access the stripped state, as it is a strict subset of the state). + +This API is rate-limited and does not require authentication. + +The request format follows [the `/state`](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state) +endpoint. + +The response body includes an array of `StrippedState`, as +[described in the `/sync` response](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-sync). + +#### Example request: + +`GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/stripped_state HTTP/1.1` + +#### Responses: + +##### Status code 200: + +The current stripped state of the room + +```json +[ + { + "content": { + "join_rule": "public" + }, + "type": "m.room.join_rules", + "sender": "@example:example.org", + "state_key": "" + }, + { + "content": { + "creator": "@example:example.org", + "room_version": "1", + "m.federate": true, + "predecessor": { + "event_id": "$something:example.org", + "room_id": "!oldroom:example.org" + } + }, + "type": "m.room.create", + "sender": "@example:example.org", + "state_key": "" + } +] +``` + +Note that this is the same example as [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state), +but limited to what would be returned as stripped state. + +##### Status code 403: + +You are not a member of the room, a potential joiner, and the room is not publicly viewable. + ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -115,25 +188,29 @@ knocking. ## Security considerations -This would allow for invisibly accessing the stripped state of a room with `knock` -join rules. This is already trivially accessible by knocking on the room, but -currently users in the room would know that the knock occurred. This does not -seem to be a major weakening of the security. +This would allow for invisibly accessing the stripped state of a room with `public` +or `knock` join rules. -## Future extensions +In the case of a public room, if the room has `history_visibility` set to `world_readable` +then this is no change. Otherwise, it is trivial to access the state of the room +by joining, but currently users in the room would know that the join occurred. +Additionally, this information is already provided by the room directory (if +the room is listed there). -### Dedicated APIs +Similarly, in the case of knocking, a user is able to trivially access the +stripped state of the room by knocking, but users in the room would know that +the knock occurred. -Dedicated client-server and server-server APIs could be added to request the -stripped state events, but that is considered out-of-scope for the current -proposal. +This does not seem to be weakening the security expectations of either join rule. + +## Future extensions ### Revisions to the room directory A future MSC could include additional information from the stripped state events in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms). -This seems to mostly be the encryption information, but there may also be other -pieces of information to include. +The main missing piece seems to be the encryption information, but there may also +be other pieces of information to include. ### Additional ways to join a room From b5d096957e2a28e46eba3ffc2948d0ea3d1e9d39 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 26 May 2021 08:22:32 -0400 Subject: [PATCH 16/19] Clarify examples. --- proposals/3173-expose-stripped-state-events.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index d54589b612d..3dccaf33031 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -24,7 +24,9 @@ This will allow for improved future use cases, such as: * Improved user experience for more complicated access controls (e.g. [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083)). -* More information available to platforms like matrix.to. +* Showing a room preview on platforms when peeking fails (using for clients as + well as matrix.to). +* Joining by alias (e.g. as in Element) could show a room preview. ## Background From b94d379921696731c0ca2ac17257cd94ea3dd2a7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 1 Jun 2021 13:59:21 -0400 Subject: [PATCH 17/19] Add federation and reword a bit. --- .../3173-expose-stripped-state-events.md | 73 +++++++++++++++---- 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 3dccaf33031..565dad7bdb9 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -79,7 +79,8 @@ recommends including the `m.room.create` event as one of the stripped state even This proposal includes a few aspects which are dealt with separately: 1. Generalizing when a user is allowed to view the stripped state of a room. -2. A consistent recommendation for which events to include in the stripped state. +2. A consistent definition of stripped state and a recommendation for which + events to include in the stripped state. 3. Providing a dedicated API for accessing the stripped state of the room. ### Accessing the stripped state of a room @@ -102,12 +103,21 @@ should consider this MSC, for example: proposes allowing users to join a room based on their membership in a space (as defined in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). -### Events to include in the stripped state +### Stripped state definitions and recommended events -It is also proposed to create a single definition for what stripped state events -should be provided to be potential joiners. Thus, it is recommended (although not -required[0](#f0)) that homeserver implementations include the -following as stripped state events: +It is also proposed to create a single definition of what the stripped state of +a room is and for what events should be included in the stripped state to be +potential joiners. + +The stripped state of a room is a list of simplified state events to help a +potential joiner identify the room. These state events may only have the +`sender`, `type`, `state_key` and `content` keys present. These events do not +replace any state that the client already has for the room, for example if the +client has archived the room. + +It is recommended (although not required[0](#f0)) that +homeserver implementations include the following events as part of the stripped +state of a room: * Create event (`m.room.create`)[1](#f1) * Join rules (`m.room.join_rules`) @@ -119,7 +129,9 @@ following as stripped state events: ### Stripped state API -`GET /_matrix/client/r0/rooms/{roomId}/stripped_state` +#### Client-server API + +`GET /_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` A dedicated API is provided to query for the stripped state of a room. As described above, any potential joiner may access the stripped state of a room @@ -128,19 +140,26 @@ may access the stripped state, as it is a strict subset of the state). This API is rate-limited and does not require authentication. -The request format follows [the `/state`](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state) -endpoint. +The request format follows [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state), +but with the addition of handling a `server_name` query parameter (as +specified for [the `/join/{roomIdOrAlias}` endpoint](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-join-roomidoralias)). The response body includes an array of `StrippedState`, as [described in the `/sync` response](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-sync). -#### Example request: +If the homeserver does not know the state of the requested room it should use +the corresponding federation API to request the stripped state from another +homeserver. + +TODO + +##### Example request: `GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/stripped_state HTTP/1.1` -#### Responses: +##### Responses: -##### Status code 200: +###### Status code 200: The current stripped state of the room @@ -174,10 +193,33 @@ The current stripped state of the room Note that this is the same example as [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state), but limited to what would be returned as stripped state. -##### Status code 403: +###### Status code 403: You are not a member of the room, a potential joiner, and the room is not publicly viewable. +#### Server-server API + +`GET /_matrix/federation/v1/stripped_state/{roomId}` + +Retrieve the stripped state of a room, this is essentially identical to the +client-server API, but will not reach out over federation. + +Path parameters: + +* `roomId` - **Required.** The room ID to get state for. + +Response format: + +* `stripped_state` - `[StrippedState]` A list of simplified events to help identify the room. + +The form of `StrippedState` is as defined in +[the `/invite/{roomId}/{eventId}` endpoint](https://matrix.org/docs/spec/server_server/latest#put-matrix-federation-v2-invite-roomid-eventid). + +The stripped state should be returned to the requesting server if the host has +a potential joiner, e.g. if the room has `join_rules` set to `public` or any +user on the request server is in possession of an invite to the room. The +requesting server is responsible for filtering the returned data to the client. + ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -222,7 +264,10 @@ for potential joiners due to membership in a space. ## Unstable prefix -N/A +| Stable Endpoint | Unstable Endpoint | +|---|---| +| `/_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` | `/_matrix/client/unstable/org.matrix.msc3173/rooms/{roomIdOrAlias}/stripped_state` | +| `/_matrix/federation/v1/stripped_state/{roomId}` | `/_matrix/federation/unstable/org.matrix.msc3173/stripped_state/{roomId}` | ## Footnotes From 122c803f35468a21ccf60ec62a2bd3d8eea2fcc5 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 1 Jun 2021 18:35:12 -0400 Subject: [PATCH 18/19] Rework this (again) to remove the API based on conversations with the SCT. --- .../3173-expose-stripped-state-events.md | 219 ++++++------------ 1 file changed, 65 insertions(+), 154 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 565dad7bdb9..69d80b61572 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -15,18 +15,10 @@ the room in some situations: and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403) receive stripped state events to display metadata to users. -This MSC proposes allowing the stripped state events that are currently available -to invited and knocking users to any user who could potentially join a room. It -also consolidates the recommendation on which events to include as stripped state -for potential joiners and provides a way to query for the stripped state directly. - -This will allow for improved future use cases, such as: - -* Improved user experience for more complicated access controls (e.g. - [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083)). -* Showing a room preview on platforms when peeking fails (using for clients as - well as matrix.to). -* Joining by alias (e.g. as in Element) could show a room preview. +This MSC proposes formalizing that the stripped state that is currently available +to invited and knocking users is available to any user who could potentially join +a room. It also defines "stripped state" and consolidates the recommendation on +which events to include in the stripped state. ## Background @@ -76,19 +68,12 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal -This proposal includes a few aspects which are dealt with separately: - -1. Generalizing when a user is allowed to view the stripped state of a room. -2. A consistent definition of stripped state and a recommendation for which - events to include in the stripped state. -3. Providing a dedicated API for accessing the stripped state of the room. +The specification does not currently define what "stripped state" is or formally +describe who can access it, instead it is specified that certain situations (e.g. +an invite or knock) provide a potential joiner with the stripped state of a room. -### Accessing the stripped state of a room - -Any user who is able to join a room shall be allowed to have access the stripped -state events of that room. Additionally, any user who could access the state of -a room may access the stripped state of a room, as it is a strict subset of -information. +This MSC clarifies what "stripped state" is and formalizes who can access the +stripped state of a room in future cases. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: @@ -96,139 +81,43 @@ limited to, the following mechanisms: * A room that has `join_rules` set to `public` or `knock`. * A room that the user is in possession of an invite to (regardless of the `join_rules`). -Future MSCs might include additional mechanism for a user to join a room and -should consider this MSC, for example: +This MSC proposes a formal definition for the stripped state of a room[1](#f1): -* [MSC3083: Restricting room membership based on space membership](https://github.com/matrix-org/matrix-doc/pull/3083) - proposes allowing users to join a room based on their membership in a space (as defined in - [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)). +> The stripped state of a room is a list of simplified state events to help a +> potential joiner identify the room. These state events may only have the +> `sender`, `type`, `state_key` and `content` keys present. -### Stripped state definitions and recommended events +### Client behavior -It is also proposed to create a single definition of what the stripped state of -a room is and for what events should be included in the stripped state to be -potential joiners. +These events do not replace any state that the client already has for the room, +for example if the client has archived the room. Instead the client should keep +two separate copies of the state: the one from the stripped state and one from the +archived state. If the client joins the room then the current state will be given +as a delta against the archived state not the stripped state. -The stripped state of a room is a list of simplified state events to help a -potential joiner identify the room. These state events may only have the -`sender`, `type`, `state_key` and `content` keys present. These events do not -replace any state that the client already has for the room, for example if the -client has archived the room. +### Server behavior -It is recommended (although not required[0](#f0)) that +It is recommended (although not required[2](#f2)) that homeserver implementations include the following events as part of the stripped state of a room: -* Create event (`m.room.create`)[1](#f1) +* Create event (`m.room.create`)[3](#f3) * Join rules (`m.room.join_rules`) * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encryption information (`m.room.encryption`)[2](#f2) -* Room topic (`m.room.topic`)[3](#f3) - -### Stripped state API - -#### Client-server API - -`GET /_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` - -A dedicated API is provided to query for the stripped state of a room. As -described above, any potential joiner may access the stripped state of a room -(and in the case of a room with `history_visibility: world_readable` -- anyone -may access the stripped state, as it is a strict subset of the state). - -This API is rate-limited and does not require authentication. - -The request format follows [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state), -but with the addition of handling a `server_name` query parameter (as -specified for [the `/join/{roomIdOrAlias}` endpoint](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-join-roomidoralias)). - -The response body includes an array of `StrippedState`, as -[described in the `/sync` response](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-sync). - -If the homeserver does not know the state of the requested room it should use -the corresponding federation API to request the stripped state from another -homeserver. - -TODO - -##### Example request: - -`GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/stripped_state HTTP/1.1` - -##### Responses: - -###### Status code 200: - -The current stripped state of the room - -```json -[ - { - "content": { - "join_rule": "public" - }, - "type": "m.room.join_rules", - "sender": "@example:example.org", - "state_key": "" - }, - { - "content": { - "creator": "@example:example.org", - "room_version": "1", - "m.federate": true, - "predecessor": { - "event_id": "$something:example.org", - "room_id": "!oldroom:example.org" - } - }, - "type": "m.room.create", - "sender": "@example:example.org", - "state_key": "" - } -] -``` - -Note that this is the same example as [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state), -but limited to what would be returned as stripped state. - -###### Status code 403: - -You are not a member of the room, a potential joiner, and the room is not publicly viewable. - -#### Server-server API - -`GET /_matrix/federation/v1/stripped_state/{roomId}` - -Retrieve the stripped state of a room, this is essentially identical to the -client-server API, but will not reach out over federation. - -Path parameters: - -* `roomId` - **Required.** The room ID to get state for. - -Response format: - -* `stripped_state` - `[StrippedState]` A list of simplified events to help identify the room. - -The form of `StrippedState` is as defined in -[the `/invite/{roomId}/{eventId}` endpoint](https://matrix.org/docs/spec/server_server/latest#put-matrix-federation-v2-invite-roomid-eventid). - -The stripped state should be returned to the requesting server if the host has -a potential joiner, e.g. if the room has `join_rules` set to `public` or any -user on the request server is in possession of an invite to the room. The -requesting server is responsible for filtering the returned data to the client. +* Encryption information (`m.room.encryption`)[4](#f4) +* Room topic (`m.room.topic`)[5](#f5) ## Potential issues -This is a generalization of current behavior and shouldn't introduce any new issues. +This is a formalization of current behavior and should not introduce new issues. ## Alternatives -A different approach to this would be to separately specify each situation in which -a user is allowed to see stripped state events, as we do currently for invites and -knocking. +A different approach would be to continue with what is done today for invites, +knocking, the room directory: separately specify that a user is allowed to see +the stripped state (and what events the stripped state should contain). ## Security considerations @@ -236,16 +125,16 @@ This would allow for invisibly accessing the stripped state of a room with `publ or `knock` join rules. In the case of a public room, if the room has `history_visibility` set to `world_readable` -then this is no change. Otherwise, it is trivial to access the state of the room -by joining, but currently users in the room would know that the join occurred. -Additionally, this information is already provided by the room directory (if -the room is listed there). +then this is no change. Additionally, this information is already provided by the +room directory (if the room is listed there). Otherwise, it is trivial to access +the state of the room by joining, but currently users in the room would know +that the join occurred. Similarly, in the case of knocking, a user is able to trivially access the stripped state of the room by knocking, but users in the room would know that the knock occurred. -This does not seem to be weakening the security expectations of either join rule. +This does not seem to weaken the security expectations of either join rule. ## Future extensions @@ -256,11 +145,27 @@ in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-ma The main missing piece seems to be the encryption information, but there may also be other pieces of information to include. +### Additional ways to access the stripped state + +[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) proposes including +the stripped state in the spaces summary. Not needing to rationalize what state +can be included for a potential joiner would simplify this (and future) MSCs. + ### Additional ways to join a room -[MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) leverages this to -expose the information available in stripped state events via the spaces summary -for potential joiners due to membership in a space. +[MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) proposes a new +join rule due to membership in a space. This MSC would clarify that the stripped +state of a room is available to those joiners. + +### Dedicated API for accessing the stripped state + +Dedicated client-server and server-server APIs could be added to request the +stripped state events, but that is considered out-of-scope for the current +proposal. + +This API would allow any potential joiner to query for the stripped state. If +the server does not know the room's state it would need to query other servers +for it. ## Unstable prefix @@ -271,17 +176,23 @@ for potential joiners due to membership in a space. ## Footnotes -[0]: Privacy conscious deployments may wish to limit the metadata +[1]: No changes are proposed to +[the definition of `history_visibility`](https://matrix.org/docs/spec/client_server/latest#room-history-visibility). +The state of a room which is `world_readable` is available to anyone. This somewhat +implies that the stripped state is also available to anyone, regardless of the join +rules, but having a `world_readable`, `invite` room does not seem valuable. [↩](#a1) + +[2]: Privacy conscious deployments may wish to limit the metadata available to users who are not in a room as the trade-off against user experience. -There seems to be no reason to not allow this. [↩](#a0) +There seems to be no reason to not allow this. [↩](#a2) -[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1) +[3]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a3) -[2]: The encryption information (`m.room.encryption`) is already sent +[4]: The encryption information (`m.room.encryption`) is already sent from Synapse and generally seems useful for a user to know before joining a room. -[↩](#a2) +[↩](#a4) -[3]: The room topic (`m.room.topic`) is included as part of the +[5]: The room topic (`m.room.topic`) is included as part of the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) response for public rooms. It is also planned to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) -in the spaces summary response. [↩](#a3) +in the spaces summary response. [↩](#a5) From 5204b85f5971d4f1fffbdd1c07f91cee080384ee Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 2 Jun 2021 07:13:23 -0400 Subject: [PATCH 19/19] Remove unstable prefixes. --- proposals/3173-expose-stripped-state-events.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 69d80b61572..830a9388a6c 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -169,10 +169,7 @@ for it. ## Unstable prefix -| Stable Endpoint | Unstable Endpoint | -|---|---| -| `/_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` | `/_matrix/client/unstable/org.matrix.msc3173/rooms/{roomIdOrAlias}/stripped_state` | -| `/_matrix/federation/v1/stripped_state/{roomId}` | `/_matrix/federation/unstable/org.matrix.msc3173/stripped_state/{roomId}` | +N/A ## Footnotes