Merge 1baf93caf5 into b1fd2af72c

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

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.

changelogs/internal/newsfragments/2222.clarification

@@ -0,0 +1 @@
+Clarify vendor prefixing requirements.

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.
 

content/proposals.md

@@ -408,41 +408,9 @@ development or testing data.
 that a particular MSC works) do not have to follow this process.
 
 1.  Have an idea for a feature.
-1.  Implement the feature using unstable endpoints, vendor prefixes, and
-    unstable feature flags as appropriate.
-    -   When using unstable endpoints, they MUST include a vendor
-        prefix. For example:
-        `/_matrix/client/unstable/com.example/login`. Vendor prefixes
-        throughout Matrix always use the Java package naming convention.
-        The MSC for the feature should identify which preferred vendor
-        prefix is to be used by early adopters.
-    -   Note that unstable namespaces do not automatically inherit
-        endpoints from stable namespaces: for example, the fact that
-        `/_matrix/client/r0/sync` exists does not imply that
-        `/_matrix/client/unstable/com.example/sync` exists.
-    -   If the client needs to be sure the server supports the feature,
-        an unstable feature flag that MUST be vendor prefixed is to be
-        used. This kind of flag shows up in the `unstable_features`
-        section of `/versions` as, for example, `com.example.new_login`.
-        The MSC for the feature should identify which preferred feature
-        flag is to be used by early adopters.
-    -   When using this approach correctly, the implementation can
-        ship/release the feature at any time, so long as the
-        implementation is able to accept the technical debt that results
-        from needing to provide adequate backwards and forwards
-        compatibility. The implementation MUST support the flag (and
-        server-side implementation) disappearing and be generally safe
-        for users. Note that implementations early in the MSC review
-        process may also be required to provide backwards compatibility
-        with earlier editions of the proposal.
-    -   If the implementation cannot support the technical debt (or if
-        it's impossible to provide forwards/backwards compatibility -
-        e.g. a user authentication change which can't be safely rolled
-        back), the implementation should not attempt to implement the
-        feature and should instead wait for a spec release.
-    -   If at any point after early release, the idea changes in a
-        backwards-incompatible way, the feature flag should also change
-        so that implementations can adapt as needed.
+1.  Implement the feature using [unstable endpoints, vendor prefixes, and
+    unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
+    as appropriate.
 1.  In parallel, or ahead of implementation, open an MSC and solicit
     review per above.
 1.  Before FCP can be called, the Spec Core Team will require evidence
@@ -452,10 +420,7 @@ that a particular MSC works) do not have to follow this process.
     forwards/backwards compatibility concerns mentioned here.
 1.  The FCP process is completed, and assuming nothing is flagged the
     MSC lands.
-1.  Implementations can now switch to using stable prefixes
-    (for example, for an endpoint, moving from
-    `/unstable/org.matrix.mscxxxx/frobnicate`
-    to `/v1/frobnicate`), assuming that the change
+1.  Implementations can now switch to using stable prefixes, assuming that the change
     is backwards compatible with older implementations. In the rare occasion
     where backwards compatibility is not possible without a new spec release,
     implementations should continue to use unstable prefixes.
@@ -471,13 +436,6 @@ that a particular MSC works) do not have to follow this process.
     started supporting the new spec release, some noise should be raised
     in the general direction of the implementation.
 
-{{% boxes/note %}}
-MSCs MUST still describe what the stable endpoints/feature looks like
-with a note towards the bottom for what the unstable feature
-flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
-com.example/new/endpoint`.
-{{% /boxes/note %}}
-
 In summary:
 
 -   Implementations MUST NOT use stable endpoints before the MSC has
@@ -489,14 +447,90 @@ In summary:
 -   Implementations SHOULD be wary of the technical debt they are
     incurring by moving faster than the spec.
 -   The vendor prefix is chosen by the developer of the feature, using
-    the Java package naming convention. The foundation's preferred
-    vendor prefix is `org.matrix`.
+    the Java package naming convention.
 -   The vendor prefixes, unstable feature flags, and unstable endpoints
     should be included in the MSC, though the MSC MUST be written in a
     way that proposes new stable endpoints. Typically this is solved by
     a small table at the bottom mapping the various values from stable
     to unstable.
 
+#### Unstable endpoints, features and vendor prefixes
+
+Unstable endpoints MUST use `/unstable` as the endpoint version and a
+vendor prefix in Java package naming format. For example:
+`/_matrix/client/unstable/com.example.mscxxxx/login`.
+
+{{% boxes/note %}}
+Proposal authors operating with a Matrix.org Foundation mandate SHOULD use
+a vendor prefix within the `org.matrix` namespace. This namespace is otherwise
+restricted. Authors who don't own a domain MAY use the `io.github` namespace
+instead.
+{{% /boxes/note %}}
+
+Note that unstable namespaces do not automatically inherit endpoints from
+stable namespaces: for example, the fact that `/_matrix/client/v3/sync`
+exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync`
+exists.
+
+Vendor prefixes MUST also be used for:
+
+-   New parameters on existing endpoints. For example:
+    `/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`.
+-   New properties in existing JSON objects. For example:
+
+    ```json
+    {
+      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+      "displayname": "Alice Margatroid",
+      "com.example.mscxxxx.phone": [{
+        "type": "landline",
+        "number": "+1-206-555-7000"
+      }],
+      ...
+    }
+    ```
+
+-   New values for existing parameters or properties. For example:
+
+    ```json
+    {
+      "errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL",
+      "error": "The email address you provided is invalid."
+    }
+    ```
+
+If the client needs to be sure the server supports the feature, an
+unstable feature flag that MUST also be vendor prefixed is to be used.
+This flag shows up in the `unstable_features` section of
+[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+as, for example, `com.example.mscxxxx.new_login`.
+
+{{% boxes/note %}}
+MSCs MUST still describe what the stable endpoints/feature looks like
+with a note towards the bottom for what the unstable feature
+flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`,
+not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`.
+{{% /boxes/note %}}
+
+When using this approach correctly, the implementation can release
+the feature at any time, so long as the implementation is able to
+accept the technical debt that results from needing to provide
+adequate backwards and forwards compatibility. The implementation
+MUST support the flag (and server-side implementation) disappearing
+and be generally safe for users. Note that implementations early in
+the MSC review process may also be required to provide backwards
+compatibility with earlier editions of the proposal.
+
+If the implementation cannot support the technical debt (or if it's
+impossible to provide forwards/backwards compatibility - e.g. a user
+authentication change which can't be safely rolled back), the
+implementation should not attempt to implement the feature and should
+instead wait for a spec release.
+
+If at any point after early release, the idea changes in a
+backwards-incompatible way, the feature flag should also change so
+that implementations can adapt as needed.
+
 ### Placeholder MSCs
 
 Some proposals may contain security-sensitive or private context which can't be

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/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: