Merge remote-tracking branch 'matrix-org/master' into travis/as/normal-events
commit
51193cac39
@ -0,0 +1,267 @@
|
||||
# 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 Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: "/"
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
paths:
|
||||
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
|
||||
get:
|
||||
summary: Retrieve metadata about a specific protocol that the application service supports.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to present clients
|
||||
with specific information about the various third party networks that
|
||||
an application service supports.
|
||||
operationId: getProtocolMetadata
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
responses:
|
||||
200:
|
||||
description: The protocol was found and metadata returned.
|
||||
schema:
|
||||
$ref: definitions/protocol_metadata.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No protocol was found with the given path.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user/{protocol}":
|
||||
get:
|
||||
summary: Retrieve the Matrix User ID of a corresponding third party user.
|
||||
description: |-
|
||||
This API is called by the homeserver in order to retrieve a Matrix
|
||||
User ID linked to a user on the third party network, given a set of
|
||||
user parameters.
|
||||
operationId: queryUserByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the user.
|
||||
responses:
|
||||
200:
|
||||
description: The Matrix User IDs found with the given parameters.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No users were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retrieve Matrix-side portal rooms leading to a third party location.
|
||||
description: |-
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
|
||||
operationId: queryLocationByProtocol
|
||||
parameters:
|
||||
- in: path
|
||||
name: protocol
|
||||
type: string
|
||||
description: The protocol ID.
|
||||
required: true
|
||||
x-example: irc
|
||||
- in: query
|
||||
name: fields...
|
||||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the third party location.
|
||||
responses:
|
||||
200:
|
||||
description: At least one portal room was found.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/location":
|
||||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retrieve an array of third party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
parameters:
|
||||
- in: query
|
||||
name: alias
|
||||
type: string
|
||||
description: The Matrix room alias to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
All found third party locations.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/_matrix/app/unstable/thirdparty/user":
|
||||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retrieve an array of third party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
parameters:
|
||||
- in: query
|
||||
name: userid
|
||||
type: string
|
||||
description: The Matrix User ID to look up.
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An array of third party users.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
description: |-
|
||||
The homeserver has not supplied credentials to the application service.
|
||||
Optional error information can be included in the body of this response.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
403:
|
||||
description: |-
|
||||
The credentials supplied by the homeserver were rejected.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
404:
|
||||
description: No mappings were found with the given parameters.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
|
||||
}
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
@ -0,0 +1,87 @@
|
||||
# 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 Client-Server Application Service Room Directory API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
# Note: this is the same access_token definition used elsewhere in the client
|
||||
# server API, however this expects an access token for an application service.
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/directory/list/appservice/{networkId}/{roomId}":
|
||||
put:
|
||||
summary: |-
|
||||
Updates a room's visibility in the application service's room directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room on the application service's room
|
||||
directory.
|
||||
|
||||
This API is similar to the room directory visibility API used by clients
|
||||
to update the homeserver's more general room directory.
|
||||
|
||||
This API requires the use of an application service access token (``as_token``)
|
||||
instead of a typical client's access_token. This API cannot be invoked by
|
||||
users who are not identified as application services.
|
||||
operationId: updateAppserviceRoomDirectoryVsibility
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: networkId
|
||||
description: |-
|
||||
The protocol (network) ID to update the room list for. This would
|
||||
have been provided by the application service as being listed as
|
||||
a supported protocol.
|
||||
required: true
|
||||
x-example: "irc"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room ID to add to the directory.
|
||||
required: true
|
||||
x-example: "!somewhere:domain.com"
|
||||
- in: body
|
||||
name: body
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
visibility:
|
||||
type: enum
|
||||
enum: ["public", "private"]
|
||||
description: |-
|
||||
Whether the room should be visible (public) in the directory
|
||||
or not (private).
|
||||
example: "public"
|
||||
required: ['visibility']
|
||||
security:
|
||||
# again, this is the appservice's token - not a typical client's
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The room's directory visibility has been updated.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: {}
|
||||
tags:
|
||||
- Application service room directory management
|
@ -0,0 +1 @@
|
||||
Add support for Room Versions.
|
@ -0,0 +1 @@
|
||||
Add server ACLs as an option for controlling federation in a room.
|
@ -0,0 +1 @@
|
||||
Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.
|
@ -0,0 +1 @@
|
||||
Add new push rules for encrypted events and ``@room`` notifications.
|
@ -0,0 +1 @@
|
||||
Add third party network room directories, as provided by application services.
|
@ -0,0 +1 @@
|
||||
Fix naming of the body field in ``PUT /directory/room``.
|
@ -0,0 +1,14 @@
|
||||
{
|
||||
"age": 242352,
|
||||
"content": {
|
||||
"allow_ip_literals": false,
|
||||
"allow": ["*"],
|
||||
"deny": ["*.evil.com", "evil.com"]
|
||||
},
|
||||
"state_key": "",
|
||||
"origin_server_ts": 1431961217939,
|
||||
"event_id": "$WLGTSEFSEF:localhost",
|
||||
"type": "m.room.server_acl",
|
||||
"room_id": "!Cuyf34gef24t:localhost",
|
||||
"sender": "@example:localhost"
|
||||
}
|
@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Server ACL
|
||||
description: |-
|
||||
An event to indicate which servers are permitted to participate in the
|
||||
room. Server ACLs may allow or deny groups of hosts. All servers participating
|
||||
in the room, including those that are denied, are expected to uphold the
|
||||
server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
|
||||
list in order for the ACLs to remain effective.
|
||||
|
||||
The ``allow`` and ``deny`` lists are lists of globs supporting ``?`` and ``*``
|
||||
as wildcards. When comparing against the server ACLs, the suspect server's port
|
||||
number must not be considered. Therefore ``evil.com``, ``evil.com:8448``, and
|
||||
``evil.com:1234`` would all match rules that apply to ``evil.com``, for example.
|
||||
|
||||
The ACLs are applied to servers when they make requests, and are applied in
|
||||
the following order:
|
||||
|
||||
1. If there is no ``m.room.server_acl`` event in the room state, allow.
|
||||
#. If the server name is an IP address (v4 or v6) literal, and ``allow_ip_literals``
|
||||
is present and ``false``, deny.
|
||||
#. If the server name matches an entry in the ``deny`` list, deny.
|
||||
#. If the server name matches an entry in the ``allow`` list, allow.
|
||||
#. Otherwise, deny.
|
||||
|
||||
.. Note::
|
||||
Server ACLs do not restrict the events relative to the room DAG via authorisation
|
||||
rules, but instead act purely at the network layer to determine which servers are
|
||||
allowed to connect and interact with a given room.
|
||||
|
||||
.. WARNING::
|
||||
Failing to provide an ``allow`` rule of some kind will prevent **all**
|
||||
servers from participating in the room, including the sender. This renders
|
||||
the room unusable. A common allow rule is ``[ "*" ]`` which would still
|
||||
permit the use of the ``deny`` list without losing the room.
|
||||
|
||||
.. WARNING::
|
||||
All compliant servers must implement server ACLs. However, legacy or noncompliant
|
||||
servers exist which do not uphold ACLs, and these MUST be manually appended to
|
||||
the denied hosts list when setting an ACL to prevent them from leaking events from
|
||||
banned servers into a room. Currently, the only way to determine noncompliant hosts is
|
||||
to check the ``prev_events`` of leaked events, therefore detecting servers which
|
||||
are not upholding the ACLs. Server versions can also be used to try to detect hosts that
|
||||
will not uphold the ACLs, although this is not comprehensive. Server ACLs were added
|
||||
in Synapse v0.32.0, although other server implementations and versions exist in the world.
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
type: object
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
allow_ip_literals:
|
||||
type: boolean
|
||||
description: |-
|
||||
True to allow server names that are IP address literals. False to
|
||||
deny. Defaults to true if missing or otherwise not a boolean.
|
||||
|
||||
This is strongly recommended to be set to ``false`` as servers running
|
||||
with IP literal names are strongly discouraged in order to require
|
||||
legitimate homeservers to be backed by a valid registered domain name.
|
||||
allow:
|
||||
type: array
|
||||
description: |-
|
||||
The server names to allow in the room, excluding any port information.
|
||||
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||
matches zero or more characters and ``?`` matches exactly one character.
|
||||
|
||||
**This defaults to an empty list when not provided, effectively disallowing
|
||||
every server.**
|
||||
items:
|
||||
type: string
|
||||
deny:
|
||||
type: array
|
||||
description: |-
|
||||
The server names to disallow in the room, excluding any port information.
|
||||
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||
matches zero or more characters and ``?`` matches exactly one character.
|
||||
|
||||
This defaults to an empty list when not provided.
|
||||
items:
|
||||
type: string
|
||||
type: object
|
||||
state_key:
|
||||
description: A zero-length string.
|
||||
pattern: '^$'
|
||||
type: string
|
||||
type:
|
||||
enum: ['m.room.server_acl']
|
||||
type: enum
|
@ -0,0 +1,70 @@
|
||||
.. 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.
|
||||
|
||||
Server Access Control Lists (ACLs) for rooms
|
||||
============================================
|
||||
|
||||
.. _module:server-acls:
|
||||
|
||||
In some scenarios room operators may wish to prevent a malicious or untrusted
|
||||
server from participating in their room. Sending an `m.room.server_acl`_ state
|
||||
event into a room is an effective way to prevent the server from participating
|
||||
in the room at the federation level.
|
||||
|
||||
Server ACLs can also be used to make rooms only federate with a limited set of
|
||||
servers, or retroactively make the room no longer federate with any other server,
|
||||
similar to setting the ``m.federate`` value on the `m.room.create`_ event.
|
||||
|
||||
{{m_room_server_acl_event}}
|
||||
|
||||
.. Note::
|
||||
Port numbers are not supported because it is unclear to parsers whether a
|
||||
port number should be matched or an IP address literal. Additionally, it
|
||||
is unlikely that one would trust a server running on a particular domain's
|
||||
port but not a different port, especially considering the server host can
|
||||
easily change ports.
|
||||
|
||||
.. Note::
|
||||
CIDR notation is not supported for IP addresses because Matrix does not
|
||||
encourage the use of IPs for identifying servers. Instead, a blanket
|
||||
``allow_ip_literals`` is provided to cover banning them.
|
||||
|
||||
Client behaviour
|
||||
----------------
|
||||
Clients are not expected to perform any additional duties beyond sending the
|
||||
event. Clients should describe changes to the server ACLs to the user in the
|
||||
user interface, such as in the timeline.
|
||||
|
||||
Clients may wish to kick affected users from the room prior to denying a server
|
||||
access to the room to help prevent those servers from participating and to
|
||||
provide feedback to the users that they have been excluded from the room.
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
Servers MUST prevent blacklisted servers from sending events or participating
|
||||
in the room when an `m.room.server_acl`_ event is present in the room state.
|
||||
Which APIs are specifically affected are described in the Server-Server API
|
||||
specification.
|
||||
|
||||
Servers should still send events to denied servers if they are still residents
|
||||
of the room.
|
||||
|
||||
|
||||
Security considerations
|
||||
-----------------------
|
||||
Server ACLs are only effective if every server in the room honours them. Servers
|
||||
that do not honour the ACLs may still permit events sent by denied servers into
|
||||
the room, leaking them to other servers in the room. To effectively enforce an
|
||||
ACL in a room, the servers that do not honour the ACLs should be denied in the
|
||||
room as well.
|
Loading…
Reference in New Issue