diff --git a/changelogs/client_server/newsfragments/2125.feature b/changelogs/client_server/newsfragments/2125.feature new file mode 100644 index 00000000..f9275b0d --- /dev/null +++ b/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). diff --git a/changelogs/client_server/newsfragments/2147.new b/changelogs/client_server/newsfragments/2147.new new file mode 100644 index 00000000..c72bf35e --- /dev/null +++ b/changelogs/client_server/newsfragments/2147.new @@ -0,0 +1 @@ +Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). diff --git a/changelogs/client_server/newsfragments/2149.feature b/changelogs/client_server/newsfragments/2149.feature new file mode 100644 index 00000000..6eff5607 --- /dev/null +++ b/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. diff --git a/changelogs/client_server/newsfragments/2158.feature b/changelogs/client_server/newsfragments/2158.feature new file mode 100644 index 00000000..f9275b0d --- /dev/null +++ b/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). diff --git a/changelogs/server_server/newsfragments/2125.feature b/changelogs/server_server/newsfragments/2125.feature new file mode 100644 index 00000000..0a369ea0 --- /dev/null +++ b/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). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c62e6b55..e539788f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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-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:` | 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:` 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 diff --git a/data/api/client-server/definitions/public_rooms_chunk.yaml b/data/api/client-server/definitions/public_rooms_chunk.yaml index d2e9a09b..33276662 100644 --- a/data/api/client-server/definitions/public_rooms_chunk.yaml +++ b/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: diff --git a/data/api/client-server/definitions/room_summary.yaml b/data/api/client-server/definitions/room_summary.yaml new file mode 100644 index 00000000..8499bac1 --- /dev/null +++ b/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 diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml new file mode 100644 index 00000000..4cdb3aa6 --- /dev/null +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -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 diff --git a/data/api/client-server/room_summary.yaml b/data/api/client-server/room_summary.yaml new file mode 100644 index 00000000..e5e241ed --- /dev/null +++ b/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 diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml index 3a4a14a5..5f6657a2 100644 --- a/data/api/client-server/space_hierarchy.yaml +++ b/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: diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml index 8394588b..adc2c3e5 100644 --- a/data/api/server-server/space_hierarchy.yaml +++ b/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 - 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: