From 25c77ab2d0a9dd6a67454e27107ee4bdcbfe86b2 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Fri, 3 Aug 2018 13:43:07 -0600
Subject: [PATCH] Define authorization requirements on federation swagger APIs

---
 api/server-server/backfill.yaml             |  6 ++++++
 api/server-server/definitions/security.yaml | 19 +++++++++++++++++++
 api/server-server/event_auth.yaml           |  6 ++++++
 api/server-server/events.yaml               |  8 ++++++++
 api/server-server/invites.yaml              |  4 ++++
 api/server-server/joins.yaml                |  6 ++++++
 api/server-server/leaving.yaml              |  6 ++++++
 api/server-server/public_rooms.yaml         |  4 ++++
 api/server-server/query.yaml                |  9 +++++++++
 api/server-server/third_party_invite.yaml   |  4 ++++
 api/server-server/transactions.yaml         |  4 ++++
 11 files changed, 76 insertions(+)
 create mode 100644 api/server-server/definitions/security.yaml

diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml
index f9f105e2..6b3cfaef 100644
--- a/api/server-server/backfill.yaml
+++ b/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
diff --git a/api/server-server/definitions/security.yaml b/api/server-server/definitions/security.yaml
new file mode 100644
index 00000000..6c9cc808
--- /dev/null
+++ b/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
diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml
index f55afddc..8857131f 100644
--- a/api/server-server/event_auth.yaml
+++ b/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
diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml
index e87a0685..cf3988a2 100644
--- a/api/server-server/events.yaml
+++ b/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
diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml
index 98d53d49..6d905e17 100644
--- a/api/server-server/invites.yaml
+++ b/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
diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml
index 14142945..e76a0aa6 100644
--- a/api/server-server/joins.yaml
+++ b/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
diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml
index 28bcf42c..be08acba 100644
--- a/api/server-server/leaving.yaml
+++ b/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
diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml
index 6cd07449..d162568f 100644
--- a/api/server-server/public_rooms.yaml
+++ b/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
diff --git a/api/server-server/query.yaml b/api/server-server/query.yaml
index f569549e..dc14724c 100644
--- a/api/server-server/query.yaml
+++ b/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
diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml
index 754a3282..5c12247c 100644
--- a/api/server-server/third_party_invite.yaml
+++ b/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
diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml
index 4f4c6b28..8d810ad5 100644
--- a/api/server-server/transactions.yaml
+++ b/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