# 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 securityDefinitions: $ref: definitions/security.yaml 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 security: - signedRequest: [] 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:example.org" 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. Note that events have a different version depending on the room version - check the `room version specification`_ for precise event formats. items: type: object title: PDU description: |- The `PDUs <#pdus>`_ contained in the auth chain. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. properties: [] example: $ref: "examples/minimal_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 security: - signedRequest: [] 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:example.org" - in: body name: body schema: type: object properties: auth_chain: type: array description: |- The auth chain (the "remote auth"). Note that events have a different version depending on the room version - check the `room version specification`_ for precise event formats. items: type: object title: PDU description: |- The `PDUs <#pdus>`_ contained in the auth chain. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. properties: [] example: $ref: "examples/minimal_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:example.org": { "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"). Note that events have a different version depending on the room version - check the `room version specification`_ for precise event formats. items: type: object title: PDU description: |- The `PDUs <#pdus>`_ contained in the auth chain. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. properties: [] example: $ref: "examples/minimal_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:example.org"] 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:example.org": { "reason": "auth_error" } } required: ['auth_chain', 'missing', 'rejects']