Document /event_auth and /query_auth
/event_auth is a fairly easy endpoint to determine the use case of. /query_auth is a little harder to investigate and has a fairly interesting purpose: it appears to be used for the sending server to admit defeat and shop around for the right auth chain, correcting it's own perspective as it goes. /query_auth is based off the following research points in synapse: *pull/977/head43ecfe0b10/synapse/handlers/federation.py (L1947-L1990)*43ecfe0b10/synapse/handlers/federation.py (L2049-L2187)*43ecfe0b10/synapse/handlers/federation.py (L1716-L1761)*43ecfe0b10/synapse/federation/federation_server.py (L393-L446)* https://github.com/matrix-org/synapse/blob/master/synapse/federation/transport/server.py#L482-L487
Travis Ralston
6 years ago
parent
329baa1b9d
commit
73958ecbff
@ -0,0 +1,172 @@
|
||||
# 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
|
||||
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']
|
||||
Loading…
Reference in New Issue