From 7f2f100420a355cf8ea50d08329e6f98989fc975 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 28 Aug 2024 14:42:30 +0200 Subject: [PATCH 1/5] MSC4156: Migrate server_name to via (#1933) Signed-off-by: Johannes Marbach --- .../newsfragments/1933.deprecation | 1 + .../client_server/newsfragments/1933.feature | 1 + data/api/client-server/joining.yaml | 25 +++++++++++++++++++ data/api/client-server/knocking.yaml | 25 +++++++++++++++++++ 4 files changed, 52 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1933.deprecation create mode 100644 changelogs/client_server/newsfragments/1933.feature diff --git a/changelogs/client_server/newsfragments/1933.deprecation b/changelogs/client_server/newsfragments/1933.deprecation new file mode 100644 index 00000000..b65ebdc7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.deprecation @@ -0,0 +1 @@ +Deprecate the `server_name` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/changelogs/client_server/newsfragments/1933.feature b/changelogs/client_server/newsfragments/1933.feature new file mode 100644 index 00000000..030b5a00 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.feature @@ -0,0 +1 @@ +Add `via` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index afd19fa8..aead420c 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -139,6 +139,31 @@ paths: type: string - in: query name: server_name + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to join the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to join the room through. One of the servers must be participating in the room. diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 1eb6cde7..39a928e8 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -50,6 +50,31 @@ paths: type: string - in: query name: server_name + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to knock on the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to knock on the room through. One of the servers must be participating in the room. From 415fb43848e7e732a95c791d3b13110fa3d45c32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Mon, 2 Sep 2024 10:41:33 +0200 Subject: [PATCH 2/5] Specify `Content-Type` and `Content-Disposition` usage in the media repo (#1935) --- .../newsfragments/1935.clarification | 1 + .../client-server-api/modules/content_repo.md | 47 ++++++++++ .../client-server/authed-content-repo.yaml | 78 ++++++++++++++-- data/api/client-server/content-repo.yaml | 88 +++++++++++++++++-- 4 files changed, 203 insertions(+), 11 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1935.clarification diff --git a/changelogs/client_server/newsfragments/1935.clarification b/changelogs/client_server/newsfragments/1935.clarification new file mode 100644 index 00000000..de90b5da --- /dev/null +++ b/changelogs/client_server/newsfragments/1935.clarification @@ -0,0 +1 @@ +Specify `Content-Type` and `Content-Disposition` usage in the media repo, as per [MSC2701](https://github.com/matrix-org/matrix-spec-proposals/pull/2701) and [MSC2702](https://github.com/matrix-org/matrix-spec-proposals/pull/2702). \ No newline at end of file diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index c9ac06d7..17715504 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -168,3 +168,50 @@ Homeservers have additional content-specific concerns: - Clients or remote homeservers may try to upload malicious files targeting vulnerabilities in either the homeserver thumbnailing or the client decoders. + +##### Serving inline content + +Clients with insecure configurations may be vulnerable to Cross-Site Scripting +attacks when served media with a `Content-Disposition` of `inline`. Clients +SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver +to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to +one of the following values when serving content with `Content-Disposition: inline`: + +* `text/css` +* `text/plain` +* `text/csv` +* `application/json` +* `application/ld+json` +* `image/jpeg` +* `image/gif` +* `image/png` +* `image/apng` +* `image/webp` +* `image/avif` +* `video/mp4` +* `video/webm` +* `video/ogg` +* `video/quicktime` +* `audio/mp4` +* `audio/webm` +* `audio/aac` +* `audio/mpeg` +* `audio/ogg` +* `audio/wave` +* `audio/wav` +* `audio/x-wav` +* `audio/x-pn-wav` +* `audio/flac` +* `audio/x-flac` + +These types are unlikely to cause Cross-Site Scripting issues when a `Content-Type` +header is provided, as clients will only try to render the data using that content +type. For example, if a HTML file is uploaded with a `Content-Type` of `image/png`, +clients will just assume that the image is corrupted, and won't render it as a +HTML page. Therefore, there is no risk in trusting the user-defined content type, +as long as the `Content-Disposition` is calculated based on that type. + +Clients SHOULD NOT rely on servers returning `inline` rather than `attachment` +on `/download`. Server implementations might decide out of an abundance of +caution that all downloads are responded to with `attachment`, regardless of +content type - clients should not be surprised by this behaviour. diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml index 43cb5881..53416cf3 100644 --- a/data/api/client-server/authed-content-repo.yaml +++ b/data/api/client-server/authed-content-repo.yaml @@ -46,9 +46,29 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: The name of the file that was previously uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -106,11 +126,21 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: |- - The `fileName` requested or the name of the file that was previously - uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -208,8 +238,24 @@ paths: "200": description: A thumbnail of the requested content. headers: + Content-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. description: The content type of the thumbnail. + required: true schema: type: string enum: @@ -512,7 +558,29 @@ components: format: uri headers: downloadContentType: - description: The content type of the file that was previously uploaded. + description: | + The content type of the file that was previously uploaded. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true schema: type: string diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 92ca6caa..f50850bd 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -248,9 +248,29 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: The name of the file that was previously uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -309,11 +329,21 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: |- - The `fileName` requested or the name of the file that was previously - uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -412,8 +442,24 @@ paths: "200": description: A thumbnail of the requested content. headers: + Content-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. description: The content type of the thumbnail. + required: true schema: type: string enum: @@ -639,7 +685,15 @@ components: contentType: in: header name: Content-Type - description: The content type of the file being uploaded + description: | + **Optional.** The content type of the file being uploaded. + + Clients SHOULD always supply this header. + + Defaults to `application/octet-stream` if it is not set. + x-changedInMatrixVersion: + "1.12": | + This header became explicitly optional with a default value. example: application/pdf schema: type: string @@ -782,7 +836,29 @@ components: format: uri headers: downloadContentType: - description: The content type of the file that was previously uploaded. + description: | + The content type of the file that was previously uploaded. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true schema: type: string From 6d088e03a1e767fbd55576e9683f243fa1fb13dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:53:06 +0200 Subject: [PATCH 3/5] Add `added-in` shortcode for unread markers section (#1941) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1941.feature | 1 + content/client-server-api/modules/read_markers.md | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1941.feature diff --git a/changelogs/client_server/newsfragments/1941.feature b/changelogs/client_server/newsfragments/1941.feature new file mode 100644 index 00000000..5e806a7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1941.feature @@ -0,0 +1 @@ +Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index 55e73dd5..830a441f 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -57,6 +57,8 @@ applicable filters are also satisfied. #### Unread markers +{{% added-in v="1.12" %}} + Clients may use "unread markers" to allow users to label rooms for later attention irrespective of [read receipts](#receipts) or [fully read markers](#fully-read-markers). From 75e77b96ff56464c6e11e4605a3b160ba15710b0 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 11 Sep 2024 13:51:27 +0200 Subject: [PATCH 4/5] Additional keys in GET /capabilities don't have to be objects (#1945) --- changelogs/client_server/newsfragments/1945.clarification | 1 + data/api/client-server/capabilities.yaml | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1945.clarification diff --git a/changelogs/client_server/newsfragments/1945.clarification b/changelogs/client_server/newsfragments/1945.clarification new file mode 100644 index 00000000..651ea6d3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1945.clarification @@ -0,0 +1 @@ +Additional keys in `GET /capabilities` don't have to be objects. diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 3ae26b22..523c6091 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -43,7 +43,9 @@ paths: The custom capabilities the server supports, using the Java package naming convention. additionalProperties: - type: object + description: |- + Application-dependent keys using the + [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). properties: m.change_password: $ref: '#/components/schemas/booleanCapability' From 2cbf6067a6d50ea2160e72d2a570f2cb8eeb0a20 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 11 Sep 2024 14:56:14 +0200 Subject: [PATCH 5/5] Use "server name" instead of "DNS name" to avoid confusion (#1946) Fixes: #1911 Signed-off-by: Johannes Marbach --- changelogs/server_server/newsfragments/1946.clarification | 1 + data/api/server-server/definitions/keys.yaml | 2 +- data/api/server-server/joins-v1.yaml | 2 +- data/api/server-server/joins-v2.yaml | 2 +- data/api/server-server/keys_query.yaml | 2 +- data/api/server-server/query.yaml | 6 ++++-- 6 files changed, 9 insertions(+), 6 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1946.clarification diff --git a/changelogs/server_server/newsfragments/1946.clarification b/changelogs/server_server/newsfragments/1946.clarification new file mode 100644 index 00000000..baf02987 --- /dev/null +++ b/changelogs/server_server/newsfragments/1946.clarification @@ -0,0 +1 @@ + Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. \ No newline at end of file diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 748debd8..c3f71083 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -19,7 +19,7 @@ example: properties: server_name: type: string - description: DNS name of the homeserver. + description: The homeserver's [server name](/appendices/#server-name). example: "example.org" verify_keys: type: object diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index a56315d1..a361836c 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -341,7 +341,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). auth_chain: type: array description: |- diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 465207e9..31f8098c 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -162,7 +162,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). members_omitted: type: boolean description: "`true` if `m.room.member` events have been omitted from `state`." diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index ed9e6302..791deb0a 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -26,7 +26,7 @@ paths: parameters: - in: path name: serverName - description: The server's DNS name to query + description: The [server name](/appendices/#server-name) to query required: true example: matrix.org schema: diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index efb3a6c9..16ed5e40 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -45,7 +45,8 @@ paths: description: |- Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias. Homeservers should only query room aliases - that belong to the target server (identified by the DNS Name in the alias). + that belong to the target server (identified by the [server name](/appendices/#server-name) + in the alias). Servers may wish to cache the response to this query to avoid requesting the information too often. @@ -111,7 +112,8 @@ paths: description: |- Performs a query to get profile information, such as a display name or avatar, for a given user. Homeservers should only query profiles for users that belong - to the target server (identified by the DNS Name in the user ID). + to the target server (identified by the [server name](/appendices/#server-name) + in the user ID). Servers may wish to cache the response to this query to avoid requesting the information too often.