Merge 1d31fe99af into a2027a3985

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

changelogs/client_server/newsfragments/2232.clarification

@@ -0,0 +1 @@
+`M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code.

changelogs/client_server/newsfragments/2234.feature

@@ -0,0 +1 @@
+Add the `m.oauth` authentication type for User-Interactive Authentication as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312).

changelogs/client_server/newsfragments/2240.clarification

@@ -0,0 +1 @@
+Clarify how to use `state_after` ahead of declaring full support for its spec version.

changelogs/client_server/newsfragments/2245.clarification

@@ -0,0 +1 @@
+`device_one_time_keys_count` is only optional if no unclaimed one-time keys exist.

changelogs/room_versions/newsfragments/2249.clarification

@@ -0,0 +1 @@
+In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send.  

content/client-server-api/_index.md

@@ -136,6 +136,17 @@ code if the endpoint is implemented, but the incorrect HTTP method is used.
 {{% added-in v="1.17" %}} The device ID supplied by the application service does
 not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
 
+`M_RESOURCE_LIMIT_EXCEEDED`
+The request cannot be completed because the homeserver has reached a
+resource limit imposed on it. For example, a homeserver held in a shared
+hosting environment may reach a resource limit if it starts using too
+much memory or disk space. The error MUST have an `admin_contact` field
+to provide the user receiving the error a place to reach out to.
+Typically, this error will appear on routes which attempt to modify
+state (e.g.: sending messages, account data, etc) and not routes which
+only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
+[`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
+
 `M_UNKNOWN`
 An unknown error has occurred.
 
@@ -221,17 +232,6 @@ The request or entity was too large.
 The resource being requested is reserved by an application service, or
 the application service making the request has not created the resource.
 
