wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Patrick Cloke 2021-06-01 18:35:12 -04:00 • committed by Richard van der Hoff
parent 4933ecd176
commit b9daaa3a3f
1 changed files with 65 additions and 154 deletions
Download patch file Download diff file Expand all files Collapse all files

219
proposals/3173-expose-stripped-state-events.md
View file

@ -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<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
@ -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
<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)