From 4abea9a6ca03b4438af26ef30afcee434dd07541 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 15 Aug 2023 02:18:45 -0400 Subject: [PATCH] Add room version 11 (#1604) * Remove duplicate words. * Add information on room version 11. * Note some event changes. * Newsfragment * Fix-up event schema. * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Fix 'new in this version'. * Clarify creator field. * Fix-up event format & examples. * Move the Redactions section to the client section. * Reference the sender instead of the creator. * More links * Even more links. * Fix order of headers. * Fix typos. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Clarify description of creator. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Clean-up intro paragraphs for redactions. * Clean-up examples and language. * Review comments. * FIx-up markup tags. --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../room_versions/newsfragments/1604.feature | 1 + content/rooms/_index.md | 14 +- content/rooms/fragments/v1-redactions.md | 18 +- content/rooms/fragments/v11-event-format.md | 4 + content/rooms/fragments/v11-redactions.md | 30 ++ content/rooms/fragments/v6-redactions.md | 16 +- content/rooms/fragments/v9-redactions.md | 41 +-- content/rooms/v11.md | 284 ++++++++++++++++++ content/rooms/v6.md | 2 +- content/rooms/v9.md | 21 ++ data/api/server-server/definitions/pdu.yaml | 4 + .../server-server/definitions/pdu_v11.yaml | 81 +++++ .../definitions/unsigned_pdu_base.yaml | 4 - data/api/server-server/examples/pdu_v11.json | 19 ++ .../event-schemas/examples/m.room.create.yaml | 3 +- .../examples/m.room.redaction.yaml | 2 +- data/event-schemas/schema/m.room.create.yaml | 6 +- .../schema/m.room.redaction.yaml | 7 +- 18 files changed, 492 insertions(+), 65 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1604.feature create mode 100644 content/rooms/fragments/v11-event-format.md create mode 100644 content/rooms/fragments/v11-redactions.md create mode 100644 content/rooms/v11.md create mode 100644 data/api/server-server/definitions/pdu_v11.yaml create mode 100644 data/api/server-server/examples/pdu_v11.json diff --git a/changelogs/room_versions/newsfragments/1604.feature b/changelogs/room_versions/newsfragments/1604.feature new file mode 100644 index 00000000..8408797d --- /dev/null +++ b/changelogs/room_versions/newsfragments/1604.feature @@ -0,0 +1 @@ +Add room version 11 as per [MSC3820](https://github.com/matrix-org/matrix-spec-proposals/pull/3820). diff --git a/content/rooms/_index.md b/content/rooms/_index.md index e75fbb13..9334c3a1 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -36,11 +36,11 @@ Alternatively, consider flipping the column/row organization to be features up top and versions on the left. --> -| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -|-------------------|---|---|---|---|---|---|---|---|---|----| -| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | -| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | -| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | +| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | +|-------------------|---|---|---|---|---|---|---|---|---|----|----| +| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ | +| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | +| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ## Complete list of room versions @@ -57,8 +57,7 @@ the default room version when creating new rooms. The available room versions are: -- [Version 1](/rooms/v1) - **Stable**. The current version of most - rooms. +- [Version 1](/rooms/v1) - **Stable**. The initial room version. - [Version 2](/rooms/v2) - **Stable**. Implements State Resolution Version 2. - [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs @@ -76,6 +75,7 @@ The available room versions are: redacting some membership events. - [Version 10](/rooms/v10) - **Stable**. Enforces integer-only power levels and adds `knock_restricted` join rule. +- [Version 11](/rooms/v11) - **Stable**. Clarifies the redaction algorithm. ## Room version grammar diff --git a/content/rooms/fragments/v1-redactions.md b/content/rooms/fragments/v1-redactions.md index f38c85f3..4731dbab 100644 --- a/content/rooms/fragments/v1-redactions.md +++ b/content/rooms/fragments/v1-redactions.md @@ -19,12 +19,14 @@ not in the following list: - `membership` The content object must also be stripped of all keys, unless it is one -of one of the following event types: +of the following event types: -- `m.room.member` allows key `membership`. -- `m.room.create` allows key `creator`. -- `m.room.join_rules` allows key `join_rule`. -- `m.room.power_levels` allows keys `ban`, `events`, `events_default`, - `kick`, `redact`, `state_default`, `users`, `users_default`. -- `m.room.aliases` allows key `aliases`. -- `m.room.history_visibility` allows key `history_visibility`. +- [`m.room.member`](/client-server-api#mroommember) allows key `membership`. +- [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`. +- [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows key `join_rule`. +- [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys + `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`, + `users_default`. +- [`m.room.aliases`](/client-server-api#historical-events) allows key `aliases`. +- [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) allows + key `history_visibility`. diff --git a/content/rooms/fragments/v11-event-format.md b/content/rooms/fragments/v11-event-format.md new file mode 100644 index 00000000..a4da710d --- /dev/null +++ b/content/rooms/fragments/v11-event-format.md @@ -0,0 +1,4 @@ + +Events in rooms of this version have the following structure: + +{{% definition path="api/server-server/definitions/pdu_v11" %}} diff --git a/content/rooms/fragments/v11-redactions.md b/content/rooms/fragments/v11-redactions.md new file mode 100644 index 00000000..3bde94ba --- /dev/null +++ b/content/rooms/fragments/v11-redactions.md @@ -0,0 +1,30 @@ + +Upon receipt of a redaction event, the server must strip off any keys +not in the following list: + +- `event_id` +- `type` +- `room_id` +- `sender` +- `state_key` +- `content` +- `hashes` +- `signatures` +- `depth` +- `prev_events` +- `auth_events` +- `origin_server_ts` + +The content object must also be stripped of all keys, unless it is one +of the following event types: + +- [`m.room.member`](/client-server-api#mroommember) allows keys `membership`, `join_authorised_via_users_server`. + Additionally, it allows the `signed` key of the `third_party_invite` key. +- [`m.room.create`](/client-server-api#mroomcreate) allows all keys. +- [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows keys `join_rule`, `allow`. +- [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys + `ban`, `events`, `events_default`, `invite`, `kick`, `redact`, `state_default`, + `users`, `users_default`. +- [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) + allows key `history_visibility`. +- [`m.room.redaction`](/client-server-api#mroomredaction) allows key `redacts`. \ No newline at end of file diff --git a/content/rooms/fragments/v6-redactions.md b/content/rooms/fragments/v6-redactions.md index 71ecf854..47b024a2 100644 --- a/content/rooms/fragments/v6-redactions.md +++ b/content/rooms/fragments/v6-redactions.md @@ -19,11 +19,13 @@ not in the following list: - `membership` The content object must also be stripped of all keys, unless it is one -of one of the following event types: +of the following event types: -- `m.room.member` allows key `membership`. -- `m.room.create` allows key `creator`. -- `m.room.join_rules` allows key `join_rule`. -- `m.room.power_levels` allows keys `ban`, `events`, `events_default`, - `kick`, `redact`, `state_default`, `users`, `users_default`. -- `m.room.history_visibility` allows key `history_visibility`. +- [`m.room.member`](/client-server-api#mroommember) allows key `membership`. +- [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`. +- [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows key `join_rule`. +- [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys + `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`, + `users_default`. +- [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) allows + key `history_visibility`. diff --git a/content/rooms/fragments/v9-redactions.md b/content/rooms/fragments/v9-redactions.md index 18c100a5..27cd97f0 100644 --- a/content/rooms/fragments/v9-redactions.md +++ b/content/rooms/fragments/v9-redactions.md @@ -1,24 +1,3 @@ ---- ---- - -{{% added-in this=true %}} `m.room.member` events now keep `join_authorised_via_users_server` -in addition to other keys in `content` when being redacted. - -{{% boxes/rationale %}} -Without the `join_authorised_via_users_server` property, redacted join events -can become invalid when verifying the auth chain of a given event, thus creating -a split-brain scenario where the user is able to speak from one server's -perspective but most others will continually reject their events. - -This can theoretically be worked around with a rejoin to the room, being careful -not to use the faulty events as `prev_events`, though instead it is encouraged -to use v9 rooms over v8 rooms to outright avoid the situation. - -[Issue #3373](https://github.com/matrix-org/matrix-doc/issues/3373) has further -information. -{{% /boxes/rationale %}} - -The full redaction algorithm follows. Upon receipt of a redaction event, the server must strip off any keys not in the following list: @@ -40,11 +19,15 @@ not in the following list: - `membership` The content object must also be stripped of all keys, unless it is one -of one of the following event types: - -- `m.room.member` allows keys `membership`, `join_authorised_via_users_server`. -- `m.room.create` allows key `creator`. -- `m.room.join_rules` allows keys `join_rule`, `allow`. -- `m.room.power_levels` allows keys `ban`, `events`, `events_default`, - `kick`, `redact`, `state_default`, `users`, `users_default`. -- `m.room.history_visibility` allows key `history_visibility`. \ No newline at end of file +of the following event types: + +- [`m.room.member`](/client-server-api#mroommember) allows keys `membership`, + `join_authorised_via_users_server`. +- [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`. +- [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows keys `join_rule`, + `allow`. +- [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys + `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`, + `users_default`. +- [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) + allows key `history_visibility`. \ No newline at end of file diff --git a/content/rooms/v11.md b/content/rooms/v11.md new file mode 100644 index 00000000..d0aa4b45 --- /dev/null +++ b/content/rooms/v11.md @@ -0,0 +1,284 @@ +--- +title: Room Version 11 +type: docs +weight: 100 +--- + +This room version builds on [version 10](/rooms/v10) while clarifying redaction +rules. + +## Client considerations + +### Redactions + +{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties +are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate) +event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction) +event keeps the `redacts` property under `content`. The +[`m.room.power_levels`](/client-server-api#mroompower_levels) event keeps the +`invite` property under `content`. + +The full redaction algorithm follows. + +{{% rver-fragment name="v11-redactions" withVersioning="true" %}} + +### Event format + +Clients should no longer depend on the `creator` property in the `content` of +[`m.room.create`](/client-server-api#mroomcreate) events. In all room versions, +clients can rely on `sender` instead to determine a room creator. + +The format of [`m.room.redaction`](/client-server-api#mroomredaction) +events has been modified. Client should look for the `redacts` key under `content` +instead of a top-level event property. + +The `third_party_invite` key of [`m.room.member`](/client-server-api#mroommember) +events is no longer redacted, *but* will only contain the `signed` key after redaction. + +## Server implementation components + +{{% boxes/warning %}} +The information contained in this section is strictly for server +implementors. Applications which use the Client-Server API are generally +unaffected by the intricacies contained here. The section above +regarding client considerations is the resource that Client-Server API +use cases should reference. +{{% /boxes/warning %}} + +This room version updates the redaction algorithm and modifies how servers should +create `m.room.create` and `m.room.redaction` events. + +Room version 11 is based upon room version 10 with the following considerations. + +### Redactions + +[See above](#redactions). + +### Event format + +The core event format is the same as [room version 10](/rooms/v10#event-format). +However, this room version changes some properties of some event types. + +{{% rver-fragment name="v11-event-format" %}} + +#### Remove the `creator` property of `m.room.create` events + +The `content` of a `m.room.create` event no longer has a `creator` property, +which previously was always equivalent to the `sender` of the event. + +#### Moving the `redacts` property of `m.room.redaction` events to a `content` property + +The `redacts` property of `m.room.redaction` events is moved from a top-level +event property to a property under the event `content`. + +For backwards-compatibility with older clients, servers should add a `redacts` property +to the top level of `m.room.redaction` events in when serving such events over the +Client-Server API. + +For improved compatibility with newer clients, servers should add a `redacts` property +to the `content` of `m.room.redaction` events in *older* room versions when serving +such events over the Client-Server API. + +### Authorization rules + +Events must be signed by the server denoted by the `sender` property. + +`m.room.redaction` events are not explicitly part of the auth rules. +They are still subject to the minimum power level rules, but should always +fall into "10. Otherwise, allow". Instead of being authorized at the time +of receipt, they are authorized at a later stage: see the +[Redactions](#redactions) section below for more information. + +The types of state events that affect authorization are: + +- [`m.room.create`](/client-server-api#mroomcreate) +- [`m.room.member`](/client-server-api#mroommember) +- [`m.room.join_rules`](/client-server-api#mroomjoin_rules) +- [`m.room.power_levels`](/client-server-api#mroompower_levels) +- [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite) + +{{% boxes/note %}} +Power levels are inferred from defaults when not explicitly supplied. +For example, mentions of the `sender`'s power level can also refer to +the default power level for users in the room. +{{% /boxes/note %}} + +The rules are as follows: + +1. {{< changed-in this="true" >}} + If type is `m.room.create`: + 1. If it has any `prev_events`, reject. + 2. If the domain of the `room_id` does not match the domain of the + `sender`, reject. + 3. If `content.room_version` is present and is not a recognised + version, reject. + 4. Otherwise, allow. +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, 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 there is no `state_key` property, or no `membership` property in + `content`, reject. + 2. If `content` has a `join_authorised_via_users_server` + key: + 1. If the event is not validly signed by the homeserver of the user ID denoted + by the key, reject. + 3. If `membership` is `join`: + 1. {{< changed-in this="true" >}} + If the only previous event is an `m.room.create` and the + `state_key` is the sender, allow. + 2. If the `sender` does not match `state_key`, reject. + 3. If the `sender` is banned, reject. + 4. If the `join_rule` is `invite` or `knock` then allow if + membership state is `invite` or `join`. + 5. If the `join_rule` is `restricted` or `knock_restricted`: + 1. If membership state is `join` or `invite`, allow. + 2. If the `join_authorised_via_users_server` key in `content` + is not a user with sufficient permission to invite other + users, reject. + 3. Otherwise, allow. + 6. If the `join_rule` is `public`, allow. + 7. Otherwise, reject. + 4. If `membership` is `invite`: + 1. If `content` has a `third_party_invite` property: + 1. If *target user* is banned, reject. + 2. If `content.third_party_invite` does not have a `signed` + property, reject. + 3. If `signed` does not have `mxid` and `token` properties, + reject. + 4. If `mxid` does not match `state_key`, reject. + 5. If there is no `m.room.third_party_invite` event in the + current room state with `state_key` matching `token`, + reject. + 6. If `sender` does not match `sender` of the + `m.room.third_party_invite`, reject. + 7. If any signature in `signed` matches any public key in + the `m.room.third_party_invite` event, allow. The public + keys are in `content` of `m.room.third_party_invite` as: + 1. A single public key in the `public_key` property. + 2. A list of public keys in the `public_keys` property. + 8. Otherwise, reject. + 2. If the `sender`'s current membership state is not `join`, + reject. + 3. If *target user*'s current membership state is `join` or + `ban`, reject. + 4. If the `sender`'s power level is greater than or equal to + the *invite level*, allow. + 5. Otherwise, reject. + 5. If `membership` is `leave`: + 1. If the `sender` matches `state_key`, allow if and only if + that user's current membership state is `invite`, `join`, + or `knock`. + 2. If the `sender`'s current membership state is not `join`, + reject. + 3. If the *target user*'s current membership state is `ban`, + and the `sender`'s power level is less than the *ban level*, + reject. + 4. If the `sender`'s power level is greater than or equal to + the *kick level*, and the *target user*'s power level is + less than the `sender`'s power level, allow. + 5. Otherwise, reject. + 6. If `membership` is `ban`: + 1. If the `sender`'s current membership state is not `join`, + reject. + 2. If the `sender`'s power level is greater than or equal to + the *ban level*, and the *target user*'s power level is less + than the `sender`'s power level, allow. + 3. Otherwise, reject. + 7. If `membership` is `knock`: + 1. If the `join_rule` is anything other than `knock` or + `knock_restricted`, reject. + 2. If `sender` does not match `state_key`, reject. + 3. If the `sender`'s current membership is not `ban` or `join`, allow. + 4. Otherwise, reject. + 8. Otherwise, the membership is unknown. Reject. +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*. +7. If the event type's *required power level* is greater than the + `sender`'s power level, reject. +8. If the event has a `state_key` that starts with an `@` and does not + match the `sender`, reject. +9. If type is `m.room.power_levels`: + 1. If any of the properties `users_default`, `events_default`, `state_default`, + `ban`, `redact`, `kick`, or `invite` in `content` are present and + not an integer, reject. + 2. If either of the properties `events` or `notifications` in `content` + are present and not an object with values that are integers, + reject. + 3. If the `users` property in `content` is not an obiect with keys that + are valid user IDs with values that are integers, reject. + 4. If there is no previous `m.room.power_levels` event in the room, + allow. + 5. For the properties `users_default`, `events_default`, `state_default`, + `ban`, `redact`, `kick`, `invite` check if they were added, + changed or removed. For each found alteration: + 1. If the current value is higher than the `sender`'s current + power level, reject. + 2. If the new value is higher than the `sender`'s current power + level, reject. + 6. For each entry being changed in, or removed from, the `events` or + `notifications` properties: + 1. If the current value is greater than the `sender`'s current + power level, reject. + 7. For each entry being added to, or changed in, the `events` or + `notifications` properties: + 1. If the new value is greater than the `sender`'s current power + level, reject. + 8. For each entry being changed in, or removed from, the `users` property, + other than the `sender`'s own entry: + 1. If the current value is greater than or equal to the `sender`'s + current power level, reject. + 9. For each entry being added to, or changed in, the `users` property: + 1. If the new value is greater than the `sender`'s current power + level, reject. + 10. Otherwise, allow. +10. Otherwise, allow. + +{{% boxes/note %}} +Some consequences of these rules: + +- Unless you are a member of the room, the only permitted operations + (apart from the initial create/join) are: joining a public room; + accepting or rejecting an invitation to a room. +- To unban somebody, you must have power level greater than or equal + to both the kick *and* ban levels, *and* greater than the target + user's power level. +{{% /boxes/note %}} + +## Unchanged from v10 + +The following sections have not been modified since v10, but are included for +completeness. + +### Handling redactions + +{{% rver-fragment name="v3-handling-redactions" %}} + +### Event IDs + +{{% rver-fragment name="v4-event-ids" %}} + +### State resolution + +{{% rver-fragment name="v2-state-res" %}} + +### Canonical JSON + +{{% rver-fragment name="v6-canonical-json" %}} + +### Signing key validity period + +{{% rver-fragment name="v5-signing-requirements" %}} diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 977f5479..b0309254 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -15,7 +15,7 @@ which implement the redaction algorithm locally should refer to the ### Redactions -{{% added-in this=true %}} All significant meaning for `m.room.aliases` +{{< added-in this=true >}} All significant meaning for `m.room.aliases` has been removed from the redaction algorithm. The remaining rules are the same as past room versions. diff --git a/content/rooms/v9.md b/content/rooms/v9.md index f6735415..cef269c6 100644 --- a/content/rooms/v9.md +++ b/content/rooms/v9.md @@ -17,6 +17,27 @@ Clients which implement the redaction algorithm locally should refer to the ### Redactions +{{< added-in this=true >}} [`m.room.member`](/client-server-api#mroommember) events +now keep `join_authorised_via_users_server` in addition to other keys in `content` +when being redacted. + +{{% boxes/rationale %}} +Without the `join_authorised_via_users_server` property, redacted join events +can become invalid when verifying the auth chain of a given event, thus creating +a split-brain scenario where the user is able to speak from one server's +perspective but most others will continually reject their events. + +This can theoretically be worked around with a rejoin to the room, being careful +not to use the faulty events as `prev_events`, though instead it is encouraged +to use v9 rooms over v8 rooms to outright avoid the situation. + +[Issue #3373](https://github.com/matrix-org/matrix-doc/issues/3373) has further +information. +{{% /boxes/rationale %}} + +The full redaction algorithm follows. + + {{% rver-fragment name="v9-redactions" withVersioning="true" %}} ## Server implementation components diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml index d87db1a3..5903f80e 100644 --- a/data/api/server-server/definitions/pdu.yaml +++ b/data/api/server-server/definitions/pdu.yaml @@ -20,6 +20,10 @@ allOf: - $ref: "unsigned_pdu.yaml" - type: object properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def456:matrix.org" hashes: type: object title: Event Hash diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml new file mode 100644 index 00000000..3edfb6c8 --- /dev/null +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -0,0 +1,81 @@ +# Copyright 2019-2023 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: A persistent data unit (event) for room version 11 and beyond. +example: + $ref: "../examples/pdu_v11.json" +allOf: + # v11 is the v4 event, but without redacts. Copy the auth_events/prev_events + # from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml. + - $ref: "unsigned_pdu_base.yaml" + - type: object + properties: + auth_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the authorization events that would + allow this event to be in the room. + + Must contain less than or equal to 10 events. Note that if the relevant + auth event selection rules are used, this restriction should never be + encountered. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + prev_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the most recent events in the room + that the homeserver was aware of when it made this event. + + Must contain less than or equal to 20 events. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + hashes: + type: object + title: Event Hash + description: |- + Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" + } + properties: + sha256: + type: string + description: The hash. + example: ThisHashCoversAllFieldsInCaseThisIsRedacted + required: ['sha256'] + signatures: + type: object + description: |- + Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "example.com": { + "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent" + } + } + additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string + required: + - auth_events + - prev_events + - hashes + - signatures diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index c21149f6..ce42236f 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -107,10 +107,6 @@ properties: description: The event hash. example: Base64EncodedSha256HashesShouldBe43BytesLong required: ['sha256'] - redacts: - type: string - description: For redaction events, the ID of the event being redacted. - example: "$def456:matrix.org" unsigned: type: object title: UnsignedData diff --git a/data/api/server-server/examples/pdu_v11.json b/data/api/server-server/examples/pdu_v11.json new file mode 100644 index 00000000..292f38a0 --- /dev/null +++ b/data/api/server-server/examples/pdu_v11.json @@ -0,0 +1,19 @@ +{ + "$ref": "unsigned_pdu_base.json", + "hashes": { + "sha256": "thishashcoversallfieldsincasethisisredacted" + }, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + }, + "auth_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ], + "prev_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ] +} diff --git a/data/event-schemas/examples/m.room.create.yaml b/data/event-schemas/examples/m.room.create.yaml index e33dbc3b..390ea78d 100644 --- a/data/event-schemas/examples/m.room.create.yaml +++ b/data/event-schemas/examples/m.room.create.yaml @@ -3,8 +3,7 @@ "type": "m.room.create", "state_key": "", "content": { - "creator": "@example:example.org", - "room_version": "1", + "room_version": "11", "m.federate": true, "predecessor": { "event_id": "$something:example.org", diff --git a/data/event-schemas/examples/m.room.redaction.yaml b/data/event-schemas/examples/m.room.redaction.yaml index 42bc8411..457b0a37 100644 --- a/data/event-schemas/examples/m.room.redaction.yaml +++ b/data/event-schemas/examples/m.room.redaction.yaml @@ -1,8 +1,8 @@ { "$ref": "core/room_event.json", "type": "m.room.redaction", - "redacts": "$fukweghifu23:localhost", "content": { + "redacts": "$fukweghifu23:localhost", "reason": "Spamming" } } diff --git a/data/event-schemas/schema/m.room.create.yaml b/data/event-schemas/schema/m.room.create.yaml index 44c9c84e..1ca37865 100644 --- a/data/event-schemas/schema/m.room.create.yaml +++ b/data/event-schemas/schema/m.room.create.yaml @@ -6,7 +6,9 @@ properties: content: properties: creator: - description: The `user_id` of the room creator. This is set by the homeserver. + description: |- + The `user_id` of the room creator. **Required** for, and only present in, room versions 1 - 10. Starting with + room version 11 the event `sender` should be used instead. type: string m.federate: description: Whether users on other servers can join this room. Defaults to `true` if key does not exist. @@ -32,8 +34,6 @@ properties: type: string description: The event ID of the last known event in the old room. required: [room_id, event_id] - required: - - creator type: object state_key: description: A zero-length string. diff --git a/data/event-schemas/schema/m.room.redaction.yaml b/data/event-schemas/schema/m.room.redaction.yaml index 143e7eff..8a7edeba 100644 --- a/data/event-schemas/schema/m.room.redaction.yaml +++ b/data/event-schemas/schema/m.room.redaction.yaml @@ -5,18 +5,19 @@ description: 'This event is created by the server to describe which event has be properties: content: properties: + redacts: + description: The event ID that was redacted. Required for, and present starting in, room version 11. + type: string reason: description: 'The reason for the redaction, if any.' type: string type: object redacts: - description: The event ID that was redacted. + description: Required for, and only present in, room versions 1 - 10. The event ID that was redacted. type: string type: enum: - m.room.redaction type: string -required: - - redacts title: Redaction type: object