-`M_RESOURCE_LIMIT_EXCEEDED`
-The request cannot be completed because the homeserver has reached a
-resource limit imposed on it. For example, a homeserver held in a shared
-hosting environment may reach a resource limit if it starts using too
-much memory or disk space. The error MUST have an `admin_contact` field
-to provide the user receiving the error a place to reach out to.
-Typically, this error will appear on routes which attempt to modify
-state (e.g.: sending messages, account data, etc) and not routes which
-only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
-[`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
-
 `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
 The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
@@ -907,6 +907,7 @@ This specification defines the following auth types:
 -   `m.login.dummy`
 -   `m.login.registration_token`
 -   {{% added-in v="1.11" %}} `m.login.terms`
+-   {{% added-in v="1.17" %}} `m.oauth`
 
 ###### Password-based
 
@@ -1245,6 +1246,40 @@ user during registration, if applicable.
 
 {{% definition path="api/client-server/definitions/m.login.terms_params" %}}
 
+###### OAuth authentication
+
+{{% added-in v="1.17" %}}
+
+| Type                          | Description                                                       |
+|-------------------------------|-------------------------------------------------------------------|
+| `m.oauth`                     | Authentication is supported by authorising via the homeserver's OAuth account management web UI. |
+
+{{% boxes/note %}}
+The `m.oauth` authentication type is currently only valid on the
+[`/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload) endpoint.
+{{% /boxes/note %}}
+
+This authentication type provides homeservers the ability to guard access to
+sensitive actions when the client has authenticated via the
+[OAuth 2.0 API](/client-server-api/#oauth-20-api), which is otherwise not
+compatible with User-Interactive Authentication (UIA). To do so, the server
+returns a 401 response on the respective request, where the response body
+includes `m.oauth` in the `flows` list, and the `m.oauth` property in the
+`params` object has the structure [shown below](#definition-moauth-params).
+
+The client is expected to open the contained URL to let the user confirm the
+action in the homeserver's account management web UI. Once the user has done
+so, the client submits an `auth` dict with just the `session`, as follows,
+to complete the stage:
+
+```json
+{
+  "session": "<session ID>"
+}
+```
+
+{{% definition path="api/client-server/definitions/m.oauth_params" %}}
+
 ##### Fallback
 
 Clients cannot be expected to be able to know how to process every
@@ -1591,6 +1626,11 @@ because they don't have access to the user's credentials anymore.
 The [User-Interactive Authentication API](#user-interactive-authentication-api)
 is not compatible with the OAuth 2.0 API, so the endpoints that depend on it for
 authentication can't be used when an access token is obtained with this API.
+
+The only exception to this is the
+[`/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload)
+endpoint which uses the [`m.oauth`](/client-server-api/#oauth-authentication)
+authentication type.
 {{% /boxes/warning %}}
 
 **Sample flow**

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

@@ -1775,19 +1775,18 @@ property is required for inclusion, though previous versions of the
 specification did not have it. In addition to `/versions`, this can be
 a way to identify the server's support for fallback keys.
 
-
-| Parameter                        | Type               | Description                                                                                                            |
-|----------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
-| device_lists                     | DeviceLists        | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
-| device_one_time_keys_count       | {string: integer}  | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device.  If an algorithm is unlisted, the count for that algorithm is assumed to be zero.  If this entire parameter is missing, the count for all algorithms is assumed to be zero.  |
-| device_unused_fallback_key_types | [string]           | **Required.** The unused fallback key algorithms.                                                                      |
+| Parameter                        | Type              | Description                                                                                                            |
+|----------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------|
+| device_lists                     | DeviceLists       | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
+| device_one_time_keys_count       | {string: integer} | **Required if any unclaimed one-time keys exist.** For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If the count for an algorithm is zero, servers MAY omit that algorithm. If the count for all algorithms is zero, servers MAY omit this parameter entirely. |
+| device_unused_fallback_key_types | [string]          | **Required.** The unused fallback key algorithms.                                                                      |
 
 `DeviceLists`
 
-| Parameter  | Type      | Description                                                                                                                                                      |
-|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| changed    | [string]  | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
-| left       | [string]  | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
+| Parameter | Type     | Description                                                                                                                                                      |
+|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| changed   | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
+| left      | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
 
 {{% boxes/note %}}
 For optimal performance, Alice should be added to `changed` in Bob's

content/rooms/fragments/v3-handling-redactions.md

@@ -17,6 +17,9 @@ is met:
 2. The domain of the redaction event's `sender` matches that of the
    original event's `sender`.
 
+Note that the first condition holds true even when the `sender` doesn't have a
+high enough power level to send the type of event that they're redacting.
+
 If the server would apply a redaction, the redaction event is also sent
 to clients. Otherwise, the server simply waits for a valid partner event
 to arrive where it can then re-check the above.

data/api/client-server/cross_signing.yaml

@@ -40,10 +40,12 @@ paths:
         makes this endpoint idempotent in the case where the response is lost over the network,
         which would otherwise cause a UIA challenge upon retry.
 
-        {{% boxes/warning %}}
-        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        {{% boxes/note %}}
+        When this endpoint requires User-Interactive Authentication,
+        it uses the [`m.oauth`](/client-server-api/#oauth-authentication)
+        authentication type if the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
-        {{% /boxes/warning %}}
+        {{% /boxes/note %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

data/api/client-server/definitions/m.oauth_params.yaml

@@ -0,0 +1,30 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: m.oauth params
+description: Schema for `m.oauth` entry in the `params` object in a User-Interactive Authentication response.
+required: ['url']
+properties:
+  url:
+    type: string
+    format: uri
+    description: |
+      A URL pointing to the homeserver's OAuth account management web UI
+      where the user can approve the action. MUST be a valid URI with scheme
+      `http://` or `https://`, the latter being RECOMMENDED.
+    pattern: "^https?://"
+example: {
+    "url": "https://example.org/account/reset-cross-signing"
+}

data/api/client-server/sync.yaml

@@ -133,10 +133,15 @@ paths:
             sync and the **start** of the timeline in `state` and MUST omit
             `state_after`.
 
-            Even if this is set to `true`, clients MUST update their local state
-            with events in `state` and `timeline` if `state_after` is missing in
-            the response, for compatibility with servers that don't support this
-            parameter.
+            Servers MAY implement this parameter ahead of declaring support for
+            the version of the spec in which it was introduced. Consequently,
+            clients MAY set this parameter to `true` regardless of the
+            [`/versions`](/client-server-api/#get_matrixclientversions) response.
+            If they do, they can infer whether the server actually supports this
+            parameter from the presence of `state_after` in the response. If
+            `state_after` is missing, clients MUST behave as if they had not
+            specified the parameter and update their local state with events
+            in `state` and `timeline`.
 
             By default, this is `false`.
           example: false