changelogs/client_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-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/2147.new

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

changelogs/client_server/newsfragments/2148.feature

@@ -1 +0,0 @@
-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/2149.feature

@@ -1 +0,0 @@
-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/2150.feature

@@ -1 +0,0 @@
-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/2154.clarification

@@ -1 +0,0 @@
-Add missing fields in example for `ExportedSessionData`.

changelogs/client_server/newsfragments/2158.feature

@@ -1 +0,0 @@
-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

@@ -1 +0,0 @@
-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

@@ -1481,549 +1481,6 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 ### OAuth 2.0 API
 
-#### Login flow
-
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant). In the context of the Matrix specification,
-this means requesting a [scope](#scope) including full client-server API
-read/write access and allocating a device ID.
-
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following values:
-
-- `device_id`: a unique identifier for this device; see the
-  [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
-- `state`: a unique opaque identifier, like a [transaction ID](#transaction-identifiers),
-  that will allow the client to maintain state between the authorization request
-  and the callback.
-- `code_verifier`: a cryptographically random value that will allow to make sure
-  that the client that makes the token request for a given `code` is the same
-  one that made the authorization request.
-
-  It is defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) as
-  a high-entropy cryptographic random string using the characters `[A-Z]`,
-  `[a-z]`, `[0-9]`, `-`, `.`, `_` and `~` with a minimum length of 43 characters
-  and a maximum length of 128 characters.
-
-**Authorization request**
-
-The client then constructs the authorization request URL using the
-`authorization_endpoint` value, with the following query parameters:
-
-| Parameter               | Value                                              |
-|-------------------------|----------------------------------------------------|
-| `response_type`         | `code`                                             |
-| `client_id`             | The client ID returned from client registration.   |
-| `redirect_uri`          | The redirect URI that MUST match one of the values registered in the client metadata |
-| `scope`                 | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
-| `state`                 | The `state` value generated previously.            |
-| `response_mode`         | `fragment` or `query` (see "[Callback](#callback)" below). |
-| `code_challenge`        | Computed from the `code_verifier` value generated previously using the SHA-256 algorithm, as described in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636). |
-| `code_challenge_method` | `S256`                                             |
-
-This authorization request URL must be opened in the user's browser:
-
-- For web-based clients, this can be done through a redirection or by opening
-  the URL in a new tab.
-- For native clients, this can be done by opening the URL using the system
-  browser, or, when available, through platform-specific APIs such as
-  [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
-  on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
-
-Sample authorization request, with extra whitespaces for readability:
-
-```
-https://account.example.com/oauth2/auth?
-    client_id     = s6BhdRkqt3 &
-    response_type = code &
-    response_mode = fragment &
-    redirect_uri  = https://app.example.com/oauth2-callback &
-    scope         = urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD &
-    state         = ewubooN9weezeewah9fol4oothohroh3 &
-    code_challenge        = 72xySjpngTcCxgbPfFmkPHjMvVDl2jW1aWP7-J6rmwU &
-    code_challenge_method = S256
-```
-
-<a id="callback"></a> **Callback**
-
-Once completed, the user is redirected to the `redirect_uri`, with either a
-successful or failed authorization in the URL fragment or query parameters.
-Whether the parameters are in the URL fragment or query parameters is determined
-by the `response_mode` value:
-
-- If set to `fragment`, the parameters will be placed in the URL fragment, like
-  `https://example.com/callback#param1=value1&param2=value2`.
-- If set to `query`, the parameters will be in placed the query string, like
-  `com.example.app:/callback?param1=value1&param2=value2`.
-
-To avoid disclosing the parameters to the web server hosting the `redirect_uri`,
-clients SHOULD use the `fragment` response mode if the `redirect_uri` is an
-HTTPS URI with a remote host.
-
-In both success and failure cases, the parameters will include the `state` value
-used in the authorization request.
-
-A successful authorization will have a `code` value, for example:
-
-```
-https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
-```
-
-A failed authorization will have the following values:
-
-- `error`: the error code
-- `error_description`: the error description (optional)
-- `error_uri`: the URI where the user can find more information about the error (optional)
-
-For example:
-
-```
-https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&error_uri=https%3A%2F%2Ferrors.example.com%2F
-```
-
-**Token request**
-
-The client then exchanges the authorization code to obtain an access token using
-the token endpoint.
-
-This is done by making a POST request to the `token_endpoint` with the following
-parameters, encoded as `application/x-www-form-urlencoded` in the body:
-
-| Parameter       | Value                                                      |
-|-----------------|------------------------------------------------------------|
-| `grant_type`    | `authorization_code`                                       |
-| `code`          | The value of `code` obtained from the callback.            |
-| `redirect_uri`  | The same `redirect_uri` used in the authorization request. |
-| `client_id`     | The client ID returned from client registration.           |
-| `code_verifier` | The value generated at the start of the authorization flow. |
-
-The server replies with a JSON object containing the access token, the token
-type, the expiration time, and the refresh token.
-
-Sample token request:
-
-```
-POST /oauth2/token HTTP/1.1
-Host: account.example.com
-Content-Type: application/x-www-form-urlencoded
-Accept: application/json
-
-grant_type=authorization_code
-  &code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
-  &redirect_uri=https://app.example.com/oauth2-callback
-  &client_id=s6BhdRkqt3
-  &code_verifier=ogie4iVaeteeKeeLaid0aizuimairaCh
-```
-
-Sample response:
-
-```json
-{
-  "access_token": "2YotnFZFEjr1zCsicMWpAA",
-  "token_type": "Bearer",
-  "expires_in": 299,
-  "refresh_token": "tGz3JOkF0XG5Qx2TlKWIA",
-  "scope": "urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD"
-}
-```
-
-Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
-endpoint to get the user ID that owns the access token.
-
-#### Token refresh flow
-
-Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
-grant](#refresh-token-grant).
-
-When the access token expires, the client must refresh it by making a `POST`
-request to the `token_endpoint` with the following parameters, encoded as
-`application/x-www-form-urlencoded` in the body:
-
-| Parameter       | Value                                                      |
-|-----------------|------------------------------------------------------------|
-| `grant_type`    | `refresh_token`                                            |
-| `refresh_token` | The `refresh_token` obtained from the token response during the last token request. |
-| `client_id`     | The client ID returned from client registration.           |
-
-The server replies with a JSON object containing the new access token, the token
-type, the expiration time, and a new refresh token, like in the authorization
-flow.
-
-#### Server metadata discovery
-
-{{% http-api spec="client-server" api="oauth_server_metadata" %}}
-
-#### Client registration
-
-Before being able to use the authorization flow to obtain an access token, a
-client needs to obtain a `client_id` by registering itself with the server.
-
-This should be done via OAuth 2.0 Dynamic Client Registration as defined in
-[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
-
-##### Client metadata
-
-In OAuth 2.0, clients register a set of metadata values with the authorization
-server, which associates it with a newly generated `client_id`. These values are
-used to describe the client to the user and define how the client interacts with
-the server.
-
-{{% definition path="schemas/oauth2-client-metadata" %}}
-
-###### Metadata localization
-
-As per [RFC 7591 section 2.2](https://tools.ietf.org/html/rfc7591#section-2.2),
-all the human-readable metadata values MAY be localized.
-
-The human-readable values include:
-- `client_name`
-- `logo_uri`
-- `tos_uri`
-- `policy-uri`
-
-For example:
-
-```json
-{
-  "client_name": "Digital mailbox",
-  "client_name#en-US": "Digital mailbox",
-  "client_name#en-GB": "Digital postbox",
-  "client_name#fr": "Boîte aux lettres numérique",
-  "tos_uri": "https://example.com/tos.html",
-  "tos_uri#fr": "https://example.com/fr/tos.html",
-  "policy_uri": "https://example.com/policy.html",
-  "policy_uri#fr": "https://example.com/fr/policy.html"
-}
-```
-
-###### Redirect URI validation
-
-The redirect URI plays a critical role in validating the authenticity of the
-client. The client "proves" its identity by demonstrating that it controls the
-redirect URI. This is why it is critical to have strict validation of the
-redirect URI.
-
-The `application_type` metadata is used to determine the type of client.
-
-In all cases, the redirect URI MUST NOT have a fragment component.
-
-**Web clients**
-
-`web` clients can use redirect URIs that:
-
-- MUST use the `https` scheme.
-- MUST NOT use a user or password in the authority component of the URI.
-- MUST use the client URI as a common base for the authority component, as
-  defined previously.
-- MAY include an `application/x-www-form-urlencoded` formatted query component.
-
-For example, with `https://example.com/` as the client URI, the following are
-valid redirect URIs:
-- `https://example.com/callback`
-- `https://app.example.com/callback`
-- `https://example.com:5173/?query=value`
-
-With the same client URI, the following are invalid redirect URIs:
-- `https://example.com/callback#fragment`
-- `http://example.com/callback`
-- `http://localhost/`
-
-**Native clients**
-
-`native` clients can use three types of redirect URIs:
-
-1. **Private-Use URI Scheme**
-    - The scheme MUST be prefixed with the client URI hostname in reverse-DNS
-      notation. For example, if the client URI is `https://example.com/`, then a
-      valid custom URI scheme would be `com.example.app:/`.
-    - There MUST NOT be an authority component. This means that the URI MUST have
-      either a single slash or none immediately following the scheme, with no
-      hostname, username, or port.
-2. **`http` URI on the loopback interface**
-    - The scheme MUST be `http`.
-    - The host part MUST be `localhost`, `127.0.0.1`, or `[::1]`.
-    - There MUST NOT be a port. The homeserver MUST then accept any port number
-      during the authorization flow.
-3. **Claimed `https` Scheme URI**
-
-    Some operating systems allow apps to claim `https` scheme URIs in the
-    domains they control. When the browser encounters a claimed URI, instead of
-    the page being loaded in the browser, the native app is launched with the
-    URI supplied as a launch parameter. The same rules as for `web` clients
-    apply.
-
-These restrictions are the same as defined by [RFC 8252 section 7](https://tools.ietf.org/html/rfc8252#section-7).
-
-For example, with `https://example.com/` as the client URI,
-
-These are valid redirect URIs:
-- `com.example.app:/callback`
-- `com.example:/`
-- `com.example:callback`
-- `http://localhost/callback`
-- `http://127.0.0.1/callback`
-- `http://[::1]/callback`
-
-These are invalid redirect URIs:
-- `example:/callback`
-- `com.example.app://callback`
-- `https://localhost/callback`
-- `http://localhost:1234/callback`
-
-##### Dynamic client registration flow
-
-To register, the client sends an HTTP `POST` request to the
-`registration_endpoint`, which can be found in the [server metadata](#server-metadata-discovery).
-The body of the request is the JSON-encoded [`OAuthClientMetadata`](#client-metadata).
-
-For example, the client could send the following registration request:
-
-```http
-POST /register HTTP/1.1
-Content-Type: application/json
-Accept: application/json
-Server: auth.example.com
-```
-
-```json
-{
-  "client_name": "My App",
-  "client_name#fr": "Mon application",
-  "client_uri": "https://example.com/",
-  "logo_uri": "https://example.com/logo.png",
-  "tos_uri": "https://example.com/tos.html",
-  "tos_uri#fr": "https://example.com/fr/tos.html",
-  "policy_uri": "https://example.com/policy.html",
-  "policy_uri#fr": "https://example.com/fr/policy.html",
-  "redirect_uris": ["https://app.example.com/callback"],
-  "token_endpoint_auth_method": "none",
-  "response_types": ["code"],
-  "grant_types": [
-    "authorization_code",
-    "refresh_token",
-    "urn:ietf:params:oauth:grant-type:token-exchange"
-  ],
-  "application_type": "web"
-}
-```
-
-Upon successful registration, the server replies with an `HTTP 201 Created`
-response, with a JSON object containing the allocated `client_id` and all the
-registered metadata values.
-
-With the registration request above, the server might reply with:
-
-```json
-{
-  "client_id": "s6BhdRkqt3",
-  "client_name": "My App",
-  "client_uri": "https://example.com/",
-  "logo_uri": "https://example.com/logo.png",
-  "tos_uri": "https://example.com/tos.html",
-  "policy_uri": "https://example.com/policy.html",
-  "redirect_uris": ["https://app.example.com/callback"],
-  "token_endpoint_auth_method": "none",
-  "response_types": ["code"],
-  "grant_types": ["authorization_code", "refresh_token"],
-  "application_type": "web"
-}
-```
-
-In this example, the server has not registered the locale-specific values for
-`client_name`, `tos_uri`, and `policy_uri`, which is why they are not present in
-the response. The server also does not support the
-`urn:ietf:params:oauth:grant-type:token-exchange` grant type, which is why it is
-not present in the response.
-
-The client MUST store the `client_id` for future use.
-
-To avoid the number of client registrations growing over time, the server MAY
-choose to delete client registrations that don't have an active session. The
-server MUST NOT delete client registrations that have an active session.
-
-Clients MUST perform a new client registration at the start of each
-authorization flow.
-
-{{% boxes/note %}}
-Because each client on each user device will do its own registration, they may
-all have different `client_id`s. This means that the server may store the same
-client registration multiple times, which could lead to a large number of client
-registrations.
-
-This can be mitigated by de-duplicating client registrations that have identical
-metadata. By doing so, different users on different devices using the same
-client can share a single `client_id`, reducing the overall number of
-registrations.
-{{% /boxes/note %}}
-
-#### 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
-several "grant types": ways to obtain an ["access token"](#using-access-tokens).
-
-All these grants types require the client to know the following [authorization
-server metadata](#server-metadata-discovery):
-- `token_endpoint`
-- `grant_types_supported`
-
-The client must also have obtained a `client_id` by [registering with the server](#client-registration).
-
-This specification supports the following grant types:
-- [Authorization code grant](#authorization-code-grant)
-- [Refresh token grant](#refresh-token-grant)
-
-##### Authorization code grant
-
-As per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1),
-the authorization code grant lets the client obtain an access token through a
-browser redirect.
-
-This grant requires the client to know the following [authorization server
-metadata](#server-metadata-discovery):
-- `authorization_endpoint`
-- `response_types_supported`
-- `response_mode_supported`
-
-To use this grant, homeservers and clients MUST:
-
-- Support the authorization code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
-- Support the [refresh token grant](#refresh-token-grant).
-- Support PKCE using the `S256` code challenge method as per [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636).
-- Use [pre-registered](#client-registration), strict redirect URIs.
-- Use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
-  Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
-  for clients with an HTTPS redirect URI.
-
-###### User registration
-
-Clients can signal to the server that the user desires to register a new account
-by initiating the authorization code grant with the `prompt=create` parameter
-set in the authorization request as defined in [Initiating User Registration via
-OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
-
-Whether the homeserver supports this parameter is advertised by the
-`prompt_values_supported` authorization server metadata.
-
-Servers that support this parameter SHOULD show the account registration UI in
-the browser.
-
-##### Refresh token grant
-
-As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
-the refresh token grant lets the client exchange a refresh token for an access
-token.
-
-When authorization is granted to a client, the homeserver MUST issue a refresh
-token to the client in addition to the access token.
-
-The access token MUST be short-lived and SHOULD be refreshed using the
-`refresh_token` when expired.
-
-The homeserver SHOULD issue a new refresh token each time an old one is used,
-and invalidate the old one. However, it MUST ensure that the client is able to
-retry the refresh request in the case that the response to the request is lost.
-
-The homeserver SHOULD consider that the session is compromised if an old,
-invalidated refresh token is used, and SHOULD revoke the session.
-
-The client MUST handle access token refresh failures as follows:
-
- - If the refresh fails due to network issues or a `5xx` HTTP status code from
-   the server, the client should retry the request with the old refresh token
-   later.
- - If the refresh fails due to a `4xx` HTTP status code from the server, the
-   client should consider the session logged out.
-
 #### Token revocation
 
 When a user wants to log out from a client, the client SHOULD use OAuth 2.0
@@ -3513,10 +2970,6 @@ 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/key_backup_session_data.yaml

@@ -23,7 +23,6 @@ properties:
     type: string
     description: |-
       The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`.
-    example: "m.megolm.v1.aes-sha2"
   forwarding_curve25519_key_chain:
     type: array
     items:
@@ -31,24 +30,31 @@ properties:
     description: |-
       Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
       events.
-    example: [ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ]
   sender_key:
     type: string
     description: |-
       Unpadded base64-encoded device Curve25519 key.
-    example: "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
   sender_claimed_keys:
     type: object
     additionalProperties:
       type: string
     description: |-
       A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device.
-    example: { "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" }
   session_key:
     type: string
     description: |-
       Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
-    example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
+example: {
+  "algorithm": "m.megolm.v1.aes-sha2",
+  "forwarding_curve25519_key_chain": [
+    "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
+  ],
+  "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+  "sender_claimed_keys": {
+    "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
+  },
+  "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
+}
 required:
   - algorithm
   - forwarding_curve25519_key_chain

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

@@ -17,8 +17,6 @@ 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:
@@ -31,8 +29,6 @@ properties:
     example: 42
   room_id:
     type: string
-    format: mx-room-id
-    pattern: "^!"
     description: The ID of the room.
     example: "!abcdefg:example.org"
   topic:
@@ -65,6 +61,7 @@ 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

@@ -1,50 +0,0 @@
-# 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/oauth_server_metadata.yaml

@@ -1,176 +0,0 @@
-# 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

data/api/client-server/room_summary.yaml

@@ -1,143 +0,0 @@
-# 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,10 +102,15 @@ paths:
                        * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
                     items:
                       allOf:
-                        - $ref: definitions/room_summary.yaml
+                        - $ref: definitions/public_rooms_chunk.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: |-
@@ -125,14 +130,6 @@ 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,10 +61,22 @@ paths:
                   room:
                     description: A summary of the room requested.
                     allOf:
-                      - $ref: ../client-server/definitions/room_summary.yaml
+                      - $ref: ../client-server/definitions/public_rooms_chunk.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: |-
@@ -84,12 +96,6 @@ 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:
@@ -99,16 +105,22 @@ paths:
                       be excluded.
                     items:
                       allOf:
-                        - $ref: ../client-server/definitions/room_summary.yaml
+                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
                         - type: object
                           title: SpaceHierarchyChildRoomsChunk
                           properties:
                             room_type:
-                              x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
+                              type: string
-                            encryption:
+                              description: The `type` of room (from
-                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                                [`m.room.create`](/client-server-api/#mroomcreate)),
-                            room_version:
+                                if any.
-                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            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.
                   inaccessible_children:
                     type: array
                     items:

data/schemas/oauth2-client-metadata.yaml

@@ -1,140 +0,0 @@
-# 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.
-title: OAuthClientMetadata
-type: object
-description: |-
-  This definition of the metadata specifies only the fields that are meaningful
-  in the context of the Matrix specification. All the possible values are
-  registered in the [OAuth Dynamic Client Registration Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata),
-  and normative definitions of them are available in their respective RFCs.
-properties:
-  client_uri:
-    type: string
-    format: uri
-    description: |-
-      A URL to a valid web page that SHOULD give the user more information about
-      the client.
-
-      This URL MUST use the `https` scheme and SHOULD NOT require authentication
-      to access. It MUST NOT use a user or password in the authority component
-      of the URI.
-
-      The server MAY reject client registrations if this field is invalid or
-      missing.
-
-      This URI is a common base for all the other URIs in the metadata: those
-      MUST be either on the same host or on a subdomain of the host of the
-      `client_uri`. The port number, path and query components MAY be different.
-
-      For example, if the `client_uri` is `https://example.com/`, then one of
-      the `redirect_uris` can be `https://example.com/callback` or
-      `https://app.example.com/callback`, but not `https://app.com/callback`.
-  client_name:
-    type: string
-    description: |-
-      Human-readable name of the client to be presented to the user.
-
-      This field can be [localized](/client-server-api/#metadata-localization).
-  logo_uri:
-    type: string
-    format: uri
-    description: |-
-      URL that references a logo for the client.
-
-      This URL MUST use the `https` scheme.
-
-      This field can be [localized](/client-server-api/#metadata-localization).
-  tos_uri:
-    type: string
-    format: uri
-    description: |-
-      URL that points to a human-readable terms of service document for the
-      client.
-
-      This URL MUST use the `https` scheme and SHOULD NOT require authentication
-      to access. It MUST NOT use a user or password in the authority component
-      of the URI.
-
-      If this field is set, the server SHOULD show or link to this URL.
-
-      This field can be [localized](/client-server-api/#metadata-localization).
-  policy_uri:
-    type: string
-    format: uri
-    description: |-
-      URL that points to a human-readable policy document for the client.
-
-      This URL MUST use the `https` scheme and SHOULD NOT require authentication
-      to access. It MUST NOT use a user or password in the authority component
-      of the URI.
-
-      If this field is set, the server SHOULD show or link to this URL.
-
-      This field can be [localized](/client-server-api/#metadata-localization).
-  redirect_uris:
-    type: array
-    description: |-
-      Array of redirection URIs for use in redirect-based flows.
-
-      At least one URI is required to use the authorization code grant.
-
-      The server MUST perform [validation on redirect URIs](/client-server-api/#redirect-uri-validation).
-    items:
-      type: string
-      format: uri
-      description: A redirection URI.
-  response_types:
-    type: array
-    description: |-
-      Array of the OAuth 2.0 response types that the client may use.
-
-      This MUST include the `code` value to use the authorization code grant.
-
-      The server MUST ignore values that it does not understand.
-    items:
-      type: string
-      description: A response type that the client may use.
-  grant_types:
-    type: array
-    description: |-
-      Array of the OAuth 2.0 grant types that the client may use.
-
-      This MUST include:
-      - the `authorization_code` value to use the authorization code grant,
-      - the `refresh_token` value to use the refresh token grant.
-
-      The server MUST ignore values that it does not understand.
-    items:
-      type: string
-      description: A grant type that the client may use.
-  token_endpoint_auth_method:
-    type: string
-    description: |-
-      String indicator of the requested authentication method for the token
-      endpoint.
-
-      The homeserver MUST support the `none` value, as most Matrix clients are
-      client-side only, do not have a server component, and therefore are public
-      clients.
-  application_type:
-    type: string
-    description: |-
-      Kind of the application.
-
-      The homeserver MUST support the `web` and `native` values to be able to
-      perform [redirect URI validation](/client-server-api/#redirect-uri-validation).
-
-      Defaults to `web` if omitted.
-required:
-  - client_uri