Merge c12fbe4540 into f62aa09e60

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

changelogs/appendices/newsfragments/2307.clarification

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

changelogs/client_server/newsfragments/2278.feature

@@ -0,0 +1 @@
+Add administrator endpoints to lock and suspend server-local users and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.1

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.2

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.3

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.4

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

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/2304.clarification

@@ -0,0 +1 @@
+Clarify the requiredness of `event_id` in `predecessor`.

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/internal/newsfragments/2317.clarification

@@ -0,0 +1 @@
+Update the footer social links to match matrix.org. Contributed by @HarHarLinks.

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.

config/_default/hugo.toml

@@ -115,11 +115,6 @@ sidebar_menu_compact = true
   url = "https://gitlab.matrix.org/matrix-org"
   icon = "fab fa-gitlab"
   desc = "Matrix on GitLab"
-[[params.links.bottom]]
-  name = "YouTube"
-  url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
-  icon = "fab fa-youtube"
-  desc = "Matrix YouTube channel"
 [[params.links.bottom]]
   name = "Mastodon"
   url = "https://mastodon.matrix.org/@matrix"
@@ -130,6 +125,21 @@ sidebar_menu_compact = true
   url = "https://bsky.app/profile/matrix.org"
   icon = "fab fa-bluesky"
   desc = "Matrix on Bluesky"
+[[params.links.bottom]]
+  name = "LinkedIn"
+  url = "https://www.linkedin.com/company/matrix-org/"
+  icon = "fab fa-linkedin"
+  desc = "Matrix on LinkedIn"
+[[params.links.bottom]]
+  name = "YouTube"
+  url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
+  icon = "fab fa-youtube"
+  desc = "Matrix YouTube channel"
+[[params.links.bottom]]
+  name = "Matrix.org Blog Feed"
+  url = "https://matrix.org/atom.xml"
+  icon = "fas fa-rss"
+  desc = "Matrix.org Blog Atom Feed"
 
 
 # configuration for the hugo development server

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

@@ -2394,9 +2394,12 @@ where feasible. The Matrix-specific actions are:
 Server administrators may apply locks to prevent users from usefully
 using their accounts, for instance, due to safety or security concerns.
 In contrast to account deactivation, locking is a non-destructive action
