diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 9b020715..772b8412 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec h2 { font-weight: $font-weight-bold; font-size: 1.3rem; - margin: 3rem 0 .5rem 0; + margin: 1.5rem 0 1rem 0; } h3 { font-weight: $font-weight-bold; font-size: 1.1rem; - margin: 1.5rem 0 .75rem 0; + margin: 1.5rem 0 1rem 0; + + } + + /* Reduce top margin of h3 if previous sibling is a h2 */ + h2 + h3 { + margin-top: 1rem; } hr { @@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec } } - // add some space between two tables when they are right next to each other - & + table { - margin-top: 4rem; - } - caption { caption-side: top; color: $dark; @@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec } } + /* Have consistent spacing around tables and examples */ + table, .highlight { + margin-top: 0; + margin-bottom: 2rem; + + /* We don't need the margin on the last child of the .rendered-data block */ + &:last-child { + margin-bottom: 0; + } + } + pre { border: 0; border-left: solid 5px $secondary; diff --git a/changelogs/appendices/newsfragments/1506.clarification b/changelogs/appendices/newsfragments/1506.clarification deleted file mode 100644 index 41ef5ac4..00000000 --- a/changelogs/appendices/newsfragments/1506.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. diff --git a/changelogs/client_server/newsfragments/2036.clarification b/changelogs/client_server/newsfragments/2036.clarification deleted file mode 100644 index 9e586ae0..00000000 --- a/changelogs/client_server/newsfragments/2036.clarification +++ /dev/null @@ -1 +0,0 @@ -The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. diff --git a/changelogs/client_server/newsfragments/2038.clarification b/changelogs/client_server/newsfragments/2038.clarification deleted file mode 100644 index 169ca65c..00000000 --- a/changelogs/client_server/newsfragments/2038.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/2046.clarification b/changelogs/client_server/newsfragments/2046.clarification deleted file mode 100644 index bdcce777..00000000 --- a/changelogs/client_server/newsfragments/2046.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify formats of string types. diff --git a/changelogs/client_server/newsfragments/2051.clarification b/changelogs/client_server/newsfragments/2051.clarification deleted file mode 100644 index e8f7a70c..00000000 --- a/changelogs/client_server/newsfragments/2051.clarification +++ /dev/null @@ -1,2 +0,0 @@ -Document the `instance_id` field of `Protocol Instance` in the responses to -`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. diff --git a/changelogs/client_server/newsfragments/2055.clarification b/changelogs/client_server/newsfragments/2055.clarification deleted file mode 100644 index f8d79ec9..00000000 --- a/changelogs/client_server/newsfragments/2055.clarification +++ /dev/null @@ -1 +0,0 @@ -Applying redactions is a SHOULD for clients. diff --git a/changelogs/client_server/newsfragments/2059.removal b/changelogs/client_server/newsfragments/2059.removal deleted file mode 100644 index 94db06f8..00000000 --- a/changelogs/client_server/newsfragments/2059.removal +++ /dev/null @@ -1 +0,0 @@ -Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). diff --git a/changelogs/client_server/newsfragments/2064.clarification b/changelogs/client_server/newsfragments/2064.clarification deleted file mode 100644 index 17cc2890..00000000 --- a/changelogs/client_server/newsfragments/2064.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which rooms are returned from `/hierarchy`. diff --git a/changelogs/client_server/newsfragments/2068.clarification b/changelogs/client_server/newsfragments/2068.clarification new file mode 100644 index 00000000..1b3c13e8 --- /dev/null +++ b/changelogs/client_server/newsfragments/2068.clarification @@ -0,0 +1 @@ +Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. diff --git a/changelogs/client_server/newsfragments/2072.clarification b/changelogs/client_server/newsfragments/2072.clarification deleted file mode 100644 index ddb9a536..00000000 --- a/changelogs/client_server/newsfragments/2072.clarification +++ /dev/null @@ -1 +0,0 @@ -Clients can choose which history visibility options they offer to users when creating rooms. diff --git a/changelogs/client_server/newsfragments/2077.clarification b/changelogs/client_server/newsfragments/2077.clarification new file mode 100644 index 00000000..2077d47f --- /dev/null +++ b/changelogs/client_server/newsfragments/2077.clarification @@ -0,0 +1 @@ +Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/2080.clarification b/changelogs/client_server/newsfragments/2080.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/2080.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/2083.clarification b/changelogs/client_server/newsfragments/2083.clarification new file mode 100644 index 00000000..cc3dc3c7 --- /dev/null +++ b/changelogs/client_server/newsfragments/2083.clarification @@ -0,0 +1,2 @@ +Clarify the format of third-party invites, including the fact that identity +server public keys can be encoded using standard or URL-safe base64. diff --git a/changelogs/client_server/newsfragments/2091.clarification b/changelogs/client_server/newsfragments/2091.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/2091.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/2047.clarification b/changelogs/client_server/newsfragments/2121.clarification similarity index 100% rename from changelogs/client_server/newsfragments/2047.clarification rename to changelogs/client_server/newsfragments/2121.clarification diff --git a/changelogs/identity_service/newsfragments/2083.clarification b/changelogs/identity_service/newsfragments/2083.clarification new file mode 100644 index 00000000..7e5575c9 --- /dev/null +++ b/changelogs/identity_service/newsfragments/2083.clarification @@ -0,0 +1 @@ +Clarify that public keys can be encoded using standard or URL-safe base64. diff --git a/changelogs/internal/newsfragments/2033.clarification b/changelogs/internal/newsfragments/2033.clarification deleted file mode 100644 index 9d3e7596..00000000 --- a/changelogs/internal/newsfragments/2033.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the changelog release info with Hugo, rather than the changelog generation script. diff --git a/changelogs/internal/newsfragments/2041.clarification b/changelogs/internal/newsfragments/2041.clarification deleted file mode 100644 index fd9a66f7..00000000 --- a/changelogs/internal/newsfragments/2041.clarification +++ /dev/null @@ -1 +0,0 @@ -Update release steps documentation. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/2042.clarification b/changelogs/internal/newsfragments/2042.clarification deleted file mode 100644 index 4abe8e4e..00000000 --- a/changelogs/internal/newsfragments/2042.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove unused `release_date` from Hugo config. diff --git a/changelogs/internal/newsfragments/2045.clarification b/changelogs/internal/newsfragments/2045.clarification deleted file mode 100644 index bfe42c51..00000000 --- a/changelogs/internal/newsfragments/2045.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that v1.0 of Matrix was a release prior to the current global versioning system. diff --git a/changelogs/internal/newsfragments/2049.clarification b/changelogs/internal/newsfragments/2049.clarification deleted file mode 100644 index 5a6e90f1..00000000 --- a/changelogs/internal/newsfragments/2049.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. diff --git a/changelogs/internal/newsfragments/2061.clarification b/changelogs/internal/newsfragments/2061.clarification deleted file mode 100644 index 3257cef1..00000000 --- a/changelogs/internal/newsfragments/2061.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the version of the Identity Service API when Matrix 1.0 was introduced. diff --git a/changelogs/internal/newsfragments/2069.clarification b/changelogs/internal/newsfragments/2069.clarification deleted file mode 100644 index 2ad407fb..00000000 --- a/changelogs/internal/newsfragments/2069.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. diff --git a/changelogs/internal/newsfragments/2073.clarification b/changelogs/internal/newsfragments/2073.clarification deleted file mode 100644 index 64dbc6c4..00000000 --- a/changelogs/internal/newsfragments/2073.clarification +++ /dev/null @@ -1 +0,0 @@ -Deduplicate the definition of `RoomKeysUpdateResponse`. diff --git a/changelogs/internal/newsfragments/2074.clarification b/changelogs/internal/newsfragments/2074.clarification deleted file mode 100644 index 4f941dd2..00000000 --- a/changelogs/internal/newsfragments/2074.clarification +++ /dev/null @@ -1 +0,0 @@ -Deduplicate the definitions of `Invite3pid`. diff --git a/changelogs/internal/newsfragments/2076.clarification b/changelogs/internal/newsfragments/2076.clarification deleted file mode 100644 index 3cf1fb94..00000000 --- a/changelogs/internal/newsfragments/2076.clarification +++ /dev/null @@ -1 +0,0 @@ -Support more locations for examples in OpenAPI definitions and JSON schemas. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/2078.clarification b/changelogs/internal/newsfragments/2078.clarification deleted file mode 100644 index d9285d5a..00000000 --- a/changelogs/internal/newsfragments/2078.clarification +++ /dev/null @@ -1 +0,0 @@ -Add link to the git commit for the unstable changelog. diff --git a/changelogs/internal/newsfragments/2081.clarification b/changelogs/internal/newsfragments/2081.clarification new file mode 100644 index 00000000..a4923694 --- /dev/null +++ b/changelogs/internal/newsfragments/2081.clarification @@ -0,0 +1 @@ +Adjust margins in rendered endpoints. diff --git a/changelogs/internal/newsfragments/2115.clarification b/changelogs/internal/newsfragments/2115.clarification new file mode 100644 index 00000000..3deaf8c8 --- /dev/null +++ b/changelogs/internal/newsfragments/2115.clarification @@ -0,0 +1 @@ +Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. diff --git a/changelogs/room_versions/newsfragments/2065.clarification b/changelogs/room_versions/newsfragments/2065.clarification deleted file mode 100644 index e7fc9f20..00000000 --- a/changelogs/room_versions/newsfragments/2065.clarification +++ /dev/null @@ -1 +0,0 @@ -For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. diff --git a/changelogs/room_versions/newsfragments/2066.clarification b/changelogs/room_versions/newsfragments/2066.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/room_versions/newsfragments/2066.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/room_versions/newsfragments/2070.clarification b/changelogs/room_versions/newsfragments/2070.clarification deleted file mode 100644 index 7d0208cd..00000000 --- a/changelogs/room_versions/newsfragments/2070.clarification +++ /dev/null @@ -1 +0,0 @@ -Refactor PDU definitions to reduce duplication. diff --git a/changelogs/server_server/newsfragments/2050.clarification b/changelogs/server_server/newsfragments/2050.clarification deleted file mode 100644 index 8c4545d3..00000000 --- a/changelogs/server_server/newsfragments/2050.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. diff --git a/changelogs/server_server/newsfragments/2063.clarification b/changelogs/server_server/newsfragments/2063.clarification deleted file mode 100644 index 4e3df516..00000000 --- a/changelogs/server_server/newsfragments/2063.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/2076.clarification b/changelogs/server_server/newsfragments/2076.clarification deleted file mode 100644 index b3cad0d2..00000000 --- a/changelogs/server_server/newsfragments/2076.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove an erroneous `room_id` field in a few examples. diff --git a/changelogs/server_server/newsfragments/2083.clarification b/changelogs/server_server/newsfragments/2083.clarification new file mode 100644 index 00000000..cc3dc3c7 --- /dev/null +++ b/changelogs/server_server/newsfragments/2083.clarification @@ -0,0 +1,2 @@ +Clarify the format of third-party invites, including the fact that identity +server public keys can be encoded using standard or URL-safe base64. diff --git a/changelogs/client_server/newsfragments/2048.clarification b/changelogs/server_server/newsfragments/2128.clarification similarity index 100% rename from changelogs/client_server/newsfragments/2048.clarification rename to changelogs/server_server/newsfragments/2128.clarification diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 84362b3b..3394c942 100644 --- a/config/_default/hugo.toml +++ b/config/_default/hugo.toml @@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. # major = "1" -# minor = "13" +# minor = "14" # User interface configuration [params.ui] diff --git a/content/changelog/v1.14.md b/content/changelog/v1.14.md new file mode 100644 index 00000000..d5f14aba --- /dev/null +++ b/content/changelog/v1.14.md @@ -0,0 +1,93 @@ +--- +title: v1.14 Changelog +linkTitle: v1.14 +type: docs +layout: changelog +outputs: + - html + - checklist +date: 2025-03-27 +--- + +## Client-Server API + +**New Endpoints** + +- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093)) + +**Removed Endpoints** + +- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059)) + +**Spec Clarifications** + +- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036)) +- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038)) +- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046)) +- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091)) +- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051)) +- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055)) +- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064)) +- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072)) + + +## Server-Server API + +**Spec Clarifications** + +- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050)) +- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063)) +- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076)) + + +## Application Service API + +No significant changes. + + +## Identity Service API + +No significant changes. + + +## Push Gateway API + +No significant changes. + + +## Room Versions + +**Backwards Compatible Changes** + +- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105)) + +**Spec Clarifications** + +- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065)) +- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066)) +- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070)) +- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114)) + + +## Appendices + +**Spec Clarifications** + +- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506)) + + +## Internal Changes/Tooling + +**Spec Clarifications** + +- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033)) +- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041)) +- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042)) +- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045)) +- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049)) +- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061)) +- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069)) +- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073)) +- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074)) +- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076)) +- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078)) diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 6f34e938..ab0e011b 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -29,3 +29,9 @@ is in before accepting a report. based on whether or not the reporting user is joined to the room. This is because users can be exposed to harmful content without being joined to a room. For instance, through room directories or invites. + +{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports +based on whether or not the reporting user is joined to any rooms that the +reported user is joined to. This is because users can be exposed to harmful +content without being joined to a room. For instance, through user +directories or invites. diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index 3e586bc4..fb997992 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise, clients will try to use the default key to decrypt secrets. Clients that want to present a simplified interface to users by not supporting -multiple keys should use the default key if one is specified. If not default +multiple keys should use the default key if one is specified. If no default key is specified, the client may behave as if there is no key is present at all. When such a client creates a key, it should mark that key as being the default key. diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index 9ac55f57..2fc8b82e 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where their Matrix user ID is not known, instead addressing them by a third-party identifier such as an email address. There are two flows here; one if a Matrix user ID is known for the third-party identifier, and one if -not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the -third-party identifier. +not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite) +with the details of the third-party identifier. The homeserver asks the identity server whether a Matrix user ID is known for that identifier: @@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier. #### Server behaviour -Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the -third-party identifier with the provided identity server. If the lookup -yields a result for a Matrix User ID then the normal invite process can -be initiated. This process ends up looking like this: +Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite), +the server is expected to look up the third-party identifier with the provided +identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup). +If the lookup yields a result for a Matrix User ID then the normal [invite +process](/server-server-api/#inviting-to-a-room) can be initiated. This process +ends up looking like this: ``` +---------+ +-------------+ +-----------------+ @@ -66,10 +68,11 @@ be initiated. This process ends up looking like this: | | | ``` -However, if the lookup does not yield a bound User ID, the homeserver -must store the invite on the identity server and emit a valid -`m.room.third_party_invite` event to the room. This process ends up -looking like this: +However, if the lookup does not yield a bound User ID, the homeserver must store +the invite on the identity server with a call to +[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite) +and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event +to the room. This process ends up looking like this: ``` +---------+ +-------------+ +-----------------+ @@ -101,15 +104,18 @@ looking like this: | | | ``` -All homeservers MUST verify the signature in the event's -`content.third_party_invite.signed` object. +The third-party user will then need to verify their identity, which results in a +request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind) +from the identity server to the homeserver that bound the third-party identifier +to a user. The homeserver then exchanges the `m.room.third_party_invite` event +in the room for a complete [`m.room.member`](#mroommember) event with +`content.membership: invite` and a `content.third_party_invite` property for the +user that has bound the third-party identifier. If the invitee is on a different +homeserver than the inviting user, the invitee's homeserver makes a request to +[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid). -The third-party user will then need to verify their identity, which -results in a call from the identity server to the homeserver that bound -the third-party identifier to a user. The homeserver then exchanges the -`m.room.third_party_invite` event in the room for a complete -`m.room.member` event for `membership: invite` for the user that has -bound the third-party identifier. +All homeservers MUST verify the signature in the `m.room.member` event's +`content.third_party_invite.signed` object. If a homeserver is joining a room for the first time because of an `m.room.third_party_invite`, the server which is already participating @@ -193,8 +199,8 @@ at any time - the completion is not shown in the diagram. H1 MUST verify the request from H3 to ensure the `signed` property is correct as well as the `key_validity_url` as still being valid. This is -done by making a request to the [identity server -/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid) +done by making a request to the identity server's +[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid) endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided URL must match the Identity Service Specification. diff --git a/content/rooms/_index.md b/content/rooms/_index.md index 9334c3a1..d970bfe7 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including discovered security vulnerabilities and age. Clients should not ask room administrators to upgrade their rooms if the -room is running a stable version. Servers SHOULD use **room version 10** as +room is running a stable version. Servers SHOULD use **room version 11** as the default room version when creating new rooms. The available room versions are: diff --git a/content/rooms/fragments/v6-event-format.md b/content/rooms/fragments/v6-event-format.md new file mode 100644 index 00000000..f230ac54 --- /dev/null +++ b/content/rooms/fragments/v6-event-format.md @@ -0,0 +1,4 @@ + +Events in rooms of this version have the following structure: + +{{% definition path="api/server-server/definitions/pdu_v6" %}} diff --git a/content/rooms/v10.md b/content/rooms/v10.md index 974a0822..81daf4d6 100644 --- a/content/rooms/v10.md +++ b/content/rooms/v10.md @@ -281,7 +281,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} ### State resolution diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 72007d97..2f728587 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -39,6 +39,13 @@ in [room version 5](/rooms/v5). [See above](#redactions). +### Event format + +{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json), +the `depth` limit has been reduced in this room version. + +{{% rver-fragment name="v6-event-format" %}} + ### Authorization rules {{% added-in v=6 %}} Rule 4, which related specifically to events @@ -229,10 +236,6 @@ completeness. {{% rver-fragment name="v4-event-ids" %}} -### Event format - -{{% rver-fragment name="v4-event-format" %}} - #### Deprecated event content schemas {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}} diff --git a/content/rooms/v7.md b/content/rooms/v7.md index ba711c55..34e2a8eb 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -225,7 +225,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/content/rooms/v8.md b/content/rooms/v8.md index c6c116a8..aabf88c5 100644 --- a/content/rooms/v8.md +++ b/content/rooms/v8.md @@ -109,7 +109,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/content/rooms/v9.md b/content/rooms/v9.md index 582ff6b4..ac3288a1 100644 --- a/content/rooms/v9.md +++ b/content/rooms/v9.md @@ -74,7 +74,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/content/server-server-api.md b/content/server-server-api.md index 65494f80..c82e3bee 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -970,9 +970,8 @@ the event to other servers in the room. ## Third-party invites {{% boxes/note %}} -More information about third-party invites is available in the -[Client-Server API](/client-server-api) under -the Third-party Invites module. +More information about third-party invites is available in the Client-Server API +under the [Third-party invites](/client-server-api/#third-party-invites) module. {{% /boxes/note %}} When a user wants to invite another user in a room but doesn't know the @@ -985,38 +984,41 @@ API](/identity-service-api). ### Cases where an association exists for a third-party identifier -If the third-party identifier is already bound to a Matrix ID, a lookup -request on the identity server will return it. The invite is then -processed by the inviting homeserver as a standard `m.room.member` -invite event. This is the simplest case. +If the third-party identifier is already bound to a Matrix ID, a [lookup +request](/identity-service-api/#post_matrixidentityv2lookup) on the identity +server will return it. The invite is then processed by the inviting homeserver +as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the +simplest case. ### Cases where an association doesn't exist for a third-party identifier If the third-party identifier isn't bound to any Matrix ID, the inviting -homeserver will request the identity server to store an invite for this -identifier and to deliver it to whoever binds it to its Matrix ID. It -will also send an `m.room.third_party_invite` event in the room to -specify a display name, a token and public keys the identity server -provided as a response to the invite storage request. +homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage) +for this identifier and to deliver it to whoever binds it to its Matrix ID. It +will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) +event in the room to specify a display name, a token and public keys the +identity server provided as a response to the invite storage request. -When a third-party identifier with pending invites gets bound to a -Matrix ID, the identity server will send a POST request to the ID's -homeserver as described in the [Invitation -Storage](/identity-service-api#invitation-storage) -section of the Identity Service API. +When a third-party identifier with pending invites gets bound to a Matrix ID, +the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind) +endpoint of the the ID's homeserver as described in the [Invitation +Storage](/identity-service-api#invitation-storage) section of the Identity +Service API. The following process applies for each invite sent by the identity server: -The invited homeserver will create an `m.room.member` invite event -containing a special `third_party_invite` section containing the token -and a signed object, both provided by the identity server. +The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember) +invite event containing a special `third_party_invite` section containing the +token and a `signed` object, both provided by the identity server. If the invited homeserver is in the room the invite came from, it can auth the event and send it. However, if the invited homeserver isn't in the room the invite came -from, it will need to request the room's homeserver to auth the event. +from, it will need to request the inviting homeserver to auth the event +at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid) +endpoint. {{% http-api spec="server-server" api="third_party_invite" %}} @@ -1337,7 +1339,7 @@ calculated as follows. The *content hash* of an event covers the complete event including the *unredacted* contents. It is calculated as follows. -First, any existing `unsigned`, `signature`, and `hashes` members are +First, any existing `unsigned`, `signatures`, and `hashes` properties are removed. The resulting object is then encoded as [Canonical JSON](/appendices#canonical-json), and the JSON is hashed using SHA-256. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 654784ca..4934ef3f 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -45,7 +45,9 @@ paths: properties: reason: type: string - description: The reason the room is being reported. + description: The reason the room is being reported. May be blank. + required: + - reason required: true security: - accessTokenQuery: [] @@ -88,12 +90,11 @@ paths: Reports an event as inappropriate to the server, which may then notify the appropriate people. The caller must be joined to the room to report it. - - It might be possible for clients to deduce whether an event exists by - timing the response, as only a report for an event that does exist - will require the homeserver to check whether a user is joined to - the room. To combat this, homeserver implementations should add - a random delay when generating a response. + + Furthermore, it might be possible for clients to deduce whether a reported + event exists by timing the response. This is because only a report for an + existing event will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. operationId: reportEvent parameters: - in: path @@ -164,6 +165,88 @@ paths: } tags: - Reporting content + "/users/{userId}/report": + post: + x-addedInMatrixVersion: "1.14" + summary: Report a user as inappropriate. + description: |- + Reports a user as inappropriate to the server, which may then notify + the appropriate people. How such information is delivered is left up to + implementations. The caller is not required to be joined to any rooms + that the reported user is joined to. + + Clients may wish to [ignore](#ignoring-users) users after reporting them. + + Clients could infer whether a reported user exists based on the 404 response. + Homeservers that wish to conceal this information MAY return 200 responses + regardless of the existence of the reported user. + + Furthermore, it might be possible for clients to deduce whether a reported + user exists by timing the response. This is because only a report for an + existing user will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. + operationId: reportUser + parameters: + - in: path + name: userId + description: The user being reported. + required: true + example: "@someguy:example.com" + schema: + type: string + format: mx-user-id + pattern: "^@" + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "this makes me sad" + } + properties: + reason: + type: string + description: The reason the room is being reported. May be blank. + required: + - reason + required: true + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: | + The user has been reported successfully or the server chose + to not disclose whether the users exists. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: |- + The user was not found on the homeserver. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The user was not found." + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Reporting content servers: - url: "{protocol}://{hostname}{basePath}" variables: diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 9d9a807d..e6fd7883 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -441,17 +441,57 @@ paths: "state": { "events": [ { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + "content": { + "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe", + "displayname": "Example user", + "membership": "join" + }, + "event_id": "$143273976499sgjks:example.org", + "origin_server_ts": 1432735824653, + "sender": "@example:example.org", + "state_key": "@example:example.org", + "type": "m.room.member", + "unsigned": { + "age": 45603, + "membership": "join" + } } ] }, "timeline": { "events": [ { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + "content": { + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid", + "membership": "join", + "reason": "Looking for support" + }, + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653, + "sender": "@alice:example.org", + "state_key": "@alice:example.org", + "type": "m.room.member", + "unsigned": { + "age": 1234, + "membership": "join" + } }, { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + "content": { + "body": "This is an example text message", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example text message", + "msgtype": "m.text" + }, + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653, + "sender": "@example:example.org", + "type": "m.room.message", + "unsigned": { + "age": 1234, + "membership": "join" + } } ], "limited": true, diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index 65148ee0..67caa387 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -57,9 +57,6 @@ paths: - A signature of the token, signed with the identity server's private key - The matrix user ID who invited them to the room - - If a token is requested from the identity server, the homeserver will - append a `m.room.third_party_invite` event to the room. operationId: inviteBy3PID security: - accessTokenQuery: [] @@ -72,6 +69,8 @@ paths: example: "!d41d8cd:matrix.org" schema: type: string + format: mx-room-id + pattern: "^!" requestBody: content: application/json: @@ -90,7 +89,9 @@ paths: value: {} "403": description: |- - You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + You do not have permission to invite the user to the room. A + meaningful `errcode` and description error text will be returned. + Example reasons for rejections are: - The invitee has been banned from the room. - The invitee is already a member of the room. diff --git a/data/api/identity/v2_pubkey.yaml b/data/api/identity/v2_pubkey.yaml index 2aaf5f8e..68e383a8 100644 --- a/data/api/identity/v2_pubkey.yaml +++ b/data/api/identity/v2_pubkey.yaml @@ -43,7 +43,8 @@ paths: properties: public_key: type: string - description: Unpadded Base64 encoded public key. + description: |- + [Unpadded Base64](/appendices/#unpadded-base64)-encoded public key. required: - public_key examples: @@ -74,7 +75,8 @@ paths: - in: query name: public_key required: true - description: The unpadded base64-encoded public key to check. + description: |- + The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check. example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: type: string @@ -105,7 +107,14 @@ paths: - in: query name: public_key required: true - description: The unpadded base64-encoded public key to check. + description: |- + The [unpadded Base64](/appendices/#unpadded-base64)-encoded public + key to check. + + This MUST be the exact same encoded string returned in the response + of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite) + endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) + event, so it may use the standard or URL-safe alphabets. example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: type: string diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml index 5dcd9a78..98e7e7f4 100644 --- a/data/api/identity/v2_store_invite.yaml +++ b/data/api/identity/v2_store_invite.yaml @@ -42,7 +42,7 @@ paths: (if present) from the request here. Also, the generated ephemeral public key will be listed as valid on - requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`. + requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid). Currently, invites may only be issued for 3pids of the `email` medium. @@ -70,10 +70,14 @@ paths: room_id: type: string description: The Matrix room ID to which the user is invited + format: mx-room-id + pattern: "^!" example: "!something:example.org" sender: type: string description: The Matrix user ID of the inviting user + format: mx-user-id + pattern: "^@" example: "@bob:example.com" room_alias: type: string @@ -81,12 +85,16 @@ paths: The Matrix room alias for the room to which the user is invited. This should be retrieved from the `m.room.canonical_alias` state event. + format: mx-room-alias + pattern: "^#" example: "#somewhere:example.org" room_avatar_url: type: string description: |- The Content URI for the room to which the user is invited. This should be retrieved from the `m.room.avatar` state event. + format: mx-mxc-uri + pattern: "^mxc:\\/\\/" example: mxc://example.org/s0meM3dia room_join_rules: type: string @@ -108,6 +116,8 @@ paths: type: string description: The Content URI for the avatar of the user ID initiating the invite. + format: mx-mxc-uri + pattern: "^mxc:\\/\\/" example: mxc://example.org/an0th3rM3dia room_type: type: string @@ -146,7 +156,7 @@ paths: public_key: type: string description: | - The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). + The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64). key_validity_url: type: string description: | diff --git a/data/api/server-server/definitions/components/pdu_base.yaml b/data/api/server-server/definitions/components/pdu_base.yaml index 4b676c8f..be275611 100644 --- a/data/api/server-server/definitions/components/pdu_base.yaml +++ b/data/api/server-server/definitions/components/pdu_base.yaml @@ -41,13 +41,6 @@ properties: type: object description: The content of the event. example: {"key": "value"} - depth: - type: integer - description: |- - The maximum depth of the `prev_events`, plus one. Must be less than the - maximum value for an integer (2^63 - 1). If the room's depth is already at - the limit, the depth must be set to the limit. - example: 12 hashes: $ref: "event_hash.yaml" signatures: diff --git a/data/api/server-server/definitions/pdu_v1.yaml b/data/api/server-server/definitions/pdu_v1.yaml index b9ba8cc1..d2fb2ef9 100644 --- a/data/api/server-server/definitions/pdu_v1.yaml +++ b/data/api/server-server/definitions/pdu_v1.yaml @@ -28,6 +28,13 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def456:matrix.org" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^63 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 auth_events: type: array description: |- diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml index a3db6ee9..409b99c6 100644 --- a/data/api/server-server/definitions/pdu_v11.yaml +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -17,6 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond. example: $ref: "../examples/pdu_v11.json" allOf: - # v11 is the v4 event, but without redacts. + # v11 is the v6 event, but without redacts. - $ref: "components/pdu_base.yaml" - - $ref: "components/auth_events_prev_events_v4.yaml" \ No newline at end of file + - $ref: "components/auth_events_prev_events_v4.yaml" + - type: object + properties: + # v6 enforces Canonical JSON and therefore needs a depth limit change + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^53 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 \ No newline at end of file diff --git a/data/api/server-server/definitions/pdu_v3.yaml b/data/api/server-server/definitions/pdu_v3.yaml index 69d8900c..ccca717b 100644 --- a/data/api/server-server/definitions/pdu_v3.yaml +++ b/data/api/server-server/definitions/pdu_v3.yaml @@ -24,6 +24,13 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def/456+oldevent" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^63 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 auth_events: type: array items: diff --git a/data/api/server-server/definitions/pdu_v4.yaml b/data/api/server-server/definitions/pdu_v4.yaml index e859ee86..2edf1b31 100644 --- a/data/api/server-server/definitions/pdu_v4.yaml +++ b/data/api/server-server/definitions/pdu_v4.yaml @@ -26,3 +26,10 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def_456-oldevent" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^63 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 diff --git a/data/api/server-server/definitions/pdu_v6.yaml b/data/api/server-server/definitions/pdu_v6.yaml new file mode 100644 index 00000000..1278a6e3 --- /dev/null +++ b/data/api/server-server/definitions/pdu_v6.yaml @@ -0,0 +1,36 @@ +# Copyright 2025 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: |- + A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10. +example: + $ref: "../examples/pdu_v4.json" +allOf: + - $ref: "components/pdu_base.yaml" + - $ref: "components/auth_events_prev_events_v4.yaml" + - type: object + properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def_456-oldevent" + # v6 enforces Canonical JSON and therefore needs a depth limit change + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^53 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index 76a7d2ff..019aa2d4 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -35,6 +35,8 @@ paths: example: "!abc123:matrix.org" schema: type: string + format: mx-room-id + pattern: "^!" requestBody: content: application/json: @@ -50,16 +52,22 @@ paths: description: |- The room ID the event is for. Must match the ID given in the path. + format: mx-room-id + pattern: "^!" example: "!abc123:matrix.org" sender: type: string description: |- The user ID of the user who sent the original `m.room.third_party_invite` event. + format: mx-user-id + pattern: "^@" example: "@joe:matrix.org" state_key: type: string description: The user ID of the invited user + format: mx-user-id + pattern: "^@" example: "@someone:example.org" content: type: object @@ -82,45 +90,7 @@ paths: third-party identifier. example: alice signed: - type: object - description: |- - A block of content which has been signed, which servers can use to - verify the event. - title: Invite Signatures - properties: - signatures: - type: object - title: Signatures - additionalProperties: - type: object - additionalProperties: - type: string - description: |- - The server signatures for this event. - - The signature is calculated using the process - described at [Signing JSON](/appendices/#signing-json). - example: - magic.forest: - ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg - mxid: - type: string - description: The invited matrix user ID - example: "@alice:localhost" - token: - type: string - description: The token used to verify the event - example: abc123 - required: - - signatures - - mxid - - token - example: - mxid: "@alice:localhost" - token: abc123 - signatures: - magic.forest: - ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml required: - display_name - signed @@ -215,6 +185,8 @@ paths: mxid: type: string description: The user that is now bound to the third-party identifier. + format: mx-user-id + pattern: "^@" example: "@alice:matrix.org" invites: type: array @@ -237,59 +209,23 @@ paths: mxid: type: string description: The now-bound user ID that received the invite. + format: mx-user-id + pattern: "^@" example: "@alice:matrix.org" room_id: type: string description: The room ID the invite is valid for. + format: mx-room-id + pattern: "^!" example: "!somewhere:example.org" sender: type: string description: The user ID that sent the invite. + format: mx-user-id + pattern: "^@" example: "@bob:matrix.org" - # TODO (TravisR): Make this reusable when doing IS spec changes - # also make sure it isn't lying about anything, like the key version signed: - type: object - title: Identity Server Signatures - description: |- - Signature from the identity server using a long-term private - key. - properties: - mxid: - type: string - description: |- - The user ID that has been bound to the third-party - identifier. - example: "@alice:matrix.org" - token: - type: string - # TODO: What is this actually? - description: A token. - example: Hello World - signatures: - type: object - title: Identity Server Signature - description: |- - The signature from the identity server. The `string` key - is the identity server's domain name, such as vector.im - additionalProperties: - type: object - title: Identity Server Domain Signature - description: The signature for the identity server. - properties: - ed25519:0: - type: string - description: The signature. - example: SomeSignatureGoesHere - required: - - ed25519:0 - example: - vector.im: - ed25519:0: SomeSignatureGoesHere - required: - - mxid - - token - - signatures + $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml required: - medium - address diff --git a/data/event-schemas/examples/m.room.member.yaml b/data/event-schemas/examples/m.room.member.yaml index 5147b258..85e9a9eb 100644 --- a/data/event-schemas/examples/m.room.member.yaml +++ b/data/event-schemas/examples/m.room.member.yaml @@ -1,6 +1,7 @@ { "$ref": "core/state_event.json", "state_key": "@alice:example.org", + "sender": "@alice:example.org", "type": "m.room.member", "content": { "membership": "join", diff --git a/data/event-schemas/schema/components/signed_third_party_invite.yaml b/data/event-schemas/schema/components/signed_third_party_invite.yaml new file mode 100644 index 00000000..b231c978 --- /dev/null +++ b/data/event-schemas/schema/components/signed_third_party_invite.yaml @@ -0,0 +1,45 @@ +title: SignedThirdPartyInvite +description: |- + A block of content which has been signed by the identity server, which + homeservers can use to verify the event. Clients should ignore this. +type: object +properties: + mxid: + description: |- + The user ID that has been bound to the third-party identifier. + type: string + format: mx-user-id + pattern: "^@" + example: "@alice:example.org" + signatures: + title: IdentityServerSignatures + description: |- + The identity server signatures for this block. This is a map of identity + server name to signing key identifier to base64-encoded signature. + + The signatures are calculated using the process described at + [Signing JSON](/appendices/#signing-json). + type: object + additionalProperties: + type: object + additionalProperties: + type: string + example: { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + token: + description: |- + The token generated by the identity server at the + [`/store_invite`](/identity-service-api/#post_matrixidentityv2store-invite) + endpoint. + + It matches the `state_key` of the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) + event. + type: string + example: "abc123" +required: + - mxid + - signatures + - token diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index 8d212687..436c0145 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -2,17 +2,27 @@ allOf: - $ref: core-event-schema/state_event.yaml description: |- - Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms//invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. + Adjusts the membership state for a user in a room. It is preferable to use the membership APIs + (`/rooms//invite` etc) when performing membership actions rather than adjusting the + state directly as there are a restricted set of valid transformations. For example, user A cannot + force user B to join a room, and trying to force this state change directly will fail. The following membership states are specified: - - `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join. - - `join` - The user has joined the room (possibly after accepting an invite), and may participate in it. - - `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked). - - `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`). - - `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join. + - `invite` - The user has been invited to join a room, but has not yet joined it. They may not + participate in the room until they join. + - `join` - The user has joined the room (possibly after accepting an invite), and may participate + in it. + - `leave` - The user was once joined to the room, but has since left (possibly by choice, or + possibly by being kicked). + - `ban` - The user has been banned from the room, and is no longer allowed to join it until they + are un-banned from the room (by having their membership state set to a value other than `ban`). + - `knock` - The user has knocked on the room, requesting permission to participate. They may not + participate in the room until they join. - The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise. + The `third_party_invite` property will be set if this invite is an `invite` event and is the + successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event, + and absent otherwise. This event may also include an `invite_room_state` key inside the event's `unsigned` data. If present, this contains an array of [stripped state events](/client-server-api/#stripped-state) @@ -57,63 +67,54 @@ properties: - ban type: string is_direct: - description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging). + description: |- + Flag indicating if the room containing this event was created with the intention of being + a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging). type: boolean join_authorised_via_users_server: x-addedInMatrixVersion: "1.2" type: string description: |- - Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level) - authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms). + Usually found on `join` events, this field is used to denote which homeserver (through + representation of a user with sufficient power level) authorised the user's join. More + information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms). - Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this - field in further events: in particular, the event must be signed by the server which - owns the user ID in the field. When copying the membership event's `content` - (for profile updates and similar) it is therefore encouraged to exclude this - field in the copy, as otherwise the event might fail event authorization. + Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) + of including this field in further events: in particular, the event must be signed by the + server which owns the user ID in the field. When copying the membership event's `content` + (for profile updates and similar) it is therefore encouraged to exclude this field in the + copy, as otherwise the event might fail event authorization. reason: x-addedInMatrixVersion: "1.1" type: string description: |- - Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban. - For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such - as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day. + Optional user-supplied text for why their membership has changed. For kicks and bans, + this is typically the reason for the kick or ban. For other membership changes, this is a + way for the user to communicate their intent without having to send a message to the + room, such as in a case where Bob rejects an invite from Alice about an upcoming concert, + but can't make it that day. - Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the - reason behind a button or other component is recommended. + Clients are not recommended to show this reason to users when receiving an invite due to + the potential for spam and abuse. Hiding the reason behind a button or other component is + recommended. third_party_invite: + title: ThirdPartyInvite + description: |- + A third-party invite, if this `m.room.member` is the successor to an + [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) + event. + type: object properties: display_name: - description: A name which can be displayed to represent the user instead of their third-party identifier + description: |- + A name which can be displayed to represent the user instead of their + third-party identifier type: string signed: - description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.' - properties: - mxid: - description: The invited matrix user ID. Must be equal to the user_id property of the event. - type: string - signatures: - description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.' - title: Signatures - type: object - additionalProperties: - type: object - additionalProperties: - type: string - token: - description: The token property of the containing third_party_invite object. - type: string - required: - - mxid - - signatures - - token - title: signed - type: object + $ref: components/signed_third_party_invite.yaml required: - display_name - signed - title: Invite - type: object required: - membership title: EventContent diff --git a/data/event-schemas/schema/m.room.third_party_invite.yaml b/data/event-schemas/schema/m.room.third_party_invite.yaml index bb4883f5..704669d2 100644 --- a/data/event-schemas/schema/m.room.third_party_invite.yaml +++ b/data/event-schemas/schema/m.room.third_party_invite.yaml @@ -1,28 +1,56 @@ --- allOf: - $ref: core-event-schema/state_event.yaml -description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room." +description: |- + Acts as an `m.room.member` invite event, where there isn't a target user_id to + invite. This event contains a token and a public key whose private key must be + used to sign the token. Any user who can present that signature may use this + invitation to join the target room. properties: content: properties: display_name: - description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID." + description: |- + A user-readable string which represents the user who has been invited. + This should not contain the user's third-party ID, as otherwise when + the invite is accepted it would leak the association between the + matrix ID and the third-party ID. type: string key_validity_url: - description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." + description: |- + A URL which can be fetched, with querystring public_key=public_key, to + validate whether the key has been revoked. The URL must return a JSON + object containing a boolean property named 'valid'. type: string + format: uri public_key: - description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility. + description: |- + An Ed25519 key with which the token must be signed (though a signature + from any entry in `public_keys` is also sufficient). + + The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64), + using the standard or URL-safe alphabets. + + This exists for backwards compatibility. type: string public_keys: description: Keys with which the token may be signed. items: properties: key_validity_url: - description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely." + description: |- + An optional URL which can be fetched, with querystring + `public_key=`, to validate whether the key has been + revoked. The URL must return a JSON object containing a boolean + property named `valid`. If this URL is absent, the key must be + considered valid indefinitely. type: string public_key: - description: A base-64 encoded ed25519 key with which token may be signed. + description: |- + An Ed25519 key with which the token may be signed. + + The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64), + using the standard or URL-safe alphabets. type: string required: - public_key @@ -35,11 +63,15 @@ properties: - public_key type: object state_key: - description: 'The token, of which a signature must be produced in order to join the room.' + description: |- + The token, of which a signature must be produced in order to join the + room. type: string type: enum: - m.room.third_party_invite type: string -title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.' +title: |- + An invitation to a room issued to a third-party identifier, rather than a + matrix user ID. type: object diff --git a/data/event-schemas/schema/m.room.topic.yaml b/data/event-schemas/schema/m.room.topic.yaml index 41588f5b..580566d2 100644 --- a/data/event-schemas/schema/m.room.topic.yaml +++ b/data/event-schemas/schema/m.room.topic.yaml @@ -2,18 +2,21 @@ allOf: - $ref: core-event-schema/state_event.yaml description: |- - A topic is a short message detailing what is currently being discussed - in the room. It can also be used as a way to display extra information - about the room, which may not be suitable for the room name. The room - topic can be set when creating a room using - [`/createRoom`](client-server-api/#post_matrixclientv3createroom), either - with the `topic` key or by specifying a full event in `initial_state`. + A topic is a short message detailing what is currently being discussed + in the room. It can also be used as a way to display extra information + about the room, which may not be suitable for the room name. The room + topic can also be set when creating a room using + [`/createRoom`](client-server-api/#post_matrixclientv3createroom), either + with the `topic` key or by specifying a full event in `initial_state`. - In order to prevent formatting abuse in room topics, clients SHOULD - limit the length of topics during both entry and display, for instance, - by capping the number of displayed lines. Additionally, clients SHOULD - ignore things like headings and enumerations (or format them as regular - text). + If the `topic` property is absent, null, or empty then the topic is unset. In other words, + an empty `topic` property effectively resets the room to having no topic. + + In order to prevent formatting abuse in room topics, clients SHOULD + limit the length of topics during both entry and display, for instance, + by capping the number of displayed lines. Additionally, clients SHOULD + ignore things like headings and enumerations (or format them as regular + text). properties: content: properties: diff --git a/data/string-formats.yaml b/data/string-formats.yaml index 352d21fc..fca325b9 100644 --- a/data/string-formats.yaml +++ b/data/string-formats.yaml @@ -51,6 +51,11 @@ mx-room-id: url: appendices#room-ids # regex: "^!" +mx-room-alias: + title: Room Alias + url: appendices#room-aliases + # regex: "^#" + mx-server-name: title: Server Name url: appendices#server-name diff --git a/static/.well-known/funding-manifest-urls b/static/.well-known/funding-manifest-urls new file mode 100644 index 00000000..1b14b420 --- /dev/null +++ b/static/.well-known/funding-manifest-urls @@ -0,0 +1 @@ +https://matrix.org/funding.json