Merge 0608624f1d into fe5a195f4a

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

changelogs/client_server/newsfragments/2311.feature

@@ -0,0 +1 @@
+`/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/client_server/newsfragments/2311.removal

@@ -0,0 +1 @@
+The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/client_server/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2324.clarification

@@ -0,0 +1 @@
+Clarified attachment encryption to require secure generation of keys and hash verification.

changelogs/internal/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2323.clarification

@@ -0,0 +1 @@
+Render error code sections as definition lists to improve readability.

config/_default/hugo.toml

@@ -65,7 +65,7 @@ description = "Home of the Matrix specification for decentralised communication"
 # Everything below this are Site Params
 
 [params]
-copyright = "The Matrix.org Foundation CIC"
+copyright = "The Matrix.org Foundation C.I.C."
 
 [params.version]
 # must be one of "unstable", "current", "historical"

content/client-server-api/_index.md

@@ -94,50 +94,50 @@ request being made was invalid.
 These error codes can be returned by any API endpoint:
 
 `M_FORBIDDEN`
-Forbidden access, e.g. joining a room without permission, failed login.
+: Forbidden access, e.g. joining a room without permission, failed login.
 
 `M_UNKNOWN_TOKEN`
-The access or refresh token specified was not recognised.
+: The access or refresh token specified was not recognised.
 
-An additional response parameter, `soft_logout`, might be present on the
+: An additional response parameter, `soft_logout`, might be present on the
 response for 401 HTTP status codes. See [the soft logout
 section](#soft-logout) for more information.
 
 `M_MISSING_TOKEN`
-No access token was specified for the request.
+: No access token was specified for the request.
 
 `M_USER_LOCKED`
-The account has been [locked](#account-locking) and cannot be used at this time.
+: The account has been [locked](#account-locking) and cannot be used at this time.
 
 `M_USER_SUSPENDED`
-The account has been [suspended](#account-suspension) and can only be used for
+: The account has been [suspended](#account-suspension) and can only be used for
 limited actions at this time.
 
 `M_BAD_JSON`
-Request contained valid JSON, but it was malformed in some way, e.g.
+: Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
 
 `M_NOT_JSON`
-Request did not contain valid JSON.
+: Request did not contain valid JSON.
 
 `M_NOT_FOUND`
-No resource was found for this request.
+: No resource was found for this request.
 
 `M_LIMIT_EXCEEDED`
-Too many requests have been sent in a short period of time. Wait a while
+: Too many requests have been sent in a short period of time. Wait a while
 then try again. See [Rate limiting](#rate-limiting).
 
 `M_UNRECOGNIZED`
-The server did not understand the request. This is expected to be returned with
+: The server did not understand the request. This is expected to be returned with
 a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
 code if the endpoint is implemented, but the incorrect HTTP method is used.
 
 `M_UNKNOWN_DEVICE`
-{{% added-in v="1.17" %}} The device ID supplied by the application service does
+: {{% added-in v="1.17" %}} The device ID supplied by the application service does
 not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
 
 `M_RESOURCE_LIMIT_EXCEEDED`
-The request cannot be completed because the homeserver has reached a
+: The request cannot be completed because the homeserver has reached a
 resource limit imposed on it. For example, a homeserver held in a shared
 hosting environment may reach a resource limit if it starts using too
 much memory or disk space. The error MUST have an `admin_contact` field
@@ -148,7 +148,7 @@ only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
 `M_UNKNOWN`
-An unknown error has occurred.
+: An unknown error has occurred.
 
 #### Other error codes
 
@@ -157,90 +157,90 @@ The following error codes are specific to certain endpoints.
 <!-- TODO: move them to the endpoints that return them -->
 
 `M_UNAUTHORIZED`
-The request was not correctly authorized. Usually due to login failures.
+: The request was not correctly authorized. Usually due to login failures.
 
 `M_USER_DEACTIVATED`
-The user ID associated with the request has been deactivated. Typically
+: The user ID associated with the request has been deactivated. Typically
 for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
 
 `M_USER_IN_USE`
-Encountered when trying to register a user ID which has been taken.
+: Encountered when trying to register a user ID which has been taken.
 
 `M_INVALID_USERNAME`
-Encountered when trying to register a user ID which is not valid.
+: Encountered when trying to register a user ID which is not valid.
 
 `M_ROOM_IN_USE`
-Sent when the room alias given to the `createRoom` API is already in
+: Sent when the room alias given to the `createRoom` API is already in
 use.
 
 `M_INVALID_ROOM_STATE`
-Sent when the initial state given to the `createRoom` API is invalid.
+: Sent when the initial state given to the `createRoom` API is invalid.
 
 `M_THREEPID_IN_USE`
-Sent when a threepid given to an API cannot be used because the same
+: Sent when a threepid given to an API cannot be used because the same
 threepid is already in use.
 
 `M_THREEPID_NOT_FOUND`
-Sent when a threepid given to an API cannot be used because no record
+: Sent when a threepid given to an API cannot be used because no record
 matching the threepid was found.
 
 `M_THREEPID_AUTH_FAILED`
-Authentication could not be performed on the third-party identifier.
+: Authentication could not be performed on the third-party identifier.
 
 `M_THREEPID_DENIED`
-The server does not permit this third-party identifier. This may happen
+: The server does not permit this third-party identifier. This may happen
 if the server only permits, for example, email addresses from a
 particular domain.
 
 `M_SERVER_NOT_TRUSTED`
-The client's request used a third-party server, e.g. identity server,
+: The client's request used a third-party server, e.g. identity server,
 that this server does not trust.
 
 `M_UNSUPPORTED_ROOM_VERSION`
-The client's request to create a room used a room version that the
+: The client's request to create a room used a room version that the
 server does not support.
 
 `M_INCOMPATIBLE_ROOM_VERSION`
-The client attempted to join a room that has a version the server does
+: The client attempted to join a room that has a version the server does
 not support. Inspect the `room_version` property of the error response
 for the room's version.
 
 `M_BAD_STATE`
-The state change requested cannot be performed, such as attempting to
+: The state change requested cannot be performed, such as attempting to
 unban a user who is not banned.
 
 `M_GUEST_ACCESS_FORBIDDEN`
-The room or resource does not permit guests to access it.
+: The room or resource does not permit guests to access it.
 
 `M_CAPTCHA_NEEDED`
-A Captcha is required to complete the request.
+: A Captcha is required to complete the request.
 
 `M_CAPTCHA_INVALID`
-The Captcha provided did not match what was expected.
+: The Captcha provided did not match what was expected.
 
 `M_MISSING_PARAM`
-A required parameter was missing from the request.
+: A required parameter was missing from the request.
 
 `M_INVALID_PARAM`
-A parameter that was specified has the wrong value. For example, the
+: A parameter that was specified has the wrong value. For example, the
 server expected an integer and instead received a string.
 
 `M_TOO_LARGE`
-The request or entity was too large.
+: The request or entity was too large.
 
 `M_EXCLUSIVE`
-The resource being requested is reserved by an application service, or
+: The resource being requested is reserved by an application service, or
 the application service making the request has not created the resource.
 
 `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
