From cf6544c0282fd210bc3538c9732b88e39b0ab312 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 4 Jul 2022 20:19:33 +0100 Subject: [PATCH 01/13] Clarify that /invite will respond with 200 if the user is already invited to the room (#1084) * Clarify that /invite will respond with 200 if the user is already in the room * Create 1084.clarification * Update changelogs/client_server/newsfragments/1084.clarification Co-authored-by: Travis Ralston --- changelogs/client_server/newsfragments/1084.clarification | 1 + data/api/client-server/inviting.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1084.clarification diff --git a/changelogs/client_server/newsfragments/1084.clarification b/changelogs/client_server/newsfragments/1084.clarification new file mode 100644 index 00000000..c0d6e0f3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1084.clarification @@ -0,0 +1 @@ +Mention that the `/rooms/{roomId}/invite` endpoint will return a 200 response if the user is already invited to the room. diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 9beda8a0..c24e5f49 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -80,7 +80,7 @@ paths: required: ["user_id"] responses: 200: - description: The user has been invited to join the room. + description: The user has been invited to join the room, or was already invited to the room. examples: application/json: { } From cc7cc4a44d30aa55745848dc7542f4b605d8e76a Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 5 Jul 2022 16:46:46 +0100 Subject: [PATCH 02/13] Fix unintentional stateres change added in #1042 (#1158) * Fix unintentional stateres change added in #1042 * Changelog --- changelogs/room_versions/newsfragments/1158.clarification | 1 + content/rooms/fragments/v2-state-res.md | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1158.clarification diff --git a/changelogs/room_versions/newsfragments/1158.clarification b/changelogs/room_versions/newsfragments/1158.clarification new file mode 100644 index 00000000..d4081aa2 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1158.clarification @@ -0,0 +1 @@ +For room versions 2–10: correct a mistaken clarification to the state resolution algorithm. diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index be650647..3a66f199 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -138,9 +138,11 @@ the auth event is not rejected. The *resolution* of a set of states is obtained as follows: -1. Select all *power events* that appear in the *full conflicted set*. Compute - the union of their auth chains, including the power events themselves. - Sort the union using the *reverse topological power ordering*. +1. Select the set *X* of all *power events* that appear in the *full + conflicted set*. For each such power event *P*, enlarge *X* by adding + the events in the auth chain of *P* which also belong to the full + conflicted set. Sort $X$ into a list using the *reverse topological + power ordering*. 2. Apply the *iterative auth checks algorithm*, starting from the *unconflicted state map*, to the list of events from the previous step to get a partially resolved state. From 848294ea377fa7140e05d486bcd9ba48a69b667a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 5 Jul 2022 21:58:41 +0100 Subject: [PATCH 03/13] events with rejected_auth_events must be rejected (#1137) This might be kinda obvious, but didn't seem to be spelt out anywhere. --- .../newsfragments/1137.clarification | 1 + content/rooms/fragments/v1-auth-rules.md | 39 ++++++++++--------- content/rooms/fragments/v3-auth-rules.md | 37 ++++++++++-------- content/rooms/fragments/v8-auth-rules.md | 35 +++++++++-------- content/rooms/v10.md | 35 +++++++++-------- 5 files changed, 80 insertions(+), 67 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1137.clarification diff --git a/changelogs/room_versions/newsfragments/1137.clarification b/changelogs/room_versions/newsfragments/1137.clarification new file mode 100644 index 00000000..b7c04045 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1137.clarification @@ -0,0 +1 @@ +For room versions 1 through 10, clarify that events with rejected `auth_events` must be rejected. diff --git a/content/rooms/fragments/v1-auth-rules.md b/content/rooms/fragments/v1-auth-rules.md index 3abc1ac2..242c7620 100644 --- a/content/rooms/fragments/v1-auth-rules.md +++ b/content/rooms/fragments/v1-auth-rules.md @@ -26,22 +26,25 @@ The rules are as follows: version, reject. 4. If `content` has no `creator` field, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. -4. If the create event content has the field `m.federate` set to `false` - and the sender domain of the event does not match the sender domain of - the create event, reject. -5. If type is `m.room.aliases`: + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. +4. If type is `m.room.aliases`: 1. If event has no `state_key`, reject. 2. If sender's domain doesn't matches `state_key`, reject. 3. Otherwise, allow. -6. If type is `m.room.member`: +5. If type is `m.room.member`: 1. If no `state_key` key or `membership` key in `content`, reject. 2. If `membership` is `join`: 1. If the only previous event is an `m.room.create` and the @@ -98,15 +101,15 @@ The rules are as follows: than the `sender`'s power level, allow. 3. Otherwise, reject. 6. Otherwise, the membership is unknown. Reject. -7. If the `sender`'s current membership state is not `join`, reject. -8. If type is `m.room.third_party_invite`: +6. If the `sender`'s current membership state is not `join`, reject. +7. If type is `m.room.third_party_invite`: 1. Allow if and only if `sender`'s current power level is greater than or equal to the *invite level*. -9. If the event type's *required power level* is greater than the +8. If the event type's *required power level* is greater than the `sender`'s power level, reject. -10. If the event has a `state_key` that starts with an `@` and does not +9. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. -11. If type is `m.room.power_levels`: +10. If type is `m.room.power_levels`: 1. If `users` key in `content` is not a dictionary with keys that are valid user IDs with values that are integers (or a string that is an integer), reject. @@ -130,14 +133,14 @@ The rules are as follows: 1. If the current value is equal to the `sender`'s current power level, reject. 6. Otherwise, allow. -12. If type is `m.room.redaction`: +11. If type is `m.room.redaction`: 1. If the `sender`'s power level is greater than or equal to the *redact level*, allow. 2. If the domain of the `event_id` of the event being redacted is the same as the domain of the `event_id` of the `m.room.redaction`, allow. 3. Otherwise, reject. -13. Otherwise, allow. +12. Otherwise, allow. {{% boxes/note %}} Some consequences of these rules: diff --git a/content/rooms/fragments/v3-auth-rules.md b/content/rooms/fragments/v3-auth-rules.md index 4c238fa2..d5da48c5 100644 --- a/content/rooms/fragments/v3-auth-rules.md +++ b/content/rooms/fragments/v3-auth-rules.md @@ -33,22 +33,25 @@ The complete list of rules, as of room version 3, is as follows: version, reject. 4. If `content` has no `creator` field, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. -4. If the create event content has the field `m.federate` set to `false` - and the sender domain of the event does not match the sender domain of - the create event, reject. -5. If type is `m.room.aliases`: + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. +4. If type is `m.room.aliases`: 1. If event has no `state_key`, reject. 2. If sender's domain doesn't matches `state_key`, reject. 3. Otherwise, allow. -6. If type is `m.room.member`: +5. If type is `m.room.member`: 1. If no `state_key` key or `membership` key in `content`, reject. 2. If `membership` is `join`: 1. If the only previous event is an `m.room.create` and the @@ -105,15 +108,15 @@ The complete list of rules, as of room version 3, is as follows: than the `sender`'s power level, allow. 3. Otherwise, reject. 6. Otherwise, the membership is unknown. Reject. -7. If the `sender`'s current membership state is not `join`, reject. -8. If type is `m.room.third_party_invite`: +6. If the `sender`'s current membership state is not `join`, reject. +7. If type is `m.room.third_party_invite`: 1. Allow if and only if `sender`'s current power level is greater than or equal to the *invite level*. -9. If the event type's *required power level* is greater than the +8. If the event type's *required power level* is greater than the `sender`'s power level, reject. -10. If the event has a `state_key` that starts with an `@` and does not +9. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. -11. If type is `m.room.power_levels`: +10. If type is `m.room.power_levels`: 1. If `users` key in `content` is not a dictionary with keys that are valid user IDs with values that are integers (or a string that is an integer), reject. @@ -137,7 +140,7 @@ The complete list of rules, as of room version 3, is as follows: 1. If the current value is equal to the `sender`'s current power level, reject. 6. Otherwise, allow. -12. Otherwise, allow. +11. Otherwise, allow. {{% boxes/note %}} Some consequences of these rules: diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md index 33813a86..ac067884 100644 --- a/content/rooms/fragments/v8-auth-rules.md +++ b/content/rooms/fragments/v8-auth-rules.md @@ -34,18 +34,21 @@ The rules are as follows: version, reject. 4. If `content` has no `creator` field, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. -4. If the create event content has the field `m.federate` set to `false` - and the sender domain of the event does not match the sender domain of - the create event, reject. -5. If type is `m.room.member`: + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. +4. If type is `m.room.member`: 1. If no `state_key` key or `membership` key in `content`, reject. 2. If `content` has a `join_authorised_via_users_server` key: @@ -119,15 +122,15 @@ The rules are as follows: or `join`, allow. 4. Otherwise, reject. 8. Otherwise, the membership is unknown. Reject. -6. If the `sender`'s current membership state is not `join`, reject. -7. If type is `m.room.third_party_invite`: +5. If the `sender`'s current membership state is not `join`, reject. +6. If type is `m.room.third_party_invite`: 1. Allow if and only if `sender`'s current power level is greater than or equal to the *invite level*. -8. If the event type's *required power level* is greater than the +7. If the event type's *required power level* is greater than the `sender`'s power level, reject. -9. If the event has a `state_key` that starts with an `@` and does not +8. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. -10. If type is `m.room.power_levels`: +9. If type is `m.room.power_levels`: 1. If `users` key in `content` is not a dictionary with keys that are valid user IDs with values that are integers (or a string that is an integer), reject. @@ -151,7 +154,7 @@ The rules are as follows: 1. If the current value is equal to the `sender`'s current power level, reject. 6. Otherwise, allow. -11. Otherwise, allow. +10. Otherwise, allow. {{% boxes/note %}} Some consequences of these rules: diff --git a/content/rooms/v10.md b/content/rooms/v10.md index 86ef7dc4..b4c20653 100644 --- a/content/rooms/v10.md +++ b/content/rooms/v10.md @@ -106,18 +106,21 @@ The rules are as follows: version, reject. 4. If `content` has no `creator` field, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. -4. If the create event content has the field `m.federate` set to `false` - and the sender domain of the event does not match the sender domain of - the create event, reject. -5. If type is `m.room.member`: + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. +4. If type is `m.room.member`: 1. If no `state_key` key or `membership` key in `content`, reject. 2. If `content` has a `join_authorised_via_users_server` key: @@ -194,15 +197,15 @@ The rules are as follows: or `join`, allow. 4. Otherwise, reject. 8. Otherwise, the membership is unknown. Reject. -6. If the `sender`'s current membership state is not `join`, reject. -7. If type is `m.room.third_party_invite`: +5. If the `sender`'s current membership state is not `join`, reject. +6. If type is `m.room.third_party_invite`: 1. Allow if and only if `sender`'s current power level is greater than or equal to the *invite level*. -8. If the event type's *required power level* is greater than the +7. If the event type's *required power level* is greater than the `sender`'s power level, reject. -9. If the event has a `state_key` that starts with an `@` and does not +8. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. -10. If type is `m.room.power_levels`: +9. If type is `m.room.power_levels`: 1. {{< added-in this="true" >}} If any of the keys `users_default`, `events_default`, `state_default`, `ban`, `redact`, `kick`, or `invite` in `content` are present and @@ -233,7 +236,7 @@ The rules are as follows: 1. If the current value is equal to the `sender`'s current power level, reject. 6. Otherwise, allow. -11. Otherwise, allow. +10. Otherwise, allow. {{% boxes/note %}} Some consequences of these rules: From 8d45231c649247ac9d60afc723bad210f701ec55 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 7 Jul 2022 11:25:26 +0100 Subject: [PATCH 04/13] fix the olm algorithm name in an example --- data/api/client-server/cross_signing.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 603d88fd..b88da999 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -168,7 +168,7 @@ paths: "user_id": "@alice:example.com", "device_id": "HIJKLMN", "algorithms": [ - "m.olm.curve25519-aes-sha256", + "m.olm.v1.curve25519-aes-sha256", "m.megolm.v1.aes-sha" ], "keys": { From 577eb5db5940c84309a07700f24bfcf083e06733 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 7 Jul 2022 11:28:38 +0100 Subject: [PATCH 05/13] add changelog --- changelogs/client_server/newsfragments/1164.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1164.clarification diff --git a/changelogs/client_server/newsfragments/1164.clarification b/changelogs/client_server/newsfragments/1164.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1164.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. From 5bf35327c67e84779fb22e0ed301e9fe3e9b6081 Mon Sep 17 00:00:00 2001 From: "DeepBlueV7.X" Date: Mon, 11 Jul 2022 19:58:27 +0000 Subject: [PATCH 06/13] Fix wording for globs in policy lists (#1165) * Fix wording for globs in policy lists The specification here does neither match how globs work in common libraries nor do they match how they are used in practice currently or how the MSC worded them (which said they should be like server ACLs). As such this seems to be an issue introduced when writing the spec text. Ref mjolnir: - https://github.com/matrix-org/mjolnir/blob/b48904bc2b4fcd636176b12dbe173ad651930f23/src/models/ListRule.ts#L44 Ref matrix bot sdk (which implements the glob used above): - https://github.com/turt2live/matrix-bot-sdk/blob/473e563236dd6edb25e7bd18d3517d1a61e037a1/src/helpers/MatrixGlob.ts#L26 - https://github.com/turt2live/matrix-bot-sdk/blob/f799b1fe1a72b9a4a6053c50cedfb43bee962558/test/helpers/MatrixGlobTest.ts#L44 Ref original MSC: - https://github.com/matrix-org/matrix-spec-proposals/blob/c7b3d998537d21694a166b4a6a4cf0490ebc0cc2/proposals/2313-moderation-policy-rooms.md?plain=1#L36 - https://spec.matrix.org/v1.3/client-server-api/#server-access-control-lists-acls-for-rooms fixes https://github.com/matrix-org/matrix-spec/issues/17 Signed-off-by: Nicolas Werner * Add changelog Signed-off-by: Nicolas Werner --- changelogs/client_server/newsfragments/1165.clarification | 1 + content/client-server-api/modules/moderation_policies.md | 2 +- data/event-schemas/moderation_policy_rule.yaml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1165.clarification diff --git a/changelogs/client_server/newsfragments/1165.clarification b/changelogs/client_server/newsfragments/1165.clarification new file mode 100644 index 00000000..0cf092bb --- /dev/null +++ b/changelogs/client_server/newsfragments/1165.clarification @@ -0,0 +1 @@ +Clarify that policy rule globs work like ACL globs. Contributed by Nico. diff --git a/content/client-server-api/modules/moderation_policies.md b/content/client-server-api/modules/moderation_policies.md index 911d1a1c..027edd5d 100644 --- a/content/client-server-api/modules/moderation_policies.md +++ b/content/client-server-api/modules/moderation_policies.md @@ -91,7 +91,7 @@ included in the ban list. #### Events The `entity` described by the state events can contain `*` and `?` to -match zero or more and one or more characters respectively. Note that +match zero or more characters and exactly one character respectively. 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/data/event-schemas/moderation_policy_rule.yaml b/data/event-schemas/moderation_policy_rule.yaml index a57a1ffe..c7a4a22c 100644 --- a/data/event-schemas/moderation_policy_rule.yaml +++ b/data/event-schemas/moderation_policy_rule.yaml @@ -15,7 +15,7 @@ properties: entity: description: |- The entity affected by this rule. Glob characters `*` and `?` can be used - to match zero or more and one or more characters respectively. + to match zero or more characters or exactly one character respectively. type: string recommendation: description: The suggested action to take. Currently only `m.ban` is specified. From adaef611dcbf68363b461774e1e16b9d02886715 Mon Sep 17 00:00:00 2001 From: David Florness Date: Tue, 12 Jul 2022 11:39:37 -0500 Subject: [PATCH 07/13] Fix typo (#1161) Signed-off-by: David Florness --- changelogs/client_server/newsfragments/1161.clarification | 1 + content/client-server-api/modules/end_to_end_encryption.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1161.clarification diff --git a/changelogs/client_server/newsfragments/1161.clarification b/changelogs/client_server/newsfragments/1161.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1161.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. 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 c7db35aa..8875e57a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1220,7 +1220,7 @@ replace it with the new key based on the key metadata as follows: keep the key that has `is_verified` set to `true`; - if they have the same values for `is_verified`, then it will keep the key with a lower `first_message_index`; -- and finally, is `is_verified` and `first_message_index` are equal, +- and finally, if `is_verified` and `first_message_index` are equal, then it will keep the key with a lower `forwarded_count`. ###### Recovery key From ead437578b7c0bff4911719afac40c87722a44e3 Mon Sep 17 00:00:00 2001 From: Brad Murray Date: Tue, 12 Jul 2022 12:59:44 -0400 Subject: [PATCH 08/13] Fix typo in m.secret.request device event name (#1135) * Fix typo in m.secret.request device event name I don't think this is supposed to be plural according to the various SDKs * Add changelog * Update changelogs/client_server/newsfragments/1135.clarification * Update changelogs/client_server/newsfragments/1135.clarification Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Travis Ralston --- changelogs/client_server/newsfragments/1135.clarification | 1 + content/client-server-api/modules/secrets.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1135.clarification diff --git a/changelogs/client_server/newsfragments/1135.clarification b/changelogs/client_server/newsfragments/1135.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1135.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index 17b515c7..47de938a 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -276,7 +276,7 @@ Example: #### Sharing To request a secret from other devices, a client sends an -`m.secret.requests` device event with `action` set to `request` and +`m.secret.request` device event with `action` set to `request` and `name` set to the identifier of the secret. A device that wishes to share the secret will reply with an `m.secret.send` event, encrypted using olm. When the original client obtains the secret, it sends an From 56400ab9a02d70c28d45c510c2dfb153620349d1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 13 Jul 2022 12:43:37 -0600 Subject: [PATCH 09/13] Add missing "added in" spec version to some key backup endpoints (#1170) * Add missing version to some key backup endpoints * Create 1170.clarification --- .../client_server/newsfragments/1170.clarification | 1 + data/api/client-server/key_backup.yaml | 11 +++++++++++ 2 files changed, 12 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1170.clarification diff --git a/changelogs/client_server/newsfragments/1170.clarification b/changelogs/client_server/newsfragments/1170.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1170.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 0b438b9e..0622d761 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -86,6 +86,7 @@ paths: tags: - End-to-end encryption get: + x-addedInMatrixVersion: "1.1" summary: Get information about the latest backup version. description: |- Get information about the latest backup version. @@ -241,6 +242,7 @@ paths: tags: - End-to-end encryption put: + x-addedInMatrixVersion: "1.1" summary: Update information about an existing backup. description: |- Update information about an existing backup. Only `auth_data` can be modified. @@ -330,6 +332,7 @@ paths: tags: - End-to-end encryption delete: + x-addedInMatrixVersion: "1.1" summary: Delete an existing key backup. description: |- Delete an existing key backup. Both the information about the backup, @@ -375,6 +378,7 @@ paths: - End-to-end encryption "/room_keys/keys/{roomId}/{sessionId}": put: + x-addedInMatrixVersion: "1.1" summary: Store a key in the backup. description: |- Store a key in the backup. @@ -447,6 +451,7 @@ paths: tags: - End-to-end encryption get: + x-addedInMatrixVersion: "1.1" summary: Retrieve a key from the backup. description: |- Retrieve a key from the backup. @@ -494,6 +499,7 @@ paths: tags: - End-to-end encryption delete: + x-addedInMatrixVersion: "1.1" summary: Delete a key from the backup. description: |- Delete a key from the backup. @@ -558,6 +564,7 @@ paths: - End-to-end encryption "/room_keys/keys/{roomId}": put: + x-addedInMatrixVersion: "1.1" summary: Store several keys in the backup for a given room. description: |- Store several keys in the backup for a given room. @@ -634,6 +641,7 @@ paths: tags: - End-to-end encryption get: + x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup for a given room. description: |- Retrieve the keys from the backup for a given room. @@ -679,6 +687,7 @@ paths: tags: - End-to-end encryption delete: + x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup for a given room. description: |- Delete the keys from the backup for a given room. @@ -834,6 +843,7 @@ paths: tags: - End-to-end encryption get: + x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup. description: |- Retrieve the keys from the backup. @@ -897,6 +907,7 @@ paths: tags: - End-to-end encryption delete: + x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup. description: |- Delete the keys from the backup. From f9028acf8e95ae93a140db17141e64b20b7e2afa Mon Sep 17 00:00:00 2001 From: David Robertson Date: Thu, 14 Jul 2022 13:01:56 +0100 Subject: [PATCH 10/13] Describe return codes for account data endpoints + minor clarifications (#1155) --- .../newsfragments/1155.clarification | 1 + .../client-server-api/modules/account_data.md | 7 +- data/api/client-server/account-data.yaml | 123 +++++++++++++++++- 3 files changed, 127 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1155.clarification diff --git a/changelogs/client_server/newsfragments/1155.clarification b/changelogs/client_server/newsfragments/1155.clarification new file mode 100644 index 00000000..08e9dd2f --- /dev/null +++ b/changelogs/client_server/newsfragments/1155.clarification @@ -0,0 +1 @@ +Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data. diff --git a/content/client-server-api/modules/account_data.md b/content/client-server-api/modules/account_data.md index 500e2bbb..2bb466f0 100644 --- a/content/client-server-api/modules/account_data.md +++ b/content/client-server-api/modules/account_data.md @@ -7,9 +7,12 @@ type: module Clients can store custom config data for their account on their homeserver. This account data will be synced between different devices and can persist across installations on a particular device. Users may -only view the account data for their own account +only view the account data for their own account. -The account\_data may be either global or scoped to a particular rooms. +The account data may be either global or scoped to a particular room. +There is no inheritance mechanism here: a given `type` of data missing +from a room's account data does not fall back to the global account +data with the same `type`. #### Events diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index f7e7993d..98bda9ee 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -71,6 +71,39 @@ paths: application/json: {} schema: type: object + 400: + description: |- + The request body is not a JSON object. Errcode: `M_BAD_JSON` + or `M_NOT_JSON`. + examples: + application/json: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: |- + The access token provided is not authorized to modify this user's account + data. Errcode: `M_FORBIDDEN`. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 405: + examples: + application/json: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } + description: |- + This `type` of account data is controlled by the server; it cannot be + modified by clients. Errcode: `M_BAD_JSON`. + schema: + $ref: "../client-server/definitions/errors/error.yaml" tags: - User data get: @@ -106,11 +139,33 @@ paths: type: object example: { "custom_account_data_key": "custom_config_value"} + 403: + description: |- + The access token provided is not authorized to retrieve this user's account + data. Errcode: `M_FORBIDDEN`. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: |- + No account data has been provided for this user with the given `type`. + Errcode: `M_NOT_FOUND`. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room account data not found." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" tags: - User data "/user/{userId}/rooms/{roomId}/account_data/{type}": put: - summary: Set some account_data for the user. + summary: Set some account_data for the user that is specific to a room. description: |- Set some account_data for the client on a given room. This config is only visible to the user that set the account_data. The config will be synced to @@ -159,10 +214,44 @@ paths: application/json: {} schema: type: object + 400: + description: |- + The request body is not a JSON object (errcode `M_BAD_JSON` or + `M_NOT_JSON`), or the given `roomID` is not a valid room ID + (errcode `M_INVALID_PARAM`). + examples: + application/json: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: |- + The access token provided is not authorized to modify this user's account + data. Errcode: `M_FORBIDDEN`. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 405: + description: |- + This `type` of account data is controlled by the server; it cannot be + modified by clients. Errcode: `M_BAD_JSON`. + examples: + application/json: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" tags: - User data get: - summary: Get some account_data for the user. + summary: Get some account_data for the user that is specific to a room. description: |- Get some account_data for the client on a given room. This config is only visible to the user that set the account_data. @@ -201,5 +290,35 @@ paths: type: object example: { "custom_account_data_key": "custom_config_value"} + 400: + description: |- + The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`. + examples: + application/json: { + "errcode": "M_INVALID_PARAM", + "error": "@notaroomid:example.org is not a valid room ID." + } + 403: + description: |- + The access token provided is not authorized to retrieve this user's account + data. Errcode: `M_FORBIDDEN`. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: |- + No account data has been provided for this user and this room with the + given `type`. Errcode: `M_NOT_FOUND`. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room account data not found." + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" tags: - User data From 16eb4cb9618ee64440001d1b4263176e760e49eb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 19 Jul 2022 13:11:53 -0600 Subject: [PATCH 11/13] Disable blank issue reporting (#1172) Folks who want to report a blank issue can still get at the form if they try hard enough, but in general everything should have a label to make triage easier. --- .github/ISSUE_TEMPLATE/config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml index 79bc995d..dc3bd0f4 100644 --- a/.github/ISSUE_TEMPLATE/config.yaml +++ b/.github/ISSUE_TEMPLATE/config.yaml @@ -1,4 +1,4 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - name: Matrix Spec Discussion url: "https://matrix.to/#/#matrix-spec:matrix.org" From 5f3b34448d1b4582c9533ccc28a8986dc722094d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 19 Jul 2022 20:25:30 +0100 Subject: [PATCH 12/13] Add HTML ids for object definitions in the formatted specification (#1174) * Remove redundant call to resolve-allof All of the callers to resolve-additional-types already call resolve-allof (or if not, they should), so this is redundant. * Update `resolve-additional-types` to take a dict I want to add more params to this, so first make it take a dict. * `render-object-table`: take a "title" rather than a "caption" ... which means we can use the result from resolve-additional-types directly. * render-object-table: support adding an anchor to generated tables. * resolve-additional-types: generate an id for each returned type * render-event: pass an anchor_base into resolve-additional-types This means that it will generate an anchor for each type, whihc will then be passed into render-object-table and used as an `id` for the table. * render-operation: pass an anchor_base into resolve-additional-types * newsfiles --- .../newsfragments/1174.clarification | 1 + .../newsfragments/1174.clarification | 1 + .../newsfragments/1174.clarification | 1 + .../newsfragments/1174.clarification | 1 + .../newsfragments/1174.clarification | 1 + layouts/partials/events/render-event.html | 5 ++- .../json-schema/resolve-additional-types.html | 43 ++++++++++++------- .../partials/openapi/render-object-table.html | 18 +++++--- .../partials/openapi/render-operation.html | 7 +-- .../partials/openapi/render-parameters.html | 2 +- layouts/partials/openapi/render-request.html | 6 ++- .../partials/openapi/render-responses.html | 6 ++- layouts/shortcodes/definition.html | 4 +- layouts/shortcodes/event-fields.html | 4 +- 14 files changed, 64 insertions(+), 36 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1174.clarification create mode 100644 changelogs/client_server/newsfragments/1174.clarification create mode 100644 changelogs/identity_service/newsfragments/1174.clarification create mode 100644 changelogs/push_gateway/newsfragments/1174.clarification create mode 100644 changelogs/server_server/newsfragments/1174.clarification diff --git a/changelogs/application_service/newsfragments/1174.clarification b/changelogs/application_service/newsfragments/1174.clarification new file mode 100644 index 00000000..9eef7945 --- /dev/null +++ b/changelogs/application_service/newsfragments/1174.clarification @@ -0,0 +1 @@ +Add HTML anchors for object definitions in the formatted specification. diff --git a/changelogs/client_server/newsfragments/1174.clarification b/changelogs/client_server/newsfragments/1174.clarification new file mode 100644 index 00000000..9eef7945 --- /dev/null +++ b/changelogs/client_server/newsfragments/1174.clarification @@ -0,0 +1 @@ +Add HTML anchors for object definitions in the formatted specification. diff --git a/changelogs/identity_service/newsfragments/1174.clarification b/changelogs/identity_service/newsfragments/1174.clarification new file mode 100644 index 00000000..9eef7945 --- /dev/null +++ b/changelogs/identity_service/newsfragments/1174.clarification @@ -0,0 +1 @@ +Add HTML anchors for object definitions in the formatted specification. diff --git a/changelogs/push_gateway/newsfragments/1174.clarification b/changelogs/push_gateway/newsfragments/1174.clarification new file mode 100644 index 00000000..9eef7945 --- /dev/null +++ b/changelogs/push_gateway/newsfragments/1174.clarification @@ -0,0 +1 @@ +Add HTML anchors for object definitions in the formatted specification. diff --git a/changelogs/server_server/newsfragments/1174.clarification b/changelogs/server_server/newsfragments/1174.clarification new file mode 100644 index 00000000..9eef7945 --- /dev/null +++ b/changelogs/server_server/newsfragments/1174.clarification @@ -0,0 +1 @@ +Add HTML anchors for object definitions in the formatted specification. diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 66e15db7..5e9f5c13 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -53,10 +53,11 @@

Content

-{{ $additional_types := partial "json-schema/resolve-additional-types" $event_data.properties.content }} +{{ $anchor_base := anchorize $event_name }} +{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $event_data.properties.content "anchor_base" $anchor_base) }} {{ range $additional_types }} - {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ partial "openapi/render-object-table" . }} {{end}}

