Merge branch 'main' into server-metadata-discovery

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2125.feature

@@ -0,0 +1 @@
+Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2149.feature

@@ -0,0 +1 @@
+Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2158.feature

@@ -0,0 +1 @@
+Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/server_server/newsfragments/2125.feature

@@ -0,0 +1 @@
+Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

content/client-server-api/_index.md

@@ -1485,6 +1485,96 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% http-api spec="client-server" api="oauth_server_metadata" %}}
 
+#### Scope
+
+The client requests a scope in the OAuth 2.0 authorization flow, which is then
+associated to the generated access and refresh tokens. This provides a framework
+for obtaining user consent.
+
+A scope is defined in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
+as a string containing a list of space-separated scope tokens.
+
+{{% boxes/note %}}
+The framework encourages the practice of obtaining additional user consent when
+a client asks for a new scope that was not granted previously. This could be
+used by future MSCs to replace the legacy [User-Interactive Authentication API](#user-interactive-authentication-api).
+{{% /boxes/note %}}
+
+##### Scope token format
+
+All scope tokens related to Matrix should start with `urn:matrix:` and use the
+`:` delimiter for further sub-division.
+
+Scope tokens related to mapping of Client-Server API access levels should start
+with `urn:matrix:client:`.
+
+{{% boxes/note %}}
+For MSCs that build on this namespace, unstable subdivisions should be used
+whilst in development. For example, if MSCXXXX wants to introduce the
+`urn:matrix:client:foo` scope, it could use
+`urn:matrix:client:com.example.mscXXXX.foo` during development.
+If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and
+`urn:matrix:client:bar`, it could use
+`urn:matrix:client:com.example.mscXXXX:foo` and
+`urn:matrix:client:com.example.mscXXXX:bar`.
+{{% /boxes/note %}}
+
+##### Allocated scope tokens
+
+This specification defines the following scope tokens:
+- [`urn:matrix:client:api:*`](#full-client-server-api-readwrite-access)
+- [`urn:matrix:client:device:<device_id>`](#device-id-allocation)
+
+###### Full client-server API read/write access
+
+| Scope                     | Purpose                                     |
+|---------------------------|---------------------------------------------|
+| `urn:matrix:client:api:*` | Grants full access to the Client-Server API. |
+
+{{% boxes/note %}}
+This token matches the behavior of the legacy authentication API. Future MSCs
+could introduce more fine-grained scope tokens like
+`urn:matrix:client:api:read:*` for read-only access.
+{{% /boxes/note %}}
+
+###### Device ID allocation
+
+| Scope                                  | Purpose                                                                                      |
+|----------------------------------------|----------------------------------------------------------------------------------------------|
+| `urn:matrix:client:device:<device_id>` | Allocates the given `device_id` and associates it to the generated access and refresh tokens. |
+
+Contrary to the legacy login and registration APIs where the homeserver is
+typically the one generating a `device_id` and providing it to the client, with
+the OAuth 2.0 API, the client is responsible for allocating the `device_id`.
+
+There MUST be exactly one `urn:matrix:client:device:<device_id>` token in the
+requested scope in the login flow.
+
+When generating a new `device_id`, the client SHOULD generate a random string
+with enough entropy. It SHOULD only use characters from the unreserved character
+list defined by [RFC 3986 section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3):
+
+```
+unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~"
+```
+
+Using this alphabet, a 10 character string is enough to stand a sufficient
+chance of being unique per user. The homeserver MAY reject a request for a
+`device_id` that is not long enough or contains characters outside the
+unreserved list.
+
+In any case it MUST only use characters allowed by the OAuth 2.0 scope
+definition in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3),
+which is defined as the following ASCII ranges:
+
+```
+%x21 / %x23-5B / %x5D-7E
+```
+
+This definition matches:
+- alphanumeric characters: `A-Z`, `a-z`, `0-9`
+- the following characters: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~``
+
 ### Account moderation
 
 #### Account locking
@@ -2896,6 +2986,10 @@ that are not `world_readable` regardless of their visibility.
 
 {{% http-api spec="client-server" api="list_public_rooms" %}}
 
+### Room Summaries
+
+{{% http-api spec="client-server" api="room_summary" %}}
+
 ## User Data
 
 ### User Directory

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

@@ -17,6 +17,8 @@ title: "PublishedRoomsChunk"
 properties:
   canonical_alias:
     type: string
+    format: mx-room-alias
+    pattern: "^#"
     description: The canonical alias of the room, if any.
     example: "#general:example.org"
   name:
@@ -29,6 +31,8 @@ properties:
     example: 42
   room_id:
     type: string
+    format: mx-room-id
+    pattern: "^!"
     description: The ID of the room.
     example: "!abcdefg:example.org"
   topic:
@@ -61,7 +65,6 @@ properties:
     example: "public"
   room_type:
     type: string
-    x-addedInMatrixVersion: "1.4"
     description: |-
       The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
 required:

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

@@ -0,0 +1,50 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: RoomSummary
+allOf:
+  - $ref: public_rooms_chunk.yaml
+  - type: object
+    properties:
+      room_type:
+        type: string
+        description: The `type` of room (from
+          [`m.room.create`](/client-server-api/#mroomcreate)),
+          if any.
+      allowed_room_ids:
+        type: array
+        items:
+          type: string
+          format: mx-room-id
+          pattern: "^!"
+        description: |-
+          If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
+          are specified by the join rules. Empty or omitted otherwise.
+      encryption:
+        type: string
+        enum:
+          - "m.megolm.v1.aes-sha2"
+        description: |-
+          The encryption algorithm to be used to encrypt messages sent in the
+          room.
+      room_version:
+        description: The version of the room.
+        type: string
+
+required:
+  - room_id
+  - num_joined_members
+  - world_readable
+  - guest_can_join

data/api/client-server/room_summary.yaml

@@ -0,0 +1,143 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Summary API
+  version: 1.0.0
+paths:
+  "/room_summary/{roomIdOrAlias}":
+    get:
+      x-addedInMatrixVersion: "1.15"
+      summary: Retrieves a summary for a room.
+      description: |-
+        Retrieves a summary for a room.
+
+        Clients should note that requests for rooms where the user's membership
+        is `invite` or `knock` might yield outdated, partial or even no data
+        since the server may not have access to the current state of the room.
+
+        Servers MAY allow unauthenticated access to this API if at least one of
+        the following conditions holds true:
+
+        - The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
+          `knock_restricted`.
+        - The room has a `world_readable` [history visibility](#room-history-visibility).
+
+        Servers should consider rate limiting requests that require a federation
+        request more heavily if the client is unauthenticated.
+      operationId: getRoomSummary
+      security:
+        - signedRequest: []
+      parameters:
+        - in: path
+          name: roomIdOrAlias
+          description: The room identifier or alias to summarise.
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            oneOf:
+              - type: string
+                format: mx-room-id
+                pattern: "^!"
+              - type: string
+                format: mx-room-alias
+                pattern: "^#"
+        - in: query
+          name: via
+          description: |-
+            The servers to attempt to request the summary from when
+            the local server cannot generate it (for instance, because
+            it has no local user in the room).
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+              format: mx-server-name
+      responses:
+        "200":
+          description: A summary of the room.
+          content:
+            application/json:
+              schema:
+                description: A summary of the room.
+                allOf:
+                  - $ref: ../client-server/definitions/room_summary.yaml
+                  - type: object
+                    properties:
+                      membership:
+                        description: |-
+                          The membership state of the user if the user is joined to the room. Absent
+                          if the API was called unauthenticated.
+                        enum:
+                          - invite
+                          - join
+                          - knock
+                          - leave
+                          - ban
+                        type: string
+                required:
+                  - guest_can_join
+                  - num_joined_members
+                  - room_id
+                  - world_readable
+              examples:
+                response:
+                  value: {
+                    room_id: "!ol19s:bleecker.street",
+                    avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
+                    guest_can_join: false,
+                    name: "CHEESE",
+                    num_joined_members: 37,
+                    topic: "Tasty tasty cheese",
+                    world_readable: true,
+                    join_rule: "public",
+                    room_type: "m.space",
+                    membership: "invite",
+                    encryption: "m.megolm.v1.aes-sha2",
+                    room_version: "9001",
+                  }
+        "404":
+          description: |-
+            The room could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found."
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/space_hierarchy.yaml

@@ -102,15 +102,10 @@ paths:
                        * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
                     items:
                       allOf:
-                        - $ref: definitions/public_rooms_chunk.yaml
+                        - $ref: definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyRoomsChunk
                           properties:
-                            room_type:
-                              type: string
-                              description: The `type` of room (from
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
-                                if any.
                             children_state:
                               type: array
                               description: |-
@@ -130,6 +125,14 @@ paths:
                                         description: The `origin_server_ts` for the event.
                                     required:
                                       - origin_server_ts
+                            room_type:
+                              x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
+                            allowed_room_ids:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            encryption:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            room_version:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                           required:
                             - children_state
                   next_batch:

data/api/server-server/space_hierarchy.yaml

@@ -61,22 +61,10 @@ paths:
                   room:
                     description: A summary of the room requested.
                     allOf:
-                      - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                      - $ref: ../client-server/definitions/room_summary.yaml
                       - type: object
                         title: SpaceHierarchyParentRoom
                         properties:
-                          room_type:
-                            type: string
-                            description: The `type` of room (from
-                              [`m.room.create`](/client-server-api/#mroomcreate)),
-                              if any.
-                          allowed_room_ids:
-                            type: array
-                            items:
-                              type: string
-                            description: |-
-                              If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
-                              are specified by the join rules. Empty or omitted otherwise.
                           children_state:
                             type: array
                             description: |-
@@ -96,6 +84,12 @@ paths:
                                       description: The `origin_server_ts` for the event.
                                   required:
                                     - origin_server_ts
+                          room_type:
+                            x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
+                          encryption:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                          room_version:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                         required:
                           - children_state
                   children:
@@ -105,22 +99,16 @@ paths:
                       be excluded.
                     items:
                       allOf:
-                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                        - $ref: ../client-server/definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyChildRoomsChunk
                           properties:
                             room_type:
-                              type: string
+                              x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
-                              description: The `type` of room (from
+                            encryption:
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                                if any.
+                            room_version:
-                            allowed_room_ids:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                              type: array
-                              items:
-                                type: string
-                              description: |-
-                                If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
-                                are specified by the join rules. Empty or omitted otherwise.
                   inaccessible_children:
                     type: array
                     items: