From 7595a63fb2cd42d68292a0e03aa45b7456b759ac Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 14 Aug 2020 16:32:29 -0400 Subject: [PATCH 001/162] initial version of olm fallback keys --- proposals/xxxx-olm-fallback-keys.md | 54 +++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 proposals/xxxx-olm-fallback-keys.md diff --git a/proposals/xxxx-olm-fallback-keys.md b/proposals/xxxx-olm-fallback-keys.md new file mode 100644 index 000000000..75322bee1 --- /dev/null +++ b/proposals/xxxx-olm-fallback-keys.md @@ -0,0 +1,54 @@ +# MSCxxxx: Olm fallback keys + +Olm uses a set of one-time keys when initializing a session between two +devices: Alice uploads one-time keys to her homeserver, and Bob claims one of +them to perform a Diffie-Hellman to generate a shared key. As implied by the +name, a one-time key is only to be used once. However, if all of Alice's +one-time keys are claimed, Bob will not be able to create a session with Alice. + +This can be addressed by Alice uploading a fallback key that is used in place +of a one-time key when no one-time keys are available. + +## Proposal + +A new request parameter, `fallback_keys`, is added to the body of the +`/keys/upload` client-server API, which is in the same format as the +`one_time_keys` parameter with the exception that there must be at most one key +per key algorithm. If the user had previously uploaded a fallback key for a +given algorithm, it is replaced -- the server will only keep one fallback key +per algorithm for each user. + +When Bob calls `/keys/claim` to claim one of Alice's one-time keys, but Alice +has no one-time keys left, the homeserver will return the fallback key instead, +if Alice had previously uploaded one. Unlike with one-time keys, fallback keys +are not deleted when they are returned by `/keys/claim`. However, the server +marks that they have been used. + +A new response parameter, `device_unused_fallback_keys`, is added to `/sync`. +This is an array listing the key algorithms for which the server has an unused +fallback key for the user. If the client wants the server to have a fallback +key for a given key algorithm, but that algorithm is not listed in +`device_unused_fallback_keys`, the client will upload a new key as above. + +## Security considerations + +Using a fallback key rather than a one-time key has security implications. An +attacker can replay a message that was originally sent with a fallback key, and +the receiving client will accept it as a new message if the fallback key is +still active. Also, an attacker that compromises a client may be able to +retrieve the private part of the fallback key to decrypt past messages if the +client has still retained the private part of the fallback key. + +For this reason, clients should not store the private part of the fallback key +indefinitely. For example, client should only store at most two fallback keys: +the current fallback key (that it has not yet received any messages for) and +the previous fallback key, and should remove the previous fallback key once it +is reasonably certain that it has received all the messages that use it (for +example, one hour after receiving the first message that used it). + +For addressing replay attacks, clients can also keep track of inbound sessions +to detect replays. + +## Unstable prefix + +TODO: ... From 94465e06c2e7f473fe0eeff28c49cfdf5d560f36 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 14 Aug 2020 16:41:48 -0400 Subject: [PATCH 002/162] use MSC number --- .../{xxxx-olm-fallback-keys.md => 2732-olm-fallback-keys.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-olm-fallback-keys.md => 2732-olm-fallback-keys.md} (98%) diff --git a/proposals/xxxx-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md similarity index 98% rename from proposals/xxxx-olm-fallback-keys.md rename to proposals/2732-olm-fallback-keys.md index 75322bee1..d24ef3800 100644 --- a/proposals/xxxx-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -1,4 +1,4 @@ -# MSCxxxx: Olm fallback keys +# MSC2732: Olm fallback keys Olm uses a set of one-time keys when initializing a session between two devices: Alice uploads one-time keys to her homeserver, and Bob claims one of From 61a886668344e78e850db8983650bfecaae817a4 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 16 Sep 2020 18:10:06 +0100 Subject: [PATCH 003/162] initial proposal --- proposals/XXXX-appservice-login.md | 79 ++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 proposals/XXXX-appservice-login.md diff --git a/proposals/XXXX-appservice-login.md b/proposals/XXXX-appservice-login.md new file mode 100644 index 000000000..d8795e206 --- /dev/null +++ b/proposals/XXXX-appservice-login.md @@ -0,0 +1,79 @@ +# MSC0000: Provide authentication method for appservice users + +Appservices within Matrix are increasingly attempting to support End-to-End Encryption. As such, they +need a way to generate devices for their users so that they can participate in E2E rooms. In order to +do so, this proposal suggests implementing an appservice extension to the +[`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). + +Appservice users do not usually need to login as they do not need their own access token, and do not +traditionally need a "device". However E2E encryption demands that all users in a room have a device +which means bridge users need to be able to generate a device on demand. + +## Proposal + +A new `type` is to be added to `POST /login`. + +`m.login.application_service` + +The `/login` endpoint may now take an `access_token` in the same way that other +authenticated endpoints do. No additional parameters should be specified in the request body. + +Example request + +```json +{ + "type": "m.login.application_service", + "identifier": { + "type": "m.id.user", + "user": "alice" + } +} +``` + +The response body should be unchanged from the existing `/login` specification. + +If +- The access token is not provided +- The access token does not correspond to a appservice +- The access token does not correspond to a appservice that manages this user +- Or the user has not previously been registered + +Then the servers should reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. + +Homeservers should ignore the `access_token` parameter if a type other than +`m.login.application_service` has been provided. + +The expected flow for appservices would be to `/register` their users, and +then `/login` to generate the appropraite device. + +## Potential issues + +This proposal means that there will be more calls to make when setting up a appservice user, when +using encryption. While this could be done during the registration step, this would prohibit creating +new devices should the appservice intentionally or inadvertently lost the client-side device data. + +## Alternatives + +One minor tweak to the current proposal could be to include the token as part of the auth data, rather than +being part of the header/params to the request. An argument could be made for either, but since the specification +expects the appservice to pass the token this way in all requests, including /register it seems wise to keep +it that way. + +Some community members have used implementation details such as a "shared secret" authentication method to +log into the accounts without having to use the /login process at all. Synapse provides such a function, +but also means the appservice can now authenticate as any user on the homeserver. + +A third option could be to create a new endpoint that simply creates a new device for an appservice user on demand. +Given the rest of the matrix eco-system does this with /login, and /login is already extensible with `type`, it would +create more work for all parties involved for little benefit. + +## Security considerations + +The /login endpoint will generate an access token which can be used to control the appservice user, which +is superflous as the appservice `as_token` should be used to authenticate all requests on behalf of ghosts. +This can safely be ignored or used, but is an extra token hanging around. + +## Unstable prefix + +Implementations should use `uk.half-shot.mscXXXX.login.application_service` for `type` given in the +`POST /login` until this lands in a released version of the specification. \ No newline at end of file From 3a649839c27a13ccddebeb1c3253cf69979cddeb Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 16 Sep 2020 18:12:07 +0100 Subject: [PATCH 004/162] 2778 --- .../{XXXX-appservice-login.md => 2778-appservice-login.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{XXXX-appservice-login.md => 2778-appservice-login.md} (96%) diff --git a/proposals/XXXX-appservice-login.md b/proposals/2778-appservice-login.md similarity index 96% rename from proposals/XXXX-appservice-login.md rename to proposals/2778-appservice-login.md index d8795e206..ba3ae1f1a 100644 --- a/proposals/XXXX-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -1,4 +1,4 @@ -# MSC0000: Provide authentication method for appservice users +# MSC2778: Providing authentication method for appservice users Appservices within Matrix are increasingly attempting to support End-to-End Encryption. As such, they need a way to generate devices for their users so that they can participate in E2E rooms. In order to @@ -75,5 +75,5 @@ This can safely be ignored or used, but is an extra token hanging around. ## Unstable prefix -Implementations should use `uk.half-shot.mscXXXX.login.application_service` for `type` given in the +Implementations should use `uk.half-shot.msc2778.login.application_service` for `type` given in the `POST /login` until this lands in a released version of the specification. \ No newline at end of file From 4751785a8c7fea71552188cdfe1a0b6e97599d16 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 16 Sep 2020 18:26:32 +0100 Subject: [PATCH 005/162] Some spelling fixes --- proposals/2778-appservice-login.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index ba3ae1f1a..22e06eb79 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -32,7 +32,8 @@ Example request The response body should be unchanged from the existing `/login` specification. -If +If: + - The access token is not provided - The access token does not correspond to a appservice - The access token does not correspond to a appservice that manages this user @@ -44,7 +45,7 @@ Homeservers should ignore the `access_token` parameter if a type other than `m.login.application_service` has been provided. The expected flow for appservices would be to `/register` their users, and -then `/login` to generate the appropraite device. +then `/login` to generate the appropriate device. ## Potential issues @@ -56,12 +57,13 @@ new devices should the appservice intentionally or inadvertently lost the client One minor tweak to the current proposal could be to include the token as part of the auth data, rather than being part of the header/params to the request. An argument could be made for either, but since the specification -expects the appservice to pass the token this way in all requests, including /register it seems wise to keep +expects the appservice to pass the token this way in all requests, including `/register`, it seems wise to keep it that way. Some community members have used implementation details such as a "shared secret" authentication method to log into the accounts without having to use the /login process at all. Synapse provides such a function, -but also means the appservice can now authenticate as any user on the homeserver. +but also means the appservice can now authenticate as any user on the homeserver. This seems undesirable from a +security standpoint. A third option could be to create a new endpoint that simply creates a new device for an appservice user on demand. Given the rest of the matrix eco-system does this with /login, and /login is already extensible with `type`, it would From f831162563ab3d87c77aecdb0a6fed4f730b31d5 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 24 Sep 2020 17:09:45 -0400 Subject: [PATCH 006/162] add clarifications, examples, etc --- proposals/2732-olm-fallback-keys.md | 45 ++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index d24ef3800..d6be01f12 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -18,6 +18,30 @@ per key algorithm. If the user had previously uploaded a fallback key for a given algorithm, it is replaced -- the server will only keep one fallback key per algorithm for each user. +When uploading fallback keys for algorithms whose key format is a signed JSON +object, client should include a property named `fallback` with a value of +`true`. + +Example: + +`POST /keys/upload` + +```json +{ + "fallback_keys": { + "signed_curve25519:AAAAAA": { + "key": "base64+public+key", + "fallback": true, + "signatures": { + "@alice:example.org": { + "ed25519:DEVICEID": "base64+signature" + } + } + } + } +} +``` + When Bob calls `/keys/claim` to claim one of Alice's one-time keys, but Alice has no one-time keys left, the homeserver will return the fallback key instead, if Alice had previously uploaded one. Unlike with one-time keys, fallback keys @@ -30,6 +54,24 @@ fallback key for the user. If the client wants the server to have a fallback key for a given key algorithm, but that algorithm is not listed in `device_unused_fallback_keys`, the client will upload a new key as above. +The `device_unused_fallback_keys` parameter must be present if the server +supports fallback keys. Clients can thus treat this field as an indication +that the server supports fallback keys, and so only upload fallback keys to +servers that support them. + +Example: + +`GET /sync` + +Response: + +```json +{ + // other fields... + "device_unused_fallback_keys": ["signed_curve25519"] +} +``` + ## Security considerations Using a fallback key rather than a one-time key has security implications. An @@ -51,4 +93,5 @@ to detect replays. ## Unstable prefix -TODO: ... +The `fallback_key` request parameter and the `device_unused_fallback_keys` +response parameter will be prefixed by `org.matrix.msc2732.`. From 48b0196ac6d2605a6f5a983621b81b74bd983c4d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 2 Oct 2020 15:52:35 -0400 Subject: [PATCH 007/162] update property name --- proposals/2732-olm-fallback-keys.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index d6be01f12..854b48c7e 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -48,13 +48,13 @@ if Alice had previously uploaded one. Unlike with one-time keys, fallback keys are not deleted when they are returned by `/keys/claim`. However, the server marks that they have been used. -A new response parameter, `device_unused_fallback_keys`, is added to `/sync`. -This is an array listing the key algorithms for which the server has an unused -fallback key for the user. If the client wants the server to have a fallback -key for a given key algorithm, but that algorithm is not listed in -`device_unused_fallback_keys`, the client will upload a new key as above. +A new response parameter, `device_unused_fallback_key_types`, is added to +`/sync`. This is an array listing the key algorithms for which the server has +an unused fallback key for the user. If the client wants the server to have a +fallback key for a given key algorithm, but that algorithm is not listed in +`device_unused_fallback_key_types`, the client will upload a new key as above. -The `device_unused_fallback_keys` parameter must be present if the server +The `device_unused_fallback_key_types` parameter must be present if the server supports fallback keys. Clients can thus treat this field as an indication that the server supports fallback keys, and so only upload fallback keys to servers that support them. @@ -68,7 +68,7 @@ Response: ```json { // other fields... - "device_unused_fallback_keys": ["signed_curve25519"] + "device_unused_fallback_key_types": ["signed_curve25519"] } ``` @@ -93,5 +93,5 @@ to detect replays. ## Unstable prefix -The `fallback_key` request parameter and the `device_unused_fallback_keys` +The `fallback_key` request parameter and the `device_unused_fallback_key_types` response parameter will be prefixed by `org.matrix.msc2732.`. From 7d9304fdde9569a4cb0733ea058fc6ed1754f1f6 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 30 Nov 2020 17:13:54 +0000 Subject: [PATCH 008/162] Clarify _bridge_alice Co-authored-by: Tulir Asokan --- proposals/2778-appservice-login.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 22e06eb79..76871c888 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -25,7 +25,7 @@ Example request "type": "m.login.application_service", "identifier": { "type": "m.id.user", - "user": "alice" + "user": "_bridge_alice" } } ``` @@ -78,4 +78,4 @@ This can safely be ignored or used, but is an extra token hanging around. ## Unstable prefix Implementations should use `uk.half-shot.msc2778.login.application_service` for `type` given in the -`POST /login` until this lands in a released version of the specification. \ No newline at end of file +`POST /login` until this lands in a released version of the specification. From 5c0000431747a20467b3b9a4d50769e604182733 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 30 Nov 2020 17:16:41 +0000 Subject: [PATCH 009/162] Add notice about identifer --- proposals/2778-appservice-login.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 76871c888..b361b2aec 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -30,6 +30,11 @@ Example request } ``` +Note: Implementations MUST use the `identifier.type`=`m.id.user` method of specifying the +localpart. The deprecated top-level `user` field **cannot** use this login flow type. This +is deliberate so as to coax developers into using the new identifier format when implementing +new flows. + The response body should be unchanged from the existing `/login` specification. If: From de65f4e1fed33100db7bb5aa59c4b0d32116e4f4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 26 Jan 2021 15:21:25 -0500 Subject: [PATCH 010/162] Add link to keys upload endpoint Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2732-olm-fallback-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index 854b48c7e..fcc7350d9 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -12,7 +12,7 @@ of a one-time key when no one-time keys are available. ## Proposal A new request parameter, `fallback_keys`, is added to the body of the -`/keys/upload` client-server API, which is in the same format as the +[`/keys/upload` client-server API](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-keys-upload), which is in the same format as the `one_time_keys` parameter with the exception that there must be at most one key per key algorithm. If the user had previously uploaded a fallback key for a given algorithm, it is replaced -- the server will only keep one fallback key From ddbcba454c14336e550809bc12e0b26d550589d4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 15 Feb 2021 10:20:48 -0500 Subject: [PATCH 011/162] Fix typo Co-authored-by: Sorunome --- proposals/2732-olm-fallback-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index fcc7350d9..7b060bec7 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -93,5 +93,5 @@ to detect replays. ## Unstable prefix -The `fallback_key` request parameter and the `device_unused_fallback_key_types` +The `fallback_keys` request parameter and the `device_unused_fallback_key_types` response parameter will be prefixed by `org.matrix.msc2732.`. From 0841f31ce48c2f337f5407991b1281b2934e4209 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 24 Mar 2021 10:24:06 -0400 Subject: [PATCH 012/162] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2732-olm-fallback-keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index 7b060bec7..5ab90117c 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -50,7 +50,7 @@ marks that they have been used. A new response parameter, `device_unused_fallback_key_types`, is added to `/sync`. This is an array listing the key algorithms for which the server has -an unused fallback key for the user. If the client wants the server to have a +an unused fallback key for the device. If the client wants the server to have a fallback key for a given key algorithm, but that algorithm is not listed in `device_unused_fallback_key_types`, the client will upload a new key as above. @@ -65,7 +65,7 @@ Example: Response: -```json +```jsonc { // other fields... "device_unused_fallback_key_types": ["signed_curve25519"] From d5633d17a49090188dd90c9898ac1ab28df9cabb Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 31 Mar 2021 11:31:51 -0400 Subject: [PATCH 013/162] Add pointer to draft. --- proposals/3083-restricted-rooms.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 proposals/3083-restricted-rooms.md diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md new file mode 100644 index 000000000..c65b1ca82 --- /dev/null +++ b/proposals/3083-restricted-rooms.md @@ -0,0 +1,4 @@ +# Restricting room membership based on space membership + +This is still in a draft stage: see +https://hackmd.io/zO0fQwo9TqurOt66mF5Qmg for the current draft. From dfcc4675b128166409b06ae32e7039613792a65e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 14 Apr 2021 13:07:03 -0400 Subject: [PATCH 014/162] Include the proposed MSC. --- proposals/3083-restricted-rooms.md | 161 ++++++++++++++++++++++++++++- 1 file changed, 159 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index c65b1ca82..1121ebf6a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -1,4 +1,161 @@ # Restricting room membership based on space membership -This is still in a draft stage: see -https://hackmd.io/zO0fQwo9TqurOt66mF5Qmg for the current draft. +Draft join rule changes for [spaces](https://github.com/matrix-org/matrix-doc/pull/1772), +this is meant to replaces the second half of [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962/). + +A desirable feature is to give room admins the power to restrict membership of +their room based on the membership of one or more spaces, for example: + +> members of the #doglovers space can join this room without an invitation[1](#f1) + +We could represent the allowed spaces with a new `join_rule` - `restricted` - to +reflect the fact that what we have is a cross between `invite` and `public`. This +would have additional content of the rooms to trust for membership. For example: + +```json +{ + "type": "m.room.join_rules", + "state_key": "", + "content": { + "join_rule": "restricted", + "allow": [ + { + "space": "!mods:example.org", + "via": ["example.org"] + }, + { + "space": "!users:example.org", + "via": ["example.org"] + } + ] + } +} +``` + +This means that a user must be a member of the `!mods:example.org` space or +`!users:example.org` space in order to join without an invite[2](#f2). Membership in +a single space is enough. + +If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the +following keys, or a string representing the MXID of the user exempted: + +* `space`: The room ID of the space to check the membership of. +* `via`: A list of servers which may be used to peek for membership of the space. + +Any entries in the list which do not match the expected format are ignored. + +When a server receives a `/join` request from a client or a `/make_join` / `/send_join` +request from a server, the request should only be permitted if the user has a valid +invite or is in one of the listed spaces (established by peeking if the server is not +already in the space, see [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444)). + +Unlike the `invite` join rule, confirmation that the `allow` rules were properly +checked cannot be enforced over federation by event authorization, so servers in +the room are trusted not to allow invalid users to join.[3](#f3) +However, user IDs listed as strings can be properly checked over federation. + +## Summary of the behaviour of join rules + +See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) +specification for full details, but the summary below should highlight the differences +between `public`, `invite`, and `restricted`. + +* `public`: anyone can join, subject to `ban` and `server_acls`, as today. +* `invite`: only people with membership `invite` can join, as today. +* `knock`: the same as `invite`, except anyone can knock, subject to `ban` and + `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). +* `private`: This is reserved and not implemented. +* `restricted`: the same as `public` from the perspective of the auth rules, but + with the additional caveat that servers are expected to check the `allow` rules + before generating a `join` event (whether for a local or a remote user). + +## Security considerations + +The `allow` feature for `join_rules` places increased trust in the servers in the + room. We consider this acceptable: if you don't want evil servers randomly + joining spurious users into your rooms, then: + +1. Don't let evil servers in your room in the first place +2. Don't use `allow` lists, given the expansion increases the attack surface anyway by letting members in other rooms dictate who's allowed into your room. + +The peek server also has significant power. For example, a poorly chosen peek +server could lie about the space membership and add an `@evil_user:example.org`. + +## Unstable prefix + +The `restricted` join rule will be included in a future room version to ensure +that servers and clients opt-into the new functionality. + +During development it is expected that an unstable room version of +`org.matrix.mscXXXX` is used. Since the room version namespaces the behaviour, +the `allow` key and the `restricted` value do not need unstable prefixes. + +## History / Rationale + +It may seem that just having the `allow` key with `public` join rules is enough, +as suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962/), +but there are concerns that having a `public` join rule that is restricted may +cause issues if an implementation does not understand the semantics of the `allow` +keyword. Using an `allow` key with `invite` join rules also does not make sense as +from the perspective of the auth rules, this is akin to `public` (since the checking +of whether a member is in the space is done during the call to `/join` +or `/make_join` / `/send_join`). + +The above concerns about an implementation not understanding the semantics of `allow` +could be solved by introducing a new room version, but if this is done it seems clearer +to just introduce a a new join rule - `restricted` - as described above. + +## Future extensions + +Potential future extensions which should not be designed out +include, but are not included in this MSC. + +### Checking space membership over federation + + + +### Kicking users out when they leave the allowed space + +In the above example, suppose `@bob:server.example` leaves `!users:example.org`: +they should be removed from the room. One option is to leave the departure up +to Bob's server `server.example`, but this places a relatively high level of trust +in that server. Additionally, if `server.example` were offline, other users in +the room would still see Bob in the room (and their servers would attempt to +send message traffic to it). + +Another consideration is that users may have joined via a direct invite, not via access through a space. + +Fixing this is thorny. Some sort of annotation on the membership events might +help. but it's unclear what the desired semantics are: + +* Assuming that users in a given space are *not* kicked when that space is + removed from `allow`, are those users then given a pass to remain + in the room indefinitely? What happens if the space is added back to + `allow` and *then* the user leaves it? +* Suppose a user joins a room via a space (SpaceA). Later, SpaceB is added to + the `allow` list and SpaceA is removed. What should happen when the + user leaves SpaceB? Are they exempt from the kick? + +### Inheriting join rules + +If you make a parent space invite-only, should that (optionally?) cascade into +child rooms? Seems to have some of the same problems as inheriting power levels, as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). + +## Footnotes + +[1]: The converse restriction, "anybody can join, provided they are not members +of the '#catlovers' space" is less useful since: + +1. Users in the banned space could simply leave it at any time +2. This functionality is already somewhat provided by [Moderation policy lists](https://matrix.org/docs/spec/client_server/r0.6.1#moderation-policy-lists). [↩](#a1) + +[2]: Note that there is nothing stopping users sending and +receiving invites in `public` rooms today, and they work as you might expect. +The only difference is that you are not *required* to hold an invite when +joining the room. [↩](#a2) + +[3]: This is a marginal decrease in security from the current +situation. Currently, a misbehaving server can allow unauthorized users to join +any room by first issuing an invite to that user. In theory that can be +prevented by raising the PL required to send an invite, but in practice that is +rarely done. [↩](#a2) From c81947a39c5332ea36e74eb104013bd166f8f733 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 15 Apr 2021 10:27:08 -0400 Subject: [PATCH 015/162] Document the error response. --- proposals/3083-restricted-rooms.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 1121ebf6a..b8e3198b7 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -44,11 +44,14 @@ following keys, or a string representing the MXID of the user exempted: Any entries in the list which do not match the expected format are ignored. -When a server receives a `/join` request from a client or a `/make_join` / `/send_join` +When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid invite or is in one of the listed spaces (established by peeking if the server is not already in the space, see [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444)). +If the user is not part of the proper space, the homeserver should return an error response +with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. + Unlike the `invite` join rule, confirmation that the `allow` rules were properly checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) From 4fc5acf500c4769b0718072f64bd56a3a88e53de Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Apr 2021 08:44:48 -0400 Subject: [PATCH 016/162] Update a placeholder. --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b8e3198b7..b9945e355 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -90,7 +90,7 @@ The `restricted` join rule will be included in a future room version to ensure that servers and clients opt-into the new functionality. During development it is expected that an unstable room version of -`org.matrix.mscXXXX` is used. Since the room version namespaces the behaviour, +`org.matrix.msc3083` is used. Since the room version namespaces the behaviour, the `allow` key and the `restricted` value do not need unstable prefixes. ## History / Rationale From 13e3f18bc44e664a57061212933b840e5114c4fd Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Apr 2021 08:49:48 -0400 Subject: [PATCH 017/162] Rework bits about peeking. --- proposals/3083-restricted-rooms.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b9945e355..979b19b0d 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -46,8 +46,8 @@ Any entries in the list which do not match the expected format are ignored. When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid -invite or is in one of the listed spaces (established by peeking if the server is not -already in the space, see [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444)). +invite or is in one of the listed spaces. Note that the server may not know if the user +is in a particular space, this is left to a future MSC to solve. If the user is not part of the proper space, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. @@ -81,9 +81,6 @@ The `allow` feature for `join_rules` places increased trust in the servers in th 1. Don't let evil servers in your room in the first place 2. Don't use `allow` lists, given the expansion increases the attack surface anyway by letting members in other rooms dictate who's allowed into your room. -The peek server also has significant power. For example, a poorly chosen peek -server could lie about the space membership and add an `@evil_user:example.org`. - ## Unstable prefix The `restricted` join rule will be included in a future room version to ensure @@ -115,7 +112,15 @@ include, but are not included in this MSC. ### Checking space membership over federation +If a server is not in a space (and thus doesn't know the membership of a space) it +cannot enforce membership of a space during a join. Peeking over federation, +as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), +could be used to establish if the user is in any of the proper spaces. +Note that there are additional security considerations with this, namely that +the peek server has significant power. For example, a poorly chosen peek +server could lie about the space membership and add an `@evil_user:example.org` +to a space to gain membership to a room. ### Kicking users out when they leave the allowed space From 7a3b7b38a5a92c5a67d948b34c69867751fb4b35 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 29 Apr 2021 15:58:31 +0100 Subject: [PATCH 018/162] Add implementations section --- proposals/2778-appservice-login.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index b361b2aec..0de59e27f 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -84,3 +84,12 @@ This can safely be ignored or used, but is an extra token hanging around. Implementations should use `uk.half-shot.msc2778.login.application_service` for `type` given in the `POST /login` until this lands in a released version of the specification. + +## Implementations + +The proposal has been implemented by a homeserver, a bridge SDK and two bridges: + +- [synapse](https://github.com/matrix-org/synapse/pull/8320) +- [mautrix-python](https://github.com/tulir/mautrix-python/commit/12d7c48ca7c15fd3ff61608369af1cf69e289aeb) +- [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp/commit/ead8a869c84d07fadc7cfcf3d522452c99faaa36) +- [matrix-appservice-bridge](https://github.com/matrix-org/matrix-appservice-bridge/pull/231/files#diff-5e93f1b51d50a44fcf0ca46ea1793c1cR851-R864) \ No newline at end of file From c9b7e9f22d44ff1da103e9d2f5698c8f728b67ab Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 29 Apr 2021 15:58:51 +0100 Subject: [PATCH 019/162] Reword need for token --- proposals/2778-appservice-login.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 0de59e27f..52c644759 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -6,8 +6,10 @@ do so, this proposal suggests implementing an appservice extension to the [`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). Appservice users do not usually need to login as they do not need their own access token, and do not -traditionally need a "device". However E2E encryption demands that all users in a room have a device -which means bridge users need to be able to generate a device on demand. +traditionally need a "device". However, E2E encryption demands that at least one user in a room has a Matrix device +which means bridge users need to be able to generate a device on demand. In the past, bridge developers +have used the bridge bot's device for all bridge users in the room, but this causes problems should the bridge +wish to only join ghosts to a room (e.g. for DMs). ## Proposal From 2c817cb1c579aa6d47cab18edf46867669518597 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 29 Apr 2021 15:58:57 +0100 Subject: [PATCH 020/162] Add another advantage --- proposals/2778-appservice-login.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 52c644759..1b7c45a3a 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -11,6 +11,10 @@ which means bridge users need to be able to generate a device on demand. In the have used the bridge bot's device for all bridge users in the room, but this causes problems should the bridge wish to only join ghosts to a room (e.g. for DMs). +Another advantage this provides is that an appservice can now be used to generate access tokens for +any user in it's namespace without having to set a password for that user, which may be useful in the +case of software where maintaining password(s) in the configuration is undesirable. + ## Proposal A new `type` is to be added to `POST /login`. From cb7bbf3787b10ecbde67eb5afb9b773553c4f64e Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 29 Apr 2021 16:00:21 +0100 Subject: [PATCH 021/162] I don't think this is a concern --- proposals/2778-appservice-login.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 1b7c45a3a..c91f81a8e 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -82,9 +82,7 @@ create more work for all parties involved for little benefit. ## Security considerations -The /login endpoint will generate an access token which can be used to control the appservice user, which -is superflous as the appservice `as_token` should be used to authenticate all requests on behalf of ghosts. -This can safely be ignored or used, but is an extra token hanging around. +None ## Unstable prefix From 03491c5cfd8b82295706e1a86648e19741dbff04 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 3 May 2021 17:42:38 +0100 Subject: [PATCH 022/162] Add security considerations --- proposals/2778-appservice-login.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index c91f81a8e..390e05478 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -82,7 +82,28 @@ create more work for all parties involved for little benefit. ## Security considerations -None +Appservices could use this new functionality to generate devices for any userId that are within it's namespace e.g. setting the +user namespace regex to `@.*:example.com` would allow appservice to control anyone on the homeserver. While this sounds scary, in practise +this is not a problem because: + +- Appservice namespaces are mainained by the homeserver admin. If the namespace were to change, then it's reasonable + to assume that the server admin is aware. There is no defense mechanism to stop a malicious server admin from creating new + devices for a given user's account as they could also do so by simply modifying the database. + +- While an appservice *could* try to masquerade as a user maliciously without the server admin expecting it, it would still + be bound by the restrictions of the namespace. Server admins are expected to be aware of the implications of adding new + appservices to their server so the burden of responsibility lies with the server admin. + +- Appservices already can /sync as any user using the `as_token` and send any messages as any user in the namespace, the only + difference is that without a dedicated access token they are unable to receive device messages. While in theory this + does make them unable to see encrypted messages, this is not designed to be a security mechanism. + +- An appservice trying to log in as a user will always create a new device, which means the user would be informed of the + new device on their existing sessions. It should be very obvious if a malicous appservice is creating new devices on your account. + +In conclusion this MSC only automates the creation of new devices for users inside an AS namespace, which is something +a server admin could already do. Appservices should always be treated with care and so with these facts in mind the MSC should +be considered secure. ## Unstable prefix From 36b19fb08366d426fb6112a59587aecbb869ba40 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 12:43:57 -0400 Subject: [PATCH 023/162] Clarify link. --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 979b19b0d..909a15343 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -1,6 +1,6 @@ # Restricting room membership based on space membership -Draft join rule changes for [spaces](https://github.com/matrix-org/matrix-doc/pull/1772), +Draft join rule changes for [MSC1772: spaces](https://github.com/matrix-org/matrix-doc/pull/1772), this is meant to replaces the second half of [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962/). A desirable feature is to give room admins the power to restrict membership of From bf9cc0a5629236135344160af5ed87ab3cf5a247 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 3 May 2021 17:44:26 +0100 Subject: [PATCH 024/162] M_EXCLUSIVE --- proposals/2778-appservice-login.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 390e05478..3f79d8c30 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -47,11 +47,12 @@ If: - The access token is not provided - The access token does not correspond to a appservice -- The access token does not correspond to a appservice that manages this user - Or the user has not previously been registered Then the servers should reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. +If the access token does not correspond to a appservice that manages this user, then the `errcode` should be `"M_EXCLUSIVE"`. + Homeservers should ignore the `access_token` parameter if a type other than `m.login.application_service` has been provided. From 3d913b36f8acf03b598e7056f4bbb3007f85c411 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 12:47:44 -0400 Subject: [PATCH 025/162] Add current proposals. --- proposals/xxxx-stripped-state-events.md | 93 +++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 proposals/xxxx-stripped-state-events.md diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/xxxx-stripped-state-events.md new file mode 100644 index 000000000..002492ba6 --- /dev/null +++ b/proposals/xxxx-stripped-state-events.md @@ -0,0 +1,93 @@ +# MSCXXXX: Exposing stripped state events to any potential joiner + +It is currently possible to inspect the state of rooms in some circumstances: + +* If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). +* Rooms in the room directory expose some of their state publicly. +* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. + +This MSC proposes exposing 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 states events are available to potential joiners. + +## Background + +When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) to include stripped state events which are useful for displaying the invite to a user: + +> An optional list of simplified events to help the receiver of the invite identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. + +The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) as part of the `/sync` response: + +> The state of a room that the user has been invited to. 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. + +These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) containing the invite. + +[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) extends this concept to also include the stripped state events in the `/sync` response for knocking users: + +> It is proposed to add a fourth possible key to rooms, called `knock`. Its value is a mapping from room ID to room information. The room information is a mapping from a key `knock_state` to another mapping with key events being a list of `StrippedStateEvent`. + +It is also provides an extended rationale of why this is useful: + +> These stripped state events contain information about the room, most notably the room's name and avatar. A client will need this information to show a nice representation of pending knocked rooms. The recommended events to include are the join rules, canonical alias, avatar, name and encryption state of the room, rather than all room state. This behaviour matches the information sent to remote homeservers when remote users are invited to a room. + +[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: + +> Join rules, invites and 3PID invites work as for a normal room, with the exception that `invite_state` sent along with invites should be amended to include the `m.room.create` event, to allow clients to discern whether an invite is to a space-room or not. + +## Proposal + +Any user who is able to join a room can access the stripped state events of that room. + +Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: + +* A room that has `join_rules` set to `public` or `knock`.[1](#f1) +* 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: + +* [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)). + +Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: + +* Create event (`m.room.create`)[2](#f2) +* Join rules (`m.room.join_rules`) +* Canonical alias (`m.room.canonical_alias`) +* Room avatar (`m.room.avatar`) +* Room name (`m.room.name`) +* Encrypted status (`m.room.encryption`)[3](#f3) + +This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. + +## Potential issues + +This is a generalization of current behavior and shouldn't introduce any 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. + +## Security considerations + +The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) does not know the user who is requesting a summary of the space, but should divulge the above information if any member of a server could see it. It is up to the calling server to properly filter this information. + +Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice or Bob (and hence whether it should share details of private rooms within that space). + +Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. + +(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) + +This does not decrease security since a server could lie and make a request on behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. + +## Future extensions + +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. + +## Unstable prefix + +N/A + +## Footnotes + +[1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) + +[2]: As suggested in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) + +[3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) From e781b75847c0651336da60e17a99f0bbfdb606e5 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 3 May 2021 18:09:27 +0100 Subject: [PATCH 026/162] Mention that /register provides a token but it's not helpful --- proposals/2778-appservice-login.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 3f79d8c30..567f84119 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -81,6 +81,12 @@ A third option could be to create a new endpoint that simply creates a new devic Given the rest of the matrix eco-system does this with /login, and /login is already extensible with `type`, it would create more work for all parties involved for little benefit. +Finally, `POST /register` does already return a `device_id`, `access_token` for appservice users by default. However critically +this means that bridges will need to be designed to store the access_token and device_id from the point of creating the user, +so older bridges would be unable to get an access token for existing users as `POST /register` would fail. +It would difficult to log out these tokens if they got exposed additionally, as the AS would not be able to fetch a new access token. +Furthermore, the ability to generate access tokens for real users who registered elsewhere would not be possible with this mechanism. + ## Security considerations Appservices could use this new functionality to generate devices for any userId that are within it's namespace e.g. setting the From ce8650837be3a5499383468f749b58139297f218 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:35:29 -0400 Subject: [PATCH 027/162] Wording. --- proposals/xxxx-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/xxxx-stripped-state-events.md index 002492ba6..c2408f080 100644 --- a/proposals/xxxx-stripped-state-events.md +++ b/proposals/xxxx-stripped-state-events.md @@ -88,6 +88,6 @@ N/A [1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) -[2]: As suggested in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) +[2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) [3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) From b6cba644591edbb7aa5b7496fdb7379a1d553b55 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:37:04 -0400 Subject: [PATCH 028/162] Update MSC number. --- ...ped-state-events.md => 3173-expose-stripped-state-events.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-stripped-state-events.md => 3173-expose-stripped-state-events.md} (99%) diff --git a/proposals/xxxx-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md similarity index 99% rename from proposals/xxxx-stripped-state-events.md rename to proposals/3173-expose-stripped-state-events.md index c2408f080..f2b04096e 100644 --- a/proposals/xxxx-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,4 +1,4 @@ -# MSCXXXX: Exposing stripped state events to any potential joiner +# MSC3173: Expose stripped state events to any potential joiner It is currently possible to inspect the state of rooms in some circumstances: From 1cfbf7620af6bc2a155f2326d74f1ce3c096a9c0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 3 May 2021 13:49:17 -0400 Subject: [PATCH 029/162] Wrapping. --- .../3173-expose-stripped-state-events.md | 98 ++++++++++++++----- 1 file changed, 74 insertions(+), 24 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index f2b04096e..8439519b8 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -6,46 +6,74 @@ It is currently possible to inspect the state of rooms in some circumstances: * Rooms in the room directory expose some of their state publicly. * [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. -This MSC proposes exposing 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 states events are available to potential joiners. +This MSC proposes exposing 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 states events are available to +potential joiners. ## Background -When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) to include stripped state events which are useful for displaying the invite to a user: +When creating an invite it is [currently recommended](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) +to include stripped state events which are useful for displaying the invite to a user: -> An optional list of simplified events to help the receiver of the invite identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. +> An optional list of simplified events to help the receiver of the invite identify +> the room. The recommended events to include are the join rules, canonical alias, +> avatar, and name of the room. -The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) as part of the `/sync` response: +The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) +as part of the `/sync` response: -> The state of a room that the user has been invited to. 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. +> The state of a room that the user has been invited to. 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. -These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) containing the invite. +These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) +containing the invite. -[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) extends this concept to also include the stripped state events in the `/sync` response for knocking users: +[MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) +extends this concept to also include the stripped state events in the `/sync` response +for knocking users: -> It is proposed to add a fourth possible key to rooms, called `knock`. Its value is a mapping from room ID to room information. The room information is a mapping from a key `knock_state` to another mapping with key events being a list of `StrippedStateEvent`. +> It is proposed to add a fourth possible key to rooms, called `knock`. Its value +> is a mapping from room ID to room information. The room information is a mapping +> from a key `knock_state` to another mapping with key events being a list of +> `StrippedStateEvent`. It is also provides an extended rationale of why this is useful: -> These stripped state events contain information about the room, most notably the room's name and avatar. A client will need this information to show a nice representation of pending knocked rooms. The recommended events to include are the join rules, canonical alias, avatar, name and encryption state of the room, rather than all room state. This behaviour matches the information sent to remote homeservers when remote users are invited to a room. +> These stripped state events contain information about the room, most notably the +> room's name and avatar. A client will need this information to show a nice +> representation of pending knocked rooms. The recommended events to include are the +> join rules, canonical alias, avatar, name and encryption state of the room, rather +> than all room state. This behaviour matches the information sent to remote +> homeservers when remote users are invited to a room. -[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: +[MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally +recommends including the `m.room.create` event as one of the stripped state events: -> Join rules, invites and 3PID invites work as for a normal room, with the exception that `invite_state` sent along with invites should be amended to include the `m.room.create` event, to allow clients to discern whether an invite is to a space-room or not. +> Join rules, invites and 3PID invites work as for a normal room, with the exception +> that `invite_state` sent along with invites should be amended to include the +> `m.room.create` event, to allow clients to discern whether an invite is to a +> space-room or not. ## Proposal Any user who is able to join a room can access the stripped state events of that room. -Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: +Potential ways that a user might be able to join include, but are not limited to, +the following mechanisms: * A room that has `join_rules` set to `public` or `knock`.[1](#f1) * 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: +Future MSCs might include additional mechanism for a user to join a room and +should consider this MSC, for example: * [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)). -Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: +Additionally, it is recommended, but not required, that homeserver implementations +include the following as stripped state events: * Create event (`m.room.create`)[2](#f2) * Join rules (`m.room.join_rules`) @@ -54,7 +82,10 @@ Additionally, it is recommended, but not required, that homeserver implementatio * Room name (`m.room.name`) * Encrypted status (`m.room.encryption`)[3](#f3) -This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. +This also implies that the above information is available to any potential joiner +in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). +I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) +can expose the information available in stripped state events. ## Potential issues @@ -62,23 +93,40 @@ This is a generalization of current behavior and shouldn't introduce any new iss ## 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 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. ## Security considerations -The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) does not know the user who is requesting a summary of the space, but should divulge the above information if any member of a server could see it. It is up to the calling server to properly filter this information. +The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +does not know the user who is requesting a summary of the space, but should divulge +the above information if any member of a server could see it. It is up to the +calling server to properly filter this information. -Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice or Bob (and hence whether it should share details of private rooms within that space). +Consider that Alice and Bob share a server; Alice is a member of a space, but Bob +is not. The remote server will not know whether the request is on behalf of Alice +or Bob (and hence whether it should share details of private rooms within that +space). -Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. +Trust is placed in the calling server: if there are any users on the calling +server in the correct space, that calling server has a right to know about the +rooms in that space and should return the relevant summaries, along with enough +information that the calling server can then do some filtering. -(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) +(The alternative, where the calling server sends the requesting `user_id`, and +the target server does the filtering, is unattractive because it rules out a +future world where the calling server can cache the result.) -This does not decrease security since a server could lie and make a request on behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. +This does not decrease security since a server could lie and make a request on +behalf of a user in the proper space to see the given information. I.e. the +calling server must be trusted anyway. ## Future extensions -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. +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. ## Unstable prefix @@ -86,8 +134,10 @@ N/A ## Footnotes -[1]: The rationale for including `knock` is that the user can trivially get this state already by knocking on the room.[↩](#a1) +[1]: The rationale for including `knock` is that the user can +trivially get this state already by knocking on the room.[↩](#a1) [2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) -[3]: This is already sent from Synapse and generally seems useful for a user to know before joining a room.[↩](#a3) +[3]: This is already sent from Synapse and generally seems useful for +a user to know before joining a room.[↩](#a3) From 69381cc6a4e653646cc4f93340f3c4660271237b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 4 May 2021 09:34:41 -0600 Subject: [PATCH 030/162] Case fold instead of lowercase Fixes https://github.com/matrix-org/matrix-doc/issues/3175 --- content/appendices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/appendices.md b/content/appendices.md index 9132dd6d2..38bf6397d 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -773,7 +773,7 @@ Represents E-Mail addresses. The `address` is the raw email address in other text such as real name, angle brackets or a mailto: prefix. In addition to lowercasing the domain component of an email address, -implementations are expected to lowercase the localpart as described +implementations are expected to case fold the localpart as described in [the unicode mapping file](https://www.unicode.org/Public/8.0.0/ucd/CaseFolding.txt) prior to any processing. For example, `Strauß@Example.com` must be considered to be `strauss@example.com` while processing the email From 51e602bf3b7b3e53bacef2c250725bef9a8a19be Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 4 May 2021 09:35:54 -0600 Subject: [PATCH 031/162] Changelogs --- changelogs/identity_service/newsfragments/3167.clarification | 2 +- changelogs/identity_service/newsfragments/3176.clarification | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/identity_service/newsfragments/3176.clarification diff --git a/changelogs/identity_service/newsfragments/3167.clarification b/changelogs/identity_service/newsfragments/3167.clarification index cc70fd710..9f68bbf2f 100644 --- a/changelogs/identity_service/newsfragments/3167.clarification +++ b/changelogs/identity_service/newsfragments/3167.clarification @@ -1 +1 @@ -Clarify that some identifiers may be lowercase prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file +Clarify that some identifiers may be case-folded to lowercase prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file diff --git a/changelogs/identity_service/newsfragments/3176.clarification b/changelogs/identity_service/newsfragments/3176.clarification new file mode 100644 index 000000000..9f68bbf2f --- /dev/null +++ b/changelogs/identity_service/newsfragments/3176.clarification @@ -0,0 +1 @@ +Clarify that some identifiers may be case-folded to lowercase prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file From 4ca319db0942dea353d3cda73fdea483bcaa801d Mon Sep 17 00:00:00 2001 From: Christian Paul Date: Wed, 5 May 2021 17:04:25 +0200 Subject: [PATCH 032/162] Update proposals/2778-appservice-login.md --- proposals/2778-appservice-login.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 567f84119..da93f32e0 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -12,7 +12,7 @@ have used the bridge bot's device for all bridge users in the room, but this cau wish to only join ghosts to a room (e.g. for DMs). Another advantage this provides is that an appservice can now be used to generate access tokens for -any user in it's namespace without having to set a password for that user, which may be useful in the +any user in its namespace without having to set a password for that user, which may be useful in the case of software where maintaining password(s) in the configuration is undesirable. ## Proposal @@ -124,4 +124,4 @@ The proposal has been implemented by a homeserver, a bridge SDK and two bridges: - [synapse](https://github.com/matrix-org/synapse/pull/8320) - [mautrix-python](https://github.com/tulir/mautrix-python/commit/12d7c48ca7c15fd3ff61608369af1cf69e289aeb) - [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp/commit/ead8a869c84d07fadc7cfcf3d522452c99faaa36) -- [matrix-appservice-bridge](https://github.com/matrix-org/matrix-appservice-bridge/pull/231/files#diff-5e93f1b51d50a44fcf0ca46ea1793c1cR851-R864) \ No newline at end of file +- [matrix-appservice-bridge](https://github.com/matrix-org/matrix-appservice-bridge/pull/231/files#diff-5e93f1b51d50a44fcf0ca46ea1793c1cR851-R864) From 0c26298b938961219391322c47b05f6d68198422 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 May 2021 18:27:07 +0100 Subject: [PATCH 033/162] Update proposals/2778-appservice-login.md Co-authored-by: Christian Paul --- proposals/2778-appservice-login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index da93f32e0..8e38c4a99 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -63,7 +63,7 @@ then `/login` to generate the appropriate device. This proposal means that there will be more calls to make when setting up a appservice user, when using encryption. While this could be done during the registration step, this would prohibit creating -new devices should the appservice intentionally or inadvertently lost the client-side device data. +new devices should the appservice intentionally or inadvertently have lost the client-side device data. ## Alternatives From 538ac0940eab651e8d4e81d8de7bcff0634e5e2a Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 May 2021 18:45:33 +0100 Subject: [PATCH 034/162] Update Alternatives section --- proposals/2778-appservice-login.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 8e38c4a99..e4583c00d 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -67,21 +67,41 @@ new devices should the appservice intentionally or inadvertently have lost the c ## Alternatives +### 1. Include the token in the `/login` request body + One minor tweak to the current proposal could be to include the token as part of the auth data, rather than being part of the header/params to the request. An argument could be made for either, but since the specification expects the appservice to pass the token this way in all requests, including `/register`, it seems wise to keep it that way. -Some community members have used implementation details such as a "shared secret" authentication method to +### 2. Use implementation specific "shared secret" authentication + +Some community members have used homeserver implementation details such as a "shared secret" authentication method to log into the accounts without having to use the /login process at all. Synapse provides such a function, -but also means the appservice can now authenticate as any user on the homeserver. This seems undesirable from a +but also means the appservice can now authenticate as any user on the homeserver. This is undesirable from a security standpoint. +### 3. Keep using `/register` solely + A third option could be to create a new endpoint that simply creates a new device for an appservice user on demand. Given the rest of the matrix eco-system does this with /login, and /login is already extensible with `type`, it would create more work for all parties involved for little benefit. -Finally, `POST /register` does already return a `device_id`, `access_token` for appservice users by default. However critically +Finally, `POST /register` does already return a `device_id` and `access_token` so appservices +could store this information rather than calling `POST /login` at all. This does however present a few problems: + +- Quite a few appservices which only support unencrypted messaging do not use/store the `device_id`/`access_token` from a register call. + In the event that an appservice eventually gains the ability to support encryption, they would be unable to fetch a new `device_id`/ + `access_token` for any existing users (as `/register` would fail for an existing user). +- If user tokens were lost or exposed, there is no way to programattically create new access tokens for these users. +- Finally, if a user was registered externally and the appservice would like to masquerade as it, it would be unable to fetch + an access token for that user. + +While `POST /register` does work, it is impactical as the sole method of fetching an access token. + + +Most appservices +which do not implement encryption do not store this information as neither the device_id or access_token are needed f However critically this means that bridges will need to be designed to store the access_token and device_id from the point of creating the user, so older bridges would be unable to get an access token for existing users as `POST /register` would fail. It would difficult to log out these tokens if they got exposed additionally, as the AS would not be able to fetch a new access token. From b8ab3d0c87e4ef07eed3f9d8de0ae9636b566d86 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 May 2021 23:03:15 +0100 Subject: [PATCH 035/162] Remove point about Element showing unexpected devices --- proposals/2778-appservice-login.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index e4583c00d..ce0828029 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -125,9 +125,6 @@ this is not a problem because: difference is that without a dedicated access token they are unable to receive device messages. While in theory this does make them unable to see encrypted messages, this is not designed to be a security mechanism. -- An appservice trying to log in as a user will always create a new device, which means the user would be informed of the - new device on their existing sessions. It should be very obvious if a malicous appservice is creating new devices on your account. - In conclusion this MSC only automates the creation of new devices for users inside an AS namespace, which is something a server admin could already do. Appservices should always be treated with care and so with these facts in mind the MSC should be considered secure. From c8e0ed60624d3ec1cbbd39c73810dbcb54c56b11 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 May 2021 23:10:00 +0100 Subject: [PATCH 036/162] Hopefully improve words around M_EXCLUSIVE --- proposals/2778-appservice-login.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index ce0828029..1fac4e171 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -17,9 +17,7 @@ case of software where maintaining password(s) in the configuration is undesirab ## Proposal -A new `type` is to be added to `POST /login`. - -`m.login.application_service` +A new `type` is to be added to `POST /login`: `m.login.application_service` The `/login` endpoint may now take an `access_token` in the same way that other authenticated endpoints do. No additional parameters should be specified in the request body. @@ -43,15 +41,16 @@ new flows. The response body should be unchanged from the existing `/login` specification. -If: +If one of the following conditions are true: - The access token is not provided - The access token does not correspond to a appservice - Or the user has not previously been registered -Then the servers should reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. +Then the servers MUST reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. -If the access token does not correspond to a appservice that manages this user, then the `errcode` should be `"M_EXCLUSIVE"`. +If the access token DOES correspond to a appservice but the user is not inside it's namespace, +then the `errcode` should be `"M_EXCLUSIVE"`. Homeservers should ignore the `access_token` parameter if a type other than `m.login.application_service` has been provided. From 93dd264c307875dc4f377591ef7427e59374ade5 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 May 2021 23:14:48 +0100 Subject: [PATCH 037/162] words --- proposals/2778-appservice-login.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 1fac4e171..5ec933507 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -6,14 +6,14 @@ do so, this proposal suggests implementing an appservice extension to the [`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). Appservice users do not usually need to login as they do not need their own access token, and do not -traditionally need a "device". However, E2E encryption demands that at least one user in a room has a Matrix device -which means bridge users need to be able to generate a device on demand. In the past, bridge developers -have used the bridge bot's device for all bridge users in the room, but this causes problems should the bridge -wish to only join ghosts to a room (e.g. for DMs). +traditionally need a "device". However, E2E encryption demands that at least one user in a room has a +Matrix device which means bridge users need to be able to generate a device on demand. In the past, +bridge developers have used the bridge bot's device for all bridge users in the room, but this causes +problems should the bridge wish to only join ghosts to a room (e.g. for DMs). Another advantage this provides is that an appservice can now be used to generate access tokens for -any user in its namespace without having to set a password for that user, which may be useful in the -case of software where maintaining password(s) in the configuration is undesirable. +any user in its namespace without having to set a password for that user, which may be useful where +maintaining password(s) in the configuration is undesirable. ## Proposal From 16290a0fe5f528a8ca8ce138aefb66e4063aa9a8 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 6 May 2021 11:12:39 +0100 Subject: [PATCH 038/162] it's --- proposals/2778-appservice-login.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 5ec933507..5b9e0a48a 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -49,7 +49,7 @@ If one of the following conditions are true: Then the servers MUST reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. -If the access token DOES correspond to a appservice but the user is not inside it's namespace, +If the access token DOES correspond to a appservice but the user is not inside its namespace, then the `errcode` should be `"M_EXCLUSIVE"`. Homeservers should ignore the `access_token` parameter if a type other than @@ -108,7 +108,7 @@ Furthermore, the ability to generate access tokens for real users who registered ## Security considerations -Appservices could use this new functionality to generate devices for any userId that are within it's namespace e.g. setting the +Appservices could use this new functionality to generate devices for any userId that are within its namespace e.g. setting the user namespace regex to `@.*:example.com` would allow appservice to control anyone on the homeserver. While this sounds scary, in practise this is not a problem because: From 45bcd86dcb2718ff311dd37c25f7bf5ad9bdd9c1 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 08:56:38 -0400 Subject: [PATCH 039/162] Strip whitespace. --- .../3173-expose-stripped-state-events.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 8439519b8..0a6609269 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -43,7 +43,7 @@ for knocking users: It is also provides an extended rationale of why this is useful: > These stripped state events contain information about the room, most notably the -> room's name and avatar. A client will need this information to show a nice +> room's name and avatar. A client will need this information to show a nice > representation of pending knocked rooms. The recommended events to include are the > join rules, canonical alias, avatar, name and encryption state of the room, rather > than all room state. This behaviour matches the information sent to remote @@ -52,9 +52,9 @@ It is also provides an extended rationale of why this is useful: [MSC1772: Spaces](https://github.com/matrix-org/matrix-doc/pull/1772) additionally recommends including the `m.room.create` event as one of the stripped state events: -> Join rules, invites and 3PID invites work as for a normal room, with the exception +> Join rules, invites and 3PID invites work as for a normal room, with the exception > that `invite_state` sent along with invites should be amended to include the -> `m.room.create` event, to allow clients to discern whether an invite is to a +> `m.room.create` event, to allow clients to discern whether an invite is to a > space-room or not. ## Proposal @@ -67,7 +67,7 @@ the following mechanisms: * A room that has `join_rules` set to `public` or `knock`.[1](#f1) * 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 +Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: * [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)). @@ -82,8 +82,8 @@ include the following as stripped state events: * Room name (`m.room.name`) * Encrypted status (`m.room.encryption`)[3](#f3) -This also implies that the above information is available to any potential joiner -in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). +This also implies that the above information is available to any potential joiner +in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. @@ -106,20 +106,20 @@ calling server to properly filter this information. Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of private rooms within that +or Bob (and hence whether it should share details of private rooms within that space). Trust is placed in the calling server: if there are any users on the calling server in the correct space, that calling server has a right to know about the -rooms in that space and should return the relevant summaries, along with enough +rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering. -(The alternative, where the calling server sends the requesting `user_id`, and +(The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) -This does not decrease security since a server could lie and make a request on -behalf of a user in the proper space to see the given information. I.e. the +This does not decrease security since a server could lie and make a request on +behalf of a user in the proper space to see the given information. I.e. the calling server must be trusted anyway. ## Future extensions From 2919e5752530f71981a5424a1abfe82a295874b6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:05:15 -0400 Subject: [PATCH 040/162] Update dependencies to include MSC3173. --- proposals/3083-restricted-rooms.md | 67 ++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 9 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 909a15343..f7846aed1 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -1,16 +1,17 @@ # Restricting room membership based on space membership -Draft join rule changes for [MSC1772: spaces](https://github.com/matrix-org/matrix-doc/pull/1772), -this is meant to replaces the second half of [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962/). - A desirable feature is to give room admins the power to restrict membership of -their room based on the membership of one or more spaces, for example: +their room based on the membership of one or more spaces from +[MSC1772: spaces](https://github.com/matrix-org/matrix-doc/pull/1772), +for example: > members of the #doglovers space can join this room without an invitation[1](#f1) -We could represent the allowed spaces with a new `join_rule` - `restricted` - to -reflect the fact that what we have is a cross between `invite` and `public`. This -would have additional content of the rooms to trust for membership. For example: +## Proposal + +A new `join_rule` (`restricted`) will be used to reflect a cross between `invite` +and `public` join rules. The content of the join rules would include the rooms +to trust for membership. For example: ```json { @@ -57,6 +58,51 @@ checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) However, user IDs listed as strings can be properly checked over federation. +### Discovery of restricted rooms + +The discovery of rooms in a space, as discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946): spaces summary, +must be updated to allow for discovery of restricted rooms. + +MSC2946 defines that a room should be included in the spaces summary if it is +accessible (world-readable or if the user is already in the room). [MSC3173](https://github.com/matrix-org/matrix-doc/pull/3173) +declares that if a user can view the stripped state of a room if they are *able* +to join the room. Combining these two MSCs, the spaces summary should include +rooms with restricted join rule which a user is able to join (i.e. they're a +member of one of the spaces declared in the join rule). + +The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +does not know the user who is requesting a summary of the space, but should divulge +the above information if any member of a server could see it. It is up to the +calling server to properly filter this information. + +Trust is placed in the calling server: if there are any users on the calling +server in the correct space, that calling server has a right to know about the +rooms in that space and should return the relevant summaries, along with enough +information that the calling server can then do some filtering, thus an +additional field is added to the server-server response of the spaces summary: + +*TODO* + +Consider that Alice and Bob share a server; Alice is a member of a space, but Bob +is not. The remote server will not know whether the request is on behalf of Alice +or Bob (and hence whether it should share details of restricted rooms within that +space). + +Consider the above with a restricted room on a different server which defers +access to the above space. When summarizing the space, the homeserver must make +a request over federation for information on the room. The response would include +the room (since Alice is able to join it), but the calling server does not know +*why* they received the room, without additional information the server cannot +properly filter the returned results. + +(The alternative, where the calling server sends the requesting `user_id`, and +the target server does the filtering, is unattractive because it rules out a +future world where the calling server can cache the result.) + +This does not decrease security since a server could lie and make a request on +behalf of a user in the proper space to see the given information. I.e. the +calling server must be trusted anyway. + ## Summary of the behaviour of join rules See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) @@ -67,7 +113,7 @@ between `public`, `invite`, and `restricted`. * `invite`: only people with membership `invite` can join, as today. * `knock`: the same as `invite`, except anyone can knock, subject to `ban` and `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). -* `private`: This is reserved and not implemented. +* `private`: This is reserved and not implemented. * `restricted`: the same as `public` from the perspective of the auth rules, but with the additional caveat that servers are expected to check the `allow` rules before generating a `join` event (whether for a local or a remote user). @@ -92,8 +138,11 @@ the `allow` key and the `restricted` value do not need unstable prefixes. ## History / Rationale +Note that this replaces the second half of an older version of +[MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). + It may seem that just having the `allow` key with `public` join rules is enough, -as suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962/), +as suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962), but there are concerns that having a `public` join rule that is restricted may cause issues if an implementation does not understand the semantics of the `allow` keyword. Using an `allow` key with `invite` join rules also does not make sense as From 62e94c5fe4293550201fb730cf4c574bc7b3a40c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:14:02 -0400 Subject: [PATCH 041/162] Remove security considerations (moved to MSC3083). --- .../3173-expose-stripped-state-events.md | 25 +------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 0a6609269..e35e0816e 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -84,7 +84,7 @@ include the following as stripped state events: This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). -I.e. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) +E.g. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) can expose the information available in stripped state events. ## Potential issues @@ -99,29 +99,6 @@ knocking. ## Security considerations -The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) -does not know the user who is requesting a summary of the space, but should divulge -the above information if any member of a server could see it. It is up to the -calling server to properly filter this information. - -Consider that Alice and Bob share a server; Alice is a member of a space, but Bob -is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of private rooms within that -space). - -Trust is placed in the calling server: if there are any users on the calling -server in the correct space, that calling server has a right to know about the -rooms in that space and should return the relevant summaries, along with enough -information that the calling server can then do some filtering. - -(The alternative, where the calling server sends the requesting `user_id`, and -the target server does the filtering, is unattractive because it rules out a -future world where the calling server can cache the result.) - -This does not decrease security since a server could lie and make a request on -behalf of a user in the proper space to see the given information. I.e. the -calling server must be trusted anyway. - ## Future extensions Dedicated client-server and server-server APIs could be added to request the From 84331fc3b6527602e7c34777f6bbd419f4337f79 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:30:40 -0400 Subject: [PATCH 042/162] Re-arrange security impact of knocking. --- .../3173-expose-stripped-state-events.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index e35e0816e..5087b4b8c 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -64,7 +64,7 @@ Any user who is able to join a room can access the stripped state events of that Potential ways that a user might be able to join include, but are not limited to, the following mechanisms: -* A room that has `join_rules` set to `public` or `knock`.[1](#f1) +* 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 @@ -75,12 +75,12 @@ should consider this MSC, for example: Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: -* Create event (`m.room.create`)[2](#f2) +* Create event (`m.room.create`)[2](#f1) * Join rules (`m.room.join_rules`) * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encrypted status (`m.room.encryption`)[3](#f3) +* Encrypted status (`m.room.encryption`)[3](#f2) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). @@ -99,6 +99,11 @@ knocking. ## Security considerations +This would allow for invisibly accessing the stripped state of a room with `knock` +join rules. This is already trivially accessible by knocking on the room, but +currently users in the room would know that the knock occurred. This does not +seem to be a major weakening of the security. + ## Future extensions Dedicated client-server and server-server APIs could be added to request the @@ -111,10 +116,7 @@ N/A ## Footnotes -[1]: The rationale for including `knock` is that the user can -trivially get this state already by knocking on the room.[↩](#a1) - -[2]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a2) +[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a1) -[3]: This is already sent from Synapse and generally seems useful for -a user to know before joining a room.[↩](#a3) +[2]: This is already sent from Synapse and generally seems useful for +a user to know before joining a room.[↩](#a2) From fab5eaa67bdf40dcc5cac03dab773909d55db34e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 10:58:35 -0400 Subject: [PATCH 043/162] Add notes from @madlittlemods. --- proposals/3083-restricted-rooms.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index f7846aed1..d6f4ee33b 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -174,13 +174,21 @@ to a space to gain membership to a room. ### Kicking users out when they leave the allowed space In the above example, suppose `@bob:server.example` leaves `!users:example.org`: -they should be removed from the room. One option is to leave the departure up -to Bob's server `server.example`, but this places a relatively high level of trust -in that server. Additionally, if `server.example` were offline, other users in -the room would still see Bob in the room (and their servers would attempt to -send message traffic to it). +should they be removed from the room? Likely not, by analogy with what happens +when you switch the join rules from public to invite. Join rules currently govern +joins, not existing room membership. -Another consideration is that users may have joined via a direct invite, not via access through a space. +It is left to a future MSC to consider this, but some potential thoughts are +given below. + +If you assume that a user *should* be removed in this case, one option is to +leave the departure up to Bob's server `server.example`, but this places a +relatively high level of trust in that server. Additionally, if `server.example` +were offline, other users in the room would still see Bob in the room (and their +servers would attempt to send message traffic to it). + +Another consideration is that users may have joined via a direct invite, not via +access through a space. Fixing this is thorny. Some sort of annotation on the membership events might help. but it's unclear what the desired semantics are: @@ -193,6 +201,9 @@ help. but it's unclear what the desired semantics are: the `allow` list and SpaceA is removed. What should happen when the user leaves SpaceB? Are they exempt from the kick? +It is possible that completely different state should be kept, or a different +`m.room.member` state could be used in a more reasonable way to track this. + ### Inheriting join rules If you make a parent space invite-only, should that (optionally?) cascade into From 5afe23a1c0033ee514c780e6ab87469eb218e400 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 11:16:27 -0400 Subject: [PATCH 044/162] More wrapping. --- proposals/3083-restricted-rooms.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index d6f4ee33b..daa08e69e 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -34,10 +34,11 @@ to trust for membership. For example: ``` This means that a user must be a member of the `!mods:example.org` space or -`!users:example.org` space in order to join without an invite[2](#f2). Membership in -a single space is enough. +`!users:example.org` space in order to join without an invite[2](#f2). +Membership in a single space is enough. -If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the +If the `allow` key is an empty list (or not a list at all), then no users are +allowed to join without an invite. Each entry is expected to be an object with the following keys, or a string representing the MXID of the user exempted: * `space`: The room ID of the space to check the membership of. @@ -50,8 +51,8 @@ request from a server, the request should only be permitted if the user has a va invite or is in one of the listed spaces. Note that the server may not know if the user is in a particular space, this is left to a future MSC to solve. -If the user is not part of the proper space, the homeserver should return an error response -with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +If the user is not part of the proper space, the homeserver should return an error +response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Unlike the `invite` join rule, confirmation that the `allow` rules were properly checked cannot be enforced over federation by event authorization, so servers in @@ -60,7 +61,8 @@ However, user IDs listed as strings can be properly checked over federation. ### Discovery of restricted rooms -The discovery of rooms in a space, as discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946): spaces summary, +The discovery of rooms in a space, as discussed in +[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946): spaces summary, must be updated to allow for discovery of restricted rooms. MSC2946 defines that a room should be included in the spaces summary if it is @@ -125,7 +127,8 @@ The `allow` feature for `join_rules` places increased trust in the servers in th joining spurious users into your rooms, then: 1. Don't let evil servers in your room in the first place -2. Don't use `allow` lists, given the expansion increases the attack surface anyway by letting members in other rooms dictate who's allowed into your room. +2. Don't use `allow` lists, given the expansion increases the attack surface anyway + by letting members in other rooms dictate who's allowed into your room. ## Unstable prefix @@ -207,7 +210,8 @@ It is possible that completely different state should be kept, or a different ### Inheriting join rules If you make a parent space invite-only, should that (optionally?) cascade into -child rooms? Seems to have some of the same problems as inheriting power levels, as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). +child rooms? Seems to have some of the same problems as inheriting power levels, +as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). ## Footnotes From f9a5b34099e29f1f22c74b8a7266f5c9da162479 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 12 May 2021 18:41:56 +0100 Subject: [PATCH 045/162] Clarify /register / /login --- proposals/2778-appservice-login.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 5b9e0a48a..43c024aab 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -55,8 +55,8 @@ then the `errcode` should be `"M_EXCLUSIVE"`. Homeservers should ignore the `access_token` parameter if a type other than `m.login.application_service` has been provided. -The expected flow for appservices would be to `/register` their users, and -then `/login` to generate the appropriate device. +Appservices creating **new** users can still use the `/register` endpoint to generate an `access_token` / `device_id` +but for existing users, the `/login` endpoint can be used instead. ## Potential issues From 590b7a48e7e7f531b28083a8043e714cac15f846 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 12 May 2021 14:36:32 -0400 Subject: [PATCH 046/162] Fill in the TODO about what how to mark access via spaces for the summary API. --- proposals/3083-restricted-rooms.md | 36 +++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index daa08e69e..71a0cd6be 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -83,7 +83,41 @@ rooms in that space and should return the relevant summaries, along with enough information that the calling server can then do some filtering, thus an additional field is added to the server-server response of the spaces summary: -*TODO* +* `allowed_spaces`: A list of space IDs which give access to this room. + +This would modify the example response given to: + +```jsonc +{ + "rooms": [ + { + "room_id": "!ol19s:bleecker.street", + "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "topic": "Tasty tasty cheese", + "world_readable": true, + "room_type": "m.space", + "allowed_spaces": ["!mods:example.org", "!users:example.org"] + }, + { ... } + ], + "events": [ + { + "type": "m.space.child", + "state_key": "!efgh:example.com", + "content": { + "via": ["example.com"], + "suggested": true + }, + "room_id": "!ol19s:bleecker.street", + "sender": "@alice:bleecker.street" + }, + { ... } + ] +} +``` Consider that Alice and Bob share a server; Alice is a member of a space, but Bob is not. The remote server will not know whether the request is on behalf of Alice From cbc4515a9463b82f48667324db95a76d09935c6f Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 13 May 2021 08:37:09 -0400 Subject: [PATCH 047/162] Spacing. --- proposals/3083-restricted-rooms.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 71a0cd6be..a3e5bd2eb 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -9,7 +9,7 @@ for example: ## Proposal -A new `join_rule` (`restricted`) will be used to reflect a cross between `invite` +A new `join_rule` (`restricted`) will be used to reflect a cross between `invite` and `public` join rules. The content of the join rules would include the rooms to trust for membership. For example: @@ -35,7 +35,7 @@ to trust for membership. For example: This means that a user must be a member of the `!mods:example.org` space or `!users:example.org` space in order to join without an invite[2](#f2). -Membership in a single space is enough. +Membership in a single space is enough. If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the @@ -52,9 +52,9 @@ invite or is in one of the listed spaces. Note that the server may not know if t is in a particular space, this is left to a future MSC to solve. If the user is not part of the proper space, the homeserver should return an error -response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. -Unlike the `invite` join rule, confirmation that the `allow` rules were properly +Unlike the `invite` join rule, confirmation that the `allow` rules were properly checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) However, user IDs listed as strings can be properly checked over federation. @@ -120,8 +120,8 @@ This would modify the example response given to: ``` Consider that Alice and Bob share a server; Alice is a member of a space, but Bob -is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of restricted rooms within that +is not. The remote server will not know whether the request is on behalf of Alice +or Bob (and hence whether it should share details of restricted rooms within that space). Consider the above with a restricted room on a different server which defers @@ -157,8 +157,8 @@ between `public`, `invite`, and `restricted`. ## Security considerations The `allow` feature for `join_rules` places increased trust in the servers in the - room. We consider this acceptable: if you don't want evil servers randomly - joining spurious users into your rooms, then: +room. We consider this acceptable: if you don't want evil servers randomly +joining spurious users into your rooms, then: 1. Don't let evil servers in your room in the first place 2. Don't use `allow` lists, given the expansion increases the attack surface anyway @@ -193,8 +193,8 @@ to just introduce a a new join rule - `restricted` - as described above. ## Future extensions -Potential future extensions which should not be designed out -include, but are not included in this MSC. +Potential future extensions which should not be designed out include, but are not +included in this MSC. ### Checking space membership over federation @@ -219,10 +219,10 @@ It is left to a future MSC to consider this, but some potential thoughts are given below. If you assume that a user *should* be removed in this case, one option is to -leave the departure up to Bob's server `server.example`, but this places a -relatively high level of trust in that server. Additionally, if `server.example` -were offline, other users in the room would still see Bob in the room (and their -servers would attempt to send message traffic to it). +leave the departure up to Bob's server `server.example`, but this places a +relatively high level of trust in that server. Additionally, if `server.example` +were offline, other users in the room would still see Bob in the room (and their +servers would attempt to send message traffic to it). Another consideration is that users may have joined via a direct invite, not via access through a space. @@ -261,7 +261,7 @@ The only difference is that you are not *required* to hold an invite when joining the room. [↩](#a2) [3]: This is a marginal decrease in security from the current -situation. Currently, a misbehaving server can allow unauthorized users to join +situation. Currently, a misbehaving server can allow unauthorized users to join any room by first issuing an invite to that user. In theory that can be prevented by raising the PL required to send an invite, but in practice that is rarely done. [↩](#a2) From 4eeb27f467c85772b19e412ff6b1f24045bca9e5 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 13 May 2021 08:41:32 -0400 Subject: [PATCH 048/162] Add more notes about edge-cases. --- proposals/3083-restricted-rooms.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index a3e5bd2eb..768529988 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -131,6 +131,12 @@ the room (since Alice is able to join it), but the calling server does not know *why* they received the room, without additional information the server cannot properly filter the returned results. +Note that there are still potential situations where each server individually +doesn't have enough information to properly return the full summary, but these +do not seem reasonable in what is considered a normal structure of spaces. (E.g. +in the above example, if the remote server is not in the space and does not know +whether the server is in the space or not it cannot return the room.) + (The alternative, where the calling server sends the requesting `user_id`, and the target server does the filtering, is unattractive because it rules out a future world where the calling server can cache the result.) From d7219fb67e6f829b905a1f315fd20c940c1521b5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 14 May 2021 15:54:14 -0600 Subject: [PATCH 049/162] Change space's valid `order` range to 0x7E 0x7F is DEL, which is clearly not intended by the proposal text. --- proposals/1772-groups-as-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1772-groups-as-rooms.md b/proposals/1772-groups-as-rooms.md index b6f60b388..1d431f841 100644 --- a/proposals/1772-groups-as-rooms.md +++ b/proposals/1772-groups-as-rooms.md @@ -126,7 +126,7 @@ relationship can be expressed in one of two ways: `origin_server_ts` of their `m.room.create` events, or ascending lexicographic order of their `room_id`s in case of equal `origin_server_ts`. `order`s which are not strings, or do not consist - solely of ascii characters in the range `\x20` (space) to `\x7F` (`~`), or + solely of ascii characters in the range `\x20` (space) to `\x7E` (`~`), or consist of more than 50 characters, are forbidden and the field should be ignored if received.) From d879eb6e009d7efcf6570ba5bbc47acf97e3da9a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 10:10:16 -0400 Subject: [PATCH 050/162] Rename encrypted status to encryption information. Co-authored-by: Travis Ralston --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 5087b4b8c..bcf2b8635 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -80,7 +80,7 @@ include the following as stripped state events: * Canonical alias (`m.room.canonical_alias`) * Room avatar (`m.room.avatar`) * Room name (`m.room.name`) -* Encrypted status (`m.room.encryption`)[3](#f2) +* Encryption information (`m.room.encryption`)[3](#f2) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). From 3fe5ca96b3506b0bf39e9bcba3da3a23171752a7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 10:53:16 -0400 Subject: [PATCH 051/162] Wrap text. --- proposals/3173-expose-stripped-state-events.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index bcf2b8635..4d7ed78b0 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -2,9 +2,12 @@ It is currently possible to inspect the state of rooms in some circumstances: -* If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). +* If the room has `history_visibility: world_readable`, then anyone can inspect + it (by calling `/state` on it). * Rooms in the room directory expose some of their state publicly. -* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) receive stripped state events. +* [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) + (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) + receive stripped state events. This MSC proposes exposing the stripped state events that are currently available to invited and knocking users to any user who could potentially join a room. It @@ -70,7 +73,9 @@ the following mechanisms: Future MSCs might include additional mechanism for a user to join a room and should consider this MSC, for example: -* [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)). +* [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)). Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: From d069ca285495846378a9aa2b7066c6a6d5c3dde0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:14:29 -0400 Subject: [PATCH 052/162] Also include the room topic. --- proposals/3173-expose-stripped-state-events.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 4d7ed78b0..b80f6256a 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -80,12 +80,13 @@ should consider this MSC, for example: Additionally, it is recommended, but not required, that homeserver implementations include the following as stripped state events: -* Create event (`m.room.create`)[2](#f1) +* Create event (`m.room.create`)[1](#f1) * 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`)[3](#f2) +* Encryption information (`m.room.encryption`)[2](#f2) +* Room topic (`m.room.topic`)[3](#f3) This also implies that the above information is available to any potential joiner in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). @@ -121,7 +122,13 @@ N/A ## Footnotes -[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772).[↩](#a1) +[1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1) -[2]: This is already sent from Synapse and generally seems useful for -a user to know before joining a room.[↩](#a2) +[2]: 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) + +[3]: 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 additional to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +in the spaces summary response. [↩](#a3) From b1051e42cb664ec209204982c8e7dd8415d32db0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:30:26 -0400 Subject: [PATCH 053/162] Various clarifications based on feedback. --- .../3173-expose-stripped-state-events.md | 51 +++++++++++++------ 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index b80f6256a..ac88305b7 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,15 +1,17 @@ # MSC3173: Expose stripped state events to any potential joiner -It is currently possible to inspect the state of rooms in some circumstances: +The current design of Matrix somtimes allows for inspecting part of the room state +without being joined to the room: * If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). -* Rooms in the room directory expose some of their state publicly. +* Rooms in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) + expose some of their state publicly. * [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) - (and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403)) - receive stripped state events. + and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403) + receive stripped state events to display metadata to users. -This MSC proposes exposing the stripped state events that are currently available +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 states events are available to potential joiners. @@ -62,10 +64,13 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal -Any user who is able to join a room can access the stripped state events of that room. +Any user who is able to join a room shall be allowed to have access the stripped +state events of that room. No changes are proposed to the mechanics of how the +users may get those state events, e.g. the `invite_state` of an invite or the +roomd irectory. -Potential ways that a user might be able to join include, but are not limited to, -the following mechanisms: +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`). @@ -77,8 +82,10 @@ should consider this MSC, for example: 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)). -Additionally, it is recommended, but not required, that homeserver implementations -include the following as stripped state events: +It is also proposed to create a single definition for what stripped state events +should be provided to be potential joiners. Thus, it is recommended (although not +required[0](#f0)) that homeserver implementations include the +following as stripped state events: * Create event (`m.room.create`)[1](#f1) * Join rules (`m.room.join_rules`) @@ -88,11 +95,6 @@ include the following as stripped state events: * Encryption information (`m.room.encryption`)[2](#f2) * Room topic (`m.room.topic`)[3](#f3) -This also implies that the above information is available to any potential joiner -in the API proposed in [MSC2946: Spaces summary](https://github.com/matrix-org/matrix-doc/pull/2946). -E.g. rooms which could be joined due to [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) -can expose the information available in stripped state events. - ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -112,16 +114,35 @@ seem to be a major weakening of the security. ## Future extensions +### Dedicated APIs + 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. +### Revisions to the room directory + +A future MSC could include additional information from the stripped state events +in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms). +This seems to mostly be the encryption information, but there may also be other +pieces of information to include. + +### 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. + ## Unstable prefix N/A ## Footnotes +[0]: 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) + [1]: As updated in [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772). [↩](#a1) [2]: The encryption information (`m.room.encryption`) is already sent From c44998cb6695f99e9419a8a3ec1160bdadc8cd0c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 17 May 2021 11:37:11 -0400 Subject: [PATCH 054/162] Fix awkward wording. --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index ac88305b7..2a15dbe7a 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -151,5 +151,5 @@ from Synapse and generally seems useful for a user to know before joining a roo [3]: 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 additional to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) +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) From 60566bf0e4b17c94ab33e52ba242692132ec586f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 18 May 2021 09:58:19 -0600 Subject: [PATCH 055/162] iterate --- .../identity_service/newsfragments/3176.clarification | 2 +- content/appendices.md | 10 +++++----- proposals/2265-email-lowercase.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/changelogs/identity_service/newsfragments/3176.clarification b/changelogs/identity_service/newsfragments/3176.clarification index 9f68bbf2f..50fb7cd12 100644 --- a/changelogs/identity_service/newsfragments/3176.clarification +++ b/changelogs/identity_service/newsfragments/3176.clarification @@ -1 +1 @@ -Clarify that some identifiers may be case-folded to lowercase prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file +Clarify that some identifiers must be case folded prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file diff --git a/content/appendices.md b/content/appendices.md index 67c41f98a..f3be0cc67 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -756,11 +756,11 @@ Represents E-Mail addresses. The `address` is the raw email address in other text such as real name, angle brackets or a mailto: prefix. In addition to lowercasing the domain component of an email address, -implementations are expected to case fold the localpart as described -in [the unicode mapping file](https://www.unicode.org/Public/8.0.0/ucd/CaseFolding.txt) -prior to any processing. For example, `Strauß@Example.com` must be -considered to be `strauss@example.com` while processing the email -address. +implementations are expected to apply the unicode case-folding algorithm +as described under "Caseless Matching" in +[chapter 5 of the unicode standard](https://www.unicode.org/versions/Unicode13.0.0/ch05.pdf#G21790). +For example, `Strauß@Example.com` must be considered to be `strauss@example.com` +while processing the email address. ### PSTN Phone numbers diff --git a/proposals/2265-email-lowercase.md b/proposals/2265-email-lowercase.md index 5a1db6825..e4fe53139 100644 --- a/proposals/2265-email-lowercase.md +++ b/proposals/2265-email-lowercase.md @@ -23,8 +23,8 @@ Sydent. This proposal suggests changing the specification of the e-mail 3PID type in [the Matrix spec appendices](https://matrix.org/docs/spec/appendices#pid-types) to mandate that, before any processing, e-mail addresses must go through a full -case folding based on [the unicode mapping -file](https://www.unicode.org/Public/8.0.0/ucd/CaseFolding.txt), on top of +case folding as described under "Caseless Matching" in +[chapter 5 of the unicode standard](https://www.unicode.org/versions/Unicode13.0.0/ch05.pdf#G21790), on top of having their domain lowercased. This means that `Strauß@Example.com` must be considered as being the same e-mail From 29e4006f3c2c2161f2bf854cf8a301336dfa7253 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 18 May 2021 12:38:29 -0400 Subject: [PATCH 056/162] Fix typo. Co-authored-by: Travis Ralston --- proposals/3173-expose-stripped-state-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 2a15dbe7a..f59368144 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -67,7 +67,7 @@ recommends including the `m.room.create` event as one of the stripped state even Any user who is able to join a room shall be allowed to have access the stripped state events of that room. No changes are proposed to the mechanics of how the users may get those state events, e.g. the `invite_state` of an invite or the -roomd irectory. +room directory. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: From e201f4977ef9dde7b5e78a661e3d263c9bb90d20 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 18 May 2021 13:04:11 -0400 Subject: [PATCH 057/162] Deprecate verifications that don't begin with a request. --- content/client-server-api/modules/end_to_end_encryption.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index bbacad6e5..cbd4f161b 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -528,7 +528,9 @@ method, then the verification should be cancelled with a `code` of `m.unexpected_message`. An `m.key.verification.start` message can also be sent independently of any -request, specifying the verification method to use. +request, specifying the verification method to use. This behaviour is +deprecated, and new clients should not begin verifications in this way. +However, clients should handle such verifications started by other clients. Individual verification methods may add additional steps, events, and properties to the verification messages. Event types for methods defined From 78adb21455431690f542ce71949e7e3f6a5adbca Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 18 May 2021 13:09:21 -0400 Subject: [PATCH 058/162] add changelog --- changelogs/client_server/newsfragments/3199.deprecaation | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3199.deprecaation diff --git a/changelogs/client_server/newsfragments/3199.deprecaation b/changelogs/client_server/newsfragments/3199.deprecaation new file mode 100644 index 000000000..6b51df6e3 --- /dev/null +++ b/changelogs/client_server/newsfragments/3199.deprecaation @@ -0,0 +1 @@ +Deprecate starting verifications that don't start with `m.key.verification.request` as per [MSC3122](https://github.com/matrix-org/matrix-doc/pull/3122). From 6923606e437240c0a901349c32853c81817b416e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 18 May 2021 13:22:33 -0400 Subject: [PATCH 059/162] Clarify what changes are being proposed. --- proposals/3173-expose-stripped-state-events.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index f59368144..37f7107c0 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -13,8 +13,8 @@ without being joined to the room: 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 states events are available to -potential joiners. +also consolidates the recommendation on which events to include as stripped state +for potential joiners. ## Background @@ -64,10 +64,16 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal +This proposal includes two aspects which are dealt with separately: + +1. Generalizing when a user is allowed to view the stripped state of a room. +2. A consistent recommendation for which events to include in the stripped state. + +### 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. No changes are proposed to the mechanics of how the -users may get those state events, e.g. the `invite_state` of an invite or the -room directory. +users may get those state events. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: @@ -82,6 +88,8 @@ should consider this MSC, for example: 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)). +### Events to include in the stripped state + It is also proposed to create a single definition for what stripped state events should be provided to be potential joiners. Thus, it is recommended (although not required[0](#f0)) that homeserver implementations include the From fd84bd721740387add932e546696cadeed889de9 Mon Sep 17 00:00:00 2001 From: Arnaud Venturi Date: Thu, 20 May 2021 17:00:10 +0200 Subject: [PATCH 060/162] Fix a typo in event soft rejection schema Signed-off-by: Arnaud Venturi --- content/server-server-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index e87e80852..c72dee522 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -550,7 +550,7 @@ then any new event `D'` will not reference `C`: / \ B C | - D + D' #### Retrieving event authorization information From 4beb86992b13fb5564ea9e7a2acf8416357fb246 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 21 May 2021 15:36:20 -0400 Subject: [PATCH 061/162] Fix broken ASCII art --- content/server-server-api.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index c72dee522..9013d6c0f 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -500,15 +500,15 @@ Example As an example consider the event graph: - A - / + A + / B where `B` is a ban of a user `X`. If the user `X` tries to set the topic by sending an event `C` while evading the ban: - A - / \ + A + / \ B C servers that receive `C` after `B` should soft fail event `C`, and so @@ -518,11 +518,11 @@ will neither relay `C` to its clients nor send any events referencing If later another server sends an event `D` that references both `B` and `C` (this can happen if it received `C` before `B`): - A - / \ + A + / \ B C - \ / - D + \ / + D then servers will handle `D` as normal. `D` is sent to the servers' clients (assuming `D` passes auth checks). The state at `D` may resolve @@ -539,15 +539,15 @@ state of the `C` branch. Let's go back to the graph before `D` was sent: - A - / \ + A + / \ B C If all the servers in the room saw `B` before `C` and so soft fail `C`, then any new event `D'` will not reference `C`: - A - / \ + A + / \ B C | D' @@ -584,15 +584,15 @@ state. For example, consider the following event graph (where the oldest event, E0, is at the top): - E0 - | - E1 - / \ + E0 + | + E1 + / \ E2 E4 | | E3 | - \ / - E5 + \ / + E5 Suppose E3 and E4 are both `m.room.name` events which set the name of the room. What should the name of the room be at E5? From 43e471faca665786b415aba97b67d5a817990235 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 21 May 2021 15:38:58 -0400 Subject: [PATCH 062/162] Add changelog --- changelogs/server_server/newsfragments/3207.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/server_server/newsfragments/3207.clarification diff --git a/changelogs/server_server/newsfragments/3207.clarification b/changelogs/server_server/newsfragments/3207.clarification new file mode 100644 index 000000000..3ccb23339 --- /dev/null +++ b/changelogs/server_server/newsfragments/3207.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. From 4b7dc17fbe8e01a7a867b2c3d42a7c4488fb3137 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 25 May 2021 15:25:50 -0400 Subject: [PATCH 063/162] Include an API endpoint. --- .../3173-expose-stripped-state-events.md | 111 +++++++++++++++--- 1 file changed, 94 insertions(+), 17 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 37f7107c0..d54589b61 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -1,7 +1,11 @@ # MSC3173: Expose stripped state events to any potential joiner -The current design of Matrix somtimes allows for inspecting part of the room state -without being joined to the room: +It can be useful to view the partial state of a room before joining to allow a user +to know *what* they're joining. For example, it improves the user experience to +show the user the room name and avatar before joining. + +It is already allowed to partially view the room state without being joined to +the room in some situations: * If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). @@ -14,7 +18,13 @@ without being joined to the room: 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. +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)). +* More information available to platforms like matrix.to. ## Background @@ -64,16 +74,18 @@ recommends including the `m.room.create` event as one of the stripped state even ## Proposal -This proposal includes two aspects which are dealt with separately: +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 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. No changes are proposed to the mechanics of how the -users may get those state events. +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. Potential ways that a user might be able to join a room include, but are not limited to, the following mechanisms: @@ -103,6 +115,67 @@ following as stripped state events: * Encryption information (`m.room.encryption`)[2](#f2) * Room topic (`m.room.topic`)[3](#f3) +### Stripped state API + +`GET /_matrix/client/r0/rooms/{roomId}/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`](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state) +endpoint. + +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). + +#### 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. + ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -115,25 +188,29 @@ knocking. ## Security considerations -This would allow for invisibly accessing the stripped state of a room with `knock` -join rules. This is already trivially accessible by knocking on the room, but -currently users in the room would know that the knock occurred. This does not -seem to be a major weakening of the security. +This would allow for invisibly accessing the stripped state of a room with `public` +or `knock` join rules. -## Future extensions +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). -### Dedicated APIs +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. -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 does not seem to be weakening the security expectations of either join rule. + +## Future extensions ### Revisions to the room directory A future MSC could include additional information from the stripped state events in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms). -This seems to mostly be the encryption information, but there may also be other -pieces of information to include. +The main missing piece seems to be the encryption information, but there may also +be other pieces of information to include. ### Additional ways to join a room From b5d096957e2a28e46eba3ffc2948d0ea3d1e9d39 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 26 May 2021 08:22:32 -0400 Subject: [PATCH 064/162] Clarify examples. --- proposals/3173-expose-stripped-state-events.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index d54589b61..3dccaf330 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -24,7 +24,9 @@ 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)). -* More information available to platforms like matrix.to. +* 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. ## Background From 8810f592078a0246d8a71a22dbffefe92713111c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 26 May 2021 11:04:50 -0600 Subject: [PATCH 065/162] Update 3167.clarification --- changelogs/identity_service/newsfragments/3167.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/identity_service/newsfragments/3167.clarification b/changelogs/identity_service/newsfragments/3167.clarification index 9f68bbf2f..16ed8dcdd 100644 --- a/changelogs/identity_service/newsfragments/3167.clarification +++ b/changelogs/identity_service/newsfragments/3167.clarification @@ -1 +1 @@ -Clarify that some identifiers may be case-folded to lowercase prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). \ No newline at end of file +Clarify that some identifiers must be case folded prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). From 8253c07dd06cb259a9ba770d3735ef48a9ab2d8f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 26 May 2021 23:59:17 +0000 Subject: [PATCH 066/162] Bump browserslist from 4.14.0 to 4.16.6 Bumps [browserslist](https://github.com/browserslist/browserslist) from 4.14.0 to 4.16.6. - [Release notes](https://github.com/browserslist/browserslist/releases) - [Changelog](https://github.com/browserslist/browserslist/blob/main/CHANGELOG.md) - [Commits](https://github.com/browserslist/browserslist/compare/4.14.0...4.16.6) Signed-off-by: dependabot[bot] --- package-lock.json | 65 +++++++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5dce70c7d..b41f83d66 100644 --- a/package-lock.json +++ b/package-lock.json @@ -135,15 +135,48 @@ } }, "browserslist": { - "version": "4.14.0", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.14.0.tgz", - "integrity": "sha512-pUsXKAF2lVwhmtpeA3LJrZ76jXuusrNyhduuQs7CDFf9foT4Y38aQOserd2lMe5DSSrjf3fx34oHwryuvxAUgQ==", + "version": "4.16.6", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.16.6.tgz", + "integrity": "sha512-Wspk/PqO+4W9qp5iUTJsa1B/QrYn1keNCcEP5OvP7WBwT4KaDly0uONYmC6Xa3Z5IqnUgS0KcgLYu1l74x0ZXQ==", "dev": true, "requires": { - "caniuse-lite": "^1.0.30001111", - "electron-to-chromium": "^1.3.523", - "escalade": "^3.0.2", - "node-releases": "^1.1.60" + "caniuse-lite": "^1.0.30001219", + "colorette": "^1.2.2", + "electron-to-chromium": "^1.3.723", + "escalade": "^3.1.1", + "node-releases": "^1.1.71" + }, + "dependencies": { + "caniuse-lite": { + "version": "1.0.30001230", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001230.tgz", + "integrity": "sha512-5yBd5nWCBS+jWKTcHOzXwo5xzcj4ePE/yjtkZyUV1BTUmrBaA9MRGC+e7mxnqXSA90CmCA8L3eKLaSUkt099IQ==", + "dev": true + }, + "colorette": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/colorette/-/colorette-1.2.2.tgz", + "integrity": "sha512-MKGMzyfeuutC/ZJ1cba9NqcNpfeqMUcYmyF1ZFY6/Cn7CNSAKx6a+s48sqLqyAiZuaP2TcqMhoo+dlwFnVxT9w==", + "dev": true + }, + "electron-to-chromium": { + "version": "1.3.739", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.3.739.tgz", + "integrity": "sha512-+LPJVRsN7hGZ9EIUUiWCpO7l4E3qBYHNadazlucBfsXBbccDFNKUBAgzE68FnkWGJPwD/AfKhSzL+G+Iqb8A4A==", + "dev": true + }, + "escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "dev": true + }, + "node-releases": { + "version": "1.1.72", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.72.tgz", + "integrity": "sha512-LLUo+PpH3dU6XizX3iVoubUNheF/owjXCZZ5yACDxNnPtgFuludV1ZL3ayK1kVep42Rmm0+R9/Y60NQbZ2bifw==", + "dev": true + } } }, "caller-callsite": { @@ -274,12 +307,6 @@ "path-type": "^4.0.0" } }, - "electron-to-chromium": { - "version": "1.3.534", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.3.534.tgz", - "integrity": "sha512-7x2S3yUrspNHQOoPk+Eo+iHViSiJiEGPI6BpmLy1eT2KRNGCkBt/NUYqjfXLd1DpDCQp7n3+LfA1RkbG+LqTZQ==", - "dev": true - }, "emoji-regex": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", @@ -295,12 +322,6 @@ "is-arrayish": "^0.2.1" } }, - "escalade": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.0.2.tgz", - "integrity": "sha512-gPYAU37hYCUhW5euPeR+Y74F7BL+IBsV93j5cvGriSaD1aG6MGsqsV1yamRdrWrb2j3aiZvb0X+UBOWpx3JWtQ==", - "dev": true - }, "escape-string-regexp": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", @@ -575,12 +596,6 @@ "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw==", "dev": true }, - "node-releases": { - "version": "1.1.60", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.60.tgz", - "integrity": "sha512-gsO4vjEdQaTusZAEebUWp2a5d7dF5DYoIpDG7WySnk7BuZDW+GPpHXoXXuYawRBr/9t5q54tirPz79kFIWg4dA==", - "dev": true - }, "normalize-path": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", From fee59e306d6c5f5930739b40f71835f1e15957f0 Mon Sep 17 00:00:00 2001 From: ilovecommits <83459976+ilovecommits@users.noreply.github.com> Date: Tue, 1 Jun 2021 10:10:42 +0000 Subject: [PATCH 067/162] Correct 'once-off' to 'one-off' --- content/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/_index.md b/content/_index.md index 4f7c30515..b6cca494f 100644 --- a/content/_index.md +++ b/content/_index.md @@ -328,7 +328,7 @@ Federation maintains *shared data structures* per-room between multiple homeservers. The data is split into `message events` and `state events`. Message events: -These describe transient 'once-off' activity in a room such as an +These describe transient 'one-off' activity in a room such as an instant messages, VoIP call setups, file transfers, etc. They generally describe communication activity. From b94d379921696731c0ca2ac17257cd94ea3dd2a7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 1 Jun 2021 13:59:21 -0400 Subject: [PATCH 068/162] Add federation and reword a bit. --- .../3173-expose-stripped-state-events.md | 73 +++++++++++++++---- 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 3dccaf330..565dad7bd 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -79,7 +79,8 @@ recommends including the `m.room.create` event as one of the stripped state even 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 recommendation for which events to include in the stripped state. +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 @@ -102,12 +103,21 @@ should consider this MSC, for example: 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)). -### Events to include in the stripped state +### Stripped state definitions and recommended events -It is also proposed to create a single definition for what stripped state events -should be provided to be potential joiners. Thus, it is recommended (although not -required[0](#f0)) that homeserver implementations include the -following as stripped state events: +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. + +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. + +It is recommended (although not required[0](#f0)) that +homeserver implementations include the following events as part of the stripped +state of a room: * Create event (`m.room.create`)[1](#f1) * Join rules (`m.room.join_rules`) @@ -119,7 +129,9 @@ following as stripped state events: ### Stripped state API -`GET /_matrix/client/r0/rooms/{roomId}/stripped_state` +#### 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 @@ -128,19 +140,26 @@ 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`](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state) -endpoint. +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). -#### Example request: +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: +##### Responses: -##### Status code 200: +###### Status code 200: The current stripped state of the room @@ -174,10 +193,33 @@ The current stripped state of the room 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: +###### 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. + ## Potential issues This is a generalization of current behavior and shouldn't introduce any new issues. @@ -222,7 +264,10 @@ for potential joiners due to membership in a space. ## Unstable prefix -N/A +| Stable Endpoint | Unstable Endpoint | +|---|---| +| `/_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` | `/_matrix/client/unstable/org.matrix.msc3173/rooms/{roomIdOrAlias}/stripped_state` | +| `/_matrix/federation/v1/stripped_state/{roomId}` | `/_matrix/federation/unstable/org.matrix.msc3173/stripped_state/{roomId}` | ## Footnotes From 122c803f35468a21ccf60ec62a2bd3d8eea2fcc5 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 1 Jun 2021 18:35:12 -0400 Subject: [PATCH 069/162] Rework this (again) to remove the API based on conversations with the SCT. --- .../3173-expose-stripped-state-events.md | 219 ++++++------------ 1 file changed, 65 insertions(+), 154 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 565dad7bd..69d80b615 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: - -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: @@ -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) From 5204b85f5971d4f1fffbdd1c07f91cee080384ee Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 2 Jun 2021 07:13:23 -0400 Subject: [PATCH 070/162] Remove unstable prefixes. --- proposals/3173-expose-stripped-state-events.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 69d80b615..830a9388a 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -169,10 +169,7 @@ for it. ## Unstable prefix -| Stable Endpoint | Unstable Endpoint | -|---|---| -| `/_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` | `/_matrix/client/unstable/org.matrix.msc3173/rooms/{roomIdOrAlias}/stripped_state` | -| `/_matrix/federation/v1/stripped_state/{roomId}` | `/_matrix/federation/unstable/org.matrix.msc3173/stripped_state/{roomId}` | +N/A ## Footnotes From 24810745c29f616a9a10501b01dd38c9e8b6ec88 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Sun, 30 May 2021 09:20:38 +0900 Subject: [PATCH 071/162] Drop Origin & Accept from Access-Control-Allow-Headers value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This change drops the Origin and Accept header names from the recommended value for the CORS Access-Control-Allow-Headers header. Per the CORS protocol, it’s not necessary or useful to include them. Per-spec at https://fetch.spec.whatwg.org/#forbidden-header-name, Origin is a “forbidden header name” set by the browser and that frontend JavaScript code is never allowed to set. So the value of Access-Control-Allow-Headers isn’t relevant to Origin or in general to other headers set by the browser itself — the browser never ever consults the Access-Control-Allow-Headers value to confirm that it’s OK for the request to include an Origin header. And per-spec at https://fetch.spec.whatwg.org/#cors-safelisted-request-header, Accept is a “CORS-safelisted request-header”, which means that browsers allow requests to contain the Accept header regardless of whether the Access-Control-Allow-Headers value contains "Accept". So it’s unnecessary for the Access-Control-Allow-Headers to explicitly include Accept. Browsers will not perform a CORS preflight for requests containing an Accept request header. Related: Related: https://github.com/matrix-org/synapse/pull/10114 Signed-off-by: Michael[tm] Smith --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 07fe9d962..7764cf47d 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -226,7 +226,7 @@ headers to be returned by servers on all requests are: Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization + Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization ## Server Discovery From 0f4961118eddaf2959ad1d765dd3a0c8422df0a6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:24:49 -0400 Subject: [PATCH 072/162] Remove spaces summary changes. --- proposals/3083-restricted-rooms.md | 86 ------------------------------ 1 file changed, 86 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 768529988..c21e40784 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -59,92 +59,6 @@ checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) However, user IDs listed as strings can be properly checked over federation. -### Discovery of restricted rooms - -The discovery of rooms in a space, as discussed in -[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946): spaces summary, -must be updated to allow for discovery of restricted rooms. - -MSC2946 defines that a room should be included in the spaces summary if it is -accessible (world-readable or if the user is already in the room). [MSC3173](https://github.com/matrix-org/matrix-doc/pull/3173) -declares that if a user can view the stripped state of a room if they are *able* -to join the room. Combining these two MSCs, the spaces summary should include -rooms with restricted join rule which a user is able to join (i.e. they're a -member of one of the spaces declared in the join rule). - -The server-server API discussed in [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) -does not know the user who is requesting a summary of the space, but should divulge -the above information if any member of a server could see it. It is up to the -calling server to properly filter this information. - -Trust is placed in the calling server: if there are any users on the calling -server in the correct space, that calling server has a right to know about the -rooms in that space and should return the relevant summaries, along with enough -information that the calling server can then do some filtering, thus an -additional field is added to the server-server response of the spaces summary: - -* `allowed_spaces`: A list of space IDs which give access to this room. - -This would modify the example response given to: - -```jsonc -{ - "rooms": [ - { - "room_id": "!ol19s:bleecker.street", - "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", - "guest_can_join": false, - "name": "CHEESE", - "num_joined_members": 37, - "topic": "Tasty tasty cheese", - "world_readable": true, - "room_type": "m.space", - "allowed_spaces": ["!mods:example.org", "!users:example.org"] - }, - { ... } - ], - "events": [ - { - "type": "m.space.child", - "state_key": "!efgh:example.com", - "content": { - "via": ["example.com"], - "suggested": true - }, - "room_id": "!ol19s:bleecker.street", - "sender": "@alice:bleecker.street" - }, - { ... } - ] -} -``` - -Consider that Alice and Bob share a server; Alice is a member of a space, but Bob -is not. The remote server will not know whether the request is on behalf of Alice -or Bob (and hence whether it should share details of restricted rooms within that -space). - -Consider the above with a restricted room on a different server which defers -access to the above space. When summarizing the space, the homeserver must make -a request over federation for information on the room. The response would include -the room (since Alice is able to join it), but the calling server does not know -*why* they received the room, without additional information the server cannot -properly filter the returned results. - -Note that there are still potential situations where each server individually -doesn't have enough information to properly return the full summary, but these -do not seem reasonable in what is considered a normal structure of spaces. (E.g. -in the above example, if the remote server is not in the space and does not know -whether the server is in the space or not it cannot return the room.) - -(The alternative, where the calling server sends the requesting `user_id`, and -the target server does the filtering, is unattractive because it rules out a -future world where the calling server can cache the result.) - -This does not decrease security since a server could lie and make a request on -behalf of a user in the proper space to see the given information. I.e. the -calling server must be trusted anyway. - ## Summary of the behaviour of join rules See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) From c7ab867cefe28bca54381d93cca824d50a892109 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:25:23 -0400 Subject: [PATCH 073/162] Fix broken backlink. --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index c21e40784..be507cb53 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -184,4 +184,4 @@ joining the room. [↩](#a2) situation. Currently, a misbehaving server can allow unauthorized users to join any room by first issuing an invite to that user. In theory that can be prevented by raising the PL required to send an invite, but in practice that is -rarely done. [↩](#a2) +rarely done. [↩](#a3) From c1eb461c8cc8d4578b6165fd68ab77a1ea39030a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:33:26 -0400 Subject: [PATCH 074/162] Remove bit about user IDs being listed directly. --- proposals/3083-restricted-rooms.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index be507cb53..aa8f25e78 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -39,7 +39,7 @@ Membership in a single space is enough. If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the -following keys, or a string representing the MXID of the user exempted: +following keys: * `space`: The room ID of the space to check the membership of. * `via`: A list of servers which may be used to peek for membership of the space. @@ -57,7 +57,6 @@ response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Unlike the `invite` join rule, confirmation that the `allow` rules were properly checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) -However, user IDs listed as strings can be properly checked over federation. ## Summary of the behaviour of join rules From 41dd06d355f42400959a963847defc5a25c6f9c6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:33:38 -0400 Subject: [PATCH 075/162] Clarify an edge case. --- proposals/3083-restricted-rooms.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index aa8f25e78..5399fb4ce 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -48,12 +48,16 @@ Any entries in the list which do not match the expected format are ignored. When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid -invite or is in one of the listed spaces. Note that the server may not know if the user -is in a particular space, this is left to a future MSC to solve. +invite or is in one of the listed spaces. If the user is not part of the proper space, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +It is possible for a homeserver receiving a `/make_join` / `/send_join` request +to not know if the user is in a particular space (due to not participating in any +of the necessary spaces). In this case the homeserver should reject the join, +the requesting server may wish to attempt to join via other homeservers. + Unlike the `invite` join rule, confirmation that the `allow` rules were properly checked cannot be enforced over federation by event authorization, so servers in the room are trusted not to allow invalid users to join.[3](#f3) From e81686c7d040c30060368032f73b4fb721d8580d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:52:35 -0400 Subject: [PATCH 076/162] Many clarifications. --- proposals/3083-restricted-rooms.md | 59 +++++++++++++++--------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 5399fb4ce..62d4029c5 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -59,7 +59,7 @@ of the necessary spaces). In this case the homeserver should reject the join, the requesting server may wish to attempt to join via other homeservers. Unlike the `invite` join rule, confirmation that the `allow` rules were properly -checked cannot be enforced over federation by event authorization, so servers in +checked cannot be enforced over federation by event authorisation, so servers in the room are trusted not to allow invalid users to join.[3](#f3) ## Summary of the behaviour of join rules @@ -72,10 +72,10 @@ between `public`, `invite`, and `restricted`. * `invite`: only people with membership `invite` can join, as today. * `knock`: the same as `invite`, except anyone can knock, subject to `ban` and `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). -* `private`: This is reserved and not implemented. -* `restricted`: the same as `public` from the perspective of the auth rules, but - with the additional caveat that servers are expected to check the `allow` rules - before generating a `join` event (whether for a local or a remote user). +* `private`: This is reserved, but unspecified. +* `restricted`: the same as `public` from the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), + but with the additional caveat that servers are expected to check the `allow` + rules before generating a `join` event (whether for a local or a remote user). ## Security considerations @@ -89,36 +89,31 @@ joining spurious users into your rooms, then: ## Unstable prefix -The `restricted` join rule will be included in a future room version to ensure -that servers and clients opt-into the new functionality. +The `restricted` join rule will be included in a future room version to allow +servers and clients to opt-into the new functionality. -During development it is expected that an unstable room version of -`org.matrix.msc3083` is used. Since the room version namespaces the behaviour, -the `allow` key and the `restricted` value do not need unstable prefixes. +During development, an unstable room version of `org.matrix.msc3083` will be used. +Since the room version namespaces the behaviour, the `allow` key and the +`restricted` value do not need unstable prefixes. -## History / Rationale +## Alternatives -Note that this replaces the second half of an older version of -[MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). - -It may seem that just having the `allow` key with `public` join rules is enough, -as suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962), +It may seem that just having the `allow` key with `public` join rules is enough +(as originally suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962)), but there are concerns that having a `public` join rule that is restricted may -cause issues if an implementation does not understand the semantics of the `allow` -keyword. Using an `allow` key with `invite` join rules also does not make sense as -from the perspective of the auth rules, this is akin to `public` (since the checking -of whether a member is in the space is done during the call to `/join` -or `/make_join` / `/send_join`). +cause issues if an implementation has not been updated to understand the semantics +of the `allow` keyword. This could be solved by introducing a new room version, +but in that case it seems clearer to introduce the `restricted` join rule, as +described above. -The above concerns about an implementation not understanding the semantics of `allow` -could be solved by introducing a new room version, but if this is done it seems clearer -to just introduce a a new join rule - `restricted` - as described above. +Using an `allow` key with `invite` join rules to broaden who can join was rejected +as an option since it requires weakening the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules). +From the perspective of the auth rules, the `restricted` join rule is identical +to `public` (since the checking of whether a member is in the space is done during +the call to `/join` or `/make_join` / `/send_join` regardless). ## Future extensions -Potential future extensions which should not be designed out include, but are not -included in this MSC. - ### Checking space membership over federation If a server is not in a space (and thus doesn't know the membership of a space) it @@ -131,6 +126,9 @@ the peek server has significant power. For example, a poorly chosen peek server could lie about the space membership and add an `@evil_user:example.org` to a space to gain membership to a room. +This MSC recommends rejecting the join in this case and allowing the requesting +homeserver to ask another homeserver. + ### Kicking users out when they leave the allowed space In the above example, suppose `@bob:server.example` leaves `!users:example.org`: @@ -167,7 +165,7 @@ It is possible that completely different state should be kept, or a different ### Inheriting join rules If you make a parent space invite-only, should that (optionally?) cascade into -child rooms? Seems to have some of the same problems as inheriting power levels, +child rooms? This would have some of the same problems as inheriting power levels, as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). ## Footnotes @@ -176,7 +174,8 @@ as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). of the '#catlovers' space" is less useful since: 1. Users in the banned space could simply leave it at any time -2. This functionality is already somewhat provided by [Moderation policy lists](https://matrix.org/docs/spec/client_server/r0.6.1#moderation-policy-lists). [↩](#a1) +2. This functionality is already partially provided by + [Moderation policy lists](https://matrix.org/docs/spec/client_server/r0.6.1#moderation-policy-lists). [↩](#a1) [2]: Note that there is nothing stopping users sending and receiving invites in `public` rooms today, and they work as you might expect. @@ -184,7 +183,7 @@ The only difference is that you are not *required* to hold an invite when joining the room. [↩](#a2) [3]: This is a marginal decrease in security from the current -situation. Currently, a misbehaving server can allow unauthorized users to join +situation. Currently, a misbehaving server can allow unauthorised users to join any room by first issuing an invite to that user. In theory that can be prevented by raising the PL required to send an invite, but in practice that is rarely done. [↩](#a3) From 8a3ad4717519c5737fbfefb1ee1b2d6ecce035e7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 4 Jun 2021 08:57:41 -0400 Subject: [PATCH 077/162] A bit less passive. --- proposals/3083-restricted-rooms.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 62d4029c5..b3daba6d3 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -2,8 +2,7 @@ A desirable feature is to give room admins the power to restrict membership of their room based on the membership of one or more spaces from -[MSC1772: spaces](https://github.com/matrix-org/matrix-doc/pull/1772), -for example: +[MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772), for example: > members of the #doglovers space can join this room without an invitation[1](#f1) @@ -74,8 +73,8 @@ between `public`, `invite`, and `restricted`. `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. * `restricted`: the same as `public` from the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), - but with the additional caveat that servers are expected to check the `allow` - rules before generating a `join` event (whether for a local or a remote user). + but with the additional caveat that servers must check the `allow` rules before + generating a `join` event (whether for a local or a remote user). ## Security considerations From 1694146beed8392d3003e8454177f4bcc83384a9 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 8 Jun 2021 17:10:41 +0100 Subject: [PATCH 078/162] Explicitly call replacement_room a room ID Fixes https://github.com/matrix-org/matrix-doc/issues/3232 --- data/event-schemas/schema/m.room.tombstone.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/event-schemas/schema/m.room.tombstone.yaml b/data/event-schemas/schema/m.room.tombstone.yaml index 0fd8ba452..1c590e1fd 100644 --- a/data/event-schemas/schema/m.room.tombstone.yaml +++ b/data/event-schemas/schema/m.room.tombstone.yaml @@ -10,7 +10,7 @@ properties: description: A server-defined message. replacement_room: type: string - description: The new room the client should be visiting. + description: The room ID of the new room the client should be visiting. required: - replacement_room - body From 524c55208adc31167813689e57137a3c55d7c800 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 9 Jun 2021 11:27:42 +0100 Subject: [PATCH 079/162] Create 3233.clarification --- changelogs/client_server/newsfragments/3233.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3233.clarification diff --git a/changelogs/client_server/newsfragments/3233.clarification b/changelogs/client_server/newsfragments/3233.clarification new file mode 100644 index 000000000..72a58f1b6 --- /dev/null +++ b/changelogs/client_server/newsfragments/3233.clarification @@ -0,0 +1 @@ +Explicitly state that `replacment_room` is a room ID in `m.room.tombstone` events. From 1d1d356aca2b665aa67e0df2a47398612d890eee Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 10 Jun 2021 12:02:14 -0400 Subject: [PATCH 080/162] Space -> room. --- proposals/3083-restricted-rooms.md | 42 +++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b3daba6d3..9146c457c 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -20,11 +20,11 @@ to trust for membership. For example: "join_rule": "restricted", "allow": [ { - "space": "!mods:example.org", + "room": "!mods:example.org", "via": ["example.org"] }, { - "space": "!users:example.org", + "room": "!users:example.org", "via": ["example.org"] } ] @@ -32,29 +32,29 @@ to trust for membership. For example: } ``` -This means that a user must be a member of the `!mods:example.org` space or -`!users:example.org` space in order to join without an invite[2](#f2). -Membership in a single space is enough. +This means that a user must be a member of the `!mods:example.org` room or +`!users:example.org` room in order to join without an invite[2](#f2). +Membership in a single room is enough. If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the following keys: -* `space`: The room ID of the space to check the membership of. -* `via`: A list of servers which may be used to peek for membership of the space. +* `room`: The room ID to check the membership of. +* `via`: A list of servers which may be used to peek for membership of the room. Any entries in the list which do not match the expected format are ignored. When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid -invite or is in one of the listed spaces. +invite or is in one of the listed rooms. -If the user is not part of the proper space, the homeserver should return an error -response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +If the user is not a member of at least one of the rooms, the homeserver should +return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in a particular space (due to not participating in any -of the necessary spaces). In this case the homeserver should reject the join, +to not know if the user is in a particular room (due to not participating in any +of the necessary rooms). In this case the homeserver should reject the join, the requesting server may wish to attempt to join via other homeservers. Unlike the `invite` join rule, confirmation that the `allow` rules were properly @@ -108,22 +108,22 @@ described above. Using an `allow` key with `invite` join rules to broaden who can join was rejected as an option since it requires weakening the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules). From the perspective of the auth rules, the `restricted` join rule is identical -to `public` (since the checking of whether a member is in the space is done during +to `public` (since the checking of whether a member is in the room is done during the call to `/join` or `/make_join` / `/send_join` regardless). ## Future extensions -### Checking space membership over federation +### Checking room membership over federation -If a server is not in a space (and thus doesn't know the membership of a space) it -cannot enforce membership of a space during a join. Peeking over federation, +If a server is not in a room (and thus doesn't know the membership of a room) it +cannot enforce membership of a room during a join. Peeking over federation, as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), -could be used to establish if the user is in any of the proper spaces. +could be used to establish if the user is in any of the proper rooms. Note that there are additional security considerations with this, namely that the peek server has significant power. For example, a poorly chosen peek -server could lie about the space membership and add an `@evil_user:example.org` -to a space to gain membership to a room. +server could lie about the room membership and add an `@evil_user:example.org` +to a room to gain membership to a room. This MSC recommends rejecting the join in this case and allowing the requesting homeserver to ask another homeserver. @@ -145,7 +145,7 @@ were offline, other users in the room would still see Bob in the room (and their servers would attempt to send message traffic to it). Another consideration is that users may have joined via a direct invite, not via -access through a space. +access through a room. Fixing this is thorny. Some sort of annotation on the membership events might help. but it's unclear what the desired semantics are: @@ -172,7 +172,7 @@ as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). [1]: The converse restriction, "anybody can join, provided they are not members of the '#catlovers' space" is less useful since: -1. Users in the banned space could simply leave it at any time +1. Users in the banned room could simply leave it at any time 2. This functionality is already partially provided by [Moderation policy lists](https://matrix.org/docs/spec/client_server/r0.6.1#moderation-policy-lists). [↩](#a1) From 7061e199e0c7ab3d6b0acdcd748cbb74387c8e1d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 10 Jun 2021 12:16:01 -0400 Subject: [PATCH 081/162] Add a type field. --- proposals/3083-restricted-rooms.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 9146c457c..fda815927 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -20,10 +20,12 @@ to trust for membership. For example: "join_rule": "restricted", "allow": [ { + "type": "room-membership", "room": "!mods:example.org", "via": ["example.org"] }, { + "type": "room-membership", "room": "!users:example.org", "via": ["example.org"] } @@ -40,10 +42,14 @@ If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the following keys: +* `type`: `"room-membership"` to describe that we are allowing access via room + membership. Future MSCs may define other types. * `room`: The room ID to check the membership of. * `via`: A list of servers which may be used to peek for membership of the room. -Any entries in the list which do not match the expected format are ignored. +Any entries in the list which do not match the expected format are ignored. Thus, +if all entries are invalid, the list behaves as if empty and all users without +an invite are rejected. When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid @@ -167,6 +173,17 @@ If you make a parent space invite-only, should that (optionally?) cascade into child rooms? This would have some of the same problems as inheriting power levels, as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). +### Additional allow types + +Future MSCs may wish to define additional values for the `type` argument, potentially +restricting access via: + +* MXIDs or servers. +* A shared secret (room password). + +These are just examples are not fully thought through for this MSC, but it should +be possible to add these behaviors in the future. + ## Footnotes [1]: The converse restriction, "anybody can join, provided they are not members From f493778f8d08e6b15eda8c7a91149f52e273009d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 12 Jun 2021 15:38:49 +0000 Subject: [PATCH 082/162] Bump glob-parent from 5.1.1 to 5.1.2 Bumps [glob-parent](https://github.com/gulpjs/glob-parent) from 5.1.1 to 5.1.2. - [Release notes](https://github.com/gulpjs/glob-parent/releases) - [Changelog](https://github.com/gulpjs/glob-parent/blob/main/CHANGELOG.md) - [Commits](https://github.com/gulpjs/glob-parent/compare/v5.1.1...v5.1.2) --- updated-dependencies: - dependency-name: glob-parent dependency-type: indirect ... Signed-off-by: dependabot[bot] --- package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index b41f83d66..a1d3b50c6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -408,9 +408,9 @@ "dev": true }, "glob-parent": { - "version": "5.1.1", - "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.1.tgz", - "integrity": "sha512-FnI+VGOpnlGHWZxthPGR+QhR78fuiK0sNLkHQv+bL9fQi57lNNdquIbna/WrfROrolq8GK5Ek6BiMwqL/voRYQ==", + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", "dev": true, "requires": { "is-glob": "^4.0.1" From 5a58af676ea39d816baa5567eb62c636afea4d4c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Jun 2021 13:11:57 -0400 Subject: [PATCH 083/162] Namespace the allow type. --- proposals/3083-restricted-rooms.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index fda815927..506067c56 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -20,12 +20,12 @@ to trust for membership. For example: "join_rule": "restricted", "allow": [ { - "type": "room-membership", + "type": "m.room_membership", "room": "!mods:example.org", "via": ["example.org"] }, { - "type": "room-membership", + "type": "m.room_membership", "room": "!users:example.org", "via": ["example.org"] } @@ -42,7 +42,7 @@ If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the following keys: -* `type`: `"room-membership"` to describe that we are allowing access via room +* `type`: `"m.room_membership"` to describe that we are allowing access via room membership. Future MSCs may define other types. * `room`: The room ID to check the membership of. * `via`: A list of servers which may be used to peek for membership of the room. @@ -98,8 +98,8 @@ The `restricted` join rule will be included in a future room version to allow servers and clients to opt-into the new functionality. During development, an unstable room version of `org.matrix.msc3083` will be used. -Since the room version namespaces the behaviour, the `allow` key and the -`restricted` value do not need unstable prefixes. +Since the room version namespaces the behaviour, the `allow` key and value, as well +as the `restricted` join rule value do not need unstable prefixes. ## Alternatives From f3e7fba85f073d16238a0047c435312958d2796b Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Jun 2021 13:13:17 -0400 Subject: [PATCH 084/162] Re-iterate that ban and server-acls matter. --- proposals/3083-restricted-rooms.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 506067c56..85ef353c2 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -74,7 +74,8 @@ specification for full details, but the summary below should highlight the diffe between `public`, `invite`, and `restricted`. * `public`: anyone can join, subject to `ban` and `server_acls`, as today. -* `invite`: only people with membership `invite` can join, as today. +* `invite`: only people with membership `invite` can join, subject to `ban` and + `server_acls`, as today. * `knock`: the same as `invite`, except anyone can knock, subject to `ban` and `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. From ed679c71f58acc1901e4f30497fa16ab0ee53aec Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Jun 2021 13:24:15 -0400 Subject: [PATCH 085/162] Clarify membership checking over federation. --- proposals/3083-restricted-rooms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 85ef353c2..b36371403 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -123,8 +123,8 @@ the call to `/join` or `/make_join` / `/send_join` regardless). ### Checking room membership over federation If a server is not in a room (and thus doesn't know the membership of a room) it -cannot enforce membership of a room during a join. Peeking over federation, -as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), +cannot enforce membership of a room during a call to `/make_join`, or `/send_join`. +Peeking over federation, as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), could be used to establish if the user is in any of the proper rooms. Note that there are additional security considerations with this, namely that @@ -132,8 +132,8 @@ the peek server has significant power. For example, a poorly chosen peek server could lie about the room membership and add an `@evil_user:example.org` to a room to gain membership to a room. -This MSC recommends rejecting the join in this case and allowing the requesting -homeserver to ask another homeserver. +As iterated above, this MSC recommends rejecting the join, potentially allowing +the requesting homeserver to retry via another homeserver. ### Kicking users out when they leave the allowed space From bfa0dfe6008cc65c4e5bf5cdf9c8d8505d42e219 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Jun 2021 13:29:13 -0400 Subject: [PATCH 086/162] Clarify auth rules for restrictedjoin rules. --- proposals/3083-restricted-rooms.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b36371403..d3b0e4a0a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -51,6 +51,10 @@ Any entries in the list which do not match the expected format are ignored. Thus if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. +From the perspective of hee [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), +the `restricted` join rule has the same behavior as `public`. Additional checks +against the `allow` rules are performed during event generation, as described below. + When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from a server, the request should only be permitted if the user has a valid invite or is in one of the listed rooms. From 39b9a9d582cb8eb9ef9295861202dc676acdd66d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Jun 2021 14:34:34 -0400 Subject: [PATCH 087/162] Clarify security concerns. --- proposals/3083-restricted-rooms.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index d3b0e4a0a..ec2893b18 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -90,8 +90,12 @@ between `public`, `invite`, and `restricted`. ## Security considerations The `allow` feature for `join_rules` places increased trust in the servers in the -room. We consider this acceptable: if you don't want evil servers randomly -joining spurious users into your rooms, then: +room. Any server which is joined to the room will be able to issue join events +for the room, there are situations which no individual server in the room can +verify that the membership event was issued in good faith. + +We consider this acceptable: if you don't want evil servers randomly joining +spurious users into your rooms, then: 1. Don't let evil servers in your room in the first place 2. Don't use `allow` lists, given the expansion increases the attack surface anyway @@ -122,6 +126,12 @@ From the perspective of the auth rules, the `restricted` join rule is identical to `public` (since the checking of whether a member is in the room is done during the call to `/join` or `/make_join` / `/send_join` regardless). +It was also considered to limit servers which can issue join membership events +to those in the `via` field (or some other list of trusted servers). This is +undesirable since it would increase centralization (e.g. a server already in the +room couldn't issue membership events for another user on that server). It is +unclear that this would significantly increase the security of the room. + ## Future extensions ### Checking room membership over federation From 91c761271650299449d4dbd02808938cc208f2e0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 16 Jun 2021 14:12:00 -0400 Subject: [PATCH 088/162] Handle feedback from Travis. --- proposals/3083-restricted-rooms.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index ec2893b18..e3415cbef 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -8,9 +8,9 @@ their room based on the membership of one or more spaces from ## Proposal -A new `join_rule` (`restricted`) will be used to reflect a cross between `invite` -and `public` join rules. The content of the join rules would include the rooms -to trust for membership. For example: +In a future room version a new `join_rule` (`restricted`) will be used to reflect +a cross between `invite` and `public` join rules. The content of the join rules +would include the rooms to trust for membership. For example: ```json { @@ -21,12 +21,12 @@ to trust for membership. For example: "allow": [ { "type": "m.room_membership", - "room": "!mods:example.org", + "room_id": "!mods:example.org", "via": ["example.org"] }, { "type": "m.room_membership", - "room": "!users:example.org", + "room_id": "!users:example.org", "via": ["example.org"] } ] @@ -44,14 +44,14 @@ following keys: * `type`: `"m.room_membership"` to describe that we are allowing access via room membership. Future MSCs may define other types. -* `room`: The room ID to check the membership of. +* `room_id`: The room ID to check the membership of. * `via`: A list of servers which may be used to peek for membership of the room. Any entries in the list which do not match the expected format are ignored. Thus, if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. -From the perspective of hee [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), +From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`. Additional checks against the `allow` rules are performed during event generation, as described below. From 8451c23154837007e02b02356a70f2a74d72a729 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Thu, 17 Jun 2021 00:19:44 +0100 Subject: [PATCH 089/162] Fix sidebar overlap for small width devices This resolves a jarring text overlap issue with the sidebar by only adjusting the `max-height` at larger widths, which matches the original rule being overridden. Fixes https://github.com/matrix-org/matrix-doc/issues/3049 --- assets-hugo/scss/custom.scss | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/assets-hugo/scss/custom.scss b/assets-hugo/scss/custom.scss index 3116762ed..62ae4532f 100644 --- a/assets-hugo/scss/custom.scss +++ b/assets-hugo/scss/custom.scss @@ -45,9 +45,6 @@ Custom SCSS for the Matrix spec scroll-behavior: smooth; overscroll-behavior: contain; - /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */ - max-height: calc(100vh - 6rem); - &>.td-sidebar-nav__section { margin-top: 1rem; } @@ -92,6 +89,15 @@ Custom SCSS for the Matrix spec } } +@media (min-width: 768px) { + @supports (position: sticky) { + .td-sidebar-nav { + /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */ + max-height: calc(100vh - 6rem); + } + } +} + /* Customise footer */ footer { box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25); From 721d4edb342fa64b5c07c8c17ca54033dceb5574 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 17 Jun 2021 14:30:21 +0000 Subject: [PATCH 090/162] Bump postcss from 7.0.32 to 7.0.36 Bumps [postcss](https://github.com/postcss/postcss) from 7.0.32 to 7.0.36. - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](https://github.com/postcss/postcss/compare/7.0.32...7.0.36) --- updated-dependencies: - dependency-name: postcss dependency-type: indirect ... Signed-off-by: dependabot[bot] --- package-lock.json | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/package-lock.json b/package-lock.json index a1d3b50c6..73994715f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -97,22 +97,10 @@ "postcss-value-parser": "^4.1.0" }, "dependencies": { - "postcss": { - "version": "7.0.32", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-7.0.32.tgz", - "integrity": "sha512-03eXong5NLnNCD05xscnGKGDZ98CyzoqPSMjOe6SuoQY7Z2hIj0Ld1g/O/UQRuOle2aRtiIRDg9tDcTGAkLfKw==", - "dev": true, - "requires": { - "chalk": "^2.4.2", - "source-map": "^0.6.1", - "supports-color": "^6.1.0" - } - }, "supports-color": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-6.1.0.tgz", "integrity": "sha512-qe1jfm1Mg7Nq/NSh6XE24gPXROEVsWHxC1LIx//XNlD9iw7YZQGjZNjYN7xGaEG6iKdA8EtNFW6R0gjnVXp+wQ==", - "dev": true, "requires": { "has-flag": "^3.0.0" } @@ -439,8 +427,7 @@ "has-flag": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha1-tdRU3CGZriJWmfNGfloH87lVuv0=", - "dev": true + "integrity": "sha1-tdRU3CGZriJWmfNGfloH87lVuv0=" }, "ignore": { "version": "5.1.8", @@ -673,9 +660,9 @@ "dev": true }, "postcss": { - "version": "7.0.32", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-7.0.32.tgz", - "integrity": "sha512-03eXong5NLnNCD05xscnGKGDZ98CyzoqPSMjOe6SuoQY7Z2hIj0Ld1g/O/UQRuOle2aRtiIRDg9tDcTGAkLfKw==", + "version": "7.0.36", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-7.0.36.tgz", + "integrity": "sha512-BebJSIUMwJHRH0HAQoxN4u1CN86glsrwsW0q7T+/m44eXOUAxSNdHRkNZPYz5vVUbg17hFgOQDE7fZk7li3pZw==", "dev": true, "requires": { "chalk": "^2.4.2", From 39fdfa3fcbfbd518a7dd011fe5fde79041f84e80 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 17 Jun 2021 14:20:49 -0400 Subject: [PATCH 091/162] Add a list of trusted servers. --- proposals/3083-restricted-rooms.md | 137 ++++++++++++++++------------- 1 file changed, 74 insertions(+), 63 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index e3415cbef..b13589cd9 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -29,14 +29,15 @@ would include the rooms to trust for membership. For example: "room_id": "!users:example.org", "via": ["example.org"] } - ] + ], + "authorised_servers": ["example.org"] } } ``` This means that a user must be a member of the `!mods:example.org` room or `!users:example.org` room in order to join without an invite[2](#f2). -Membership in a single room is enough. +Membership in a single allowed room is enough. If the `allow` key is an empty list (or not a list at all), then no users are allowed to join without an invite. Each entry is expected to be an object with the @@ -51,30 +52,46 @@ Any entries in the list which do not match the expected format are ignored. Thus if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. -From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), -the `restricted` join rule has the same behavior as `public`. Additional checks -against the `allow` rules are performed during event generation, as described below. - -When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` -request from a server, the request should only be permitted if the user has a valid -invite or is in one of the listed rooms. +The `authorised_servers` key lists servers which are trusted to verify the above +allow rules. It must be a list of string server name, a special value of `"*"` +can be used to allow any server with a member in the room. Any non-string entries +are discarded, if the list is non-existent or empty then no users may join without +an invite.[3](#f3) -If the user is not a member of at least one of the rooms, the homeserver should -return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), +the `restricted` join rule has the same behavior as `public`, with the additional +caveat that servers must ensure that: + +* The user's current membership is `invite` or `join`, or +* The `m.room.member` event has a valid signature from one of the servers listed + in `authorised_servers`. + +The above check must also be performed against the current room state to potentially +soft-fail the event. This is the primary mechanism for guarding against state +changes when old events are referenced. (E.g. if an authorised server is removed +it should not be able to issue new membership events by referencing an old event +in the room.) + +When an authorised homeserver receives a `/join` request from a client or a +`/make_join` / `/send_join` request from another homeserver, the request should +only be permitted if the user has a valid invite or is in one of the listed rooms. +If the user is not a member of at least one of the rooms, the authorised homeserver +should return an error response with HTTP status code of 403 and an `errcode` of +`M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request to not know if the user is in a particular room (due to not participating in any of the necessary rooms). In this case the homeserver should reject the join, -the requesting server may wish to attempt to join via other homeservers. +the requesting server may wish to attempt to join via another authorised homeserver. -Unlike the `invite` join rule, confirmation that the `allow` rules were properly -checked cannot be enforced over federation by event authorisation, so servers in -the room are trusted not to allow invalid users to join.[3](#f3) +Note that the authorised homeservers have significant power, as they are trusted +to confirm that the `allow` rules were properly checked (since this cannot +easily be enforced over federation by event authorisation).[4](#f4) ## Summary of the behaviour of join rules See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) -specification for full details, but the summary below should highlight the differences +specification for full details, the summary below is meant to highlight the differences between `public`, `invite`, and `restricted`. * `public`: anyone can join, subject to `ban` and `server_acls`, as today. @@ -83,23 +100,19 @@ between `public`, `invite`, and `restricted`. * `knock`: the same as `invite`, except anyone can knock, subject to `ban` and `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. -* `restricted`: the same as `public` from the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), - but with the additional caveat that servers must check the `allow` rules before - generating a `join` event (whether for a local or a remote user). +* `restricted`: the same as `public`, with the additional caveat that servers must + verify the `m.room.member` event is signed by one of the `authorised_servers` if + a member is not yet invited or joined to the room. ## Security considerations -The `allow` feature for `join_rules` places increased trust in the servers in the -room. Any server which is joined to the room will be able to issue join events -for the room, there are situations which no individual server in the room can -verify that the membership event was issued in good faith. +The `allow` feature for `join_rules` places increased trust in the authorised +servers. Any authorised server which is joined to the room will be able to issue +join events for the room which no individual server in the room could verify was +issued in good faith. -We consider this acceptable: if you don't want evil servers randomly joining -spurious users into your rooms, then: - -1. Don't let evil servers in your room in the first place -2. Don't use `allow` lists, given the expansion increases the attack surface anyway - by letting members in other rooms dictate who's allowed into your room. +The increased trust in authorised servers is considered an acceptable trade-off +between increased centralisation and increased security. ## Unstable prefix @@ -114,42 +127,36 @@ as the `restricted` join rule value do not need unstable prefixes. It may seem that just having the `allow` key with `public` join rules is enough (as originally suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962)), -but there are concerns that having a `public` join rule that is restricted may -cause issues if an implementation has not been updated to understand the semantics -of the `allow` keyword. This could be solved by introducing a new room version, -but in that case it seems clearer to introduce the `restricted` join rule, as -described above. +but there are concerns that changing the behaviour of a pre-existing a `public` +join rule may cause security issues in older implementations (that do not yet +understand the new behaviour). This could be solved by introducing a new room +version, thus it seems clearer to introduce a new join rule -- `restricted`. -Using an `allow` key with `invite` join rules to broaden who can join was rejected +Using an `allow` key with the `invite` join rules to broaden who can join was rejected as an option since it requires weakening the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules). From the perspective of the auth rules, the `restricted` join rule is identical -to `public` (since the checking of whether a member is in the room is done during -the call to `/join` or `/make_join` / `/send_join` regardless). - -It was also considered to limit servers which can issue join membership events -to those in the `via` field (or some other list of trusted servers). This is -undesirable since it would increase centralization (e.g. a server already in the -room couldn't issue membership events for another user on that server). It is -unclear that this would significantly increase the security of the room. +to `public` with additional checks on the signature to ensure it was issued by +an authorised server. ## Future extensions ### Checking room membership over federation -If a server is not in a room (and thus doesn't know the membership of a room) it -cannot enforce membership of a room during a call to `/make_join`, or `/send_join`. -Peeking over federation, as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), +If an authorised server is not in an allowed room (and thus doesn't know the +membership of it) then the server cannot enforce the membership checks while +generating a join event. Peeking over federation, as described in +[MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), could be used to establish if the user is in any of the proper rooms. -Note that there are additional security considerations with this, namely that -the peek server has significant power. For example, a poorly chosen peek +This would then delegate power out to a (potentially) untrusted server, giving that +the peek server significant power. For example, a poorly chosen peek server could lie about the room membership and add an `@evil_user:example.org` -to a room to gain membership to a room. +to an allowed room to gain membership to a room. As iterated above, this MSC recommends rejecting the join, potentially allowing the requesting homeserver to retry via another homeserver. -### Kicking users out when they leave the allowed space +### Kicking users out when they leave the allowed room In the above example, suppose `@bob:server.example` leaves `!users:example.org`: should they be removed from the room? Likely not, by analogy with what happens @@ -171,22 +178,22 @@ access through a room. Fixing this is thorny. Some sort of annotation on the membership events might help. but it's unclear what the desired semantics are: -* Assuming that users in a given space are *not* kicked when that space is +* Assuming that users in an allowed room are *not* kicked when that room is removed from `allow`, are those users then given a pass to remain - in the room indefinitely? What happens if the space is added back to + in the room indefinitely? What happens if the room is added back to `allow` and *then* the user leaves it? -* Suppose a user joins a room via a space (SpaceA). Later, SpaceB is added to - the `allow` list and SpaceA is removed. What should happen when the - user leaves SpaceB? Are they exempt from the kick? +* Suppose a user joins a room via an allowed room (RoomA). Later, RoomB is added + to the `allow` list and RoomA is removed. What should happen when the + user leaves RoomB? Are they exempt from the kick? It is possible that completely different state should be kept, or a different `m.room.member` state could be used in a more reasonable way to track this. ### Inheriting join rules -If you make a parent space invite-only, should that (optionally?) cascade into -child rooms? This would have some of the same problems as inheriting power levels, -as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). +If an allowed room is a space and you make a parent space invite-only, should that +(optionally?) cascade into child rooms? This would have some of the same problems +as inheriting power levels, as discussed in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962). ### Additional allow types @@ -213,8 +220,12 @@ receiving invites in `public` rooms today, and they work as you might expect. The only difference is that you are not *required* to hold an invite when joining the room. [↩](#a2) -[3]: This is a marginal decrease in security from the current -situation. Currently, a misbehaving server can allow unauthorised users to join -any room by first issuing an invite to that user. In theory that can be -prevented by raising the PL required to send an invite, but in practice that is -rarely done. [↩](#a3) +[3]: This unfortunately introduces another piece of data which must be +maintained by room administrators. It is recommended that clients initially set +this to the homeserver of the creator or the special value `"*"`. [↩](#a3) + +[4]: This has the downside of increased centralisation, as a homeserver +that is not an authorised server but is already in the room may not issue a join +event for another user on that server. (It must go through the `/make_join` / +`/send_join` flow of an authorised server.) This is considered a reasonable +trade-off. [↩](#a4) From 3bab6bd9e1ec9287e84ef43ce745719719d33f8a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 17 Jun 2021 14:21:45 -0400 Subject: [PATCH 092/162] Remove via field. --- proposals/3083-restricted-rooms.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b13589cd9..936470b98 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -21,13 +21,11 @@ would include the rooms to trust for membership. For example: "allow": [ { "type": "m.room_membership", - "room_id": "!mods:example.org", - "via": ["example.org"] + "room_id": "!mods:example.org" }, { "type": "m.room_membership", - "room_id": "!users:example.org", - "via": ["example.org"] + "room_id": "!users:example.org" } ], "authorised_servers": ["example.org"] @@ -46,7 +44,6 @@ following keys: * `type`: `"m.room_membership"` to describe that we are allowing access via room membership. Future MSCs may define other types. * `room_id`: The room ID to check the membership of. -* `via`: A list of servers which may be used to peek for membership of the room. Any entries in the list which do not match the expected format are ignored. Thus, if all entries are invalid, the list behaves as if empty and all users without From 8e0b0014862e5fc09e34ec10cb36f3fd7936e2bf Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 17 Jun 2021 14:22:55 -0400 Subject: [PATCH 093/162] Add a note about ensuring each allowed room has at least one server in it. --- proposals/3083-restricted-rooms.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 936470b98..053adca81 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -80,6 +80,8 @@ It is possible for a homeserver receiving a `/make_join` / `/send_join` request to not know if the user is in a particular room (due to not participating in any of the necessary rooms). In this case the homeserver should reject the join, the requesting server may wish to attempt to join via another authorised homeserver. +If no authorised servers are in an allowed room its membership cannot be checked +(and this is a misconfiguration). Note that the authorised homeservers have significant power, as they are trusted to confirm that the `allow` rules were properly checked (since this cannot From 0b499321dc62c2ebea40d20f8a0607c066ed8f99 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 18 Jun 2021 08:09:36 -0400 Subject: [PATCH 094/162] Clarifications. Co-authored-by: Jonathan de Jong --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 053adca81..bd5b506ef 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -101,7 +101,7 @@ between `public`, `invite`, and `restricted`. * `private`: This is reserved, but unspecified. * `restricted`: the same as `public`, with the additional caveat that servers must verify the `m.room.member` event is signed by one of the `authorised_servers` if - a member is not yet invited or joined to the room. + a member was not yet invited or joined into the room. ## Security considerations From d86f8aa3d7217840dcef51b976cdbcc22b5952b3 Mon Sep 17 00:00:00 2001 From: Christian Paul Date: Tue, 22 Jun 2021 13:01:03 +0200 Subject: [PATCH 095/162] Add "knock" membership to /members endpoint (#3254) --- data/api/client-server/rooms.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 0dd60d8e6..f8931893e 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -206,6 +206,7 @@ paths: enum: - join - invite + - knock - leave - ban description: |- @@ -220,6 +221,7 @@ paths: enum: - join - invite + - knock - leave - ban description: |- From b4296efa54baa543f658cc0a18aa1cc92394a65d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 22 Jun 2021 08:34:05 -0400 Subject: [PATCH 096/162] Remove the authorised servers list. --- proposals/3083-restricted-rooms.md | 91 ++++++++++++++---------------- 1 file changed, 41 insertions(+), 50 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index bd5b506ef..8af446ca5 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -27,8 +27,7 @@ would include the rooms to trust for membership. For example: "type": "m.room_membership", "room_id": "!users:example.org" } - ], - "authorised_servers": ["example.org"] + ] } } ``` @@ -49,43 +48,38 @@ Any entries in the list which do not match the expected format are ignored. Thus if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. -The `authorised_servers` key lists servers which are trusted to verify the above -allow rules. It must be a list of string server name, a special value of `"*"` -can be used to allow any server with a member in the room. Any non-string entries -are discarded, if the list is non-existent or empty then no users may join without -an invite.[3](#f3) +When an homeserver receives a `/join` request from a client or a `/make_join` / +`/send_join` request from another homeserver, the request should only be permitted +if the user has a valid invite or is in one of the listed rooms. If the user is +not a member of at least one of the rooms, the homeserver should return an error +response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. + +It is possible for a homeserver receiving a `/make_join` / `/send_join` request +to not know if the user is in a particular room (due to not participating in any +of the necessary rooms). In this case the homeserver should reject the join, +the requesting server may wish to attempt to join via another homeserver. If no +servers are in an allowed room its membership cannot be checked (and this is a +misconfiguration). From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional caveat that servers must ensure that: -* The user's current membership is `invite` or `join`, or -* The `m.room.member` event has a valid signature from one of the servers listed - in `authorised_servers`. +* The user's previous membership was `invite` or `join`, or +* The `m.room.member` event has a valid signature from a homeserver whose users + have the power to issue invites. The above check must also be performed against the current room state to potentially soft-fail the event. This is the primary mechanism for guarding against state -changes when old events are referenced. (E.g. if an authorised server is removed -it should not be able to issue new membership events by referencing an old event -in the room.) - -When an authorised homeserver receives a `/join` request from a client or a -`/make_join` / `/send_join` request from another homeserver, the request should -only be permitted if the user has a valid invite or is in one of the listed rooms. -If the user is not a member of at least one of the rooms, the authorised homeserver -should return an error response with HTTP status code of 403 and an `errcode` of -`M_FORBIDDEN`. +changes when old events are referenced. (E.g. if the power levels change, a +server should not be able to issue new membership events by referencing an old +event in the room.) -It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in a particular room (due to not participating in any -of the necessary rooms). In this case the homeserver should reject the join, -the requesting server may wish to attempt to join via another authorised homeserver. -If no authorised servers are in an allowed room its membership cannot be checked -(and this is a misconfiguration). - -Note that the authorised homeservers have significant power, as they are trusted -to confirm that the `allow` rules were properly checked (since this cannot -easily be enforced over federation by event authorisation).[4](#f4) +Note that the homeservers whose users can issue invites are trusted to confirm +that the `allow` rules were properly checked (since this cannot easily be +enforced over federation by event authorisation).[3](#f3) +(The rationale for trusting these homeservers is that they could easily +side-step the restriction by issuing an invite first.) ## Summary of the behaviour of join rules @@ -100,18 +94,20 @@ between `public`, `invite`, and `restricted`. `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. * `restricted`: the same as `public`, with the additional caveat that servers must - verify the `m.room.member` event is signed by one of the `authorised_servers` if - a member was not yet invited or joined into the room. + verify the `m.room.member` event is signed by a homeserver whose users may issue + invites if the joining member was not previously invited or joined into the room. ## Security considerations -The `allow` feature for `join_rules` places increased trust in the authorised -servers. Any authorised server which is joined to the room will be able to issue -join events for the room which no individual server in the room could verify was -issued in good faith. +Although increased trust to enforce the join rules during `/join` / `/make_join` +/ `/send_join` is placed in the homeservers whose users can issue invites, this +is considered only a miniscule change in room security. -The increased trust in authorised servers is considered an acceptable trade-off -between increased centralisation and increased security. +This MSC limits the homeservers who can issue join events (via calls to `/join`, +`/make_join`, and `/send_join`) and trusts those servers to enforce the additional +allow rules. Although other homeservers may not be able to verify that a join +event was issued in good faith, there is no benefit for a homeserver to do this +since they could have issued an invite anyway. ## Unstable prefix @@ -134,14 +130,13 @@ version, thus it seems clearer to introduce a new join rule -- `restricted`. Using an `allow` key with the `invite` join rules to broaden who can join was rejected as an option since it requires weakening the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules). From the perspective of the auth rules, the `restricted` join rule is identical -to `public` with additional checks on the signature to ensure it was issued by -an authorised server. +to `public` with additional checks on the signature of the event. ## Future extensions ### Checking room membership over federation -If an authorised server is not in an allowed room (and thus doesn't know the +If a homeserver is not in an allowed room (and thus doesn't know the membership of it) then the server cannot enforce the membership checks while generating a join event. Peeking over federation, as described in [MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444), @@ -219,12 +214,8 @@ receiving invites in `public` rooms today, and they work as you might expect. The only difference is that you are not *required* to hold an invite when joining the room. [↩](#a2) -[3]: This unfortunately introduces another piece of data which must be -maintained by room administrators. It is recommended that clients initially set -this to the homeserver of the creator or the special value `"*"`. [↩](#a3) - -[4]: This has the downside of increased centralisation, as a homeserver -that is not an authorised server but is already in the room may not issue a join -event for another user on that server. (It must go through the `/make_join` / -`/send_join` flow of an authorised server.) This is considered a reasonable -trade-off. [↩](#a4) +[3]: This has the downside of increased centralisation, as some +homeservers that are already in the room may not issue a join event for another +user on that server. (It must go through the `/make_join` / `/send_join` flow of +a server whose users may issue invites.) This is considered a reasonable +trade-off. [↩](#a3) From e5305a72f2d56db24a16b0c6a0988d975106f7e3 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 22 Jun 2021 08:46:19 -0400 Subject: [PATCH 097/162] Clarifications / simplifications. --- proposals/3083-restricted-rooms.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 8af446ca5..8107a9934 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -55,11 +55,10 @@ not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in a particular room (due to not participating in any -of the necessary rooms). In this case the homeserver should reject the join, -the requesting server may wish to attempt to join via another homeserver. If no -servers are in an allowed room its membership cannot be checked (and this is a -misconfiguration). +to not know if the user is in any of the allowed room (due to not participating +in them). In this case the homeserver should reject the join, the requesting +server may wish to attempt to join via another homeserver. If no servers are in +an allowed room its membership cannot be checked (and this is a misconfiguration). From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional @@ -78,8 +77,6 @@ event in the room.) Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[3](#f3) -(The rationale for trusting these homeservers is that they could easily -side-step the restriction by issuing an invite first.) ## Summary of the behaviour of join rules @@ -99,15 +96,11 @@ between `public`, `invite`, and `restricted`. ## Security considerations -Although increased trust to enforce the join rules during `/join` / `/make_join` -/ `/send_join` is placed in the homeservers whose users can issue invites, this -is considered only a miniscule change in room security. - -This MSC limits the homeservers who can issue join events (via calls to `/join`, -`/make_join`, and `/send_join`) and trusts those servers to enforce the additional -allow rules. Although other homeservers may not be able to verify that a join -event was issued in good faith, there is no benefit for a homeserver to do this -since they could have issued an invite anyway. +Increased trust to enforce the join rules during calls to `/join`, `/make_join`, +and `/send_join` is placed in the homeservers whose users can issue invites. +Although it is possible for those homeservers to issue a join event in bad faith, +there is no real-world benefit to doing this as those homeservers could easily +side-side the restriction by issuing an invite first anyway. ## Unstable prefix From 08cddf0b038668ea360d95e3c1a9eb64daf6edcc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 22 Jun 2021 11:49:31 -0600 Subject: [PATCH 098/162] changelog for https://github.com/matrix-org/matrix-doc/pull/3254 --- changelogs/client_server/newsfragments/3254.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3254.feature diff --git a/changelogs/client_server/newsfragments/3254.feature b/changelogs/client_server/newsfragments/3254.feature new file mode 100644 index 000000000..c73c27ec6 --- /dev/null +++ b/changelogs/client_server/newsfragments/3254.feature @@ -0,0 +1 @@ +Add support for knocking, as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). \ No newline at end of file From a330dee081c562a2befb25cb4bdeee1c996c0f1c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 22 Jun 2021 19:52:51 -0600 Subject: [PATCH 099/162] Changelog for https://github.com/matrix-org/matrix-doc/pull/3225 --- changelogs/client_server/newsfragments/3225.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3225.clarification diff --git a/changelogs/client_server/newsfragments/3225.clarification b/changelogs/client_server/newsfragments/3225.clarification new file mode 100644 index 000000000..046b25cf1 --- /dev/null +++ b/changelogs/client_server/newsfragments/3225.clarification @@ -0,0 +1 @@ +Update `Access-Control-Allow-Headers` recommendation to fit CORS specification. \ No newline at end of file From fb091fed039fef50ac9b551fa89db8f6592a458c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 22 Jun 2021 20:25:46 -0600 Subject: [PATCH 100/162] Apply suggestions from code review Co-authored-by: Hubert Chathi Co-authored-by: penn5 Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2778-appservice-login.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 43c024aab..62bf5b049 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -5,7 +5,7 @@ need a way to generate devices for their users so that they can participate in E do so, this proposal suggests implementing an appservice extension to the [`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). -Appservice users do not usually need to login as they do not need their own access token, and do not +Appservice users do not usually need to log in as they do not need their own access token, and do not traditionally need a "device". However, E2E encryption demands that at least one user in a room has a Matrix device which means bridge users need to be able to generate a device on demand. In the past, bridge developers have used the bridge bot's device for all bridge users in the room, but this causes @@ -44,13 +44,13 @@ The response body should be unchanged from the existing `/login` specification. If one of the following conditions are true: - The access token is not provided -- The access token does not correspond to a appservice +- The access token does not correspond to an appservice - Or the user has not previously been registered Then the servers MUST reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. -If the access token DOES correspond to a appservice but the user is not inside its namespace, -then the `errcode` should be `"M_EXCLUSIVE"`. +If the access token DOES correspond to an appservice but the user is not inside its namespace, +then the `errcode` must be `"M_EXCLUSIVE"`. Homeservers should ignore the `access_token` parameter if a type other than `m.login.application_service` has been provided. @@ -109,10 +109,10 @@ Furthermore, the ability to generate access tokens for real users who registered ## Security considerations Appservices could use this new functionality to generate devices for any userId that are within its namespace e.g. setting the -user namespace regex to `@.*:example.com` would allow appservice to control anyone on the homeserver. While this sounds scary, in practise +user namespace regex to `@.*:example.com` would allow appservice to control anyone on the homeserver. While this sounds scary, in practice this is not a problem because: -- Appservice namespaces are mainained by the homeserver admin. If the namespace were to change, then it's reasonable +- Appservice namespaces are maintained by the homeserver admin. If the namespace were to change, then it's reasonable to assume that the server admin is aware. There is no defense mechanism to stop a malicious server admin from creating new devices for a given user's account as they could also do so by simply modifying the database. From ec2c1f6f5399cbb8295454c57e588fa7fbc8b662 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 22 Jun 2021 20:29:26 -0600 Subject: [PATCH 101/162] Remove what appears to be leftover notes --- proposals/2778-appservice-login.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/proposals/2778-appservice-login.md b/proposals/2778-appservice-login.md index 62bf5b049..fd509ab89 100644 --- a/proposals/2778-appservice-login.md +++ b/proposals/2778-appservice-login.md @@ -2,7 +2,7 @@ Appservices within Matrix are increasingly attempting to support End-to-End Encryption. As such, they need a way to generate devices for their users so that they can participate in E2E rooms. In order to -do so, this proposal suggests implementing an appservice extension to the +do so, this proposal suggests implementing an appservice extension to the [`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). Appservice users do not usually need to log in as they do not need their own access token, and do not @@ -47,7 +47,7 @@ If one of the following conditions are true: - The access token does not correspond to an appservice - Or the user has not previously been registered -Then the servers MUST reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. +Then the servers MUST reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. If the access token DOES correspond to an appservice but the user is not inside its namespace, then the `errcode` must be `"M_EXCLUSIVE"`. @@ -95,16 +95,8 @@ could store this information rather than calling `POST /login` at all. This does - If user tokens were lost or exposed, there is no way to programattically create new access tokens for these users. - Finally, if a user was registered externally and the appservice would like to masquerade as it, it would be unable to fetch an access token for that user. - -While `POST /register` does work, it is impactical as the sole method of fetching an access token. - -Most appservices -which do not implement encryption do not store this information as neither the device_id or access_token are needed f However critically -this means that bridges will need to be designed to store the access_token and device_id from the point of creating the user, -so older bridges would be unable to get an access token for existing users as `POST /register` would fail. -It would difficult to log out these tokens if they got exposed additionally, as the AS would not be able to fetch a new access token. -Furthermore, the ability to generate access tokens for real users who registered elsewhere would not be possible with this mechanism. +While `POST /register` does work, it is impactical as the sole method of fetching an access token. ## Security considerations @@ -116,7 +108,7 @@ this is not a problem because: to assume that the server admin is aware. There is no defense mechanism to stop a malicious server admin from creating new devices for a given user's account as they could also do so by simply modifying the database. -- While an appservice *could* try to masquerade as a user maliciously without the server admin expecting it, it would still +- While an appservice *could* try to masquerade as a user maliciously without the server admin expecting it, it would still be bound by the restrictions of the namespace. Server admins are expected to be aware of the implications of adding new appservices to their server so the burden of responsibility lies with the server admin. @@ -125,7 +117,7 @@ this is not a problem because: does make them unable to see encrypted messages, this is not designed to be a security mechanism. In conclusion this MSC only automates the creation of new devices for users inside an AS namespace, which is something -a server admin could already do. Appservices should always be treated with care and so with these facts in mind the MSC should +a server admin could already do. Appservices should always be treated with care and so with these facts in mind the MSC should be considered secure. ## Unstable prefix From c1169424a3437ee2d3bf86dbe32dbb5cc8ec3a12 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Wed, 23 Jun 2021 14:26:30 +0200 Subject: [PATCH 102/162] sso_login_redirect: Fix a copy-pasted operationId --- data/api/client-server/sso_login_redirect.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 8c92a3ce6..f15f19e49 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -56,7 +56,7 @@ paths: The server MUST respond with an HTTP redirect to the SSO interface for that IdP. - operationId: redirectToSSO + operationId: redirectToIdP parameters: - in: path type: string From 6d041d4dd9d5313383fd8f527deb1deb17929a9c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 24 Jun 2021 08:20:44 -0400 Subject: [PATCH 103/162] Fix typos. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 8107a9934..1aae6d42a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -81,7 +81,7 @@ enforced over federation by event authorisation).[3](#f3) ## Summary of the behaviour of join rules See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) -specification for full details, the summary below is meant to highlight the differences +specification for full details; the summary below is meant to highlight the differences between `public`, `invite`, and `restricted`. * `public`: anyone can join, subject to `ban` and `server_acls`, as today. @@ -100,7 +100,7 @@ Increased trust to enforce the join rules during calls to `/join`, `/make_join`, and `/send_join` is placed in the homeservers whose users can issue invites. Although it is possible for those homeservers to issue a join event in bad faith, there is no real-world benefit to doing this as those homeservers could easily -side-side the restriction by issuing an invite first anyway. +side-step the restriction by issuing an invite first anyway. ## Unstable prefix From 69aec559acaa631bdedb928e09f7549ff2c372d4 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 24 Jun 2021 08:30:49 -0400 Subject: [PATCH 104/162] Clarify soft-failure is extension of current algorithm. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 1aae6d42a..9adad0b62 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -68,11 +68,10 @@ caveat that servers must ensure that: * The `m.room.member` event has a valid signature from a homeserver whose users have the power to issue invites. -The above check must also be performed against the current room state to potentially -soft-fail the event. This is the primary mechanism for guarding against state -changes when old events are referenced. (E.g. if the power levels change, a -server should not be able to issue new membership events by referencing an old -event in the room.) +As normal, the above check is also performed against the current room state during +[soft-failure](https://matrix.org/docs/spec/server_server/r0.1.4#soft-failure), +to guard against servers issuing new membership events by referencing old +events in the room. Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be From 42a34de18da103d9bfcf809125d5ebfaf3d95897 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 24 Jun 2021 08:32:36 -0400 Subject: [PATCH 105/162] Clarify that signature checks only apply to joining users. --- proposals/3083-restricted-rooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 9adad0b62..63d290aa7 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -65,8 +65,8 @@ the `restricted` join rule has the same behavior as `public`, with the additiona caveat that servers must ensure that: * The user's previous membership was `invite` or `join`, or -* The `m.room.member` event has a valid signature from a homeserver whose users - have the power to issue invites. +* The `m.room.member` event with a `membership` of `join` has a valid signature + from a homeserver whose users have the power to issue invites. As normal, the above check is also performed against the current room state during [soft-failure](https://matrix.org/docs/spec/server_server/r0.1.4#soft-failure), From 808bb1bc5a45fd74a89d2295ac6626fc0a43126f Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 28 Jun 2021 08:34:44 -0400 Subject: [PATCH 106/162] Pull note about ban & ACLs out of each join rule description. --- proposals/3083-restricted-rooms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 63d290aa7..6e30f09ed 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -81,13 +81,13 @@ enforced over federation by event authorisation).[3](#f3) See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) specification for full details; the summary below is meant to highlight the differences -between `public`, `invite`, and `restricted`. +between `public`, `invite`, and `restricted`. Note that all join rules are subject +to `ban` and `server_acls`. -* `public`: anyone can join, subject to `ban` and `server_acls`, as today. -* `invite`: only people with membership `invite` can join, subject to `ban` and - `server_acls`, as today. -* `knock`: the same as `invite`, except anyone can knock, subject to `ban` and - `server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). +* `public`: anyone can join, as today. +* `invite`: only people with membership `invite` can join, as today. +* `knock`: the same as `invite`, except anyone can knock. See + [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. * `restricted`: the same as `public`, with the additional caveat that servers must verify the `m.room.member` event is signed by a homeserver whose users may issue From 87f993820de683c2e2954786960cc6b2e35a9b5f Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 28 Jun 2021 08:35:44 -0400 Subject: [PATCH 107/162] Use a different room version to specify changes in join rules. --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 6e30f09ed..b33c4f0c4 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -106,7 +106,7 @@ side-step the restriction by issuing an invite first anyway. The `restricted` join rule will be included in a future room version to allow servers and clients to opt-into the new functionality. -During development, an unstable room version of `org.matrix.msc3083` will be used. +During development, an unstable room version of `org.matrix.msc3083.v2` will be used. Since the room version namespaces the behaviour, the `allow` key and value, as well as the `restricted` join rule value do not need unstable prefixes. From 182c806bc45549c72b2d3ca1864bc471351e9ec2 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 28 Jun 2021 08:55:52 -0400 Subject: [PATCH 108/162] Clarify what happens if a homeserver cannot verify membership. --- proposals/3083-restricted-rooms.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b33c4f0c4..a77c36383 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -55,10 +55,13 @@ not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in any of the allowed room (due to not participating -in them). In this case the homeserver should reject the join, the requesting -server may wish to attempt to join via another homeserver. If no servers are in -an allowed room its membership cannot be checked (and this is a misconfiguration). +to not know if the user is in some of the allowed room (due to not participating +in them). Any allow room that the homeserver cannot verify the membership should +be treated as if the user is not in that room. If the user is not in any of the +rooms (or some of the rooms cannot be verified) the homeserver should reject the +join, as above. The requesting server may wish to attempt to join via another +homeserver. If no servers are in any of the allowed rooms its membership cannot +be verified (and this is a misconfiguration). From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional From 1be4019a6267a2963cd8a689da310efbefa49998 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 28 Jun 2021 09:02:19 -0400 Subject: [PATCH 109/162] Clarify implications of signing events. --- proposals/3083-restricted-rooms.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index a77c36383..bd6b0a7e3 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -69,7 +69,18 @@ caveat that servers must ensure that: * The user's previous membership was `invite` or `join`, or * The `m.room.member` event with a `membership` of `join` has a valid signature - from a homeserver whose users have the power to issue invites. + from a homeserver whose users have the power to issue invites. This implies + that: + + * A join event issued via `/make_join` & `/send_join` is signed by the not + just the requesting server, but also the resident server. (This seems like + an improvement regardless since the resident server is accepting the event + on behalf of the joining server and ideally this should be verifiable after + the fact, even for current room versions.) + * The auth chain of the join event needs to include an event which proves + the homeserver can be issuing the join. This can be done by including the + `m.room.power_levels` event and an `m.room.member` event with `membership` + equal to `join` for a member who could issue invites from that server. As normal, the above check is also performed against the current room state during [soft-failure](https://matrix.org/docs/spec/server_server/r0.1.4#soft-failure), From 76333ee222c67cd99e60836fe635c1d8c16d0351 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 1 Jul 2021 12:54:00 -0400 Subject: [PATCH 110/162] Add notes about the via key and authorised servers being out of sync. --- proposals/3083-restricted-rooms.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index bd6b0a7e3..19ea0ab9c 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -206,6 +206,24 @@ restricting access via: These are just examples are not fully thought through for this MSC, but it should be possible to add these behaviors in the future. +### Interaction with `m.space.child` events + +[MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) defines a `via` +key in the content of `m.space.child` events: + +> the content must contain a via `key` which gives a list of candidate servers +> that can be used to join the room. + +It is possible for the candidate servers and the list of authorised servers to +not be in sync. In the case where there's no overlap between these lists, it may +not be possible for a server to complete the request. + +If there is some overlap between the lists of servers the join request should +complete successfully. + +A future MSC may define a way to override or update the `via` key in a coherent +manner. + ## Footnotes [1]: The converse restriction, "anybody can join, provided they are not members From 5f2240a59e0498014e442dc0cb5ae330be94c3bd Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 12 Jul 2021 13:53:20 -0400 Subject: [PATCH 111/162] Fix typo. Co-authored-by: Hubert Chathi --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 19ea0ab9c..7389cacb5 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -72,7 +72,7 @@ caveat that servers must ensure that: from a homeserver whose users have the power to issue invites. This implies that: - * A join event issued via `/make_join` & `/send_join` is signed by the not + * A join event issued via `/make_join` & `/send_join` is signed by not just the requesting server, but also the resident server. (This seems like an improvement regardless since the resident server is accepting the event on behalf of the joining server and ideally this should be verifiable after From 30372321b38228c339d7fa1c65c771acd7807d9e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:32:11 -0400 Subject: [PATCH 112/162] Fix typo. Co-authored-by: Travis Ralston --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 7389cacb5..b9e3660e5 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -55,7 +55,7 @@ not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in some of the allowed room (due to not participating +to not know if the user is in some of the allowed rooms (due to not participating in them). Any allow room that the homeserver cannot verify the membership should be treated as if the user is not in that room. If the user is not in any of the rooms (or some of the rooms cannot be verified) the homeserver should reject the From 2c65a03d594043e8f83aeeaab9894bbffef6bbc3 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:35:31 -0400 Subject: [PATCH 113/162] Fix typo. Co-authored-by: Matthew Hodgson --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index b9e3660e5..60d542907 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -128,7 +128,7 @@ as the `restricted` join rule value do not need unstable prefixes. It may seem that just having the `allow` key with `public` join rules is enough (as originally suggested in [MSC2962](https://github.com/matrix-org/matrix-doc/pull/2962)), -but there are concerns that changing the behaviour of a pre-existing a `public` +but there are concerns that changing the behaviour of a pre-existing `public` join rule may cause security issues in older implementations (that do not yet understand the new behaviour). This could be solved by introducing a new room version, thus it seems clearer to introduce a new join rule -- `restricted`. From b9204cccf844afc27e7b2876fae8d452b6615462 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:35:49 -0400 Subject: [PATCH 114/162] Remove extraneous paragraph. --- proposals/3083-restricted-rooms.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 60d542907..6f45b68b1 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -82,11 +82,6 @@ caveat that servers must ensure that: `m.room.power_levels` event and an `m.room.member` event with `membership` equal to `join` for a member who could issue invites from that server. -As normal, the above check is also performed against the current room state during -[soft-failure](https://matrix.org/docs/spec/server_server/r0.1.4#soft-failure), -to guard against servers issuing new membership events by referencing old -events in the room. - Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[3](#f3) From d95200f5e220056d512658fee4b20d668be54cb5 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:36:54 -0400 Subject: [PATCH 115/162] Add domains to the example room aliases. --- proposals/3083-restricted-rooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 6f45b68b1..93095247a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -4,7 +4,7 @@ A desirable feature is to give room admins the power to restrict membership of their room based on the membership of one or more spaces from [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772), for example: -> members of the #doglovers space can join this room without an invitation[1](#f1) +> members of the #doglovers:example.com space can join this room without an invitation[1](#f1) ## Proposal @@ -222,7 +222,7 @@ manner. ## Footnotes [1]: The converse restriction, "anybody can join, provided they are not members -of the '#catlovers' space" is less useful since: +of the #catlovers:example.com space" is less useful since: 1. Users in the banned room could simply leave it at any time 2. This functionality is already partially provided by From dc945a48435ec65949b239431585b9d086f5564f Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:43:48 -0400 Subject: [PATCH 116/162] Reword intro. --- proposals/3083-restricted-rooms.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 93095247a..5a23a9db1 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -1,10 +1,19 @@ # Restricting room membership based on space membership A desirable feature is to give room admins the power to restrict membership of -their room based on the membership of one or more spaces from -[MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772), for example: +their room based on the membership of one or more rooms. -> members of the #doglovers:example.com space can join this room without an invitation[1](#f1) +Potential usecases include: + +* Private spaces (allowing any member of a [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) + space to join child rooms in that space), for example: + + > members of the #doglovers:example.com space can join this room without an invitation[1](#f1) +* Room upgrades for private rooms (instead of issuing invites to each user). +* Allowing all users in a private room to be able to join a private breakout room. + +This does not preclude members from being directly invited to the room, which is +still a useful discovery feature. ## Proposal From 2012466214781414659032d555584d639adcc5ef Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:46:29 -0400 Subject: [PATCH 117/162] Clarify users must be joined to an allowed room. Co-authored-by: Matthew Hodgson --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 5a23a9db1..3e0f0f7ce 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -59,7 +59,7 @@ an invite are rejected. When an homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from another homeserver, the request should only be permitted -if the user has a valid invite or is in one of the listed rooms. If the user is +if the user is invited to this room, or is joined to one of the listed rooms. If the user is not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. From db40a1c8a3adbbb137d4e05f4739b4908366a346 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 08:47:14 -0400 Subject: [PATCH 118/162] Reflow. --- proposals/3083-restricted-rooms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 3e0f0f7ce..bf67cd119 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -59,9 +59,9 @@ an invite are rejected. When an homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from another homeserver, the request should only be permitted -if the user is invited to this room, or is joined to one of the listed rooms. If the user is -not a member of at least one of the rooms, the homeserver should return an error -response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +if the user is invited to this room, or is joined to one of the listed rooms. If +the user is not a member of at least one of the rooms, the homeserver should return +an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a homeserver receiving a `/make_join` / `/send_join` request to not know if the user is in some of the allowed rooms (due to not participating From 81a588e63126ffae53d56df17b498adf9d3cfde5 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 12:59:43 -0400 Subject: [PATCH 119/162] Add note about including the authorising server in the content. --- proposals/3083-restricted-rooms.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index bf67cd119..91bf5f5b0 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -82,18 +82,19 @@ caveat that servers must ensure that: that: * A join event issued via `/make_join` & `/send_join` is signed by not - just the requesting server, but also the resident server. (This seems like - an improvement regardless since the resident server is accepting the event - on behalf of the joining server and ideally this should be verifiable after - the fact, even for current room versions.) + just the requesting server, but also the resident server.[3](#f3) * The auth chain of the join event needs to include an event which proves the homeserver can be issuing the join. This can be done by including the `m.room.power_levels` event and an `m.room.member` event with `membership` equal to `join` for a member who could issue invites from that server. + In order to find a corresponding event quickly for verification, the + content of the join event should include the other user's MXID in the + content with the key `join_authorised_via_users_server`. + Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be -enforced over federation by event authorisation).[3](#f3) +enforced over federation by event authorisation).[4](#f4) ## Summary of the behaviour of join rules @@ -242,8 +243,13 @@ receiving invites in `public` rooms today, and they work as you might expect. The only difference is that you are not *required* to hold an invite when joining the room. [↩](#a2) -[3]: This has the downside of increased centralisation, as some +[3]: This seems like an improvement regardless since the resident server +is accepting the event on behalf of the joining server and ideally this should be +verifiable after the fact, even for current room versions. Requiring all events +to be signed and verified in this way is left to a future MSC. [↩](#a3) + +[4]: This has the downside of increased centralisation, as some homeservers that are already in the room may not issue a join event for another user on that server. (It must go through the `/make_join` / `/send_join` flow of a server whose users may issue invites.) This is considered a reasonable -trade-off. [↩](#a3) +trade-off. [↩](#a4) From b41a1a3392af52da91854f3ef61b23d970286a81 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 13 Jul 2021 13:06:54 -0400 Subject: [PATCH 120/162] Update the information on signature checking. --- proposals/3083-restricted-rooms.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 91bf5f5b0..89103c0d6 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -81,8 +81,11 @@ caveat that servers must ensure that: from a homeserver whose users have the power to issue invites. This implies that: - * A join event issued via `/make_join` & `/send_join` is signed by not - just the requesting server, but also the resident server.[3](#f3) + * A join event issued via `/send_join` is signed by not just the requesting + server, but also the resident server.[3](#f3) + + In order for the joining server to receive the proper signatures the join + event will be returned via `/send_join` in the `join_event` field. * The auth chain of the join event needs to include an event which proves the homeserver can be issuing the join. This can be done by including the `m.room.power_levels` event and an `m.room.member` event with `membership` From 290f9032f4c4b0d87b3290ab2f0c5d3c24262eb2 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 16 Jul 2021 13:03:49 -0400 Subject: [PATCH 121/162] Updates from review. --- proposals/3083-restricted-rooms.md | 33 +++++++++++++++++++----------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 89103c0d6..063251d93 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -72,6 +72,8 @@ join, as above. The requesting server may wish to attempt to join via another homeserver. If no servers are in any of the allowed rooms its membership cannot be verified (and this is a misconfiguration). +TODO Better define errors over federation. + From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional caveat that servers must ensure that: @@ -85,35 +87,39 @@ caveat that servers must ensure that: server, but also the resident server.[3](#f3) In order for the joining server to receive the proper signatures the join - event will be returned via `/send_join` in the `join_event` field. + event will be returned via `/send_join` in the `event` field. * The auth chain of the join event needs to include an event which proves the homeserver can be issuing the join. This can be done by including the `m.room.power_levels` event and an `m.room.member` event with `membership` equal to `join` for a member who could issue invites from that server. In order to find a corresponding event quickly for verification, the - content of the join event should include the other user's MXID in the - content with the key `join_authorised_via_users_server`. + content of the join event should include the chosen user's MXID in the + content with the key `join_authorised_via_users_server`. The actual user + chosen is arbitrary. Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[4](#f4) +To better cope with joining via aliases, homeservers should use the list of +authorised servers (not the list of candidate servers) when a user attempts to +join a room. + ## Summary of the behaviour of join rules See the [join rules](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-join-rules) specification for full details; the summary below is meant to highlight the differences -between `public`, `invite`, and `restricted`. Note that all join rules are subject -to `ban` and `server_acls`. +between `public`, `invite`, and `restricted` from a user perspective. Note that +all join rules are subject to `ban` and `server_acls`. * `public`: anyone can join, as today. * `invite`: only people with membership `invite` can join, as today. * `knock`: the same as `invite`, except anyone can knock. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). * `private`: This is reserved, but unspecified. -* `restricted`: the same as `public`, with the additional caveat that servers must - verify the `m.room.member` event is signed by a homeserver whose users may issue - invites if the joining member was not previously invited or joined into the room. +* `restricted`: the same as `invite`, except users may also join if they are a + member of a room listed in the `allow` rules. ## Security considerations @@ -214,7 +220,7 @@ restricting access via: These are just examples are not fully thought through for this MSC, but it should be possible to add these behaviors in the future. -### Interaction with `m.space.child` events +### Client considerations [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) defines a `via` key in the content of `m.space.child` events: @@ -222,13 +228,16 @@ key in the content of `m.space.child` events: > the content must contain a via `key` which gives a list of candidate servers > that can be used to join the room. -It is possible for the candidate servers and the list of authorised servers to -not be in sync. In the case where there's no overlap between these lists, it may -not be possible for a server to complete the request. +It is possible for the list of candidate servers and the list of authorised +servers to diverge. It may not be possible for a user to join a room if there's +no overlap between these lists. If there is some overlap between the lists of servers the join request should complete successfully. +Clients should also consider the authorised servers when generating candidate +servers to embed in links to the room, e.g. via matrix.to. + A future MSC may define a way to override or update the `via` key in a coherent manner. From ffb9095c82672c49f2a500797cd10a919495ea4a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 16 Jul 2021 13:15:29 -0400 Subject: [PATCH 122/162] Add a note about resident servers. --- proposals/3083-restricted-rooms.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 063251d93..dadff3762 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -98,6 +98,12 @@ caveat that servers must ensure that: content with the key `join_authorised_via_users_server`. The actual user chosen is arbitrary. + This creates a new restriction on the relationship between the resident + servers used for `/make_join` and `/send_join` -- they must now both go to + the same server (since the `join_authorised_via_users_server` is added in + the call to `/make_join`, while the final signature is added during + the call to `/send_join`). + Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[4](#f4) From 7caff82b36617963ea9f8672c852c95046169bfb Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 19 Jul 2021 14:57:34 -0400 Subject: [PATCH 123/162] Add information about errors over federation. --- proposals/3083-restricted-rooms.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index dadff3762..d739c48e9 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -63,16 +63,16 @@ if the user is invited to this room, or is joined to one of the listed rooms. If the user is not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. -It is possible for a homeserver receiving a `/make_join` / `/send_join` request -to not know if the user is in some of the allowed rooms (due to not participating -in them). Any allow room that the homeserver cannot verify the membership should -be treated as if the user is not in that room. If the user is not in any of the -rooms (or some of the rooms cannot be verified) the homeserver should reject the -join, as above. The requesting server may wish to attempt to join via another -homeserver. If no servers are in any of the allowed rooms its membership cannot -be verified (and this is a misconfiguration). - -TODO Better define errors over federation. +It is possible for a resident homeserver (one which receives a `/make_join` / +`/send_join` request to not know if the user is in some of the allowed rooms (due +to not participating in them). If the user is not in any of the allowed rooms that +are known to the homeserver it should return an error response with HTTP status code +of 400 with an `errcode` of `M_CANNOT_ALLOW`. The joining server should attempt to +join via another resident homeserver. If the resident homeserver knows that the +user is not in *any* of the allowed rooms it should return an error response with +HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a +configuration error if there are allowed rooms with no participating authorised +servers. From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional From 55b99d29e4a7df3a77e298b95d9e977882c361be Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 19 Jul 2021 15:10:29 -0400 Subject: [PATCH 124/162] Clarify if a resident server cannot issue a join vs. if they're unsure if the user is allowed to join. --- proposals/3083-restricted-rooms.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index d739c48e9..8e7c82fe7 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -67,13 +67,18 @@ It is possible for a resident homeserver (one which receives a `/make_join` / `/send_join` request to not know if the user is in some of the allowed rooms (due to not participating in them). If the user is not in any of the allowed rooms that are known to the homeserver it should return an error response with HTTP status code -of 400 with an `errcode` of `M_CANNOT_ALLOW`. The joining server should attempt to -join via another resident homeserver. If the resident homeserver knows that the -user is not in *any* of the allowed rooms it should return an error response with -HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a +of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should +attempt to join via another resident homeserver. If the resident homeserver knows +that the user is not in *any* of the allowed rooms it should return an error response +with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a configuration error if there are allowed rooms with no participating authorised servers. +A chosen resident homeserver might also be unable to issue invites, in this case +it should return an error response with HTTP status code of 400 and an `errcode` +of `M_CANNOT_ALLOW`. The joining server should attempt to join via another +resident homeserver. + From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional caveat that servers must ensure that: From 48c1d9d99838e10272904564ab82100c36ec20a9 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 12:28:55 -0400 Subject: [PATCH 125/162] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 8e7c82fe7..83073f216 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -64,7 +64,7 @@ the user is not a member of at least one of the rooms, the homeserver should ret an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. It is possible for a resident homeserver (one which receives a `/make_join` / -`/send_join` request to not know if the user is in some of the allowed rooms (due +`/send_join` request) to not know if the user is in some of the allowed rooms (due to not participating in them). If the user is not in any of the allowed rooms that are known to the homeserver it should return an error response with HTTP status code of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should @@ -74,7 +74,7 @@ with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is configuration error if there are allowed rooms with no participating authorised servers. -A chosen resident homeserver might also be unable to issue invites, in this case +A chosen resident homeserver might also be unable to issue invites; in this case it should return an error response with HTTP status code of 400 and an `errcode` of `M_CANNOT_ALLOW`. The joining server should attempt to join via another resident homeserver. @@ -84,7 +84,7 @@ the `restricted` join rule has the same behavior as `public`, with the additiona caveat that servers must ensure that: * The user's previous membership was `invite` or `join`, or -* The `m.room.member` event with a `membership` of `join` has a valid signature +* The join event has a valid signature from a homeserver whose users have the power to issue invites. This implies that: From 88a94049d29179f1a8a1a531ee121389804258af Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 13:23:17 -0400 Subject: [PATCH 126/162] Review feedback. --- proposals/3083-restricted-rooms.md | 60 ++++++++++++++++-------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 83073f216..923477dcc 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -63,45 +63,35 @@ if the user is invited to this room, or is joined to one of the listed rooms. If the user is not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. -It is possible for a resident homeserver (one which receives a `/make_join` / -`/send_join` request) to not know if the user is in some of the allowed rooms (due -to not participating in them). If the user is not in any of the allowed rooms that -are known to the homeserver it should return an error response with HTTP status code -of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should -attempt to join via another resident homeserver. If the resident homeserver knows -that the user is not in *any* of the allowed rooms it should return an error response -with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a -configuration error if there are allowed rooms with no participating authorised -servers. - -A chosen resident homeserver might also be unable to issue invites; in this case -it should return an error response with HTTP status code of 400 and an `errcode` -of `M_CANNOT_ALLOW`. The joining server should attempt to join via another -resident homeserver. - From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional caveat that servers must ensure that: * The user's previous membership was `invite` or `join`, or -* The join event has a valid signature - from a homeserver whose users have the power to issue invites. This implies - that: +* The join event has a valid signature from a homeserver whose users have the + power to issue invites. + + When generating a join event the server should include the MXID of a local user + who could issue an invite in the content with the key + `join_authorised_via_users_server`. The actual user chosen is arbitrary. + + This implies that: * A join event issued via `/send_join` is signed by not just the requesting server, but also the resident server.[3](#f3) In order for the joining server to receive the proper signatures the join event will be returned via `/send_join` in the `event` field. - * The auth chain of the join event needs to include an event which proves - the homeserver can be issuing the join. This can be done by including the - `m.room.power_levels` event and an `m.room.member` event with `membership` - equal to `join` for a member who could issue invites from that server. + * The auth chain of the join event needs to include events which prove + the homeserver can be issuing the join. This can be done by including: - In order to find a corresponding event quickly for verification, the - content of the join event should include the chosen user's MXID in the - content with the key `join_authorised_via_users_server`. The actual user - chosen is arbitrary. + * The `m.room.power_levels` event + * The `m.room.member` event (with `membership` equal to `join`) the user + specified in `join_authorised_via_users_server`. + + It should be confirmed that the authorising user is in the room. (This + prevents situations where any homeserver could process the join, even if + they weren't in the room, under certain power level conditions.) This creates a new restriction on the relationship between the resident servers used for `/make_join` and `/send_join` -- they must now both go to @@ -113,6 +103,22 @@ Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[4](#f4) +It is possible for a resident homeserver (one which receives a `/make_join` / +`/send_join` request) to not know if the user is in some of the allowed rooms (due +to not participating in them). If the user is not in any of the allowed rooms that +are known to the homeserver it should return an error response with HTTP status code +of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should +attempt to join via another resident homeserver. If the resident homeserver knows +that the user is not in *any* of the allowed rooms it should return an error response +with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a +configuration error if there are allowed rooms with no participating authorised +servers. + +A chosen resident homeserver might also be unable to issue invites; in this case +it should return an error response with HTTP status code of 400 and an `errcode` +of `M_CANNOT_ALLOW`. The joining server should attempt to join via another +resident homeserver. + To better cope with joining via aliases, homeservers should use the list of authorised servers (not the list of candidate servers) when a user attempts to join a room. From c0b7f0762e093eb5e3be704d89c05f83ca0e015b Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 13:36:26 -0400 Subject: [PATCH 127/162] Move back section about errors for make/send_join & some review comments. --- proposals/3083-restricted-rooms.md | 36 +++++++++++++++--------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 923477dcc..8c1f5b6b2 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -63,6 +63,23 @@ if the user is invited to this room, or is joined to one of the listed rooms. If the user is not a member of at least one of the rooms, the homeserver should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. +It is possible for a resident homeserver (one which receives a `/make_join` / +`/send_join` request) to not know if the user is in some of the allowed rooms (due +to not participating in them). If the user is not in any of the allowed rooms that +are known to the homeserver it should return an error response with HTTP status code +of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should +attempt to join via another resident homeserver. If the resident homeserver knows +that the user is not in *any* of the allowed rooms it should return an error response +with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a +configuration error if there are allowed rooms with no participating authorised +servers. + +A chosen resident homeserver might also be unable to issue invites (which, as below, +is a pre-requisite for generating a correctly-signed join event). In this case +it should return an error response with HTTP status code of 400 and an `errcode` +of `M_CANNOT_ALLOW`. The joining server should attempt to join via another +resident homeserver. + From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional caveat that servers must ensure that: @@ -86,8 +103,7 @@ caveat that servers must ensure that: the homeserver can be issuing the join. This can be done by including: * The `m.room.power_levels` event - * The `m.room.member` event (with `membership` equal to `join`) the user - specified in `join_authorised_via_users_server`. + * The join event of the user specified in `join_authorised_via_users_server`. It should be confirmed that the authorising user is in the room. (This prevents situations where any homeserver could process the join, even if @@ -103,22 +119,6 @@ Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be enforced over federation by event authorisation).[4](#f4) -It is possible for a resident homeserver (one which receives a `/make_join` / -`/send_join` request) to not know if the user is in some of the allowed rooms (due -to not participating in them). If the user is not in any of the allowed rooms that -are known to the homeserver it should return an error response with HTTP status code -of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should -attempt to join via another resident homeserver. If the resident homeserver knows -that the user is not in *any* of the allowed rooms it should return an error response -with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a -configuration error if there are allowed rooms with no participating authorised -servers. - -A chosen resident homeserver might also be unable to issue invites; in this case -it should return an error response with HTTP status code of 400 and an `errcode` -of `M_CANNOT_ALLOW`. The joining server should attempt to join via another -resident homeserver. - To better cope with joining via aliases, homeservers should use the list of authorised servers (not the list of candidate servers) when a user attempts to join a room. From 77422e211f8956b14d327a78de02f6aa45656883 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 13:37:40 -0400 Subject: [PATCH 128/162] Move changes to make/send_join out of auth rules section. --- proposals/3083-restricted-rooms.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 8c1f5b6b2..3e4a33f07 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -109,11 +109,11 @@ caveat that servers must ensure that: prevents situations where any homeserver could process the join, even if they weren't in the room, under certain power level conditions.) - This creates a new restriction on the relationship between the resident - servers used for `/make_join` and `/send_join` -- they must now both go to - the same server (since the `join_authorised_via_users_server` is added in - the call to `/make_join`, while the final signature is added during - the call to `/send_join`). +The above creates a new restriction on the relationship between the resident +servers used for `/make_join` and `/send_join` -- they must now both go to +the same server (since the `join_authorised_via_users_server` is added in +the call to `/make_join`, while the final signature is added during +the call to `/send_join`). Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be From 3885a9446498166cc459d4dab57dd9a37727ab32 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 13:41:05 -0400 Subject: [PATCH 129/162] Include an additional error situation. --- proposals/3083-restricted-rooms.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 3e4a33f07..cbb2a2684 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -113,7 +113,9 @@ The above creates a new restriction on the relationship between the resident servers used for `/make_join` and `/send_join` -- they must now both go to the same server (since the `join_authorised_via_users_server` is added in the call to `/make_join`, while the final signature is added during -the call to `/send_join`). +the call to `/send_join`). If a request to `/send_join` is received that includes +an event from a different resident server it should return an error response with +HTTP status code of 400. Note that the homeservers whose users can issue invites are trusted to confirm that the `allow` rules were properly checked (since this cannot easily be From d9cae9bac0643f9ccb8f2d478a991beb541f8828 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 20 Jul 2021 13:42:57 -0400 Subject: [PATCH 130/162] More review comments. --- proposals/3083-restricted-rooms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index cbb2a2684..a2c5f6633 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -77,7 +77,7 @@ servers. A chosen resident homeserver might also be unable to issue invites (which, as below, is a pre-requisite for generating a correctly-signed join event). In this case it should return an error response with HTTP status code of 400 and an `errcode` -of `M_CANNOT_ALLOW`. The joining server should attempt to join via another +of `M_UNABLE_TO_GRANT_JOIN`. The joining server should attempt to join via another resident homeserver. From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), @@ -88,9 +88,9 @@ caveat that servers must ensure that: * The join event has a valid signature from a homeserver whose users have the power to issue invites. - When generating a join event the server should include the MXID of a local user - who could issue an invite in the content with the key - `join_authorised_via_users_server`. The actual user chosen is arbitrary. + When generating a join event for `/join` or `/make_join`, the server should + include the MXID of a local user who could issue an invite in the content with + the key `join_authorised_via_users_server`. The actual user chosen is arbitrary. This implies that: From d12886912e95277e5a8fc7a4858d7edf8a42dd43 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 21 Jul 2021 07:38:27 -0400 Subject: [PATCH 131/162] Fix typos. Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index a2c5f6633..da21da92a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -57,7 +57,7 @@ Any entries in the list which do not match the expected format are ignored. Thus if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. -When an homeserver receives a `/join` request from a client or a `/make_join` / +When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from another homeserver, the request should only be permitted if the user is invited to this room, or is joined to one of the listed rooms. If the user is not a member of at least one of the rooms, the homeserver should return @@ -102,7 +102,7 @@ caveat that servers must ensure that: * The auth chain of the join event needs to include events which prove the homeserver can be issuing the join. This can be done by including: - * The `m.room.power_levels` event + * The `m.room.power_levels` event. * The join event of the user specified in `join_authorised_via_users_server`. It should be confirmed that the authorising user is in the room. (This @@ -182,7 +182,7 @@ generating a join event. Peeking over federation, as described in could be used to establish if the user is in any of the proper rooms. This would then delegate power out to a (potentially) untrusted server, giving that -the peek server significant power. For example, a poorly chosen peek +peek server significant power. For example, a poorly chosen peek server could lie about the room membership and add an `@evil_user:example.org` to an allowed room to gain membership to a room. @@ -193,7 +193,7 @@ the requesting homeserver to retry via another homeserver. In the above example, suppose `@bob:server.example` leaves `!users:example.org`: should they be removed from the room? Likely not, by analogy with what happens -when you switch the join rules from public to invite. Join rules currently govern +when you switch the join rules from `public` to `invite`. Join rules currently govern joins, not existing room membership. It is left to a future MSC to consider this, but some potential thoughts are @@ -209,7 +209,7 @@ Another consideration is that users may have joined via a direct invite, not via access through a room. Fixing this is thorny. Some sort of annotation on the membership events might -help. but it's unclear what the desired semantics are: +help, but it's unclear what the desired semantics are: * Assuming that users in an allowed room are *not* kicked when that room is removed from `allow`, are those users then given a pass to remain @@ -236,7 +236,7 @@ restricting access via: * MXIDs or servers. * A shared secret (room password). -These are just examples are not fully thought through for this MSC, but it should +These are just examples and are not fully thought through for this MSC, but it should be possible to add these behaviors in the future. ### Client considerations From 2e7db4ac02e4a61dd86a19991fd884c8f3abac00 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 21 Jul 2021 07:41:56 -0400 Subject: [PATCH 132/162] Clarify error conditions. Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index da21da92a..44f5773a2 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -66,8 +66,8 @@ an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN` It is possible for a resident homeserver (one which receives a `/make_join` / `/send_join` request) to not know if the user is in some of the allowed rooms (due to not participating in them). If the user is not in any of the allowed rooms that -are known to the homeserver it should return an error response with HTTP status code -of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should +are known to the homeserver, and the homeserver is not participating in all listed +rooms, then it should return an error response with HTTP status code of 400 with an `errcode` of `M_UNABLE_TO_AUTHORISE_JOIN`. The joining server should attempt to join via another resident homeserver. If the resident homeserver knows that the user is not in *any* of the allowed rooms it should return an error response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`. Note that it is a From 72ffbfe0bdac92a840ea5e4745b53eba3f4e7463 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 21 Jul 2021 07:48:31 -0400 Subject: [PATCH 133/162] Rename MSC. --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 44f5773a2..4994ed06a 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -1,4 +1,4 @@ -# Restricting room membership based on space membership +# Restricting room membership based on membership in other rooms A desirable feature is to give room admins the power to restrict membership of their room based on the membership of one or more rooms. From 806d6fcc243f8b22f31dbb7fe0a80eece1451d6e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 21 Jul 2021 08:12:39 -0400 Subject: [PATCH 134/162] Add proposal for room version 8. --- proposals/3289-rooms-v8.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 proposals/3289-rooms-v8.md diff --git a/proposals/3289-rooms-v8.md b/proposals/3289-rooms-v8.md new file mode 100644 index 000000000..e766e1e04 --- /dev/null +++ b/proposals/3289-rooms-v8.md @@ -0,0 +1,15 @@ +# MSC3289: Room Version 8 + +A new room version, `8`, is proposed using [room version 7](https://spec.matrix.org/unstable/rooms/v7/) +as a base and incorporating the following MSCs: + +* [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) - Restricting room + membership based on membership in other rooms + +Though other MSCs are capable of being included in this version, they do not have +sufficient implementation to be considered for this room version. A future room +version may include them. + +Room version `8` upon being added to the specification shall be considered stable. +No other room versions are affected by this MSC. Before room version `8` can enter +the specification, MSC3083 needs complete its final comment period. From 2a92acc59da1306c49e31d3c2ee97c57cb188a9d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Wed, 21 Jul 2021 13:42:24 +0100 Subject: [PATCH 135/162] Update 3289-rooms-v8.md --- proposals/3289-rooms-v8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3289-rooms-v8.md b/proposals/3289-rooms-v8.md index e766e1e04..7212e0a8c 100644 --- a/proposals/3289-rooms-v8.md +++ b/proposals/3289-rooms-v8.md @@ -12,4 +12,4 @@ version may include them. Room version `8` upon being added to the specification shall be considered stable. No other room versions are affected by this MSC. Before room version `8` can enter -the specification, MSC3083 needs complete its final comment period. +the specification, MSC3083 needs to complete its final comment period. From 31a9b2a72072633d43d6964a94d0e753c5f0d4de Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 22 Jul 2021 10:17:37 -0400 Subject: [PATCH 136/162] Clarifications. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3083-restricted-rooms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 4994ed06a..a8b2af3d0 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -82,7 +82,7 @@ resident homeserver. From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules), the `restricted` join rule has the same behavior as `public`, with the additional -caveat that servers must ensure that: +caveat that servers must ensure that, for `m.room.member` events with a `membership` of `join`: * The user's previous membership was `invite` or `join`, or * The join event has a valid signature from a homeserver whose users have the From db089aa1f5e7a400120194929353f037eb5f711d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 22 Jul 2021 10:18:14 -0400 Subject: [PATCH 137/162] De-indent section. --- proposals/3083-restricted-rooms.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index a8b2af3d0..501625a56 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -92,22 +92,22 @@ caveat that servers must ensure that, for `m.room.member` events with a `members include the MXID of a local user who could issue an invite in the content with the key `join_authorised_via_users_server`. The actual user chosen is arbitrary. - This implies that: +The changes to the auth rules imply that: - * A join event issued via `/send_join` is signed by not just the requesting - server, but also the resident server.[3](#f3) +* A join event issued via `/send_join` is signed by not just the requesting + server, but also the resident server.[3](#f3) - In order for the joining server to receive the proper signatures the join - event will be returned via `/send_join` in the `event` field. - * The auth chain of the join event needs to include events which prove - the homeserver can be issuing the join. This can be done by including: + In order for the joining server to receive the proper signatures the join + event will be returned via `/send_join` in the `event` field. +* The auth chain of the join event needs to include events which prove + the homeserver can be issuing the join. This can be done by including: - * The `m.room.power_levels` event. - * The join event of the user specified in `join_authorised_via_users_server`. + * The `m.room.power_levels` event. + * The join event of the user specified in `join_authorised_via_users_server`. - It should be confirmed that the authorising user is in the room. (This - prevents situations where any homeserver could process the join, even if - they weren't in the room, under certain power level conditions.) + It should be confirmed that the authorising user is in the room. (This + prevents situations where any homeserver could process the join, even if + they weren't in the room, under certain power level conditions.) The above creates a new restriction on the relationship between the resident servers used for `/make_join` and `/send_join` -- they must now both go to From 9699aa87f632bc393b29a7fd29258e309192fb81 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 23 Jul 2021 07:19:09 -0400 Subject: [PATCH 138/162] Note unstable prefix. --- proposals/3083-restricted-rooms.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 501625a56..941e2f483 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -157,6 +157,9 @@ During development, an unstable room version of `org.matrix.msc3083.v2` will be Since the room version namespaces the behaviour, the `allow` key and value, as well as the `restricted` join rule value do not need unstable prefixes. +An unstable key of `org.matrix.msc3083.v2.event` will be used in the response +from `/send_join` in place of `event` during development. + ## Alternatives It may seem that just having the `allow` key with `public` join rules is enough From 203c107e9e689b7b7812846f78f4712b9ca22539 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 27 Jul 2021 09:40:05 -0400 Subject: [PATCH 139/162] Update redaction rules. --- proposals/3289-rooms-v8.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/3289-rooms-v8.md b/proposals/3289-rooms-v8.md index 7212e0a8c..1589da080 100644 --- a/proposals/3289-rooms-v8.md +++ b/proposals/3289-rooms-v8.md @@ -13,3 +13,10 @@ version may include them. Room version `8` upon being added to the specification shall be considered stable. No other room versions are affected by this MSC. Before room version `8` can enter the specification, MSC3083 needs to complete its final comment period. + +## Updated redaction rules + +Room version 8 shall update the redaction rules for the `m.room.join_rules` event. +[Room version 1](https://spec.matrix.org/unstable/rooms/v1/#redactions) defines +that only the `join_rule` key in the content object should be kept. Room version +8 defines that both the `join_rule` and `allow` keys of the content shall be kept. From 7d0e931a38acfa74d38b16038cc0190dbca8479f Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Fri, 11 Jun 2021 12:37:54 +0200 Subject: [PATCH 140/162] OpenAPI: require all bodies in client-server Signed-off-by: Lukas Lihotzki --- changelogs/client_server/newsfragments/3238.clarification | 1 + data/api/client-server/receipts.yaml | 1 + data/api/client-server/report_content.yaml | 1 + data/api/client-server/room_send.yaml | 1 + data/api/client-server/room_state.yaml | 1 + data/api/client-server/users.yaml | 1 + 6 files changed, 6 insertions(+) create mode 100644 changelogs/client_server/newsfragments/3238.clarification diff --git a/changelogs/client_server/newsfragments/3238.clarification b/changelogs/client_server/newsfragments/3238.clarification new file mode 100644 index 000000000..63e54ba6c --- /dev/null +++ b/changelogs/client_server/newsfragments/3238.clarification @@ -0,0 +1 @@ +Clarify that all request bodies are required. diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 716946ace..66610092b 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -61,6 +61,7 @@ paths: description: |- Extra receipt information to attach to `content` if any. The server will automatically set the `ts` field. + required: true schema: type: object example: { diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 380995ead..19d6b6d0c 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -49,6 +49,7 @@ paths: x-example: "$something:example.org" - in: body name: body + required: true schema: type: object example: { diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml index c22fcfe47..18658f612 100644 --- a/data/api/client-server/room_send.yaml +++ b/data/api/client-server/room_send.yaml @@ -65,6 +65,7 @@ paths: x-example: "35" - in: body name: body + required: true schema: type: object example: { diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index 381c5c57e..016a82736 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -74,6 +74,7 @@ paths: x-example: "@alice:example.com" - in: body name: body + required: true schema: type: object example: { diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index 255c538b1..31bc971c8 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -47,6 +47,7 @@ paths: parameters: - in: body name: body + required: true schema: type: object properties: From 20e07cab025f4f3fa7abc1a2505a86a1fe0563d8 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 27 Jul 2021 12:17:39 -0400 Subject: [PATCH 141/162] Add note about redacting the allow key. --- proposals/3083-restricted-rooms.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3083-restricted-rooms.md b/proposals/3083-restricted-rooms.md index 941e2f483..1caa9f970 100644 --- a/proposals/3083-restricted-rooms.md +++ b/proposals/3083-restricted-rooms.md @@ -57,6 +57,8 @@ Any entries in the list which do not match the expected format are ignored. Thus if all entries are invalid, the list behaves as if empty and all users without an invite are rejected. +The `allow` key is to be protected when redacting an event. + When a homeserver receives a `/join` request from a client or a `/make_join` / `/send_join` request from another homeserver, the request should only be permitted if the user is invited to this room, or is joined to one of the listed rooms. If From 0a016466c61856b8c402e3792ccf8cad55afc99f Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 27 Jul 2021 12:28:20 -0400 Subject: [PATCH 142/162] Revert "Update redaction rules." This reverts commit 203c107e9e689b7b7812846f78f4712b9ca22539. --- proposals/3289-rooms-v8.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/proposals/3289-rooms-v8.md b/proposals/3289-rooms-v8.md index 1589da080..7212e0a8c 100644 --- a/proposals/3289-rooms-v8.md +++ b/proposals/3289-rooms-v8.md @@ -13,10 +13,3 @@ version may include them. Room version `8` upon being added to the specification shall be considered stable. No other room versions are affected by this MSC. Before room version `8` can enter the specification, MSC3083 needs to complete its final comment period. - -## Updated redaction rules - -Room version 8 shall update the redaction rules for the `m.room.join_rules` event. -[Room version 1](https://spec.matrix.org/unstable/rooms/v1/#redactions) defines -that only the `join_rule` key in the content object should be kept. Room version -8 defines that both the `join_rule` and `allow` keys of the content shall be kept. From 729812fe050e2368326074453e0874f1d196e4db Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Thu, 5 Aug 2021 11:49:18 +0100 Subject: [PATCH 143/162] `/_matrix/federation/v1/user/devices/{userId}`: Rename `self_signing_keys` to `self_signing_key` (#3312) Apparently, in response to a /_matrix/federation/v1/user/devices/{userId} request, Synapse actually returns a key called "self_signing_key" instead of "self_signing_keys". --- changelogs/server_server/newsfragments/3312.clarification | 1 + data/api/server-server/user_devices.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/3312.clarification diff --git a/changelogs/server_server/newsfragments/3312.clarification b/changelogs/server_server/newsfragments/3312.clarification new file mode 100644 index 000000000..a9e1fe8df --- /dev/null +++ b/changelogs/server_server/newsfragments/3312.clarification @@ -0,0 +1 @@ +Correct the `/_matrix/federation/v1/user/devices/{userId}` response which actually returns `"self_signing_key"` instead of `"self_signing_keys"`. diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 0c2348dab..9fb15777f 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -96,7 +96,7 @@ paths: "ed25519:base64+master+public+key": "base64+master+public+key", } } - self_signing_keys: + self_signing_key: type: object description: |- The user\'s self-signing key. From 29465f35198e3625079cc4c185902aff50e3ad10 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Mon, 9 Aug 2021 08:54:34 +0200 Subject: [PATCH 144/162] OpenAPI: use uri format In avatar_url, pusher url, wellknown base_url, getUrlPreview, and submit_url. Signed-off-by: Lukas Lihotzki --- data/api/client-server/administrative_contact.yaml | 1 + data/api/client-server/content-repo.yaml | 3 +++ data/api/client-server/definitions/public_rooms_response.yaml | 3 ++- data/api/client-server/definitions/request_token_response.yaml | 1 + data/api/client-server/definitions/wellknown/homeserver.yaml | 1 + .../client-server/definitions/wellknown/identity_server.yaml | 1 + data/api/client-server/profile.yaml | 3 +++ data/api/client-server/pusher.yaml | 2 ++ data/api/client-server/rooms.yaml | 1 + data/api/client-server/search.yaml | 1 + data/api/client-server/users.yaml | 1 + data/event-schemas/schema/m.room.member.yaml | 1 + 12 files changed, 18 insertions(+), 1 deletion(-) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 9966015b0..f1db14db9 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -154,6 +154,7 @@ paths: properties: submit_url: type: string + format: uri description: |- An optional field containing a URL where the client must submit the validation token to, with identical parameters diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index c36fa837d..fb91c7c53 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -66,6 +66,7 @@ paths: properties: content_uri: type: string + format: uri description: "The [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content." examples: application/json: { @@ -360,6 +361,7 @@ paths: parameters: - in: query type: string + format: uri x-example: "https://matrix.org" name: url description: "The URL to get a preview of." @@ -389,6 +391,7 @@ paths: The byte-size of the image. Omitted if there is no image attached. "og:image": type: string + format: uri description: |- An [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image. examples: diff --git a/data/api/client-server/definitions/public_rooms_response.yaml b/data/api/client-server/definitions/public_rooms_response.yaml index 8cf9935c2..406f83b0e 100644 --- a/data/api/client-server/definitions/public_rooms_response.yaml +++ b/data/api/client-server/definitions/public_rooms_response.yaml @@ -68,6 +68,7 @@ properties: rules like any other user. avatar_url: type: string + format: uri description: The URL for the room's avatar, if one is set. join_rule: type: string @@ -110,4 +111,4 @@ example: { "next_batch": "p190q", "prev_batch": "p1902", "total_room_count_estimate": 115 -} \ No newline at end of file +} diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml index b801af984..aa9379f6f 100644 --- a/data/api/client-server/definitions/request_token_response.yaml +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -22,6 +22,7 @@ properties: example: "123abc" submit_url: type: string + format: uri description: |- An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service diff --git a/data/api/client-server/definitions/wellknown/homeserver.yaml b/data/api/client-server/definitions/wellknown/homeserver.yaml index 92ff34ed3..6f6d3cb9a 100644 --- a/data/api/client-server/definitions/wellknown/homeserver.yaml +++ b/data/api/client-server/definitions/wellknown/homeserver.yaml @@ -18,6 +18,7 @@ type: object properties: base_url: type: string + format: uri description: The base URL for the homeserver for client-server connections. example: https://matrix.example.com required: diff --git a/data/api/client-server/definitions/wellknown/identity_server.yaml b/data/api/client-server/definitions/wellknown/identity_server.yaml index a8f7c31cf..a86ad8b1b 100644 --- a/data/api/client-server/definitions/wellknown/identity_server.yaml +++ b/data/api/client-server/definitions/wellknown/identity_server.yaml @@ -18,6 +18,7 @@ type: object properties: base_url: type: string + format: uri description: The base URL for the identity server for client-server connections. example: https://identity.example.com required: diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 6a8d6a775..d1d4306cf 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -129,6 +129,7 @@ paths: properties: avatar_url: type: string + format: uri description: The new avatar URL for this user. responses: 200: @@ -170,6 +171,7 @@ paths: properties: avatar_url: type: string + format: uri description: The user's avatar URL if they have set one, otherwise not present. 404: description: There is no avatar URL for this user or this user does not exist. @@ -204,6 +206,7 @@ paths: properties: avatar_url: type: string + format: uri description: The user's avatar URL if they have set one, otherwise not present. displayname: type: string diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index 69882066f..9feccb4f0 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -113,6 +113,7 @@ paths: properties: url: type: string + format: uri description: |- Required if `kind` is `http`. The URL to use to send notifications to. @@ -220,6 +221,7 @@ paths: properties: url: type: string + format: uri description: |- Required if `kind` is `http`. The URL to use to send notifications to. MUST be an HTTPS URL with a path of diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index f8931893e..2f161e2bf 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -303,6 +303,7 @@ paths: description: The display name of the user this object is representing. avatar_url: type: string + format: uri description: The mxc avatar url of the user this object is representing. description: A map from user ID to a RoomMember object. type: object diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 1dc9804e2..8bc255286 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -238,6 +238,7 @@ paths: title: Display name avatar_url: type: string + format: uri title: Avatar Url events_before: type: array diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index 31bc971c8..4a264f3a1 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -96,6 +96,7 @@ paths: description: The display name of the user, if one exists. avatar_url: type: string + format: uri example: "mxc://bar.com/foo" description: The avatar url, as an MXC, if one exists. limited: diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index 928e1528f..37975cbe1 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -45,6 +45,7 @@ properties: avatar_url: description: 'The avatar URL for this user, if any.' type: string + format: uri displayname: description: 'The display name for this user, if any.' type: From e7e0455e276337b7ddb0e04b42d5b3d40bb56081 Mon Sep 17 00:00:00 2001 From: Niels Basjes Date: Tue, 10 Aug 2021 13:51:29 +0200 Subject: [PATCH 145/162] Explain the reasons why `` TLS certificate is needed rather than `` for SRV delegation. (#3322) Signed-off-by: Niels Basjes --- .../server_server/newsfragments/3322.clarification | 1 + content/server-server-api.md | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 changelogs/server_server/newsfragments/3322.clarification diff --git a/changelogs/server_server/newsfragments/3322.clarification b/changelogs/server_server/newsfragments/3322.clarification new file mode 100644 index 000000000..fdcd7db9b --- /dev/null +++ b/changelogs/server_server/newsfragments/3322.clarification @@ -0,0 +1 @@ +Explain the reasons why `` TLS certificate is needed rather than `` for SRV delegation. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index 9013d6c0f..763c0e68f 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -134,6 +134,15 @@ to send. The process overall is as follows: 8448 and a `Host` header containing the ``. The target server must present a valid certificate for ``. +{{% boxes/note %}} +The reasons we require `` rather than `` for SRV +delegation are: + 1. DNS is insecure (not all domains have DNSSEC), so the target of the delegation + must prove that it is a valid delegate for `` via TLS. + 2. Consistency with the recommendations in [RFC6125](https://datatracker.ietf.org/doc/html/rfc6125#section-6.2.1) + and other applications using SRV records such [XMPP](https://datatracker.ietf.org/doc/html/rfc6120#section-13.7.2.1). +{{% /boxes/note %}} + The TLS certificate provided by the target server must be signed by a known Certificate Authority. Servers are ultimately responsible for determining the trusted Certificate Authorities, however are strongly From 0382eac23e9981926949e2cb6dca69612ad0353d Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 10 Aug 2021 18:05:28 +0100 Subject: [PATCH 146/162] Use `changelogs/release.yaml` for the version number source everywhere (#3310) Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- config.toml | 6 ++++++ layouts/partials/navbar.html | 6 ++++-- .../changelog/changelog-changes.html | 20 +++++++++++-------- .../changelog/changelog-description.html | 6 +++++- 4 files changed, 27 insertions(+), 11 deletions(-) diff --git a/config.toml b/config.toml index 1e4cb70e7..c18c024eb 100644 --- a/config.toml +++ b/config.toml @@ -43,7 +43,13 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release status = "unstable" +# A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://matrix.org/docs/spec/" +# The following is used when status = "stable", and is displayed in various UI elements on a released version +# of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. +#major = "1" +#minor = "0" +#release_date = "April 01, 2021" # User interface configuration [params.ui] diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html index 8a7364401..e78ee9c41 100644 --- a/layouts/partials/navbar.html +++ b/layouts/partials/navbar.html @@ -45,8 +45,10 @@ {{ $status := .Site.Params.version.status }} {{ if ne $status "unstable"}} - {{ $ret = .Site.Params.version.number }} - {{ $ret = delimit (slice "version" $ret) " " }} + {{ $path := path.Join "changelogs" }} + + {{/* produces a string similar to "version v1.5" */}} + {{ $ret = delimit (slice "version v" .Site.Params.version.major "." .Site.Params.version.minor) "" }} {{ end }} {{ return $ret }} diff --git a/layouts/shortcodes/changelog/changelog-changes.html b/layouts/shortcodes/changelog/changelog-changes.html index a1e277283..11a598580 100644 --- a/layouts/shortcodes/changelog/changelog-changes.html +++ b/layouts/shortcodes/changelog/changelog-changes.html @@ -7,22 +7,26 @@ it expects to find newsfragments describing changes to that API. If the `version.status` setting in config.toml is anything other than - "unstable", then it also expects to find a "release.yaml" file in /changelogs, - which contains: - - `tag`: Git tag for this release - - `date`: date of this release - It then renders this info a table, before the list of changes. + "unstable", then it also expects to find additional settings under + `version` in config.toml: + - `major`: the major version number of the release + - `minor`: the minor version number of the release + - `release_date`: the date of the release + + The release tag is calculated as `v.`; for example `v1.5`. + + It then renders this into a table displayed before the list of changes. */}} {{ $path := path.Join "changelogs" }} {{ $status := .Site.Params.version.status }} +{{ $release_tag := delimit (slice "v" .Site.Params.version.major "." .Site.Params.version.minor) "" }} {{ if ne $status "unstable" }} -{{ $release_info := readFile (path.Join $path "release.yaml") | transform.Unmarshal }} - - + +
Git commithttps://github.com/matrix-org/matrix-doc/tree/{{ $release_info.tag }}
Release date{{ $release_info.date }}
Git commithttps://github.com/matrix-org/matrix-doc/tree/{{ $release_tag }}
Release date{{ .Site.Params.version.release_date }}
{{ end }} diff --git a/layouts/shortcodes/changelog/changelog-description.html b/layouts/shortcodes/changelog/changelog-description.html index 738ff675b..3c7197252 100644 --- a/layouts/shortcodes/changelog/changelog-description.html +++ b/layouts/shortcodes/changelog/changelog-description.html @@ -8,8 +8,12 @@ {{ $status := .Site.Params.version.status }} {{ if eq $status "unstable"}} +

