Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-21 13:33:44 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'main' into server-metadata-discovery

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2025-06-17 15:17:52 +00:00
parent 468ddf9d15 a2a9a02efa
commit be0e04a4f6
No known key found for this signature in database
GPG key ID: F26F4BE20A08255B
10 changed files with 317 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2125.feature Normal file
View file

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

1
changelogs/client_server/newsfragments/2149.feature Normal file
View file

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

1
changelogs/client_server/newsfragments/2158.feature Normal file
View file

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

1
changelogs/server_server/newsfragments/2125.feature Normal file
View file

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

94
content/client-server-api/_index.md
View file

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

5
data/api/client-server/definitions/public_rooms_chunk.yaml
View file

@ -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:

50
data/api/client-server/definitions/room_summary.yaml Normal file
View file

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

143
data/api/client-server/room_summary.yaml Normal file
View file

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

15
data/api/client-server/space_hierarchy.yaml
View file

@ -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:

38
data/api/server-server/space_hierarchy.yaml
View file

@ -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
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.
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
inaccessible_children:
type: array
items: