From b16b1a24d9d14b6d2d5caa863f8ed3e4aa988d06 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 00000000..002492ba --- /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 34cd85829b71254659660ca4ad5eea72a164f0a4 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 002492ba..c2408f08 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 36a0251c9a2f61431e1c7d929d8d1b6c2c79b0f0 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 c2408f08..f2b04096 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 c2a3b5d0795393c9f73131a88a741492c98cf42d 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 f2b04096..8439519b 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 34f006ce8b2f2f37f32e366ec6cac6442c74c6c4 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 8439519b..0a660926 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 bf41af7c15713d5d5f75e9f64998161e5186764a 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 0a660926..e35e0816 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 517174b19df39e92863ed3bf8acbe16ba323f19b 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 e35e0816..5087b4b8 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 56b1b0454443c01bcc24531e57c33caae7b8ac75 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 5087b4b8..bcf2b863 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 12abecf5b5d58ec5a465071072adc4596ed48657 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 bcf2b863..4d7ed78b 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 086095f72eeea1f7b786a9beff77ce89ea1edcf5 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 4d7ed78b..b80f6256 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 1c34a466edc7b675339cbf984e18399cbb5ff01e 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 b80f6256..ac88305b 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 1672ce2b0c5b0d785c242f9bbe277b20f57784a1 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 ac88305b..2a15dbe7 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 2522ed5eae25ef255aa96659bd18e3ace32eac59 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 2a15dbe7..f5936814 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 7daf3376b29edd5c8dbb1fd8a4c01902ea00d587 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 f5936814..37f7107c 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 c37512343ee1b231fcd09bc1dcaa304c072a4acd 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 37f7107c..d54589b6 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 8082b2f813de68ce9e6b734e074a0a2698d971d9 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 d54589b6..3dccaf33 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 4933ecd1768b38138d43e9448c779161394dbb74 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 3dccaf33..565dad7b 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 b9daaa3a3f60c12c727d21f52f31442a3e3e774f 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 565dad7b..69d80b61 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 c027957f01e4f0e41c68813a66d2fd2bced1a20e 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 69d80b61..830a9388 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