Spec for MSC4133: Update profile endpoints to support extended fields (#2071)

Signed-off-by: Tom Foster <[email protected]>
Signed-off-by: Johannes Marbach <[email protected]>
Co-authored-by: Patrick Cloke <[email protected]>
Co-authored-by: Johannes Marbach <[email protected]>
Co-authored-by: Richard van der Hoff <[email protected]>

Author: 4 people

changelogs/client_server/newsfragments/2071.deprecation

@@ -0,0 +1 @@
+Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

changelogs/client_server/newsfragments/2071.feature

@@ -0,0 +1 @@
+Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability,as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

content/client-server-api/_index.md

@@ -2491,8 +2491,66 @@ using an `unstable` version.
 When this capability is not listed, clients should use `"1"` as the
 default and only stable `available` room version.
 
+### `m.profile_fields` capability
+
+{{% added-in v="1.16" %}}
+
+This capability defines which [profile](#profiles) fields the user is
+able to change.
+
+The capability value has a required flag, `enabled`, and two optional lists, `allowed` and
+`disallowed`.
+
+When `enabled` is `false`, all profile fields are managed by the server
+and the client is not permitted to make any changes.
+
+When `enabled` is `true`, clients are permitted to modify profile fields,
+subject to the restrictions implied by the OPTIONAL lists `allowed` and
+`disallowed`. 
+
+If `allowed` is present, clients can modify only the fields
+listed. They SHOULD assume all other fields to be managed by
+the server. In this case, `disallowed` has no meaning and should be ignored.
+
+If `disallowed` is present (and `allowed` is not), clients SHOULD assume
+that the listed fields are managed by the server. Clients may modify any
+fields that are *not* listed, provided `enabled` is `true`.
+
+If neither `allowed` nor `disallowed` is present, clients can modify all fields
+without restrictions, provided `enabled` is `true`.
+
+When this capability is not listed, clients SHOULD assume the user is able to change
+profile fields without any restrictions, provided the homeserver
+advertises a specification version that includes the `m.profile_fields`
+capability in the [`/versions`](/client-server-api/#get_matrixclientversions)
+response.
+
+An example of the capability API's response for this capability is:
+
+```json
+{
+  "capabilities": {
+    "m.profile_fields": {
+      "enabled": true,
+      "disallowed": ["displayname"]
+    }
+  }
+}
+```
+
 ### `m.set_displayname` capability
 
+{{% boxes/note %}}
+{{% changed-in v="1.16" %}}
+This capability is now deprecated. Clients SHOULD use the
+[`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
+capability instead.
+
+For backwards compatibility, servers that forbid setting the 
+`displayname` profile field in the `m.profile_fields` capability
+MUST still present this capability with `"enabled": false`.
+{{% /boxes/note %}}
+
 This capability has a single flag, `enabled`, to denote whether the user
 is able to change their own display name via profile endpoints. Cases for
 disabling might include users mapped from external identity/directory
@@ -2517,6 +2575,17 @@ An example of the capability API's response for this capability is:
 
 ### `m.set_avatar_url` capability
 
+{{% boxes/note %}}
+{{% changed-in v="1.16" %}}
+This capability is now deprecated. Clients SHOULD use the
+[`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
+capability instead.
+
+For backwards compatibility, servers that forbid setting the 
+`avatar_url` profile field in the `m.profile_fields` capability
+MUST still present this capability with `"enabled": false`.
+{{% /boxes/note %}}
+
 This capability has a single flag, `enabled`, to denote whether the user
 is able to change their own avatar via profile endpoints. Cases for
 disabling might include users mapped from external identity/directory

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

@@ -63,7 +63,8 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname). Guest users may only modify their display name; other profile fields may not be changed.
+* {{% added-in v="1.16" %}} [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname). Again, guest users may delete their display name but not other profile fields.
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

data/api/client-server/capabilities.yaml

@@ -73,11 +73,25 @@ paths:
                           - default
                           - available
                       m.set_displayname:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their display name.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their display name.
+                          Refer to `m.profile_fields` for extended profile management.
+                          
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `displayname` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.set_avatar_url:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their avatar.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their avatar.
+                          Refer to `m.profile_fields` for extended profile management.
+
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `avatar_url` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -86,6 +100,47 @@ paths:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
+                      m.profile_fields:
+                        x-addedInMatrixVersion: "1.16"
+                        type: object
+                        title: ProfileFieldsCapability
+                        description: Capability to indicate if the user can set or modify extended profile fields via
+                          [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients SHOULD assume custom profile fields are supported, provided the
+                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
+                        properties:
+                          allowed:
+                            type: array
+                            description: |
+                              If present, a list of profile fields that clients are allowed to create, modify or delete,
+                              provided `enabled` is `true`; no other profile fields may be changed.
+                              
+                              If absent, clients may set all profile fields except those forbidden by the `disallowed`
+                              list, where present.
+                            items:
+                              type: string
+                            example:
+                              - "m.example_field"
+                              - "org.example.job_title"
+                          disallowed:
+                            type: array
+                            description:  |
+                              This property has no meaning if `allowed` is also specified.
+                              
+                              Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
+                              Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
+                              included in this list.
+                            items:
+                              type: string
+                            example:
+                              - "org.example.managed_field"
+                          enabled:
+                            type: boolean
+                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
+                            example: true
+                        required:
+                          - enabled
               examples:
                 response:
                   value: {