Spec for MSC4312: Resetting cross-signing keys in the OAuth world

Signed-off-by: Johannes Marbach <[email protected]>

Author: Johennes

content/client-server-api/_index.md

@@ -906,6 +906,7 @@ This specification defines the following auth types:
 -   `m.login.msisdn`
 -   `m.login.dummy`
 -   `m.login.registration_token`
+-   {{% added-in v="1.17" %}} `m.oauth`
 
 ###### Password-based
 
@@ -1244,6 +1245,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
@@ -1590,6 +1625,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**

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,29 @@
+# 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.
+example: {
+    "url": "https://example.org/account/reset-cross-signing"
+}