Merge remote-tracking branch 'matrix-org/master' into travis/c2s/pills

pull/1547/head
Travis Ralston 6 years ago
commit fa3e9a7609

@ -23,9 +23,29 @@ buildswaggerui: &buildswaggerui
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
patch api/client-server/index.html swagger-ui.patch patch api/client-server/index.html swagger-ui.patch
checkexamples: &checkexamples
name: Check Event Examples
command: |
source /env/bin/activate
cd event-schemas
./check_examples.py
genmatrixassets: &genmatrixassets
name: Generate/Verify matrix.org assets
command: |
source /env/bin/activate
./scripts/generate-matrix-org-assets
version: 2 version: 2
jobs: jobs:
check-docs:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *checkexamples
- run: *genmatrixassets # We don't actually use the assets, but we do want to make sure they build
build-docs: build-docs:
docker: docker:
- image: uhoreg/matrix-doc-build - image: uhoreg/matrix-doc-build

@ -19,12 +19,14 @@ properties:
protocol: protocol:
description: The protocol ID that the third party location is a part of. description: The protocol ID that the third party location is a part of.
type: string type: string
example: irc example: "irc"
fields: fields:
description: Information used to identify this third party location. description: Information used to identify this third party location.
type: object type: object
example: example: {
"network": "freenode" "network": "freenode",
"channel": "#matrix" "channel": "#matrix"
}
required: ['alias', 'protocol', 'fields']
title: Location title: Location
type: object type: object

