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 oauth2-grant-types

Browse source
This commit is contained in:
Richard van der Hoff 2025-06-17 18:19:44 +01:00 committed by GitHub
parent 1c32e21b69 51ccbbd240
commit e9526c7564
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 498 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/2147.new Normal file
View file

@ -0,0 +1 @@
Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965).

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

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

@ -1481,6 +1481,100 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
### OAuth 2.0 API
#### Server metadata discovery
{{% 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: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~``
#### Grant types
[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) and other RFCs define
@ -3137,6 +3231,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

176
data/api/client-server/oauth_server_metadata.yaml Normal file
View file

@ -0,0 +1,176 @@
# 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 OAuth 2.0 Server Metadata Discovery API
version: 1.0.0
paths:
"/auth_metadata":
get:
summary: Get the OAuth 2.0 authorization server metadata.
description: |-
Gets the OAuth 2.0 authorization server metadata, as defined in
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
endpoint URLs and the supported parameters that can be used by the
clients.
This endpoint definition includes only the fields that are meaningful in
the context of the Matrix specification. The full list of possible
fields is available in the [OAuth Authorization Server Metadata
registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
and normative definitions of them are available in their respective
RFCs.
{{% boxes/note %}}
The authorization server metadata is relatively large and may change
over time. Clients should:
- Cache the metadata appropriately based on HTTP caching headers
- Refetch the metadata if it is stale
{{% /boxes/note %}}
operationId: getAuthMetadata
responses:
"200":
description: The OAuth 2.0 authorization server metadata.
content:
application/json:
schema:
type: object
properties:
issuer:
type: string
format: uri
description: |-
The authorization server's issuer identifier, which is a URL that uses the
`https` scheme and has no query or fragment components.
This is not used in the context of the Matrix specification, but is required
by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
authorization_endpoint:
type: string
format: uri
description: |-
URL of the authorization endpoint, necessary to use the authorization code
grant.
token_endpoint:
type: string
format: uri
description: |-
URL of the token endpoint, necessary to use the authorization code grant and
the refresh token grant.
revocation_endpoint:
type: string
format: uri
description: |-
URL of the revocation endpoint, necessary to log out a client by invalidating
its access and refresh tokens.
registration_endpoint:
type: string
format: uri
description: |-
URL of the client registration endpoint, necessary to perform dynamic
registration of a client.
response_types_supported:
type: array
description: |-
List of OAuth 2.0 response type strings that the server supports at the
authorization endpoint.
This array MUST contain at least the `code` value, for clients to be able to
use the authorization code grant.
items:
type: string
description: A response type that the server supports.
grant_types_supported:
type: array
description: |-
List of OAuth 2.0 grant type strings that the server supports at the token
endpoint.
This array MUST contain at least the `authorization_code` and `refresh_token`
values, for clients to be able to use the authorization code grant and refresh
token grant, respectively.
items:
type: string
description: A grant type that the server supports.
response_modes_supported:
type: array
description: |-
List of OAuth 2.0 response mode strings that the server supports at the
authorization endpoint.
This array MUST contain at least the `query` and `fragment` values, for
improved security in the authorization code grant.
items:
type: string
description: A response mode that the server supports.
code_challenge_methods_supported:
type: array
description: |-
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
that the server supports at the authorization endpoint.
This array MUST contain at least the `S256` value, for improved security in
the authorization code grant.
items:
type: string
description: A PKCE code challenge method that the server supports.
prompt_values_supported:
type: array
description: |-
List of OpenID Connect prompt values that the server supports at the
authorization endpoint.
Only the `create` value defined in [Initiating User Registration via OpenID
Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
supported, for a client to signal to the server that the user desires to
register a new account.
items:
type: string
description: A prompt value that the server supports.
required:
- issuer
- authorization_endpoint
- token_endpoint
- revocation_endpoint
- registration_endpoint
- response_types_supported
- grant_types_supported
- response_modes_supported
- code_challenge_methods_supported
example: {
"issuer": "https://account.example.com/",
"authorization_endpoint": "https://account.example.com/oauth2/auth",
"token_endpoint": "https://account.example.com/oauth2/token",
"registration_endpoint": "https://account.example.com/oauth2/clients/register",
"revocation_endpoint": "https://account.example.com/oauth2/revoke",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"response_modes_supported": ["query", "fragment"],
"code_challenge_methods_supported": ["S256"],
}
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1

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: