Allow /versions to optionally accept authentication (#1728)

* Allow /versions to optionally accept authentication

According to MSC2046.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Set "Requires Authentication: Optional"

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

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).

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

layouts/partials/openapi/render-operation.html

@@ -59,7 +59,23 @@ <h1 id="{{ lower $method }}{{ $anchor }}">
   </tr>
  <tr>
   <th>Requires authentication:</th>
-  <td>{{ if $operation_data.security }}Yes{{ else }}No{{ end }}</td>
+  {{/*
+    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 }}
+  <td>{{ $requires_authentication }}</td>
  </tr>
 </table>