From 542a219623645ad5bcb3048605ebad493a693b9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 7 Mar 2024 01:30:06 +0100 Subject: [PATCH] Allow `/versions` to optionally accept authentication (#1728) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Allow /versions to optionally accept authentication According to MSC2046. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Set "Requires Authentication: Optional" Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../client_server/newsfragments/1728.feature | 1 + data/api/client-server/versions.yaml | 21 +++++++++++++++---- .../partials/openapi/render-operation.html | 18 +++++++++++++++- 3 files changed, 35 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1728.feature diff --git a/changelogs/client_server/newsfragments/1728.feature b/changelogs/client_server/newsfragments/1728.feature new file mode 100644 index 00000000..98d055fb --- /dev/null +++ b/changelogs/client_server/newsfragments/1728.feature @@ -0,0 +1 @@ +Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index 14785e53..7cf9a40e 100644 --- a/data/api/client-server/versions.yaml +++ b/data/api/client-server/versions.yaml @@ -34,11 +34,21 @@ paths: which has not yet landed in the spec. For example, a feature currently undergoing the proposal process may appear here and eventually be taken off this list once the feature lands in the spec and the server deems it - reasonable to do so. Servers may wish to keep advertising features here - after they've been released into the spec to give clients a chance to - upgrade appropriately. Additionally, clients should avoid using unstable - features in their stable releases. + reasonable to do so. Servers can choose to enable some features only for + some users, so clients should include authentication in the request to + get all the features available for the logged-in user. If no + authentication is provided, the server should only return the features + available to all users. Servers may wish to keep advertising features + here after they've been released into the spec to give clients a chance + to upgrade appropriately. Additionally, clients should avoid using + unstable features in their stable releases. operationId: getVersions + security: + - {} + - accessToken: [] + x-changedInMatrixVersion: + "1.10": | + This endpoint can behave differently when authentication is provided. responses: "200": description: The versions supported by the server. @@ -89,3 +99,6 @@ servers: default: localhost:8008 basePath: default: /_matrix/client +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index b3878664..253e2efe 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -59,7 +59,23 @@ Requires authentication: - {{ if $operation_data.security }}Yes{{ else }}No{{ end }} + {{/* + Authentication is defined with the `security` key. We assume that the + key is not set if no authentication is necessary. If the key is set, + authentication is required unless it contains an item that is an empty + object. + */}} + {{ $requires_authentication := "Yes" }} + {{ if $operation_data.security }} + {{ range $operation_data.security }} + {{ if eq (len (index $operation_data.security 0)) 0 }} + {{ $requires_authentication = "Optional" }} + {{ end }} + {{ end }} + {{ else }} + {{ $requires_authentication = "No" }} + {{ end }} + {{ $requires_authentication }}