From 6bd4b3c08a7a5137700c8fbf76008b27de92efe0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 10 Feb 2020 20:29:38 +0000 Subject: [PATCH 1/9] MSC: Updated semantics for publishing room aliases --- proposals/2432-revised-alias-publishing.md | 225 +++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 proposals/2432-revised-alias-publishing.md diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md new file mode 100644 index 00000000000..8ef08f7db53 --- /dev/null +++ b/proposals/2432-revised-alias-publishing.md @@ -0,0 +1,225 @@ +# MSC2432: Updated semantics for publishing room aliases + +This MSC offers an alternative to [MSC2260](https://github.com/matrix-org/matrix-doc/issues/2260). + +## Background + +The [`m.room.aliases`](https://matrix.org/docs/spec/client_server/r0.6.0#m-room-aliases) +state event exists to list the available aliases for a given room. This serves +two purposes: + + * It allows existing members of the room to discover alternative aliases, + which may be useful for them to pass this knowledge on to others trying to + join. + + * Secondarily, it helps to educate users about how Matrix works by + illustrating multiple aliases per room and giving a perception of the size + of the network. + +However, it has problems: + + * Any user in the entire ecosystem can create aliases for rooms, which are + then unilaterally added to `m.room.aliases`, and room admins are unable to + remove them. This is an abuse + vector (https://github.com/matrix-org/matrix-doc/issues/625). + + * For various reasons, the `m.room.aliases` event tends to get out of sync + with the actual aliases (https://github.com/matrix-org/matrix-doc/issues/2262). + +## Proposal + +We propose that that room moderators should be able to manually curate a list +of "official" aliases for their room, instead of matrix servers automatically +publishing lists of all room aliases into the room state. No particular +guarantees are offered that this alias list is entirely accurate: it becomes +room moderators' responsibilty to keep it so. + +Meanwhile, the aliases that map to a given room on a given server become +the ultimate responsibility of the administrators of that server. We give them +tools to inspect the alias list and clean it up when necessary, in addition to +the current tools which allow restriction of who can create aliases in the +first place. + +A detailed list of proposed modifications to the Matrix spec follows: + + * `m.room.aliases` loses any special meaning within the spec. In particular: + + * Clients should no longer format it specially in room timelines. + + * Clients and servers should no longer consider `m.room.aliases` when + [calculating the display name for a + room](https://matrix.org/docs/spec/client_server/r0.6.0#calculating-the-display-name-for-a-room). + + (Note: servers follow the room display-name algorithm when calculating + room names for certain types of push notification.) + + * A future room version will remove the special [authorization +rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and +[redaction rules](https://matrix.org/docs/spec/client_server/r0.6.0#redactions). + + * [`m.room.canonical_alias`](https://matrix.org/docs/spec/client_server/r0.6.0#m-room-canonical-alias) + is extended to include a new `alt_aliases` property. This, if present, + should be a list of alternative aliases for the room. An example event might + look like: + + ```json + { + "content": { + "alias": "#somewhere:localhost", + "alt_aliases": [ + "#somewhere:overthere.com", + "#somewhereelse:example.com" + ] + }, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "state_key": "", + "type": "m.room.canonical_alias" + } + ``` + + It is valid for `alt_aliases` to be non-empty even if `alias` is absent or + empty. This means that no alias has been picked out as the 'main' alias. + + (Note: although the spec currently claims that `alias` is mandatory, Synapse + generates `m.room.canonical` alias events with no `alias` property when the + main alias is deleted. This change would legitimise that behaviour.) + + (For clarity: it is not proposed that the `alt_aliases` be considered when + calculating the displayname for a room.) + + * [`PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-rooms-roomid-state-eventtype-statekey) + is extended to recommend that servers validate any *new* aliases added to + `m.room.canonical_alias` by checking that it is a valid alias according to + the [syntax](https://matrix.org/docs/spec/appendices#room-aliases), and by + looking up the alias and and that it corresponds to the expected room ID. + + (Note: Synapse currently implements this check on the main alias, though + this is unspecced.) + + (TODO: what error code should be returned if the alias is invalid, or if it + points to the wrong room?) + + * Currently, [`PUT /_matrix/client/r0/directory/room/{roomAlias}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-directory-room-roomalias) + attempts to send updated `m.room.aliases` events on the caller's + behalf. (This is implemented in Synapse but does not appear to be explicitly + specced.) This functionality should be removed. + + * Currently, [`DELETE /_matrix/client/r0/directory/room/{roomAlias}`](https://matrix.org/docs/spec/client_server/r0.6.0#delete-matrix-client-r0-directory-room-roomalias), + attempts to send updated `m.room.aliases` and/or `m.room.canonical_alias` + events on the caller's behalf, removing any aliases which have been + deleted. (Again, this is implemented in Synapse but does not appear to be + explicitly specced.) The `m.room.aliases` functionality should be removed, + and the `m.room.canonical_alias` functionality should be extended to cover + `alt_aliases`. As today, no error occurs if the caller does not have + permission to send such an event. + + * A new api endpoint, `GET /_matrix/client/r0/rooms/{roomId}/aliases` is + added, which returns the list of aliases currently defined on the local + server for the given room. The response looks like: + + ```json + { + "aliases": [ + "#somewhere:example.com", + "#somewhereelse:example.com", + "#special_alias:example.com" + ] + } + ``` + + This API can be called by any current member of the room (calls from other + users result in `M_FORBIDDEN`). + + TODO: should this be tied in with `history_visibilty` to allow peeking from + non-members? On the one hand that feels like pointless clutter; on the other + it feels like it makes it more consistent with peekable rooms. + +Various APIs are currently subject to implementation-defined access +restrictions. No change to the specification is changed in this regard +(implementations will continue to be free to impose their own +restrictions). Nevertheless as part of this MSC it is useful to consider some +proposed changes to Synapse's implementation: + + * No change: `PUT /_matrix/client/r0/directory/room/{roomAlias}`: Synapse + only allows access to current members of the room, and also exposes some + configuration options which allow restriction of which users are allowed to + create aliases in general. + + * `DELETE /_matrix/client/r0/directory/room/{roomAlias}`: in this case, + currently Synapse restricts its use to the user that created the alias, and + server admins. + + It is proposed to extend this to local users who have a power-level + sufficient to send an `m.room.canonical_alias` event in the room that the + alias currently points to. + + * [`PUT /_matrix/client/r0/directory/list/room/{roomId}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-directory-list-room-roomid) + and the corresponding unspecced `DELETE` api (both of which set the + visibility of a room in the public directory): currently Synapse restricts + their use to server admins and local users who have a PL sufficient to send + an `m.room.aliases` event in the room (ignoring the special auth + rules). This will be changed to check against the PL required to send an + `m.room.canonical_alias` event. + +It is envisaged that Matrix clients will then change their "Room Settings" user +interface to display the aliases from `m.room.canonical_alias` instead of those +in `m.room.aliases`, as well as giving moderators the ability to update that +list. Clients might also wish to use the new `GET +/_matrix/client/r0/rooms/{roomId}/aliases` endpoint to obtain and display the +currently-available local aliases, though given that this list may be subject +to abuse, it should probably not be shown by default. + +### Future work + +This work isn't considered part of this MSC, but rather a potential extension +for the future. + + * It may be useful to be able to query remote servers for their alias + list. This could be done by extending `GET + /_matrix/client/r0/rooms/{roomId}/aliases` to take a `server_name` + parameter, and defining an API in the server_server spec which will expose + the requested information, subject to the calling homeserver having at least + one user with a right to see it. + + * Similarly, room moderators may wish to be able to delete aliases on a remote + server for their room. We could envisage a fedaration API which allows such + a request to be made, subject to the calling homeserver having at least one + moderator in the room. + +## Potential issues + +The biggest problem with this proposal is that existing clients, which rely on +`m.room.aliases` in one way or another, will lose functionality. In particular, +they may not know about aliases that exist, or they may look at outdated +`m.room.aliases` events that list aliases that no longer exist. However, since +`m.room.aliases` is best-effort anyway, these are both problems that exist to +some extent today. + +## Alternatives + +We considered continuing to use `m.room.aliases` to advertise room aliases +instead of `m.room.canonical_alias`, but the significant changes in semantics +made that seem inappropriate. + +We also considered using separate state events for each advertised alias, +rather than listing them all in one event. This might increase the number of +aliases which can be advertised, and help to reduce races when editing the +list. However, the 64KB limit of an event still allows room for hundreds of +aliases of any sane length, and we don't expect the list to be changing +frequently enough for races to be a practical concern. Ultimately the added +complexity seemed redundant. + +A previous suggestion was +[MSC2260](https://github.com/matrix-org/matrix-doc/issues/2260), which proposed +keeping `m.room.aliases` largely as-is, but giving room moderators tools to +control who can send them via room power-levels. We dismissed it for the +reasons set out at +https://github.com/matrix-org/matrix-doc/pull/2260#issuecomment-584207073. + +## Security considerations + +None currently identified. + +## Unstable prefix + +TBD. From 95ff26679bf4f780509e73d2201cafe9ce40c111 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 11 Feb 2020 11:16:56 +0000 Subject: [PATCH 2/9] Apply suggestions from code review Co-Authored-By: Matthew Hodgson Co-Authored-By: Hubert Chathi --- proposals/2432-revised-alias-publishing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index 8ef08f7db53..0afdf195861 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -32,7 +32,7 @@ We propose that that room moderators should be able to manually curate a list of "official" aliases for their room, instead of matrix servers automatically publishing lists of all room aliases into the room state. No particular guarantees are offered that this alias list is entirely accurate: it becomes -room moderators' responsibilty to keep it so. +room moderators' responsibility to keep it so. Meanwhile, the aliases that map to a given room on a given server become the ultimate responsibility of the administrators of that server. We give them @@ -182,7 +182,7 @@ for the future. one user with a right to see it. * Similarly, room moderators may wish to be able to delete aliases on a remote - server for their room. We could envisage a fedaration API which allows such + server for their room. We could envisage a federation API which allows such a request to be made, subject to the calling homeserver having at least one moderator in the room. From 786772f7646f8767c008872abc6fc41b9fe7b809 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 18 Feb 2020 16:24:46 +0000 Subject: [PATCH 3/9] Update proposals/2432-revised-alias-publishing.md Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2432-revised-alias-publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index 0afdf195861..a68872640e9 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -81,7 +81,7 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and empty. This means that no alias has been picked out as the 'main' alias. (Note: although the spec currently claims that `alias` is mandatory, Synapse - generates `m.room.canonical` alias events with no `alias` property when the + generates `m.room.canonical_alias` events with no `alias` property when the main alias is deleted. This change would legitimise that behaviour.) (For clarity: it is not proposed that the `alt_aliases` be considered when From 645dbcc0912624a32d070b2c7ae30d936f1e2f7b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 19 Feb 2020 07:25:34 +0000 Subject: [PATCH 4/9] make room alias lists peekable --- proposals/2432-revised-alias-publishing.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index a68872640e9..4a5d95adfbe 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -128,11 +128,8 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and ``` This API can be called by any current member of the room (calls from other - users result in `M_FORBIDDEN`). - - TODO: should this be tied in with `history_visibilty` to allow peeking from - non-members? On the one hand that feels like pointless clutter; on the other - it feels like it makes it more consistent with peekable rooms. + users result in `M_FORBIDDEN`). For rooms with `history_visibility` set to + `world_readable`, it can also be called by users outside the room. Various APIs are currently subject to implementation-defined access restrictions. No change to the specification is changed in this regard From 30d762cc72ad179ceb612dea046418770546714e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 19 Feb 2020 07:25:49 +0000 Subject: [PATCH 5/9] document unstable prefixes/feature flags --- proposals/2432-revised-alias-publishing.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index 4a5d95adfbe..81d59e71a3e 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -219,4 +219,11 @@ None currently identified. ## Unstable prefix -TBD. +While this feature is in development, the following names will be in use: + +| Proposed final name | Name while in development | +| `GET /_matrix/client/r0/rooms/{roomId}/aliases` | `GET /_matrix/client/unstable/org.matrix.msc2432/rooms/{roomId}/aliases` | + +Servers will indicate support for the new endpoint via a non-empty value for feature flag +`org.matrix.msc2432` in `unstable_features` in the response to `GET +/_matrix/client/versions`. From 98a6cd0f45426beca4eb1e0334573a1ea3748642 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 19 Feb 2020 07:29:55 +0000 Subject: [PATCH 6/9] fix table --- proposals/2432-revised-alias-publishing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index 81d59e71a3e..c527a14ed6c 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -222,6 +222,7 @@ None currently identified. While this feature is in development, the following names will be in use: | Proposed final name | Name while in development | +| --- | --- | | `GET /_matrix/client/r0/rooms/{roomId}/aliases` | `GET /_matrix/client/unstable/org.matrix.msc2432/rooms/{roomId}/aliases` | Servers will indicate support for the new endpoint via a non-empty value for feature flag From 8b9ea10e11bd0a460211e1826543fe17f2667e19 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 19 Feb 2020 07:31:57 +0000 Subject: [PATCH 7/9] server admins can list aliases --- proposals/2432-revised-alias-publishing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index c527a14ed6c..433ce0f66b4 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -131,6 +131,9 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and users result in `M_FORBIDDEN`). For rooms with `history_visibility` set to `world_readable`, it can also be called by users outside the room. + Servers might also choose to allow access to other users such as server + administrators. + Various APIs are currently subject to implementation-defined access restrictions. No change to the specification is changed in this regard (implementations will continue to be free to impose their own From 4e123ca12113bd0587ac641503f0e8da9f6af4f0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Sat, 29 Feb 2020 23:29:33 +0000 Subject: [PATCH 8/9] Update proposals/2432-revised-alias-publishing.md Co-Authored-By: Kitsune Ral --- proposals/2432-revised-alias-publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index 433ce0f66b4..dff72df5ae8 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -135,7 +135,7 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and administrators. Various APIs are currently subject to implementation-defined access -restrictions. No change to the specification is changed in this regard +restrictions. No change to the specification is introduced in this regard (implementations will continue to be free to impose their own restrictions). Nevertheless as part of this MSC it is useful to consider some proposed changes to Synapse's implementation: From 7917d087f3874f07cfaf0750ed493ded95bc77ac Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 19 Mar 2020 15:21:50 +0000 Subject: [PATCH 9/9] clarifications --- proposals/2432-revised-alias-publishing.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/proposals/2432-revised-alias-publishing.md b/proposals/2432-revised-alias-publishing.md index dff72df5ae8..4c2f010f13b 100644 --- a/proposals/2432-revised-alias-publishing.md +++ b/proposals/2432-revised-alias-publishing.md @@ -96,8 +96,16 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and (Note: Synapse currently implements this check on the main alias, though this is unspecced.) - (TODO: what error code should be returned if the alias is invalid, or if it - points to the wrong room?) + The following error codes are specified: + + * HTTP 400, with `errcode: M_INVALID_PARAMETER` if an attempt is made to add + an entry which is not a well-formed alias (examples: too long, doesn't + start with `#`, doesn't contain a `:`). + + * HTTP 400, with `errcode: M_BAD_ALIAS` if an added alias does not point at + the given room (either because the alias doesn't exist, because it can't + be resolved due to an unreachable server, or because the alias points at a + different room). * Currently, [`PUT /_matrix/client/r0/directory/room/{roomAlias}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-directory-room-roomalias) attempts to send updated `m.room.aliases` events on the caller's @@ -110,8 +118,14 @@ rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and deleted. (Again, this is implemented in Synapse but does not appear to be explicitly specced.) The `m.room.aliases` functionality should be removed, and the `m.room.canonical_alias` functionality should be extended to cover - `alt_aliases`. As today, no error occurs if the caller does not have - permission to send such an event. + `alt_aliases`. + + The behaviour if the calling user has permission to delete the alias but + does not have permission to send `m.room.canonical_alias` events in the room + (for example, by virtue of being a "server administrator", or by being the + user that created the alias) is implementation-defined. It is *recommended* + that in this case, the alias is deleted anyway, and a successful response is + returned to the client. * A new api endpoint, `GET /_matrix/client/r0/rooms/{roomId}/aliases` is added, which returns the list of aliases currently defined on the local