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:
* 43ecfe0b10/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
pull/977/head
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']

@ -440,6 +440,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
----

Loading…
Cancel
Save