Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 11:34:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' into johannes/reporting-rooms

Browse source
This commit is contained in:
Johannes Marbach 2024-09-25 20:26:36 +02:00
parent 883e9e3f8c 2cbf6067a6
commit c2b90d5084
18 changed files with 271 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1933.deprecation Normal file
View file

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

1
changelogs/client_server/newsfragments/1933.feature Normal file
View file

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

1
changelogs/client_server/newsfragments/1935.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/1941.feature Normal file
View file

@ -0,0 +1 @@
Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867).

1
changelogs/client_server/newsfragments/1945.clarification Normal file
View file

@ -0,0 +1 @@
Additional keys in `GET /capabilities` don't have to be objects.

1
changelogs/server_server/newsfragments/1946.clarification Normal file
View file

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

47
content/client-server-api/modules/content_repo.md
View file

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

2
content/client-server-api/modules/read_markers.md
View file

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

78
data/api/client-server/authed-content-repo.yaml
View file

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

4
data/api/client-server/capabilities.yaml
View file

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

88
data/api/client-server/content-repo.yaml
View file

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

25
data/api/client-server/joining.yaml
View file

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

25
data/api/client-server/knocking.yaml
View file

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

2
data/api/server-server/definitions/keys.yaml
View file

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

2
data/api/server-server/joins-v1.yaml
View file

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

2
data/api/server-server/joins-v2.yaml
View file

@ -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`."

2
data/api/server-server/keys_query.yaml
View file

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

6
data/api/server-server/query.yaml
View file

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