-The user is unable to reject an invite to join the server notices room.
+: The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
 `M_THREEPID_MEDIUM_NOT_SUPPORTED`
-The homeserver does not support adding a third party identifier of the given medium.
+: The homeserver does not support adding a third party identifier of the given medium.
 
 `M_THREEPID_IN_USE`
-The third party identifier specified by the client is not acceptable because it is
+: The third party identifier specified by the client is not acceptable because it is
 already in use in some way.
 
 #### Rate limiting
@@ -3320,7 +3320,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color
 ### Redactions
 
 Since events are extensible it is possible for malicious users and/or
-servers to add keys that are, for example offensive or illegal. Since
+servers to add keys that are, for example, offensive or illegal. Since
 some events cannot be simply deleted, e.g. membership events, we instead
 'redact' events. This involves removing all keys from an event that are
 not required by the protocol. This stripped down event is thereafter
@@ -3418,7 +3418,7 @@ This specification describes the following relationship types:
 * [Event replacements](#event-replacements).
 * [Event annotations](#event-annotations-and-reactions).
 * [Threads](#threading).
-* [References](#reference-relations)
+* [References](#reference-relations).
 
 #### Aggregations of child events
 

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

@@ -350,11 +350,14 @@ field, and as a result should remove her from its list of tracked users.
 When encryption is enabled in a room, files should be uploaded encrypted
 on the homeserver.
 
-In order to achieve this, a client should generate a single-use 256-bit
+In order to achieve this, the client generates a single-use 256-bit AES
-AES key, and encrypt the file using AES-CTR. The counter should be
+key, and encrypts the file using AES-CTR. The counter is 64 bits long,
-64-bit long, starting at 0 and prefixed by a random 64-bit
+starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
-Initialization Vector (IV), which together form a 128-bit unique counter
+which together form a 128-bit unique counter block.
-block.
+
+Clients MUST generate both the AES key and IV using a cryptographically 
+secure random source and MUST NOT use the same key or IV multiple
+times. The latter 64 bits of the 128-bit counter block MUST start at zero.
 
 {{% boxes/warning %}}
 An IV must never be used multiple times with the same key. This implies
@@ -364,13 +367,14 @@ same key and IV.
 {{% /boxes/warning %}}
 
 Then, the encrypted file can be uploaded to the homeserver. The key and
-the IV must be included in the room event along with the resulting
+the IV are included in the room event along with the resulting `mxc://`
-`mxc://` in order to allow recipients to decrypt the file. As the event
+in order to allow recipients to decrypt the file. As the event
 containing those will be Megolm encrypted, the server will never have
 access to the decrypted file.
 
-A hash of the ciphertext must also be included, in order to prevent the
+A hash of the ciphertext MUST also be included, in order to prevent the
-homeserver from changing the file content.
+homeserver from changing the file content. Clients MUST verify the hash
+before using the file contents.
 
 A client should send the data as an encrypted `m.room.message` event,
 using either `m.file` as the msgtype, or the appropriate msgtype for the
@@ -392,7 +396,7 @@ properties.
 | url       | string           | **Required.** The URL to the file.                                                             |
 | key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
 | iv        | string           | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.    |
-| hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
+| hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
 | v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
 
 `JWK`

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

@@ -107,7 +107,7 @@ flag to `true`.
 ```
 
 {{% boxes/note %}}
-Clients which are acutely aware of threads (they do not render threads, but are otherwise
+Clients which are aware of threads (they do not render threads, but are otherwise
 aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
 of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.
 

content/identity-service-api.md

@@ -71,53 +71,53 @@ the keys `error` and `errcode` MUST always be present.
 Some standard error codes are below:
 
 `M_NOT_FOUND`
-The resource requested could not be located.
+: The resource requested could not be located.
 
 `M_MISSING_PARAMS`
-The request was missing one or more parameters.
+: The request was missing one or more parameters.
 
 `M_INVALID_PARAM`
-The request contained one or more invalid parameters.
+: The request contained one or more invalid parameters.
 
 `M_SESSION_NOT_VALIDATED`
-The session has not been validated.
+: The session has not been validated.
 
 `M_NO_VALID_SESSION`
-A session could not be located for the given parameters.
+: A session could not be located for the given parameters.
 
 `M_SESSION_EXPIRED`
-The session has expired and must be renewed.
+: The session has expired and must be renewed.
 
 `M_INVALID_EMAIL`
-The email address provided was not valid.
+: The email address provided was not valid.
 
 `M_EMAIL_SEND_ERROR`
-There was an error sending an email. Typically seen when attempting to
+: There was an error sending an email. Typically seen when attempting to
 verify ownership of a given email address.
 
 `M_INVALID_ADDRESS`
-The provided third-party address was not valid.
+: The provided third-party address was not valid.
 
 `M_SEND_ERROR`
-There was an error sending a notification. Typically seen when
+: There was an error sending a notification. Typically seen when
 attempting to verify ownership of a given third-party address.
 
 `M_UNRECOGNIZED`
-The request contained an unrecognised value, such as an unknown token or
+: The request contained an unrecognised value, such as an unknown token or
 medium.
 
-This is also used as the response if a server did not understand the request.
+: This is also used as the response if a server did not understand the request.
 This is expected to be returned with a 404 HTTP status code if the endpoint is
 not implemented or a 405 HTTP status code if the endpoint is implemented, but
 the incorrect HTTP method is used.
 
 `M_THREEPID_IN_USE`
-The third-party identifier is already in use by another user. Typically
+: The third-party identifier is already in use by another user. Typically
 this error will have an additional `mxid` property to indicate who owns
 the third-party identifier.
 
 `M_UNKNOWN`
-An unknown error has occurred.
+: An unknown error has occurred.
 
 ## Privacy
 

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

@@ -23,14 +23,14 @@ properties:
   not_senders:
     description: A list of sender IDs to exclude. If this list is absent then no senders
       are excluded. A matching sender will be excluded even if it is listed in the
-      `'senders'` filter.
+      `senders` filter.
     items:
       type: string
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
       event types are excluded. A matching type will be excluded even if it is listed
-      in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
+      in the `types` filter. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
@@ -43,7 +43,7 @@ properties:
     type: array
   types:
     description: A list of event types to include. If this list is absent then all
-      event types are included. A `'*'` can be used as a wildcard to match any sequence
+      event types are included. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

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

@@ -39,7 +39,7 @@ allOf:
         for more information. Defaults to `false`.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
-        are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+        are excluded. A matching room will be excluded even if it is listed in the `rooms`
         filter.
       items:
         type: string

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

@@ -17,15 +17,15 @@ properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
       fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
-      to include. So ['content.body'] will include the 'body' field of the 'content' object.
+      to include. So `['content.body']` will include the `body` field of the `content` object.
       A server may include more fields than were requested.
     items:
       type: string
     type: array
   event_format:
-    description: The format to use for events. 'client' will return the events in
+    description: The format to use for events. `client` will return the events in
-      a format suitable for clients. 'federation' will return the raw event as received
+      a format suitable for clients. `federation` will return the raw event as received
-      over federation. The default is 'client'.
+      over federation. The default is `client`.
     enum:
     - client
     - federation
@@ -45,7 +45,7 @@ properties:
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
-          are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+          are excluded. A matching room will be excluded even if it is listed in the `rooms`
           filter. This filter is applied before the filters in `ephemeral`,
           `state`, `timeline` or `account_data`
         items:
@@ -65,7 +65,7 @@ properties:
           events that appear in the `ephemeral` property in the `/sync`
           response.
       include_leave:
-        description: Include rooms that the user has left in the sync, default false
+        description: Include rooms that the user has left in the sync. Defaults to `false`.
         type: boolean
       state:
         type: object

data/api/client-server/list_public_rooms.yaml

@@ -226,7 +226,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string
@@ -277,4 +277,4 @@ components:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery
     accessTokenBearer:
-      $ref: definitions/security.yaml#/accessTokenBearer
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login.yaml

@@ -163,7 +163,7 @@ paths:
                     known client device, a new device will be created. The given
                     device ID must not be the same as a
                     [cross-signing](/client-server-api/#cross-signing) key ID.
-                    The server will auto-generate a device_id
+                    The server will auto-generate a `device_id`
                     if this is not specified.
                 initial_device_display_name:
                   type: string

data/api/client-server/password_management.yaml

@@ -57,7 +57,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether the user's other access tokens, and their associated devices, should be
-                    revoked if the request succeeds. Defaults to true.
+                    revoked if the request succeeds. Defaults to `true`.
 
                     When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
                     for the user's remaining devices.

data/api/client-server/registration.yaml

@@ -126,7 +126,7 @@ paths:
                   description: |-
                     ID of the client device. If this does not correspond to a
                     known client device, a new device will be created. The server
-                    will auto-generate a device_id if this is not specified.
+                    will auto-generate a `device_id` if this is not specified.
                   example: GHTYAJCE
                 initial_device_display_name:
                   type: string
@@ -139,11 +139,11 @@ paths:
                   description: |-
                     If true, an `access_token` and `device_id` should not be
                     returned from this call, therefore preventing an automatic
-                    login. Defaults to false.
+                    login. Defaults to `false`.
                   example: false
                 refresh_token:
                   type: boolean
-                  description: If true, the client supports refresh tokens.
+                  description: If `true`, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
         required: true
       responses:

data/api/client-server/report_content.yaml

@@ -25,6 +25,15 @@ paths:
         the appropriate people. How such information is delivered is left up to
         implementations. The caller is not required to be joined to the room to
         report it.
+
+        Clients could infer whether a reported room exists based on the 404 response.
+        Homeservers that wish to conceal this information MAY return 200 responses
+        regardless of the existence of the reported room.
+
+        Furthermore, it might be possible for clients to deduce whether a reported
+        room exists by timing the response. This is because only a report for an
+        existing room will require the homeserver to do further processing. To
+        combat this, homeservers MAY add a random delay when generating a response.
       operationId: reportRoom
       parameters:
         - in: path
@@ -52,6 +61,11 @@ paths:
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
+      x-changedInMatrixVersion:
+        1.18: |
+          Servers MAY prevent room ID enumeration by using the 200 response
+          regardless of the existence of the reported room and/or by adding
+          a random delay when generating responses.
       responses:
         "200":
           description: The room has been reported successfully.
@@ -91,6 +105,10 @@ paths:
         the appropriate people. The caller must be joined to the room to report
         it.
 
+        Clients could infer whether a reported event or room exists based on the 404
+        response. Homeservers that wish to conceal this information MAY return 200
+        responses regardless of the existence of the reported event or room.
+
         Furthermore, it might be possible for clients to deduce whether a reported
         event exists by timing the response. This is because only a report for an
         existing event will require the homeserver to do further processing. To
@@ -117,15 +135,9 @@ paths:
             schema:
               type: object
               example: {
-                "score": -100,
                 "reason": "this makes me sad"
               }
               properties:
-                score:
-                  type: integer
-                  description: |-
-                    The score to rate this content as where -100 is most offensive
-                    and 0 is inoffensive.
                 reason:
                   type: string
                   description: The reason the content is being reported.
@@ -136,6 +148,10 @@ paths:
       x-changedInMatrixVersion:
         1.8: |
           This endpoint now requires the user to be joined to the room.
+        1.18: |
+          The `score` request parameter was removed. Additionally, servers
+          may prevent event/room ID enumeration by using the 200 response
+          regardless of the existence of the reported event/room.
       responses:
         "200":
           description: The event has been reported successfully.

data/api/client-server/room_send.yaml

@@ -31,7 +31,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        [Room Events](/client-server-api/#room-events) for the m. event specification.
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
 
         Homeservers MUST allow clients to send `m.room.redaction` events with this
         endpoint for all room versions. In rooms with a version older than 11 they

data/api/server-server/public_rooms.yaml

@@ -49,7 +49,7 @@ paths:
           name: include_all_networks
           description: |-
             Whether or not to include all networks/protocols defined by application
-            services on the homeserver. Defaults to false.
+            services on the homeserver. Defaults to `false`.
           example: false
           schema:
             type: boolean
@@ -121,7 +121,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string

data/event-schemas/schema/core-event-schema/event.yaml

@@ -7,8 +7,7 @@ properties:
       When interacting with the REST API, this is the HTTP body.
     type: object
   type:
-    description: The type of event. This SHOULD be namespaced similar to Java package
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
-      naming conventions e.g. 'com.example.subdomain.event.type'
     type: string
 required:
   - type

data/event-schemas/schema/m.room.server_acl.yaml

@@ -54,7 +54,7 @@ properties:
         type: boolean
         description: |-
           True to allow server names that are IP address literals. False to
-          deny. Defaults to true if missing or otherwise not a boolean.
+          deny. Defaults to `true` if missing or otherwise not a boolean.
 
           This is strongly recommended to be set to `false` as servers running
           with IP literal names are strongly discouraged in order to require

layouts/_partials/events/render-event.html

@@ -49,7 +49,7 @@
   </tr>
 {{ if $state_key }}
   <tr>
-   <th>State key</th>
+   <th>State key:</th>
    <td>{{ $state_key.description | markdownify }}</td>
  </tr>
 {{ end }}