Merge pull request #1475 from turt2live/travis/s2s/event-auth

Document /event_auth and /query_auth

api/server-server/event_auth.yaml

@@ -0,0 +1,174 @@
+# 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.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Event Authorization API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+consumes: 
+  - application/json
+produces:
+  - application/json
+paths:
+  "/event_auth/{roomId}/{eventId}":
+    get:
+      summary: Get the auth chain for a given event
+      description: |-
+        Retrieves the complete auth chain for a given event.
+      operationId: getEventAuth
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get the auth chain for.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to get the auth chain of.
+          required: true
+          x-example: "$helloworld:domain.com"
+      responses:
+        200:
+          description: The auth chain for the event.
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: |-
+                  The full set of authorization events that make up the state of
+                  the room, and their authorization events, recursively. 
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+            required: ['auth_chain']
+  "/query_auth/{roomId}/{eventId}":
+    post:
+      summary: Compare auth chains with the receiving server
+      description: |-
+        Compares the auth chain provided with what the receiving server has for the
+        room ID and event ID combination.
+
+        The auth difference can be calculated in two parts, where the "remote auth"
+        is the auth chain provided by the sending server and the "local auth" is the
+        auth chain the receiving server has. With those lists, the algorithm works
+        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
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to compare the auth chain in.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to compare the auth chain of.
+          required: true
+          x-example: "$helloworld:domain.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: The auth chain (the "remote auth").
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              missing:
+                type: array
+                description: |-
+                  A list of event IDs that the sender thinks the receiver is missing.
+                items:
+                  type: string
+                example: []
+              rejects:
+                type: object
+                description: |-
+                  The set of events that the sending server has rejected from the provided
+                  auth chain.
+
+                  The ``string`` key is the event ID that was rejected.
+                additionalProperties:
+                  type: object
+                  title: Rejection Reason
+                  properties:
+                    reason:
+                      type: enum
+                      enum: ['auth_error', 'replaced', 'not_ancestor']
+                      description: |-
+                        The reason for the event being rejected.
+                  required: ['reason']
+                example: {
+                  "$some_event:domain.com": {
+                    "reason": "auth_error"
+                  }
+                }
+            required: ['auth_chain']
+      responses:
+        200:
+          description: The auth chain differences, as determined by the receiver.
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: |-
+                  The auth chain the receiver has, and used to determine the auth
+                  chain differences (the "local auth").
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              missing:
+                type: array
+                description: |-
+                  The list of event IDs that the receiver believes it is missing, 
+                  after comparing the "remote auth" and "local auth" chains.
+                items:
+                  type: string
+                example: ["$a_missing_event:domain.com"]
+              rejects:
+                type: object
+                description: |-
+                  The set of events that the receiving server has rejected from the
+                  auth chain, not including events that the sending server is missing
+                  as determined from the difference algorithm.
+
+                  The ``string`` key is the event ID that was rejected.
+                additionalProperties:
+                  type: object
+                  title: Rejection Reason
+                  properties:
+                    reason:
+                      type: enum
+                      enum: ['auth_error', 'replaced', 'not_ancestor']
+                      description: |-
+                        The reason for the event being rejected.
+                  required: ['reason']
+                example: {
+                  "$some_event:domain.com": {
+                    "reason": "auth_error"
+                  }
+                }
+            required: ['auth_chain', 'missing', 'rejects']

specification/server_server_api.rst

@@ -439,6 +439,15 @@ The rules are as follows:
 
   I think there is some magic about 3pid invites too.
 
+Retrieving event authorization information
+++++++++++++++++++++++++++++++++++++++++++
+
+The homeserver may be missing event authorization information, or wish to check
+with other servers to ensure it is receiving the correct auth chain. These APIs
+give the homeserver an avenue for getting the information it needs.
+
+{{event_auth_ss_http_api}}
+
 EDUs
 ----