Merge d96a10b92a into 1edf62c3f1

changelogs/appendices/newsfragments/2396.clarification

@@ -1 +0,0 @@
-Clarify that clients must avoid producing ambiguous matrix.to URIs. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2412.clarification

@@ -1 +0,0 @@
-Use the User ID type in OlmPayload and DeviceKeys.

changelogs/client_server/newsfragments/2418.clarification

@@ -1 +0,0 @@
-Rename OlmPayload to OlmPlaintext to avoid confusion with Olm message Payload Bytes.

content/appendices.md

@@ -887,22 +887,20 @@ https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
 
 The identifier may be a room ID, room alias, or user ID. The
 extra parameter is only used in the case of permalinks where an event ID
-is referenced. The matrix.to URI, when referenced, MUST always start
+is referenced. The matrix.to URI, when referenced, must always start
 with `https://matrix.to/#/` followed by the identifier.
 
 The `<additional arguments>` and the preceding question mark are
-OPTIONAL and only apply in certain circumstances, documented below.
+optional and only apply in certain circumstances, documented below.
 
-Clients SHOULD NOT rely on matrix.to URIs falling back to a web server
+Clients should not rely on matrix.to URIs falling back to a web server
-if accessed and instead SHOULD perform some sort of action within the
+if accessed and instead should perform some sort of action within the
 client. For example, if the user were to click on a matrix.to URI for a
-room alias, the client MAY open a view for the user to participate in
+room alias, the client may open a view for the user to participate in
 the room.
 
 The components of the matrix.to URI (`<identifier>` and
 `<extra parameter>`) MUST be percent-encoded as per RFC 3986.
-Failure to do so will result in downstream software misinterpreting
-the links as invalid/not turning them into clickable links in UI.
 
 Examples of matrix.to URIs are:
 

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

@@ -1762,9 +1762,12 @@ Messages with type 1 can only be decrypted with an existing session. If
 there is no matching session, the client must treat this as an invalid
 message.
 
-The plaintext corresponding to the "Cipher-Text" in an an [Olm message](/olm-megolm/olm/#normal-messages) is of the form:
+The plaintext payload is of the form:
 
-{{% definition path="api/client-server/definitions/olm_plaintext" %}}
+{{% definition path="api/client-server/definitions/olm_payload" %}}
+
+The type and content of the plaintext message event are given in the
+payload.
 
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully

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

@@ -20,8 +20,6 @@ properties:
     description: |-
       The ID of the user the device belongs to. Must match the user ID used
       when logging in.
-    format: mx-user-id
-    pattern: "^@"
     example: "@alice:example.com"
   device_id:
     type: string

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

@@ -14,9 +14,9 @@
 
 
 type: object
-title: OlmPlaintext
+title: OlmPayload
 description: |-
-  The plaintext of an event encrypted using Olm.
+  The plaintext payload of an event encrypted using Olm.
 properties:
   type:
     type: string
@@ -27,13 +27,9 @@ properties:
   sender:
     type: string
     description: The user ID of the event sender.
-    format: mx-user-id
-    pattern: "^@"
   recipient:
     type: string
     description: The user ID of the intended event recipient.
-    format: mx-user-id
-    pattern: "^@"
   recipient_keys:
     description: The recipient's signing keys of the encrypted event.
     $ref: "#/components/schemas/SigningKeys"

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

@@ -18,10 +18,14 @@ accessTokenBearer:
     or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
+
+    This is the preferred method.
   scheme: bearer
 appserviceAccessTokenBearer:
   type: http
   description: |-
     The `as_token` of an application service, using the `Authorization: Bearer`
     header.
+
+    This is the preferred method.
   scheme: bearer

data/api/identity/definitions/security.yaml

@@ -16,4 +16,6 @@ accessTokenBearer:
   description: |-
     The `access_token` returned by a call to `/register`, using the
     `Authorization: Bearer` header.
+    
+    This is the preferred method.
   scheme: bearer

data/event-schemas/schema/m.room_key_bundle.yaml

@@ -13,7 +13,7 @@ description: |-
   [Olm](/client-server-api/#molmv1curve25519-aes-sha2).
 
   The `sender_device_keys` property in the [Olm
-  plaintext](/client-server-api/#definition-olmplaintext) MUST be
+  plaintext](/client-server-api/#definition-olmpayload) MUST be
   populated. Recipients SHOULD ignore `m.room_key_bundle` messages which omit
   them.
 properties: