From 05620913d5a0a5c177bd3a327400a102fa8bc157 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 31 Jan 2023 19:59:40 +0000 Subject: [PATCH 01/32] Fix anchor for room-knocking heading (#1423) Fixes #1407 --- changelogs/room_versions/newsfragments/1423.clarification | 1 + content/server-server-api.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1423.clarification diff --git a/changelogs/room_versions/newsfragments/1423.clarification b/changelogs/room_versions/newsfragments/1423.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1423.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index 13bd9934..34f9f5b5 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -877,7 +877,8 @@ on the resulting `m.room.member` event. If the joining server fails all conditions then a 403 `M_FORBIDDEN` error is used by the resident server. -## Knocking upon a room + +## Knocking upon a room Rooms can permit knocking through the join rules, and if permitted this gives users a way to request to join (be invited) to the room. Users who From a7790fcbbf79c7570439f7a3ac890b69c4d84222 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 31 Jan 2023 20:00:26 +0000 Subject: [PATCH 02/32] Clarify room version grammar (#1422) Apparently the SHOULD is confusing --- changelogs/room_versions/newsfragments/1422.clarification | 1 + content/rooms/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1422.clarification diff --git a/changelogs/room_versions/newsfragments/1422.clarification b/changelogs/room_versions/newsfragments/1422.clarification new file mode 100644 index 00000000..efb63c69 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1422.clarification @@ -0,0 +1 @@ +Clarify the grammar for room versions. diff --git a/content/rooms/_index.md b/content/rooms/_index.md index 190b305e..e75fbb13 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -86,7 +86,7 @@ split-brain situation due to not understanding the new rules. A room version is defined as a string of characters which MUST NOT exceed 32 codepoints in length. Room versions MUST NOT be empty and -SHOULD contain only the characters `a-z`, `0-9`, `.`, and `-`. +MUST contain only the characters `a-z`, `0-9`, `.`, and `-`. Room versions are not intended to be parsed and should be treated as opaque identifiers. Room versions consisting only of the characters From 5c485ade2ec46402c91027f2424f4d7cda3be6ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Feb 2023 11:58:11 -0700 Subject: [PATCH 03/32] Prepare changelogs for v1.6 --- changelogs/application_service/newsfragments/1347.feature | 2 +- changelogs/client_server/newsfragments/1347.feature | 2 +- changelogs/identity_service/newsfragments/1347.feature | 2 +- changelogs/internal/newsfragments/1370.clarification | 2 +- changelogs/push_gateway/newsfragments/1347.feature | 2 +- changelogs/server_server/newsfragments/1347.feature | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/changelogs/application_service/newsfragments/1347.feature b/changelogs/application_service/newsfragments/1347.feature index 175d13d5..f5aa481f 100644 --- a/changelogs/application_service/newsfragments/1347.feature +++ b/changelogs/application_service/newsfragments/1347.feature @@ -1 +1 @@ -Add information on standard error responses for unknown endpoints/methods. +Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/client_server/newsfragments/1347.feature b/changelogs/client_server/newsfragments/1347.feature index 175d13d5..f5aa481f 100644 --- a/changelogs/client_server/newsfragments/1347.feature +++ b/changelogs/client_server/newsfragments/1347.feature @@ -1 +1 @@ -Add information on standard error responses for unknown endpoints/methods. +Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/identity_service/newsfragments/1347.feature b/changelogs/identity_service/newsfragments/1347.feature index 175d13d5..f5aa481f 100644 --- a/changelogs/identity_service/newsfragments/1347.feature +++ b/changelogs/identity_service/newsfragments/1347.feature @@ -1 +1 @@ -Add information on standard error responses for unknown endpoints/methods. +Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/internal/newsfragments/1370.clarification b/changelogs/internal/newsfragments/1370.clarification index 4ce9b9cb..84780634 100644 --- a/changelogs/internal/newsfragments/1370.clarification +++ b/changelogs/internal/newsfragments/1370.clarification @@ -1,2 +1,2 @@ -Rename "" to "content" in the OpenAPI files for content uploads. +Rename `` to `content` in the OpenAPI files for content uploads. diff --git a/changelogs/push_gateway/newsfragments/1347.feature b/changelogs/push_gateway/newsfragments/1347.feature index 175d13d5..f5aa481f 100644 --- a/changelogs/push_gateway/newsfragments/1347.feature +++ b/changelogs/push_gateway/newsfragments/1347.feature @@ -1 +1 @@ -Add information on standard error responses for unknown endpoints/methods. +Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/server_server/newsfragments/1347.feature b/changelogs/server_server/newsfragments/1347.feature index 175d13d5..f5aa481f 100644 --- a/changelogs/server_server/newsfragments/1347.feature +++ b/changelogs/server_server/newsfragments/1347.feature @@ -1 +1 @@ -Add information on standard error responses for unknown endpoints/methods. +Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). From e9a463d87147cc15e18153c4fc4d3011fc6b30cc Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 7 Feb 2023 15:50:31 -0500 Subject: [PATCH 04/32] Send heroes for nameless rooms on send_join (#1425) Co-authored-by: Patrick Cloke --- changelogs/server_server/newsfragments/1425.feature | 1 + data/api/server-server/joins-v2.yaml | 10 ++++++++++ 2 files changed, 11 insertions(+) create mode 100644 changelogs/server_server/newsfragments/1425.feature diff --git a/changelogs/server_server/newsfragments/1425.feature b/changelogs/server_server/newsfragments/1425.feature new file mode 100644 index 00000000..1add27ff --- /dev/null +++ b/changelogs/server_server/newsfragments/1425.feature @@ -0,0 +1 @@ +Note that `/_matrix/federation/v2/send_join` should include heroes for nameless rooms, even when allowed to omit membership events, per [MSC3943](https://github.com/matrix-org/matrix-doc/pull/3943). diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 1248c0c9..129e5d2e 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -72,6 +72,16 @@ paths: If `true`, indicates that that calling server can accept a reduced response, in which membership events are omitted from `state` and redundant events are omitted from `auth_chain`. + + If the room to be joined has no `m.room.name` nor + `m.room.canonical_alias` events in its current state, the resident + server should determine the room members who would be included in + the `m.heroes` property of the room summary as defined in the + [Client-Server /sync + response](/client-server-api/#get_matrixclientv3sync). The resident + server should include these members' membership events in the + response `state` field, and include the auth chains for these + membership events in the response `auth_chain` field. x-addedInMatrixVersion: "1.6" - in: body name: body From ad94985754cdeb359ad9865901861cdab2ed7a04 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 9 Feb 2023 23:58:16 -0500 Subject: [PATCH 05/32] Define hkdf-hmac-sha256.v2 MAC method for SAS verification (#1412) Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../client_server/newsfragments/1412.feature | 1 + .../modules/end_to_end_encryption.md | 88 +++++++++++++------ .../examples/m.key.verification.accept.yaml | 2 +- .../m.key.verification.start$m.sas.v1.yaml | 2 +- .../schema/m.key.verification.accept.yaml | 2 +- .../schema/m.key.verification.mac.yaml | 4 +- .../m.key.verification.start$m.sas.v1.yaml | 7 +- 7 files changed, 73 insertions(+), 33 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1412.feature diff --git a/changelogs/client_server/newsfragments/1412.feature b/changelogs/client_server/newsfragments/1412.feature new file mode 100644 index 00000000..5f89e057 --- /dev/null +++ b/changelogs/client_server/newsfragments/1412.feature @@ -0,0 +1 @@ +Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index ad10a633..067fadab 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -668,22 +668,22 @@ The process between Alice and Bob verifying each other would be: the users to select a method. 14. Alice and Bob compare the strings shown by their devices, and tell their devices if they match or not. -15. Assuming they match, Alice and Bob's devices calculate the HMAC of - their own device keys and a comma-separated sorted list of the key - IDs that they wish the other user to verify, using SHA-256 as the - hash function. HMAC is defined in [RFC - 2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is - different for each item and is calculated by generating 32 bytes - (256 bits) using [the key verification HKDF](#hkdf-calculation). +15. Assuming they match, Alice and Bob's devices each calculate Message + Authentication Codes (MACs) for: + * Each of the keys that they wish the other user to verify (usually their + device ed25519 key and their master cross-signing key). + * The complete list of key IDs that they wish the other user to verify. + + The MAC calculation is defined [below](#mac-calculation). 16. Alice's device sends Bob's device an `m.key.verification.mac` message containing the MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does the same for Bob's device keys and key IDs concurrently with Alice. 17. When the other device receives the `m.key.verification.mac` message, - the device calculates the HMAC of its copies of the other device's - keys given in the message, as well as the HMAC of the + the device calculates the MACs of its copies of the other device's + keys given in the message, as well as the MAC of the comma-separated, sorted, list of key IDs in the message. The device - compares these with the HMAC values given in the message, and if + compares these with the MAC values given in the message, and if everything matches then the device keys are verified. 18. Alice and Bob's devices send `m.key.verification.done` messages to complete the verification. @@ -767,7 +767,55 @@ following error codes are used in addition to those already specified: {{% event event="m.key.verification.mac" %}} -###### HKDF calculation +###### MAC calculation + +During the verification process, Message Authentication Codes (MACs) are calculated +for keys and lists of key IDs. + +The method used to calculate these MACs depends upon the value of the +`message_authentication_code` property in the [`m.key.verification.accept`](#mkeyverificationaccept) +message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is +defined as follows: + +The MAC used is HMAC as defined in [RFC +5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash +function. The shared secret is supplied as the input keying material. No salt +is used, and in the info parameter is the concatenation of: + +- The string `MATRIX_KEY_VERIFICATION_MAC`. +- The Matrix ID of the user whose key is being MAC-ed. +- The Device ID of the device sending the MAC. +- The Matrix ID of the other user. +- The Device ID of the device receiving the MAC. +- The `transaction_id` being used. +- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the + item being MAC-ed is the list of key IDs. + +If a key is being MACed, the MAC is performed on the public key as encoded +according to the [key algorithm](#key-algorithms). For example, for `ed25519` +keys, it is the unpadded base64-encoded key. + +If the key list is being MACed, the list is sorted lexicographically and +comma-separated with no extra whitespace added, with each key written in the +form `{algorithm}:{keyId}`. For example, the key list could look like: +`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can +reconstruct the list from the names in the `mac` property of the +`m.key.verification.mac` message and ensure that no keys were added or removed. + +The MAC values are base64-encoded and sent in a +[`m.key.verification.mac`](#mkeyverificationmac) message. + +{{% boxes/note %}} +The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a +bug in the original implementation in libolm. To remedy this, +`hkdf-hmac-sha256.v2` was introduced, which calculates the MAC in the same way, +but uses a correct base64 encoding. `hkdf-hmac-sha256` is deprecated and will +be removed in a future version of the spec. Use of `hkdf-hmac-sha256` should +be avoided whenever possible: if both parties support `hkdf-hmac-sha256.v2`, +then `hkdf-hmac-sha256` MUST not be used. +{{% /boxes/note %}} + +###### SAS HKDF calculation In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869) and uses the previously @@ -815,23 +863,9 @@ HKDF is used over the plain shared secret as it results in a harder attack as well as more uniform data to work with. {{% /boxes/rationale %}} -For verification of each party's device keys, HKDF is as defined in RFC -5869 and uses SHA-256 as the hash function. The shared secret is -supplied as the input keying material. No salt is used, and in the info -parameter is the concatenation of: - -- The string `MATRIX_KEY_VERIFICATION_MAC`. -- The Matrix ID of the user whose key is being MAC-ed. -- The Device ID of the device sending the MAC. -- The Matrix ID of the other user. -- The Device ID of the device receiving the MAC. -- The `transaction_id` being used. -- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the - item being MAC-ed is the list of key IDs. - ###### SAS method: `decimal` -Generate 5 bytes using [HKDF](#hkdf-calculation) then take sequences of 13 bits +Generate 5 bytes using [HKDF](#sas-hkdf-calculation) then take sequences of 13 bits to convert to decimal numbers (resulting in 3 numbers between 0 and 8191 inclusive each). Add 1000 to each calculated number. @@ -849,7 +883,7 @@ separator, such as dashes, or with the numbers on individual lines. ###### SAS method: `emoji` -Generate 6 bytes using [HKDF](#hkdf-calculation) then split the first 42 bits +Generate 6 bytes using [HKDF](#sas-hkdf-calculation) then split the first 42 bits into 7 groups of 6 bits, similar to how one would base64 encode something. Convert each group of 6 bits to a number and use the following table to get the corresponding emoji: diff --git a/data/event-schemas/examples/m.key.verification.accept.yaml b/data/event-schemas/examples/m.key.verification.accept.yaml index 98e89c06..2cda7994 100644 --- a/data/event-schemas/examples/m.key.verification.accept.yaml +++ b/data/event-schemas/examples/m.key.verification.accept.yaml @@ -5,7 +5,7 @@ "method": "m.sas.v1", "key_agreement_protocol": "curve25519", "hash": "sha256", - "message_authentication_code": "hkdf-hmac-sha256", + "message_authentication_code": "hkdf-hmac-sha256.v2", "short_authentication_string": ["decimal", "emoji"], "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" } diff --git a/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml index dae1d405..080606c8 100644 --- a/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml +++ b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml @@ -6,7 +6,7 @@ "method": "m.sas.v1", "key_agreement_protocols": ["curve25519"], "hashes": ["sha256"], - "message_authentication_codes": ["hkdf-hmac-sha256"], + "message_authentication_codes": ["hkdf-hmac-sha256.v2", "hkdf-hmac-sha256"], "short_authentication_string": ["decimal", "emoji"] } } diff --git a/data/event-schemas/schema/m.key.verification.accept.yaml b/data/event-schemas/schema/m.key.verification.accept.yaml index ae63995b..2a1bbf0d 100644 --- a/data/event-schemas/schema/m.key.verification.accept.yaml +++ b/data/event-schemas/schema/m.key.verification.accept.yaml @@ -26,7 +26,7 @@ properties: message_authentication_code: type: string description: |- - The message authentication code the device is choosing to use, out of + The message authentication code method the device is choosing to use, out of the options in the `m.key.verification.start` message. short_authentication_string: type: array diff --git a/data/event-schemas/schema/m.key.verification.mac.yaml b/data/event-schemas/schema/m.key.verification.mac.yaml index 9f7f5f4f..7f404fa0 100644 --- a/data/event-schemas/schema/m.key.verification.mac.yaml +++ b/data/event-schemas/schema/m.key.verification.mac.yaml @@ -3,7 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Sends the MAC of a device's key to the partner device. + Sends the MAC of a device's key to the partner device. The MAC is calculated + using the method given in `message_authentication_code` property of the + `m.key.verification.accept` message. properties: content: properties: diff --git a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml index 515a72a1..9bc7bcad 100644 --- a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml +++ b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml @@ -41,8 +41,11 @@ properties: message_authentication_codes: type: array description: |- - The message authentication codes that the sending device understands. - Must include at least `hkdf-hmac-sha256`. + The message authentication code methods that the sending device understands. + Must include at least `hkdf-hmac-sha256.v2`. Should also include + `hkdf-hmac-sha256` for compatibility with older clients, though this + identifier is deprecated and will be removed in a future version of + the spec. items: type: string short_authentication_string: From 6b02e393082570db2d0a651ddb79a365bc4a0f8d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 10 Feb 2023 12:04:24 +0000 Subject: [PATCH 06/32] Move `.m.rule.roomnotif` before `.m.rule.tombstone` (#1421) See https://github.com/matrix-org/matrix-spec/issues/1406 for the reasoning on this. TL;DR: the spec has always been wrong here. --- .../newsfragments/1421.clarification | 1 + content/client-server-api/modules/push.md | 64 +++++++++---------- 2 files changed, 33 insertions(+), 32 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1421.clarification diff --git a/changelogs/client_server/newsfragments/1421.clarification b/changelogs/client_server/newsfragments/1421.clarification new file mode 100644 index 00000000..07b86e2f --- /dev/null +++ b/changelogs/client_server/newsfragments/1421.clarification @@ -0,0 +1 @@ +Correct the order of the default override pushrules in the spec. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 74da879f..0a104bc1 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -524,6 +524,38 @@ Definition: } ``` +**`.m.rule.roomnotif`** + +Matches any message whose content is unencrypted and contains the text +`@room`, signifying the whole room should be notified of the event. + +Definition: + +```json +{ + "rule_id": ".m.rule.roomnotif", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "content.body", + "pattern": "@room" + }, + { + "kind": "sender_notification_permission", + "key": "room" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight" + } + ] +} +``` + **`.m.rule.tombstone`** Matches any state event whose type is `m.room.tombstone`. This is @@ -587,38 +619,6 @@ Definition: } ``` -**`.m.rule.roomnotif`** - -Matches any message whose content is unencrypted and contains the text -`@room`, signifying the whole room should be notified of the event. - -Definition: - -```json -{ - "rule_id": ".m.rule.roomnotif", - "default": true, - "enabled": true, - "conditions": [ - { - "kind": "event_match", - "key": "content.body", - "pattern": "@room" - }, - { - "kind": "sender_notification_permission", - "key": "room" - } - ], - "actions": [ - "notify", - { - "set_tweak": "highlight" - } - ] -} -``` - ###### Default Content Rules **`.m.rule.contains_user_name`** From b5566dbadb3872a23fe6ac9671b9b4b0761c08f5 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 13 Feb 2023 10:36:58 +0000 Subject: [PATCH 07/32] Clarify which events will be included in Stripped State (#1409) Signed-off-by: Andy Balaam andy.balaam@matrix.org --- .../newsfragments/1409.clarification | 1 + content/client-server-api/_index.md | 21 +++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1409.clarification diff --git a/changelogs/client_server/newsfragments/1409.clarification b/changelogs/client_server/newsfragments/1409.clarification new file mode 100644 index 00000000..40bea800 --- /dev/null +++ b/changelogs/client_server/newsfragments/1409.clarification @@ -0,0 +1 @@ +Clarify which events will be included in Stripped State. Contributed by @andybalaam. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 06318ae3..9385f3a1 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1579,15 +1579,18 @@ detail on why this assumption is unsafe. ### Stripped state -Stripped state events are simplified state events to help a potential -joiner identify the room. These state events can only have the `sender`, -`type`, `state_key` and `content` keys present. +Stripped state is a simplified view of the state of a room intended to help a +potential joiner identify the room. It consists of a limited set of state events +that are themselves simplified to reduce the amount of data required. -These stripped state events typically appear on invites, knocks, and in -other places where a user *could* join the room under the conditions -available (such as a [`restricted` room](#restricted-rooms)). +Stripped state events can only have the `sender`, `type`, `state_key` and +`content` properties present. -Clients should only use stripped state events so long as they don't have +Stripped state typically appears in invites, knocks, and in other places where a +user *could* join the room under the conditions available (such as a +[`restricted` room](#restricted-rooms)). + +Clients should only use stripped state events when they don't have access to the proper state of the room. Once the state of the room is available, all stripped state should be discarded. In cases where the client has an archived state of the room (such as after being kicked) @@ -1595,8 +1598,8 @@ and the client is receiving stripped state for the room, such as from an invite or knock, then the stripped state should take precedence until fresh state can be acquired from a join. -The following state events should be represented as stripped state when -possible: +Stripped state should contain some or all of the following state events, which +should be represented as stripped state events when possible: * [`m.room.create`](#mroomcreate) * [`m.room.name`](#mroomname) From a383698be506362ed35001e2533a375417943ee3 Mon Sep 17 00:00:00 2001 From: "DeepBlueV7.X" Date: Mon, 13 Feb 2023 21:36:52 +0100 Subject: [PATCH 08/32] Improve distinction between tags and their attributes in the rich text section (#1433) Originally the tags used to be bold, followed by a colon and separated into two columns in a table. This at least restores the table aspect, which makes it clear, that font is not an attribute (and similar). This seems to have gotten lost in the transition to the new design. Signed-off-by: Nicolas Werner --- .../newsfragments/1433.clarification | 1 + .../modules/instant_messaging.md | 29 +++++-------------- 2 files changed, 9 insertions(+), 21 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1433.clarification diff --git a/changelogs/client_server/newsfragments/1433.clarification b/changelogs/client_server/newsfragments/1433.clarification new file mode 100644 index 00000000..5bce3c4d --- /dev/null +++ b/changelogs/client_server/newsfragments/1433.clarification @@ -0,0 +1 @@ +Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 4932e410..c892d48e 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -48,27 +48,14 @@ are listed, clients should translate the value (a `#` character followed by a 6-character hex color code) to the appropriate CSS/attributes for the tag. -`font` -`data-mx-bg-color`, `data-mx-color`, `color` - -`span` -`data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see -[spoiler messages](#spoiler-messages)) - -`a` -`name`, `target`, `href` (provided the value is not relative and has a -scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) - -`img` -`width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix -Content (MXC) URI](#matrix-content-mxc-uris)) - -`ol` -`start` - -`code` -`class` (only classes which start with `language-` for syntax -highlighting) +| Tag | Permitted Attributes | +|--------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `font` | `data-mx-bg-color`, `data-mx-color`, `color` | +| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)) | +| `a` | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | +| `img` | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (MXC) URI](#matrix-content-mxc-uris)) | +| `ol` | `start` | +| `code` | `class` (only classes which start with `language-` for syntax highlighting) | Additionally, web clients should ensure that *all* `a` tags get a `rel="noopener"` to prevent the target page from referencing the From 97e353d26b16811bafa0c92096cf13402fb59fdc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Feb 2023 08:24:21 -0700 Subject: [PATCH 09/32] Tag Matrix 1.6 --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index aa7673e8..72652954 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. 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. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -#major = "1" -#minor = "5" -#release_date = "November 17, 2022" +major = "1" +minor = "6" +release_date = "February 14, 2023" # User interface configuration [params.ui] From 029e9888359c02f52e5a61a328af94108a4b638b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Feb 2023 08:26:03 -0700 Subject: [PATCH 10/32] Matrix 1.6 --- .../newsfragments/1347.feature | 1 - .../newsfragments/1169.clarification | 1 - .../newsfragments/1239.clarification | 1 - .../newsfragments/1321.clarification | 1 - .../client_server/newsfragments/1347.feature | 1 - .../newsfragments/1348.clarification | 1 - .../newsfragments/1353.clarification | 1 - .../newsfragments/1355.clarification | 1 - .../newsfragments/1363.clarification | 1 - .../client_server/newsfragments/1366.feature | 1 - .../newsfragments/1381.clarification | 1 - .../newsfragments/1382.clarification | 1 - .../newsfragments/1409.clarification | 1 - .../client_server/newsfragments/1412.feature | 1 - .../newsfragments/1417.clarification | 1 - .../newsfragments/1421.clarification | 1 - .../newsfragments/1433.clarification | 1 - .../newsfragments/1347.feature | 1 - .../internal/newsfragments/1357.clarification | 1 - .../internal/newsfragments/1368.clarification | 1 - .../internal/newsfragments/1370.clarification | 2 - .../internal/newsfragments/1384.clarification | 1 - .../internal/newsfragments/1415.clarification | 1 - .../push_gateway/newsfragments/1347.feature | 1 - .../room_versions/newsfragments/1397.feature | 1 - .../newsfragments/1422.clarification | 1 - .../newsfragments/1423.clarification | 1 - .../server_server/newsfragments/1347.feature | 1 - .../newsfragments/1349.clarification | 1 - .../server_server/newsfragments/1350.breaking | 1 - .../newsfragments/1351.clarification | 1 - .../server_server/newsfragments/1366.feature | 1 - .../newsfragments/1371.clarification | 1 - .../newsfragments/1376.clarification | 1 - .../newsfragments/1383.clarification | 1 - .../server_server/newsfragments/1393.feature | 1 - .../server_server/newsfragments/1398.feature | 1 - .../server_server/newsfragments/1425.feature | 1 - content/changelog/v1.6.md | 135 ++++++++++++++++++ 39 files changed, 135 insertions(+), 39 deletions(-) delete mode 100644 changelogs/application_service/newsfragments/1347.feature delete mode 100644 changelogs/client_server/newsfragments/1169.clarification delete mode 100644 changelogs/client_server/newsfragments/1239.clarification delete mode 100644 changelogs/client_server/newsfragments/1321.clarification delete mode 100644 changelogs/client_server/newsfragments/1347.feature delete mode 100644 changelogs/client_server/newsfragments/1348.clarification delete mode 100644 changelogs/client_server/newsfragments/1353.clarification delete mode 100644 changelogs/client_server/newsfragments/1355.clarification delete mode 100644 changelogs/client_server/newsfragments/1363.clarification delete mode 100644 changelogs/client_server/newsfragments/1366.feature delete mode 100644 changelogs/client_server/newsfragments/1381.clarification delete mode 100644 changelogs/client_server/newsfragments/1382.clarification delete mode 100644 changelogs/client_server/newsfragments/1409.clarification delete mode 100644 changelogs/client_server/newsfragments/1412.feature delete mode 100644 changelogs/client_server/newsfragments/1417.clarification delete mode 100644 changelogs/client_server/newsfragments/1421.clarification delete mode 100644 changelogs/client_server/newsfragments/1433.clarification delete mode 100644 changelogs/identity_service/newsfragments/1347.feature delete mode 100644 changelogs/internal/newsfragments/1357.clarification delete mode 100644 changelogs/internal/newsfragments/1368.clarification delete mode 100644 changelogs/internal/newsfragments/1370.clarification delete mode 100644 changelogs/internal/newsfragments/1384.clarification delete mode 100644 changelogs/internal/newsfragments/1415.clarification delete mode 100644 changelogs/push_gateway/newsfragments/1347.feature delete mode 100644 changelogs/room_versions/newsfragments/1397.feature delete mode 100644 changelogs/room_versions/newsfragments/1422.clarification delete mode 100644 changelogs/room_versions/newsfragments/1423.clarification delete mode 100644 changelogs/server_server/newsfragments/1347.feature delete mode 100644 changelogs/server_server/newsfragments/1349.clarification delete mode 100644 changelogs/server_server/newsfragments/1350.breaking delete mode 100644 changelogs/server_server/newsfragments/1351.clarification delete mode 100644 changelogs/server_server/newsfragments/1366.feature delete mode 100644 changelogs/server_server/newsfragments/1371.clarification delete mode 100644 changelogs/server_server/newsfragments/1376.clarification delete mode 100644 changelogs/server_server/newsfragments/1383.clarification delete mode 100644 changelogs/server_server/newsfragments/1393.feature delete mode 100644 changelogs/server_server/newsfragments/1398.feature delete mode 100644 changelogs/server_server/newsfragments/1425.feature create mode 100644 content/changelog/v1.6.md diff --git a/changelogs/application_service/newsfragments/1347.feature b/changelogs/application_service/newsfragments/1347.feature deleted file mode 100644 index f5aa481f..00000000 --- a/changelogs/application_service/newsfragments/1347.feature +++ /dev/null @@ -1 +0,0 @@ -Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/client_server/newsfragments/1169.clarification b/changelogs/client_server/newsfragments/1169.clarification deleted file mode 100644 index 6d550dbc..00000000 --- a/changelogs/client_server/newsfragments/1169.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the power levels integer range. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1239.clarification b/changelogs/client_server/newsfragments/1239.clarification deleted file mode 100644 index f2c403d1..00000000 --- a/changelogs/client_server/newsfragments/1239.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `/context` always returns `event` even if `limit` is zero. Contributed by @sumnerevans at @beeper. diff --git a/changelogs/client_server/newsfragments/1321.clarification b/changelogs/client_server/newsfragments/1321.clarification deleted file mode 100644 index ad53c046..00000000 --- a/changelogs/client_server/newsfragments/1321.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify what fields are required when deleting a pusher \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1347.feature b/changelogs/client_server/newsfragments/1347.feature deleted file mode 100644 index f5aa481f..00000000 --- a/changelogs/client_server/newsfragments/1347.feature +++ /dev/null @@ -1 +0,0 @@ -Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/client_server/newsfragments/1348.clarification b/changelogs/client_server/newsfragments/1348.clarification deleted file mode 100644 index 000ef5f7..00000000 --- a/changelogs/client_server/newsfragments/1348.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve the presentation of push rule kinds and actions. diff --git a/changelogs/client_server/newsfragments/1353.clarification b/changelogs/client_server/newsfragments/1353.clarification deleted file mode 100644 index fa9316da..00000000 --- a/changelogs/client_server/newsfragments/1353.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing description to m.call.answer schema. diff --git a/changelogs/client_server/newsfragments/1355.clarification b/changelogs/client_server/newsfragments/1355.clarification deleted file mode 100644 index 6d550dbc..00000000 --- a/changelogs/client_server/newsfragments/1355.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the power levels integer range. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1363.clarification b/changelogs/client_server/newsfragments/1363.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1363.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1366.feature b/changelogs/client_server/newsfragments/1366.feature deleted file mode 100644 index 42d035f5..00000000 --- a/changelogs/client_server/newsfragments/1366.feature +++ /dev/null @@ -1 +0,0 @@ -Add `/rooms//timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/changelogs/client_server/newsfragments/1381.clarification b/changelogs/client_server/newsfragments/1381.clarification deleted file mode 100644 index 8132e060..00000000 --- a/changelogs/client_server/newsfragments/1381.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify parts of the end-to-end encryption sections. diff --git a/changelogs/client_server/newsfragments/1382.clarification b/changelogs/client_server/newsfragments/1382.clarification deleted file mode 100644 index 6f08f207..00000000 --- a/changelogs/client_server/newsfragments/1382.clarification +++ /dev/null @@ -1 +0,0 @@ -Move login API definitions to the right heading. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1409.clarification b/changelogs/client_server/newsfragments/1409.clarification deleted file mode 100644 index 40bea800..00000000 --- a/changelogs/client_server/newsfragments/1409.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which events will be included in Stripped State. Contributed by @andybalaam. diff --git a/changelogs/client_server/newsfragments/1412.feature b/changelogs/client_server/newsfragments/1412.feature deleted file mode 100644 index 5f89e057..00000000 --- a/changelogs/client_server/newsfragments/1412.feature +++ /dev/null @@ -1 +0,0 @@ -Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). diff --git a/changelogs/client_server/newsfragments/1417.clarification b/changelogs/client_server/newsfragments/1417.clarification deleted file mode 100644 index b1b0b8c9..00000000 --- a/changelogs/client_server/newsfragments/1417.clarification +++ /dev/null @@ -1 +0,0 @@ -Add links to the spec for the definition of 3PID `medium`. diff --git a/changelogs/client_server/newsfragments/1421.clarification b/changelogs/client_server/newsfragments/1421.clarification deleted file mode 100644 index 07b86e2f..00000000 --- a/changelogs/client_server/newsfragments/1421.clarification +++ /dev/null @@ -1 +0,0 @@ -Correct the order of the default override pushrules in the spec. diff --git a/changelogs/client_server/newsfragments/1433.clarification b/changelogs/client_server/newsfragments/1433.clarification deleted file mode 100644 index 5bce3c4d..00000000 --- a/changelogs/client_server/newsfragments/1433.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. diff --git a/changelogs/identity_service/newsfragments/1347.feature b/changelogs/identity_service/newsfragments/1347.feature deleted file mode 100644 index f5aa481f..00000000 --- a/changelogs/identity_service/newsfragments/1347.feature +++ /dev/null @@ -1 +0,0 @@ -Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/internal/newsfragments/1357.clarification b/changelogs/internal/newsfragments/1357.clarification deleted file mode 100644 index 282ef8ca..00000000 --- a/changelogs/internal/newsfragments/1357.clarification +++ /dev/null @@ -1 +0,0 @@ -Add link to the unstable spec to the README. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1368.clarification b/changelogs/internal/newsfragments/1368.clarification deleted file mode 100644 index a08f1ebe..00000000 --- a/changelogs/internal/newsfragments/1368.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve safety of the proposals retrieval script in the event of failure. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1370.clarification b/changelogs/internal/newsfragments/1370.clarification deleted file mode 100644 index 84780634..00000000 --- a/changelogs/internal/newsfragments/1370.clarification +++ /dev/null @@ -1,2 +0,0 @@ -Rename `` to `content` in the OpenAPI files for content uploads. - diff --git a/changelogs/internal/newsfragments/1384.clarification b/changelogs/internal/newsfragments/1384.clarification deleted file mode 100644 index 46c5f9f0..00000000 --- a/changelogs/internal/newsfragments/1384.clarification +++ /dev/null @@ -1 +0,0 @@ -Stop autogenerating examples where we already have an example. diff --git a/changelogs/internal/newsfragments/1415.clarification b/changelogs/internal/newsfragments/1415.clarification deleted file mode 100644 index 390f37e3..00000000 --- a/changelogs/internal/newsfragments/1415.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve formatting of definitions in the Push Notifications section. diff --git a/changelogs/push_gateway/newsfragments/1347.feature b/changelogs/push_gateway/newsfragments/1347.feature deleted file mode 100644 index f5aa481f..00000000 --- a/changelogs/push_gateway/newsfragments/1347.feature +++ /dev/null @@ -1 +0,0 @@ -Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/room_versions/newsfragments/1397.feature b/changelogs/room_versions/newsfragments/1397.feature deleted file mode 100644 index 4ffe3415..00000000 --- a/changelogs/room_versions/newsfragments/1397.feature +++ /dev/null @@ -1 +0,0 @@ -Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904). \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1422.clarification b/changelogs/room_versions/newsfragments/1422.clarification deleted file mode 100644 index efb63c69..00000000 --- a/changelogs/room_versions/newsfragments/1422.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the grammar for room versions. diff --git a/changelogs/room_versions/newsfragments/1423.clarification b/changelogs/room_versions/newsfragments/1423.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/room_versions/newsfragments/1423.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/server_server/newsfragments/1347.feature b/changelogs/server_server/newsfragments/1347.feature deleted file mode 100644 index f5aa481f..00000000 --- a/changelogs/server_server/newsfragments/1347.feature +++ /dev/null @@ -1 +0,0 @@ -Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). diff --git a/changelogs/server_server/newsfragments/1349.clarification b/changelogs/server_server/newsfragments/1349.clarification deleted file mode 100644 index 52a9c92d..00000000 --- a/changelogs/server_server/newsfragments/1349.clarification +++ /dev/null @@ -1 +0,0 @@ -Include examples inline instead of using a reference for invite endpoint definitions. diff --git a/changelogs/server_server/newsfragments/1350.breaking b/changelogs/server_server/newsfragments/1350.breaking deleted file mode 100644 index 81ce2585..00000000 --- a/changelogs/server_server/newsfragments/1350.breaking +++ /dev/null @@ -1 +0,0 @@ -Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938). diff --git a/changelogs/server_server/newsfragments/1351.clarification b/changelogs/server_server/newsfragments/1351.clarification deleted file mode 100644 index 935332ad..00000000 --- a/changelogs/server_server/newsfragments/1351.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix `POST _matrix/federation/v1/user/keys/claim` response schema. diff --git a/changelogs/server_server/newsfragments/1366.feature b/changelogs/server_server/newsfragments/1366.feature deleted file mode 100644 index 22834501..00000000 --- a/changelogs/server_server/newsfragments/1366.feature +++ /dev/null @@ -1 +0,0 @@ -Add `/timestamp_to_event/` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/changelogs/server_server/newsfragments/1371.clarification b/changelogs/server_server/newsfragments/1371.clarification deleted file mode 100644 index e43199b8..00000000 --- a/changelogs/server_server/newsfragments/1371.clarification +++ /dev/null @@ -1 +0,0 @@ -Correct the default invite level definition in the "Checks performed on receipt of a PDU" section. diff --git a/changelogs/server_server/newsfragments/1376.clarification b/changelogs/server_server/newsfragments/1376.clarification deleted file mode 100644 index 470783c4..00000000 --- a/changelogs/server_server/newsfragments/1376.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that CNAMEs are permissible for server names. diff --git a/changelogs/server_server/newsfragments/1383.clarification b/changelogs/server_server/newsfragments/1383.clarification deleted file mode 100644 index f6713b87..00000000 --- a/changelogs/server_server/newsfragments/1383.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix `edu_type` in EDU examples. diff --git a/changelogs/server_server/newsfragments/1393.feature b/changelogs/server_server/newsfragments/1393.feature deleted file mode 100644 index e5ca05a5..00000000 --- a/changelogs/server_server/newsfragments/1393.feature +++ /dev/null @@ -1 +0,0 @@ -Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1398.feature b/changelogs/server_server/newsfragments/1398.feature deleted file mode 100644 index e5ca05a5..00000000 --- a/changelogs/server_server/newsfragments/1398.feature +++ /dev/null @@ -1 +0,0 @@ -Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1425.feature b/changelogs/server_server/newsfragments/1425.feature deleted file mode 100644 index 1add27ff..00000000 --- a/changelogs/server_server/newsfragments/1425.feature +++ /dev/null @@ -1 +0,0 @@ -Note that `/_matrix/federation/v2/send_join` should include heroes for nameless rooms, even when allowed to omit membership events, per [MSC3943](https://github.com/matrix-org/matrix-doc/pull/3943). diff --git a/content/changelog/v1.6.md b/content/changelog/v1.6.md new file mode 100644 index 00000000..acef1f7c --- /dev/null +++ b/content/changelog/v1.6.md @@ -0,0 +1,135 @@ +--- +date: 2023-02-14T08:25:40-07:00 +--- + + +## v1.6 + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.6
Release dateFebruary 14, 2023
+ + +### Client-Server API + + +Backwards Compatible Changes + + +- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) +- Add `/rooms//timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). ([#1366](https://github.com/matrix-org/matrix-spec/issues/1366)) +- Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). ([#1412](https://github.com/matrix-org/matrix-spec/issues/1412)) + + +Spec Clarifications + + +- Clarify the power levels integer range. ([#1169](https://github.com/matrix-org/matrix-spec/issues/1169), [#1355](https://github.com/matrix-org/matrix-spec/issues/1355)) +- Clarify that `/context` always returns `event` even if `limit` is zero. Contributed by @sumnerevans at @beeper. ([#1239](https://github.com/matrix-org/matrix-spec/issues/1239)) +- Clarify what fields are required when deleting a pusher ([#1321](https://github.com/matrix-org/matrix-spec/issues/1321)) +- Improve the presentation of push rule kinds and actions. ([#1348](https://github.com/matrix-org/matrix-spec/issues/1348)) +- Add missing description to m.call.answer schema. ([#1353](https://github.com/matrix-org/matrix-spec/issues/1353)) +- Fix various typos throughout the specification. ([#1363](https://github.com/matrix-org/matrix-spec/issues/1363)) +- Clarify parts of the end-to-end encryption sections. ([#1381](https://github.com/matrix-org/matrix-spec/issues/1381)) +- Move login API definitions to the right heading. Contributed by @HarHarLinks. ([#1382](https://github.com/matrix-org/matrix-spec/issues/1382)) +- Clarify which events will be included in Stripped State. Contributed by @andybalaam. ([#1409](https://github.com/matrix-org/matrix-spec/issues/1409)) +- Add links to the spec for the definition of 3PID `medium`. ([#1417](https://github.com/matrix-org/matrix-spec/issues/1417)) +- Correct the order of the default override pushrules in the spec. ([#1421](https://github.com/matrix-org/matrix-spec/issues/1421)) +- Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433)) + + +### Server-Server API + + +Breaking Changes + + +- Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938). ([#1350](https://github.com/matrix-org/matrix-spec/issues/1350)) + + +Backwards Compatible Changes + + +- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) +- Add `/timestamp_to_event/` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). ([#1366](https://github.com/matrix-org/matrix-spec/issues/1366)) +- Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). ([#1393](https://github.com/matrix-org/matrix-spec/issues/1393), [#1398](https://github.com/matrix-org/matrix-spec/issues/1398)) +- Note that `/_matrix/federation/v2/send_join` should include heroes for nameless rooms, even when allowed to omit membership events, per [MSC3943](https://github.com/matrix-org/matrix-doc/pull/3943). ([#1425](https://github.com/matrix-org/matrix-spec/issues/1425)) + + +Spec Clarifications + + +- Include examples inline instead of using a reference for invite endpoint definitions. ([#1349](https://github.com/matrix-org/matrix-spec/issues/1349)) +- Fix `POST _matrix/federation/v1/user/keys/claim` response schema. ([#1351](https://github.com/matrix-org/matrix-spec/issues/1351)) +- Correct the default invite level definition in the "Checks performed on receipt of a PDU" section. ([#1371](https://github.com/matrix-org/matrix-spec/issues/1371)) +- Clarify that CNAMEs are permissible for server names. ([#1376](https://github.com/matrix-org/matrix-spec/issues/1376)) +- Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383)) + + +### Application Service API + + +Backwards Compatible Changes + + +- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) + + +### Identity Service API + + +Backwards Compatible Changes + + +- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) + + +### Push Gateway API + + +Backwards Compatible Changes + + +- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) + + +### Room Versions + + +Backwards Compatible Changes + + +- Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904). ([#1397](https://github.com/matrix-org/matrix-spec/issues/1397)) + + +Spec Clarifications + + +- Clarify the grammar for room versions. ([#1422](https://github.com/matrix-org/matrix-spec/issues/1422)) +- Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423)) + + +### Appendices + + +No significant changes. + + +### Internal Changes/Tooling + + +Spec Clarifications + + +- Add link to the unstable spec to the README. ([#1357](https://github.com/matrix-org/matrix-spec/issues/1357)) +- Improve safety of the proposals retrieval script in the event of failure. ([#1368](https://github.com/matrix-org/matrix-spec/issues/1368)) +- Rename `` to `content` in the OpenAPI files for content uploads. ([#1370](https://github.com/matrix-org/matrix-spec/issues/1370)) +- Stop autogenerating examples where we already have an example. ([#1384](https://github.com/matrix-org/matrix-spec/issues/1384)) +- Improve formatting of definitions in the Push Notifications section. ([#1415](https://github.com/matrix-org/matrix-spec/issues/1415)) From 49b74140804c001a2f719054d044d926a70d3263 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Feb 2023 08:27:47 -0700 Subject: [PATCH 11/32] Return to unstable --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index 72652954..d1749268 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://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. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -major = "1" -minor = "6" -release_date = "February 14, 2023" +# major = "1" +# minor = "6" +# release_date = "February 14, 2023" # User interface configuration [params.ui] From 377e301c6116a85794d3bd6c04192fb3b956265d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Feb 2023 08:45:17 -0700 Subject: [PATCH 12/32] Fix MSC naming reference --- content/changelog/v1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/changelog/v1.6.md b/content/changelog/v1.6.md index acef1f7c..07574ff3 100644 --- a/content/changelog/v1.6.md +++ b/content/changelog/v1.6.md @@ -25,7 +25,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) - Add `/rooms//timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). ([#1366](https://github.com/matrix-org/matrix-spec/issues/1366)) -- Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). ([#1412](https://github.com/matrix-org/matrix-spec/issues/1412)) +- Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). ([#1412](https://github.com/matrix-org/matrix-spec/issues/1412)) Spec Clarifications From 5c7bb2fcd55fbc888593c1b6a2cf8156694b1ffc Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 14 Feb 2023 17:08:47 +0000 Subject: [PATCH 13/32] Remove some erroneous underscores from the Client-Server spec text (#1432) Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/client_server/newsfragments/1432.clarification | 1 + content/client-server-api/_index.md | 8 ++++---- 2 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1432.clarification diff --git a/changelogs/client_server/newsfragments/1432.clarification b/changelogs/client_server/newsfragments/1432.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/1432.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9385f3a1..4787d222 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -739,7 +739,7 @@ submit: ``` Alternatively reply using a 3PID bound to the user's account on the -homeserver using the `/account/3pid`\_ API rather than giving the `user` +homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API rather than giving the `user` explicitly as follows: ```json @@ -1047,7 +1047,7 @@ ID. A client can identify a user using a 3PID associated with the user's account on the homeserver, where the 3PID was previously associated -using the `/account/3pid`\_ API. See the [3PID +using the [`/account/3pid`](#get_matrixclientv3account3pid) API. See the [3PID Types](/appendices#3pid-types) Appendix for a list of Third-party ID media. @@ -1067,7 +1067,7 @@ ID media. A client can identify a user using a phone number associated with the user's account, where the phone number was previously associated using -the `/account/3pid`\_ API. The phone number can be passed in as entered +the [`/account/3pid`](#get_matrixclientv3account3pid) API. The phone number can be passed in as entered by the user; the homeserver will be responsible for canonicalising it. If the client wishes to canonicalise the phone number, then it can use the `m.id.thirdparty` identifier type with a `medium` of `msisdn` @@ -1108,7 +1108,7 @@ request as follows: ``` Alternatively, a client can use a 3PID bound to the user's account on -the homeserver using the `/account/3pid`\_ API rather than giving the +the homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API rather than giving the `user` explicitly, as follows: ```json From ea4719793041dfccdef9071edb5ad8526536619b Mon Sep 17 00:00:00 2001 From: Saiprakash Shet Date: Thu, 16 Feb 2023 02:39:29 +0530 Subject: [PATCH 14/32] Update spelling in s2s authorization (#1431) * Issue #1231/Update spelling in s2s authorization * Update spelling in s2s authorization. * Apply suggestions from code review --------- Co-authored-by: Travis Ralston --- changelogs/server_server/newsfragments/1431.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1431.clarification diff --git a/changelogs/server_server/newsfragments/1431.clarification b/changelogs/server_server/newsfragments/1431.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1431.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index 34f9f5b5..bcf0db4e 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -350,7 +350,7 @@ 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 + server. 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 From 71b223586803fba02e9b317eaf2ad778b3bd1878 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Tue, 21 Feb 2023 18:38:48 +0100 Subject: [PATCH 15/32] Clarify that reply chain fallback for threads may not be present (#1439) --- changelogs/client_server/newsfragments/1439.clarification | 1 + content/client-server-api/modules/threading.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1439.clarification diff --git a/changelogs/client_server/newsfragments/1439.clarification b/changelogs/client_server/newsfragments/1439.clarification new file mode 100644 index 00000000..ed05216d --- /dev/null +++ b/changelogs/client_server/newsfragments/1439.clarification @@ -0,0 +1 @@ +Clarify that reply chain fallback for threads may not be present. diff --git a/content/client-server-api/modules/threading.md b/content/client-server-api/modules/threading.md index 2a7f02d0..240ae33d 100644 --- a/content/client-server-api/modules/threading.md +++ b/content/client-server-api/modules/threading.md @@ -74,7 +74,7 @@ Clients which understand how to work with threads should simply do so, however c might not be aware of threads (due to age or scope) might not be able to helpfully represent the conversation history to its users. -To work around this, events sent by clients which understand threads include [rich reply](#rich-replies) +To work around this, events sent by clients which understand threads SHOULD include [rich reply](#rich-replies) metadata to attempt to form a reply chain representation of the conversation. This representation is not ideal for heavily threaded rooms, but allows for users to have context as to what is being discussed with respect to other messages in the room. From 77d0f20226cb37125879771cb2528def77b5cf12 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 22 Feb 2023 11:35:36 +0000 Subject: [PATCH 16/32] Remove spurious 'weight: 340' (#1442) --- changelogs/client_server/newsfragments/1442.clarification | 1 + content/client-server-api/modules/spaces.md | 2 -- 2 files changed, 1 insertion(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1442.clarification diff --git a/changelogs/client_server/newsfragments/1442.clarification b/changelogs/client_server/newsfragments/1442.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1442.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/modules/spaces.md b/content/client-server-api/modules/spaces.md index cf192a69..11734ac3 100644 --- a/content/client-server-api/modules/spaces.md +++ b/content/client-server-api/modules/spaces.md @@ -1,5 +1,3 @@ -weight: 340 - ### Spaces {{% added-in v="1.2" %}} From 427f472331e73e98624ad26b42f6ef0922d09cad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 28 Feb 2023 14:19:27 +0100 Subject: [PATCH 17/32] Remove overridden references to `examples/minimal_pdu.json` and add the missing `room_id` field. (#1454) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The syntax is incorrect and would require to use allOf because a $ref can't have siblings. However the only field not overwritten of that definition is room_id, so we include it instead of the $ref Signed-off-by: Kévin Commaille --- changelogs/server_server/newsfragments/1454.clarification | 1 + data/api/server-server/invites-v1.yaml | 4 ++-- data/api/server-server/invites-v2.yaml | 4 ++-- data/api/server-server/joins-v1.yaml | 4 ++-- data/api/server-server/joins-v2.yaml | 2 +- data/api/server-server/knocks.yaml | 4 ++-- data/api/server-server/leaving-v1.yaml | 4 ++-- data/api/server-server/leaving-v2.yaml | 2 +- 8 files changed, 13 insertions(+), 12 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1454.clarification diff --git a/changelogs/server_server/newsfragments/1454.clarification b/changelogs/server_server/newsfragments/1454.clarification new file mode 100644 index 00000000..6d68b88a --- /dev/null +++ b/changelogs/server_server/newsfragments/1454.clarification @@ -0,0 +1 @@ +Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`. diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index ed880c5a..ee439aa2 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -85,7 +85,7 @@ paths: example: $ref: "../../event-schemas/examples/invite_room_state.json" example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@joe:elsewhere.com", "origin": "example.org", @@ -126,7 +126,7 @@ paths: 200, { "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 0785aadd..afb8a571 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -89,7 +89,7 @@ paths: example: { "room_version": "2", "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@joe:elsewhere.com", "origin": "example.org", @@ -122,7 +122,7 @@ paths: examples: application/json: { "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index 1b850266..edb987f2 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -139,7 +139,7 @@ paths: application/json: { "room_version": "2", "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", @@ -310,7 +310,7 @@ paths: - type - content example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 129e5d2e..3a8a47b1 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -147,7 +147,7 @@ paths: - type - content example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index aa388bda..de17f44d 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -129,7 +129,7 @@ paths: application/json: { "room_version": "7", "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", @@ -264,7 +264,7 @@ paths: - type - content example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index df314d5a..40c8a062 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -118,7 +118,7 @@ paths: application/json: { "room_version": "2", "event": { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", @@ -221,7 +221,7 @@ paths: - depth - content example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index e3b8f089..dd96eaaa 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -117,7 +117,7 @@ paths: - depth - content example: { - "$ref": "examples/minimal_pdu.json", + "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", From a9e9202e898c347cc149dbc5dafb81893e68153d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 28 Feb 2023 14:56:19 +0000 Subject: [PATCH 18/32] Load Inter CSS directly (#1444) Move the load of the Inter font CSS from _variables_project.scss to head-end.html. Empirically, this seems to fix #965 --- assets/scss/_variables_project.scss | 12 ++++++------ changelogs/internal/newsfragments/1444.clarification | 1 + layouts/partials/hooks/head-end.html | 10 ++++++++++ 3 files changed, 17 insertions(+), 6 deletions(-) create mode 100644 changelogs/internal/newsfragments/1444.clarification diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 9b4a0b15..8ff5fe98 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -41,12 +41,12 @@ $table-row-default: $secondary-lighter-background; $td-enable-google-fonts: false; /* - * Replace the default font with Inter - we load it from a local copy, which is downloaded from - * Google Fonts manually via a script: - * https://github.com/matrix-org/matrix-spec/tree/main/static/css/fonts + * Replace the default font with Inter. * * The $font-family-sans-serif definition here overrides the default value set by docsy: * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68 - * and adds "Inter" to the front. */ -@import url("../css/fonts/Inter.css"); -$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; \ No newline at end of file + * and adds "Inter" to the front. + * + * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html. + */ +$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; diff --git a/changelogs/internal/newsfragments/1444.clarification b/changelogs/internal/newsfragments/1444.clarification new file mode 100644 index 00000000..1bbaa905 --- /dev/null +++ b/changelogs/internal/newsfragments/1444.clarification @@ -0,0 +1 @@ +Update references to Inter font. diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html index 925c43cc..7bceff45 100644 --- a/layouts/partials/hooks/head-end.html +++ b/layouts/partials/hooks/head-end.html @@ -6,6 +6,16 @@ */}} +{{/* + Load the Inter font. + + We load it from a local copy, which is downloaded from + Google Fonts manually via a script: + https://github.com/matrix-org/matrix-spec/tree/main/static/css/fonts +*/}} + + + {{ $scss := "scss/custom.scss"}} {{ if .Site.IsServer }} {{/* Note the missing postCSS. This makes it snappier to develop in Chrome, but makes it look sub-optimal in other browsers. */}} From a45138c3b4a722ef4f4eb98788dc25c94a3dce61 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:04:57 +0000 Subject: [PATCH 19/32] Minor updates to documentation style (#1456) i.e. has full-stops --- meta/documentation_style.rst | 46 ++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 3a17cbd6..468b2675 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -44,33 +44,39 @@ Stylistic notes General ~~~~~~~ -Try to write clearly and unambiguously. Remember that many readers will not -have English as their first language. +* Try to write clearly and unambiguously. Remember that many readers will not + have English as their first language. -Prefer British English (colour, -ise) to American English. +* Prefer British English (colour, -ise) to American English. -The word "homeserver" is spelt thus (rather than "home server", "Homeserver", -or (argh) "Home Server"). However, an identity server is two words. +* The word "homeserver" is spelt thus (rather than "home server", "Homeserver", + or (argh) "Home Server"). However, an identity server is two words. -An "identity server" (spelt thus) implements the Identity Service API (also spelt -thus). However, "Application Services" (spelt thus) implement the Application Service -API. Application Services should not be called "appservices" in documentation. +* An "identity server" (spelt thus) implements the Identity Service API (also spelt + thus). However, "Application Services" (spelt thus) implement the Application Service + API. Application Services should not be called "appservices" in documentation. -.. Rationale: "homeserver" distinguishes from a "home server" which is a server - you have at home. "identity server" is clear, whereas "identityserver" is - horrible. + .. Rationale: "homeserver" distinguishes from a "home server" which is a server + you have at home. "identity server" is clear, whereas "identityserver" is + horrible. -Lists should: +* Lists should: -* Be introduced with a colon. -* Be used where they provide clarity. -* Contain entries which start with a capital and end with a full stop. + * Be introduced with a colon. + * Be used where they provide clarity. + * Contain entries which start with a capital and end with a full stop. -When talking about properties in JSON objects, prefer the word "property" to "field", -"member", or various other alternatives. For example: "this property will be set to -X if ...". Also avoid the term "key" unless you are specifically talking about the -*name* of a property - and be mindful of the scope for confusion with cryptographic -keys. +* When talking about properties in JSON objects, prefer the word "property" to "field", + "member", or various other alternatives. For example: "this property will be set to + X if ...". Also avoid the term "key" unless you are specifically talking about the + *name* of a property - and be mindful of the scope for confusion with cryptographic + keys. + +* "i.e." (*id est*) is an abbreviation and hence is written with two full + stops. Prefer full sentences where possible without loss of clarity. + +* Prefer "for example" over "e.g.". If you *must* use "e.g.", remember it too + is an abbreviation (*exempli gratia*). Changes between spec versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From f9ea0f9d9b51271ff33afc6b8f71a2b78d8abcdb Mon Sep 17 00:00:00 2001 From: David Robertson Date: Thu, 2 Mar 2023 16:58:04 +0000 Subject: [PATCH 20/32] Only include endpoint path in `` (#1446) --- assets/scss/custom.scss | 14 +++++++++----- .../internal/newsfragments/1446.clarification | 1 + layouts/partials/openapi/render-operation.html | 2 +- 3 files changed, 11 insertions(+), 6 deletions(-) create mode 100644 changelogs/internal/newsfragments/1446.clarification diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 1534d5bd..9d748bd2 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -288,16 +288,20 @@ footer { /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */ .rendered-data { background-color: $secondary-lightest-background; - padding: 1rem; - margin: 1rem 0; + padding: 0.85rem; + margin: 0.85rem 0; details { summary { - padding: .5rem 0; - p { - max-width: 80%; + h1 { + margin: 0; + /* Ensure the disclosure control is vertically centred with the header text. */ + vertical-align: middle; } } + p { + max-width: 80%; + } } .deprecated-inline { diff --git a/changelogs/internal/newsfragments/1446.clarification b/changelogs/internal/newsfragments/1446.clarification new file mode 100644 index 00000000..fdc3d1fc --- /dev/null +++ b/changelogs/internal/newsfragments/1446.clarification @@ -0,0 +1 @@ +Endpoint disclosures now hide everything but the URL. diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 74b729cf..1e480671 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -33,6 +33,7 @@ {{ $method }} {{ $endpoint }} +
@@ -49,7 +50,6 @@

{{ $operation_data.description | markdownify }}

- From 10844fef8c04498b2464c11e6aff27748332f046 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 7 Mar 2023 16:45:14 +0000 Subject: [PATCH 21/32] Clarification to transaction identifier idempotent semantics (#1449) --- .../newsfragments/1449.clarification | 1 + content/client-server-api/_index.md | 41 +++++++++++++------ 2 files changed, 30 insertions(+), 12 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1449.clarification diff --git a/changelogs/client_server/newsfragments/1449.clarification b/changelogs/client_server/newsfragments/1449.clarification new file mode 100644 index 00000000..1c105229 --- /dev/null +++ b/changelogs/client_server/newsfragments/1449.clarification @@ -0,0 +1 @@ +Clarify the semantics that make requests idempotent. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4787d222..d2759a46 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -214,19 +214,36 @@ See the [Server Notices](#server-notices) module for more information. ### Transaction identifiers The client-server API typically uses `HTTP PUT` to submit requests with -a client-generated transaction identifier. This means that these -requests are idempotent. It **only** serves to identify new requests -from retransmits. After the request has finished, the `{txnId}` value -should be changed (how is not specified; a monotonically increasing -integer is recommended). +a client-generated transaction identifier in the HTTP path. -The scope of a transaction ID is a "client session", where that session -is identified by a particular access token. When [refreshing](#refreshing-access-tokens) -an access token, the transaction ID's scope is retained. This means that -if a client with token `A` uses `TXN1` as their transaction ID, refreshes -the token to `B`, and uses `TXN1` again it'll be assumed to be a duplicate -request and ignored. If the client logs out and back in between the `A` and -`B` tokens, `TXN1` could be used once for each. +The purpose of the transaction ID is to allow the homeserver to distinguish a +new request from a retransmission of a previous request so that it can make +the request idempotent. + +The transaction ID should **only** be used for this purpose. + +From the client perspective, after the request has finished, the `{txnId}` +value should be changed by for the next request (how is not specified; a +monotonically increasing integer is recommended). + +The homeserver should identify a request as a retransmission if the +transaction ID is the same as a previous request, and the path of the +HTTP request is the same. + +Where a retransmission has been identified, the homeserver should return +the same HTTP response code and content as the original request. +For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}` +would return a `200 OK` with the `event_id` of the original request in +the response body. + +As well as the HTTP path, the scope of a transaction ID is a "client +session", where that session is identified by a particular access token. +When [refreshing](#refreshing-access-tokens) an access token, the +transaction ID's scope is retained. This means that if a client with +token `A` uses `TXN1` as their transaction ID, refreshes the token to +`B`, and uses `TXN1` again it'll be assumed to be a duplicate request +and ignored. If the client logs out and back in between the `A` and `B` +tokens, `TXN1` could be used once for each. Some API endpoints may allow or require the use of `POST` requests without a transaction ID. Where this is optional, the use of a `PUT` From 9ebcf5f2578992fe881d70b9eb259eb179c8718d Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 7 Mar 2023 17:51:30 +0100 Subject: [PATCH 22/32] OpenAPI compliance: avoid $ref siblings (#1457) This strives to fix all remaining cases where additional attributes (most often 'description' but not only) are provided next to $ref by wrapping $ref in allOf; and also drops allOf in a couple of places where $ref is the only element under it. --- .../newsfragments/1457.clarification | 1 + .../newsfragments/1457.clarification | 1 + .../newsfragments/1457.clarification | 1 + .../definitions/errors/rate_limited.yaml | 41 ++++++++++--------- .../definitions/event_batch.yaml | 4 +- .../client-server/definitions/push_rule.yaml | 3 +- data/api/client-server/notifications.yaml | 4 +- data/api/client-server/old_sync.yaml | 3 +- data/api/client-server/search.yaml | 4 +- data/api/identity/v2_associations.yaml | 3 +- data/api/identity/v2_invitation_signing.yaml | 3 +- .../event-schemas/m.device_list_update.yaml | 3 +- .../event-schemas/m.signing_key_update.yaml | 8 ++-- data/api/server-server/user_devices.yaml | 3 +- 14 files changed, 44 insertions(+), 38 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1457.clarification create mode 100644 changelogs/identity_service/newsfragments/1457.clarification create mode 100644 changelogs/server_server/newsfragments/1457.clarification diff --git a/changelogs/client_server/newsfragments/1457.clarification b/changelogs/client_server/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/client_server/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/identity_service/newsfragments/1457.clarification b/changelogs/identity_service/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/identity_service/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/server_server/newsfragments/1457.clarification b/changelogs/server_server/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/server_server/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/data/api/client-server/definitions/errors/rate_limited.yaml b/data/api/client-server/definitions/errors/rate_limited.yaml index 1530458b..d5a8ebb1 100644 --- a/data/api/client-server/definitions/errors/rate_limited.yaml +++ b/data/api/client-server/definitions/errors/rate_limited.yaml @@ -11,23 +11,24 @@ # 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. -$ref: error.yaml -type: object -title: RateLimitError -description: The rate limit was reached for this request -properties: - errcode: - type: string - description: The M_LIMIT_EXCEEDED error code - example: M_LIMIT_EXCEEDED - error: - type: string - description: A human-readable error message. - example: Too many requests - retry_after_ms: - type: integer - description: |- - The amount of time in milliseconds the client should wait - before trying the request again. - example: 2000 -required: ["errcode"] +allOf: + - $ref: error.yaml + - type: object + title: RateLimitError + description: The rate limit was reached for this request + properties: + errcode: + type: string + description: The M_LIMIT_EXCEEDED error code + example: M_LIMIT_EXCEEDED + error: + type: string + description: A human-readable error message. + example: Too many requests + retry_after_ms: + type: integer + description: |- + The amount of time in milliseconds the client should wait + before trying the request again. + example: 2000 + required: ["errcode"] diff --git a/data/api/client-server/definitions/event_batch.yaml b/data/api/client-server/definitions/event_batch.yaml index e326184c..cc2453ed 100644 --- a/data/api/client-server/definitions/event_batch.yaml +++ b/data/api/client-server/definitions/event_batch.yaml @@ -16,9 +16,7 @@ properties: events: description: List of events. items: - allOf: - - $ref: ../../../event-schemas/schema/core-event-schema/event.yaml - type: object + $ref: ../../../event-schemas/schema/core-event-schema/event.yaml type: array type: object title: EventBatch diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 06efad74..19ec89d5 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -38,8 +38,7 @@ properties: conditions: type: array items: - allOf: - - $ref: push_condition.yaml + $ref: push_condition.yaml description: |- The conditions that must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Only diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 809b2c0d..8f8b62b4 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -109,10 +109,10 @@ paths: - object - string event: - type: object title: Event description: The Event object for the event that triggered the notification. - "$ref": "definitions/client_event_without_room_id.yaml" + allOf: + - "$ref": "definitions/client_event_without_room_id.yaml" profile_tag: type: string description: The profile tag of the rule that matched this event. diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 8813d10f..329289d8 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -221,7 +221,8 @@ paths: type: object title: "InviteEvent" description: "The invite event if `membership` is `invite`" - $ref: "definitions/client_event.yaml" + allOf: + - $ref: "definitions/client_event.yaml" messages: type: object title: PaginationChunk diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 5454f0a1..2d45fe2a 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -204,7 +204,8 @@ paths: type: object title: Event description: The event that matched. - "$ref": "definitions/client_event.yaml" + allOf: + - "$ref": "definitions/client_event.yaml" context: type: object title: Event Context @@ -270,7 +271,6 @@ paths: type: array title: Room State items: - type: object "$ref": "definitions/client_event.yaml" groups: type: object diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index ae72b77c..4a83a34f 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -191,7 +191,8 @@ paths: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services. - $ref: "../../schemas/server-signatures.yaml" + allOf: + - $ref: "../../schemas/server-signatures.yaml" required: - address - medium diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml index d81b973d..2308dc7b 100644 --- a/data/api/identity/v2_invitation_signing.yaml +++ b/data/api/identity/v2_invitation_signing.yaml @@ -74,7 +74,8 @@ paths: signatures: type: object description: The signature of the mxid, sender, and token. - $ref: "../../schemas/server-signatures.yaml" + allOf: + - $ref: "../../schemas/server-signatures.yaml" token: type: string description: The token for the invitation. diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml index 2221ad5f..81519e66 100644 --- a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml @@ -85,7 +85,8 @@ allOf: description: |- The updated identity keys (if any) for this device. May be absent if the device has no E2E keys defined. - $ref: ../../../client-server/definitions/device_keys.yaml + allOf: + - $ref: ../../../client-server/definitions/device_keys.yaml required: - user_id - device_id diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml index 55d91141..aea99fe0 100644 --- a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -37,8 +37,8 @@ allOf: description: The user ID whose cross-signing keys have changed. example: "@alice:example.com" master_key: - type: object - $ref: ../../../client-server/definitions/cross_signing_key.yaml + allOf: + - $ref: ../../../client-server/definitions/cross_signing_key.yaml example: { "user_id": "@alice:example.com", "usage": ["master"], @@ -47,8 +47,8 @@ allOf: } } self_signing_key: - type: object - $ref: ../../../client-server/definitions/cross_signing_key.yaml + allOf: + - $ref: ../../../client-server/definitions/cross_signing_key.yaml example: { "user_id": "@alice:example.com", "usage": ["self_signing"], diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 1c127f9b..14242867 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -76,7 +76,8 @@ paths: keys: type: object description: Identity keys for the device. - $ref: "../client-server/definitions/device_keys.yaml" + allOf: + - $ref: "../client-server/definitions/device_keys.yaml" device_display_name: type: string description: Optional display name for the device. From c0955a6aee9073a536ed8c525527b9ce2819a74d Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 8 Mar 2023 09:58:29 +0000 Subject: [PATCH 23/32] Add a hyphen between third and party when used as an adjective (#1447) --- attic/drafts/model/rooms.rst | 2 +- attic/drafts/model/third-party-id.rst | 12 ++--- .../newsfragments/1447.clarification | 1 + .../newsfragments/1447.clarification | 1 + changelogs/legacy/application_service.rst | 2 +- changelogs/legacy/client_server.rst | 4 +- changelogs/legacy/identity_service.rst | 4 +- .../newsfragments/1447.clarification | 1 + content/_index.md | 2 +- content/appendices.md | 2 +- content/application-service-api.md | 12 ++--- content/client-server-api/_index.md | 22 ++++---- content/client-server-api/modules/openid.md | 4 +- .../modules/third_party_invites.md | 36 ++++++------- .../modules/third_party_networks.md | 16 +++--- content/identity-service-api.md | 10 ++-- content/server-server-api.md | 6 +-- .../definitions/location.yaml | 4 +- .../definitions/location_batch.yaml | 2 +- .../definitions/protocol.yaml | 10 ++-- .../definitions/protocol_metadata.yaml | 2 +- .../application-service/definitions/user.yaml | 6 +-- .../definitions/user_batch.yaml | 2 +- data/api/application-service/protocols.yaml | 24 ++++----- .../client-server/administrative_contact.yaml | 54 +++++++++---------- data/api/client-server/create_room.yaml | 6 +-- .../definitions/third_party_signed.yaml | 4 +- data/api/client-server/inviting.yaml | 2 +- data/api/client-server/list_public_rooms.yaml | 2 +- data/api/client-server/login.yaml | 4 +- data/api/client-server/registration.yaml | 16 +++--- .../api/client-server/third_party_lookup.yaml | 42 +++++++-------- .../client-server/third_party_membership.yaml | 18 +++---- data/api/server-server/public_rooms.yaml | 4 +- .../api/server-server/third_party_invite.yaml | 32 +++++------ data/event-schemas/schema/m.room.member.yaml | 2 +- .../schema/m.room.third_party_invite.yaml | 4 +- 37 files changed, 190 insertions(+), 187 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1447.clarification create mode 100644 changelogs/client_server/newsfragments/1447.clarification create mode 100644 changelogs/server_server/newsfragments/1447.clarification diff --git a/attic/drafts/model/rooms.rst b/attic/drafts/model/rooms.rst index 2f57f2bc..01d25c2f 100644 --- a/attic/drafts/model/rooms.rst +++ b/attic/drafts/model/rooms.rst @@ -246,7 +246,7 @@ anyway. In this arrangement there is now a room with both users may join but neither has the power to invite any others. Both users now have the confidence that (at least within the messaging system itself) their messages remain private and -cannot later be provably leaked to a third party. They can freely set the topic +cannot later be provably leaked to a third-party. They can freely set the topic or name if they choose and add or edit any other state of the room. The update powerlevel of each of these fixed properties should be 1, to lock out the users from being able to alter them. diff --git a/attic/drafts/model/third-party-id.rst b/attic/drafts/model/third-party-id.rst index 838a6799..ccbd005f 100644 --- a/attic/drafts/model/third-party-id.rst +++ b/attic/drafts/model/third-party-id.rst @@ -1,9 +1,9 @@ ====================== -Third Party Identities +Third-party Identities ====================== -A description of how email addresses, mobile phone numbers and other third -party identifiers can be used to authenticate and discover users in Matrix. +A description of how email addresses, mobile phone numbers and other third-party +identifiers can be used to authenticate and discover users in Matrix. Overview @@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate with those contacts in Matrix without manually exchanging a Matrix User ID with them. -Third Party IDs +Third-party IDs --------------- [[TODO(markjh): Describe the format of a 3PID]] -Third Party ID Associations +Third-party ID Associations --------------------------- -An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID). +An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID). Each 3PID can be associated with one Matrix User ID at a time. [[TODO(markjh): JSON format of the association.]] diff --git a/changelogs/application_service/newsfragments/1447.clarification b/changelogs/application_service/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/application_service/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1447.clarification b/changelogs/client_server/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/legacy/application_service.rst b/changelogs/legacy/application_service.rst index 51a97637..a59e1bb9 100644 --- a/changelogs/legacy/application_service.rst +++ b/changelogs/legacy/application_service.rst @@ -22,5 +22,5 @@ r0.1.0 This is the first release of the Application Service specification. It includes support for application services being able to interact with -homeservers and bridge third party networks, such as IRC, over to Matrix +homeservers and bridge third-party networks, such as IRC, over to Matrix in a standard and accessible way. diff --git a/changelogs/legacy/client_server.rst b/changelogs/legacy/client_server.rst index c5b8fae9..ef71bbbc 100644 --- a/changelogs/legacy/client_server.rst +++ b/changelogs/legacy/client_server.rst @@ -211,7 +211,7 @@ Backwards Compatible Changes - Add a common standard for user, room, and group mentions in messages. (`#1547 `_) - Add server ACLs as an option for controlling federation in a room. (`#1550 `_) - Add new push rules for encrypted events and ``@room`` notifications. (`#1551 `_) -- Add third party network room directories, as provided by application services. (`#1554 `_) +- Add third-party network room directories, as provided by application services. (`#1554 `_) - Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 `_) - Add an ``inhibit_login`` registration option. (`#1589 `_) - Recommend that servers set a Content Security Policy for the content repository. (`#1600 `_) @@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made: - Push notification - History visibility - Search - - Invites based on third party identifiers + - Invites based on third-party identifiers - Room tagging - Guest access - Client config diff --git a/changelogs/legacy/identity_service.rst b/changelogs/legacy/identity_service.rst index 7cccc0cf..6941e275 100644 --- a/changelogs/legacy/identity_service.rst +++ b/changelogs/legacy/identity_service.rst @@ -48,7 +48,7 @@ r0.1.0 ====== This is the first release of the Identity Service API. With this API, clients and -homeservers can store bindings between third party identifiers such as email addresses +homeservers can store bindings between third-party identifiers such as email addresses and phone numbers, associating them with Matrix user IDs. Additionally, identity -servers offer the ability to invite third party users to Matrix rooms by storing +servers offer the ability to invite third-party users to Matrix rooms by storing the invite until the identifier is bound. diff --git a/changelogs/server_server/newsfragments/1447.clarification b/changelogs/server_server/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/server_server/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/content/_index.md b/content/_index.md index 62e2ef85..6396e4a3 100644 --- a/content/_index.md +++ b/content/_index.md @@ -372,7 +372,7 @@ servers that are in the room that can be used to join via. Users in Matrix are identified via their Matrix user ID. However, existing 3rd party ID namespaces can also be used in order to identify Matrix users. A Matrix "Identity" describes both the user ID and any -other existing IDs from third party namespaces *linked* to their +other existing IDs from third-party namespaces *linked* to their account. Matrix users can *link* third-party IDs (3PIDs) such as email addresses, social network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping diff --git a/content/appendices.md b/content/appendices.md index 203c650a..72bda5e9 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -892,7 +892,7 @@ unique servers based on the following criteria: ## 3PID Types -Third Party Identifiers (3PIDs) represent identifiers on other +Third-party Identifiers (3PIDs) represent identifiers on other namespaces that might be associated with a particular person. They comprise a tuple of `medium` which is a string that identifies the namespace in which the identifier exists, and an `address`: a string diff --git a/content/application-service-api.md b/content/application-service-api.md index fa24d6fd..7a14869a 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -232,18 +232,18 @@ mappings. {{% http-api spec="application-service" api="query_room" %}} -#### Third party networks +#### Third-party networks Application services may declare which protocols they support via their registration configuration for the homeserver. These networks are -generally for third party services such as IRC that the application +generally for third-party services such as IRC that the application service is managing. Application services may populate a Matrix room directory for their registered protocols, as defined in the Client-Server API Extensions. -Each protocol may have several "locations" (also known as "third party +Each protocol may have several "locations" (also known as "third-party locations" or "3PLs"). A location within a protocol is a place in the -third party network, such as an IRC channel. Users of the third party +third-party network, such as an IRC channel. Users of the third-party network may also be represented by the application service. Locations and users can be searched by fields defined by the application @@ -399,13 +399,13 @@ the user implied by `sender_localpart`. #### Application service room directories Application services can maintain their own room directories for their -defined third party protocols. These room directories may be accessed by +defined third-party protocols. These room directories may be accessed by clients through additional parameters on the `/publicRooms` client-server endpoint. {{% http-api spec="client-server" api="appservice_room_directory" %}} -### Referencing messages from a third party network +### Referencing messages from a third-party network Application services should include an `external_url` in the `content` of events it emits to indicate where the message came from. This diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d2759a46..617d9259 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -150,15 +150,15 @@ Sent when a threepid given to an API cannot be used because no record matching the threepid was found. `M_THREEPID_AUTH_FAILED` -Authentication could not be performed on the third party identifier. +Authentication could not be performed on the third-party identifier. `M_THREEPID_DENIED` -The server does not permit this third party identifier. This may happen +The server does not permit this third-party identifier. This may happen if the server only permits, for example, email addresses from a particular domain. `M_SERVER_NOT_TRUSTED` -The client's request used a third party server, e.g. identity server, +The client's request used a third-party server, e.g. identity server, that this server does not trust. `M_UNSUPPORTED_ROOM_VERSION` @@ -764,8 +764,8 @@ explicitly as follows: "type": "m.login.password", "identifier": { "type": "m.id.thirdparty", - "medium": "", - "address": "" + "medium": "", + "address": "" }, "password": "", "session": "" @@ -1071,8 +1071,8 @@ ID media. ```json "identifier": { "type": "m.id.thirdparty", - "medium": "", - "address": "" + "medium": "", + "address": "" } ``` @@ -1132,8 +1132,8 @@ the homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API r { "type": "m.login.password", "identifier": { - "medium": "", - "address": "" + "medium": "", + "address": "" }, "password": "" } @@ -1258,7 +1258,7 @@ can be added and bound at the same time, depending on context. #### Notes on identity servers Identity servers in Matrix store bindings (relationships) between a -user's third party identifier, typically email or phone number, and +user's third-party identifier, typically email or phone number, and their user ID. Once a user has chosen an identity server, that identity server should be used by all clients. @@ -2566,7 +2566,7 @@ that profile. | [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional | | [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | | [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | -| [Third Party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | | [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | | [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional | | [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional | diff --git a/content/client-server-api/modules/openid.md b/content/client-server-api/modules/openid.md index 6e0c2d04..1aff30cd 100644 --- a/content/client-server-api/modules/openid.md +++ b/content/client-server-api/modules/openid.md @@ -1,8 +1,8 @@ ### OpenID -This module allows users to verify their identity with a third party -service. The third party service does need to be matrix-aware in that it +This module allows users to verify their identity with a third-party +service. The third-party service does need to be matrix-aware in that it will need to know to resolve matrix homeservers to exchange the user's token for identity information. diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index fcf0b86a..aff7b530 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -1,12 +1,12 @@ -### Third party invites +### Third-party invites 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 +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` with the details of the -third party identifier. +third-party identifier. The homeserver asks the identity server whether a Matrix user ID is known for that identifier: @@ -22,7 +22,7 @@ When the invitee's homeserver receives the notification of the binding, it should insert an `m.room.member` event into the room's graph for that user, with `content.membership` = `invite`, as well as a `content.third_party_invite` property which contains proof that the -invitee does indeed own that third party identifier. See the +invitee does indeed own that third-party identifier. See the [m.room.member](#mroommember) schema for more information. #### Events @@ -31,14 +31,14 @@ invitee does indeed own that third party identifier. See the #### Client behaviour -A client asks a server to invite a user by their third party identifier. +A client asks a server to invite a user by their third-party identifier. {{% http-api spec="client-server" api="third_party_membership" %}} #### Server behaviour Upon receipt of an `/invite`, the server is expected to look up the -third party identifier with the provided identity server. If the lookup +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: @@ -104,12 +104,12 @@ 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 +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 +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. +bound the third-party identifier. 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 @@ -123,7 +123,7 @@ view of the room. They may, however, indicate to their clients that a member's membership is questionable. For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, -and an identity server IS, the full sequence for a third party invite +and an identity server IS, the full sequence for a third-party invite would look like the following. This diagram assumes H1 and H2 are residents of the room while H3 is attempting to join. @@ -144,7 +144,7 @@ residents of the room while H3 is attempting to join. | | | POST /store-invite | | | | | |---------------------------------------------------------------------------------------------->| | | | | | | - | | | | Token, keys, etc for third party invite | + | | | | Token, keys, etc for third-party invite | | | |<----------------------------------------------------------------------------------------------| | | | | | | | | | (Federation) Emit m.room.third_party_invite | | | @@ -214,13 +214,13 @@ still be performed, so the attack surface here is minimized. There are a number of privacy and trust implications to this module. It is important for user privacy that leaking the mapping between a -matrix user ID and a third party identifier is hard. In particular, -being able to look up all third party identifiers from a matrix user ID -(and accordingly, being able to link each third party identifier) should -be avoided wherever possible. To this end, the third party identifier is +matrix user ID and a third-party identifier is hard. In particular, +being able to look up all third-party identifiers from a matrix user ID +(and accordingly, being able to link each third-party identifier) should +be avoided wherever possible. To this end, the third-party identifier is not put in any event, rather an opaque display name provided by the identity server is put into the events. Clients should not remember or -display third party identifiers from invites, other than for the use of +display third-party identifiers from invites, other than for the use of the inviter themself. Homeservers are not required to trust any particular identity server(s). diff --git a/content/client-server-api/modules/third_party_networks.md b/content/client-server-api/modules/third_party_networks.md index a0db5785..e4d9cf53 100644 --- a/content/client-server-api/modules/third_party_networks.md +++ b/content/client-server-api/modules/third_party_networks.md @@ -1,18 +1,18 @@ -### Third Party Networks +### Third-party Networks -Application services can provide access to third party networks via +Application services can provide access to third-party networks via bridging. This allows Matrix users to communicate with users on other communication platforms, with messages ferried back and forth by the application service. A single application service may bridge multiple -third party networks, and many individual locations within those -networks. A single third party network location may be bridged to +third-party networks, and many individual locations within those +networks. A single third-party network location may be bridged to multiple Matrix rooms. -#### Third Party Lookups +#### Third-party Lookups -A client may wish to provide a rich interface for joining third party -locations and connecting with third party users. Information necessary -for such an interface is provided by third party lookups. +A client may wish to provide a rich interface for joining third-party +locations and connecting with third-party users. Information necessary +for such an interface is provided by third-party lookups. {{% http-api spec="client-server" api="third_party_lookup" %}} diff --git a/content/identity-service-api.md b/content/identity-service-api.md index a9676120..9e2d5cdf 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -98,11 +98,11 @@ There was an error sending an email. Typically seen when attempting to verify ownership of a given email address. `M_INVALID_ADDRESS` -The provided third party address was not valid. +The provided third-party address was not valid. `M_SEND_ERROR` There was an error sending a notification. Typically seen when -attempting to verify ownership of a given third party address. +attempting to verify ownership of a given third-party address. `M_UNRECOGNIZED` The request contained an unrecognised value, such as an unknown token or @@ -114,9 +114,9 @@ not implemented or a 405 HTTP status code if the endpoint is implemented, but the incorrect HTTP method is used. `M_THREEPID_IN_USE` -The third party identifier is already in use by another user. Typically +The third-party identifier is already in use by another user. Typically this error will have an additional `mxid` property to indicate who owns -the third party identifier. +the third-party identifier. `M_UNKNOWN` An unknown error has occurred. @@ -369,7 +369,7 @@ To start a session, the client makes a request to the appropriate token to the user, and the user provides the token to the client. The client then provides the token to the appropriate `/submitToken` endpoint, completing the session. At this point, the client should -`/bind` the third party identifier or leave it for another entity to +`/bind` the third-party identifier or leave it for another entity to bind. ### Format of a validation token diff --git a/content/server-server-api.md b/content/server-server-api.md index bcf0db4e..ff14bd04 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -938,9 +938,9 @@ the event to other servers in the room. ## Third-party invites {{% boxes/note %}} -More information about third party invites is available in the +More information about third-party invites is available in the [Client-Server API](/client-server-api) under -the Third Party Invites module. +the Third-party Invites module. {{% /boxes/note %}} When a user wants to invite another user in a room but doesn't know the @@ -1076,7 +1076,7 @@ more specific queries that can be made. ## OpenID -Third party services can exchange an access token previously generated +Third-party services can exchange an access token previously generated by the Client-Server API for information about a user. This can help verify that a user is who they say they are without granting full access to the user's account. diff --git a/data/api/application-service/definitions/location.yaml b/data/api/application-service/definitions/location.yaml index 5a0f92c8..12cdad59 100644 --- a/data/api/application-service/definitions/location.yaml +++ b/data/api/application-service/definitions/location.yaml @@ -17,11 +17,11 @@ properties: type: string example: "#freenode_#matrix:matrix.org" protocol: - description: The protocol ID that the third party location is a part of. + description: The protocol ID that the third-party location is a part of. type: string example: "irc" fields: - description: Information used to identify this third party location. + description: Information used to identify this third-party location. type: object example: { "network": "freenode", diff --git a/data/api/application-service/definitions/location_batch.yaml b/data/api/application-service/definitions/location_batch.yaml index 3f6de9df..35875ddb 100644 --- a/data/api/application-service/definitions/location_batch.yaml +++ b/data/api/application-service/definitions/location_batch.yaml @@ -12,6 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: array -description: List of matched third party locations. +description: List of matched third-party locations. items: $ref: location.yaml diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index b16eedfc..f29d72e8 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -16,28 +16,28 @@ type: object properties: user_fields: description: |- - Fields which may be used to identify a third party user. These should be + Fields which may be used to identify a third-party user. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the nickname of a user. type: array items: type: string - description: Field used to identify a third party user. + description: Field used to identify a third-party user. example: ["network", "nickname"] location_fields: description: |- - Fields which may be used to identify a third party location. These should be + Fields which may be used to identify a third-party location. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the name of a channel. type: array items: type: string - description: Field used to identify a third party location. + description: Field used to identify a third-party location. example: ["network", "channel"] icon: - description: A content URI representing an icon for the third party protocol. + description: A content URI representing an icon for the third-party protocol. type: string example: "mxc://example.org/aBcDeFgH" field_types: diff --git a/data/api/application-service/definitions/protocol_metadata.yaml b/data/api/application-service/definitions/protocol_metadata.yaml index e7bf45da..cd2af89f 100644 --- a/data/api/application-service/definitions/protocol_metadata.yaml +++ b/data/api/application-service/definitions/protocol_metadata.yaml @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -description: Dictionary of supported third party protocols. +description: Dictionary of supported third-party protocols. additionalProperties: $ref: protocol.yaml example: { diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml index 258e7c13..3178b56d 100644 --- a/data/api/application-service/definitions/user.yaml +++ b/data/api/application-service/definitions/user.yaml @@ -15,15 +15,15 @@ # TODO: Change userid to user_id as a breaking change properties: userid: - description: A Matrix User ID represting a third party user. + description: A Matrix User ID represting a third-party user. type: string example: "@_gitter_jim:matrix.org" protocol: - description: The protocol ID that the third party location is a part of. + description: The protocol ID that the third-party location is a part of. type: string example: "gitter" fields: - description: Information used to identify this third party location. + description: Information used to identify this third-party location. type: object example: { "user": "jim" diff --git a/data/api/application-service/definitions/user_batch.yaml b/data/api/application-service/definitions/user_batch.yaml index 3653feb4..f9885996 100644 --- a/data/api/application-service/definitions/user_batch.yaml +++ b/data/api/application-service/definitions/user_batch.yaml @@ -12,6 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: array -description: List of matched third party users. +description: List of matched third-party users. items: $ref: user.yaml diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index b1e3ce6e..47f62b8f 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -32,7 +32,7 @@ paths: summary: Retrieve metadata about a specific protocol that the application service supports. description: |- This API is called by the homeserver when it wants to present clients - with specific information about the various third party networks that + with specific information about the various third-party networks that an application service supports. operationId: getProtocolMetadata security: @@ -78,10 +78,10 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix User ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third-party user. description: |- This API is called by the homeserver in order to retrieve a Matrix - User ID linked to a user on the third party network, given a set of + User ID linked to a user on the third-party network, given a set of user parameters. operationId: queryUserByProtocol security: @@ -133,9 +133,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/location/{protocol}": get: - summary: Retrieve Matrix-side portal rooms leading to a third party location. + summary: Retrieve Matrix-side portal rooms leading to a third-party location. description: |- - Retrieve a list of Matrix portal rooms that lead to the matched third party location. + Retrieve a list of Matrix portal rooms that lead to the matched third-party location. operationId: queryLocationByProtocol security: - homeserverAccessToken: [] @@ -151,7 +151,7 @@ paths: type: string description: |- One or more custom fields that are passed to the application - service to help identify the third party location. + service to help identify the third-party location. responses: 200: description: At least one portal room was found. @@ -186,9 +186,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/location": get: - summary: Reverse-lookup third party locations given a Matrix room alias. + summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- - Retrieve an array of third party network locations from a Matrix room + Retrieve an array of third-party network locations from a Matrix room alias. operationId: queryLocationByAlias security: @@ -201,7 +201,7 @@ paths: responses: 200: description: |- - All found third party locations. + All found third-party locations. schema: $ref: definitions/location_batch.yaml 401: @@ -233,9 +233,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix User ID. + summary: Reverse-lookup third-party users given a Matrix User ID. description: |- - Retrieve an array of third party users from a Matrix User ID. + Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - homeserverAccessToken: [] @@ -247,7 +247,7 @@ paths: responses: 200: description: |- - An array of third party users. + An array of third-party users. schema: $ref: definitions/user_batch.yaml 401: diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 8bee761f..fd6adc94 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -30,12 +30,12 @@ securityDefinitions: paths: "/account/3pid": get: - summary: Gets a list of a user's third party identifiers. + summary: Gets a list of a user's third-party identifiers. description: |- - Gets a list of the third party identifiers that the homeserver has + Gets a list of the third-party identifiers that the homeserver has associated with the user's account. - This is *not* the same as the list of third party identifiers bound to + This is *not* the same as the list of third-party identifiers bound to the user's Matrix ID in identity servers. Identifiers in this list may be used by the homeserver as, for example, @@ -64,15 +64,15 @@ paths: type: array items: type: object - title: Third party identifier + title: Third-party identifier properties: medium: type: string - description: The medium of the third party identifier. + description: The medium of the third-party identifier. enum: ["email", "msisdn"] address: type: string - description: The third party identifier address. + description: The third-party identifier address. validated_at: type: integer format: int64 @@ -84,7 +84,7 @@ paths: format: int64 description: The timestamp, in milliseconds, when the homeserver - associated the third party identifier with the user. + associated the third-party identifier with the user. required: ['medium', 'address', 'validated_at', 'added_at'] tags: - Account management @@ -115,7 +115,7 @@ paths: three_pid_creds: title: "ThreePidCredentials" type: object - description: The third party credentials to associate with the account. + description: The third-party credentials to associate with the account. properties: client_secret: type: string @@ -174,7 +174,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third party credentials could not be verified by the identity server." + "error": "The third-party credentials could not be verified by the identity server." } schema: "$ref": "definitions/errors/error.yaml" @@ -290,9 +290,9 @@ paths: - Account management "/account/3pid/delete": post: - summary: Deletes a third party identifier from the user's account + summary: Deletes a third-party identifier from the user's account description: |- - Removes a third party identifier from the user's account. This might not + Removes a third-party identifier from the user's account. This might not cause an unbind of the identifier from the identity server. Unlike other endpoints, this endpoint does not take an `id_access_token` @@ -318,18 +318,18 @@ paths: example: "example.org" medium: type: string - description: The medium of the third party identifier being removed. + description: The medium of the third-party identifier being removed. enum: ["email", "msisdn"] example: "email" address: type: string - description: The third party address being removed. + description: The third-party address being removed. example: "example@example.org" required: ['medium', 'address'] responses: 200: description: |- - The homeserver has disassociated the third party identifier from the + The homeserver has disassociated the third-party identifier from the user. schema: type: object @@ -355,9 +355,9 @@ paths: - Account management "/account/3pid/unbind": post: - summary: Removes a user's third party identifier from an identity server. + summary: Removes a user's third-party identifier from an identity server. description: |- - Removes a user's third party identifier from the provided identity server + Removes a user's third-party identifier from the provided identity server without removing it from the homeserver. Unlike other endpoints, this endpoint does not take an `id_access_token` @@ -383,18 +383,18 @@ paths: example: "example.org" medium: type: string - description: The medium of the third party identifier being removed. + description: The medium of the third-party identifier being removed. enum: ["email", "msisdn"] example: "email" address: type: string - description: The third party address being removed. + description: The third-party address being removed. example: "example@example.org" required: ['medium', 'address'] responses: 200: description: |- - The identity server has disassociated the third party identifier from the + The identity server has disassociated the third-party identifier from the user. schema: type: object @@ -446,18 +446,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The third party identifier is already in use on the homeserver, or + The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -466,7 +466,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_IN_USE", - "error": "Third party identifier already in use" + "error": "Third-party identifier already in use" } tags: - Account management @@ -496,18 +496,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The third party identifier is already in use on the homeserver, or + The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -516,7 +516,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_IN_USE", - "error": "Third party identifier already in use" + "error": "Third-party identifier already in use" } tags: - Account management diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 07d9c0af..a39cc4f5 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -138,7 +138,7 @@ paths: invite_3pid: type: array description: |- - A list of objects representing third party IDs to invite into + A list of objects representing third-party IDs to invite into the room. items: type: object @@ -146,7 +146,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third-party identifier lookups. id_access_token: type: string description: |- @@ -160,7 +160,7 @@ paths: (see [the list of recognised values](/appendices/#3pid-types)). address: type: string - description: The invitee's third party identifier. + description: The invitee's third-party identifier. required: ["id_server", "id_access_token", "medium", "address"] room_version: type: string diff --git a/data/api/client-server/definitions/third_party_signed.yaml b/data/api/client-server/definitions/third_party_signed.yaml index 4af422b4..071d9491 100644 --- a/data/api/client-server/definitions/third_party_signed.yaml +++ b/data/api/client-server/definitions/third_party_signed.yaml @@ -12,10 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -title: Third Party Signed +title: Third-party Signed description: |- A signature of an `m.third_party_invite` token to prove that this user - owns a third party identity which has been invited to the room. + owns a third-party identity which has been invited to the room. properties: sender: type: string diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 96e3dae2..53439e95 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -36,7 +36,7 @@ paths: *Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter knows the Matrix identifier of the invitee. The other is documented in the - [third party invites](/client-server-api/#third-party-invites) section.* + [third-party invites](/client-server-api/#third-party-invites) section.* This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 6391bbbd..185a955e 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -219,7 +219,7 @@ paths: third_party_instance_id: type: string description: |- - The specific third party network/protocol to request from the + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 4c348fcd..7c33d1a4 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -107,10 +107,10 @@ paths: description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. medium: type: string - description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. + description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. address: type: string - description: Third party identifier for the user. Deprecated in favour of `identifier`. + description: Third-party identifier for the user. Deprecated in favour of `identifier`. password: type: string description: |- diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index f48385e9..9fe4d4ad 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -272,7 +272,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- @@ -324,7 +324,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- @@ -443,18 +443,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The referenced third party identifier is not recognised by the + The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -500,18 +500,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The referenced third party identifier is not recognised by the + The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index f56554e3..ba368459 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Third Party Lookup API" + title: "Matrix Client-Server Third-party Lookup API" version: "1.0.0" host: localhost:8008 schemes: @@ -43,12 +43,12 @@ paths: schema: $ref: ../application-service/definitions/protocol_metadata.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. description: |- - Fetches the metadata from the homeserver about a particular third party protocol. + Fetches the metadata from the homeserver about a particular third-party protocol. operationId: getProtocolMetadata security: - accessToken: [] @@ -74,16 +74,16 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/location/{protocol}": get: - summary: Retrieve Matrix-side portals rooms leading to a third party location. + summary: Retrieve Matrix-side portals rooms leading to a third-party location. description: |- Requesting this endpoint with a valid protocol name results in a list of successful mapping results in a JSON array. Each result contains objects to represent the Matrix room or rooms that represent a portal - to this third party network. Each has the Matrix room alias string, - an identifier for the particular third party network protocol, and an + to this third-party network. Each has the Matrix room alias string, + an identifier for the particular third-party network protocol, and an object containing the network-specific fields that comprise this identifier. It should attempt to canonicalise the identifier as much as reasonably possible given the network type. @@ -94,14 +94,14 @@ paths: - in: path name: protocol type: string - description: The protocol used to communicate to the third party network. + description: The protocol used to communicate to the third-party network. required: true x-example: irc - in: query name: searchFields type: string description: |- - One or more custom fields to help identify the third party + One or more custom fields to help identify the third-party location. responses: 200: @@ -117,12 +117,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix User ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third-party user. description: |- - Retrieve a Matrix User ID linked to a user on the third party service, given + Retrieve a Matrix User ID linked to a user on the third-party service, given a set of user parameters. operationId: queryUserByProtocol security: @@ -154,12 +154,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/location": get: - summary: Reverse-lookup third party locations given a Matrix room alias. + summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- - Retrieve an array of third party network locations from a Matrix room + Retrieve an array of third-party network locations from a Matrix room alias. operationId: queryLocationByAlias security: @@ -174,7 +174,7 @@ paths: responses: 200: description: |- - All found third party locations. + All found third-party locations. schema: $ref: ../application-service/definitions/location_batch.yaml 404: @@ -186,12 +186,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix User ID. + summary: Reverse-lookup third-party users given a Matrix User ID. description: |- - Retrieve an array of third party users from a Matrix User ID. + Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - accessToken: [] @@ -205,7 +205,7 @@ paths: responses: 200: description: |- - An array of third party users. + An array of third-party users. schema: $ref: ../application-service/definitions/user_batch.yaml 404: @@ -217,4 +217,4 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index 27bcad37..c6ce230e 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Room Membership API for third party identifiers" + title: "Matrix Client-Server Room Membership API for third-party identifiers" version: "1.0.0" host: localhost:8008 schemes: @@ -33,9 +33,9 @@ paths: description: |- *Note that there are two forms of this API, which are documented separately. This version of the API does not require that the inviter know the Matrix - identifier of the invitee, and instead relies on third party identifiers. + identifier of the invitee, and instead relies on third-party identifiers. The homeserver uses an identity server to perform the mapping from - third party identifier to a Matrix identifier. The other is documented in the* + third-party identifier to a Matrix identifier. The other is documented in the* [joining rooms section](/client-server-api/#post_matrixclientv3roomsroomidinvite). This API invites a user to participate in a particular room. @@ -46,18 +46,18 @@ paths: join that room. If the identity server did know the Matrix user identifier for the - third party identifier, the homeserver will append a `m.room.member` + third-party identifier, the homeserver will append a `m.room.member` event to the room. If the identity server does not know a Matrix user identifier for the - passed third party identifier, the homeserver will issue an invitation - which can be accepted upon providing proof of ownership of the third + passed third-party identifier, the homeserver will issue an invitation + which can be accepted upon providing proof of ownership of the third- party identifier. This is achieved by the identity server generating a token, which it gives to the inviting homeserver. The homeserver will add an `m.room.third_party_invite` event into the graph for the room, containing that token. - When the invitee binds the invited third party identifier to a Matrix + When the invitee binds the invited third-party identifier to a Matrix user ID, the identity server will give the user a list of pending invitations, each containing: @@ -96,7 +96,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third-party identifier lookups. id_access_token: type: string description: |- @@ -110,7 +110,7 @@ paths: `email` (see [the list of recognised values](/appendices/#3pid-types)). address: type: string - description: The invitee's third party identifier. + description: The invitee's third-party identifier. required: ["id_server", "id_access_token", "medium", "address"] responses: 200: diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index c65a649a..3079b7c2 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -60,7 +60,7 @@ paths: name: third_party_instance_id type: string description: |- - The specific third party network/protocol to request from the homeserver. + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. x-example: "irc" responses: @@ -131,7 +131,7 @@ paths: third_party_instance_id: type: string description: |- - The specific third party network/protocol to request from the + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index 9a636aa9..55e4d628 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -14,7 +14,7 @@ swagger: '2.0' info: - title: "Matrix Federation Third Party Invites API" + title: "Matrix Federation Third-party Invites API" version: "1.0.0" host: localhost:8448 schemes: @@ -29,7 +29,7 @@ securityDefinitions: paths: "/exchange_third_party_invite/{roomId}": put: - summary: Request a server to auth a third party invite event + summary: Request a server to auth a third-party invite event description: |- The receiving server will verify the partial `m.room.member` event given in the request body. If valid, the receiving server will issue @@ -42,7 +42,7 @@ paths: - in: path name: roomId type: string - description: The room ID to exchange a third party invite in + description: The room ID to exchange a third-party invite in required: true x-example: "!abc123:matrix.org" - in: body @@ -84,14 +84,14 @@ paths: example: invite third_party_invite: type: object - description: The third party invite - title: Third Party Invite + description: The third-party invite + title: Third-party Invite properties: display_name: type: string description: |- A name which can be displayed to represent the user instead of their - third party identifier. + third-party identifier. example: "alice" signed: type: object @@ -203,11 +203,11 @@ paths: "/3pid/onbind": put: summary: |- - Notifies the server that a third party identifier has been bound to one + Notifies the server that a third-party identifier has been bound to one of its users. description: |- Used by identity servers to notify the homeserver that one of its users - has bound a third party identifier successfully, including any pending + has bound a third-party identifier successfully, including any pending room invites the identity server has been made aware of. operationId: onBindThirdPartyIdentifier parameters: @@ -221,36 +221,36 @@ paths: medium: type: string description: |- - The type of third party identifier. Currently only "email" is + The type of third-party identifier. Currently only "email" is a possible value. example: "email" address: type: string description: |- - The third party identifier itself. For example, an email address. + The third-party identifier itself. For example, an email address. example: "alice@example.com" mxid: type: string - description: The user that is now bound to the third party identifier. + description: The user that is now bound to the third-party identifier. example: "@alice:matrix.org" invites: type: array description: |- - A list of pending invites that the third party identifier has received. + A list of pending invites that the third-party identifier has received. items: type: object - title: Third Party Invite + title: Third-party Invite properties: medium: type: string description: |- - The type of third party invite issues. Currently only + The type of third-party invite issues. Currently only "email" is used. example: "email" address: type: string description: |- - The third party identifier that received the invite. + The third-party identifier that received the invite. example: "alice@example.com" mxid: type: string @@ -276,7 +276,7 @@ paths: mxid: type: string description: |- - The user ID that has been bound to the third party + The user ID that has been bound to the third-party identifier. example: "@alice:matrix.org" token: diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index bf2f7145..24b6005f 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -88,7 +88,7 @@ properties: third_party_invite: 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.' 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 f4188192..7a00616b 100644 --- a/data/event-schemas/schema/m.room.third_party_invite.yaml +++ b/data/event-schemas/schema/m.room.third_party_invite.yaml @@ -7,7 +7,7 @@ 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'." @@ -42,5 +42,5 @@ properties: 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 From b441b19cc31b5325367df9edc4fa343741cb8a01 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Wed, 8 Mar 2023 11:39:06 +0100 Subject: [PATCH 24/32] More cleanup before upgrading to OpenAPI 3.1 (#1455) * `cross_signing_key.yaml`: the parameter documentation already restricts the number of properties * `receipts.yaml`: use `maxProperties: 0` to say the object is empty (the comment is still there but is not really needed any more) Signed-off-by: Alexey Rusakov --- changelogs/client_server/newsfragments/1455.clarification | 1 + data/api/client-server/definitions/cross_signing_key.yaml | 2 ++ data/api/client-server/receipts.yaml | 3 ++- 3 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1455.clarification diff --git a/changelogs/client_server/newsfragments/1455.clarification b/changelogs/client_server/newsfragments/1455.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1455.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/client-server/definitions/cross_signing_key.yaml b/data/api/client-server/definitions/cross_signing_key.yaml index cebc5ecd..d937daab 100644 --- a/data/api/client-server/definitions/cross_signing_key.yaml +++ b/data/api/client-server/definitions/cross_signing_key.yaml @@ -35,6 +35,8 @@ properties: The public key. The object must have exactly one property, whose name is in the form `:`, and whose value is the unpadded base64 public key. + minProperties: 1 + maxProperties: 1 example: "ed25519:alice+base64+public+key": "alice+base64+public+key" signatures: diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 27825001..0b8d4593 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -93,7 +93,8 @@ paths: application/json: { } schema: - type: object # empty json object + type: object + maxProperties: 0 # empty json object 429: description: This request was rate-limited. schema: From afae1083aa62b414782b52e1a7968b2480ce1c72 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 8 Mar 2023 08:06:06 -0500 Subject: [PATCH 25/32] Clarify what key content-specific rules match against. (#1441) --- .../newsfragments/1441.clarification | 1 + content/appendices.md | 8 ++++++++ .../modules/moderation_policies.md | 4 ++-- content/client-server-api/modules/push.md | 15 +++++++-------- .../client-server/definitions/push_condition.yaml | 4 ++-- data/api/client-server/definitions/push_rule.yaml | 4 ++-- data/event-schemas/schema/m.room.server_acl.yaml | 10 ++++------ 7 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1441.clarification diff --git a/changelogs/client_server/newsfragments/1441.clarification b/changelogs/client_server/newsfragments/1441.clarification new file mode 100644 index 00000000..f03519b8 --- /dev/null +++ b/changelogs/client_server/newsfragments/1441.clarification @@ -0,0 +1 @@ +Clarify what event property the content-specific push rules match against. diff --git a/content/appendices.md b/content/appendices.md index 72bda5e9..dc3ced66 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -934,6 +934,14 @@ The `address` is the telephone number represented as a MSISDN (Mobile Station International Subscriber Directory Number) as defined by the E.164 numbering plan. Note that MSISDNs do not include a leading '+'. +## Glob-style matching + +It is useful to match strings via globbing in some situations. Globbing in Matrix +uses the following rules: + +* The character `*` matches zero or more characters. +* `?` matches exactly one character. + ## Security Threat Model ### Denial of Service diff --git a/content/client-server-api/modules/moderation_policies.md b/content/client-server-api/modules/moderation_policies.md index 910df6a0..82a05963 100644 --- a/content/client-server-api/modules/moderation_policies.md +++ b/content/client-server-api/modules/moderation_policies.md @@ -75,8 +75,8 @@ technique for receiving updates to the policy's rules. #### Events -The `entity` described by the state events can contain `*` and `?` to -match zero or more characters and exactly one character respectively. Note that +The `entity` described by the state events is interpreted as a +[glob-style pattern](/appendices#glob-style-matching). Note that rules against rooms can describe a room ID or room alias - the subscriber is responsible for resolving the alias to a room ID if desired. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 0a104bc1..9c8d0adf 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -155,8 +155,12 @@ The different `kind`s of rule, in the order that they are checked, are: 1. **Content-specific rules (`content`).** These configure behaviour for (unencrypted) messages that match certain patterns. Content rules take one parameter: `pattern`, that gives the - glob pattern to match against. This is treated in the same way as - `pattern` for `event_match`. + [glob-style pattern](/appendices#glob-style-matching) to match against. + The match is performed case-insensitively, and must match any substring of + the `content.body` property which starts and ends at a word boundary. A word + boundary is defined as the start or end of the value, or any character not + in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`.The exact meaning of + "case insensitive" is defined by the implementation of the homeserver. 1. **Room-specific rules (`room`).** These rules change the behaviour of all messages for a given room. The @@ -264,18 +268,13 @@ This is a glob pattern match on a field of the event. Parameters: - `key`: The dot-separated path of the property of the event to match, e.g. `content.body`. -- `pattern`: The glob-style pattern to match against. +- `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against. The match is performed case-insensitively, and must match the entire value of the event field given by `key` (though see below regarding `content.body`). The exact meaning of "case insensitive" is defined by the implementation of the homeserver. -Within `pattern`: - - * The character `*` matches zero or more characters. - * `?` matches exactly one character. - If the property specified by `key` is completely absent from the event, or does not have a string value, then the condition will not match, even if `pattern` is `*`. diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 044f8627..4f2fe472 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -34,8 +34,8 @@ properties: pattern: type: string description: |- - Required for `event_match` conditions. The glob-style pattern to - match against. + Required for `event_match` conditions. The [glob-style pattern](/appendices#glob-style-matching) + to match against. is: type: string description: |- diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 19ec89d5..94a9d320 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -46,8 +46,8 @@ properties: pattern: type: string description: |- - The glob-style pattern to match against. Only applicable to `content` - rules. + The [glob-style pattern](/appendices#glob-style-matching) to match against. + Only applicable to `content` rules. required: - actions - default diff --git a/data/event-schemas/schema/m.room.server_acl.yaml b/data/event-schemas/schema/m.room.server_acl.yaml index 744e5231..c7a26c33 100644 --- a/data/event-schemas/schema/m.room.server_acl.yaml +++ b/data/event-schemas/schema/m.room.server_acl.yaml @@ -7,8 +7,8 @@ description: |- server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts list in order for the ACLs to remain effective. - The `allow` and `deny` lists are lists of globs supporting `?` and `*` - as wildcards. When comparing against the server ACLs, the suspect server's port + The `allow` and `deny` lists are lists of [glob-style patterns](/appendices#glob-style-matching). + When comparing against the server ACLs, the suspect server's port number must not be considered. Therefore `evil.com`, `evil.com:8448`, and `evil.com:1234` would all match rules that apply to `evil.com`, for example. @@ -61,8 +61,7 @@ properties: type: array description: |- The server names to allow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where `*` - matches zero or more characters and `?` matches exactly one character. + Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching). **This defaults to an empty list when not provided, effectively disallowing every server.** @@ -72,8 +71,7 @@ properties: type: array description: |- The server names to disallow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where `*` - matches zero or more characters and `?` matches exactly one character. + Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching). This defaults to an empty list when not provided. items: From a481d6aafb03adc7dfe50d60aa1efc49c64d3404 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 10 Mar 2023 19:39:24 -0700 Subject: [PATCH 26/32] Add mention of private sign off to contributing guidelines (#1462) --- CONTRIBUTING.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2aeefd7e..46c6c560 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -167,3 +167,15 @@ include the line in your commit or pull request comment:: can't be accepted. Git makes this trivial - just use the -s flag when you do ``git commit``, having first set ``user.name`` and ``user.email`` git configs (which you should have done anyway :) + +Private sign off +~~~~~~~~~~~~~~~~ + +If you would like to provide your legal name privately to the Matrix.org +Foundation (instead of in a public commit or comment), you can do so by emailing +your legal name and a link to the pull request to dco@matrix.org. It helps to +include "sign off" or similar in the subject line. You will then be instructed +further. + +Once private sign off is complete, doing so for future contributions will not +be required. From 53d7de2376b19cc9dabef6b0c0875b7c2719a1d2 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 14 Mar 2023 10:57:52 -0400 Subject: [PATCH 27/32] Define how clients process push rules (#1461) * Move Push Rules section out from Client Behaviour. * Clarify server vs. client behavior. * Remove references to unencrypted content. --- .../newsfragments/1461.clarification | 1 + content/client-server-api/modules/push.md | 164 ++++++++++-------- 2 files changed, 92 insertions(+), 73 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1461.clarification diff --git a/changelogs/client_server/newsfragments/1461.clarification b/changelogs/client_server/newsfragments/1461.clarification new file mode 100644 index 00000000..c205f380 --- /dev/null +++ b/changelogs/client_server/newsfragments/1461.clarification @@ -0,0 +1 @@ +Improve documentation of how clients use push rules. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 9c8d0adf..7667dd7a 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -85,58 +85,7 @@ Push Ruleset sender, a particular room, or by default. The push ruleset contains the entire set of scopes and rules. -#### Client behaviour - -Clients MUST configure a Pusher before they will receive push -notifications. There is a single API endpoint for this, as described -below. - -{{% http-api spec="client-server" api="pusher" %}} - -##### Listing Notifications - -A client can retrieve a list of events that it has been notified about. -This may be useful so that users can see a summary of what important -messages they have received. - -{{% http-api spec="client-server" api="notifications" %}} - -##### Receiving notifications - -Servers MUST include the number of unread notifications in a client's -`/sync` stream, and MUST update it as it changes. Notifications are -determined by the push rules which apply to an event. - -When the user updates their read receipt (either by using the API or by -sending an event), notifications prior to and including that event MUST -be marked as read. Which specific events are affected can vary depending -on whether a [threaded read receipt](#threaded-read-receipts) was used. -Note that users can send both an `m.read` and `m.read.private` receipt, -both of which are capable of clearing notifications. - -If the user has both `m.read` and `m.read.private` set in the room then -the receipt which is more recent/ahead must be used to determine where -the user has read up to. For example, given an oldest-first set of events A, -B, C, and D the `m.read` receipt could be at event C and `m.read.private` -at event A - the user is considered to have read up to event C. If the -`m.read.private` receipt is then updated to point to B or C, the user's -notification state doesn't change (the `m.read` receipt is still more -ahead), however if the `m.read.private` receipt were to be updated to -event D then the user has read up to D (the `m.read` receipt is now -behind the `m.read.private` receipt). - -{{< added-in v="1.4" >}} When handling threaded read receipts, the server -is to partition the notification count to each thread (with the main timeline -being its own thread). To determine if an event is part of a thread the -server follows the [event relationship](#forming-relationships-between-events) -until it finds a thread root (as specified by the [threading module](#threading)), -however it is not recommended that the server traverse infinitely. Instead, -implementations are encouraged to do a maximum of 3 hops to find a thread -before deciding that the event does not belong to a thread. This is primarily -to ensure that future events, like `m.reaction`, are correctly considered -"part of" a given thread. - -##### Push Rules +#### Push Rules A push rule is a single rule that states under what *conditions* an event should be passed onto a push gateway and *how* the notification @@ -153,8 +102,8 @@ The different `kind`s of rule, in the order that they are checked, are: The highest priority rules are user-configured overrides. 1. **Content-specific rules (`content`).** - These configure behaviour for (unencrypted) messages that match certain - patterns. Content rules take one parameter: `pattern`, that gives the + These configure behaviour for messages that match certain patterns. Content + rules take one parameter: `pattern`, that gives the [glob-style pattern](/appendices#glob-style-matching) to match against. The match is performed case-insensitively, and must match any substring of the `content.body` property which starts and ends at a word boundary. A word @@ -188,7 +137,7 @@ rules match an event, the homeserver MUST NOT notify the Push Gateway for that event. Homeservers MUST NOT notify the Push Gateway for events that the user has sent themselves. -###### Actions +##### Actions All rules have an associated list of `actions`. An action affects if and how a notification is delivered for a matching event. The following @@ -246,7 +195,7 @@ they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. `{ "set_tweak": "sound", "value": "default" }`. -###### Conditions +##### Conditions `override` and `underride` rules MAY have a list of 'conditions'. All conditions must hold true for an event in order for the rule to match. A @@ -346,10 +295,10 @@ For an example of this, see the default rule **`contains_display_name`** -This matches unencrypted messages where `content.body` contains the -owner's display name in that room. This is a separate rule because -display names may change and as such it would be hard to maintain a rule -that matched the user's display name. This condition has no parameters. +This matches messages where `content.body` contains the owner's display name in +that room. This is a separate condition because display names may change and as such +it would be hard to maintain a rule that matched the user's display name. This +condition has no parameters. **`room_member_count`** @@ -375,7 +324,7 @@ Parameters: to look up the power level required to send a notification type from the `notifications` object in the power level event content. -##### Predefined Rules +#### Predefined Rules Homeservers can specify "server-default rules". They operate at a lower priority than "user-defined rules", except for the `.m.rule.master` rule @@ -384,7 +333,7 @@ for all server-default rules MUST start with a dot (".") to identify them as "server-default". The following server-default rules are specified: -###### Default Override Rules +##### Default Override Rules **`.m.rule.master`** @@ -495,8 +444,8 @@ Definition: **`.m.rule.contains_display_name`** -Matches any message whose content is unencrypted and contains the user's -current display name in the room in which it was sent. +Matches any message whose content contains the user's current display name +in the room in which it was sent. Definition: @@ -525,8 +474,9 @@ Definition: **`.m.rule.roomnotif`** -Matches any message whose content is unencrypted and contains the text -`@room`, signifying the whole room should be notified of the event. +Matches any message from a sender with the proper power level whose content +contains the text `@room`, signifying the whole room should be notified of +the event. Definition: @@ -618,12 +568,12 @@ Definition: } ``` -###### Default Content Rules +##### Default Content Rules **`.m.rule.contains_user_name`** -Matches any message whose content is unencrypted and contains the local -part of the user's Matrix ID, separated by word boundaries. +Matches any message whose content contains the local part of the user's +Matrix ID, separated by word boundaries. Definition (as a `content` rule): @@ -646,7 +596,7 @@ Definition (as a `content` rule): } ``` -###### Default Underride Rules +##### Default Underride Rules **`.m.rule.call`** @@ -795,14 +745,14 @@ Definition: } ``` -##### Push Rules: API +#### Push Rules: API Clients can retrieve, add, modify and remove push rules globally or per-device using the APIs below. {{% http-api spec="client-server" api="pushrules" %}} -##### Push Rules: Events +#### Push Rules: Events When a user changes their push rules a `m.push_rules` event is sent to all clients in the `account_data` section of their next [`/sync`](#get_matrixclientv3sync) request. @@ -810,7 +760,7 @@ The content of the event is the current push rules for the user. {{% event event="m.push_rules" %}} -###### Examples +##### Examples To create a rule that suppresses notifications for the room with ID `!dj234r78wl45Gh4D:matrix.org`: @@ -861,8 +811,76 @@ than the room, sender and content rules): ] }' + +#### Client behaviour + +Clients MUST configure a Pusher before they will receive push +notifications. There is a single API endpoint for this, as described +below. + +{{% http-api spec="client-server" api="pusher" %}} + +##### Listing Notifications + +A client can retrieve a list of events that it has been notified about. +This may be useful so that users can see a summary of what important +messages they have received. + +{{% http-api spec="client-server" api="notifications" %}} + +##### Receiving notifications + +Servers MUST include the number of unread notifications in a client's +`/sync` stream, and MUST update it as it changes. Notifications are +determined by the push rules which apply to an event. + +For encrypted events, the homeserver has limited access to the event content +and properly processing push rules falls on the client. Clients should process +push rules for each incoming event *after decrypting* them. This may result in +needing to modify the number of unread notifications received from the homeserver. + +##### Marking notifications as read + +When the user updates their read receipt (either by using the API or by +sending an event), notifications prior to and including that event MUST +be marked as read. Which specific events are affected can vary depending +on whether a [threaded read receipt](#threaded-read-receipts) was used. +Note that users can send both an `m.read` and `m.read.private` receipt, +both of which are capable of clearing notifications. + +If the user has both `m.read` and `m.read.private` set in the room then +the receipt which is more recent/ahead must be used to determine where +the user has read up to. For example, given an oldest-first set of events A, +B, C, and D the `m.read` receipt could be at event C and `m.read.private` +at event A - the user is considered to have read up to event C. If the +`m.read.private` receipt is then updated to point to B or C, the user's +notification state doesn't change (the `m.read` receipt is still more +ahead), however if the `m.read.private` receipt were to be updated to +event D then the user has read up to D (the `m.read` receipt is now +behind the `m.read.private` receipt). + +{{< added-in v="1.4" >}} When handling threaded read receipts, the server +is to partition the notification count to each thread (with the main timeline +being its own thread). To determine if an event is part of a thread the +server follows the [event relationship](#forming-relationships-between-events) +until it finds a thread root (as specified by the [threading module](#threading)), +however it is not recommended that the server traverse infinitely. Instead, +implementations are encouraged to do a maximum of 3 hops to find a thread +before deciding that the event does not belong to a thread. This is primarily +to ensure that future events, like `m.reaction`, are correctly considered +"part of" a given thread. + #### Server behaviour +When receiving a new event homeservers process push rules for each of the local +users in the room (excluding the sender). This may result in: + +* Generating a new number of unread notifications for the user. +* Making a request to the configured push gateway. + +The updated notification count from a new event MUST appear in the same `/sync` +response as the event itself. + #### Push Gateway behaviour ##### Recommendations for APNS From 35f5439e00bb6fb2f6338b92bf2063c4bc0e72b1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 14 Mar 2023 15:43:44 +0000 Subject: [PATCH 28/32] Correct a small typo in the push rules spec (#1465 --- changelogs/client_server/newsfragments/1465.clarifications | 1 + content/client-server-api/modules/push.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1465.clarifications diff --git a/changelogs/client_server/newsfragments/1465.clarifications b/changelogs/client_server/newsfragments/1465.clarifications new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/1465.clarifications @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 7667dd7a..d5056119 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -249,7 +249,7 @@ Other `topic` values which will match are: * `"LUNCH"` (case-insensitive; `*` may match zero characters) -The following `membership` values will NOT match: +The following `topic` values will NOT match: * `" lunch"` (note leading space) * `"lunc"` (`?` must match a character) * `null` (not a string) From 09e2250a8d27d8fd49662710bfb8799b90449e66 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 14 Mar 2023 20:27:42 +0000 Subject: [PATCH 29/32] Spec implicit filter event limit (#1463) Signed-off-by: Stuart Mumford --- changelogs/client_server/newsfragments/1463.clarification | 1 + data/api/client-server/definitions/event_filter.yaml | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1463.clarification diff --git a/changelogs/client_server/newsfragments/1463.clarification b/changelogs/client_server/newsfragments/1463.clarification new file mode 100644 index 00000000..1cf431ee --- /dev/null +++ b/changelogs/client_server/newsfragments/1463.clarification @@ -0,0 +1 @@ +Clarify that servers should enforce a default `limit` on a filter if one is not specified. diff --git a/data/api/client-server/definitions/event_filter.yaml b/data/api/client-server/definitions/event_filter.yaml index b6888693..d03c85da 100644 --- a/data/api/client-server/definitions/event_filter.yaml +++ b/data/api/client-server/definitions/event_filter.yaml @@ -14,7 +14,11 @@ title: EventFilter properties: limit: - description: The maximum number of events to return. + description: | + The maximum number of events to return, must be an integer greater than 0. + + Servers should apply a default value, and impose a maximum value to avoid + resource exhaustion. type: integer not_senders: description: A list of sender IDs to exclude. If this list is absent then no senders From bdc87784a1ee66e647518b928dc582b02d810f57 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 14 Mar 2023 20:32:38 +0000 Subject: [PATCH 30/32] Clarify that Persistent data unit is PDU (#1466) Signed-off-by: Stuart Mumford --- changelogs/server_server/newsfragments/1466.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1466.clarification diff --git a/changelogs/server_server/newsfragments/1466.clarification b/changelogs/server_server/newsfragments/1466.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1466.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index ff14bd04..c77b179f 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -18,7 +18,7 @@ signatures in HTTP Authorization headers at the HTTP layer. There are three main kinds of communication that occur between homeservers: -Persisted Data Units (PDUs): +Persistent Data Units (PDUs): These events are broadcast from one homeserver to any others that have joined the same room (identified by Room ID). They are persisted in long-term storage and record the history of messages and state for a From acb631d3d6879eb77a56fae1f55238f5b69088c2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 21 Mar 2023 15:59:23 +0000 Subject: [PATCH 31/32] Change the server aggregation for edits (#1440) per matrix-org/matrix-spec-proposals#3925 --- .../client_server/newsfragments/1440.feature | 1 + .../modules/event_replacements.md | 74 ++++++++++--------- 2 files changed, 42 insertions(+), 33 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1440.feature diff --git a/changelogs/client_server/newsfragments/1440.feature b/changelogs/client_server/newsfragments/1440.feature new file mode 100644 index 00000000..119ab2d6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1440.feature @@ -0,0 +1 @@ +Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index a4257fc3..a50ba830 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -133,13 +133,6 @@ being overwritten entirely by `m.new_content`, with the exception of `m.relates_ which is left *unchanged*. Any `m.relates_to` property within `m.new_content` is ignored. -{{% boxes/note %}} -Note that server implementations must not *actually* overwrite -the original event's `content`: instead the server presents it as being overwritten -when it is served over the client-server API. See [Server-side replacement of content](#server-side-replacement-of-content) -below. -{{% /boxes/note %}} - For example, given a pair of events: ```json @@ -195,14 +188,17 @@ replacement event. ##### Server-side aggregation of `m.replace` relationships +{{< changed-in v="1.7" >}} + Note that there can be multiple events with an `m.replace` relationship to a given event (for example, if an event is edited multiple times). These should be [aggregated](#aggregations) by the homeserver. -The aggregation format of `m.replace` relationships gives the `event_id`, -`origin_server_ts`, and `sender` of the **most recent** replacement event. The -most recent event is determined by comparing `origin_server_ts`; if two or more -replacement events have identical `origin_server_ts`, the event with the +The aggregation format of `m.replace` relationships gives the **most recent** +replacement event, formatted [as normal](#room-event-format). + +The most recent event is determined by comparing `origin_server_ts`; if two or +more replacement events have identical `origin_server_ts`, the event with the lexicographically largest `event_id` is treated as more recent. This aggregation is bundled under the `unsigned` property as `m.relations` for any @@ -211,49 +207,61 @@ event that is the target of an `m.replace` relationship. For example: ```json { "event_id": "$original_event_id", - // irrelevant fields not shown + "type": "m.room.message", + "content": { + "body": "I really like cake", + "msgtype": "m.text", + "formatted_body": "I really like cake" + }, "unsigned": { "m.relations": { "m.replace": { "event_id": "$latest_edit_event_id", "origin_server_ts": 1649772304313, "sender": "@editing_user:localhost" + "type": "m.room.message", + "content": { + "body": "* I really like *chocolate* cake", + "msgtype": "m.text", + "m.new_content": { + "body": "I really like *chocolate* cake", + "msgtype": "m.text" + }, + "m.relates_to": { + "rel_type": "m.replace", + "event_id": "$original_event_id" + } + } } } } + // irrelevant fields not shown } ``` -If the original event is -[redacted](#redactions), any +If the original event is [redacted](#redactions), any `m.replace` relationship should **not** be bundled with it (whether or not any subsequent replacements are themselves redacted). Note that this behaviour is specific to the `m.replace` relationship. See also [redactions of edited events](#redactions-of-edited-events) below. -##### Server-side replacement of content +**Note:** the `content` of the original event is left intact. In particular servers +should **not** replace the content with that of the replacement event. -Whenever an `m.replace` is to be bundled with an event as above, the server -should also modify the content of the original event according to the -`m.new_content` of the most recent replacement event (determined as above). - -An exception applies to [`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid), -which should return the unmodified event (though the relationship should still -be bundled, as described above). +{{ boxes/rationale }} +In previous versions of the specification, servers were expected to replace the +content of an edited event whenever it was served to clients (with the +exception of the +[`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid) +endpoint). However, that behaviour made reliable client-side implementation +difficult, and servers should no longer make this replacement. +{{ /boxes/rationale }} #### Client behaviour -Clients can often ignore `m.replace` events, because any events returned -by the server to the client will be updated by the server to account for -subsequent edits. - -However, clients should apply the replacement themselves when the server is -unable to do so. This happens in the following situations: - - * The client has already received and stored the original event before the - message edit event arrives. - - * The original event (and hence its replacement) are encrypted. +Since the server will not replace the content of any edited events, clients +should take note of any replacement events they receive, and apply the +replacement whenever possible and appropriate. Client authors are reminded to take note of the requirements for [Validity of replacement events](#validity-of-replacement-events), and to ignore any From d6f38f157da94b2db2b5a8d88cd2758fd4e49778 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 21 Mar 2023 16:27:54 +0000 Subject: [PATCH 32/32] Add a sentence about what canonical JSON is (#1468) Signed-off-by: Stuart Mumford --- changelogs/appendices/newsfragments/1468.clarification | 1 + content/appendices.md | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 changelogs/appendices/newsfragments/1468.clarification diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification new file mode 100644 index 00000000..6f8ab86f --- /dev/null +++ b/changelogs/appendices/newsfragments/1468.clarification @@ -0,0 +1 @@ +Clarify that the term "Canonical JSON" is a specific thing within the matrix specification. diff --git a/content/appendices.md b/content/appendices.md index dc3ced66..446e709a 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -83,7 +83,11 @@ object. ### Canonical JSON -We define the canonical JSON encoding for a value to be the shortest +To ensure that all implementations use the same JSON encoding we define +"Canonical JSON". This should not be confused with other uses of +"Canonical JSON" outside of the specification. + +We define this encoding for a value to be the shortest UTF-8 JSON encoding with dictionary keys lexicographically sorted by Unicode codepoint. Numbers in the JSON must be integers in the range `[-(2**53)+1, (2**53)-1]`.