Various clarifications to auth rules text (matrix-org#1270)

changelogs/room_versions/newsfragments/1270.clarification

@@ -0,0 +1 @@
+Various clarifications to the text on event authorisation rules.

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

@@ -19,12 +19,12 @@ the default power level for users in the room.
 The rules are as follows:
 
 1.  If type is `m.room.create`:
-    1.  If it has any previous events, reject.
+    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.  If `content` has no `creator` field, reject.
+    4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
 2.  Considering the event's `auth_events`:
     1.  If there are duplicate entries for a given `type` and `state_key` pair,
@@ -45,7 +45,8 @@ The rules are as follows:
     2.  If sender's domain doesn't matches `state_key`, reject.
     3.  Otherwise, allow.
 5.  If type is `m.room.member`:
-    1.  If no `state_key` key or `membership` key in `content`, reject.
+    1.  If there is no `state_key` property, or no `membership` property in
+        `content`, reject.
     2.  If `membership` is `join`:
         1.  If the only previous event is an `m.room.create` and the
             `state_key` is the creator, allow.
@@ -56,11 +57,11 @@ The rules are as follows:
         5.  If the `join_rule` is `public`, allow.
         6.  Otherwise, reject.
     3.  If `membership` is `invite`:
-        1.  If `content` has `third_party_invite` key:
+        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`
-                key, reject.
-            3.  If `signed` does not have `mxid` and `token` keys,
+                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
@@ -71,8 +72,8 @@ The rules are as follows:
             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` field.
-                2.  A list of public keys in the `public_keys` field.
+                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.

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

@@ -2,11 +2,11 @@
 toc_hide: true
 ---
 
-{{% added-in this=true %}} In room versions 1 and 2, events need a
+{{< added-in this=true >}} In room versions 1 and 2, events need a
 signature from the domain of the `event_id` in order to be considered
 valid. This room version does not include an `event_id` over federation
 in the same respect, so does not need a signature from that server.
-The event must still be signed by the server denoted by the `sender`,
+The event must still be signed by the server denoted by the `sender` property,
 however.
 
 The types of state events that affect authorization are:
@@ -26,12 +26,12 @@ the default power level for users in the room.
 The complete list of rules, as of room version 3, is as follows:
 
 1.  If type is `m.room.create`:
-    1.  If it has any previous events, reject.
+    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.  If `content` has no `creator` field, reject.
+    4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
 2.  Considering the event's `auth_events`:
     1.  If there are duplicate entries for a given `type` and `state_key` pair,
@@ -52,7 +52,8 @@ The complete list of rules, as of room version 3, is as follows:
     2.  If sender's domain doesn't matches `state_key`, reject.
     3.  Otherwise, allow.
 5.  If type is `m.room.member`:
-    1.  If no `state_key` key or `membership` key in `content`, reject.
+    1.  If there is no `state_key` property, or no `membership` property in
+        `content`, reject.
     2.  If `membership` is `join`:
         1.  If the only previous event is an `m.room.create` and the
             `state_key` is the creator, allow.
@@ -63,11 +64,11 @@ The complete list of rules, as of room version 3, is as follows:
         5.  If the `join_rule` is `public`, allow.
         6.  Otherwise, reject.
     3.  If `membership` is `invite`:
-        1.  If `content` has `third_party_invite` key:
+        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`
-                key, reject.
-            3.  If `signed` does not have `mxid` and `token` keys,
+                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
@@ -78,8 +79,8 @@ The complete list of rules, as of room version 3, is as follows:
             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` field.
-                2.  A list of public keys in the `public_keys` field.
+                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.

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

@@ -2,7 +2,7 @@
 toc_hide: true
 ---
 
-Events must be signed by the server denoted by the `sender` key.
+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
@@ -27,12 +27,12 @@ the default power level for users in the room.
 The rules are as follows:
 
 1.  If type is `m.room.create`:
-    1.  If it has any previous events, reject.
+    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.  If `content` has no `creator` field, reject.
+    4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
 2.  Considering the event's `auth_events`:
     1.  If there are duplicate entries for a given `type` and `state_key` pair,
@@ -49,9 +49,10 @@ The rules are as follows:
    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:
+    1.  If there is no `state_key` property, or no `membership` property in
+        `content`, reject.
+    2.  {{< added-in this=true >}}
+        If `content` has a `join_authorised_via_users_server` property:
         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`:
@@ -61,7 +62,8 @@ The rules are as follows:
         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`:
+        5.  {{< added-in this=true >}}
+            If the `join_rule` is `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
@@ -70,11 +72,11 @@ The rules are as follows:
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.
     4.  If `membership` is `invite`:
-        1.  If `content` has `third_party_invite` key:
+        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`
-                key, reject.
-            3.  If `signed` does not have `mxid` and `token` keys,
+                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
@@ -85,8 +87,8 @@ The rules are as follows:
             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` field.
-                2.  A list of public keys in the `public_keys` field.
+                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.

content/rooms/v10.md

@@ -74,7 +74,7 @@ correctly structured are rejected under the authorization rules below.
 
 ### Authorization rules
 
-Events must be signed by the server denoted by the `sender` key.
+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
@@ -99,12 +99,12 @@ the default power level for users in the room.
 The rules are as follows:
 
 1.  If type is `m.room.create`:
-    1.  If it has any previous events, reject.
+    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.  If `content` has no `creator` field, reject.
+    4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
 2.  Considering the event's `auth_events`:
     1.  If there are duplicate entries for a given `type` and `state_key` pair,
@@ -121,7 +121,8 @@ The rules are as follows:
    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.
+    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
@@ -143,11 +144,11 @@ The rules are as follows:
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.
     4.  If `membership` is `invite`:
-        1.  If `content` has `third_party_invite` key:
+        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`
-                key, reject.
-            3.  If `signed` does not have `mxid` and `token` keys,
+                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
@@ -158,8 +159,8 @@ The rules are as follows:
             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` field.
-                2.  A list of public keys in the `public_keys` field.
+                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.

content/rooms/v3.md

@@ -89,15 +89,15 @@ The complete structure of a event in a v3 room is shown below.
 
 ### Authorization rules
 
-{{% added-in this=true %}} `m.room.redaction` events are no longer
+{{< added-in this=true >}} `m.room.redaction` events are no longer
 explicitly part of the auth rules. They are still subject to the
 minimum power level rules, but should always fall into "11. 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.
 
 <!-- set withVersioning=true so we get all the "new in this version" stuff -->
-{{% rver-fragment name="v3-auth-rules" withVersioning=true %}}
+{{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
 
 ## Unchanged from v2
 

content/rooms/v6.md

@@ -55,7 +55,7 @@ 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.
 
-Events must be signed by the server denoted by the `sender` key.
+Events must be signed by the server denoted by the `sender` property.
 
 The types of state events that affect authorization are:
 
@@ -74,12 +74,12 @@ the default power level for users in the room.
 The rules are as follows:
 
 1.  If type is `m.room.create`:
-    1.  If it has any previous events, reject.
+    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.  If `content` has no `creator` field, reject.
+    4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
 2.  Reject if event has `auth_events` that:
     1.  have duplicate entries for a given `type` and `state_key` pair
@@ -90,7 +90,8 @@ The rules are as follows:
 3.  If event does not have a `m.room.create` in its `auth_events`,
     reject.
 4.  If type is `m.room.member`:
-    1.  If no `state_key` key or `membership` key in `content`, reject.
+    1.  If there is no `state_key` property, or no `membership` property in
+        `content`, reject.
     2.  If `membership` is `join`:
         1.  If the only previous event is an `m.room.create` and the
             `state_key` is the creator, allow.
@@ -101,11 +102,11 @@ The rules are as follows:
         5.  If the `join_rule` is `public`, allow.
         6.  Otherwise, reject.
     3.  If `membership` is `invite`:
-        1.  If `content` has `third_party_invite` key:
+        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`
-                key, reject.
-            3.  If `signed` does not have `mxid` and `token` keys,
+                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
@@ -116,8 +117,8 @@ The rules are as follows:
             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` field.
-                2.  A list of public keys in the `public_keys` field.
+                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.