Merge 1d1fa4cb5b into a6da9443da

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/appendices/newsfragments/2307.clarification

@@ -0,0 +1 @@
+Add identifier pronunciation guidelines. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2292.feature

@@ -0,0 +1 @@
+Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267).

changelogs/client_server/newsfragments/2298.feature

@@ -0,0 +1 @@
+Add support for `m.room.redaction` events at the `PUT /rooms/{roomId}/send/{eventType}/{txnId}` endpoint, as per [MSC4169](https://github.com/matrix-org/matrix-spec-proposals/pull/4169).

changelogs/client_server/newsfragments/2299.feature

@@ -0,0 +1 @@
+Clients supporting the `ol` HTML element must also support the `start` attribute, as per [MSC4313](https://github.com/matrix-org/matrix-spec-proposals/pull/4313).

changelogs/client_server/newsfragments/2305.feature

@@ -0,0 +1 @@
+Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380).

changelogs/room_versions/newsfragments/2303.clarification

@@ -0,0 +1 @@
+Remove the post-1.16 release note for room version 12.

changelogs/server_server/newsfragments/2191.clarification

@@ -0,0 +1 @@
+Clarify what the `minimum_valid_until_ts` field means when it is set in key queries.

changelogs/server_server/newsfragments/2300.clarification

@@ -0,0 +1 @@
+Change `m.signing_update` typo to `m.signing_key_update`. Contributed by @velikopter

content/appendices.md

@@ -533,6 +533,11 @@ where `domain` is the [server name](#server-name) of the homeserver
 which allocated the identifier, and `localpart` is an identifier
 allocated by that homeserver.
 
+Because the domain part identifies the server on which the ID resolves,
+the canonical pronunciation of the separating `:` is "on".
+For example, `@user:matrix.org` would be pronounced as "at user on matrix dot
+org".
+
 The precise grammar defining the allowable format of an identifier
 depends on the type of identifier. For example, event IDs can sometimes
 be represented with a `domain` component under some conditions - see the

content/client-server-api/_index.md

@@ -2619,6 +2619,40 @@ An example of the capability API's response for this capability is:
 }
 ```
 
+### `m.forget_forced_upon_leave` capability
+
+{{% added-in v="1.18" %}}
+
+This capability has a single flag, `enabled`, which indicates whether or
+not the server automatically forgets rooms which the user has left.
+
+When `enabled` is `true` and the user leaves a room, the server will automatically
+forget the room — just as if the user had called [`/forget`](#post_matrixclientv3roomsroomidforget)
+themselves. This behavior applies irrespective of whether the user has left the
+room on their own (through [`/leave`](#post_matrixclientv3roomsroomidleave)) or
+has been kicked or banned from the room by another user.
+
+When `enabled` is `false`, the server does not automatically forget rooms
+upon leave. In this case, clients MAY distinguish the actions of leaving
+and forgetting a room in their UI. Similarly, clients MAY retrieve and
+visualize left but unforgotten rooms using a [filter](#filtering) with
+`include_leave = true`.
+
+When the capability or the `enabled` property are not present, clients SHOULD
+assume that the server does not automatically forget rooms.
+
+An example of the capability API's response for this capability is:
+
+```json
+{
+  "capabilities": {
+    "m.forget_forced_upon_leave": {
+      "enabled": true
+    }
+  }
+}
+```
+
 ### `m.room_versions` capability
 
 This capability describes the default and available room versions a
@@ -3315,6 +3349,14 @@ the topic to be removed from the room.
 
 #### Client behaviour
 
+{{% changed-in v="1.18" %}}
+
+If the server advertises support for a spec version that supports it, clients
+MAY use the [`PUT /rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
+endpoint to send `m.room.redaction` events in all room versions.
+
+They can also use the following endpoint.
+
 {{% http-api spec="client-server" api="redaction" %}}
 
 ### Forming relationships between events
@@ -4029,6 +4071,7 @@ that profile.
 | [Sticker Messages](#sticker-messages)                      | Optional  | Optional | Optional | Optional | Optional |
 | [Third-party Networks](#third-party-networks)              | Optional  | Optional | Optional | Optional | Optional |
 | [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
+| [Invite permission](#invite-permission)                    | Optional  | Optional | Optional | Optional | Optional |
 
 *Please see each module for more details on what clients need to
 implement.*
@@ -4102,6 +4145,7 @@ systems.
 {{% cs-module name="SSO client login/authentication" filename="sso_login" %}}
 {{% cs-module name="Direct Messaging" filename="dm" %}}
 {{% cs-module name="Ignoring Users" filename="ignore_users" %}}
+{{% cs-module name="Invite permission" filename="invite_permission" %}}
 {{% cs-module name="Sticker Messages" filename="stickers" %}}
 {{% cs-module name="Reporting Content" filename="report_content" %}}
 {{% cs-module name="Third-party Networks" filename="third_party_networks" %}}

content/client-server-api/modules/instant_messaging.md

@@ -84,6 +84,10 @@ Additionally, web clients should ensure that *all* `a` tags get a
 `rel="noopener"` to prevent the target page from referencing the
 client's tab/window.
 
+{{% added-in v="1.18" %}} Clients that support rendering numbered lists via the
+`ol` tag MUST also support the `start` attribute in order to prevent loss of
+meaning of a message due to the numbering of list items.
+
 Tags must not be nested more than 100 levels deep. Clients should only
 support the subset of tags they can render, falling back to other
 representations of the tags where possible. For example, a client may

content/client-server-api/modules/invite_permission.md

@@ -0,0 +1,51 @@
+
+### Invite permission
+
+{{% added-in v="1.18" %}}
+
+Users may want to control who is allowed to invite them to new rooms. This module defines how
+clients and servers can implement invite permission.
+
+#### Account data
+
+{{% event event="m.invite_permission_config" %}}
+
+#### Client behaviour
+
+To reject invites from all users automatically, clients MAY add an [`m.invite_permission_config`](#minvite_permission_config)
+event in the user's [account data](#client-config) with the `default_action` property set to
+`block`. To stop rejecting all invites, the same event without the `default_action` property MUST be
+added to the account data.
+
+When the `default_action` field is unset, other parts of the specification might still have effects
+on invites seen by clients, like [ignoring users](#ignoring-users).
+
+Attempting to send an invite to a user that blocks invites will result in an error response with the
+`M_INVITE_BLOCKED` error code.
+
+#### Server behaviour
+
+When invites to a given user are blocked, the user's homeserver MUST respond to the following
+endpoints with an HTTP 403 status code, with the Matrix error code `M_INVITE_BLOCKED`, if the user
+is invited:
+
+* [`PUT /_matrix/federation/v1/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv1inviteroomideventid)
+* [`PUT /_matrix/federation/v2/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv2inviteroomideventid)
+* [`POST /_matrix/client/v3/rooms/{roomId}/invite`](#post_matrixclientv3roomsroomidinvite)
+* [`POST /_matrix/client/v3/createRoom`](#post_matrixclientv3createroom), due to a user in the
+  `invite` list. It is possible for one of the invited users to be rejected whilst the room creation
+  as a whole succeeds.
+* [`PUT /_matrix/client/v3/rooms/{roomId}/state/m.room.member/{stateKey}`](#put_matrixclientv3roomsroomidstateeventtypestatekey),
+  when the `membership` is set to `invite`.
+
+In addition, invite events for this user already in the database, or received over federation, MUST
+NOT be served over client synchronisation endpoints such as [`GET /sync`](#get_matrixclientv3sync).
+ 
+Servers MAY return any suppressed invite events over `GET /sync` if invite blocking is later
+disabled.
+ 
+Other endpoints, such as [`GET /rooms/{roomId}/state`](#get_matrixclientv3roomsroomidstate), are not
+affected by invite blocking: invite events are returned as normal.
+ 
+The Application Services API is also unaffected by invite blocking: invite events are sent over
+[`PUT /_matrix/app/v1/transactions/{txnId}`](/application-service-api/#put_matrixappv1transactionstxnid).

content/rooms/_index.md

@@ -56,19 +56,6 @@ Clients should not ask room administrators to upgrade their rooms if the
 room is running a stable version. Servers SHOULD use **room version 12** as
 the default room version when creating new rooms.
 
-{{% boxes/note %}}
-
-{{% added-in v="1.16" %}}
-
-Room version 12 is introduced and made default in this specification release.
-Servers are encouraged to continue using room version 11 as the default room
-version for the early days and weeks following this specification release,
-and then gradually switch the default over when they deem appropriate.
-
-<!-- TODO(SCT): Remove this note box in Matrix 1.17 -->
-
-{{% /boxes/note %}}
-
 The available room versions are:
 
 -   [Version 1](/rooms/v1) - **Stable**. The initial room version.

data/api/client-server/capabilities.yaml

@@ -50,6 +50,12 @@ paths:
                       m.change_password:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change their password.
+                      m.forget_forced_upon_leave:
+                        x-addedInMatrixVersion: "1.18"
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: |-
+                          Capability to indicate if the server automatically forgets rooms once the user
+                          leaves.
                       m.room_versions:
                         type: object
                         description: The room versions the server supports.

data/api/client-server/create_room.yaml

@@ -250,7 +250,6 @@ paths:
                   }
         "400":
           description: |-
-
             The request is invalid. A meaningful `errcode` and description
             error text will be returned. Example reasons for rejection include:
 
@@ -274,6 +273,17 @@ paths:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
+        "403":
+          description: |-
+            Creating the room is not allowed.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that one of the homeservers of the invited users rejected
+            the invite due to [invite blocking](/client-server-api/#invite-permission).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
       tags:
         - Room creation
 servers:

data/api/client-server/inviting.yaml

@@ -99,12 +99,18 @@ paths:
                 $ref: definitions/errors/error.yaml
         "403":
           description: |-
-            You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to invite the user to the room. A
+            meaningful `errcode` and description error text will be returned.
+            Example reasons for rejections are:
 
             - The invitee has been banned from the room.
             - The invitee is already a member of the room.
             - The inviter is not currently in the room.
             - The inviter's power level is insufficient to invite users to the room.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
           content:
             application/json:
               schema:

data/api/client-server/leaving.yaml

@@ -19,6 +19,10 @@ paths:
   "/rooms/{roomId}/leave":
     post:
       summary: Stop the requesting user participating in a particular room.
+      x-changedInMatrixVersion:
+        "1.18": |-
+          Servers may additionally forget the room provided that they make this behavior
+          transparent.
       description: |-
         This API stops a user participating in a particular room.
 
@@ -29,8 +33,15 @@ paths:
         If the user was invited to the room, but had not joined, this call
         serves to reject the invite.
 
-        The user will still be allowed to retrieve history from the room which
+        Servers MAY additionally forget the room when this endpoint is called –
-        they were previously allowed to see.
+        just as if the user had also invoked [`/forget`](/client-server-api/#post_matrixclientv3roomsroomidforget).
+        Servers that do this, MUST inform clients about this behavior using the
+        [`m.forget_forced_upon_leave`](/client-server-api/#mforget_forced_upon_leave-capability)
+        capability.
+
+        If the server doesn't automatically forget the room, the user will still be
+        allowed to retrieve history from the room which they were previously allowed
+        to see.
       operationId: leaveRoom
       security:
         - accessTokenQuery: []

data/api/client-server/room_send.yaml

@@ -20,6 +20,10 @@ paths:
   "/rooms/{roomId}/send/{eventType}/{txnId}":
     put:
       summary: Send a message event to the given room.
+      x-changedInMatrixVersion:
+        "1.18": |-
+          Homeservers must support sending `m.room.redaction` events with this endpoint
+          for all room versions.
       description: |-
         This endpoint is used to send a message event to a room. Message events
         allow access to historical events and pagination, making them suited
@@ -28,6 +32,11 @@ paths:
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
         [Room Events](/client-server-api/#room-events) for the m. event specification.
+
+        Homeservers MUST allow clients to send `m.room.redaction` events with this
+        endpoint for all room versions. In rooms with a version older than 11 they
+        MUST move the `redacts` property inside the `content` to the top level of
+        the event.
       operationId: sendMessage
       security:
         - accessTokenQuery: []

data/api/client-server/room_state.yaml

@@ -116,7 +116,13 @@ paths:
                     "error": "The alias '#hello:example.org' does not point to this room."
                   }
         "403":
-          description: The sender doesn't have permission to send the event into the room.
+          description: |-
+            The sender doesn't have permission to send the event into the room.
+
+            {{% added-in v="1.18"%}} If the `eventType` is `m.room.member` and
+            the `membership` is `invite`, the `M_INVITE_BLOCKED` error code is
+            used to indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
           content:
             application/json:
               schema:

data/api/client-server/third_party_membership.yaml

@@ -97,6 +97,10 @@ paths:
             - The invitee is already a member of the room.
             - The inviter is not currently in the room.
             - The inviter's power level is insufficient to invite users to the room.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
           content:
             application/json:
               schema:

data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml

@@ -25,7 +25,7 @@ allOf:
       edu_type:
         type: string
         enum: ['m.signing_key_update']
-        description: The string `m.signing_update`.
+        description: The string `m.signing_key_update`.
         example: "m.signing_key_update"
       content:
         type: object

data/api/server-server/invites-v1.yaml

@@ -155,11 +155,17 @@ paths:
                   ]
         "403":
           description: |-
-            The invite is not allowed. This could be for a number of reasons, including:
+            The invite is not allowed.
+
+            The `M_FORBIDDEN` error code is used to indicate one of the following:
 
             * The sender is not allowed to send invites to the target user/homeserver.
             * The homeserver does not permit anyone to invite its users.
             * The homeserver refuses to participate in the room.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
           content:
             application/json:
               schema:

data/api/server-server/invites-v2.yaml

@@ -192,11 +192,17 @@ paths:
                   }
         "403":
           description: |-
-            The invite is not allowed. This could be for a number of reasons, including:
+            The invite is not allowed.
+
+            The `M_FORBIDDEN` error code is used to indicate one of the following:
 
             * The sender is not allowed to send invites to the target user/homeserver.
             * The homeserver does not permit anyone to invite its users.
             * The homeserver refuses to participate in the room.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
           content:
             application/json:
               schema:

data/api/server-server/keys_query.yaml

@@ -34,10 +34,10 @@ paths:
         - in: query
           name: minimum_valid_until_ts
           description: |-
-            A millisecond POSIX timestamp in milliseconds indicating when the returned
+            A millisecond POSIX timestamp. The returned keys SHOULD be valid
-            certificates will need to be valid until to be useful to the requesting server.
+            until at least this timestamp.
 
-            If not supplied, the current time as determined by the notary server is used.
+            If not supplied, the notary server MUST use the current time.
           required: false
           example: 1234567890
           schema:
@@ -98,12 +98,11 @@ paths:
                           type: integer
                           format: int64
                           description: |-
-                            A millisecond POSIX timestamp in milliseconds indicating when
+                            A millisecond POSIX timestamp. The returned keys
-                            the returned certificates will need to be valid until to be
+                            SHOULD be valid until at least this timestamp.
-                            useful to the requesting server.
 
-                            If not supplied, the current time as determined by the notary
+                            If not supplied, the notary server MUST use the
-                            server is used.
+                            current time.
                           example: 1234567890
               required:
                 - server_keys

data/event-schemas/examples/m.invite_permission_config.yaml

@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.invite_permission_config",
+  "content": {
+    "default_action": "block"
+  }
+}

data/event-schemas/schema/m.invite_permission_config.yaml

@@ -0,0 +1,21 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+allOf:
+  - $ref: core-event-schema/event.yaml
+  - title: Invite Permission
+    type: object
+    description: |-
+      The permission configuration for receiving invites for the current account.
+    properties:
+      content:
+        type: object
+        properties:
+          default_action:
+            type: string
+            description: |-
+              When set to `block`, the user does not wish to receive *any* room invites, and they
+              should be rejected automatically by the homeserver.
+
+              A missing, invalid or unsupported value means that the user wants to receive invites
+              as normal. Other parts of the specification might still have effects on invites, like
+              [ignoring users](/client-server-api/#ignoring-users).