-that can be reversed. This specification describes the behaviour of clients
-and servers when an account is locked. It deliberately leaves the methods
-for locking and unlocking accounts as a server implementation detail.
+that can be reversed.
+
+{{% added-in v="1.18" %}} To lock or unlock an account, administrators
+SHOULD use the [`PUT /admin/lock/{userId}`](#put_matrixclientv1adminlockuserid)
+endpoint. They MAY also use [`GET /admin/lock/{userId}`](#get_matrixclientv1adminlockuserid)
+to check whether a user's account is locked.
 
 When an account is locked, servers MUST return a `401 Unauthorized` error
 response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout)
@@ -2445,6 +2448,11 @@ from that account. The effect is similar to [locking](#account-locking), though
 without risk of the client losing state from a logout. Suspensions are reversible,
 like locks and unlike deactivations.
 
+{{% added-in v="1.18" %}} To suspend or unsuspend an account, administrators
+SHOULD use the [`PUT /admin/suspend/{userId}`](#put_matrixclientv1adminsuspenduserid)
+endpoint. They MAY also use [`GET /admin/suspend/{userId}`](#get_matrixclientv1adminsuspenduserid)
+to check whether a user's account is suspended.
+
 The actions a user can perform while suspended is deliberately left as an
 implementation detail. Servers SHOULD permit the user to perform at least the
 following, however:
@@ -2500,9 +2508,6 @@ Content-Type: application/json
 }
 ```
 
-APIs for initiating suspension or unsuspension are not included in this version
-of the specification, and left as an implementation detail.
-
 ### Adding Account Administrative Contact Information
 
 A homeserver may keep some contact information for administrative use.
@@ -4071,6 +4076,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.*
@@ -4144,6 +4150,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/client-server-api/modules/room_upgrades.md

@@ -43,8 +43,8 @@ They must be explicitly set during the `/upgrade` call.
 {{% /boxes/note %}}
 
 {{% boxes/note %}}
-{{% added-in v="1.16" %}} When upgrading to room version 12 or later, the `predecessor` field MAY NOT contain
-an `event_id`.
+{{% added-in v="1.16" %}} When upgrading to room version 12 or later, the `event_id` property inside
+`predecessor` MAY be omitted.
 {{% /boxes/note %}}
 
 3.  Replicates transferable state events to the new room. The exact

data/api/client-server/admin.yaml

@@ -16,7 +16,7 @@ info:
   title: Matrix Client-Server Administration API
   version: 1.0.0
 paths:
-  "/admin/whois/{userId}":
+  "/v3/admin/whois/{userId}":
     get:
       summary: Gets information about a particular user.
       description: |-
@@ -107,6 +107,391 @@ paths:
                   }
       tags:
         - Server administration
+  "/v1/admin/suspend/{userId}":
+    get:
+      summary: Gets information about the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the suspended status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                suspended:
+                  type: boolean
+                  description: Whether to suspend the target account.
+                  example: true
+              required:
+                - suspended
+            examples:
+                request:
+                  value: {
+                    "suspended": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to suspend their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+  "/v1/admin/lock/{userId}":
+    get:
+      summary: Gets information about the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the locked status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                locked:
+                  type: boolean
+                  description: Whether to lock the target account.
+                  example: true
+              required:
+                - locked
+            examples:
+                request:
+                  value: {
+                    "locked": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                    example: true
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to lock their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:
@@ -118,7 +503,7 @@ servers:
       hostname:
         default: localhost:8008
       basePath:
-        default: /_matrix/client/v3
+        default: /_matrix/client
 components:
   securitySchemes:
     accessTokenQuery:

data/api/client-server/capabilities.yaml

@@ -84,7 +84,7 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
                           Refer to `m.profile_fields` for extended profile management.
-                          
+
                           For backwards compatibility, servers that directly or indirectly include the
                           `displayname` profile field in the `m.profile_fields` capability MUST also
                           set this capability accordingly.
@@ -121,7 +121,7 @@ paths:
                             description: |
                               If present, a list of profile fields that clients are allowed to create, modify or delete,
                               provided `enabled` is `true`; no other profile fields may be changed.
-                              
+
                               If absent, clients may set all profile fields except those forbidden by the `disallowed`
                               list, where present.
                             items:
@@ -133,7 +133,7 @@ paths:
                             type: array
                             description:  |
                               This property has no meaning if `allowed` is also specified.
-                              
+
                               Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
                               Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
                               included in this list.
@@ -147,6 +147,34 @@ paths:
                             example: true
                         required:
                           - enabled
+                      m.account_moderation:
+                        x-addedInMatrixVersion: "1.18"
+                        type: object
+                        title: AccountModerationCapability
+                        description: |-
+                          Capability to indicate if the user can perform account moderation actions
+                          via [server administration](/client-server-api/#server-administration)
+                          endpoints.
+
+                          This property should be omitted altogether if `suspend` and `lock` would
+                          be `false`.
+                        properties:
+                          suspend:
+                            type: boolean
+                            description: |-
+                              `true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](/client-server-api/#put_matrixclientv1adminsuspenduserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
+                          lock:
+                            type: boolean
+                            description: |-
+                              `true` if the user can lock a user via [`PUT /admin/lock/{userId}`](/client-server-api/#put_matrixclientv1adminlockuserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
               examples:
                 response:
                   value: {

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

@@ -83,7 +83,7 @@ paths:
                   value: {}
         "400":
           description: |-
-            
+
             The request is invalid. A meaningful `errcode` and description
             error text will be returned. Example reasons for rejection include:
 
@@ -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/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/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
-            certificates will need to be valid until to be useful to the requesting server.
+            A millisecond POSIX timestamp. The returned keys SHOULD be valid
+            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
-                            the returned certificates will need to be valid until to be
-                            useful to the requesting server.
+                            A millisecond POSIX timestamp. The returned keys
+                            SHOULD be valid 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.
                           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).