@ -11,41 +11,60 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
title: Protocol
type: object
properties: properties:
user_fields: user_fields:
description: Fields used to identify a third party user. description: |-
Fields which may be used to identify a third party user. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the nickname of a user.
type: array type: array
items: items:
type: string type: string
description: Field used to identify a third party user. description: Field used to identify a third party user.
example: ["network", "nickname"] example: ["network", "nickname"]
location_fields: location_fields:
description: Fields used to identify a third party location. description: |-
Fields which may be used to identify a third party location. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the name of a channel.
type: array type: array
items: items:
type: string type: string
description: Field used to identify a third party location. description: Field used to identify a third party location.
example: ["network", "channel"] example: ["network", "channel"]
icon: icon:
description: An icon representing the third party protocol. description: A content URI representing an icon for the third party protocol.
type: string type: string
example: "mxc://example.org/aBcDeFgH" example: "mxc://example.org/aBcDeFgH"
field_types: field_types:
title: Field Types title: Field Types
description: All location or user fields should have an entry here. description: |-
The type definitions for the fields defined in the ``user_fields`` and
``location_fields``. Each entry in those arrays MUST have an entry here. The
``string`` key for this object is field name itself.
May be an empty object if no fields are defined.
type: object type: object
properties: additionalProperties:
fieldname:
title: Field Type title: Field Type
description: Definition of valid values for a field. description: Definition of valid values for a field.
type: object type: object
properties: properties:
regexp: regexp:
description: A regular expression for validation of a field's value. description: |-
A regular expression for validation of a field's value. This may be relatively
coarse to verify the value as the application service providing this protocol
may apply additional validation or filtering.
type: string type: string
placeholder: placeholder:
description: An placeholder serving as a valid example of the field value. description: An placeholder serving as a valid example of the field value.
type: string type: string
required: ['regexp', 'placeholder']
required: ['fieldname']
example: { example: {
"network": { "network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+", "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
@ -63,17 +82,32 @@ properties:
instances: instances:
description: |- description: |-
A list of objects representing independent instances of configuration. A list of objects representing independent instances of configuration.
For instance multiple networks on IRC if multiple are bridged by the For example, multiple networks on IRC if multiple are provided by the
same bridge. same application service.
type: array type: array
items: items:
type: object type: object
title: Protocol Instance
properties:
desc:
type: string
description: A human-readable description for the protocol, such as the name.
example: "Freenode"
icon:
type: string
description: |-
An optional content URI representing the protocol. Overrides the one provided
at the higher level Protocol object.
example: "mxc://example.org/JkLmNoPq"
fields:
type: object
description: Preset values for ``fields`` the client may use to search by.
example: { example: {
"desc": "Freenode", "network": "freenode"
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
} }
} network_id:
title: Protocol type: string
type: object description: A unique identifier across all instances.
example: "freenode"
required: ['desc', 'fields', 'network_id']
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

@ -36,6 +36,7 @@ example: {
}, },
"instances": [ "instances": [
{ {
"network_id": "freenode",
"desc": "Freenode", "desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq", "icon": "mxc://example.org/JkLmNoPq",
"fields": { "fields": {
@ -59,6 +60,7 @@ example: {
}, },
"instances": [ "instances": [
{ {
"network_id": "gitter",
"desc": "Gitter", "desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt", "icon": "mxc://example.org/zXyWvUt",
"fields": {} "fields": {}

@ -21,11 +21,13 @@ properties:
protocol: protocol:
description: The protocol ID that the third party location is a part of. description: The protocol ID that the third party location is a part of.
type: string type: string
example: gitter example: "gitter"
fields: fields:
description: Information used to identify this third party location. description: Information used to identify this third party location.
type: object type: object
example: example: {
"user": "jim" "user": "jim"
}
required: ['userid', 'protocol', 'fields']
title: User title: User
type: object type: object

@ -1,4 +1,3 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd # Copyright 2018 New Vector Ltd
# #
# Licensed under the Apache License, Version 2.0 (the "License"); # Licensed under the Apache License, Version 2.0 (the "License");
@ -26,76 +25,6 @@ consumes:
produces: produces:
- application/json - application/json
paths: paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events.
schema:
type: object
example: {
"events": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
description: "Transaction informations"
properties:
events:
type: array
description: A list of events
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {
}
schema:
type: object
"/_matrix/app/unstable/thirdparty/protocol/{protocol}": "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
get: get:
summary: Retrieve metadata about a specific protocol that the application service supports. summary: Retrieve metadata about a specific protocol that the application service supports.
@ -198,7 +127,7 @@ paths:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}": "/_matrix/app/unstable/thirdparty/location/{protocol}":
get: get:
summary: Retreive Matrix-side portal rooms leading to a third party location. summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |- description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location. Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol operationId: queryLocationByProtocol
@ -251,7 +180,7 @@ paths:
get: get:
summary: Reverse-lookup third party locations given a Matrix room alias. summary: Reverse-lookup third party locations given a Matrix room alias.
description: |- description: |-
Retreive an array of third party network locations from a Matrix room Retrieve an array of third party network locations from a Matrix room
alias. alias.
operationId: queryLocationByAlias operationId: queryLocationByAlias
parameters: parameters:
@ -296,7 +225,7 @@ paths:
get: get:
summary: Reverse-lookup third party users given a Matrix User ID. summary: Reverse-lookup third party users given a Matrix User ID.
description: |- description: |-
Retreive an array of third party users from a Matrix User ID. Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID operationId: queryUserByID
parameters: parameters:
- in: query - in: query

@ -0,0 +1,74 @@
# Copyright 2016 OpenMarket Ltd
# 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: "/"
produces:
- application/json
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events.
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
]
}
description: Transaction information
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object

@ -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

@ -147,14 +147,22 @@ paths:
type: string type: string
description: The invitee's third party identifier. description: The invitee's third party identifier.
required: ["id_server", "medium", "address"] required: ["id_server", "medium", "address"]
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not
support the room version.
example: "1"
creation_content: creation_content:
title: CreationContent title: CreationContent
type: object type: object
description: |- description: |-
Extra keys, such as ``m.federate``, to be added to the content Extra keys, such as ``m.federate``, to be added to the content
of the `m.room.create`_ event. The server will clobber the following of the `m.room.create`_ event. The server will clobber the following
keys: ``creator``. Future versions of the specification may allow keys: ``creator``, ``room_version``. Future versions of the specification
the server to clobber other keys. may allow the server to clobber other keys.
initial_state: initial_state:
type: array type: array
description: |- description: |-

@ -41,7 +41,7 @@ paths:
required: true required: true
x-example: "#monkeys:matrix.org" x-example: "#monkeys:matrix.org"
- in: body - in: body
name: roomInfo name: body
description: Information about this room alias. description: Information about this room alias.
required: true required: true
schema: schema:
@ -50,6 +50,7 @@ paths:
room_id: room_id:
type: string type: string
description: The room ID to set. description: The room ID to set.
required: ['room_id']
example: { example: {
"room_id": "!abnjk1jdasj98:capuchins.com" "room_id": "!abnjk1jdasj98:capuchins.com"
} }
@ -57,8 +58,7 @@ paths:
200: 200:
description: The mapping was created. description: The mapping was created.
examples: examples:
application/json: { application/json: {}
}
schema: schema:
type: object type: object
409: 409:

@ -194,8 +194,26 @@ paths:
description: |- description: |-
A string to search for in the room metadata, e.g. name, A string to search for in the room metadata, e.g. name,
topic, canonical alias etc. (Optional). topic, canonical alias etc. (Optional).
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
homeserver. Can only be used if ``include_all_networks`` is false.
example: "irc"
example: { example: {
"limit": 10, "filter": {"generic_search_term": "foo"}} "limit": 10,
"filter": {
"generic_search_term": "foo"
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
responses: responses:
200: 200:
description: A list of the rooms on the server. description: A list of the rooms on the server.

@ -90,7 +90,7 @@ paths:
The homeserver domain the consumer should use when attempting to The homeserver domain the consumer should use when attempting to
verify the user's identity. verify the user's identity.
expires_in: expires_in:
type: int type: integer
description: |- description: |-
The number of seconds before this token expires and a new one must The number of seconds before this token expires and a new one must
be generated. be generated.

@ -343,6 +343,8 @@ paths:
This endpoint allows the creation, modification and deletion of pushers This endpoint allows the creation, modification and deletion of pushers
for this user ID. The behaviour of this endpoint varies depending on the for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body. values in the JSON body.
When creating push rules, they MUST be enabled by default.
operationId: setPushRule operationId: setPushRule
security: security:
- accessToken: [] - accessToken: []
@ -424,7 +426,7 @@ paths:
required: ["actions"] required: ["actions"]
responses: responses:
200: 200:
description: The pusher was set. description: The push rule was created/updated.
examples: examples:
application/json: { application/json: {
} }

@ -73,7 +73,7 @@ paths:
$ref: definitions/errors/error.yaml $ref: definitions/errors/error.yaml
"/thirdparty/location/{protocol}": "/thirdparty/location/{protocol}":
get: get:
summary: Retreive Matrix-side portals rooms leading to a third party location. summary: Retrieve Matrix-side portals rooms leading to a third party location.
description: |- description: |-
Requesting this endpoint with a valid protocol name results in a list Requesting this endpoint with a valid protocol name results in a list
of successful mapping results in a JSON array. Each result contains of successful mapping results in a JSON array. Each result contains
@ -151,7 +151,7 @@ paths:
get: get:
summary: Reverse-lookup third party locations given a Matrix room alias. summary: Reverse-lookup third party locations given a Matrix room alias.
description: |- description: |-
Retreive an array of third party network locations from a Matrix room Retrieve an array of third party network locations from a Matrix room
alias. alias.
operationId: queryLocationByAlias operationId: queryLocationByAlias
security: security:
@ -181,7 +181,7 @@ paths:
get: get:
summary: Reverse-lookup third party users given a Matrix User ID. summary: Reverse-lookup third party users given a Matrix User ID.
description: |- description: |-
Retreive an array of third party users from a Matrix User ID. Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID operationId: queryUserByID
security: security:
- accessToken: [] - accessToken: []

@ -49,6 +49,15 @@ paths:
description: The user ID the join event will be for. description: The user ID the join event will be for.
required: true required: true
x-example: "@someone:example.org" x-example: "@someone:example.org"
- in: query
type: array
items:
type: string
name: ver
description: |-
The room versions the sending server has support for. Defaults
to ``[1]``.
x-example: ["1", "2"]
responses: responses:
200: 200:
description: |- description: |-
@ -142,6 +151,30 @@ paths:
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}] ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
] ]
} }
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
parameters.
The error should be passed through to clients so that they
may give better feedback to users.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
"/send_join/{roomId}/{eventId}": "/send_join/{roomId}/{eventId}":
put: put:
summary: Submit a signed join event to a resident server summary: Submit a signed join event to a resident server

@ -49,6 +49,20 @@ paths:
A pagination token from a previous call to this endpoint to fetch more A pagination token from a previous call to this endpoint to fetch more
rooms. rooms.
x-example: "GetMoreRoomsTokenHere" x-example: "GetMoreRoomsTokenHere"
- in: query
name: include_all_networks
type: boolean
description: |-
Whether or not to include all networks/protocols defined by application
services on the homeserver. Defaults to false.
x-example: false
- in: query
name: third_party_instance_id
type: string
description: |-
The specific third party network/protocol to request from the homeserver.
Can only be used if ``include_all_networks`` is false.
x-example: "irc"
responses: responses:
200: 200:
description: The public room list for the homeserver. description: The public room list for the homeserver.

@ -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"
}

@ -11,6 +11,9 @@ properties:
m.federate: m.federate:
description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist. description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist.
type: boolean type: boolean
room_version:
description: The version of the room. Defaults to ``"1"`` if the key does not exist.
type: string
required: required:
- creator - creator
type: object type: object

@ -13,8 +13,8 @@ properties:
algorithm: algorithm:
type: string type: string
enum: enum:
- m.olm.curve25519-aes-sha256 - m.olm.v1.curve25519-aes-sha2
- m.megolm.v1.aes-sha - m.megolm.v1.aes-sha2
description: |- description: |-
The encryption algorithm used to encrypt this event. The The encryption algorithm used to encrypt this event. The
value of this field determines which other properties will be value of this field determines which other properties will be

@ -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

@ -41,6 +41,37 @@ Examples of valid server names are:
* ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port) * ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port)
Room Versions
~~~~~~~~~~~~~
Room versions are used to change properties of rooms that may not be compatible
with other servers. For example, changing the rules for event authorization would
cause older servers to potentially end up in a split-brain situation due to them
not understanding the new rules.
A room version is defined as a string of characters which MUST NOT exceed 32
codepoints in length. Room versions MUST NOT be empty and SHOULD contain only
the characters ``a-z``, ``0-9``, ``.``, and ``-``.
Room versions are not intended to be parsed and should be treated as opaque
identifiers. Room versions consisting only of the characters ``0-9`` and ``.``
are reserved for future versions of the Matrix protocol.
The complete grammar for a legal room version is::
room_version = 1*room_version_char
room_version_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "."
Examples of valid room versions are:
* ``1`` (would be reserved by the Matrix protocol)
* ``1.2`` (would be reserved by the Matrix protocol)
* ``1.2-beta``
* ``com.example.version``
Common Identifier Format Common Identifier Format
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~

@ -75,8 +75,7 @@ said to be interested in a given event if one of the application service's names
users is the target of the event, or is a joined member of the room where the event users is the target of the event, or is a joined member of the room where the event
occurred. occurred.
An application An application service can also state whether they should be the only ones who
service can also state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive" can manage a specified namespace. This is referred to as an "exclusive"
namespace. An exclusive namespace prevents humans and other application namespace. An exclusive namespace prevents humans and other application
services from creating/deleting entities in that namespace. Typically, services from creating/deleting entities in that namespace. Typically,
@ -90,33 +89,77 @@ regular expressions and look like:
users: users:
- exclusive: true - exclusive: true
regex: @_irc.freenode.net_.* regex: "@_irc.freenode.net_.*"
Application services may define the following namespaces (with none being explicitly required):
+------------------+-----------------------------------------------------------+
| Name | Description |
+==================+===========================================================+
| users | Events which are sent from certain users. |
+------------------+-----------------------------------------------------------+
| aliases | Events which are sent in rooms with certain room aliases. |
+------------------+-----------------------------------------------------------+
| rooms | Events which are sent in rooms with certain room IDs. |
+------------------+-----------------------------------------------------------+
Each individual namespace MUST declare the following fields:
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| Name | Description |
+==================+===================================================================================================================================+
| exclusive | **Required** A true or false value stating whether this application service has exclusive access to events within this namespace. |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| regex | **Required** A regular expression defining which values this namespace includes. |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
Exclusive user and alias namespaces should begin with an underscore after the
sigil to avoid collisions with other users on the homeserver. Application
services should additionally attempt to identify the service they represent
in the reserved namespace. For example, ``@_irc_.*`` would be a good namespace
to register for an application service which deals with IRC.
The registration is represented by a series of key-value pairs, which this The registration is represented by a series of key-value pairs, which this
specification will present as YAML. An example HS configuration required to pass specification will present as YAML. See below for the possible options along
traffic to the AS is: with their explanation:
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Description |
+==================+====================================================================================================================================================+
| id | **Required.** A unique, user-defined ID of the application service which will never change. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| url | **Required.** The URL for the application service. May include a path after the domain name. Optionally set to ``null`` if no traffic is required. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| as_token | **Required.** A unique token for application services to use to authenticate requests to Homeservers. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| hs_token | **Required.** A unique token for Homeservers to use to authenticate requests to application services. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| sender_localpart | **Required.** The localpart of the user associated with the application service. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| namespaces | **Required.** A list of ``users``, ``aliases`` and ``rooms`` namespaces that the application service controls. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| rate_limited | Whether requests from masqueraded users are rate-limited. The sender is excluded. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| protocols | The external protocols which the application service provides (e.g. IRC). |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
An example registration file for an IRC-bridging application service is below:
.. code-block:: yaml .. code-block:: yaml
id: <user-defined unique ID of AS which will never change> id: "IRC Bridge"
url: <base url of AS> url: "http://127.0.0.1:1234"
as_token: <token AS will add to requests to HS> as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
hs_token: <token HS will add to requests to AS> hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
sender_localpart: <localpart of AS user> sender_localpart: "_irc_bot" # Will result in @_irc_bot:domain.com
namespaces: namespaces:
users: # Namespaces of users which should be delegated to the AS users:
- exclusive: <bool> - exclusive: true
regex: <regex> regex: "@_irc_bridge_.*"
- ... aliases:
aliases: [] # Namespaces of room aliases which should be delegated to the AS - exclusive: false
rooms: [] # Namespaces of room ids which should be delegated to the AS regex: "#_irc_bridge_.*"
rooms: []
Exclusive user and alias namespaces should begin with an underscore after the
sigil to avoid collisions with other users on the homeserver. Application
services should additionally attempt to identify the service they represent
in the reserved namespace. For example, ``@_irc_.*`` would be a good namespace
to register for an application service which deals with IRC.
.. WARNING:: .. WARNING::
If the homeserver in question has multiple application services, each If the homeserver in question has multiple application services, each
@ -155,6 +198,8 @@ be made without blocking other aspects of the homeserver. Homeservers MUST NOT
alter (e.g. add more) events they were going to send within that transaction ID alter (e.g. add more) events they were going to send within that transaction ID
on retries, as the AS may have already processed the events. on retries, as the AS may have already processed the events.
{{transactions_as_http_api}}
Querying Querying
++++++++ ++++++++
@ -180,13 +225,25 @@ this request (e.g. to join a room alias).
{{query_room_as_http_api}} {{query_room_as_http_api}}
HTTP APIs Third party networks
+++++++++ ++++++++++++++++++++
Application services may declare which protocols they support via their registration
configuration for the homeserver. These networks are generally for third party services
such as IRC that the application service is managing. Application services may populate
a Matrix room directory for their registered protocols, as defined in the Client-Server
API Extensions.
This contains application service APIs which are used by the homeserver. All Each protocol may have several "locations" (also known as "third party locations" or "3PLs").
application services MUST implement these APIs. These APIs are defined below. A location within a protocol is a place in the third party network, such as an IRC channel.
Users of the third party network may also be represented by the application service.
{{application_service_as_http_api}} Locations and users can be searched by fields defined by the application service, such
as by display name or other attribute. When clients request the homeserver to search
in a particular "network" (protocol), the search fields will be passed along to the
application service for filtering.
{{protocols_as_http_api}}
.. _create the user: `sect:asapi-permissions`_ .. _create the user: `sect:asapi-permissions`_
@ -198,6 +255,9 @@ Application services can use a more powerful version of the
client-server API by identifying itself as an application service to the client-server API by identifying itself as an application service to the
homeserver. homeserver.
Endpoints defined in this section MUST be supported by homeservers in the
client-server API as accessible only by application services.
Identity assertion Identity assertion
++++++++++++++++++ ++++++++++++++++++
The client-server API infers the user ID from the ``access_token`` provided in The client-server API infers the user ID from the ``access_token`` provided in
@ -294,6 +354,15 @@ API MUST do so with a virtual user (provide a ``user_id`` via the query string).
is expected that the application service use the transactions pushed to it to is expected that the application service use the transactions pushed to it to
handle events rather than syncing with the user implied by ``sender_localpart``. handle events rather than syncing with the user implied by ``sender_localpart``.
Application service room directories
++++++++++++++++++++++++++++++++++++
Application services can maintain their own room directories for their defined
third party protocols. These room directories may be accessed by clients through
additional parameters on the ``/publicRooms`` client-server endpoint.
{{appservice_room_directory_cs_http_api}}
Event fields Event fields
~~~~~~~~~~~~ ~~~~~~~~~~~~

@ -148,6 +148,13 @@ Some requests have unique error codes:
:``M_SERVER_NOT_TRUSTED``: :``M_SERVER_NOT_TRUSTED``:
The client's request used a third party server, eg. ID server, that this server does not trust. The client's request used a third party server, eg. ID server, that this server does not trust.
:``M_UNSUPPORTED_ROOM_VERSION``:
The client's request to create a room used a room version that the server does not support.
:``M_INCOMPATIBLE_ROOM_VERSION``:
The client attempted to join a room that has a version the server does not support. Inspect the
``room_version`` property of the error response for the room's version.
.. _sect:txn_ids: .. _sect:txn_ids:
The client-server API typically uses ``HTTP PUT`` to submit requests with a The client-server API typically uses ``HTTP PUT`` to submit requests with a

@ -369,6 +369,41 @@ Definition:
} }
``.m.rule.roomnotif``
`````````````````````
Matches any message whose content is unencrypted and contains the
text ``@room``, signifying the whole room should be notified of
the event.
Definition:
.. code:: json
{
"rule_id": ".m.rule.roomnotif",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "content.body",
"pattern": "@room"
},
{
"kind": "sender_notification_permission",
"key": "room"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": true
}
]
}
Default Content Rules Default Content Rules
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
@ -428,7 +463,47 @@ Definition:
"value": false "value": false
} }
] ]
}
``.m.rule.encrypted_room_one_to_one``
`````````````````````````````````````
Matches any encrypted event sent in a room with exactly two members.
Unlike other push rules, this rule cannot be matched against the content
of the event by nature of it being encrypted. This causes the rule to
be an "all or nothing" match where it either matches *all* events that
are encrypted (in 1:1 rooms) or none.
Definition:
.. code:: json
{
"rule_id": ".m.rule.encrypted_room_one_to_one",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "room_member_count",
"is": "2"
}
],
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
}, },
{
"set_tweak": "highlight",
"value": false
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.encrypted"
}
]
}
``.m.rule.room_one_to_one`` ``.m.rule.room_one_to_one``
``````````````````````````` ```````````````````````````
@ -489,6 +564,37 @@ Definition:
] ]
} }
``.m.rule.encrypted``
`````````````````````
Matches all encrypted events. Unlike other push rules, this rule cannot
be matched against the content of the event by nature of it being encrypted.
This causes the rule to be an "all or nothing" match where it either
matches *all* events that are encrypted (in 1:1 rooms) or none.
Definition:
.. code:: json
{
"rule_id": ".m.rule.encrypted",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.encrypted"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
]
}
Conditions Conditions
++++++++++ ++++++++++
@ -523,6 +629,21 @@ rule determines its behaviour. The following conditions are defined:
count is strictly less than the given number and so forth. If no prefix is count is strictly less than the given number and so forth. If no prefix is
present, this parameter defaults to ``==``. present, this parameter defaults to ``==``.
``sender_notification_permission``
This takes into account the current power levels in the room, ensuring the
sender of the event has high enough power to trigger the notification.
Parameters:
* ``key``: A string that determines the power level the sender must have to trigger
notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_
event schema for information about what the defaults are and how to interpret the event.
The ``key`` is used to look up the power level required to send a notification type
from the ``notifications`` object in the power level event content.
Unrecognised conditions MUST NOT match any events, effectively making the push
rule disabled.
Push Rules: API Push Rules: API
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~

@ -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.

@ -929,6 +929,32 @@ described in the `Client-Server API`_, being sure to use the ``allow_remote``
parameter (set to ``false``). parameter (set to ``false``).
Server Access Control Lists (ACLs)
----------------------------------
Server ACLs and their purpose are described in the `Server ACLs`_ section of the
Client-Server API.
When a remote server makes a request, it MUST be verified to be allowed by the
server ACLs. If the server is denied access to a room, the receiving server
MUST reply with a 403 HTTP status code and an ``errcode`` of ``M_FORBIDDEN``.
The following endpoint prefixes MUST be protected:
* ``/_matrix/federation/v1/send`` (on a per-PDU basis)
* ``/_matrix/federation/v1/make_join``
* ``/_matrix/federation/v1/make_leave``
* ``/_matrix/federation/v1/send_join``
* ``/_matrix/federation/v1/send_leave``
* ``/_matrix/federation/v1/invite``
* ``/_matrix/federation/v1/state``
* ``/_matrix/federation/v1/state_ids``
* ``/_matrix/federation/v1/backfill``
* ``/_matrix/federation/v1/event_auth``
* ``/_matrix/federation/v1/query_auth``
* ``/_matrix/federation/v1/get_missing_events``
Signing Events Signing Events
-------------- --------------

@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/report_content.rst - modules/report_content.rst
- modules/third_party_networks.rst - modules/third_party_networks.rst
- modules/openid.rst - modules/openid.rst
- modules/server_acls.rst
- modules/mentions.rst - modules/mentions.rst

Loading…
Cancel
Save