Merge 0608624f1d into 2baca03e6b

Signed-off-by: famfo <famfo@famfo.xyz>

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/internal/newsfragments/2318.clarification

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

changelogs/server_server/newsfragments/2326.clarification

@@ -0,0 +1 @@
+Clarify the s2s profile query behaviour and responses.

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

@@ -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/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.
 

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
-      a format suitable for clients. 'federation' will return the raw event as received
-      over federation. The default is 'client'.
+    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
+      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/api/server-server/query.yaml

@@ -111,22 +111,26 @@ paths:
       summary: Query for profile information about a given user
       description: |-
         Performs a query to get profile information, such as a display name or avatar,
-        for a given user. Homeservers should only query profiles for users that belong
+        for a given user. Homeservers MUST only query profiles for users that belong
         to the target server (identified by the [server name](/appendices/#server-name)
         in the user ID).
 
-        Servers may wish to cache the response to this query to avoid requesting the
-        information too often.
+        Responding servers MAY
+          - allow users to set arbitrary key/value pairs in their profile in addition to the
+            specified pairs
+          - deny profile look-up over federation by responding with 403 and an error code of
+            `M_FORBIDDEN`
+          - omit certain key/value pairs in the response
 
-        Servers MAY deny profile look-up over federation by responding with 403 and an
-        error code of `M_FORBIDDEN`.
+        Requseting servers MAY wish to cache the response to this query to avoid requesting the
+        information too often.
       operationId: queryProfile
       security:
         - signedRequest: []
       parameters:
         - in: query
           name: user_id
-          description: The user ID to query. Must be a user local to the receiving homeserver.
+          description: The user ID to query. MUST be a user local to the receiving homeserver.
           required: true
           example: "@someone:example.org"
           schema:
@@ -134,24 +138,24 @@ paths:
         - in: query
           name: field
           description: |-
-            The field to query. If specified, the server will only return the given field
-            in the response. If not specified, the server will return the full profile for
-            the user.
+            The field of the profile to query. If specified, the server MUST only return the
+            given field in the response. If not specified, the server MUST return the full,
+            public, profile for the user.
+
+            Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these
+            servers MAY allow users to set additional key/value pairs.
           schema:
             type: string
-            enum:
-              - displayname
-              - avatar_url
       responses:
         "200":
           description: |-
             The profile for the user. If a `field` is specified in the request, only the
-            matching field should be included in the response. If no `field` was specified,
-            the response should include the fields of the user's profile that can be made
+            matching field MUST included in the response. If no `field` was specified,
+            the response MUST include the fields of the user's profile that can be made
             public, such as the display name and avatar.
 
             If the user does not have a particular field set on their profile, the server
-            should exclude it from the response body or give it the value `null`.
+            MUST either exclude it from the response body or give it the value `null`.
           content:
             application/json:
               schema:
@@ -160,20 +164,20 @@ paths:
                   displayname:
                     type: string
                     description: |-
-                      The display name of the user. May be omitted if the user does not have a
-                      display name set.
+                      The display name of the user. MUST either be omitted or set to `null` if
+                      the user does not have a display name set.
                     example: John Doe
                   avatar_url:
                     type: string
                     description: |-
-                      The avatar URL for the user's avatar. May be omitted if the user does not
-                      have an avatar set.
-                    example: mxc://matrix.org/MyC00lAvatar
+                      The avatar URL for the user's avatar. MUST either be omitted or set to
+                      `null` if the user does not have an avatar set.
+                    example: mxc://example.org/MyC00lAvatar
               examples:
                 response:
                   value: {
                     "displayname": "John Doe",
-                    "avatar_url": "mxc://matrix.org/MyC00lAvatar"
+                    "avatar_url": "mxc://example.org/MyC00lAvatar"
                   }
         "403":
           x-addedInMatrixVersion: "1.12"
@@ -190,7 +194,7 @@ paths:
                     "error": "Profile lookup over federation is disabled on this homeserver"
                   }
         "404":
-          description: The user does not exist or does not have a profile.
+          description: The user does not exist, does not have a profile or the queried field does not exist.
           content:
             application/json:
               schema:

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
-      naming conventions e.g. 'com.example.subdomain.event.type'
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
     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 }}