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: +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. -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. - -### 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)