Examples

diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index 26df52e5..63a15bee 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -1,25 +1,34 @@ {{/* - Finds and returns all nested objects, given: + Finds and returns all nested objects, given a dict containing: + * `schema`: a JSON schema object + * `anchor_base`: a prefix to add to the HTML anchors generated for each object. If nil, no anchors are generated. - * `this_object`: a JSON schema object + This template finds all nested objects inside `schema`. - Given a schema object, this template finds all nested objects under that - schema. + Assumes that "resolve-refs" and "resolve-allof" has already been called on the + input schema. - It "cleans" each object by copying only the parts of the objects that - the renderer needs, and adds the result to an array, `additional_objects`. - - Finally it returns the array of all the objects it found. + Returns an array of all the objects found. For each object, the following properties are returned: + * title + * properties + * required + * enum + * anchor: a string suitable for using as an html anchor for this object (if `anchor_base` was set, and the object has a title) Note that the returned array may contain duplicate objects. */}} -{{ $this_object := partial "json-schema/resolve-allof" . }} +{{ $this_object := .schema }} +{{ $anchor_base := .anchor_base }} {{ $additional_objects := slice }} {{ if eq $this_object.type "object" }} + {{/* give this object an anchor, if it has a name */}} + {{ if (and $anchor_base $this_object.title) }} + {{ $this_object = merge $this_object (dict "anchor" (printf "%s_%s" $anchor_base (anchorize $this_object.title))) }} + {{ end }} {{/* Add the object we were passed into the $additional_objects array @@ -34,7 +43,7 @@ {{ $additional_objects = $additional_objects | append (partial "clean-object" $this_object.additionalProperties) }} {{ range $key, $property := $this_object.additionalProperties.properties }} - {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects "anchor_base" $anchor_base) }} {{ end }} {{ end }} @@ -44,7 +53,7 @@ Add any nested objects referenced in this object's `properties` */}} {{ range $key, $property := $this_object.properties}} - {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects "anchor_base" $anchor_base) }} {{ end }} {{ end }} @@ -55,10 +64,10 @@ */}} {{ if reflect.IsSlice $this_object.items}} {{ range $this_object.items }} - {{ $additional_objects = partial "get-additional-objects" (dict "this_object" . "additional_objects" $additional_objects) }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" . "additional_objects" $additional_objects "anchor_base" $anchor_base) }} {{ end }} {{ else }} - {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $this_object.items "additional_objects" $additional_objects) }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $this_object.items "additional_objects" $additional_objects "anchor_base" $anchor_base) }} {{ end }} {{ end }} @@ -71,8 +80,12 @@ {{ define "partials/get-additional-objects" }} {{ $additional_objects := .additional_objects }} + /* although we expect resolve-allof to be called on the input, resolve-allof does not recurse into + * nested objects, so we have to call it again. + */ {{ $this_object := partial "json-schema/resolve-allof" .this_object }} - {{ $more_objects := partial "json-schema/resolve-additional-types" $this_object }} + + {{ $more_objects := partial "json-schema/resolve-additional-types" (dict "schema" $this_object "anchor_base" .anchor_base) }} {{/* As far as I know we don't have something like Array.concat(), so add them one at a time */}} @@ -88,5 +101,5 @@ but with (for example) different examples will be considered different. */}} {{ define "partials/clean-object" }} - {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum) }} + {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }} {{ end }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index e132af30..7de88071 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -2,23 +2,27 @@ Render a table listing the properties of an object, given: - * `caption`: optional caption for the table + * `title`: optional caption for the table + + * `anchor`: optional HTML element id for the table + * `properties`: dictionary of the properties to list, each given as: - `property_name` : `property_data` + `property_name` : `property_data` + * `required`: array containing the names of required properties. - In some cases (such as response body specifications) this isn't used, and - instead properties have a `required` boolean attribute. We support this too. + In some cases (such as response body specifications) this isn't used, and + instead properties have a `required` boolean attribute. We support this too. */}} -{{ $caption := .caption }} +{{ $title := .title }} {{ $properties := .properties}} {{ $required := .required}} {{ if $properties }} - - {{ with $caption }} + + {{ with $title }} {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 6d516d06..74b729cf 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -22,13 +22,14 @@ {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} {{ $path := .path }} +{{ $anchor := anchorize $endpoint }}
-

+

{{ $method }} {{ $endpoint }}

@@ -63,9 +64,9 @@
{{ . }}
-{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path) }} +{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path "anchor_base" $anchor ) }}
-{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path) }} +{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path "anchor_base" $anchor ) }} diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html index 2a36ea8d..b7861b7f 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -25,6 +25,6 @@ {{ end }} {{/* and render the parameters */}} - {{ partial "openapi/render-object-table" (dict "caption" $caption "properties" $param_dict) }} + {{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }} {{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5e801299..be39fa38 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -4,6 +4,7 @@ * `parameters`: OpenAPI/Swagger data specifying the parameters * `path`: the path where this definition was found, to enable us to resolve "$ref" + * `anchor_base`: a prefix to add to the HTML anchors generated for each object This template renders: * the "simple parameters" (header, path, query parameters) @@ -14,6 +15,7 @@ {{ $parameters := .parameters }} {{ $path := .path }} +{{ $anchor_base := .anchor_base }}

Request

@@ -38,10 +40,10 @@ {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-allof" $schema }} - {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} {{ $additional_types = uniq $additional_types }} {{ range $additional_types }} - {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ partial "openapi/render-object-table" . }} {{ end }}

Request body example

diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 79636945..c6556fbb 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -4,6 +4,7 @@ * `responses`: OpenAPI/Swagger data specifying the responses * `path`: the path where this definition was found, to enable us to resolve "$ref" + * `anchor_base`: a prefix to add to the HTML anchors generated for each object This template renders: * a summary of all the different responses @@ -15,6 +16,7 @@ {{ $responses := .responses }} {{ $path := .path }} +{{ $anchor_base := .anchor_base }}

Responses

@@ -71,10 +73,10 @@ response. (This will be a no-op for response types which aren't objects or arrays.) */}} - {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} {{ $additional_types = uniq $additional_types }} {{ range $additional_types }} - {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ partial "openapi/render-object-table" . }} {{ end }} {{/* diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 2e000c73..2828db48 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -45,11 +45,11 @@ -{{ $additional_types := partial "json-schema/resolve-additional-types" $definition }} +{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition) }} {{ $additional_types = uniq $additional_types }} {{ range $additional_types }} - {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ partial "openapi/render-object-table" . }} {{end}}

Examples

diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html index 83651c21..7120f87f 100644 --- a/layouts/shortcodes/event-fields.html +++ b/layouts/shortcodes/event-fields.html @@ -35,9 +35,9 @@ {{ $event = merge $event (dict "title" "") }} -{{ $additional_types := partial "json-schema/resolve-additional-types" $event }} +{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $event) }} {{ range $additional_types }} - {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ partial "openapi/render-object-table" . }} {{end}} From ea42cd3c7b40caae0b6925e1620173dd004e04a7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:02:48 +0100 Subject: [PATCH 13/13] Move various e2e defintions out to yaml files (#1166) We have code to generate tables, which we should use in the e2e section. --- assets/scss/custom.scss | 1 - .../newsfragments/1166.clarification | 1 + .../modules/end_to_end_encryption.md | 58 ++--------------- .../definitions/key_backup_auth_data.yaml | 36 +++++++++++ .../definitions/key_backup_session_data.yaml | 62 +++++++++++++++++++ .../megolm_export_session_data.yaml | 38 ++++++++++++ layouts/shortcodes/definition.html | 4 ++ 7 files changed, 147 insertions(+), 53 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1166.clarification create mode 100644 data/api/client-server/definitions/key_backup_auth_data.yaml create mode 100644 data/api/client-server/definitions/key_backup_session_data.yaml create mode 100644 data/api/client-server/definitions/megolm_export_session_data.yaml diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 35b4e3dc..8a5c0e58 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -323,7 +323,6 @@ footer { table { table-layout: fixed; width: 100%; - margin: 4rem 0; caption { caption-side: top; diff --git a/changelogs/client_server/newsfragments/1166.clarification b/changelogs/client_server/newsfragments/1166.clarification new file mode 100644 index 00000000..9db3e7c3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1166.clarification @@ -0,0 +1 @@ +Clarify the format of some structures in the End-to-end encryption module. 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 8875e57a..10f21e86 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1255,25 +1255,12 @@ When a backup is created with the `algorithm` set to `m.megolm_backup.v1.curve25519-aes-sha2`, the `auth_data` should have the following format: -`AuthData` - -| Parameter | Type | Description | -| -----------| -----------|--------------------------------------------------------------------------------------------------| -| public_key | string | **Required.** The curve25519 public key used to encrypt the backups, encoded in unpadded base64. | -| signatures | Signatures | Optional. Signatures of the ``auth_data``, as Signed JSON | +{{% definition path="api/client-server/definitions/key_backup_auth_data" %}} The `session_data` field in the backups is constructed as follows: -1. Encode the session key to be backed up as a JSON object with the - properties: - -| Parameter | Type | Description | -| --------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| algorithm | string | **Required.** The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`. | -| forwarding_curve25519_key_chain | [string] | **Required.** Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. | -| sender_key | string | **Required.** Unpadded base64-encoded device curve25519 key. | -| sender_claimed_keys | {string: string} | **Required.** A map from algorithm name (`ed25519`) to the identity key for the sending device. | -| session_key | string | **Required.** Unpadded base64-encoded session key in [session-sharing format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-sharing-format). | +1. Encode the session key to be backed up as a JSON object using the + `SessionData` format defined below. 2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral key and the backup's public key to generate a shared @@ -1295,6 +1282,8 @@ The `session_data` field in the backups is constructed as follows: the resulting MAC are base64-encoded, and become the `mac` property of the `session_data`. +{{% definition path="api/client-server/definitions/key_backup_session_data" %}} + {{% http-api spec="client-server" api="key_backup" %}} ##### Key exports @@ -1344,42 +1333,7 @@ user-supplied passphrase, and is created as follows: The exported sessions are formatted as a JSON array of `SessionData` objects described as follows: -`SessionData` - -| Parameter | Type | Description | -|-----------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| algorithm | string | Required. The encryption algorithm that the session uses. Must be `m.megolm.v1.aes-sha2`. | -| forwarding_curve25519_key_chain | [string] | Required. Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. | -| room_id | string | Required. The room where the session is used. | -| sender_key | string | Required. The Curve25519 key of the device which initiated the session originally. | -| sender_claimed_keys | {string: string} | Required. The Ed25519 key of the device which initiated the session originally. | -| session_id | string | Required. The ID of the session. | -| session_key | string | Required. The key for the session. | - -This is similar to the format before encryption used for the session -keys in [Server-side key backups](#server-side-key-backups) but adds the -`room_id` and `session_id` fields. - -Example: - -``` -[ - { - "algorithm": "m.megolm.v1.aes-sha2", - "forwarding_curve25519_key_chain": [ - "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" - ], - "room_id": "!Cuyf34gef24t:localhost", - "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", - "sender_claimed_keys": { - "ed25519": "", - }, - "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..." - }, - ... -] -``` +{{% definition path="api/client-server/definitions/megolm_export_session_data" %}} #### Messaging Algorithms diff --git a/data/api/client-server/definitions/key_backup_auth_data.yaml b/data/api/client-server/definitions/key_backup_auth_data.yaml new file mode 100644 index 00000000..e057e433 --- /dev/null +++ b/data/api/client-server/definitions/key_backup_auth_data.yaml @@ -0,0 +1,36 @@ +# Copyright 2022 The Matrix.org Foundation C.I.C +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +type: object +title: AuthData +description: |- + The format of the `auth_data` when a key backup is created with the + `algorithm` set to `m.megolm_backup.v1.curve25519-aes-sha2`. +properties: + public_key: + type: string + description: |- + The curve25519 public key used to encrypt the backups, encoded in unpadded base64. + example: "abcdefg" + signatures: + type: object + description: |- + Signatures of the `auth_data`, as Signed JSON + example: { + "something": { + "ed25519:something": "hijklmnop" + } + } +required: ['public_key'] diff --git a/data/api/client-server/definitions/key_backup_session_data.yaml b/data/api/client-server/definitions/key_backup_session_data.yaml new file mode 100644 index 00000000..18963cbe --- /dev/null +++ b/data/api/client-server/definitions/key_backup_session_data.yaml @@ -0,0 +1,62 @@ +# Copyright 2022 The Matrix.org Foundation C.I.C +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +type: object +title: SessionData +description: |- + The format of a backed-up session key, prior to encryption, when using the + `m.megolm_backup.v1.curve25519-aes-sha2` algorithm. +properties: + algorithm: + type: string + description: |- + The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`. + forwarding_curve25519_key_chain: + type: array + items: + type: string + description: |- + Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. + sender_key: + type: string + description: |- + Unpadded base64-encoded device Curve25519 key. + sender_claimed_keys: + type: object + additionalProperties: + type: string + description: |- + A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device. + session_key: + type: string + description: |- + Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format). +example: { + "algorithm": "m.megolm.v1.aes-sha2", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ], + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "sender_claimed_keys": { + "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y", + }, + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..." +} +required: + - algorithm + - forwarding_curve25519_key_chain + - sender_key + - sender_claimed_keys + - session_key diff --git a/data/api/client-server/definitions/megolm_export_session_data.yaml b/data/api/client-server/definitions/megolm_export_session_data.yaml new file mode 100644 index 00000000..8c1e5010 --- /dev/null +++ b/data/api/client-server/definitions/megolm_export_session_data.yaml @@ -0,0 +1,38 @@ +# Copyright 2022 The Matrix.org Foundation C.I.C +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +allOf: + - $ref: key_backup_session_data.yaml + - type: object + description: |- + The format used to encode a Megolm session key for export. + + This is similar to the format before encryption used for the session keys + in [Server-side key backups](#server-side-key-backups) but adds the + `room_id` and `session_id` fields. + properties: + room_id: + type: string + description: |- + The room where the session is used. + example: "!Cuyf34gef24t:localhost" + session_id: + type: string + description: |- + The Megolm session ID. + example: "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" + required: + - room_id + - session_id diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 2828db48..fdb307f7 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -18,6 +18,10 @@ {{/* The definition is referenced by the .path parameter */}} {{ $definition := index .Site.Data $pieces }} +{{ if not $definition }} + {{ errorf "site data %s not found" $path }} +{{ end }} + {{/* The base path, which we use to resolve $ref, omits the last component */}} {{ $pieces = first (sub (len $pieces) 1) $pieces}} {{ $path = delimit $pieces "/" }}