Define authorization requirements on federation swagger APIs

api/server-server/backfill.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/backfill/{roomId}":
     get:
@@ -33,6 +35,8 @@ paths:
         Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
         are retrieved, up to the total number given by the ``limit``.
       operationId: backfillRoom
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -85,6 +89,8 @@ paths:
         walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
         and stopping at the ``limit``.
       operationId: getMissingPreviousEvents
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/definitions/security.yaml

@@ -0,0 +1,19 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+signedRequest:
+  type: apiKey
+  description: |-
+    The ``Authorization`` header defined in the `Authentication`_ section.
+  name: Authorization
+  in: header

api/server-server/event_auth.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/event_auth/{roomId}/{eventId}":
     get:
@@ -31,6 +33,8 @@ paths:
       description: |-
         Retrieves the complete auth chain for a given event.
       operationId: getEventAuth
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -72,6 +76,8 @@ paths:
         bottom-up after sorting each chain by depth then by event ID. The differences
         are then discovered and returned as the response to this API call.
       operationId: compareEventAuth
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/events.yaml

@@ -22,6 +22,8 @@ schemes:
 basePath: /_matrix/federation/v1
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/state/{roomId}":
     get:
@@ -29,6 +31,8 @@ paths:
       description: |-
         Retrieves a snapshot of a room's state at a given event.
       operationId: getRoomState
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -74,6 +78,8 @@ paths:
         event IDs. This performs the same function as calling ``/state/{roomId}``,
         however this returns just the event IDs rather than the full events.
       operationId: getRoomStateIds
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -117,6 +123,8 @@ paths:
       description: |-
         Retrieves a single event.
       operationId: getEvent
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: eventId

api/server-server/invites.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/invite/{roomId}/{eventId}":
     put:
@@ -33,6 +35,8 @@ paths:
         homeserver and the invited homeserver, it can be sent to all of the servers in the 
         room by the inviting homeserver.
       operationId: sendInvite
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/joins.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/make_join/{roomId}/{userId}":
     get:
@@ -32,6 +34,8 @@ paths:
         Asks the receiving server to return information that the sending
         server will need to prepare a join event to get into the room.
       operationId: makeJoin
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -145,6 +149,8 @@ paths:
         Submits a signed join event to the resident server for it
         to accept it into the room's graph.
       operationId: sendJoin
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/leaving.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/make_leave/{roomId}/{userId}":
     get:
@@ -32,6 +34,8 @@ paths:
         Asks the receiving server to return information that the sending
         server will need to prepare a leave event to get out of the room.
       operationId: makeLeave
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId
@@ -151,6 +155,8 @@ paths:
         Submits a signed leave event to the resident server for it
         to accept it into the room's graph.
       operationId: sendLeave
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/public_rooms.yaml

@@ -22,6 +22,8 @@ schemes:
 basePath: /_matrix/federation/v1
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/publicRooms":
     get:
@@ -31,6 +33,8 @@ paths:
         rooms that are listed on another homeserver's directory, just those
         listed on the receiving homeserver's directory.
       operationId: getPublicRooms
+      security:
+        - signedRequest: []
       parameters:
         - in: query
           name: limit

api/server-server/query.yaml

@@ -23,6 +23,8 @@ schemes:
 basePath: /_matrix/federation/v1
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/query/{queryType}":
     get:
@@ -32,6 +34,8 @@ paths:
         arguments are dependent on which type of query is being made. Known query types
         are specified as their own endpoints as an extension to this definition.
       operationId: queryInfo
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: queryType
@@ -54,6 +58,8 @@ paths:
         Servers may wish to cache the response to this query to avoid requesting the
         information too often.
       operationId: queryRoomDirectory
+      security:
+        - signedRequest: []
       parameters:
         - in: query
           name: room_alias
@@ -110,6 +116,9 @@ paths:
 
         Servers may wish to cache the response to this query to avoid requesting the
         information too often.
+      operationId: queryProfile
+      security:
+        - signedRequest: []
       parameters:
         - in: query
           name: user_id

api/server-server/third_party_invite.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/exchange_third_party_invite/{roomId}":
     put:
@@ -34,6 +36,8 @@ paths:
         an invite as per the `Inviting to a room`_ section before returning a
         response to this request.
       operationId: exchangeThirdPartyInvite
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: roomId

api/server-server/transactions.yaml

@@ -24,6 +24,8 @@ consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/send/{txnId}":
     put:
@@ -36,6 +38,8 @@ paths:
         The sending server must wait and retry for a 200 OK response before sending a
         transaction with a different ``txnId`` to the receiving server.
       operationId: sendTransaction
+      security:
+        - signedRequest: []
       parameters:
         - in: path
           name: txnId