From c5074f2a1f1cc0a0d825b4d5154be2a9b3552380 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Thu, 22 Feb 2024 15:32:01 +0100
Subject: [PATCH] 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 <zecakeh@tedomum.fr>
---
 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 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..4c004c27 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/layouts/partials/openapi/render-operation.html
@@ -59,7 +59,22 @@
   </tr>
  <tr>
   <th>Requires authentication:</th>
-  <td>{{ if $operation_data.security }}Yes{{ else }}No{{ end }}</td>
+  {{/*
+    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 }}
+  <td>{{ if $requires_authentication }}Yes{{ else }}No{{ end }}</td>
  </tr>
 </table>