Merge f42ce28bfe into c4bfd2feb8

Signed-off-by: Tom Foster <tom@tcpip.uk>
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Richard van der Hoff <richard@matrix.org>

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).

changelogs/client_server/newsfragments/2188.clarification

@@ -0,0 +1 @@
+Clarify terminology for keys in cross-signing module.

changelogs/client_server/newsfragments/2195.clarification

@@ -0,0 +1 @@
+Fix `/sync` flow referencing incorrect parameter to use with `/messages`.

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
@@ -2837,7 +2906,7 @@ most recent message events for each room, as well as the state of the
 room at the start of the returned timeline. The response also includes a
 `next_batch` field, which should be used as the value of the `since`
 parameter in the next call to `/sync`. Finally, the response includes,
-for each room, a `prev_batch` field, which can be passed as a `start`
+for each room, a `prev_batch` field, which can be passed as a `from`/`to`
 parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier
 messages.
 

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

@@ -93,7 +93,7 @@ Example:
 ```
 
 `ed25519` and `curve25519` keys are used for [device keys](#device-keys).
-Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing).
+Additionally, `ed25519` keys are keys used for [cross-signing](#cross-signing).
 
 `signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
 
@@ -675,7 +675,7 @@ The process between Alice and Bob verifying each other would be:
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
     * Each of the keys that they wish the other user to verify (usually their
-      device ed25519 key and their master cross-signing key).
+      device ed25519 key and their master key, see below).
     * The complete list of key IDs that they wish the other user to verify.
 
     The MAC calculation is defined [below](#mac-calculation).
@@ -931,16 +931,16 @@ and can be translated online:
 Rather than requiring Alice to verify each of Bob's devices with each of
 her own devices and vice versa, the cross-signing feature allows users
 to sign their device keys such that Alice and Bob only need to verify
-once. With cross-signing, each user has a set of cross-signing keys that
+once. With cross-signing, each user has a set of ed25519 key pairs that
 are used to sign their own device keys and other users' keys, and can be
 used to trust device keys that were not verified directly.
 
-Each user has three ed25519 key pairs for cross-signing:
+Each user has three ed25519 key pairs used for cross-signing:
 
--   a master key (MSK) that serves as the user's identity in
-    cross-signing and signs their other cross-signing keys;
+-   a master key (MK) that serves as the user's identity in
+    cross-signing and signs their user-signing and self-signing keys;
 -   a user-signing key (USK) -- only visible to the user that it belongs
-    to --that signs other users' master keys; and
+    to -- that signs other users' master keys; and
 -   a self-signing key (SSK) that signs the user's own device keys.
 
 The master key may also be used to sign other items such as the backup
@@ -950,13 +950,15 @@ previously verified Bob's device and Bob's device has signed his master
 key, then Alice's device can trust Bob's master key, and she can sign it
 with her user-signing key.
 
-Users upload their cross-signing keys to the server using [POST
+Users upload the public part of their master, user-signing and self-signing
+key to the server using [POST
 /\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
-new cross-signing keys, her user ID will appear in the `changed`
+new keys, her user ID will appear in the `changed`
 property of the `device_lists` field of the `/sync` of response of all
 users who share an encrypted room with her. When Bob sees Alice's user
 ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
-to retrieve Alice's device and cross-signing keys.
+to retrieve Alice's device keys, as well as their master, user-signing and
+self-signing key.
 
 If Alice has a device and wishes to send an encrypted message to Bob,
 she can trust Bob's device if:
@@ -971,13 +973,13 @@ The following diagram illustrates how keys are signed:
 
 ```
     +------------------+                ..................   +----------------+
-    | +--------------+ |   ..................            :   | +------------+ |
-    | |              v v   v            :   :            v   v v            | |
-    | |           +-----------+         :   :         +-----------+         | |
-    | |           | Alice MSK |         :   :         |  Bob MSK  |         | |
-    | |           +-----------+         :   :         +-----------+         | |
-    | |             |       :           :   :           :       |           | |
-    | |          +--+       :...        :   :        ...:       +--+        | |
+    | +--------------+ |  ...................            :   | +------------+ |
+    | |              v v  v             :   :            v   v v            | |
+    | |           +----------+          :   :         +----------+          | |
+    | |           | Alice MK |          :   :         |  Bob MK  |          | |
+    | |           +----------+          :   :         +----------+          | |
+    | |             |      :            :   :           :      |            | |
+    | |          +--+      :....        :   :        ...:      +---+        | |
     | |          v             v        :   :        v             v        | |
     | |    +-----------+ .............  :   :  ............. +-----------+  | |
     | |    | Alice SSK | : Alice USK :  :   :  :  Bob USK  : |  Bob SSK  |  | |
@@ -1004,11 +1006,11 @@ signatures that she cannot see:
     +------------------+                +----------------+   +----------------+
     | +--------------+ |                |                |   | +------------+ |
     | |              v v                |                v   v v            | |
-    | |           +-----------+         |             +-----------+         | |
-    | |           | Alice MSK |         |             |  Bob MSK  |         | |
-    | |           +-----------+         |             +-----------+         | |
-    | |             |       |           |                       |           | |
-    | |          +--+       +--+        |                       +--+        | |
+    | |           +----------+          |             +----------+          | |
+    | |           | Alice MK |          |             |  Bob MK  |          | |
+    | |           +----------+          |             +----------+          | |
+    | |             |      |            |                      |            | |
+    | |          +--+      +---+        |                      +---+        | |
     | |          v             v        |                          v        | |
     | |    +-----------+ +-----------+  |                    +-----------+  | |
     | |    | Alice SSK | | Alice USK |  |                    |  Bob SSK  |  | |
@@ -1024,16 +1026,16 @@ signatures that she cannot see:
 ```
 
 [Verification methods](#device-verification) can be used to verify a
-user's master key by using the master public key, encoded using unpadded
+user's master key by treating the master public key, encoded using unpadded
 base64, as the device ID, and treating it as a normal device. For
 example, if Alice and Bob verify each other using SAS, Alice's
 `m.key.verification.mac` message to Bob may include
 `"ed25519:alices+master+public+key": "alices+master+public+key"` in the
 `mac` property. Servers therefore must ensure that device IDs will not
-collide with cross-signing public keys.
+collide with public keys used for cross-signing.
 
-The cross-signing private keys can be stored on the server or shared with other
-devices using the [Secrets](#secrets) module.  When doing so, the master,
+Using the [Secrets](#secrets) module the private keys used for cross-signing can
+be stored on the server or shared with other devices.  When doing so, the master,
 user-signing, and self-signing keys are identified using the names
 `m.cross_signing.master`, `m.cross_signing.user_signing`, and
 `m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
@@ -1052,14 +1054,14 @@ If a user's client sees that any other user has changed their master
 key, that client must notify the user about the change before allowing
 communication between the users to continue.
 
-Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
-(`ed25519:PUBLIC_KEY`) occupy the same namespace, clients must ensure that they
-use the correct keys when verifying.
+Since device key IDs (`ed25519:DEVICE_ID`) as well as master, user-signing and
+self-signing key IDs (`ed25519:PUBLIC_KEY`) occupy the same namespace, clients
+must ensure that they use the correct keys when verifying.
 
-While servers MUST not allow devices to have the same IDs as cross-signing
-keys, a malicious server could construct such a situation, so clients must not
-rely on the server being well-behaved and should take the following precautions
-against this.
+While servers MUST not allow devices to have the same IDs as keys used for
+cross-signing, a malicious server could construct such a situation, so clients
+must not rely on the server being well-behaved and should take the following
+precautions against this:
 
 1. Clients MUST refer to keys by their public keys during the verification
    process, rather than only by the key ID.
@@ -1067,7 +1069,8 @@ against this.
    verification process, and ensure that they do not change in the course of
    verification.
 3. Clients SHOULD also display a warning and MUST refuse to verify a user when
-   they detect that the user has a device with the same ID as a cross-signing key.
+   they detect that the user has a device with the same ID as a key used for
+   cross-signing.
 
 A user's user-signing and self-signing keys are intended to be easily
 replaceable if they are compromised by re-issuing a new key signed by
@@ -1104,7 +1107,7 @@ user-signing keys.
 
 Verifying by QR codes provides a quick way to verify when one of the parties
 has a device capable of scanning a QR code. The QR code encodes both parties'
-master signing keys as well as a random shared secret that is used to allow
+master keys as well as a random shared secret that is used to allow
 bi-directional verification from a single scan.
 
 To advertise the ability to show a QR code, clients use the names
@@ -1202,15 +1205,14 @@ The binary segment MUST be of the following form:
     bytes of the ID as a UTF-8 string
   - the ID encoded as a UTF-8 string
 - the first key, as 32 bytes.  The key to use depends on the mode field:
-  - if `0x00` or `0x01`, then the current user's own master cross-signing public key
+  - if `0x00` or `0x01`, then the current user's own master public key
   - if `0x02`, then the current device's Ed25519 signing key
 - the second key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00`, then what the device thinks the other user's master
-    cross-signing public key is
+    public key is
   - if `0x01`, then what the device thinks the other device's Ed25519 signing
     public key is
-  - if `0x02`, then what the device thinks the user's master cross-signing public
-    key is
+  - if `0x02`, then what the device thinks the user's master public key is
 - a random shared secret, as a sequence of bytes.  It is suggested to use a secret
   that is about 8 bytes long.  Note: as we do not share the length of the
   secret, and it is not a fixed size, clients will just use the remainder of
@@ -1221,14 +1223,14 @@ For example, if Alice displays a QR code encoding the following binary data:
 ```
       "MATRIX"    |ver|mode| len   | event ID
  4D 41 54 52 49 58  02  00   00 2D   21 41 42 43 44 ...
-| user's cross-signing key    | other user's cross-signing key | shared secret
-  00 01 02 03 04 05 06 07 ...   10 11 12 13 14 15 16 17 ...      20 21 22 23 24 25 26 27
+| the first key               | the second key              | shared secret
+  00 01 02 03 04 05 06 07 ...   10 11 12 13 14 15 16 17 ...   20 21 22 23 24 25 26 27
 ```
 
-this indicates that Alice is verifying another user (say Bob), in response to
-the request from event "$ABCD...", her cross-signing key is
+Mode `0x00` indicates that Alice is verifying another user (say Bob), in
+response to the request from event "$ABCD...", her master key is
 `0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
-Bob's cross-signing key is `1011121314151617...` (which is "EBESExQVFh..." in
+Bob's master key is `1011121314151617...` (which is "EBESExQVFh..." in
 base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
 base64).
 
@@ -1300,8 +1302,8 @@ one of its variants.
 Clients must only store keys in backups after they have ensured that the
 `auth_data` is trusted. This can be done either by:
 
-- checking that it is signed by the user's [master cross-signing
-  key](#cross-signing) or by a verified device belonging to the same user, or
+- checking that it is signed by the user's [master key](#cross-signing)
+  or by a verified device belonging to the same user, or
 - deriving the public key from a private key that it obtained from a trusted
   source. Trusted sources for the private key include the user entering the
   key, retrieving the key stored in [secret storage](#secret-storage), or
@@ -1786,13 +1788,14 @@ a way to identify the server's support for fallback keys.
 
 | Parameter  | Type      | Description                                                                                                                                                      |
 |------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| changed    | [string]  | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
+| changed    | [string]  | List of users who have updated their device identity or their master, self-signing or user-signing keys, or who now share an encrypted room with the client since the previous sync response. |
 | left       | [string]  | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
 
 {{% boxes/note %}}
 For optimal performance, Alice should be added to `changed` in Bob's
-sync only when she updates her devices or cross-signing keys, or when
-Alice and Bob now share a room but didn't share any room previously.
+sync only when she updates her devices or master, self-signing or
+user-signing keys, or when Alice and Bob now share a room but didn't
+share any room previously.
 However, for the sake of simpler logic, a server may add Alice to
 `changed` when Alice and Bob share a new room, even if they previously
 already shared a room.

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

data/api/client-server/cross_signing.yaml

@@ -21,16 +21,16 @@ paths:
       x-addedInMatrixVersion: "1.1"
       x-changedInMatrixVersion:
         "1.11": UIA is not always required for this endpoint.
-      summary: Upload cross-signing keys.
+      summary: Upload keys used for cross-signing.
       description: |-
-        Publishes cross-signing keys for the user.
+        Publishes keys used for cross-signing for the user.
 
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         User-Interactive Authentication MUST be performed, except in these cases:
-        - there is no existing cross-signing master key uploaded to the homeserver, OR
-        - there is an existing cross-signing master key and it exactly matches the
-          cross-signing master key provided in the request body. If there are any additional
+        - there is no existing master key uploaded to the homeserver, OR
+        - there is an existing master key and it exactly matches the
+          master key provided in the request body. If there are any additional
           keys provided in the request (self-signing key, user-signing key) they MUST also
           match the existing keys stored on the server. In other words, the request contains
           no new keys.

data/api/client-server/definitions/cross_signing_key.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 type: object
 title: CrossSigningKey
-description: Cross signing key
+description: Key used for cross signing
 properties:
   user_id:
     type: string

data/api/client-server/keys.yaml

@@ -219,7 +219,7 @@ paths:
                     x-addedInMatrixVersion: "1.1"
                     type: object
                     description: |-
-                      Information on the master cross-signing keys of the queried users.
+                      Information on the master keys of the queried users.
                       A map from user ID, to master key information.  For each key, the
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`, along with the signatures

data/api/client-server/profile.yaml

@@ -16,48 +16,117 @@ info:
   title: Matrix Client-Server Profile API
   version: 1.0.0
 paths:
-  "/profile/{userId}/displayname":
+  "/profile/{userId}/{keyName}":
     put:
-      summary: Set the user's display name.
+      x-changedInMatrixVersion:
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+      summary: Set a profile field for a user.
       description: |-
-        This API sets the given user's display name. You must have permission to
-        set this user's display name, e.g. you need to have their `access_token`.
-      operationId: setDisplayName
+        Set or update a profile field for a user. Must be authenticated with an
+        access token authorised to make changes. Servers MAY impose size limits
+        on individual fields, and the total profile MUST be under 64 KiB.
+
+        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
+        them rather than treating `null` as a deletion request. Clients that want to delete a
+        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+      operationId: setProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to set.
+          description: The user whose profile field should be set.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: keyName
+          description: The name of the profile field to set. This MUST be either
+            `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
+        description: A JSON object containing the property whose name matches
+          the `keyName` specified in the URL. See `additionalProperties` for
+          further details.
+        required: true
         content:
           application/json:
             schema:
               type: object
-              example: {
-                "displayname": "Alice Margatroid"
-              }
-              properties:
-                displayname:
-                  type: string
-                  description: The new display name for this user.
-        description: The new display name information.
-        required: true
+              minProperties: 1
+              description: |
+                An object which contains exactly one property. The key
+                of that property MUST match the `keyName` specified in the URL.
+                
+                For `avatar_url`, the value MUST be an MXC URI string. 
+                
+                For `displayname`, the value MUST be a string.
+                
+                For custom keys, any JSON type is allowed. Servers MAY not validate
+                these values, but clients SHOULD follow the format defined for that key.
+              additionalProperties: true
+              example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
-          description: The display name was set.
+          description: The profile field was set.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object # empty JSON object
               examples:
                 response:
                   value: {}
+        "400":
+          description: |
+            The input was invalid in some way. This can include one
+            of the following error codes:
+            
+            - `M_BAD_JSON`: The provided value is not valid JSON.
+            - `M_MISSING_PARAM`: The required `keyName` property is
+              missing from the request body.
+            - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
+              make the profile exceed its maximum allowed size of 64 KiB.
+            - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the
+              maximum allowed key length of 255 bytes.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    {
+                      "errcode": "M_BAD_JSON",
+                      "error": "Malformed JSON payload.",
+                    }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The server is unwilling to perform the operation, either
+            due to insufficient permissions or because profile modifications
+            are disabled.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -67,98 +136,125 @@ paths:
       tags:
         - User data
     get:
-      summary: Get the user's display name.
-      description: |-
-        Get the user's display name. This API may be used to fetch the user's
-        own displayname or to query the name of other users; either locally or
-        on remote homeservers.
-      operationId: getDisplayName
+      x-changedInMatrixVersion:
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+      summary: Get a profile field for a user.
+      description: Get the value of a profile field for a user.
+      operationId: getProfileField
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to get.
+          description: The user whose profile field should be returned.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: keyName
+          description: The name of the profile field to retrieve.
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The display name for this user.
+          description: The profile field value was retrieved.
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  displayname:
-                    type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
+                description: |
+                  An object with one property, whose key matches the `keyName` specified
+                  in the URL, and whose value is the current setting of that profile field.
+                additionalProperties: true
               examples:
                 response:
-                  value: {
-                    "displayname": "Alice Margatroid"
-                  }
+                  value: { "displayname": "Alice" }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has a display name.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has the specified profile field.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no display name for this user or this user does not exist.
+          description: There is no profile field with this key for this user, or
+            the user does not exist.
       tags:
         - User data
-  "/profile/{userId}/avatar_url":
-    put:
-      summary: Set the user's avatar URL.
-      description: |-
-        This API sets the given user's avatar URL. You must have permission to
-        set this user's avatar URL, e.g. you need to have their `access_token`.
-      operationId: setAvatarUrl
+    delete:
+      x-addedInMatrixVersion: "1.16"
+      summary: Remove a profile field from a user.
+      description: Remove a specific field from a user's profile.
+      operationId: deleteProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose avatar URL to set.
+          description: The user whose profile field should be deleted.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example: {
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
-              }
-              properties:
-                avatar_url:
-                  type: string
-                  format: uri
-                  description: The new avatar URL for this user.
-        description: The new avatar information.
-        required: true
+        - in: path
+          name: keyName
+          description: The name of the profile field to delete.
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The avatar URL was set.
+          description: The profile field was deleted or it doesn't exist.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object
               examples:
                 response:
                   value: {}
+        "400":
+          description: The request is malformed, contains invalid JSON, or
+            specifies an invalid key.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The user is not authorised to delete this profile field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -167,63 +263,11 @@ paths:
                 $ref: definitions/errors/rate_limited.yaml
       tags:
         - User data
-    get:
-      summary: Get the user's avatar URL.
-      description: |-
-        Get the user's avatar URL. This API may be used to fetch the user's
-        own avatar URL or to query the URL of other users; either locally or
-        on remote homeservers.
-      operationId: getAvatarUrl
-      parameters:
-        - in: path
-          name: userId
-          description: The user whose avatar URL to get.
-          required: true
-          example: "@alice:example.com"
-          schema:
-            type: string
-      responses:
-        "200":
-          description: The avatar URL for this user.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  avatar_url:
-                    type: string
-                    format: uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
-              examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-                  }
-        "403":
-          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has an avatar URL.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
-        "404":
-          description: There is no avatar URL for this user or this user does not exist.
-      tags:
-        - User data
   "/profile/{userId}":
     get:
-      summary: Get this user's profile information.
+      summary: Get all profile information for a user.
       description: |-
-        Get the combined profile information for this user. This API may be used
-        to fetch the user's own profile information or other users; either
-        locally or on remote homeservers.
+        Get the complete profile for a user.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -243,45 +287,49 @@ paths:
                 properties:
                   avatar_url:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
                     description: The user's avatar URL if they have set one, otherwise not present.
                   displayname:
                     type: string
                     description: The user's display name if they have set one, otherwise not
                       present.
+                additionalProperties:
+                  x-addedInMatrixVersion: "1.16"
+                  description: Additional profile fields.
               examples:
                 response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                    "displayname": "Alice Margatroid"
-                  }
+                  value:
+                    {
+                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                      "displayname": "Alice Margatroid",
+                      "m.example_field": "custom_value",
+                    }
         "403":
           x-addedInMatrixVersion: "1.2"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has profile information.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has profile information.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no profile information for this user or this user does not
-            exist.
+          description: There is no profile information for this user or this
+            user does not exist.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Profile not found"
-                  }
+                  value:
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
       tags:
         - User data
 servers:

data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml

@@ -17,7 +17,7 @@ type: object
 title: m.signing_key_update
 description: |-
   An EDU that lets servers push details to each other when one of their users
-  updates their cross-signing keys.
+  updates their keys used for cross-signing.
 allOf:
   - $ref: ../edu.yaml
   - type: object
@@ -34,7 +34,7 @@ allOf:
         properties:
           user_id:
             type: string
-            description: The user ID whose cross-signing keys have changed.
+            description: The user ID whose keys have changed.
             example: "@alice:example.com"
           master_key:
             allOf:

data/api/server-server/user_devices.yaml

@@ -79,7 +79,7 @@ paths:
                         - keys
                   master_key:
                     type: object
-                    description: The user\'s master cross-signing key.
+                    description: The user\'s master key.
                     allOf:
                       - $ref: ../client-server/definitions/cross_signing_key.yaml
                       - example:

data/api/server-server/user_keys.yaml

@@ -194,7 +194,7 @@ paths:
                     x-addedInMatrixVersion: "1.1"
                     type: object
                     description: |-
-                      Information on the master cross-signing keys of the queried users.
+                      Information on the master keys of the queried users.
                       A map from user ID, to master key information.  For each key, the
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`, along with the signatures