Apply suggestions from code review

Co-authored-by: Denis Kasak <dkasak@termina.org.uk>

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

@@ -996,16 +996,23 @@ 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 IDs and cross-signing keys occupy the same namespace, clients must
+Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
-ensure that they use the correct keys when verifying. While servers must not
+(`ed25519:PUBLIC_KEY`) occupy the same namespace, clients must ensure that they
-allow devices to have the same IDs as cross-signing keys, a malicious server
+use the correct keys when verifying.
-could construct such a situation, so clients must not rely on the server being
+
-well-behaved and should take precautions against this. For example, clients
+While servers MUST not allow devices to have the same IDs as cross-signing
-should refer to keys using the public keys rather than only by the device
+keys, a malicious server could construct such a situation, so clients must not
-ID. Clients should also fix the keys that are being verified, and ensure that
+rely on the server being well-behaved and should take the following precautions
-they do not change in the course of verification. Clients may also display a
+against this.
-warning and refuse to verify a user when it detects that the user has a device
+
-with the same ID as a cross-signing key.
+1. Clients MUST refer to keys by their public keys during the verification
+   process, rather than only by the key ID.
+2. Clients MUST fix the keys that are being verified at the beginning of the
+   verification process, and ensure that they do not change in the course of
+   verification.
+3. Clients SHOULD also display a warning and MAY refuse to verify a user when
+   it detects 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

data/event-schemas/schema/m.secret.request.yaml

@@ -26,7 +26,7 @@ properties:
         description: |-
           A random string uniquely identifying (with respect to the requester
           and the target) the target for a secret. If the secret is requested
-          from multiple devices at the same time, the same ID may be used for
+          from multiple devices at the same time, the same ID MAY be used for
           every target. The same ID is also used in order to cancel a previous
           request.
     required:

data/event-schemas/schema/m.secret.send.yaml

@@ -9,8 +9,8 @@ description: |-
   The `request_id` must match the ID previously given in an `m.secret.request`
   event. The recipient must ensure that this event comes from a device that the
   `m.secret.request` event was originally sent to, and that the device is
-  trusted. This should be done by checking the sender key of the Olm session that
+  a trusted device owned by the recipient. This should be done by checking the
-  the event was sent over.
+  sender key of the Olm session that the event was sent over.
 properties:
   content:
     properties: