Clarify auth rules for m.room.power_levels events (#1269)

changelogs/room_versions/newsfragments/1269.clarification

@@ -0,0 +1 @@
+Reword the event auth rules to clarify that users cannot demote other users with the same power level.

content/rooms/fragments/v1-auth-rules.md

@@ -111,29 +111,32 @@ The rules are as follows:
 9. 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`:
-    1.  If `users` key in `content` is not a dictionary with keys that
+    1.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers (or a string
         that is an integer), reject.
     2.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    3.  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
+        1.  If the current value is greater than the `sender`'s current
             power level, reject.
-        2.  If the new value is higher than the `sender`'s current power
+        2.  If the new value is greater than the `sender`'s current power
             level, reject.
-    4.  For each entry being added, changed or removed in both the
-        `events` and `users` keys:
-        1.  If the current value is higher than the `sender`'s current
+    4.  For each entry being changed in, or removed from, the `events` property:
+        1.  If the current value is greater than the `sender`'s current
             power level, reject.
-        2.  If the new value is higher than the `sender`'s current power
+    5.  For each entry being added to, or changed in, the `events` property:
+        1.  If the new value is greater than the `sender`'s current power
             level, reject.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    6.  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.
+    7.  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.
+    8. Otherwise, allow.
 11. If type is `m.room.redaction`:
     1.  If the `sender`'s power level is greater than or equal to the
         *redact level*, allow.

content/rooms/fragments/v3-auth-rules.md

@@ -118,29 +118,32 @@ The complete list of rules, as of room version 3, is as follows:
 9.  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`:
-    1.  If `users` key in `content` is not a dictionary with keys that
+    1.  If `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers (or a string
         that is an integer), reject.
     2.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    3.  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
+        1.  If the current value is greater than the `sender`'s current
             power level, reject.
-        2.  If the new value is higher than the `sender`'s current power
+        2.  If the new value is greater than the `sender`'s current power
             level, reject.
-    4.  For each entry being added, changed or removed in both the
-        `events` and `users` keys:
-        1.  If the current value is higher than the `sender`'s current
+    4.  For each entry being changed in, or removed from, the `events` property:
+        1.  If the current value is greater than the `sender`'s current
             power level, reject.
-        2.  If the new value is higher than the `sender`'s current power
+    5.  For each entry being added to, or changed in, the `events` property:
+        1.  If the new value is greater than the `sender`'s current power
             level, reject.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    6.  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.
+    7.  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.
+    8.  Otherwise, allow.
 11. Otherwise, allow.
 
 {{% boxes/note %}}

content/rooms/fragments/v8-auth-rules.md

@@ -132,29 +132,34 @@ The rules are as follows:
 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 `users` key in `content` is not a dictionary with keys that
+    1.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers (or a string
         that is an integer), reject.
     2.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    3.  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.
-    4.  For each entry being added, changed or removed in both the
-        `events`, `users`, and `notifications` keys:
-        1.  If the current value is higher than the `sender`'s current
+    4.  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.
-        2.  If the new value is higher than the `sender`'s current power
+    5.  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.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    6.  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.
+    7.  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.
+    8. Otherwise, allow.
 10. Otherwise, allow.
 
 {{% boxes/note %}}

content/rooms/v10.md

@@ -207,35 +207,40 @@ The rules are as follows:
     match the `sender`, reject.
 9. If type is `m.room.power_levels`:
     1.  {{< added-in this="true" >}}
-        If any of the keys `users_default`, `events_default`, `state_default`,
+        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.  {{< added-in this="true" >}}
-        If either of the keys `events` or `notifications` in `content`
-        are present and not a dictionary with values that are integers,
+        If either of the properties `events` or `notifications` in `content`
+        are present and not an object with values that are integers,
         reject.
-    3.  If `users` key in `content` is not a dictionary with keys that
+    3.  If the `users` property in `content` is not an obiect with keys that
         are valid user IDs with values that are integers, reject.
-    2.  If there is no previous `m.room.power_levels` event in the room,
+    4.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    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.
-    4.  For each entry being added, changed or removed in both the
-        `events`, `users`, and `notifications` keys:
-        1.  If the current value is higher than the `sender`'s current
+    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.
-        2.  If the new value is higher than the `sender`'s current power
+    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.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    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 %}}

content/rooms/v6.md

@@ -46,14 +46,14 @@ fall into "10. Otherwise, allow". Instead of being authorized at the time
 of receipt, they are authorized at a later stage: see the
 [Handling Redactions](#handling-redactions) section below for more information.
 
-{{% added-in this=true %}} Rule 4, which related specifically to events
+{{< added-in this=true >}} Rule 4, which related specifically to events
 of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
 authorization checks relating to state events.
 
-{{% added-in this=true %}} Additionally, the authorization rules for events
-of type `m.room.power_levels` now include the content key `notifications`.
-This new rule takes the place of rule 10.4, which checked the `events` and
-`users` keys.
+{{< added-in this=true >}} Additionally, the authorization rules for events of
+type `m.room.power_levels` now include a `notifications` property under
+`content`.  This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
+the `events` property.
 
 Events must be signed by the server denoted by the `sender` property.
 
@@ -156,29 +156,36 @@ The rules are as follows:
 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 `users` key in `content` is not a dictionary with keys that
+    1.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers (or a string
         that is an integer), reject.
     2.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    3.  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.
-    4.  For each entry being added, changed or removed in both the
-        `events`, `users`, and `notifications` keys:
-        1.  If the current value is higher than the `sender`'s current
+    4.  {{< changed-in this="true" >}}
+        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.
-        2.  If the new value is higher than the `sender`'s current power
+    5.  {{< changed-in this="true" >}}
+        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.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    6.  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.
+    7.  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.
+    8. Otherwise, allow.
 10. Otherwise, allow.
 
 {{% boxes/note %}}

content/rooms/v7.md

@@ -151,29 +151,34 @@ The rules are as follows:
 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 `users` key in `content` is not a dictionary with keys that
+    1.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers (or a string
         that is an integer), reject.
     2.  If there is no previous `m.room.power_levels` event in the room,
         allow.
-    3.  For the keys `users_default`, `events_default`, `state_default`,
+    3.  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.
-    4.  For each entry being added, changed or removed in both the
-        `events`, `users`, and `notifications` keys:
-        1.  If the current value is higher than the `sender`'s current
+    4.  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.
-        2.  If the new value is higher than the `sender`'s current power
+    5.  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.
-    5.  For each entry being changed under the `users` key, other than
-        the `sender`'s own entry:
-        1.  If the current value is equal to the `sender`'s current
-            power level, reject.
-    6.  Otherwise, allow.
+    6.  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.
+    7.  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.
+    8. Otherwise, allow..
 10. Otherwise, allow.
 
 {{% boxes/note %}}