Rework this (again) to remove the API based on conversations with the SCT.

clokep · richvdh · commit b9daaa3a3f60 · 2021-08-27T19:17:15.000+01:00
diff --git 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,176 +68,73 @@ 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:
 
 * 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<sup id="a1">[1](#f1)</sup>:
 
-* [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<sup id="a0">[0](#f0)</sup>) that
+It is recommended (although not required<sup id="a2">[2](#f2)</sup>) that
 homeserver implementations include the following events as part of the stripped
 state of a room:
 
-* Create event (`m.room.create`)<sup id="a1">[1](#f1)</sup>
+* Create event (`m.room.create`)<sup id="a3">[3](#f3)</sup>
 * 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`)<sup id="a2">[2](#f2)</sup>
-* Room topic (`m.room.topic`)<sup id="a3">[3](#f3)</sup>
-
-### 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`)<sup id="a4">[4](#f4)</sup>
+* Room topic (`m.room.topic`)<sup id="a5">[5](#f5)</sup>
 
 ## 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
 
 This would allow for invisibly accessing the stripped state of a room with `public`
 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
 
-<a id="f0"/>[0]: Privacy conscious deployments may wish to limit the metadata
+<a id="f1"/>[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)
+
+<a id="f2"/>[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)
 
-<a id="f1"/>[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1)
+<a id="f3"/>[3]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a3)
 
-<a id="f2"/>[2]: The encryption information (`m.room.encryption`) is already sent
+<a id="f4"/>[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)
 
-<a id="f3"/>[3]: The room topic (`m.room.topic`) is included as part of the
+<a id="f5"/>[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)
