Merge pull request #2432 from matrix-org/rav/proposal/alt_canonical_a…

…liases

MSC2432: Updated semantics for publishing room aliases

proposals/2432-revised-alias-publishing.md

@@ -0,0 +1,247 @@
+# 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' 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
+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.)
+
+   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
+   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`.
+
+   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
+   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`). 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 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:
+
+ * 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 federation 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
+
+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`.