Merge 3c17aa3789 into b1fd2af72c

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

changelogs/client_server/newsfragments/2181.clarification

@@ -0,0 +1,2 @@
+Clarify that the stripped state in `invite_state` and `knock_state` in `GET /sync` response must
+include the full `m.room.member` event of the user.

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

@@ -0,0 +1 @@
+Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users.

changelogs/client_server/newsfragments/2250.clarification

@@ -0,0 +1 @@
+Minor grammatical fix in the Secrets module description.

content/client-server-api/_index.md

@@ -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/secrets.md

@@ -59,7 +59,7 @@ clients will try to use the default key to decrypt secrets.
 
 Clients that want to present a simplified interface to users by not supporting
 multiple keys should use the default key if one is specified. If no default
-key is specified, the client may behave as if there is no key is present at
+key is specified, the client may behave as if no key is present at
 all. When such a client creates a key, it should mark that key as being the
 default key.
 

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 %}}
+        {{% boxes/note %}}
-        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        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/login.yaml

@@ -262,6 +262,8 @@ paths:
                 or the requested device ID is the same as a cross-signing key
                 ID.
               * `M_USER_DEACTIVATED`: The user has been deactivated.
+                Servers MAY instead use `M_FORBIDDEN` when they can no longer authenticate
+                the deactivated user (e.g. their password has been wiped).
           content:
             application/json:
               schema:

data/api/client-server/sync.yaml

@@ -374,8 +374,14 @@ paths:
                                     description: |-
                                       The [stripped state events](/client-server-api/#stripped-state) that form the
                                       invite state.
+
+                                      MUST also include the `m.room.member` event of the user with a membership of
+                                      `invite`, and using the same event format as joined rooms with the `event_id`
+                                      and `origin_server_ts` fields.
                                     items:
-                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                      anyOf:
+                                        - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                        - $ref: definitions/client_event_without_room_id.yaml
                                     type: array
                       knock:
                         title: Knocked rooms
@@ -399,8 +405,14 @@ paths:
                                     description: |-
                                       The [stripped state events](/client-server-api/#stripped-state) that form the
                                       knock state.
+
+                                      MUST also include the `m.room.member` event of the user with a membership of
+                                      `knock`, and using the same event format as joined rooms with the `event_id` and
+                                      `origin_server_ts` fields.
                                     items:
-                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                      anyOf:
+                                        - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                        - $ref: definitions/client_event_without_room_id.yaml
                                     type: array
                       leave:
                         title: Left rooms
@@ -633,6 +645,8 @@ paths:
                                 "sender": "@alice:example.com",
                                 "type": "m.room.member",
                                 "state_key": "@bob:example.com",
+                                "event_id": "$19dl9d3848dJLle:example.com",
+                                "origin_server_ts": 1432735439654,
                                 "content": {
                                   "membership": "invite"
                                 }
@@ -657,6 +671,8 @@ paths:
                                 "sender": "@bob:example.com",
                                 "type": "m.room.member",
                                 "state_key": "@bob:example.com",
+                                "event_id": "$Fg83Kl3764di23a:example.com",
+                                "origin_server_ts": 143273039402,
                                 "content": {
                                   "membership": "knock"
                                 }