This is the unstable version of the Matrix specification.

This changelog lists changes made since the last release of the specification.

+ {{ else }} -

This is version {{ .Site.Params.version.number }} of the Matrix specification.

+ +

This is version v{{ .Site.Params.version.major }}.{{ .Site.Params.version.minor }} of the Matrix specification.

+ {{ end }} From fa6e6112830311c9a5d5733ef718472fa442de0e Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Tue, 10 Aug 2021 20:24:59 +0200 Subject: [PATCH 147/162] OpenAPI: fix key_backup operation IDs --- .../client_server/newsfragments/3327.breaking | 1 + data/api/client-server/key_backup.yaml | 40 +++++++++---------- 2 files changed, 21 insertions(+), 20 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3327.breaking diff --git a/changelogs/client_server/newsfragments/3327.breaking b/changelogs/client_server/newsfragments/3327.breaking new file mode 100644 index 000000000..85c0da8ba --- /dev/null +++ b/changelogs/client_server/newsfragments/3327.breaking @@ -0,0 +1 @@ +Fix key_backup operation IDs in OpenAPI spec. diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 7c42f6b53..73044c6d1 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -375,7 +375,7 @@ paths: summary: Store a key in the backup. description: |- Store a key in the backup. - operationId: postRoomKeysKeyRoomIdSessionId + operationId: putRoomKeysBySessionId security: - accessToken: [] parameters: @@ -443,10 +443,10 @@ paths: tags: - End-to-end encryption get: - summary: Retrieve a key from the backup + summary: Retrieve a key from the backup. description: |- Retrieve a key from the backup. - operationId: getRoomKeysKeyRoomIdSessionId + operationId: getRoomKeysBySessionId security: - accessToken: [] parameters: @@ -488,10 +488,10 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" delete: - summary: Delete a key from the backup + summary: Delete a key from the backup. description: |- Delete a key from the backup. - operationId: deleteRoomKeysKeyRoomIdSessionId + operationId: deleteRoomKeysBySessionId security: - accessToken: [] parameters: @@ -551,8 +551,8 @@ paths: put: summary: Store several keys in the backup for a given room. description: |- - Store a key in the backup. - operationId: postRoomKeysKeyRoomId + Store several keys in the backup for a given room. + operationId: putRoomKeysByRoomId security: - accessToken: [] parameters: @@ -624,10 +624,10 @@ paths: tags: - End-to-end encryption get: - summary: Retrieve the keys from the backup for a given room + summary: Retrieve the keys from the backup for a given room. description: |- - Retrieve the keys from the backup for a given room - operationId: getRoomKeysKeyRoomId + Retrieve the keys from the backup for a given room. + operationId: getRoomKeysByRoomId security: - accessToken: [] parameters: @@ -667,10 +667,10 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" delete: - summary: Delete a key from the backup + summary: Delete the keys from the backup for a given room. description: |- - Delete a key from the backup. - operationId: deleteRoomKeysKeyRoomId + Delete the keys from the backup for a given room. + operationId: deleteRoomKeysByRoomId security: - accessToken: [] parameters: @@ -725,7 +725,7 @@ paths: summary: Store several keys in the backup. description: |- Store several keys in the backup. - operationId: postRoomKeysKey + operationId: putRoomKeys security: - accessToken: [] parameters: @@ -817,10 +817,10 @@ paths: tags: - End-to-end encryption get: - summary: Retrieve the keys from the backup for a given room + summary: Retrieve the keys from the backup. description: |- - Retrieve the keys from the backup for a given room - operationId: getRoomKeysKeyRoomId + Retrieve the keys from the backup. + operationId: getRoomKeys security: - accessToken: [] parameters: @@ -876,10 +876,10 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" delete: - summary: Delete a key from the backup + summary: Delete the keys from the backup. description: |- - Delete a key from the backup. - operationId: deleteRoomKeysKeyRoomId + Delete the keys from the backup. + operationId: deleteRoomKeys security: - accessToken: [] parameters: From 0c4b7ad5f08e5421ff83d54c4e86dda8be1f61e9 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Thu, 12 Aug 2021 19:50:00 +0200 Subject: [PATCH 148/162] OpenAPI: add auth property in uploadCrossSigningKeys Signed-off-by: Lukas Lihotzki --- changelogs/client_server/newsfragments/3331.clarification | 1 + data/api/client-server/cross_signing.yaml | 6 ++++++ 2 files changed, 7 insertions(+) create mode 100644 changelogs/client_server/newsfragments/3331.clarification diff --git a/changelogs/client_server/newsfragments/3331.clarification b/changelogs/client_server/newsfragments/3331.clarification new file mode 100644 index 000000000..4e0836b88 --- /dev/null +++ b/changelogs/client_server/newsfragments/3331.clarification @@ -0,0 +1 @@ +Add auth property to UIA endpoint uploadCrossSigningKeys. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index a0516ef2c..c4c4d10f8 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -66,6 +66,12 @@ paths: request. allOf: - $ref: definitions/cross_signing_key.yaml + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" example: { "master_key": { "user_id": "@alice:example.com", From 73112677c8a874bfa12c32d5e27686e2d728c6a0 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Thu, 12 Aug 2021 19:56:22 +0200 Subject: [PATCH 149/162] OpenAPI: require all bodies in cross_signing Signed-off-by: Lukas Lihotzki --- changelogs/client_server/newsfragments/3332.clarification | 1 + data/api/client-server/cross_signing.yaml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/3332.clarification diff --git a/changelogs/client_server/newsfragments/3332.clarification b/changelogs/client_server/newsfragments/3332.clarification new file mode 100644 index 000000000..63e54ba6c --- /dev/null +++ b/changelogs/client_server/newsfragments/3332.clarification @@ -0,0 +1 @@ +Clarify that all request bodies are required. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index a0516ef2c..122782a56 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -42,6 +42,7 @@ paths: name: keys description: |- The keys to be published. + required: true schema: type: object properties: @@ -143,6 +144,7 @@ paths: name: signatures description: |- The signatures to be published. + required: true schema: type: object title: Signatures From 3497a8d8cc7c50dd4d5a4844318f35bfce366b99 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Tue, 10 Aug 2021 19:24:37 +0200 Subject: [PATCH 150/162] OpenAPI: add missing tags peekEvents remains untagged, because it is explicitly excluded. Signed-off-by: Lukas Lihotzki --- data/api/client-server/administrative_contact.yaml | 4 ++++ data/api/client-server/cross_signing.yaml | 4 ++++ data/api/client-server/key_backup.yaml | 12 ++++++++++++ data/api/client-server/list_public_rooms.yaml | 4 ++++ data/api/client-server/registration.yaml | 8 ++++++++ data/api/client-server/sso_login_redirect.yaml | 4 ++++ data/api/client-server/third_party_lookup.yaml | 12 ++++++++++++ 7 files changed, 48 insertions(+) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index f1db14db9..313ce17d1 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -470,6 +470,8 @@ paths: "errcode": "M_THREEPID_IN_USE", "error": "Third party identifier already in use" } + tags: + - User data "/account/3pid/msisdn/requestToken": post: summary: Begins the validation process for a phone number for association with the user's account. @@ -518,3 +520,5 @@ paths: "errcode": "M_THREEPID_IN_USE", "error": "Third party identifier already in use" } + tags: + - User data diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index a0516ef2c..6f83606bf 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -129,6 +129,8 @@ paths: "errcode": "M_FORBIDDEN", "error": "Key ID in use" } + tags: + - End-to-end encryption "/keys/signatures/upload": post: summary: Upload cross-signing signatures. @@ -222,3 +224,5 @@ paths: } } } + tags: + - End-to-end encryption diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 7c42f6b53..08f3b20bf 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -487,6 +487,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption delete: summary: Delete a key from the backup description: |- @@ -547,6 +549,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption "/room_keys/keys/{roomId}": put: summary: Store several keys in the backup for a given room. @@ -666,6 +670,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption delete: summary: Delete a key from the backup description: |- @@ -720,6 +726,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption "/room_keys/keys": put: summary: Store several keys in the backup. @@ -875,6 +883,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption delete: summary: Delete a key from the backup description: |- @@ -923,3 +933,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 4175b0a96..87806e04a 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -61,6 +61,8 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + tags: + - Room discovery put: summary: Sets the visibility of a room in the room directory description: |- @@ -111,6 +113,8 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + tags: + - Room discovery "/publicRooms": get: summary: Lists the public rooms on the server. diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 925ad00b8..be416e70b 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -265,6 +265,8 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + tags: + - User data "/register/msisdn/requestToken": post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account @@ -315,6 +317,8 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + tags: + - User data "/account/password": post: summary: "Changes a user's password." @@ -434,6 +438,8 @@ paths: "errcode": "M_THREEPID_NOT_FOUND", "error": "Email not found" } + tags: + - User data "/account/password/msisdn/requestToken": post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. @@ -489,6 +495,8 @@ paths: "errcode": "M_THREEPID_NOT_FOUND", "error": "Phone number not found" } + tags: + - User data "/account/deactivate": post: summary: "Deactivate a user's account." diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index f15f19e49..b58d88fe4 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -46,6 +46,8 @@ paths: headers: Location: type: "string" + tags: + - Session management "/login/sso/redirect/{idpId}": get: summary: Redirect the user's browser to the SSO interface for an IdP. @@ -83,3 +85,5 @@ paths: The IdP ID was not recognized by the server. The server is encouraged to provide a user-friendly page explaining the error given the user will be navigated to it. + tags: + - Session management diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index 3d348df2f..6f8829655 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -42,6 +42,8 @@ paths: description: The protocols supported by the homeserver. schema: $ref: ../application-service/definitions/protocol_metadata.yaml + tags: + - Third Party Lookup "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. @@ -71,6 +73,8 @@ paths: } schema: $ref: definitions/errors/error.yaml + tags: + - Third Party Lookup "/thirdparty/location/{protocol}": get: summary: Retrieve Matrix-side portals rooms leading to a third party location. @@ -112,6 +116,8 @@ paths: } schema: $ref: definitions/errors/error.yaml + tags: + - Third Party Lookup "/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix User ID of a corresponding third party user. @@ -147,6 +153,8 @@ paths: } schema: $ref: definitions/errors/error.yaml + tags: + - Third Party Lookup "/thirdparty/location": get: summary: Reverse-lookup third party locations given a Matrix room alias. @@ -177,6 +185,8 @@ paths: } schema: $ref: definitions/errors/error.yaml + tags: + - Third Party Lookup "/thirdparty/user": get: summary: Reverse-lookup third party users given a Matrix User ID. @@ -206,3 +216,5 @@ paths: } schema: $ref: definitions/errors/error.yaml + tags: + - Third Party Lookup From a1f4ab2203a989795a6df13a6e1499bb12dd810d Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Thu, 12 Aug 2021 09:09:41 +0200 Subject: [PATCH 151/162] OpenAPI: split User data tag Signed-off-by: Lukas Lihotzki --- .../client-server/administrative_contact.yaml | 16 ++++++++-------- data/api/client-server/registration.yaml | 16 ++++++++-------- data/api/client-server/users.yaml | 2 +- data/api/client-server/whoami.yaml | 2 +- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 313ce17d1..d3f0a63ab 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -87,7 +87,7 @@ paths: associated the third party identifier with the user. required: ['medium', 'address', 'validated_at', 'added_at'] tags: - - User data + - Account management post: summary: Adds contact information to the user's account. description: |- @@ -179,7 +179,7 @@ paths: schema: "$ref": "definitions/errors/error.yaml" tags: - - User data + - Account management "/account/3pid/add": post: summary: Adds contact information to the user's account. @@ -235,7 +235,7 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management "/account/3pid/bind": post: summary: Binds a 3PID to the user's account through an Identity Service. @@ -289,7 +289,7 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management "/account/3pid/delete": post: summary: Deletes a third party identifier from the user's account @@ -354,7 +354,7 @@ paths: required: - id_server_unbind_result tags: - - User data + - Account management "/account/3pid/unbind": post: summary: Removes a user's third party identifier from an identity server. @@ -418,7 +418,7 @@ paths: required: - id_server_unbind_result tags: - - User data + - Account management "/account/3pid/email/requestToken": post: summary: Begins the validation process for an email address for association with the user's account. @@ -471,7 +471,7 @@ paths: "error": "Third party identifier already in use" } tags: - - User data + - Account management "/account/3pid/msisdn/requestToken": post: summary: Begins the validation process for a phone number for association with the user's account. @@ -521,4 +521,4 @@ paths: "error": "Third party identifier already in use" } tags: - - User data + - Account management diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index be416e70b..526233fa4 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -214,7 +214,7 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management "/register/email/requestToken": post: summary: Begins the validation process for an email to be used during registration. @@ -266,7 +266,7 @@ paths: schema: "$ref": "definitions/errors/error.yaml" tags: - - User data + - Account management "/register/msisdn/requestToken": post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account @@ -318,7 +318,7 @@ paths: schema: "$ref": "definitions/errors/error.yaml" tags: - - User data + - Account management "/account/password": post: summary: "Changes a user's password." @@ -382,7 +382,7 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management "/account/password/email/requestToken": post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password @@ -439,7 +439,7 @@ paths: "error": "Email not found" } tags: - - User data + - Account management "/account/password/msisdn/requestToken": post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. @@ -496,7 +496,7 @@ paths: "error": "Phone number not found" } tags: - - User data + - Account management "/account/deactivate": post: summary: "Deactivate a user's account." @@ -573,7 +573,7 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management "/register/available": get: summary: Checks to see if a username is available on the server. @@ -635,4 +635,4 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Account management diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index 4a264f3a1..ae015e7a5 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -107,4 +107,4 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - User directory diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml index 3458c4d0d..54d9cde90 100644 --- a/data/api/client-server/whoami.yaml +++ b/data/api/client-server/whoami.yaml @@ -89,4 +89,4 @@ paths: schema: "$ref": "definitions/errors/rate_limited.yaml" tags: - - User data + - Session management From 2f5ad16230edd47f5a18026e63d002cd388178e6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 12 Aug 2021 16:44:55 -0400 Subject: [PATCH 152/162] Mention that a canonical alias event should be created if alias specified --- data/api/client-server/create_room.yaml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index fc558c03d..a3cb1176d 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -48,16 +48,19 @@ paths: (and not other members) permission to send state events. Overridden by the `power_level_content_override` parameter. - 4. Events set by the `preset`. Currently these are the `m.room.join_rules`, + 4. An `m.room.canonical_alias` event if `room_alias_name` is given and + no `m.room.canonical_alias` event is given in `initial_state`. + + 5. Events set by the `preset`. Currently these are the `m.room.join_rules`, `m.room.history_visibility`, and `m.room.guest_access` state events. - 5. Events listed in `initial_state`, in the order that they are + 6. Events listed in `initial_state`, in the order that they are listed. - 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` + 7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` state events). - 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + 8. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with `membership: invite` and `m.room.third_party_invite`). The available presets do the following with respect to room state: @@ -112,7 +115,8 @@ paths: would be `#foo:example.com`. The complete room alias will become the canonical alias for - the room. + the room and an `m.room.canonical_alias` event will be sent + into the room. name: type: string description: |- From 5a3d5a5decfda986b2f531eeef6fbebd97c47921 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 12 Aug 2021 17:18:45 -0400 Subject: [PATCH 153/162] add changelog --- changelogs/client_server/newsfragments/3337.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3337.clarification diff --git a/changelogs/client_server/newsfragments/3337.clarification b/changelogs/client_server/newsfragments/3337.clarification new file mode 100644 index 000000000..9f8eb2f25 --- /dev/null +++ b/changelogs/client_server/newsfragments/3337.clarification @@ -0,0 +1 @@ +Mention that a canonical alias event should be added when a room is created with an alias. \ No newline at end of file From d0a6c5b2b3a3d9dfeb19eaa8557759b541199538 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 13 Aug 2021 12:43:33 -0400 Subject: [PATCH 154/162] drop initial state check --- data/api/client-server/create_room.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index a3cb1176d..2a120f2c3 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -48,8 +48,7 @@ paths: (and not other members) permission to send state events. Overridden by the `power_level_content_override` parameter. - 4. An `m.room.canonical_alias` event if `room_alias_name` is given and - no `m.room.canonical_alias` event is given in `initial_state`. + 4. An `m.room.canonical_alias` event if `room_alias_name` is given. 5. Events set by the `preset`. Currently these are the `m.room.join_rules`, `m.room.history_visibility`, and `m.room.guest_access` state events. From ca86eea1267c027b5324887aacdab434df5c5c38 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Wed, 11 Aug 2021 23:20:18 +0200 Subject: [PATCH 155/162] OpenAPI: add titles --- changelogs/client_server/newsfragments/3330.clarification | 1 + data/api/client-server/definitions/errors/error.yaml | 3 ++- data/api/client-server/definitions/errors/rate_limited.yaml | 3 ++- data/api/client-server/definitions/event_batch.yaml | 1 + data/api/client-server/definitions/openid_token.yaml | 1 + .../client-server/definitions/request_token_response.yaml | 1 + data/api/client-server/definitions/room_event_batch.yaml | 1 + data/api/client-server/definitions/state_event_batch.yaml | 1 + data/api/client-server/definitions/timeline_batch.yaml | 1 + data/api/client-server/key_backup.yaml | 6 ++++++ 10 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3330.clarification diff --git a/changelogs/client_server/newsfragments/3330.clarification b/changelogs/client_server/newsfragments/3330.clarification new file mode 100644 index 000000000..5df676a14 --- /dev/null +++ b/changelogs/client_server/newsfragments/3330.clarification @@ -0,0 +1 @@ +Add titles for OpenAPI objects. diff --git a/data/api/client-server/definitions/errors/error.yaml b/data/api/client-server/definitions/errors/error.yaml index 7471da6f6..89a0d44f9 100644 --- a/data/api/client-server/definitions/errors/error.yaml +++ b/data/api/client-server/definitions/errors/error.yaml @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object +title: Error description: A Matrix-level Error properties: errcode: @@ -22,4 +23,4 @@ properties: type: string description: A human-readable error message. example: An unknown error occurred -required: ["errcode"] \ No newline at end of file +required: ["errcode"] diff --git a/data/api/client-server/definitions/errors/rate_limited.yaml b/data/api/client-server/definitions/errors/rate_limited.yaml index aca82ce7b..1530458ba 100644 --- a/data/api/client-server/definitions/errors/rate_limited.yaml +++ b/data/api/client-server/definitions/errors/rate_limited.yaml @@ -13,6 +13,7 @@ # limitations under the License. $ref: error.yaml type: object +title: RateLimitError description: The rate limit was reached for this request properties: errcode: @@ -29,4 +30,4 @@ properties: The amount of time in milliseconds the client should wait before trying the request again. example: 2000 -required: ["errcode"] \ No newline at end of file +required: ["errcode"] diff --git a/data/api/client-server/definitions/event_batch.yaml b/data/api/client-server/definitions/event_batch.yaml index 1694652ca..e326184c5 100644 --- a/data/api/client-server/definitions/event_batch.yaml +++ b/data/api/client-server/definitions/event_batch.yaml @@ -21,3 +21,4 @@ properties: type: object type: array type: object +title: EventBatch diff --git a/data/api/client-server/definitions/openid_token.yaml b/data/api/client-server/definitions/openid_token.yaml index 32929ef6f..e74ddfff5 100644 --- a/data/api/client-server/definitions/openid_token.yaml +++ b/data/api/client-server/definitions/openid_token.yaml @@ -13,6 +13,7 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object +title: OpenIdCredentials properties: access_token: type: string diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml index aa9379f6f..0f8c8cab9 100644 --- a/data/api/client-server/definitions/request_token_response.yaml +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object +title: RequestTokenResponse properties: sid: type: string diff --git a/data/api/client-server/definitions/room_event_batch.yaml b/data/api/client-server/definitions/room_event_batch.yaml index 45bcb4231..4a7dab193 100644 --- a/data/api/client-server/definitions/room_event_batch.yaml +++ b/data/api/client-server/definitions/room_event_batch.yaml @@ -25,3 +25,4 @@ properties: - origin_server_ts type: array type: object +title: RoomEventBatch diff --git a/data/api/client-server/definitions/state_event_batch.yaml b/data/api/client-server/definitions/state_event_batch.yaml index 9518300fb..f3966dcda 100644 --- a/data/api/client-server/definitions/state_event_batch.yaml +++ b/data/api/client-server/definitions/state_event_batch.yaml @@ -26,3 +26,4 @@ properties: - state_key type: array type: object +title: StateEventBatch diff --git a/data/api/client-server/definitions/timeline_batch.yaml b/data/api/client-server/definitions/timeline_batch.yaml index e243b485f..65a7622a1 100644 --- a/data/api/client-server/definitions/timeline_batch.yaml +++ b/data/api/client-server/definitions/timeline_batch.yaml @@ -24,3 +24,4 @@ properties: rooms/{roomId}/messages endpoint. type: string type: object +title: TimelineBatch diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 73044c6d1..bf7900f9f 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -409,6 +409,7 @@ paths: description: The update succeeded. schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- @@ -519,6 +520,7 @@ paths: description: The update succeeded schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- @@ -580,6 +582,7 @@ paths: description: The update succeeded schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- @@ -692,6 +695,7 @@ paths: description: The update succeeded schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- @@ -773,6 +777,7 @@ paths: description: The update succeeded schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- @@ -895,6 +900,7 @@ paths: description: The update succeeded schema: type: object + title: RoomKeysUpdateResponse properties: etag: description: |- From 042156950f37fd56bb1bf0844fc9886590318873 Mon Sep 17 00:00:00 2001 From: Denis Kasak Date: Mon, 16 Aug 2021 10:29:28 +0200 Subject: [PATCH 156/162] Fix typo in /_matrix/client/r0/account/3pid/delete. --- data/api/client-server/administrative_contact.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index d3f0a63ab..e6e1267b8 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -346,7 +346,7 @@ paths: description: |- An indicator as to whether or not the homeserver was able to unbind the 3PID from the identity server. `success` indicates that the - indentity server has unbound the identifier whereas `no-support` + identity server has unbound the identifier whereas `no-support` indicates that the identity server refuses to support the request or the homeserver was not able to determine an identity server to unbind from. From 2a7fb018b8132db10e0da3c3f2cb19b2f31e07b5 Mon Sep 17 00:00:00 2001 From: Lukas Lihotzki Date: Thu, 12 Aug 2021 23:13:54 +0200 Subject: [PATCH 157/162] OpenAPI: include peekEvents Disambiguate from getEvents by a trailing space in path (like inviteUser). Signed-off-by: Lukas Lihotzki --- .../client_server/newsfragments/3336.clarification | 1 + data/api/client-server/peeking_events.yaml | 9 ++++++--- 2 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3336.clarification diff --git a/changelogs/client_server/newsfragments/3336.clarification b/changelogs/client_server/newsfragments/3336.clarification new file mode 100644 index 000000000..bb06ffec9 --- /dev/null +++ b/changelogs/client_server/newsfragments/3336.clarification @@ -0,0 +1 @@ +Disambiguate getEvents and peekEvents, and include both in swagger. diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 85eb87683..0bf303ef1 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -27,9 +27,11 @@ produces: securityDefinitions: $ref: definitions/security.yaml paths: - "/events": + # With an extra " " to disambiguate from the getEvents endpoint + # The extra space makes it sort first for what I'm sure is a good reason. + "/events ": get: - summary: Listen on the event stream. + summary: Listen on the event stream of a particular room. description: |- This will listen for new events related to a particular room and return them to the caller. This will block until an event is received, or until @@ -103,4 +105,5 @@ paths: - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" 400: description: "Bad pagination `from` parameter." - # No tags to exclude this from the swagger UI - use the normal version instead. + tags: + - Room participation From 54255851f642f84a4f1aaf7bc063eebe3d76752b Mon Sep 17 00:00:00 2001 From: Denis Kasak Date: Tue, 17 Aug 2021 09:54:21 +0000 Subject: [PATCH 158/162] Add newsfragment for #3339. (#3342) --- changelogs/client_server/newsfragments/3339.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/3339.clarification diff --git a/changelogs/client_server/newsfragments/3339.clarification b/changelogs/client_server/newsfragments/3339.clarification new file mode 100644 index 000000000..3ccb23339 --- /dev/null +++ b/changelogs/client_server/newsfragments/3339.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. From f102ff340709fdf93079644931ca5c74258aed95 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Aug 2021 18:21:58 +0100 Subject: [PATCH 159/162] Update documentation_style.rst (#3351) hugo tales commonmark. --- meta/documentation_style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index cfec5e3ba..6779c78c8 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -8,7 +8,7 @@ in. Format ------ -Documentation is written in github-flavored markdown. +Documentation is written in Commonmark markdown. Sections -------- From dd6a55a8480bb9689862058b1edc35aaf2fd04ed Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Aug 2021 18:24:41 +0100 Subject: [PATCH 160/162] Notes on how to use `hugo` from docker (#3349) ... and the minimum version required. --- README.md | 60 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c13d4eafd..75f55affa 100644 --- a/README.md +++ b/README.md @@ -5,44 +5,44 @@ This repository contains the Matrix Specification, rendered at [spec.matrix.org] Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org) on Matrix for help. -Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org). +Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org). We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details. ## Structure The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site generator) with the following structure: -* `/assets`: assets that need postprocessing using [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/). +* `/assets`: assets that need postprocessing using [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/). For example, Sass files would go here. -* `/content`: files that will become pages in the site go here. Typically these are Markdown files with some YAML front - matter indicating, [among other things](https://gohugo.io/content-management/front-matter/), what layout should be - applied to this page. The organization of files under `/content` determines the organization of pages in the built +* `/content`: files that will become pages in the site go here. Typically these are Markdown files with some YAML front + matter indicating, [among other things](https://gohugo.io/content-management/front-matter/), what layout should be + applied to this page. The organization of files under `/content` determines the organization of pages in the built site. -* `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as - [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and +* `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as + [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and parse them. This is also where our Swagger/OpenAPI definitions and schemas are. -* `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of +* `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of a page: for example, whether it has header, footer, sidebar, and so on. - * `/layouts/partials`: these templates can be called from other templates, so they can be used to factor out - template code that's used in more than one template. An obvious example here is something like a sidebar, where - several different page layouts might all include the sidebar. But also, partial templates can return values: this + * `/layouts/partials`: these templates can be called from other templates, so they can be used to factor out + template code that's used in more than one template. An obvious example here is something like a sidebar, where + several different page layouts might all include the sidebar. But also, partial templates can return values: this means they can be used like functions, that can be called by multiple templates to do some common processing. * `/layouts/shortcodes`: these templates can be called directly from files in `/content`. * `/static`: static files which don't need preprocessing. JS or CSS files could live here. -* `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are - supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own - versions of any of the theme layouts in the base `/layouts` directory. That is, if a theme provides - `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of the +* `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are + supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own + versions of any of the theme layouts in the base `/layouts` directory. That is, if a theme provides + `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of the template will be used. It also has the following top-level file: -* `config.toml`: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings +* `config.toml`: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings defined here are available in templates. All these directories above are configurable via `config.toml` settings. Additionally, the following directories may be of interest: @@ -59,34 +59,40 @@ Additionally, the following directories may be of interest: Please read [CONTRIBUTING.rst](./CONTRIBUTING.rst) before authoring a change to the spec. Note that spec authoring takes place after an MSC has been accepted, not as part of a proposal itself. -1. Install the extended version (often the OS default) of Hugo: +1. Install the extended version (often the OS default) of Hugo: + . Note that at least Hugo + v0.74 is required. + + Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/. 2. Run `git submodule update --init --recursive` for good measure. 3. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed. 4. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required. -5. Run `hugo serve` to run a local webserver which builds whenever a file change is detected. If watching doesn't appear - to be working for you, try `hugo serve --disableFastRender` instead. +5. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313 + klakegg/hugo serve`) to run a local webserver which builds whenever a file + change is detected. If watching doesn't appear to be working for you, try + adding `--disableFastRender` to the commandline. 6. Edit the specification 🙂 -We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font -Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in +We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font +Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in [#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) before opening a PR. ## Building the specification -If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above -steps for authoring changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the -spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` +If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above +steps for authoring changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the +spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` to the `hugo -d "spec"` command. -For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` -and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file, +For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` +and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file, there are a number of options: * It can be uploaded from your filesystem to an online editor/viewer such as [on the swagger website](http://editor.swagger.io/). * You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation via an online viewer; for example, at . -* You can host the swagger UI yourself. See for advice on how to +* You can host the swagger UI yourself. See for advice on how to do so. ## Issue tracking From 8b2c12626094d16457b35b5af4a5ed6e1ac5b4c2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Aug 2021 18:38:02 +0100 Subject: [PATCH 161/162] Update documentation_style.rst (#3352) --- meta/documentation_style.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 6779c78c8..aea495bd3 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -66,6 +66,12 @@ Lists should: * Be used where they provide clarity. * Contain entries which start with a capital and end with a full stop. +When talking about properties in JSON objects, prefer the word "property" to "field", +"member", or various other alternatives. For example: "this property will be set to +X if ...". Also avoid the term "key" unless you are specifically talking about the +*name* of a property - and be mindful of the scope for confusion with cryptographic +keys. + OpenAPI ~~~~~~~ From dd0cc92ba89f754a918cb98f90fbf9b468c5dd56 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 23 Aug 2021 18:07:56 +0100 Subject: [PATCH 162/162] Start a 'conventions' section in the Appendices (#3350) I wanted a section for "here's what new APIs ought to do", which isn't really very useful for consumers of the existing APIs. --- .../newsfragments/3350.clarification | 1 + content/appendices.md | 19 +++++++ content/client-server-api/_index.md | 51 ++++++++++--------- 3 files changed, 47 insertions(+), 24 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3350.clarification diff --git a/changelogs/client_server/newsfragments/3350.clarification b/changelogs/client_server/newsfragments/3350.clarification new file mode 100644 index 000000000..c5524f19b --- /dev/null +++ b/changelogs/client_server/newsfragments/3350.clarification @@ -0,0 +1 @@ +Add an 'API conventions' section to the Appendices. \ No newline at end of file diff --git a/content/appendices.md b/content/appendices.md index f3be0cc67..b97b1f91d 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -1039,3 +1039,22 @@ The event signing algorithm should emit the following signed event: } } ``` + +## Conventions for Matrix APIs + +This section is intended primarily to guide API designers when adding to Matrix, +setting guidelines to follow for how those APIs should work. This is important to +maintain consistency with the Matrix protocol, and thus improve developer +experience. + +### HTTP endpoint and JSON property naming + +The names of the API endpoints for the HTTP transport follow a convention of +using underscores to separate words (for example `/delete_devices`). + +The key names in JSON objects passed over the API also follow this convention. + +{{% boxes/note %}} +There are a few historical exceptions to this rule, such as `/createRoom`. +These inconsistencies may be addressed in future versions of this specification. +{{% /boxes/note %}} diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7764cf47d..b81cb6080 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -4,7 +4,7 @@ weight: 10 type: docs --- -The client-server API provides a simple lightweight API to let clients +The client-server API allows clients to send messages, control rooms and synchronise conversation history. It is designed to support both lightweight clients which store no state and lazy-load data from the server as required - as well as heavyweight @@ -20,20 +20,15 @@ supported as optional extensions - e.g. a packed binary encoding over stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip mobile usage. For the default HTTP transport, all API calls use a Content-Type of `application/json`. In addition, all strings MUST be -encoded as UTF-8. Clients are authenticated using opaque `access_token` -strings (see [Client Authentication](#client-authentication) for -details), passed as a query string parameter on all requests. +encoded as UTF-8. -The names of the API endpoints for the HTTP transport follow a -convention of using underscores to separate words (for example -`/delete_devices`). The key names in JSON objects passed over the API -also follow this convention. +Clients are authenticated using opaque `access_token` strings (see [Client +Authentication](#client-authentication) for details). -{{% boxes/note %}} -There are a few historical exceptions to this rule, such as -`/createRoom`. A future version of this specification will address the -inconsistency. -{{% /boxes/note %}} +See also [Conventions for Matrix APIs](/appendices#conventions-for-matrix-apis) +in the Appendices for conventions which all Matrix APIs are expected to follow. + +### Standard error response Any errors which occur at the Matrix API level MUST return a "standard error response". This is a JSON object which looks like: @@ -46,15 +41,17 @@ error response". This is a JSON object which looks like: ``` The `error` string will be a human-readable error message, usually a -sentence explaining what went wrong. The `errcode` string will be a -unique string which can be used to handle an error message e.g. -`M_FORBIDDEN`. These error codes should have their namespace first in -ALL CAPS, followed by a single \_ to ease separating the namespace from -the error code. For example, if there was a custom namespace -`com.mydomain.here`, and a `FORBIDDEN` code, the error code should look -like `COM.MYDOMAIN.HERE_FORBIDDEN`. There may be additional keys -depending on the error, but the keys `error` and `errcode` MUST always -be present. +sentence explaining what went wrong. + +The `errcode` string will be a unique string which can be used to handle an +error message e.g. `M_FORBIDDEN`. Error codes should have their namespace +first in ALL CAPS, followed by a single `_`. For example, if there was a custom +namespace `com.mydomain.here`, and a `FORBIDDEN` code, the error code should +look like `COM.MYDOMAIN.HERE_FORBIDDEN`. Error codes defined by this +specification should start `M_`. + +Some `errcode`s define additional keys which should be present in the error +response object, but the keys `error` and `errcode` MUST always be present. Errors are generally best expressed by their error code rather than the HTTP status code returned. When encountering the error code `M_UNKNOWN`, @@ -66,7 +63,9 @@ found. However, if the client were to receive an error code of `M_UNKNOWN` with a 400 Bad Request, the client should assume that the request being made was invalid. -The common error codes are: +#### Common error codes + +These error codes can be returned by any API endpoint: `M_FORBIDDEN` Forbidden access, e.g. joining a room without permission, failed login. @@ -98,7 +97,11 @@ then try again. `M_UNKNOWN` An unknown error has occurred. -Other error codes the client might encounter are: +#### Other error codes + +The following error codes are specific to certain endpoints. + +. `M_UNRECOGNIZED` The server did not understand the request.