From 34589078fdbdee7fb23648e2ab9169431d09b27f Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Tue, 10 May 2022 19:34:01 +0200 Subject: [PATCH 01/19] Clarify that valid_until_ts is in milliseconds, like other timestamps used in Matrix Signed-off-by: Valentin Lorentz --- changelogs/server_server/newsfragments/1055.clarification | 1 + data/api/server-server/definitions/keys.yaml | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1055.clarification diff --git a/changelogs/server_server/newsfragments/1055.clarification b/changelogs/server_server/newsfragments/1055.clarification new file mode 100644 index 00000000..748f7793 --- /dev/null +++ b/changelogs/server_server/newsfragments/1055.clarification @@ -0,0 +1 @@ +Clarify that valid_until_ts is in milliseconds, like other timestamps used in Matrix diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 135e81ac..97ac1667 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -88,9 +88,10 @@ properties: type: integer format: int64 description: |- - POSIX timestamp when the list of valid keys should be refreshed. This field MUST - be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST - be considered invalid, depending on the [room version specification](/rooms). + POSIX timestamp in milliseconds when the list of valid keys should be refreshed. + This field MUST be ignored in room versions 1, 2, 3, and 4. Keys used beyond this + timestamp MUST be considered invalid, depending on the + [room version specification](/rooms). Servers MUST use the lesser of this field and 7 days into the future when determining if a key is valid. This is to avoid a situation where an attacker From 81d61d87f40fe81470a8458b7c3325bff87bb1fc Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 10 May 2022 20:29:29 +0100 Subject: [PATCH 02/19] Italicise primes and brackets in state res desc (#1043) * Italicise primes and brackets in state res desc I don't like it but it seems to make things look decent in Firefox. This is probably good enough---we're not Knuth, after all. Additionally I have avoided the use of `*E*'s` as in "E's prev_events" since the apostrophe looks poor here. Resolves #774. An alternative to #1040. * Changelog --- .../newsfragments/1043.clarification | 1 + content/rooms/fragments/v2-state-res.md | 21 +++++++++---------- content/rooms/v1.md | 16 +++++++------- 3 files changed, 19 insertions(+), 19 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1043.clarification diff --git a/changelogs/room_versions/newsfragments/1043.clarification b/changelogs/room_versions/newsfragments/1043.clarification new file mode 100644 index 00000000..49e552f4 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1043.clarification @@ -0,0 +1 @@ +Adjust mathematical notation used in the description of state resolution to render better in browsers. \ No newline at end of file diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index b238e1d8..d12f45c3 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -2,20 +2,19 @@ toc_hide: true --- -The room state *S*′(*E*) after an event *E* is defined in terms of the -room state *S*(*E*) before *E*, and depends on whether *E* is a state +The room state *S′(E)* after an event *E* is defined in terms of the +room state *S(E)* before *E*, and depends on whether *E* is a state event or a message event: -- If *E* is a message event, then *S*′(*E*) = *S*(*E*). -- If *E* is a state event, then *S*′(*E*) is *S*(*E*), except that its - entry corresponding to *E*'s `event_type` and `state_key` is - replaced by *E*'s `event_id`. +- If *E* is a message event, then *S′(E)* = *S(E)*. +- If *E* is a state event, then *S′(E)* is *S(E)*, except that its + entry corresponding to the `event_type` and `state_key` of *E* is + replaced by the `event_id` of *E*. -The room state *S*(*E*) before *E* is the *resolution* of the set of -states {*S*′(*E*1), *S*′(*E*2), …} consisting of -the states after each of *E*'s `prev_event`s -{*E*1, *E*2, …}, where the resolution of a set of -states is given in the algorithm below. +The room state *S(E)* before *E* is the *resolution* of the set of +states {*S′(E*1*)*, *S′(E*2*)*, …} +after the `prev_event`s {*E*1, *E*2, …} of *E*. +The resolution of a set of states is given in the algorithm below. #### Definitions diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 1519873b..a69e3d5d 100644 --- a/content/rooms/v1.md +++ b/content/rooms/v1.md @@ -66,18 +66,18 @@ This is fixed in the state resolution algorithm introduced in room version 2. {{% /boxes/warning %}} -The room state *S*′(*E*) after an event *E* is defined in terms of the +The room state *S′*(*E*) after an event *E* is defined in terms of the room state *S*(*E*) before *E*, and depends on whether *E* is a state event or a message event: -- If *E* is a message event, then *S*′(*E*) = *S*(*E*). -- If *E* is a state event, then *S*′(*E*) is *S*(*E*), except that its - entry corresponding to *E*'s `event_type` and `state_key` is - replaced by *E*'s `event_id`. +- If *E* is a message event, then *S′(E)* = *S(E)*. +- If *E* is a state event, then *S′(E)* is *S(E)*, except that its + entry corresponding to the `event_type` and `state_key` of *E* is + replaced by the `event_id` of *E*. -The room state *S*(*E*) before *E* is the *resolution* of the set of -states {*S*′(*E*′), *S*′(*E*″), …} consisting of the states after each -of *E*'s `prev_event`s {*E*′, *E*″, …}. +The room state *S(E)* before *E* is the *resolution* of the set of +states {*S′(E′)*, *S′(E″)*, …} after the `prev_events` {*E′*, *E″*, …}. +of *E*. The *resolution* of a set of states is defined as follows. The resolved state is built up in a number of passes; here we use *R* to refer to the From 29e70360436c078db932d013863ece5c8fa1d65b Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 10 May 2022 20:31:19 +0100 Subject: [PATCH 03/19] Auth rules: PDU content definitions cross-refs (#1050) * Auth rules: PDU content definitions cross-refs * Changelog * Apparently v6 & v7 auth rules aren't in fragments --- .../room_versions/newsfragments/1050.clarification | 1 + content/rooms/fragments/v1-auth-rules.md | 10 +++++----- content/rooms/fragments/v3-auth-rules.md | 10 +++++----- content/rooms/fragments/v8-auth-rules.md | 10 +++++----- content/rooms/v6.md | 10 +++++----- content/rooms/v7.md | 10 +++++----- 6 files changed, 26 insertions(+), 25 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1050.clarification diff --git a/changelogs/room_versions/newsfragments/1050.clarification b/changelogs/room_versions/newsfragments/1050.clarification new file mode 100644 index 00000000..0da1098a --- /dev/null +++ b/changelogs/room_versions/newsfragments/1050.clarification @@ -0,0 +1 @@ +Add cross-references to PDU content definitions from the authorisation rules. diff --git a/content/rooms/fragments/v1-auth-rules.md b/content/rooms/fragments/v1-auth-rules.md index d7c4dace..e2429313 100644 --- a/content/rooms/fragments/v1-auth-rules.md +++ b/content/rooms/fragments/v1-auth-rules.md @@ -4,11 +4,11 @@ toc_hide: true The types of state events that affect authorization are: -- `m.room.create` -- `m.room.member` -- `m.room.join_rules` -- `m.room.power_levels` -- `m.room.third_party_invite` +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroom) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) {{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. diff --git a/content/rooms/fragments/v3-auth-rules.md b/content/rooms/fragments/v3-auth-rules.md index 1a6ae490..8e902602 100644 --- a/content/rooms/fragments/v3-auth-rules.md +++ b/content/rooms/fragments/v3-auth-rules.md @@ -11,11 +11,11 @@ however. The types of state events that affect authorization are: -- `m.room.create` -- `m.room.member` -- `m.room.join_rules` -- `m.room.power_levels` -- `m.room.third_party_invite` +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroom) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) {{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md index 4b14762d..3583df41 100644 --- a/content/rooms/fragments/v8-auth-rules.md +++ b/content/rooms/fragments/v8-auth-rules.md @@ -12,11 +12,11 @@ of receipt, they are authorized at a later stage: see the The types of state events that affect authorization are: -- `m.room.create` -- `m.room.member` -- `m.room.join_rules` -- `m.room.power_levels` -- `m.room.third_party_invite` +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroom) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) {{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 67131371..cb87082c 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -59,11 +59,11 @@ Events must be signed by the server denoted by the `sender` key. The types of state events that affect authorization are: -- `m.room.create` -- `m.room.member` -- `m.room.join_rules` -- `m.room.power_levels` -- `m.room.third_party_invite` +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroom) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) {{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. diff --git a/content/rooms/v7.md b/content/rooms/v7.md index 07e09238..2ada06f7 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -45,11 +45,11 @@ of receipt, they are authorized at a later stage: see the The types of state events that affect authorization are: -- `m.room.create` -- `m.room.member` -- `m.room.join_rules` -- `m.room.power_levels` -- `m.room.third_party_invite` +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroom) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) {{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. From 61e7a73a4f61942d6a43691914a6f02935364c04 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 10 May 2022 21:40:01 +0200 Subject: [PATCH 04/19] Drop lifetime from the call answer event example (#1054) * Drop lifetime from the call answer event example * Changelog --- changelogs/client_server/newsfragments/1054.clarification | 1 + data/event-schemas/examples/m.call.answer.yaml | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1054.clarification diff --git a/changelogs/client_server/newsfragments/1054.clarification b/changelogs/client_server/newsfragments/1054.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1054.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/event-schemas/examples/m.call.answer.yaml b/data/event-schemas/examples/m.call.answer.yaml index a4cfc1e1..aaa4da71 100644 --- a/data/event-schemas/examples/m.call.answer.yaml +++ b/data/event-schemas/examples/m.call.answer.yaml @@ -4,7 +4,6 @@ "content": { "version" : 0, "call_id": "12345", - "lifetime": 60000, "answer": { "type" : "answer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" From 9ede29a01dae856ecb0649e5e85e2f6e2ccbea19 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 10 May 2022 20:51:23 +0100 Subject: [PATCH 05/19] Attempt to define a valid event (#1045) * Attempt to define a valid event Resolves #1044. Well, maybe. * Changelog * link to /rooms, thanks Travis Co-authored-by: Travis Ralston Co-authored-by: Travis Ralston --- changelogs/server_server/newsfragments/1045.clarification | 1 + content/server-server-api.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1045.clarification diff --git a/changelogs/server_server/newsfragments/1045.clarification b/changelogs/server_server/newsfragments/1045.clarification new file mode 100644 index 00000000..7b805569 --- /dev/null +++ b/changelogs/server_server/newsfragments/1045.clarification @@ -0,0 +1 @@ +Expand a little on what it means for a PDU to be valid when discussing checks on PDUs. diff --git a/content/server-server-api.md b/content/server-server-api.md index 349649bd..991806af 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -356,7 +356,9 @@ specification](/rooms). Whenever a server receives an event from a remote server, the receiving server must ensure that the event: -1. Is a valid event, otherwise it is dropped. +1. Is a valid event, otherwise it is dropped. For an event to be valid, it + must contain a `room_id`, and it must comply with the event format of + that [room version](/rooms). 2. Passes signature checks, otherwise it is dropped. 3. Passes hash checks, otherwise it is redacted before being processed further. From 573dbb3b74978d56b7aeab317a64811e6d3f666d Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Wed, 11 May 2022 18:14:24 +0100 Subject: [PATCH 06/19] Fix error code typo (#1059) * Fix error code typo See https://spec.matrix.org/v1.2/client-server-api/#other-error-codes * Create 1059.clarification --- changelogs/client_server/newsfragments/1059.clarification | 1 + data/api/client-server/room_state.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1059.clarification diff --git a/changelogs/client_server/newsfragments/1059.clarification b/changelogs/client_server/newsfragments/1059.clarification new file mode 100644 index 00000000..2e94fb7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1059.clarification @@ -0,0 +1 @@ +Fix room state 400 code error examples to match known error codes. diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index 89792e63..d43bc802 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -114,7 +114,7 @@ paths: Some example error codes include: - * `M_INVALID_PARAMETER`: One or more aliases within the `m.room.canonical_alias` + * `M_INVALID_PARAM`: One or more aliases within the `m.room.canonical_alias` event have invalid syntax. * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event From c4e54509dbc9e2883b95325ddac9cafc2273273f Mon Sep 17 00:00:00 2001 From: David Robertson Date: Mon, 23 May 2022 18:22:33 +0100 Subject: [PATCH 07/19] PDU check 5 should consult state before an event (#1070) --- changelogs/server_server/newsfragments/1070.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1070.clarification diff --git a/changelogs/server_server/newsfragments/1070.clarification b/changelogs/server_server/newsfragments/1070.clarification new file mode 100644 index 00000000..6661503e --- /dev/null +++ b/changelogs/server_server/newsfragments/1070.clarification @@ -0,0 +1 @@ +Clarify that checks on PDUs should refer to the state _before_ an event. diff --git a/content/server-server-api.md b/content/server-server-api.md index 991806af..24b6a889 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -364,7 +364,7 @@ server must ensure that the event: further. 4. Passes authorization rules based on the event's auth events, otherwise it is rejected. -5. Passes authorization rules based on the state at the event, +5. Passes authorization rules based on the state before the event, otherwise it is rejected. 6. Passes authorization rules based on the current state of the room, otherwise it is "soft failed". From bb47f08ee7f21928461c295fc44fd7585a0cfb4a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 25 May 2022 12:27:30 +0200 Subject: [PATCH 08/19] Remove broken "token-based" link (#1081) This used to link to a section in the UIA docs (https://matrix.org/docs/spec/client_server/r0.6.1#token-based), but that was removed in 7c6636a5. --- changelogs/client_server/newsfragments/1081.clarification | 1 + content/client-server-api/_index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1081.clarification diff --git a/changelogs/client_server/newsfragments/1081.clarification b/changelogs/client_server/newsfragments/1081.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1081.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 3edb5b16..da19a7de 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1056,8 +1056,8 @@ as follows: } ``` -As with [token-based]() interactive login, the `token` must encode the -user ID. In the case that the token is not valid, the homeserver must +The `token` must encode the user ID, since there is no other identifying +data in the request. In the case that the token is not valid, the homeserver must respond with `403 Forbidden` and an error code of `M_FORBIDDEN`. If the homeserver advertises `m.login.sso` as a viable flow, and the From c11991f9de39383a3ac4e387c26e498a571c7f0a Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 22 Jun 2021 17:46:24 +0200 Subject: [PATCH 09/19] openapi_extensions.md: add a clarification for oneOf --- openapi_extensions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openapi_extensions.md b/openapi_extensions.md index 6905d663..22d1ac66 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -54,6 +54,8 @@ doesn't work, as in the following example: properties: ... ``` +This can only be used to define the type of named properties. In particular, +the current tooling does not support `oneOf` inside `additionalProperties`. ## OpenAPI 3's "2xx" format for response codes From f8bf0fa0ac70e59edb4304682863eccd63eff2aa Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 22 Jun 2021 17:51:53 +0200 Subject: [PATCH 10/19] profile.yaml: require displayname/avatar_url This makes a deliberate choice for the question stated in #2717. --- data/api/client-server/profile.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index e8bdc4de..84502580 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -56,6 +56,7 @@ paths: displayname: type: string description: The new display name for this user. + required: ["displayname"] responses: 200: description: The display name was set. @@ -131,6 +132,7 @@ paths: type: string format: uri description: The new avatar URL for this user. + required: ["avatar_url"] responses: 200: description: The avatar URL was set. From 7abdd45c06bc82d801959b8682442c3eb2a8deee Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 22 Jun 2021 17:53:41 +0200 Subject: [PATCH 11/19] notifications.yaml: Use int64 for timestamp --- data/api/client-server/notifications.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 6d141ff8..809b2c0d 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -126,6 +126,7 @@ paths: description: The ID of the room in which the event was posted. ts: type: integer + format: int64 description: |- The unix timestamp at which the event notification was sent, in milliseconds. From 92db4e20da9b1f340e12860cbfb524375ce77134 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 22 Jun 2021 17:54:58 +0200 Subject: [PATCH 12/19] /password: formalise 'default' for logout_devices --- data/api/client-server/registration.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 810d8bc9..d500cfc4 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -352,9 +352,10 @@ paths: example: "ihatebananas" logout_devices: type: boolean + default: true description: |- Whether the user's other access tokens, and their associated devices, should be - revoked if the request succeeds. Defaults to true. + revoked if the request succeeds. When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) for the user's remaining devices. From e38c4e6f179271ec7f72b800b5a77a7044dee7b4 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Fri, 27 May 2022 18:22:16 +0200 Subject: [PATCH 13/19] Revert accidentally pushed commits This reverts commits: c11991f9de39383a3ac4e387c26e498a571c7f0a. f8bf0fa0ac70e59edb4304682863eccd63eff2aa. 7abdd45c06bc82d801959b8682442c3eb2a8deee. 92db4e20da9b1f340e12860cbfb524375ce77134. --- data/api/client-server/notifications.yaml | 1 - data/api/client-server/profile.yaml | 2 -- data/api/client-server/registration.yaml | 3 +-- openapi_extensions.md | 2 -- 4 files changed, 1 insertion(+), 7 deletions(-) diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 809b2c0d..6d141ff8 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -126,7 +126,6 @@ paths: description: The ID of the room in which the event was posted. ts: type: integer - format: int64 description: |- The unix timestamp at which the event notification was sent, in milliseconds. diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 84502580..e8bdc4de 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -56,7 +56,6 @@ paths: displayname: type: string description: The new display name for this user. - required: ["displayname"] responses: 200: description: The display name was set. @@ -132,7 +131,6 @@ paths: type: string format: uri description: The new avatar URL for this user. - required: ["avatar_url"] responses: 200: description: The avatar URL was set. diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index d500cfc4..810d8bc9 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -352,10 +352,9 @@ paths: example: "ihatebananas" logout_devices: type: boolean - default: true description: |- Whether the user's other access tokens, and their associated devices, should be - revoked if the request succeeds. + revoked if the request succeeds. Defaults to true. When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) for the user's remaining devices. diff --git a/openapi_extensions.md b/openapi_extensions.md index 22d1ac66..6905d663 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -54,8 +54,6 @@ doesn't work, as in the following example: properties: ... ``` -This can only be used to define the type of named properties. In particular, -the current tooling does not support `oneOf` inside `additionalProperties`. ## OpenAPI 3's "2xx" format for response codes From 25a9dcfd3cef268fc672098eeb6f1dd8df660007 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Sat, 28 May 2022 03:04:09 +0100 Subject: [PATCH 14/19] Clarify that the resident server should sign the restricted join (#1093) * Clarify that server should sign the restricted join * Changelog * Changelog --- changelogs/room_versions/newsfragments/1093.clarification | 1 + content/rooms/fragments/v8-auth-rules.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1093.clarification diff --git a/changelogs/room_versions/newsfragments/1093.clarification b/changelogs/room_versions/newsfragments/1093.clarification new file mode 100644 index 00000000..6176b102 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1093.clarification @@ -0,0 +1 @@ +Auth rules: clarify that the resident server must sign a restricted join event. diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md index 3583df41..6a548787 100644 --- a/content/rooms/fragments/v8-auth-rules.md +++ b/content/rooms/fragments/v8-auth-rules.md @@ -46,7 +46,7 @@ The rules are as follows: 1. If no `state_key` key or `membership` key in `content`, reject. 2. If `content` has a `join_authorised_via_users_server` key: - 1. If the event is not validly signed by the user ID denoted + 1. If the event is not validly signed by the homeserver of the user ID denoted by the key, reject. 3. If `membership` is `join`: 1. If the only previous event is an `m.room.create` and the From 3f7b0e80a3c5de7d1e142a080a11f2f56f4b21f4 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Mon, 30 May 2022 14:13:55 +0100 Subject: [PATCH 15/19] Minor drive-by state res clarifications (#1042) * Opinionated rewrite of unconflicted state map * Define auth chain --- .../newsfragments/1042.clarification | 1 + content/rooms/fragments/v2-state-res.md | 27 +++++++++++++------ 2 files changed, 20 insertions(+), 8 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1042.clarification diff --git a/changelogs/server_server/newsfragments/1042.clarification b/changelogs/server_server/newsfragments/1042.clarification new file mode 100644 index 00000000..2f3fad6f --- /dev/null +++ b/changelogs/server_server/newsfragments/1042.clarification @@ -0,0 +1 @@ +Clarify the meaning of "unconflicted state map" and "auth chain" in state res v2. diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index d12f45c3..e666d7f8 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -30,11 +30,22 @@ the `membership` is `leave` or `ban` and the `sender` does not match the might remove someone's ability to do something in the room. **Unconflicted state map and conflicted state set.** -The *unconflicted state map* is the state where the value of each key -exists and is the same in each state *S**i*. The *conflicted -state set* is the set of all other state events. Note that the -unconflicted state map only has one event per `(event_type, state_key)`, -whereas the conflicted state set may have multiple events. +The keys of the state maps *Si* are 2-tuples of strings of the form +*K* = `(event_type, state_key)`. The values *V* are state events. +The key-value pairs (*K*, *V*) across all state maps *Si* can be +divided into two collections. +If a given key *K* is present in every *Si* with the same value *V* +in each state map, then the pair (*K*, *V*) belongs to the *unconflicted state map*. +Otherwise (*K*, *V*) belongs to the *conflicted state set*. + +Note that the unconflicted state map only has one event for each key *K*, +whereas the conflicted state set may associate multiple events to the same key. + +**Auth chain.** +The *auth chain* of an event *E* is the set containing all of *E*'s auth events, +all of *their* auth events, and so on recursively, stretching back to the +start of the room. Put differently, these are the events reachable by walking +the graph induced by an event's `auth_events` links. **Auth difference.** The *auth difference* is calculated by first calculating the full auth @@ -111,9 +122,9 @@ the auth event is not rejected. The *resolution* of a set of states is obtained as follows: -1. Take all *power events* and any events in their auth chains, - recursively, that appear in the *full conflicted set* and order them - by the *reverse topological power ordering*. +1. Select all *power events* that appear in the *full conflicted set*. Compute + the union of their auth chains, including the power events themselves. + Sort the union using the *reverse topological power ordering*. 2. Apply the *iterative auth checks algorithm*, starting from the *unconflicted state map*, to the list of events from the previous step to get a partially resolved state. From 278005519826d6fa9390470c6dda2e2ea8db23eb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 30 May 2022 17:33:56 -0400 Subject: [PATCH 16/19] clarify federation Authorization header an add destination property (#1067) * clarify federation Authorization header an add destination property * add changelogs * some clarifications * more clarifications, fixes * use HTML in the added-in/changed-in shortcodes * Apply suggestions from code review Co-authored-by: Travis Ralston --- .../newsfragments/1067.clarification | 1 + .../server_server/newsfragments/1067.feature | 1 + content/server-server-api.md | 46 +++++++++++++++++-- layouts/shortcodes/added-in.html | 6 +-- layouts/shortcodes/changed-in.html | 6 +-- 5 files changed, 50 insertions(+), 10 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1067.clarification create mode 100644 changelogs/server_server/newsfragments/1067.feature diff --git a/changelogs/server_server/newsfragments/1067.clarification b/changelogs/server_server/newsfragments/1067.clarification new file mode 100644 index 00000000..ad1ca8f0 --- /dev/null +++ b/changelogs/server_server/newsfragments/1067.clarification @@ -0,0 +1 @@ +Clarify the format for the Authorization header. diff --git a/changelogs/server_server/newsfragments/1067.feature b/changelogs/server_server/newsfragments/1067.feature new file mode 100644 index 00000000..1e88a3d9 --- /dev/null +++ b/changelogs/server_server/newsfragments/1067.feature @@ -0,0 +1 @@ +Add a destination property to the Authorization header. diff --git a/content/server-server-api.md b/content/server-server-api.md index 24b6a889..f70e8994 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -255,7 +255,7 @@ condition applies throughout the request signing process. Step 2 add Authorization header: GET /target HTTP/1.1 - Authorization: X-Matrix origin=origin.hs.example.com,key="ed25519:key1",sig="ABCDEF..." + Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..." Content-Type: application/json @@ -283,14 +283,52 @@ def authorization_headers(origin_name, origin_signing_key, for key, sig in signed_json["signatures"][origin_name].items(): authorization_headers.append(bytes( - "X-Matrix origin=%s,key=\"%s\",sig=\"%s\"" % ( - origin_name, key, sig, + "X-Matrix origin=\"%s\",destination=\"%s\",key=\"%s\",sig=\"%s\"" % ( + origin_name, destination_name, key, sig, ) )) - return ("Authorization", authorization_headers) + return ("Authorization", authorization_headers[0]) ``` +The format of the Authorization header is given in +[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In +summary, the header begins with authorization scheme `X-Matrix`, followed by +one or more spaces, followed by a comma-separated list of parameters written as +name=value pairs. The names are case insensitive and order does not matter. The +values must be enclosed in quotes if they contain characters that are not +allowed in `token`s, as defined in +[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a +value is a valid `token`, it may or may not be enclosed in quotes. Quoted +values may include backslash-escaped characters. When parsing the header, the +recipient must unescape the characters. That is, a backslash-character pair is +replaced by the character that follows the backslash. + +For compatibility with older servers, the sender should +- only include one space after `X-Matrix`, +- only use lower-case names, and +- avoid using backslashes in parameter values. + +For compatibility with older servers, the recipient should allow colons to be +included in values without requiring the value to be enclosed in quotes. + +The authorization parameters to include are: + +- `origin`: the server name of the sending server. This is the same as the + `origin` field from JSON described in step 1. +- `destination`: {{< added-in v="1.3" >}} the server name of the receiving + sender. This is the same as the `destination` field from the JSON described + in step 1. For compatibility with older servers, recipients should accept + requests without this parameter, but MUST always send it. If this property + is included, but the value does not match the receiving server's name, the + receiving server must deny the request with an HTTP status code 401 + Unauthorized. +- `key`: the ID, including the algorithm name, of the sending server's key used + to sign the request. +- `signature`: the signature of the JSON as calculated in step 1. + +Unknown parameters are ignored. + ### Response Authentication Responses are authenticated by the TLS server certificate. A homeserver diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html index 4113d922..149be685 100644 --- a/layouts/shortcodes/added-in.html +++ b/layouts/shortcodes/added-in.html @@ -2,7 +2,7 @@ {{ $this := .Params.this }} {{ if $this }} - **[New in this version]** + [New in this version] {{ else }} - **[Added in `v{{ $ver }}`]** -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} \ No newline at end of file + [Added in v{{ $ver }}] +{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} diff --git a/layouts/shortcodes/changed-in.html b/layouts/shortcodes/changed-in.html index 0eb35faa..8da2559a 100644 --- a/layouts/shortcodes/changed-in.html +++ b/layouts/shortcodes/changed-in.html @@ -2,7 +2,7 @@ {{ $this := .Params.this }} {{ if $this }} - **[Changed in this version]** + [Changed in this version] {{ else }} - **[Changed in `v{{ $ver }}`]** -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} \ No newline at end of file + [Changed in v{{ $ver }}] +{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} From 515269b2e337b14957a7e0d0a456566a0a08bde8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 31 May 2022 09:24:06 -0600 Subject: [PATCH 17/19] Unify & standardize the v1.3 changelog (#1102) * Reference MSCs where MSCs were not being referenced. * Alter language to appear consistent and from a single voice. * Bundle and group various changes together (will affect the final changelog - the rendered one still doesn't bundle appropriately). * Move entries to the spec area they are intended to be in. --- changelogs/client_server/newsfragments/1003.clarification | 2 +- changelogs/client_server/newsfragments/1059.clarification | 2 +- changelogs/client_server/newsfragments/3681.clarification | 2 +- changelogs/room_versions/newsfragments/1037.clarification | 3 +-- changelogs/room_versions/newsfragments/1042.clarification | 1 + changelogs/room_versions/newsfragments/1043.clarification | 2 +- changelogs/room_versions/newsfragments/1050.clarification | 2 +- changelogs/room_versions/newsfragments/1093.clarification | 2 +- changelogs/room_versions/newsfragments/3737.clarification | 2 +- changelogs/room_versions/newsfragments/3739.feature | 2 +- changelogs/server_server/newsfragments/1038.clarification | 2 +- changelogs/server_server/newsfragments/1042.clarification | 1 - changelogs/server_server/newsfragments/1045.clarification | 2 +- changelogs/server_server/newsfragments/1055.clarification | 2 +- changelogs/server_server/newsfragments/1067.feature | 2 +- changelogs/server_server/newsfragments/1070.clarification | 2 +- changelogs/server_server/newsfragments/998.clarification | 2 +- 17 files changed, 16 insertions(+), 17 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1042.clarification delete mode 100644 changelogs/server_server/newsfragments/1042.clarification diff --git a/changelogs/client_server/newsfragments/1003.clarification b/changelogs/client_server/newsfragments/1003.clarification index efe68e48..9b2788cc 100644 --- a/changelogs/client_server/newsfragments/1003.clarification +++ b/changelogs/client_server/newsfragments/1003.clarification @@ -1 +1 @@ -Adjust the OpenAPI specification so that the type `Flow information` is explicitly defined when the CS spec is rendered. +Adjust the OpenAPI specification so that the type `Flow information` is explicitly defined when the client-server API is rendered. diff --git a/changelogs/client_server/newsfragments/1059.clarification b/changelogs/client_server/newsfragments/1059.clarification index 2e94fb7f..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/1059.clarification +++ b/changelogs/client_server/newsfragments/1059.clarification @@ -1 +1 @@ -Fix room state 400 code error examples to match known error codes. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/3681.clarification b/changelogs/client_server/newsfragments/3681.clarification index f7c29003..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/3681.clarification +++ b/changelogs/client_server/newsfragments/3681.clarification @@ -1 +1 @@ -Fix broken syntax in Server Access Control Lists definition. \ No newline at end of file +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1037.clarification b/changelogs/room_versions/newsfragments/1037.clarification index 9ac53c6d..e8aa3349 100644 --- a/changelogs/room_versions/newsfragments/1037.clarification +++ b/changelogs/room_versions/newsfragments/1037.clarification @@ -1,2 +1 @@ -Improve readability of definitions in the state resolution v2 algorithm. - +Improve readability and understanding of the state resolution algorithms. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1042.clarification b/changelogs/room_versions/newsfragments/1042.clarification new file mode 100644 index 00000000..e8aa3349 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1042.clarification @@ -0,0 +1 @@ +Improve readability and understanding of the state resolution algorithms. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1043.clarification b/changelogs/room_versions/newsfragments/1043.clarification index 49e552f4..e8aa3349 100644 --- a/changelogs/room_versions/newsfragments/1043.clarification +++ b/changelogs/room_versions/newsfragments/1043.clarification @@ -1 +1 @@ -Adjust mathematical notation used in the description of state resolution to render better in browsers. \ No newline at end of file +Improve readability and understanding of the state resolution algorithms. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1050.clarification b/changelogs/room_versions/newsfragments/1050.clarification index 0da1098a..f548b987 100644 --- a/changelogs/room_versions/newsfragments/1050.clarification +++ b/changelogs/room_versions/newsfragments/1050.clarification @@ -1 +1 @@ -Add cross-references to PDU content definitions from the authorisation rules. +Improve readability of the authorization rules. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1093.clarification b/changelogs/room_versions/newsfragments/1093.clarification index 6176b102..06145378 100644 --- a/changelogs/room_versions/newsfragments/1093.clarification +++ b/changelogs/room_versions/newsfragments/1093.clarification @@ -1 +1 @@ -Auth rules: clarify that the resident server must sign a restricted join event. +For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/3737.clarification b/changelogs/room_versions/newsfragments/3737.clarification index c3b51679..6caf519a 100644 --- a/changelogs/room_versions/newsfragments/3737.clarification +++ b/changelogs/room_versions/newsfragments/3737.clarification @@ -1 +1 @@ -Fix join membership auth rules when `join_rule` is `knock`. +For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. diff --git a/changelogs/room_versions/newsfragments/3739.feature b/changelogs/room_versions/newsfragments/3739.feature index c20ec3ad..ddb88446 100644 --- a/changelogs/room_versions/newsfragments/3739.feature +++ b/changelogs/room_versions/newsfragments/3739.feature @@ -1 +1 @@ -Update the default room version to 9. \ No newline at end of file +Update the default room version to 9 as per [MSC3589](https://github.com/matrix-org/matrix-spec-proposals/pull/3589). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1038.clarification b/changelogs/server_server/newsfragments/1038.clarification index 39fbeddb..ad1ca8f0 100644 --- a/changelogs/server_server/newsfragments/1038.clarification +++ b/changelogs/server_server/newsfragments/1038.clarification @@ -1 +1 @@ -Fix origin server name in S2S Request Authentication example. +Clarify the format for the Authorization header. diff --git a/changelogs/server_server/newsfragments/1042.clarification b/changelogs/server_server/newsfragments/1042.clarification deleted file mode 100644 index 2f3fad6f..00000000 --- a/changelogs/server_server/newsfragments/1042.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the meaning of "unconflicted state map" and "auth chain" in state res v2. diff --git a/changelogs/server_server/newsfragments/1045.clarification b/changelogs/server_server/newsfragments/1045.clarification index 7b805569..adb3ec16 100644 --- a/changelogs/server_server/newsfragments/1045.clarification +++ b/changelogs/server_server/newsfragments/1045.clarification @@ -1 +1 @@ -Expand a little on what it means for a PDU to be valid when discussing checks on PDUs. +Clarify what a "valid event" means when performing checks on a received PDU. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1055.clarification b/changelogs/server_server/newsfragments/1055.clarification index 748f7793..f9394c6a 100644 --- a/changelogs/server_server/newsfragments/1055.clarification +++ b/changelogs/server_server/newsfragments/1055.clarification @@ -1 +1 @@ -Clarify that valid_until_ts is in milliseconds, like other timestamps used in Matrix +Clarify that `valid_until_ts` is in milliseconds, like other timestamps used in Matrix. diff --git a/changelogs/server_server/newsfragments/1067.feature b/changelogs/server_server/newsfragments/1067.feature index 1e88a3d9..0b067b36 100644 --- a/changelogs/server_server/newsfragments/1067.feature +++ b/changelogs/server_server/newsfragments/1067.feature @@ -1 +1 @@ -Add a destination property to the Authorization header. +Add a `destination` property to the Authorization header, as per [MSC3383](https://github.com/matrix-org/matrix-spec-proposals/pull/3383). diff --git a/changelogs/server_server/newsfragments/1070.clarification b/changelogs/server_server/newsfragments/1070.clarification index 6661503e..ef4b1e6a 100644 --- a/changelogs/server_server/newsfragments/1070.clarification +++ b/changelogs/server_server/newsfragments/1070.clarification @@ -1 +1 @@ -Clarify that checks on PDUs should refer to the state _before_ an event. +Clarify that checks on PDUs should refer to the state *before* an event. diff --git a/changelogs/server_server/newsfragments/998.clarification b/changelogs/server_server/newsfragments/998.clarification index c285269a..495fdade 100644 --- a/changelogs/server_server/newsfragments/998.clarification +++ b/changelogs/server_server/newsfragments/998.clarification @@ -1 +1 @@ -Remove `origin` field from PDUs which exists on many but not all PDUs in practice and doesn't serve an actual purpose. +Remove largely unused `origin` field from PDUs. From a91030f27bf6b54f9fd32c38a653c0881070c0f4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 31 May 2022 09:24:25 -0600 Subject: [PATCH 18/19] Re-add paragraph about how some state keys are reserved (#1100) * Re-add paragraph about how some state keys are reserved Fixes https://github.com/matrix-org/matrix-spec/issues/1013 * changelog --- changelogs/client_server/newsfragments/1100.clarification | 1 + .../definitions/client_event_without_room_id.yaml | 4 ++++ 2 files changed, 5 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1100.clarification diff --git a/changelogs/client_server/newsfragments/1100.clarification b/changelogs/client_server/newsfragments/1100.clarification new file mode 100644 index 00000000..e17a2538 --- /dev/null +++ b/changelogs/client_server/newsfragments/1100.clarification @@ -0,0 +1 @@ +Clarify that state keys starting with `@` are in fact reserved. Regressed from [#3658](https://github.com/matrix-org/matrix-spec-proposals/pull/3658). \ No newline at end of file diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml index 1b6d6073..c4db8b0e 100644 --- a/data/api/client-server/definitions/client_event_without_room_id.yaml +++ b/data/api/client-server/definitions/client_event_without_room_id.yaml @@ -38,6 +38,10 @@ properties: Present if, and only if, this event is a *state* event. The key making this piece of state unique in the room. Note that it is often an empty string. + + State keys starting with an `@` are reserved for referencing user IDs, such + as room members. With the exception of a few events, state events set with a + given user's ID as the state key MUST only be set by that user. type: string example: '@user:example.org' sender: From 10bd1b50383c43a1b83aa01b42de5578a49aa200 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 31 May 2022 09:24:45 -0600 Subject: [PATCH 19/19] Re-add timestamp massaging (#1094) * Re-add timestamp massaging Per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316) * changelog --- .../newsfragments/1094.feature | 1 + content/application-service-api.md | 39 +++++++++++++++---- 2 files changed, 33 insertions(+), 7 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1094.feature diff --git a/changelogs/application_service/newsfragments/1094.feature b/changelogs/application_service/newsfragments/1094.feature new file mode 100644 index 00000000..e1b2d5cb --- /dev/null +++ b/changelogs/application_service/newsfragments/1094.feature @@ -0,0 +1 @@ +Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). \ No newline at end of file diff --git a/content/application-service-api.md b/content/application-service-api.md index 07362c51..61227660 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -300,13 +300,38 @@ An example request would be: #### Timestamp massaging -Previous drafts of the Application Service API permitted application -services to alter the timestamp of their sent events by providing a `ts` -query parameter when sending an event. This API has been excluded from -the first release due to design concerns, however some servers may still -support the feature. Please visit [issue -\#1585](https://github.com/matrix-org/matrix-doc/issues/1585) for more -information. +{{% added-in v="1.3" %}} + +Application services can alter the timestamp associated with an event, allowing +the application service to better represent the "real" time an event was sent +at. While this doesn't affect the server-side ordering of the event, it can allow +an application service to better represent when an event would have been sent/received +at, such as in the case of bridges where the remote network might have a slight +delay and the application service wishes to bridge the proper time onto the message. + +When authenticating requests as an application service, the caller can append a `ts` +query string argument to change the `origin_server_ts` of the resulting event. Attempting +to set the timestamp to anything other than what is accepted by `origin_server_ts` should +be rejected by the server as a bad request. + +When not present, the server's behaviour is unchanged: the local system time of the server +will be used to provide a timestamp, representing "now". + +The `ts` query string argument is only valid on the following endpoints: + +* [`PUT /rooms/{roomId}/send/{eventType}/{txnId}`](/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) +* [`PUT /rooms/{roomId}/state/{eventType}/{stateKey}`](/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + +Other endpoints, such as `/kick`, do not support `ts`: instead, callers can use the +`PUT /state` endpoint to mimic the behaviour of the other APIs. + +{{% boxes/warning %}} +Changing the time of an event does not change the server-side (DAG) ordering for the +event. The event will still be appended at the tip of the DAG as though the timestamp +was set to "now". Future MSCs, like [MSC2716](https://github.com/matrix-org/matrix-spec-proposals/pull/2716), +are expected to provide functionality which can allow DAG order manipulation (for history +imports and similar behaviour). +{{% /boxes/warning %}} #### Server admin style permissions