From c5074f2a1f1cc0a0d825b4d5154be2a9b3552380 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 22 Feb 2024 15:32:01 +0100 Subject: [PATCH 1/3] Allow /versions to optionally accept authentication MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit According to MSC2046. Signed-off-by: Kévin Commaille --- data/api/client-server/versions.yaml | 21 +++++++++++++++---- .../partials/openapi/render-operation.html | 17 ++++++++++++++- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index 14785e53a..7cf9a40ef 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 b3878664f..4c004c27c 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -59,7 +59,22 @@

Requires authentication: - {{ if $operation_data.security }}Yes{{ else }}No{{ end }} + {{/* + Authentication is optional if one of these is true: + - the security key is not set + - the security value contains an empty object + */}} + {{ $requires_authentication := 1 }} + {{ if $operation_data.security }} + {{ range $operation_data.security }} + {{ if eq (len (index $operation_data.security 0)) 0 }} + {{ $requires_authentication = 0 }} + {{ end }} + {{ end }} + {{ else }} + {{ $requires_authentication = 0 }} + {{ end }} + {{ if $requires_authentication }}Yes{{ else }}No{{ end }} From 8ade27c301aea0fc8fb7da444345f04c7c6e0e36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 22 Feb 2024 16:39:05 +0100 Subject: [PATCH 2/3] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1728.feature | 1 + 1 file changed, 1 insertion(+) 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 000000000..98d055fba --- /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). From 82d37d8e1a152d7c9d8fe36661fa23571286c74d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 4 Mar 2024 10:36:17 +0100 Subject: [PATCH 3/3] Set "Requires Authentication: Optional" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- layouts/partials/openapi/render-operation.html | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 4c004c27c..253e2efe8 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -60,21 +60,22 @@

Requires authentication: {{/* - Authentication is optional if one of these is true: - - the security key is not set - - the security value contains an empty object + 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 := 1 }} + {{ $requires_authentication := "Yes" }} {{ if $operation_data.security }} {{ range $operation_data.security }} {{ if eq (len (index $operation_data.security 0)) 0 }} - {{ $requires_authentication = 0 }} + {{ $requires_authentication = "Optional" }} {{ end }} {{ end }} {{ else }} - {{ $requires_authentication = 0 }} + {{ $requires_authentication = "No" }} {{ end }} - {{ if $requires_authentication }}Yes{{ else }}No{{ end }} + {{ $requires_authentication }}