Merge 6e7c8a6da0 into 70c7d59caa

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2270.feature

@@ -0,0 +1 @@
+Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).

changelogs/internal/newsfragments/2222.clarification

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

content/client-server-api/_index.md

@@ -645,7 +645,7 @@ manage their account like [changing their password](#password-management),
 [deactivating their account](#account-deactivation).
 
 With the OAuth 2.0 API, all account management is done via the homeserver's web
-UI.
+UI that can be accessed by users via the [account management URL](#oauth-20-account-management).
 
 ### Legacy API
 
@@ -2271,6 +2271,54 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### Account management {id="oauth-20-account-management"}
+
+{{% added-in v="1.18" %}}
+
+All account management is done via the homeserver's web UI.
+
+This specification defines extensions to the [OAuth Authorization Server
+Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
+to offer clients a way to deep-link to the account management capabilities of
+the homeserver to allow the user to complete the account management operations
+in a browser.
+
+##### Account management URL discovery
+
+The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
+extended to include the following fields:
+
+| Field                                  | Description                                                                                     |
+|----------------------------------------|-------------------------------------------------------------------------------------------------|
+| `account_management_uri`               | The URL where the user is able to access the account management capabilities of the homeserver. |
+| `account_management_actions_supported` | An array of actions that the account management URL supports, as defined below.                 |
+
+##### Account management URL parameters
+
+The account management URL MAY accept the following query parameters:
+
+| Parameter   | Description                                                                                                                           |
+|-------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| `action`    | **Optional**. The action that the user wishes to take. Must match one of the actions in `account_management_actions_supported` above. |
+| `device_id` | **Optional**. Identifies a particular Matrix device ID for actions that support it.                                                   |
+
+If the `org.matrix.device_view` or `org.matrix.device_delete` actions are
+advertised as supported by the server then the server SHOULD support the
+`device_id` parameter.
+
+##### Account management URL actions
+
+The following account management actions are defined:
+
+| Action                           | Description                                                                                                                                          |
+|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `org.matrix.profile`             | The user wishes to view/edit their profile (name, avatar, contact details).                                                                          |
+| `org.matrix.devices_list`        | The user wishes to view a list of their devices.                                                                                                     |
+| `org.matrix.device_view`         | The user wishes to view the details of a specific device. A `device_id` SHOULD be provided.                                                          |
+| `org.matrix.device_delete`       | The user wishes to delete/log out a specific device. A `device_id` SHOULD be provided.                                                               |
+| `org.matrix.account_deactivate`  | The user wishes to deactivate their account.                                                                                                         |
+| `org.matrix.cross_signing_reset` | The user wishes to reset their cross-signing identity. Servers SHOULD use this action in the URL of the [`m.oauth`](#oauth-authentication) UIA type. |
+
 ### Account moderation
 
 #### Account locking

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
+1.  Implement the feature using [unstable endpoints, vendor prefixes, and
-    unstable feature flags as appropriate.
+    unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
-    -   When using unstable endpoints, they MUST include a vendor
+    as appropriate.
-        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.  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
+1.  Implementations can now switch to using stable prefixes, assuming that the change
-    (for example, for an endpoint, moving from
-    `/unstable/org.matrix.mscxxxx/frobnicate`
-    to `/v1/frobnicate`), 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
+    the Java package naming convention.
-    vendor prefix is `org.matrix`.
 -   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/oauth_server_metadata.yaml

@@ -139,6 +139,32 @@ paths:
                     items:
                       type: string
                       description: A prompt value that the server supports.
+                  account_management_uri:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      The URL where the user is able to access the account management capabilities
+                      of the homeserver.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                  account_management_actions_supported:
+                    x-addedInMatrixVersion: "1.18"
+                    type: array
+                    description: |-
+                      List of actions that the account management URL supports.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                    items:
+                      type: string
+                      enum:
+                        - "org.matrix.profile"
+                        - "org.matrix.devices_list"
+                        - "org.matrix.device_view"
+                        - "org.matrix.device_delete"
+                        - "org.matrix.account_deactivate"
+                        - "org.matrix.cross_signing_reset"
+                      description: An action that the account management URL supports.
                 required:
                   - issuer
                   - authorization_endpoint
@@ -159,6 +185,15 @@ paths:
                   "grant_types_supported": ["authorization_code", "refresh_token"],
                   "response_modes_supported": ["query", "fragment"],
                   "code_challenge_methods_supported": ["S256"],
+                  "account_management_uri": "https://account.example.com/manage",
+                  "account_management_actions_supported": [
+                    "org.matrix.profile",
+                    "org.matrix.devices_list",
+                    "org.matrix.device_view",
+                    "org.matrix.device_delete",
+                    "org.matrix.account_deactivate",
+                    "org.matrix.cross_signing_reset",
+                  ],
                 }
       tags:
         - Session management