wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into travis/s2s/backfill

Browse source
This commit is contained in:
Travis Ralston 2018-08-03 08:54:40 -06:00 • committed by GitHub
commit 3a9fb11c9b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 663 additions and 304 deletions
Download patch file Download diff file Expand all files Collapse all files

54
api/server-server/definitions/keys.yaml
View file

@ -20,50 +20,62 @@ properties:
server_name:
type: string
description: DNS name of the homeserver.
required: true # TODO: Verify
required: true
example: "example.org"
verify_keys:
type: object
description: Public keys of the homeserver for verifying digital signatures.
required: true # TODO: Verify
description: |-
Public keys of the homeserver for verifying digital signatures.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``abc123`` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
required: true
additionalProperties:
type: object
title: Verify Key
example: {
"ed25519:auto2": {
"key": "Base+64+Encoded+Signature+Verification+Key"
"ed25519:abc123": {
"key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
}
}
properties:
key:
type: string
description: The key
description: The `Unpadded Base64`_ encoded key.
required: true
example: "Base+64+Encoded+Signature+Verification+Key"
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
old_verify_keys:
type: object
description: The public keys that the server used to use and when it stopped using them.
description: |-
The public keys that the server used to use and when it stopped using them.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``0ldK3y`` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
additionalProperties:
type: object
title: Old Verify Key
example: {
"ed25519:auto1": {
"expired_ts": 922834800000,
"key": "Base+64+Encoded+Signature+Verification+Key"
"ed25519:0ldK3y": {
"expired_ts": 1532645052628,
"key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
}
}
properties:
expired_ts:
type: integer
format: int64
description: The expiration time.
description: POSIX timestamp in milliseconds for when this key expired.
required: true
example: 922834800000
example: 1532645052628
key:
type: string
description: The key.
description: The `Unpadded Base64`_ encoded key.
required: true
example: "Base+64+Encoded+Signature+Verification+Key"
example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
signatures:
type: object
description: Digital signatures for this object signed using the ``verify_keys``.
@ -72,7 +84,7 @@ properties:
title: Signed Server
example: {
"example.org": {
"ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
"ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
}
}
additionalProperties:
@ -80,17 +92,19 @@ properties:
name: Encoded Signature Verification Key
tls_fingerprints:
type: array
description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_.
description: Hashes of X.509 TLS certificates used by this server.
items:
type: object
title: TLS Fingerprint
properties:
sha256:
type: string
description: The encoded fingerprint.
example: Base+64+Encoded+SHA-256-Fingerprint
description: The `Unpadded Base64`_ encoded fingerprint.
example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
valid_until_ts:
type: integer
format: int64
description: POSIX timestamp when the list of valid keys should be refreshed.
description: |-
POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
timestamp are no longer valid.
example: 1052262000000

4
api/server-server/definitions/keys_query_response.yaml
View file

@ -15,13 +15,13 @@ type: object
description: Server keys
example: {
"server_keys": [{
$ref: "../examples/server_key.json"
$ref: "../examples/server_key_notary_signed.json"
}]
}
properties:
server_keys:
type: array
title: Server Keys
description: The server keys.
description: The queried server's keys, signed by the notary server.
items:
$ref: "keys.yaml"

8
api/server-server/definitions/transaction.yaml
View file

@ -25,11 +25,13 @@ properties:
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on originating homeserver when this transaction started.
example: 1234567890
description: |-
POSIX timestamp in milliseconds on originating homeserver when this
transaction started.
example: 1532991320875
pdus:
type: array
description: List of persistent updates to rooms.
items:
$ref: "pdu.yaml"
required: ['origin', 'origin_server_ts', 'pdus']
required: ['origin', 'origin_server_ts', 'pdus']

76
api/server-server/events.yaml
View file

@ -27,7 +27,7 @@ paths:
get:
summary: Get all the state of a given room
description: |-
Retrieves a snapshot of the entire current state of the given room.
Retrieves a snapshot of a room's state at a given event.
operationId: getRoomState
parameters:
- in: path
@ -36,11 +36,81 @@ paths:
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
responses:
200:
description: The room state for the room (kept under ``pdus``).
description: |-
The fully resolved state for the room, including the authorization
chain for the events.
schema:
$ref: "definitions/transaction.yaml"
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"}]
pdus:
type: array
description: |-
The fully resolved state of the room at the given event.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
required: ['auth_chain', 'pdus']
"/state_ids/{roomId}":
get:
summary: Get all the state event IDs of a given room
description: |-
Retrieves a snapshot of a room's state at a given event, in the form of
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
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: event_id
type: string
description: An event ID in the room to retrieve the state at.
required: true
x-example: "$helloworld:matrix.org"
responses:
200:
description: |-
The fully resolved state for the room, including the authorization
chain for the events.
schema:
type: object
properties:
auth_chain_ids:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively.
items:
type: string
example: ["$an_event:domain.com"]
pdu_ids:
type: array
description: |-
The fully resolved state of the room at the given event.
items:
type: string
example: ["$an_event:domain.com"]
required: ['auth_chain_ids', 'pdu_ids']
"/event/{eventId}":
get:
summary: Get a single event

16
api/server-server/examples/server_key.json
View file

@ -1,23 +1,23 @@
{
"server_name": "example.org",
"verify_keys": {
"ed25519:auto2": {
"key": "Base+64+Encoded+Signature+Verification+Key"
"ed25519:abc123": {
"key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
}
},
"old_verify_keys": {
"ed25519:auto1": {
"expired_ts": 922834800000,
"key": "Base+64+Encoded+Old+Verify+Key"
"ed25519:0ldk3y": {
"expired_ts": 1532645052628,
"key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
}
},
"signatures": {
"example.org": {
"ed25519:auto2": "Base+64+Encoded+Signature"
"ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
}
},
"tls_fingerprints": [{
"sha256": "Base+64+Encoded+SHA-256-Fingerprint"
"sha256": "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
}],
"valid_until_ts": 1052262000000
"valid_until_ts": 1652262000000
}

11
api/server-server/examples/server_key_notary_signed.json Normal file
View file

@ -0,0 +1,11 @@
{
"$ref": "server_key.json",
"signatures": {
"example.org": {
"ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
},
"notary.server.com": {
"ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
}
}
}

31
api/server-server/joins.yaml
View file

@ -29,7 +29,6 @@ paths:
description: |-
Asks the receiving server to return information that the sending
server will need to prepare a join event to get into the room.
This is part of the `Joining Rooms`_ handshake.
operationId: makeJoin
parameters:
- in: path
@ -95,7 +94,9 @@ paths:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to join the room.
allow the member to join the room. This should normally be the
``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
events.
items:
type: array
maxItems: 2
@ -128,7 +129,12 @@ paths:
"state_key": "@someone:example.org",
"content": {
"membership": "join"
}
},
"auth_events": [
["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
]
}
"/send_join/{roomId}/{eventId}":
put:
@ -250,27 +256,30 @@ paths:
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: The auth chain.
items:
type: object
properties: {}
# TODO: Verify schema
schema:
$ref: "definitions/pdu.yaml"
state:
type: array
description: The room state.
items:
type: object
properties: {}
# TODO: Verify schema
required: ["auth_chain", "state"]
schema:
$ref: "definitions/pdu.yaml"
required: ["auth_chain", "state", "origin"]
examples:
application/json: [
200,
{
# TODO: Use the appropriate refs (see TODOs in schema)
"auth_chain": [],
"state": []
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/pdu.json"}],
"state": [{"$ref": "examples/pdu.json"}]
}
]

66
api/server-server/keys_query.yaml
View file

@ -25,49 +25,61 @@ produces:
paths:
"/query/{serverName}/{keyId}":
get:
summary: Retrieve a server key.
description: Retrieve a server key.
summary: Query for another server's keys
description: |-
Query for another server's keys. The receiving (notary) server must
sign the keys returned by the queried server.
operationId: perspectivesKeyQuery
parameters:
- in: path
name: serverName
type: string
description: Server name.
description: The server's DNS name to query
required: true
x-example: matrix.org
- in: path
name: keyId
type: string
description: Key ID.
required: true
x-example: TODO # No examples in spec so far
description: |-
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
look up.
required: false
x-example: "ed25519:abc123"
- in: query
name: minimum_valid_until_ts
type: integer
format: int64
description: Minimum Valid Until Milliseconds.
required: true # TODO: Verify
description: |-
A millisecond POSIX timestamp in milliseconds indicating when the returned
certificates will need to be valid until to be useful to the requesting server.
If not supplied, the current time as determined by the notary server is used.
required: false
x-example: 1234567890
responses:
200:
description: The keys for the server
description: |-
The keys for the server, or an empty array if the server could not be reached
and no cached keys were available.
schema:
$ref: "definitions/keys_query_response.yaml"
"/query":
post:
summary: Retrieve a server key
description: Retrieve a server key.
summary: Query for several server's keys
description: |-
Query for keys from multiple servers in a batch format. The receiving (notary)
server must sign the keys returned by the queried servers.
operationId: bulkPerspectivesKeyQuery
parameters:
- in: body
name: body
schema:
type: object
# TODO: Improve example
example: {
"server_keys": {
"{server_name}": {
"{key_id}": {
"example.org": {
"ed25519:abc123": {
"minimum_valid_until_ts": 1234567890
}
}
@ -76,7 +88,16 @@ paths:
properties:
server_keys:
type: object
description: The query criteria.
description: |-
The query criteria. The outer ``string`` key on the object is the
server name (eg: ``matrix.org``). The inner ``string`` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty ``server_keys``
array in the response.
The notary server may return multiple keys regardless of the Key IDs
given.
additionalProperties:
type: object
name: ServerName
@ -84,16 +105,25 @@ paths:
additionalProperties:
type: object
title: Query Criteria
description: The server keys to query.
description: The server key IDs to query.
properties:
minimum_valid_until_ts:
type: integer
format: int64
description: Minimum Valid Until MS.
description: |-
A millisecond POSIX timestamp in milliseconds indicating when
the returned certificates will need to be valid until to be
useful to the requesting server.
If not supplied, the current time as determined by the notary
server is used.
example: 1234567890
required: ['server_keys']
responses:
200:
description: The keys for the server.
description: |-
The keys for the queried servers, signed by the notary server. Servers which
are offline and have no cached keys will not be included in the result. This
may result in an empty array.
schema:
$ref: "definitions/keys_query_response.yaml"

29
api/server-server/keys_server.yaml
View file

@ -25,18 +25,37 @@ produces:
paths:
"/server/{keyId}":
get:
summary: Get the server's key
description: Get the server's key.
summary: Get the homeserver's public key(s)
description: |-
Gets the homeserver's published TLS fingerprints and signing keys.
The homeserver may have any number of active keys and may have a
number of old keys.
Intermediate notary servers should cache a response for half of its
lifetime to avoid serving a stale response. Originating servers should
avoid returning responses that expire in less than an hour to avoid
repeated reqests for a certificate that is about to expire. Requesting
servers should limit how frequently they query for certificates to
avoid flooding a server with requests.
If the server fails to respond to this request, intermediate notary
servers should continue to return the last response they received
from the server so that the signatures of old events can still be
checked.
operationId: getServerKey
parameters:
- in: path
name: keyId
type: string
description: Key ID
description: |-
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
look up.
required: false
x-example: TODO # No examples in the spec so far
x-example: "ed25519:abc123"
deprecated: true
responses:
200:
description: The server's keys.
description: The homeserver's keys
schema:
$ref: "definitions/keys.yaml"

266
api/server-server/leaving.yaml Normal file
View file

@ -0,0 +1,266 @@
# 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 Leave Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/make_leave/{roomId}/{userId}":
get:
summary: Get information required to make a leave event for a room
description: |-
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
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: userId
type: string
description: The user ID the leave event will be for.
required: true
x-example: "@someone:example.org"
responses:
200:
description: |-
An unsigned event that the sending server may use as a template
for when it calls ``/send_leave``.
schema:
allOf:
- $ref: "definitions/unsigned_pdu.yaml"
- type: object
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value ``leave``.
example: "leave"
required: ['membership']
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to leave the room. This should normally be the
``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
events.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
examples:
application/json: {
"$ref": "examples/unsigned_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"content": {
"membership": "leave"
},
"auth_events": [
["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
]
}
403:
description: |-
The request is not authorized. This could mean that the user is not in the room.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "User is not in the room."
}
"/send_leave/{roomId}/{eventId}":
put:
summary: Submit a signed leave event to a resident server
description: |-
Submits a signed leave event to the resident server for it
to accept it into the room's graph.
operationId: sendLeave
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID for the leave event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
allOf:
- $ref: "definitions/pdu.yaml"
- type: object
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value ``leave``.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to leave the room.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
example: {
"$ref": "examples/pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"content": {
"membership": "leave"
}
}
responses:
200:
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: Empty Object
description: An empty object.
examples:
application/json: [200, {}]

58
api/server-server/transactions.yaml
View file

@ -30,16 +30,18 @@ paths:
Push messages representing live activity to another server. The destination name
will be set to that of the receiving server itself. Each embedded PDU in the
transaction body will be processed.
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
parameters:
- in: path
name: txnId
type: string
# TODO: "Overrides any ID given in the JSON body" - What does this mean?
description: |-
The transaction ID. Overrides any ID given in the JSON body.
The transaction ID.
required: true
x-example: TODO # No examples in the spec so far
x-example: S0meTransacti0nId
- in: body
name: body
type: object
@ -51,7 +53,9 @@ paths:
properties:
edus:
type: array
description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
description: |-
List of ephemeral messages. May be omitted if there are no ephemeral
messages to be sent.
items:
$ref: "definitions/edu.yaml"
example: {
@ -60,5 +64,47 @@ paths:
}
responses:
200:
# TODO: Spec this (and figure out what it is)
description: TODO
description: |-
The result of processing the transaction. The server is to use this response even in
the event of one or more PDUs failing to be processed.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: PDU Processing Results
description: The results for the processing of each PDU in the transaction.
properties:
pdus:
type: object
description: |-
The PDUs from the original transaction. The string key represents the ID of the
PDU (event) that was processed.
additionalProperties:
type: object
title: PDU Processing Result
description: Information about how the PDU was handled.
properties:
error:
type: string
description: |-
A human readable description about what went wrong in processing this PDU.
If no error is present, the PDU can be considered successfully handled.
example: "You are not allowed to send a message to this room."
required: ['pdus']
examples:
application/json: [
200,
{
"pdus": {
"$successful_event:domain.com": {},
"$failed_event:example.org": {
"error": "You are not allowed to send a message to this room."
}
}
}
]