Merge 4ceec843a9 into be21886a73

Signed-off-by: Kierre Sametti vel@riseup.net

changelogs/client_server/newsfragments/2301.feature

@@ -0,0 +1 @@
+Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).

changelogs/client_server/newsfragments/2306.clarification

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

changelogs/client_server/newsfragments/2316.clarification

@@ -0,0 +1 @@
+Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI.

changelogs/room_versions/newsfragments/2297.clarification

@@ -0,0 +1 @@
+Clarify meaning of floating-point powerlevels.

changelogs/server_server/newsfragments/2284.clarification

@@ -0,0 +1 @@
+Specify validation for PDUs passed to and returned from federation membership endpoints.

changelogs/server_server/newsfragments/2319.removal

@@ -0,0 +1 @@
+Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376).

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

@@ -5,6 +5,91 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be
 created whose conversation contents are not decryptable or interceptable
 on any of the participating homeservers.
 
+#### Recommended client behaviour
+
+{{% added-in v="1.18" %}}
+
+While clients are able to choose what encryption features they implement based
+on their threat model, this section recommends behaviours that will improve the
+overall user experience and security of encrypted conversations.
+
+While a user may be unable to [verify](#device-verification) every other user
+that they communicate with, or may be unaware of the need to verify other users,
+[cross-signing](#cross-signing) gives some measure of protection and so SHOULD
+be used where possible. In particular, clients SHOULD implement the following
+recommendations.
+
+* Clients SHOULD create new [cross-signing keys](#cross-signing) for users who
+  do not yet have cross-signing keys.
+* Clients SHOULD encourage users to set up their [Secret Storage](#storage) to
+  avoid needing to reset their cryptographic identity in case the user does not
+  have an existing device that can [share the secrets](#sharing) with the new
+  device. The user's Secret Storage SHOULD contain the user's cross-signing
+  private keys and the [key backup](#server-side-key-backups) decryption key
+  (if the user is using key backup). The user's Secret Storage SHOULD have a
+  [default key](#key-storage) (a key referred to by
+  `m.secret_storage.default_key`) that encrypts the private cross-signing keys
+  and key backup decryption key (if available).
+* Clients SHOULD encourage users to [cross-sign](#cross-signing) their devices.
+  This includes both when logging in a new device, and for existing devices.
+  Clients MAY even go so  far as to require cross-signing of devices by
+  preventing the user from using  the client until the device is cross-signed.
+  If the user cannot cross-sign their device (for example, if they have
+  forgotten their Secret Storage key), the client can allow users to reset their
+  [Secret Storage](#storage), cross-signing keys, and [key backup](#server-side-key-backups).
+* When Alice [verifies](#device-verification) Bob, the verification SHOULD
+  verify their [cross-signing keys](#cross-signing). Any flow between different
+  users that does not verify the users' cross-signing keys (it verifies only the
+  device keys) is deprecated.
+* Clients SHOULD flag when [cross-signing keys](#cross-signing) change. If
+  Alice's cross-signing keys change, Alice's own devices MUST alert her to this
+  fact, and prompt her to re-cross-sign those devices. If Bob is in an
+  encrypted room with Alice,  Bob's devices SHOULD inform him of Alice's key
+  change and SHOULD prevent him from sending an encrypted message to Alice
+  without acknowledging the change. Bob's clients may behave differently
+  depending on whether Bob had previously [verified](#device-verification)
+  Alice or not. For example, if Bob had previously verified Alice, and Alice's
+  keys change, Bob's client may require Bob to re-verify, or may display a more
+  aggressive warning.
+* Clients SHOULD NOT send encrypted [to-device](#send-to-device-messaging)
+  messages, such as [room keys](#sharing-keys-between-devices) or [secrets](#secrets)
+  (via [Secret Sharing](#sharing)), to [non-cross-signed](#cross-signing)
+  devices by default. Non-cross-signed devices don't provide any assurance that
+  the device belongs to the user, and server admins can trivially create new
+  devices for users. When sending room keys, clients can use a
+  [`m.room_key.withheld`](#mroom_keywithheld) message with a code of
+  `m.unverified` to indicate to the non-cross-signed device why it is not
+  receiving the room key.
+
+  Note that clients cannot selectively send room events only to cross-signed
+  devices. The only way to exclude non-cross-signed devices from encrypted
+  conversations is to not send the room keys so those devices won't be able to
+  decrypt the messages.
+* Similarly, messages sent from [non-cross-signed](#cross-signing) devices
+  cannot be trusted and SHOULD NOT be displayed to the user. Clients have no
+  assurance that encrypted messages sent from non-cross-signed devices were sent
+  by the user, rather than an impersonator.
+* Matrix clients MUST NOT consider non-cryptographic devices (devices which do
+  not have [device identity keys](#device-keys) uploaded to the homeserver) to
+  be equivalent to [non-cross-signed](#cross-signing) cryptographic devices for
+  purposes of enforcing E2EE policy. For example, clients SHOULD NOT warn nor
+  refuse to send messages due to the presence of non-cryptographic devices. For
+  all intents and purposes, non-cryptographic devices are a completely separate
+  concept and do not exist from the perspective of the cryptography layer since
+  they do not have identity keys, so it is impossible to send them decryption
+  keys.
+* Clients MAY make provisions for encrypted bridges. Some bridges are structured
+  in a way such that only one user controlled by the bridge (often called the
+  bridge bot) participates in encryption, and encrypted messages from other
+  bridge users are encrypted by the bridge bot. Thus encrypted messages sent by
+  one user could be encrypted by a [Megolm](#mmegolmv1aes-sha2) session sent by
+  a different user. Clients MAY accept such messages, provided the session
+  creator's device is [cross-signed](#cross-signing). However, the client MUST
+  annotate the message with a warning, unless the client has a way to check that
+  the bridge bot is permitted to encrypt messages on behalf of the user. Future
+  MSCs such as [MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
+  may provide a secure way to allow such impersonation.
+
 #### Key Distribution
 
 Encryption and Authentication in Matrix is based around public-key
@@ -93,7 +178,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 used for [cross-signing](#cross-signing).
 
 `signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
 
@@ -674,8 +759,11 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 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
+    * {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
-      device ed25519 key and their master cross-signing key).
+      to verify (usually their device ed25519 key and their master signing key, 
+      see below). The master signing key SHOULD be included when two different
+      users are verifying each other. Verifying individual devices of other
+      users is deprecated.
     * The complete list of key IDs that they wish the other user to verify.
 
     The MAC calculation is defined [below](#mac-calculation).
@@ -931,40 +1019,42 @@ 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 cross-signing 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 (cross-signing keys):
 
--   a master key (MSK) that serves as the user's identity in
+-   a master signing key (MSK, for historical reasons sometimes known as
-    cross-signing and signs their other cross-signing keys;
+    `master_key`) 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 signing 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
+The master signing key may also be used to sign other items such as the backup
-key. The master key may also be signed by the user's own device keys to
+key. The master signing key may also be signed by the user's own device keys to
 aid in migrating from device verifications: if Alice's device had
 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
+key, then Alice's device can trust Bob's master signing 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 parts of their master signing, user-signing and
+self-signing keys 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 cross-signing keys.
 
 If Alice has a device and wishes to send an encrypted message to Bob,
 she can trust Bob's device if:
 
--   Alice's device is using a master key that has signed her
+-   Alice's device is using a master signing key that has signed her
     user-signing key,
--   Alice's user-signing key has signed Bob's master key,
+-   Alice's user-signing key has signed Bob's master signing key,
--   Bob's master key has signed Bob's self-signing key, and
+-   Bob's master signing key has signed Bob's self-signing key, and
 -   Bob's self-signing key has signed Bob's device key.
 
 The following diagram illustrates how keys are signed:
@@ -1024,27 +1114,28 @@ 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 signing key by treating its public key (master signing public
-base64, as the device ID, and treating it as a normal device. For
+key), encoded using unpadded base64, as the device ID, and treating it as a
-example, if Alice and Bob verify each other using SAS, Alice's
+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.
 
-The cross-signing private keys can be stored on the server or shared with other
+Using the [Secrets](#secrets) module the private parts of the cross-signing keys can
-devices using the [Secrets](#secrets) module.  When doing so, the master,
+be stored on the server or shared with other devices.  When doing so, the
-user-signing, and self-signing keys are identified using the names
+master signing, user-signing, and self-signing keys are identified using the
-`m.cross_signing.master`, `m.cross_signing.user_signing`, and
+names `m.cross_signing.master`, `m.cross_signing.user_signing`, and
 `m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
 before being encrypted.
 
 ###### Key and signature security
 
-A user's master key could allow an attacker to impersonate that user to
+A user's master signing key could allow an attacker to impersonate that user to
 other users, or other users to that user. Thus clients must ensure that
-the private part of the master key is treated securely. If clients do
+the private part of the master signing key is treated securely. If clients do
-not have a secure means of storing the master key (such as a secret
+not have a secure means of storing the master signing key (such as a secret
 storage system provided by the operating system), then clients must not
 store the private part.
 
@@ -1057,9 +1148,9 @@ Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
 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
+keys, a malicious server could construct such a situation, so clients
-rely on the server being well-behaved and should take the following precautions
+must not rely on the server being well-behaved and should take the following
-against this.
+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,31 +1158,32 @@ 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 cross-signing
+   key.
 
 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
-the user's master key and possibly by re-verifying devices or users.
+the user's master signing key and possibly by re-verifying devices or users.
 However, doing so relies on the user being able to notice when their
 keys have been compromised, and it involves extra work for the user, and
 so although clients do not have to treat the private parts as
-sensitively as the master key, clients should still make efforts to
+sensitively as the master signing key, clients should still make efforts to
 store the private part securely, or not store it at all. Clients will
 need to balance the security of the keys with the usability of signing
 users and devices when performing key verification.
 
 To avoid leaking of social graphs, servers will only allow users to see:
 
--   signatures made by the user's own master, self-signing or
+-   signatures made by the user's own master signing, self-signing or
     user-signing keys,
 -   signatures made by the user's own devices about their own master
     key,
 -   signatures made by other users' self-signing keys about their
     respective devices,
--   signatures made by other users' master keys about their respective
+-   signatures made by other users' master signing keys about their respective
     self-signing key, or
 -   signatures made by other users' devices about their respective
-    master keys.
+    master signing keys.
 
 Users will not be able to see signatures made by other users'
 user-signing keys.
@@ -1193,24 +1285,24 @@ The binary segment MUST be of the following form:
 - one byte indicating the QR code verification mode.  Should be one of the
   following values:
   - `0x00` verifying another user with cross-signing
-  - `0x01` self-verifying in which the current device does trust the master key
+  - `0x01` self-verifying in which the current device does trust the master signing key
   - `0x02` self-verifying in which the current device does not yet trust the
-    master key
+    master signing key
 - the event ID or `transaction_id` of the associated verification
   request event, encoded as:
   - two bytes in network byte order (big-endian) indicating the length in
     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 signing 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
+  - if `0x02`, then what the device thinks the user's master signing public key
-    key is
+    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 +1313,14 @@ For example, if Alice displays a QR code encoding the following binary data:
 ```nohighlight
       "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
+| 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
+Mode `0x00` indicates that Alice is verifying another user (say Bob), in
-the request from event "$ABCD...", her cross-signing key is
+response to the request from event "$ABCD...", her master signing 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 signing key is `1011121314151617...` (which is "EBESExQVFh..." in
 base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
 base64).
 
@@ -1300,8 +1392,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
+- checking that it is signed by the user's [master signing key](#cross-signing)
-  key](#cross-signing) or by a verified device belonging to the same user, or
+  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

content/rooms/fragments/v1-floaty-power-levels.md

@@ -0,0 +1,41 @@
+
+##### `m.room.power_levels` events accept values as floats
+
+When the value is a float
+ * First, exponential notation is applied: `5.114698E4` becomes `51146.98`
+ * Second, the value is truncated at the decimal point: `51146.98` becomes `51146`.
+
+Values outside the range represented by IEE754 binary64 (a "double") cause the
+powerlevel event to be rejected, as do `Infinity`, `-Infinity` and `NaN`.
+
+For example, this is a valid `m.room.power_levels` event in this room version:
+
+```json
+{
+  "content": {
+    "ban": 50,
+    "events": {
+      "m.room.power_levels": 100
+    },
+    "events_default": 0,
+    "state_default": 50,
+    "users": {
+      "@example:example.org": 100,
+      "@alice:localhost": 50,
+      "@bob:localhost": 50.57
+    },
+    "users_default": 0
+  },
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
+  "sender": "@example:example.org",
+  "state_key": "",
+  "type": "m.room.power_levels"
+}
+```
+
+In this example, both `@bob:localhost` and `@alice:localhost` have the same effective
+power level of `50`, even though the values are technically different.
+
+Note that, since this room version does not enforce that events comply with the requirements
+of [Canonical JSON](/appendices#canonical-json), power levels can be formatted as floats.

content/rooms/v1.md

@@ -59,6 +59,8 @@ Events in version 1 rooms have the following structure:
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v1-auth-rules" %}}

content/rooms/v2.md

@@ -57,6 +57,8 @@ Events in rooms of this version have the following structure:
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v1-auth-rules" %}}

content/rooms/v3.md

@@ -87,6 +87,8 @@ The complete structure of a event in a v3 room is shown below.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% boxes/note %}}

content/rooms/v4.md

@@ -76,6 +76,8 @@ the changes in this room version.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v3-auth-rules" %}}

content/rooms/v5.md

@@ -58,6 +58,8 @@ completeness.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v3-auth-rules" %}}

content/rooms/v6.md

@@ -42,7 +42,8 @@ in [room version 5](/rooms/v5).
 ### Event format
 
 {{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
-the `depth` limit has been reduced in this room version.
+the `depth` limit has been reduced in this room version, and numeric values may
+no longer be formatted as floats.
 
 {{% rver-fragment name="v6-event-format" %}}
 

content/server-server-api.md

@@ -868,8 +868,10 @@ selecting a resident from the candidate list, and using the
 enough information for the joining server to fill in the event.
 
 The joining server is expected to add or replace the `origin`,
-`origin_server_ts`, and `event_id` on the templated event received by
+`origin_server_ts`, and `event_id` on the templated event received by the
-the resident server. This event is then signed by the joining server.
+resident server. The joining server MUST also verify that the `type`, `room_id`,
+`sender`, `state_key` and `content.membership` fields have the expected values.
+This event is then signed by the joining server.
 
 To complete the join handshake, the joining server submits this new event
 to the resident server it used for `GET /make_join`, using the `PUT /send_join`

data/api/client-server/cross_signing.yaml

@@ -32,9 +32,9 @@ paths:
         except when used by an application service.
 
         User-Interactive Authentication MUST be performed for regular clients, except in these cases:
-        - there is no existing cross-signing master key uploaded to the homeserver, OR
+        - there is no existing master signing key uploaded to the homeserver, OR
-        - there is an existing cross-signing master key and it exactly matches the
+        - there is an existing master signing key and it exactly matches the
-          cross-signing master key provided in the request body. If there are any additional
+          master signing 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.
@@ -61,22 +61,22 @@ paths:
               type: object
               properties:
                 master_key:
-                  description: Optional. The user\'s master key.
+                  description: Optional. The user\'s master signing key.
                   allOf:
                     - $ref: definitions/cross_signing_key.yaml
                 self_signing_key:
                   description: |-
                     Optional. The user\'s self-signing key. Must be signed by
-                    the accompanying master key, or by the user\'s most recently
+                    the accompanying master signing key, or by the user\'s most recently
-                    uploaded master key if no master key is included in the
+                    uploaded master signing key if no master signing key is included in the
                     request.
                   allOf:
                     - $ref: definitions/cross_signing_key.yaml
                 user_signing_key:
                   description: |-
                     Optional. The user\'s user-signing key. Must be signed by
-                    the accompanying master key, or by the user\'s most recently
+                    the accompanying master signing key, or by the user\'s most recently
-                    uploaded master key if no master key is included in the
+                    uploaded master signing key if no master signing key is included in the
                     request.
                   allOf:
                     - $ref: definitions/cross_signing_key.yaml
@@ -147,7 +147,7 @@ paths:
 
             * `M_INVALID_SIGNATURE`: For example, the self-signing or
               user-signing key had an incorrect signature.
-            * `M_MISSING_PARAM`: No master key is available.
+            * `M_MISSING_PARAM`: No master signing key is available.
           content:
             application/json:
               schema:

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
@@ -44,8 +44,8 @@ properties:
     title: Signatures
     description: |-
       Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
-      Optional for the master key. Other keys must be signed by the
+      Optional for the master signing key. Other keys must be signed by the
-      user\'s master key.
+      user\'s master signing key.
     example: {
         "@alice:example.com": {
             "ed25519:alice+base64+master+key": "signature+of+key"

data/api/client-server/keys.yaml

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

data/api/client-server/login.yaml

@@ -70,6 +70,21 @@ paths:
                       }
                     ]
                   }
+        "404":
+          description: |-
+            With `M_UNRECOGNIZED`: the homeserver does not support the legacy authentication API.
+            (See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_UNRECOGNIZED",
+                      "error": "OAuth 2.0 authentication is in use on this homeserver.",
+                    }
         "429":
           description: This request was rate-limited.
           content:

data/api/client-server/oauth_server_metadata.yaml

@@ -208,6 +208,21 @@ paths:
                     "org.matrix.cross_signing_reset",
                   ],
                 }
+        "404":
+          description: |-
+            With `M_UNRECOGNIZED`: the homeserver does not support the OAuth 2.0 API.
+            (See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_UNRECOGNIZED",
+                      "error": "Legacy authentication is in use on this homeserver.",
+                    }
       tags:
         - Session management
 servers:

data/api/server-server/invites-v1.yaml

@@ -36,6 +36,28 @@ paths:
         Also note that if the remote homeserver is already in the room, it will receive the
         invite event twice; once through this endpoint, and again through a [federation
         transaction](/server-server-api/#transactions).
+
+        Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
+        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        return `M_INVALID_PARAM` if:
+
+        * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `invite`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not a user ID on the receiving server.
+
+        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        SHOULD return `M_INVALID_PARAM` if:
+
+        * The `m.room.create` event is missing from `invite_room_state`.
+        * One or more entries in `invite_room_state` are not formatted according
+          to the room's version.
+        * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * One or more events does not reside in the same room as the invite.
+          Note: Some room versions may require calculating the room ID for an
+          event rather than relying on the presence of `room_id`.
       operationId: sendInviteV1
       security:
         - signedRequest: []
@@ -83,8 +105,7 @@ paths:
                             MUST additionally be formatted according to the room version specification.
 
                             Servers might need to apply validation to the `invite_room_state` depending
-                            on room version. See the `400 M_MISSING_PARAM` error definition for more
+                            on room version. See endpoint description for more information.
-                            information.
 
                             Note that events have a different format depending on the room
                             version - check the [room version specification](/rooms) for
@@ -178,23 +199,7 @@ paths:
                   }
         "400":
           description: |-
-            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            The request is invalid in some way.
-            the following:
-
-            * The `m.room.create` event is missing from `invite_room_state`.
-            * One or more entries in `invite_room_state` are not formatted according
-              to the room's version.
-            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
-            * One or more events does not reside in the same room as the invite.
-              Note: Some room versions may require calculating the room ID for an
-              event rather than relying on the presence of `room_id`.
-
-            Servers MAY apply the validation above to room versions 1 through 11,
-            and SHOULD apply the validation above to all other room versions.
-
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:
@@ -202,7 +207,7 @@ paths:
               examples:
                 response:
                   value: {
-                    "errcode": "M_MISSING_PARAM",
+                    "errcode": "M_INVALID_PARAM",
                     "error": "Create event not among invite state entries."
                   }
 servers:

data/api/server-server/invites-v2.yaml

@@ -40,6 +40,28 @@ paths:
         Also note that if the remote homeserver is already in the room, it will receive the
         invite event twice; once through this endpoint, and again through a [federation
         transaction](/server-server-api/#transactions).
+
+        Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
+        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        return `M_INVALID_PARAM` if:
+
+        * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `invite`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not a user ID on the receiving server.
+
+        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        SHOULD return `M_INVALID_PARAM` if:
+
+        * The `m.room.create` event is missing from `invite_room_state`.
+        * One or more entries in `invite_room_state` are not formatted according
+          to the room's version.
+        * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * One or more events does not reside in the same room as the invite.
+          Note: Some room versions may require calculating the room ID for an
+          event rather than relying on the presence of `room_id`.
       operationId: sendInviteV2
       security:
         - signedRequest: []
@@ -84,8 +106,7 @@ paths:
                     MUST additionally be formatted according to the room version specification.
 
                     Servers might need to apply validation to the `invite_room_state` depending
-                    on room version. See the `400 M_MISSING_PARAM` error definition for more
+                    on room version. See the endpoint description for more information.
-                    information.
 
                     Note that events have a different format depending on the room
                     version - check the [room version specification](/rooms) for
@@ -154,22 +175,8 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
-            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
-            the following:
+            with a Client-Server API request, the Client-Server API request SHOULD fail
-
-            * The `m.room.create` event is missing from `invite_room_state`.
-            * One or more entries in `invite_room_state` are not formatted according
-              to the room's version.
-            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
-            * One or more events does not reside in the same room as the invite.
-              Note: Some room versions may require calculating the room ID for an
-              event rather than relying on the presence of `room_id`.
-
-            Servers MAY apply the validation above to room versions 1 through 11,
-            and SHOULD apply the validation above to all other room versions.
-
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
             with a 5xx error rather than being passed through.
           content:
             application/json:

data/api/server-server/joins-v1.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a join event to get into the room.
+
+        Before signing the returned template and calling `/send_join`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `join`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to join through another server.
       operationId: makeJoin
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the join event will be for.
+          description: The user ID the join event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -223,171 +234,6 @@ paths:
                     "errcode": "M_NOT_FOUND",
                     "error": "Unknown room"
                   }
-  "/send_join/{roomId}/{eventId}":
-    put:
-      deprecated: true
-      summary: Submit a signed join event to a resident server
-      description: |-
-        **Note:**
-        Servers should instead prefer to use the v2 `/send_join` endpoint.
-
-        Submits a signed join event to the resident server for it
-        to accept it into the room's graph. Note that events have
-        a different format depending on the room version - check
-        the [room version specification](/rooms) for precise event formats.
-        **The request and response body here describe the common
-        event fields in more detail and may be missing other required
-        fields for a PDU.**
-      operationId: sendJoinV1
-      security:
-        - signedRequest: []
-      parameters:
-        - in: path
-          name: roomId
-          description: The room ID that is about to be joined.
-          required: true
-          example: "!abc123:matrix.org"
-          schema:
-            type: string
-        - in: path
-          name: eventId
-          description: The event ID for the join event.
-          required: true
-          example: $abc123:example.org
-          schema:
-            type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                sender:
-                  type: string
-                  description: The user ID of the joining member.
-                  example: "@someone:example.org"
-                origin:
-                  type: string
-                  description: The name of the joining homeserver.
-                  example: matrix.org
-                origin_server_ts:
-                  type: integer
-                  format: int64
-                  description: A timestamp added by the joining homeserver.
-                  example: 1234567890
-                type:
-                  type: string
-                  description: The value `m.room.member`.
-                  example: m.room.member
-                state_key:
-                  type: string
-                  description: The user ID of the joining member.
-                  example: "@someone:example.org"
-                content:
-                  type: object
-                  title: Membership Event Content
-                  description: The content of the event.
-                  example:
-                    membership: join
-                  properties:
-                    membership:
-                      type: string
-                      description: The value `join`.
-                      example: join
-                    join_authorised_via_users_server:
-                      type: string
-                      x-addedInMatrixVersion: "1.2"
-                      description: |-
-                        Required if the room is [restricted](/client-server-api/#restricted-rooms)
-                        and is joining through one of the conditions available. If the
-                        user is responding to an invite, this is not required.
-
-                        An arbitrary user ID belonging to the resident server in
-                        the room being joined that is able to issue invites to other
-                        users. This is used in later validation of the auth rules for
-                        the `m.room.member` event.
-
-                        The resident server which owns the provided user ID must have a
-                        valid signature on the event. If the resident server is receiving
-                        the `/send_join` request, the signature must be added before sending
-                        or persisting the event to other servers.
-                  required:
-                    - membership
-              required:
-                - state_key
-                - sender
-                - origin
-                - origin_server_ts
-                - type
-                - content
-        required: true
-      responses:
-        "200":
-          description: The join event has been accepted into the room.
-          content:
-            application/json:
-              schema:
-                type: array
-                minItems: 2
-                maxItems: 2
-                items:
-                  anyOf:
-                    - type: integer
-                      description: The value `200`.
-                      example: 200
-                    - type: object
-                      title: Room State
-                      description: The state for the room.
-                      properties:
-                        auth_chain:
-                          type: array
-                          description: |-
-                            The auth chain for the entire current room state prior to the join event.
-
-                            Note that events have a different format depending on the room version - check the
-                            [room version specification](/rooms) for precise event formats.
-                          items:
-                            type: object
-                            title: PDU
-                            description: |-
-                              The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
-                              on the room version - check the [room version specification](/rooms) for precise event formats.
-                        state:
-                          type: array
-                          description: |-
-                            The resolved current room state prior to the join event.
-
-                            The event format varies depending on the room version - check the [room version specification](/rooms)
-                            for precise event formats.
-                          items:
-                            type: object
-                            title: PDU
-                            description: |-
-                              The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
-                              on the room version - check the [room version specification](/rooms) for precise event formats.
-                      required:
-                        - auth_chain
-                        - state
-              examples:
-                response:
-                  value: [
-                    200,
-                    {
-                      "auth_chain": [
-                        {
-                          "$ref": "examples/minimal_pdu.json"
-                        }
-                      ],
-                      "state": [
-                        {
-                          "$ref": "examples/minimal_pdu.json"
-                        }
-                      ],
-                      "event": {
-                        "$ref": "examples/pdu_v4_join_membership.json"
-                      }
-                    }
-                  ]
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/joins-v2.yaml

@@ -22,15 +22,6 @@ paths:
     put:
       summary: Submit a signed join event to a resident server
       description: |-
-        **Note:**
-        This API is nearly identical to the v1 API with the
-        exception of the response format being fixed.
-
-        This endpoint is preferred over the v1 API as it provides
-        a more standardised response format. Senders which receive
-        a 400, 404, or other status code which indicates this endpoint
-        is not available should retry using the v1 API instead.
-
         Submits a signed join event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
@@ -38,6 +29,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `join`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendJoinV2
       security:
         - signedRequest: []
@@ -247,6 +247,10 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
+            with a Client-Server API request, the Client-Server API request SHOULD fail
+            with a 5xx error rather than being passed through.
+
             New in `v1.2`, the following error conditions might happen:
 
             If the room is [restricted](/client-server-api/#restricted-rooms)

data/api/server-server/knocks.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a knock event for the room.
+
+        Before signing the returned template and calling `/send_knock`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `knock`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to knock through another server.
       operationId: makeKnock
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the knock event will be for.
+          description: The user ID the knock event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -204,6 +215,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The knock event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `knock`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendKnock
       security:
         - signedRequest: []
@@ -330,6 +350,19 @@ paths:
                       "$ref": "./examples/invite_or_knock_state.json"
                     }
                   }
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a knock event."
+                  }
         "403":
           description: |-
             The knocking server or user is not permitted to knock on the room, such as when the

data/api/server-server/leaving-v1.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a leave event to get out of the room.
+
+        Before signing the returned template and calling `/send_leave`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `leave`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to leave through another server.
       operationId: makeLeave
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the leave event will be for.
+          description: The user ID the leave event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -138,117 +149,6 @@ paths:
                     "errcode": "M_FORBIDDEN",
                     "error": "User is not in the room."
                   }
-  "/send_leave/{roomId}/{eventId}":
-    put:
-      deprecated: true
-      summary: Submit a signed leave event to a resident server
-      description: |-
-        **Note:**
-        Servers should instead prefer to use the v2 `/send_leave` endpoint.
-
-        Submits a signed leave event to the resident server for it
-        to accept it into the room's graph. Note that events have
-        a different format depending on the room version - check
-        the [room version specification](/rooms) for precise event formats.
-        **The request and response body here describe the common
-        event fields in more detail and may be missing other required
-        fields for a PDU.**
-      operationId: sendLeaveV1
-      security:
-        - signedRequest: []
-      parameters:
-        - in: path
-          name: roomId
-          description: The room ID that is about to be left.
-          required: true
-          example: "!abc123:matrix.org"
-          schema:
-            type: string
-        - in: path
-          name: eventId
-          description: The event ID for the leave event.
-          required: true
-          example: $abc123:example.org
-          schema:
-            type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                sender:
-                  type: string
-                  description: The user ID of the leaving member.
-                  example: "@someone:example.org"
-                origin:
-                  type: string
-                  description: The name of the leaving homeserver.
-                  example: matrix.org
-                origin_server_ts:
-                  type: integer
-                  format: int64
-                  description: A timestamp added by the leaving homeserver.
-                  example: 1234567890
-                type:
-                  type: string
-                  description: The value `m.room.member`.
-                  example: m.room.member
-                state_key:
-                  type: string
-                  description: The user ID of the leaving member.
-                  example: "@someone:example.org"
-                content:
-                  type: object
-                  title: Membership Event Content
-                  description: The content of the event.
-                  example:
-                    membership: leave
-                  properties:
-                    membership:
-                      type: string
-                      description: The value `leave`.
-                      example: leave
-                  required:
-                    - membership
-                depth:
-                  type: integer
-                  description: This field must be present but is ignored; it may be 0.
-                  example: 12
-              required:
-                - state_key
-                - sender
-                - origin
-                - origin_server_ts
-                - type
-                - depth
-                - content
-        required: true
-      responses:
-        "200":
-          description: |-
-            An empty response to indicate the event was accepted into the graph by
-            the receiving homeserver.
-          content:
-            application/json:
-              schema:
-                type: array
-                minItems: 2
-                maxItems: 2
-                items:
-                  anyOf:
-                    - type: integer
-                      description: The value `200`.
-                      example: 200
-                    - type: object
-                      title: Empty Object
-                      description: An empty object.
-              examples:
-                response:
-                  value: [
-                    200,
-                    {}
-                  ]
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/leaving-v2.yaml

@@ -22,15 +22,6 @@ paths:
     put:
       summary: Submit a signed leave event to a resident server
       description: |-
-        **Note:**
-        This API is nearly identical to the v1 API with the
-        exception of the response format being fixed.
-
-        This endpoint is preferred over the v1 API as it provides
-        a more standardised response format. Senders which receive
-        a 400, 404, or other status code which indicates this endpoint
-        is not available should retry using the v1 API instead.
-
         Submits a signed leave event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
@@ -38,6 +29,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `leave`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendLeaveV2
       security:
         - signedRequest: []
@@ -134,6 +134,19 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

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 signing key.
                     allOf:
                       - $ref: ../client-server/definitions/cross_signing_key.yaml
                       - example:

data/api/server-server/user_keys.yaml

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