From 09a768763d89365308152168095be862b246efcc Mon Sep 17 00:00:00 2001 From: Konstantinos Sideris Date: Sat, 14 Jan 2017 19:09:23 +0200 Subject: [PATCH 001/240] Add missing enum fields for the set_presence parameter Signed-off-by: Konstantinos Sideris --- api/client-server/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 66f7d935..b7965da9 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -76,7 +76,7 @@ paths: - in: query name: set_presence type: string - enum: ["offline"] + enum: ["offline", "online", "unavailable"] description: |- Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is From 1e656d836ead371bb395a768e35173a6cf41f5ea Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Sun, 15 Apr 2018 22:35:44 +0100 Subject: [PATCH 002/240] spec notifications key on power level event and provide @room in example --- event-schemas/examples/m.room.power_levels | 5 ++++- event-schemas/schema/m.room.power_levels | 8 ++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.power_levels b/event-schemas/examples/m.room.power_levels index 0c8f8bc5..2b0aaca5 100644 --- a/event-schemas/examples/m.room.power_levels +++ b/event-schemas/examples/m.room.power_levels @@ -14,7 +14,10 @@ "users": { "@example:localhost": 100 }, - "users_default": 0 + "users_default": 0, + "notifications": { + "room": 20 + } }, "state_key": "", "origin_server_ts": 1431961217939, diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index 13a44c70..f348b52d 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -85,6 +85,14 @@ properties: ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if unspecified. type: number + notifications: + additionalProperties: + type: number + description: |- + The power level requirements for specific notification types. + This is a mapping from ``key`` to power level for that notifications key. + title: Notification power level requirements + type: object type: object state_key: description: A zero-length string. From 60ae73b179c53213ce952251c7e9f4d14c323fef Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Sun, 15 Apr 2018 22:37:23 +0100 Subject: [PATCH 003/240] specify default --- event-schemas/schema/m.room.power_levels | 1 + 1 file changed, 1 insertion(+) diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index f348b52d..a00746f0 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -91,6 +91,7 @@ properties: description: |- The power level requirements for specific notification types. This is a mapping from ``key`` to power level for that notifications key. + Defaults to 50 for unspecified keys. title: Notification power level requirements type: object type: object From c305317fa57b918d68731f69a0ab21367debde0b Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Sun, 15 Apr 2018 22:41:24 +0100 Subject: [PATCH 004/240] explicitly specify @room --- event-schemas/schema/m.room.power_levels | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index a00746f0..25d33f08 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -86,13 +86,16 @@ properties: unspecified. type: number notifications: + properties: + room: + type: number + description: The level required to trigger an ``@room`` notification. Defaults to 50 if unspecified. additionalProperties: type: number description: |- The power level requirements for specific notification types. This is a mapping from ``key`` to power level for that notifications key. - Defaults to 50 for unspecified keys. - title: Notification power level requirements + title: Notifications type: object type: object state_key: From 9ca62edda0a664f65ac7ff31b659a77efce7edb1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 25 May 2018 19:39:54 +0100 Subject: [PATCH 005/240] Document new application service registration file options. --- .../application_service.yaml | 2 +- specification/application_service_api.rst | 89 +++++++++++++++---- 2 files changed, 75 insertions(+), 16 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index c39ce198..a63774a2 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -43,7 +43,7 @@ paths: x-example: "35" - in: body name: body - description: A list of events + description: A list of events. schema: type: object example: { diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..6eb8e87e 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -83,34 +83,93 @@ regular expressions and look like: users: - exclusive: true - regex: @irc.freenode.net_.* + regex: "@irc.freenode.net_.*" + group_id: "+irc:matrix.org" + +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. | ++------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + +An optional ``group_id`` field may be added to the users namespace: + ++------------------+-----------------------------------------------------------+ +| Name | Description | ++==================+===========================================================+ +| group_id | All matching users will be considered part of this group. | ++------------------+-----------------------------------------------------------+ + +.. WARNING:: + + Users that are matched by ``group_id`` should not be publically listed by + Homeservers. The intention is to differentiate users, perhaps with a flair, + rather than having a list of people to spam. 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 -traffic to the AS is: +specification will present as YAML. See below for the possible options along +with their explanation: + ++------------------+----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++==================+==========================================================================================================+ +| id | **Required.** A unique, user-defined ID of the Application Service which will never change. | ++------------------+----------------------------------------------------------------------------------------------------------+ +| url | **Required.** The base URL for the Application Service. | ++------------------+----------------------------------------------------------------------------------------------------------+ +| 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 - id: - url: - as_token: - hs_token: - sender_localpart: + id: "IRC Bridge" + url: "http://127.0.0.1:1234" + as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46" + hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e" + sender_localpart: "_irc_bot" # Will result in @_irc_bot:domain.com namespaces: - users: # Namespaces of users which should be delegated to the AS - - exclusive: - regex: - - ... - aliases: [] # Namespaces of room aliases which should be delegated to the AS - rooms: [] # Namespaces of room ids which should be delegated to the AS + users: + - exclusive: true + regex: "@irc_bridge_.*" + aliases: + - exclusive: false + regex: "#irc_bridge_.*" + rooms: [] .. WARNING:: If the homeserver in question has multiple application services, each ``as_token`` and ``id`` MUST be unique per application service as these are used to identify the application service. The homeserver MUST enforce this. - Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From d6fb5afd16ad1682d90c9dd3bd505e9baf60e513 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 28 May 2018 23:30:40 +0100 Subject: [PATCH 006/240] Clarified group_id group visibility, url possibilities, regex starters Changed Application Service capatalization to be consistent with the rest of the document. --- specification/application_service_api.rst | 68 ++++++++++++----------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 6eb8e87e..31983a0c 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -83,10 +83,10 @@ regular expressions and look like: users: - exclusive: true - regex: "@irc.freenode.net_.*" + regex: "@_irc.freenode.net_.*" group_id: "+irc:matrix.org" -Application Services may define the following namespaces (with none being explicitly required): +Application services may define the following namespaces (with none being explicitly required): +------------------+-----------------------------------------------------------+ | Name | Description | @@ -103,22 +103,24 @@ 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. | +| 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. | +------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -An optional ``group_id`` field may be added to the users namespace: +An application service's users and regex field MUST begin with an underscore (``_``), in +order to provide a visually clear distinction between AS users and regular +users. An optional ``group_id`` field may be added to the ``users`` namespace: -+------------------+-----------------------------------------------------------+ -| Name | Description | -+==================+===========================================================+ -| group_id | All matching users will be considered part of this group. | -+------------------+-----------------------------------------------------------+ ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Description | ++==================+============================================================================================================================================================================================================================================================================+ +| group_id | An existing group that all matching user IDs will be considered a part of. Users who are joined to this group through an application service are not to be listed when querying for the group's members, however the group should be listed when querying a user's groups. | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. WARNING:: - Users that are matched by ``group_id`` should not be publically listed by + Users that are matched by ``group_id`` should not be publicly listed by Homeservers. The intention is to differentiate users, perhaps with a flair, rather than having a list of people to spam. @@ -127,27 +129,27 @@ The registration is represented by a series of key-value pairs, which this specification will present as YAML. See below for the possible options along with their explanation: -+------------------+----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+==================+==========================================================================================================+ -| id | **Required.** A unique, user-defined ID of the Application Service which will never change. | -+------------------+----------------------------------------------------------------------------------------------------------+ -| url | **Required.** The base URL for the Application Service. | -+------------------+----------------------------------------------------------------------------------------------------------+ -| 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: ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 @@ -159,10 +161,10 @@ An example registration file for an IRC-bridging Application Service is below: namespaces: users: - exclusive: true - regex: "@irc_bridge_.*" + regex: "@_irc_bridge_.*" aliases: - exclusive: false - regex: "#irc_bridge_.*" + regex: "#_irc_bridge_.*" rooms: [] .. WARNING:: From 0dd330962d7bf54e65737d5ca0e5f9a074c237e3 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 3 Jul 2018 14:14:26 -0400 Subject: [PATCH 007/240] initial draft of .well-known discovery --- .../definitions/wellknown/homeserver.yaml | 23 ++++++ .../definitions/wellknown/homeserver.yaml~ | 23 ++++++ .../wellknown/identity_server.yaml | 23 ++++++ api/client-server/wellknown.yaml | 63 ++++++++++++++++ specification/client_server_api.rst | 72 +++++++++++++++++++ 5 files changed, 204 insertions(+) create mode 100644 api/client-server/definitions/wellknown/homeserver.yaml create mode 100644 api/client-server/definitions/wellknown/homeserver.yaml~ create mode 100644 api/client-server/definitions/wellknown/identity_server.yaml create mode 100644 api/client-server/wellknown.yaml diff --git a/api/client-server/definitions/wellknown/homeserver.yaml b/api/client-server/definitions/wellknown/homeserver.yaml new file mode 100644 index 00000000..7efba816 --- /dev/null +++ b/api/client-server/definitions/wellknown/homeserver.yaml @@ -0,0 +1,23 @@ +# 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. +title: Homeserver Information +description: |- + Used by clients to discover homeserver information. +type: object +properties: + base_url: + type: string + description: The base URL for the homeserver for client-server connections. +required: + - base_url diff --git a/api/client-server/definitions/wellknown/homeserver.yaml~ b/api/client-server/definitions/wellknown/homeserver.yaml~ new file mode 100644 index 00000000..e42dfbf3 --- /dev/null +++ b/api/client-server/definitions/wellknown/homeserver.yaml~ @@ -0,0 +1,23 @@ +# 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. +title: Authentication Data +description: |- + Used by clients to submit authentication information to the interactive-authentication API +type: object +properties: + base_url: + type: string + description: The base URL for the homeserver for client-server connections. +required: + - base_url diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml new file mode 100644 index 00000000..eb0e0baf --- /dev/null +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -0,0 +1,23 @@ +# 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. +title: Identity Server Information +description: |- + Used by clients to discover identity server information. +type: object +properties: + base_url: + type: string + description: The base URL for the identity server for client-server connections. +required: + - base_url diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml new file mode 100644 index 00000000..44d9ef73 --- /dev/null +++ b/api/client-server/wellknown.yaml @@ -0,0 +1,63 @@ +# 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 server discovery API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /.well-known +produces: + - application/json +paths: + "/matrix/client": + get: + summary: Gets Matrix server discovery information about the domain. + description: |- + Gets discovery information about the domain. The file may include + additional keys, which SHOULD follow the Java package naming convention, + e.g. ``com.example.myapp.property``. This ensures property names are + suitably namespaced for each application and reduces the risk of + clashes. + + **FIXME:** do we need to add a note that this endpoint is not + necessarily handled by the homeserver, but by another webserver? Or + does the context make this clear enough? + operationId: getWellknown + responses: + 200: + description: Server discovery information + examples: + application/json: { + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "m.identity_server": { + "base_url": "https://identity.example.com" + } + } + schema: + type: object + properties: + m.homeserver: + description: Information about the homeserver to connect to. + "$ref": "definitions/wellknown/homeserver.yaml" + m.identity_server: + description: Information about the identity server to connect to. + "$ref": "definitions/wellknown/identity_server.yaml" + 404: + description: No server discovery information available + tags: + - Server administration diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index dec3a4f4..e0befddf 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -164,6 +164,78 @@ recommended. {{versions_cs_http_api}} +Server Discovery +~~~~~~~~~~~~~~~~ + +In order to allow users to connect to a Matrix server without needing to +explicitly specify the homeserver's URL or other parameters, clients may use an +auto-discovery mechanism to determine the server's URL based on a user's +Matrix ID. Auto-discovery should only be done at login time, with the +discovered values retained for the duration of the user's session. + +In this section, the following terms are used with specific meanings: + +``PROMPT`` + Retrieve the specific piece of information from the user in a way which + fits within the existing client UX, if the client is inclined to do so. + Failure can take place instead if no good UX is possible at this point. + +``IGNORE`` + Stop the current auto-discovery mechanism. If no more auto-discovery + mechanisms are available, then the client may use other methods of + determining the required parameters, such as prompting the user, or using + default values. + +``FAIL_PROMPT`` + Inform the user that auto-discovery failed due to invalid/empty data and + ``PROMPT`` for the parameter. + +``FAIL_ERROR`` + Inform the user that auto-discovery did not return any usable URLs. Do not + continue further with the current login process. At this point, valid data + was obtained, but no homeserver is available to serve the client. No further + guess should be attempted and the user should make a conscientious decision + what to do next. + +Well-known URI +++++++++++++++ + +The ``.well-known`` method uses a JSON file at a predetermined location to +specify parameter values. The flow for this method is as follows: + +1. Extract the server name from the user's Matrix ID by splitting the Matrix ID + at the first colon. +2. Extract the DNS name from the server name. +3. Make a GET request to ``https://dns_name/.well-known/matrix/client``. + + a. If the returned status code is 404, then ``IGNORE``. + b. If the returned status code is not 200, or the response body is empty, + then ``FAIL_PROMPT``. + c. Parse the response body as a JSON object + + i. If the content cannot be parsed, then ``FAIL_PROMPT``. + + d. Extract the ``base_url`` value from the ``m.homeserver`` property. This + value is to be used as the base URL of the homeserver. + + i. If this value is not provided, then ``FAIL_PROMPT``. + + e. Validate the homeserver base URL: + + i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. + ii. Clients should validate that the URL points to a valid homeserver + before accepting it. Currently, the suggested way of validating is + to connect to the ``/_matrix/client/versions`` endpoint, and to parse + and validate the data. If any step in the validation fails, then + ``FAIL_ERROR``. + + f. If the ``m.identity_server`` property is present, extract the + ``base_url`` value for use as the base URL of the identity server. This + value can be validated as in the step above, but using + ``/_matrix/identity/api/v1``. + +{{wellknown_cs_http_api}} + Client Authentication --------------------- From 5bc29eb11c5c07c47e6fb4afe0c7c1caba12cbf2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 4 Jul 2018 17:01:35 -0400 Subject: [PATCH 008/240] remove accidentally-committed backup file --- .../definitions/wellknown/homeserver.yaml~ | 23 ------------------- 1 file changed, 23 deletions(-) delete mode 100644 api/client-server/definitions/wellknown/homeserver.yaml~ diff --git a/api/client-server/definitions/wellknown/homeserver.yaml~ b/api/client-server/definitions/wellknown/homeserver.yaml~ deleted file mode 100644 index e42dfbf3..00000000 --- a/api/client-server/definitions/wellknown/homeserver.yaml~ +++ /dev/null @@ -1,23 +0,0 @@ -# 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. -title: Authentication Data -description: |- - Used by clients to submit authentication information to the interactive-authentication API -type: object -properties: - base_url: - type: string - description: The base URL for the homeserver for client-server connections. -required: - - base_url From ce1e2c0904a793b25527e88e060e0d0f6809cc1f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 4 Jul 2018 17:58:37 -0400 Subject: [PATCH 009/240] incorporate feedback from reviewers --- api/client-server/wellknown.yaml | 13 +++++++----- changelogs/client_server.rst | 4 ++++ specification/client_server_api.rst | 31 ++++++++++++++++------------- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index 44d9ef73..8d19f38a 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -27,14 +27,13 @@ paths: summary: Gets Matrix server discovery information about the domain. description: |- Gets discovery information about the domain. The file may include - additional keys, which SHOULD follow the Java package naming convention, + additional keys, which MUST follow the Java package naming convention, e.g. ``com.example.myapp.property``. This ensures property names are suitably namespaced for each application and reduces the risk of clashes. - **FIXME:** do we need to add a note that this endpoint is not - necessarily handled by the homeserver, but by another webserver? Or - does the context make this clear enough? + Note that this endpoint is not necessarily handled by the homeserver, + but by another webserver, to be used for discovering the homeserver URL. operationId: getWellknown responses: 200: @@ -55,8 +54,12 @@ paths: description: Information about the homeserver to connect to. "$ref": "definitions/wellknown/homeserver.yaml" m.identity_server: - description: Information about the identity server to connect to. + description: Optional. Information about the identity server to connect to. "$ref": "definitions/wellknown/identity_server.yaml" + additionalProperties: + description: Application-dependent keys using Java package naming convention. + required: + - m.homeserver 404: description: No server discovery information available tags: diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..c6eb740a 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -16,6 +16,10 @@ Unreleased changes - Add sticker message event definition. (`#1158 `_). + - Server discovery: + - Add ``.well-known`` discovery method + (`#1359 `_). + - Spec clarifications: - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e0befddf..fbeb87cb 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -168,17 +168,17 @@ Server Discovery ~~~~~~~~~~~~~~~~ In order to allow users to connect to a Matrix server without needing to -explicitly specify the homeserver's URL or other parameters, clients may use an -auto-discovery mechanism to determine the server's URL based on a user's -Matrix ID. Auto-discovery should only be done at login time, with the -discovered values retained for the duration of the user's session. +explicitly specify the homeserver's URL or other parameters, clients SHOULD use +an auto-discovery mechanism to determine the server's URL based on a user's +Matrix ID. Auto-discovery should only be done at login time. In this section, the following terms are used with specific meanings: ``PROMPT`` Retrieve the specific piece of information from the user in a way which - fits within the existing client UX, if the client is inclined to do so. - Failure can take place instead if no good UX is possible at this point. + fits within the existing client user experience, if the client is inclined to + do so. Failure can take place instead if no good user experience for this is + possible at this point. ``IGNORE`` Stop the current auto-discovery mechanism. If no more auto-discovery @@ -223,16 +223,19 @@ specify parameter values. The flow for this method is as follows: e. Validate the homeserver base URL: i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. - ii. Clients should validate that the URL points to a valid homeserver - before accepting it. Currently, the suggested way of validating is - to connect to the ``/_matrix/client/versions`` endpoint, and to parse - and validate the data. If any step in the validation fails, then - ``FAIL_ERROR``. + ii. Clients SHOULD validate that the URL points to a valid homeserver + before accepting it by connecting to the ``/_matrix/client/versions`` + endpoint, and parsing and validating the data. If any step in the + validation fails, then ``FAIL_ERROR``. Validation is done as a simple + check against configuration errors, before sending sensitive + information such as a user's password to the server. f. If the ``m.identity_server`` property is present, extract the - ``base_url`` value for use as the base URL of the identity server. This - value can be validated as in the step above, but using - ``/_matrix/identity/api/v1``. + ``base_url`` value for use as the base URL of the identity server. + Validation for this URL is done as in the step above, but using + ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the + ``m.identity_server`` property is present, but does not have a + ``base_url`` value, then ``FAIL_ERROR``. {{wellknown_cs_http_api}} From 8ffac01efec2295e584e22bdb72753ef59d34fbd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Aug 2018 20:57:00 -0600 Subject: [PATCH 010/240] Document OpenID in the client-server API Part of https://github.com/matrix-org/matrix-doc/issues/857 Reference: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/rest/client/v2_alpha/openid.py#L31-L58 --- api/client-server/openid.yaml | 103 +++++++++++++++++++++++++++++++ specification/modules/openid.rst | 24 +++++++ specification/targets.yaml | 1 + 3 files changed, 128 insertions(+) create mode 100644 api/client-server/openid.yaml create mode 100644 specification/modules/openid.rst diff --git a/api/client-server/openid.yaml b/api/client-server/openid.yaml new file mode 100644 index 00000000..4b89232e --- /dev/null +++ b/api/client-server/openid.yaml @@ -0,0 +1,103 @@ +# 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 OpenID API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/{userId}/openid/request_token": + post: + summary: Get an OpenID token object to verify the requester's identity. + description: |- + Gets an OpenID token object that the requester may supply to another + service to verify their identity in Matrix. The generated token is only + valid for exchanging for user information from the federation API for + OpenID. + + The access token generated is only valid for the OpenID API. It cannot + be used to request another OpenID access token or call ``/sync``, for + example. + operationId: requestOpenIdToken + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: |- + The user to request and OpenID token for. Should be the user who + is authenticated for the request. + required: true + x-example: "@alice:example.com" + - in: body + name: body + description: An empty object. Reserved for future expansion. + required: true + schema: + type: object + example: {} + responses: + 200: + description: |- + OpenID token information. This response is nearly compatible with the + response documented in the `OpenID 1.0 Specification `_ + with the only difference being the lack of an ``id_token``. Instead, + the Matrix homeserver's name is provided. + examples: + application/json: { + "access_token": "SomeT0kenHere", + "token_type": "Bearer", + "matrix_server_name": "example.com", + "expires_in": 3600, + } + schema: + type: object + properties: + access_token: + type: string + description: |- + An access token the consumer may use to verify the identity of + the person who generated the token. This is given to the federation + API ``GET /openid/userinfo``. + token_type: + type: string + description: The string ``Bearer``. + matrix_server_name: + type: string + description: |- + The homeserver domain the consumer should use when attempting to + verify the user's identity. + expires_in: + type: int + description: |- + The number of seconds before this token expires and a new one must + be generated. + required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in'] + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - OpenID diff --git a/specification/modules/openid.rst b/specification/modules/openid.rst new file mode 100644 index 00000000..63406719 --- /dev/null +++ b/specification/modules/openid.rst @@ -0,0 +1,24 @@ +.. 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. + +OpenID +====== + +.. _module:openid: + +This module allows users to verify their identity with a third party service. The +third party service does need to be matrix-aware in that it will need to know to +resolve matrix homeservers to exchange the user's token for identity information. + +{{openid_cs_http_api}} diff --git a/specification/targets.yaml b/specification/targets.yaml index 53957e0a..5480bbc5 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -66,6 +66,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/stickers.rst - modules/report_content.rst - modules/third_party_networks.rst + - modules/openid.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] From dcae88c29011e8e1a4349137b42a6b63181b5385 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Aug 2018 22:13:21 -0600 Subject: [PATCH 011/240] Document OpenID in the server-server API Part of https://github.com/matrix-org/matrix-doc/issues/857 Reference: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/federation/transport/server.py#L543-L557 --- api/server-server/openid.yaml | 63 +++++++++++++++++++++++++++++ specification/server_server_api.rst | 12 ++++++ 2 files changed, 75 insertions(+) create mode 100644 api/server-server/openid.yaml diff --git a/api/server-server/openid.yaml b/api/server-server/openid.yaml new file mode 100644 index 00000000..0eac48c8 --- /dev/null +++ b/api/server-server/openid.yaml @@ -0,0 +1,63 @@ +# Copyright 2017 Kamax.io +# 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 OpenID API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/openid/userinfo": + get: + summary: Exchange an OpenID token for user information + description: |- + Exchanges an OpenID access token for information about the user + who generated the token. Currently this only exposes the Matrix + User ID of the owner. + operationId: exchangeOpenIdToken + parameters: + - in: path + name: access_token + type: string + description: |- + The OpenID access token to get information about the owner for. + required: true + x-example: SomeT0kenHere + responses: + 200: + description: |- + Information about the user who generated the OpenID access token. + schema: + type: object + properties: + sub: + type: string + description: The Matrix User ID who generated the token. + example: "@alice:example.com" + required: ['sub'] + 401: + description: The token was not recognized or has expired. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Access token unknown or expired" + } diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 84a76639..e6fc8936 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -995,6 +995,18 @@ that can be made. {{query_ss_http_api}} +OpenID +------ + +Third party services can exchange an access token previously generated by the +`Client-Server API` for information about a user. This can help verify that a +user is who they say they are without granting full access to the user's account. + +Access tokens generated by the OpenID API are only good for the OpenID API and +nothing else. + +{{openid_ss_http_api}} + Send-to-device messaging ------------------------ From 05a2427c7304292e48d9501574b7bdf006ce3153 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 19:51:05 -0600 Subject: [PATCH 012/240] Document how presence EDUs work between servers It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it. --- .../event-schemas/m.presence.accept.yaml | 45 +++++++++ .../event-schemas/m.presence.deny.yaml | 54 +++++++++++ .../event-schemas/m.presence.invite.yaml | 44 +++++++++ .../definitions/event-schemas/m.presence.yaml | 97 +++++++++++++++++++ scripts/templating/matrix_templates/units.py | 1 + specification/server_server_api.rst | 67 ++++--------- 6 files changed, 258 insertions(+), 50 deletions(-) create mode 100644 api/server-server/definitions/event-schemas/m.presence.accept.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.deny.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.invite.yaml create mode 100644 api/server-server/definitions/event-schemas/m.presence.yaml diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence.accept.yaml new file mode 100644 index 00000000..3b80ac44 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.accept.yaml @@ -0,0 +1,45 @@ +# 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. + +type: object +title: Presence Invite Accept EDU +description: |- + An EDU representing approval for the observing user to subscribe to the + presence of the the observed user. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.presence_accept`` + example: "m.presence_accept" + content: + type: object + description: The invite information. + title: Invite Information + properties: + observed_user: + type: string + description: |- + The user ID that has approved the ``observer_user`` to + subscribe to their presence. + example: "@alice:elsewhere.com" + observer_user: + type: string + description: |- + The user ID that requested to subscribe to the presence of + the ``observed_user``. + example: "@john:matrix.org" + required: ['observer_user', 'observed_user'] diff --git a/api/server-server/definitions/event-schemas/m.presence.deny.yaml b/api/server-server/definitions/event-schemas/m.presence.deny.yaml new file mode 100644 index 00000000..1383866c --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.deny.yaml @@ -0,0 +1,54 @@ +# 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. + +type: object +title: Presence Invite Deny EDU +description: |- + An EDU representing a declination or revocation for the observing user + to subscribe to the presence of the observed user. +example: { + "origin": "domain.com", + "destination": "elsewhere.org", + "edu_type": "m.presence_deny", + "content": { + "observed_user": "@alice:elsewhere.org", + "observer_user": "@john:domain.com" + } +} +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.presence_deny`` + example: "m.presence_deny" + content: + type: object + description: The invite information. + title: Invite Information + properties: + observed_user: + type: string + description: |- + The user ID that has declined or revoked the ``observer_user`` from + subscribing to their presence. + example: "@alice:elsewhere.com" + observer_user: + type: string + description: |- + The user ID that requested to subscribe to the presence of + the ``observed_user``. + example: "@john:matrix.org" + required: ['observer_user', 'observed_user'] diff --git a/api/server-server/definitions/event-schemas/m.presence.invite.yaml b/api/server-server/definitions/event-schemas/m.presence.invite.yaml new file mode 100644 index 00000000..eeb00ae3 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.invite.yaml @@ -0,0 +1,44 @@ +# 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. + +type: object +title: Presence Invite EDU +description: |- + An EDU representing a request to subscribe to a user's presence. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.presence_invite`` + example: "m.presence_invite" + content: + type: object + description: The invite information. + title: Invite Information + properties: + observed_user: + type: string + description: |- + The user ID the ``observer_user`` would like to subscribe + to the presence of. + example: "@alice:elsewhere.com" + observer_user: + type: string + description: |- + The user ID that is wishing to subscribe to the presence of + the ``observed_user``. + example: "@john:matrix.org" + required: ['observer_user', 'observed_user'] diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml new file mode 100644 index 00000000..bebf8211 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -0,0 +1,97 @@ +# 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. + +type: object +title: Presence EDU +description: |- + An EDU representing presence updates for users of the sending homeserver. + Can also be used to request additional presence updates for users of the + receiving homeserver. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.presence`` + example: "m.presence" + content: + type: object + description: The presence updates and requests. + title: Presence Update + properties: + push: + type: array + description: |- + A list of presence updates that the receiving server is likely + to be interested in, or is subscribed to. + items: + type: object + title: User Presence Update + properties: + user_id: + type: string + description: The user ID this presence EDU is for. + example: "@john:matrix.org" + presence: + type: enum + enum: ['offline', 'unavailable', 'online'] + description: The presence of the user. + example: "online" + status_msg: + type: string + description: An optional description to accompany the presence. + example: "Making cupcakes" + last_active_ago: + type: integer + format: int64 + description: |- + The number of milliseconds that have ellapsed since the user + last did something. + example: 5000 + currently_active: + type: boolean + description: |- + Whether or not the user is currently using a device of theirs. + Defaults to false. + example: true + required: ['user_id', 'presence', 'last_active_ago'] + poll: + type: array + description: |- + New user IDs that the sending server would like to subscribe to the + presence of. The sending server should not include users it has already + requested to be subscribed to. + + The receiving server should ensure the sending server has reasonable + interest in subscribing to the provided users. The receiver may ignore + a request to subscribe to a user the sender does not have reasonable + interest in. Reasonable interest may be residing in a room with the user, + being subscribed to a presence list, or some other requirement. + + If non-empty, the receiving server should immediately send the presence + updates to the sender for the users requested. + items: + type: string + example: ["@alice:elsewhere.org"] + unpoll: + type: array + description: |- + New user IDs the sending server is no longer interested in receiving + presence updates for. The sending server should not include users it + has previously requested to be unsubscribed from. + items: + type: string + example: ["@bob:elsewhere.org"] + required: ['push'] diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 88f7b86c..bb821097 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -49,6 +49,7 @@ SWAGGER_DEFINITIONS = { os.path.join(matrix_doc_dir, "api/identity/definitions"): "is", os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push", os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss", + os.path.join(matrix_doc_dir, "api/server-server/definitions/presence"): "ss_presence", } EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples") EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema") diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a3d3f83a..d5177a04 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -838,57 +838,16 @@ Presence The server API for presence is based entirely on exchange of the following EDUs. There are no PDUs or Federation Queries involved. -Performing a presence update and poll subscription request:: +Servers should only send presence updates for users that the receiving server +would be interested in. This can include the receiving server sharing a room +with a given user, or a user on the receiving server has added one of the +sending server's users to their presence list. - EDU type: m.presence - - Content keys: - push: (optional): list of push operations. - Each should be an object with the following keys: - user_id: string containing a User ID - presence: "offline"|"unavailable"|"online"|"free_for_chat" - status_msg: (optional) string of free-form text - last_active_ago: milliseconds since the last activity by the user - - poll: (optional): list of strings giving User IDs - - unpoll: (optional): list of strings giving User IDs - -The presence of this combined message is two-fold: it informs the recipient -server of the current status of one or more users on the sending server (by the -``push`` key), and it maintains the list of users on the recipient server that -the sending server is interested in receiving updates for, by adding (by the -``poll`` key) or removing them (by the ``unpoll`` key). The ``poll`` and -``unpoll`` lists apply *changes* to the implied list of users; any existing IDs -that the server sent as ``poll`` operations in a previous message are not -removed until explicitly requested by a later ``unpoll``. - -On receipt of a message containing a non-empty ``poll`` list, the receiving -server should immediately send the sending server a presence update EDU of its -own, containing in a ``push`` list the current state of every user that was in -the original EDU's ``poll`` list. - -Sending a presence invite:: - - EDU type: m.presence_invite - - Content keys: - observed_user: string giving the User ID of the user whose presence is - requested (i.e. the recipient of the invite) - observer_user: string giving the User ID of the user who is requesting to - observe the presence (i.e. the sender of the invite) - -Accepting a presence invite:: - - EDU type: m.presence_accept - - Content keys - as for m.presence_invite - -Rejecting a presence invite:: - - EDU type: m.presence_deny - - Content keys - as for m.presence_invite +Servers may also request additional users by including them in the ``poll`` +array on an ``m.presence`` update. The receiving server may ignore users +requested in this array. The receiving server should maintain a list of +subscribed users for the sending server, which is appended to by the ``poll`` +array and deleted from by the ``unpoll`` array. .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence @@ -896,6 +855,14 @@ Rejecting a presence invite:: - Explain the zero-byte presence inference logic See also: docs/client-server/model/presence +{{definition_ss_event_schemas_m_presence}} + +{{definition_ss_event_schemas_m_presence_invite}} + +{{definition_ss_event_schemas_m_presence_accept}} + +{{definition_ss_event_schemas_m_presence_accept}} + Querying for information ------------------------ From e03bfbc47b5079a7bd54bbce1a4996524b6fc617 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 22:52:33 -0600 Subject: [PATCH 013/240] Document how read receipts work over federation Federation format: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L153-L166 Population of the fields that the above uses to construct the EDU: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L48-L56 --- .../definitions/event-schemas/m.receipt.yaml | 82 +++++++++++++++++++ specification/server_server_api.rst | 12 +++ 2 files changed, 94 insertions(+) create mode 100644 api/server-server/definitions/event-schemas/m.receipt.yaml diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml new file mode 100644 index 00000000..b8638427 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -0,0 +1,82 @@ +# 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. + +type: object +title: Receipt EDU +description: |- + An EDU representing receipt updates for users of the sending homeserver. + When receiving receipts, the server should only update entries that are + listed in the EDU. Receipts previously received that do not appear in the + EDU should not be removed or otherwise manipulated. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.receipt`` + example: "m.receipt" + content: + type: object + description: |- + Receipts for a particular room. The string key is the room ID for + which the receipts under it belong. + additionalProperties: + type: object + title: Room Receipts + properties: + # We strongly define the receipt type to help spec future ones later + # on. At that point, m.read can become optional (maybe). + "m.read": + type: object + description: Read receipts for users in the room. + title: User Read Receipt + properties: + event_ids: + type: array + description: |- + The event ID that the user has read up to. Must be exactly + one element in length. + minItems: 1 + maxItems: 1 + items: + type: string + example: ['$read_this_event:matrix.org'] + data: + type: object + description: Metadata for the read receipt. + title: Read Receipt Metadata + properties: + ts: + type: integer + format: int64 + description: |- + A POSIX timestamp in milliseconds for when the user read + the event specified in the read receipt. + example: 1533358089009 + required: ['ts'] + required: ['event_ids', 'data'] + required: ['m.read'] + example: { + "!some_room:domain.com": { + "m.read": { + "@john:matrix.org": { + "event_ids": ["$read_this_event:matrix.org"], + "data": { + "ts": 1533358089009 + } + } + } + } + } diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a3d3f83a..f19f41a6 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -896,6 +896,18 @@ Rejecting a presence invite:: - Explain the zero-byte presence inference logic See also: docs/client-server/model/presence +Receipts +-------- + +Receipts are EDUs used to communicate a marker for a given event. Currently the +only kind of receipt supported is a "read receipt", or where in the timeline a +user has read up to. + +Read receipts for events events that a user sent do not need to be sent. It is +implied that by sending the event the user has read up to the event. + +{{definition_ss_event_schemas_m_receipt}} + Querying for information ------------------------ From 0a7e670715cd31b73bf5bf0c14ebb36f1a76ccb7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 8 Aug 2018 08:28:52 -0600 Subject: [PATCH 014/240] Document how typing notifications work over federation Relevant synapse code: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/typing.py#L221-L230 --- .../definitions/event-schemas/m.typing.yaml | 45 +++++++++++++++++++ specification/server_server_api.rst | 10 +++++ 2 files changed, 55 insertions(+) create mode 100644 api/server-server/definitions/event-schemas/m.typing.yaml diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml new file mode 100644 index 00000000..d4fa2f81 --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -0,0 +1,45 @@ +# 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. + +type: object +title: Typing Notification EDU +description: A typing notification EDU for a user in a room. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: string + description: The string ``m.typing`` + example: "m.typing" + content: + type: object + description: The typing notification. + title: Typing Notification + properties: + room_id: + type: string + description: |- + The room where the user's typing status has been updated. + example: "!somewhere:matrix.org" + user_id: + type: string + description: |- + The user ID that has had their typing status changed. + example: "@john:matrix.org" + typing: + type: boolean + description: Whether the user is typing in the room or not. + example: true + required: ['room_id', 'user_id', 'typing'] diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a3d3f83a..4188c36b 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -833,6 +833,16 @@ should be retrieved for. {{public_rooms_ss_http_api}} +Typing Notifications +-------------------- + +When a server's users send typing notifications, those notifications need to +be sent to other servers in the room so their users are aware of the same +state. Receiving servers should verify that the user is in the room, and is +a user belonging to the sending server. + +{{definition_ss_event_schemas_m_typing}} + Presence -------- The server API for presence is based entirely on exchange of the following From 25c77ab2d0a9dd6a67454e27107ee4bdcbfe86b2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 13:43:07 -0600 Subject: [PATCH 015/240] Define authorization requirements on federation swagger APIs --- api/server-server/backfill.yaml | 6 ++++++ api/server-server/definitions/security.yaml | 19 +++++++++++++++++++ api/server-server/event_auth.yaml | 6 ++++++ api/server-server/events.yaml | 8 ++++++++ api/server-server/invites.yaml | 4 ++++ api/server-server/joins.yaml | 6 ++++++ api/server-server/leaving.yaml | 6 ++++++ api/server-server/public_rooms.yaml | 4 ++++ api/server-server/query.yaml | 9 +++++++++ api/server-server/third_party_invite.yaml | 4 ++++ api/server-server/transactions.yaml | 4 ++++ 11 files changed, 76 insertions(+) create mode 100644 api/server-server/definitions/security.yaml diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index f9f105e2..6b3cfaef 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/backfill/{roomId}": get: @@ -33,6 +35,8 @@ paths: Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it are retrieved, up to the total number given by the ``limit``. operationId: backfillRoom + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -85,6 +89,8 @@ paths: walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events`` and stopping at the ``limit``. operationId: getMissingPreviousEvents + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/definitions/security.yaml b/api/server-server/definitions/security.yaml new file mode 100644 index 00000000..6c9cc808 --- /dev/null +++ b/api/server-server/definitions/security.yaml @@ -0,0 +1,19 @@ +# 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. +signedRequest: + type: apiKey + description: |- + The ``Authorization`` header defined in the `Authentication`_ section. + name: Authorization + in: header diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index f55afddc..8857131f 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/event_auth/{roomId}/{eventId}": get: @@ -31,6 +33,8 @@ paths: description: |- Retrieves the complete auth chain for a given event. operationId: getEventAuth + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -72,6 +76,8 @@ paths: bottom-up after sorting each chain by depth then by event ID. The differences are then discovered and returned as the response to this API call. operationId: compareEventAuth + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index e87a0685..cf3988a2 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -22,6 +22,8 @@ schemes: basePath: /_matrix/federation/v1 produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/state/{roomId}": get: @@ -29,6 +31,8 @@ paths: description: |- Retrieves a snapshot of a room's state at a given event. operationId: getRoomState + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -74,6 +78,8 @@ paths: 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 + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -117,6 +123,8 @@ paths: description: |- Retrieves a single event. operationId: getEvent + security: + - signedRequest: [] parameters: - in: path name: eventId diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml index 98d53d49..6d905e17 100644 --- a/api/server-server/invites.yaml +++ b/api/server-server/invites.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/invite/{roomId}/{eventId}": put: @@ -33,6 +35,8 @@ paths: homeserver and the invited homeserver, it can be sent to all of the servers in the room by the inviting homeserver. operationId: sendInvite + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 14142945..e76a0aa6 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/make_join/{roomId}/{userId}": get: @@ -32,6 +34,8 @@ paths: Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room. operationId: makeJoin + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -145,6 +149,8 @@ paths: Submits a signed join event to the resident server for it to accept it into the room's graph. operationId: sendJoin + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 28bcf42c..be08acba 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/make_leave/{roomId}/{userId}": get: @@ -32,6 +34,8 @@ paths: 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 + security: + - signedRequest: [] parameters: - in: path name: roomId @@ -151,6 +155,8 @@ paths: Submits a signed leave event to the resident server for it to accept it into the room's graph. operationId: sendLeave + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml index 6cd07449..d162568f 100644 --- a/api/server-server/public_rooms.yaml +++ b/api/server-server/public_rooms.yaml @@ -22,6 +22,8 @@ schemes: basePath: /_matrix/federation/v1 produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/publicRooms": get: @@ -31,6 +33,8 @@ paths: rooms that are listed on another homeserver's directory, just those listed on the receiving homeserver's directory. operationId: getPublicRooms + security: + - signedRequest: [] parameters: - in: query name: limit diff --git a/api/server-server/query.yaml b/api/server-server/query.yaml index f569549e..dc14724c 100644 --- a/api/server-server/query.yaml +++ b/api/server-server/query.yaml @@ -23,6 +23,8 @@ schemes: basePath: /_matrix/federation/v1 produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/query/{queryType}": get: @@ -32,6 +34,8 @@ paths: arguments are dependent on which type of query is being made. Known query types are specified as their own endpoints as an extension to this definition. operationId: queryInfo + security: + - signedRequest: [] parameters: - in: path name: queryType @@ -54,6 +58,8 @@ paths: Servers may wish to cache the response to this query to avoid requesting the information too often. operationId: queryRoomDirectory + security: + - signedRequest: [] parameters: - in: query name: room_alias @@ -110,6 +116,9 @@ paths: Servers may wish to cache the response to this query to avoid requesting the information too often. + operationId: queryProfile + security: + - signedRequest: [] parameters: - in: query name: user_id diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 754a3282..5c12247c 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/exchange_third_party_invite/{roomId}": put: @@ -34,6 +36,8 @@ paths: an invite as per the `Inviting to a room`_ section before returning a response to this request. operationId: exchangeThirdPartyInvite + security: + - signedRequest: [] parameters: - in: path name: roomId diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 4f4c6b28..8d810ad5 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/send/{txnId}": put: @@ -36,6 +38,8 @@ paths: 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 + security: + - signedRequest: [] parameters: - in: path name: txnId From 6ad71f785e833f4e140647bd3a76f3af748b38fc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Aug 2018 12:48:59 -0600 Subject: [PATCH 016/240] Improve documentation for pushers and push gateways This fixes a number of formatting issues alongside a few documentation problems: * The push gateway can actually expect less parameters than previously advertised. This is for user privacy. * Introduction of the `m.email` pusher for email-capable homeservers. * Fields not being flagged as required on some endpoints. * Document the `event_id_only` format Note: this does not attempt to document push rules, just pushers. Fixes https://github.com/matrix-org/matrix-doc/issues/1374 Fixes https://github.com/matrix-org/matrix-doc/issues/1087 --- api/client-server/pusher.yaml | 106 ++++++++++++++++++---------- api/push-gateway/push_notifier.yaml | 90 +++++++++++------------ specification/modules/push.rst | 3 + 3 files changed, 116 insertions(+), 83 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 938014c6..0e9cf641 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -1,4 +1,5 @@ # 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. @@ -31,30 +32,30 @@ paths: get: summary: Gets the current pushers for the authenticated user description: |- - Gets all currently active pushers for the authenticated user + Gets all currently active pushers for the authenticated user. operationId: getPushers security: - accessToken: [] responses: 200: - description: The pushers for this user + description: The pushers for this user. examples: application/json: { - "pushers": [ - { - "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", - "kind": "http", - "app_id": "face.mcapp.appy.prod", - "app_display_name": "Appy McAppface", - "device_display_name": "Alice's Phone", - "profile_tag": "xyz", - "lang": "en-US", - "data": { - "url": "https://example.com/_matrix/push/v1/notify" - } + "pushers": [ + { + "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", + "kind": "http", + "app_id": "face.mcapp.appy.prod", + "app_display_name": "Appy McAppface", + "device_display_name": "Alice's Phone", + "profile_tag": "xyz", + "lang": "en-US", + "data": { + "url": "https://example.com/_matrix/push/v1/notify" } - ] - } + } + ] + } schema: type: object properties: @@ -70,7 +71,7 @@ paths: pushkey: type: string description: |- - This is a unique identifier for this pusher. See `/set` for + This is a unique identifier for this pusher. See ``/set`` for more detail. Max length, 512 bytes. kind: @@ -115,6 +116,19 @@ paths: description: |- Required if ``kind`` is ``http``. The URL to use to send notifications to. + format: + type: string + description: |- + The format to use when sending notifications to the Push + Gateway. + required: + - pushkey + - app_id + - kind + - app_display_name + - device_display_name + - lang + - data tags: - Push notifications "/pushers/set": @@ -130,23 +144,24 @@ paths: parameters: - in: body name: pusher - description: The pusher information + description: The pusher information. required: true schema: type: object example: { - "lang": "en", - "kind": "http", - "app_display_name": "Mat Rix", - "device_display_name": "iPhone 9", - "profile_tag": "xxyyzz", - "app_id": "com.example.app.ios", - "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", - "data": { - "url": "https://push-gateway.location.here" - }, - "append": false - } + "lang": "en", + "kind": "http", + "app_display_name": "Mat Rix", + "device_display_name": "iPhone 9", + "profile_tag": "xxyyzz", + "app_id": "com.example.app.ios", + "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", + "data": { + "url": "https://push-gateway.location.here/_matrix/push/v1/notify", + "format": "event_id_only" + }, + "append": false + } properties: pushkey: type: string @@ -157,11 +172,15 @@ paths: for APNS or the Registration ID for GCM. If your notification client has no such concept, use any unique identifier. Max length, 512 bytes. + + If the ``kind`` is ``"email"``, this is the email address to + send notifications to. kind: type: string description: |- The kind of pusher to configure. ``"http"`` makes a pusher that - sends HTTP pokes. ``null`` deletes the pusher. + sends HTTP pokes. ``"email"`` makes a pusher that emails the + user with unread notifications. ``null`` deletes the pusher. app_id: type: string description: |- @@ -169,6 +188,8 @@ paths: It is recommended that this end with the platform, such that different platform versions get different app identifiers. Max length, 64 chars. + + If the ``kind`` is ``"email"``, this is ``"m.email"``. app_display_name: type: string description: |- @@ -188,7 +209,7 @@ paths: type: string description: |- The preferred language for receiving notifications (e.g. 'en' - or 'en-US') + or 'en-US'). data: type: object description: |- @@ -202,6 +223,15 @@ paths: description: |- Required if ``kind`` is ``http``. The URL to use to send notifications to. + format: + type: string + description: |- + The format to send notifications in to Push Gateways. If + unset or unrecognized, the homeserver should populate as + many fields as it can in the push notification. If set to + ``"event_id_only"``, the homeserver should only send the + absolute minimum amount of information possible to the push + gateway by not including optional fields. append: type: boolean description: |- @@ -216,17 +246,17 @@ paths: 200: description: The pusher was set. examples: - application/json: { - } + application/json: {} schema: - type: object # empty json object + type: object + description: An empty object. 400: description: One or more of the pusher values were invalid. examples: application/json: { - "error": "Missing parameters: lang, data", - "errcode": "M_MISSING_PARAM" - } + "error": "Missing parameters: lang, data", + "errcode": "M_MISSING_PARAM" + } schema: "$ref": "definitions/errors/error.yaml" 429: diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 9b6e78d3..9f57b00a 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -1,4 +1,5 @@ # 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. @@ -19,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/push/%CLIENT_MAJOR_VERSION% +basePath: /_matrix/push/v1 consumes: - application/json produces: @@ -38,14 +39,14 @@ paths: Notifications about a particular event will normally cause the user to be alerted in some way. It is therefore necessary to perform duplicate - suppression for such notifications using the `event_id` field to avoid + suppression for such notifications using the ``event_id`` field to avoid retries of this HTTP API causing duplicate alerts. The operation of updating counts of unread notifications should be idempotent and therefore do not require duplicate suppression. - Notifications are sent to the URL configured when the pusher is - created. This means that the HTTP path may be different depending on the - push gateway. + Notifications are sent to the URL configured when the pusher is created. + This means that the HTTP path may be different depending on the push + gateway. operationId: notify parameters: - in: body @@ -55,36 +56,36 @@ paths: schema: type: object example: { - "notification": { - "id": "$3957tyerfgewrf384", - "room_id": "!slw48wfj34rtnrf:example.com", - "type": "m.room.message", - "sender": "@exampleuser:matrix.org", - "sender_display_name": "Major Tom", - "room_name": "Mission Control", - "room_alias": "#exampleroom:matrix.org", - "prio": "high", - "content": { - "msgtype": "m.text", - "body": "I'm floating in a most peculiar way." - }, - "counts": { - "unread" : 2, - "missed_calls": 1 - }, - "devices": [ - { - "app_id": "org.matrix.matrixConsole.ios", - "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", - "pushkey_ts": 12345678, - "data" : {}, - "tweaks": { - "sound": "bing" - } + "notification": { + "id": "$3957tyerfgewrf384", + "room_id": "!slw48wfj34rtnrf:example.com", + "type": "m.room.message", + "sender": "@exampleuser:matrix.org", + "sender_display_name": "Major Tom", + "room_name": "Mission Control", + "room_alias": "#exampleroom:matrix.org", + "prio": "high", + "content": { + "msgtype": "m.text", + "body": "I'm floating in a most peculiar way." + }, + "counts": { + "unread" : 2, + "missed_calls": 1 + }, + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data" : {}, + "tweaks": { + "sound": "bing" } - ] - } + } + ] } + } required: ["notification"] properties: notification: @@ -111,14 +112,10 @@ paths: type: string description: |- The type of the event as in the event's ``type`` field. - Required if the notification relates to a specific - Matrix event. sender: type: string description: |- The sender of the event as in the corresponding event field. - Required if the notification relates to a specific - Matrix event. sender_display_name: type: string description: |- @@ -149,14 +146,15 @@ paths: title: EventContent description: |- The ``content`` field from the event, if present. If the - event had no content field, this field is omitted. + event had no content field or the pusher wishes to not include + it, this field is omitted. counts: type: object title: Counts description: |- This is a dictionary of the current number of unacknowledged communications for the recipient user. Counts whose value is - zero are omitted. + zero should be omitted. properties: unread: type: integer @@ -180,10 +178,10 @@ paths: app_id: type: string description: |- - The app_id given when the pusher was created. + The ``app_id`` given when the pusher was created. pushkey: type: string - description: The pushkey given when the pusher was created. + description: The ``pushkey`` given when the pusher was created. pushkey_ts: type: integer description: |- @@ -202,13 +200,14 @@ paths: description: |- A dictionary of customisations made to the way this notification is to be presented. These are added by push rules. + required: ['app_id', 'pushkey'] responses: 200: description: A list of rejected push keys. examples: application/json: { - "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] - } + "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] + } schema: type: object # empty json object properties: @@ -222,7 +221,8 @@ paths: pushkeys and remove the associated pushers. It may not necessarily be the notification in the request that failed: it could be that a previous notification to the same pushkey - failed. + failed. May be empty. items: type: string - description: A pushkey + description: A pushkey that has been rejected. + required: ['rejected'] diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 9bb65b96..e6a7acf5 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -65,6 +65,9 @@ APNS or Google's GCM. This happens as follows: notifications. 5. The Push Provider sends the notification to the device. +Homeservers may optionally support email notifications or other push kinds +of push, identified by the ``kind`` field of the pusher configuration. + Definitions for terms used in this section are below: Push Provider From fcca80dad8329332733a23038a9840db397af4c8 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 14 Aug 2018 17:58:57 -0400 Subject: [PATCH 017/240] various minor fixes - formatting fixes - add examples to homeserver/identity server discovery schema - replace DNS name with hostname --- .../definitions/wellknown/homeserver.yaml | 7 ++++--- .../definitions/wellknown/identity_server.yaml | 7 ++++--- api/client-server/wellknown.yaml | 8 ++++---- specification/client_server_api.rst | 14 +++++++------- 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/api/client-server/definitions/wellknown/homeserver.yaml b/api/client-server/definitions/wellknown/homeserver.yaml index 7efba816..92ff34ed 100644 --- a/api/client-server/definitions/wellknown/homeserver.yaml +++ b/api/client-server/definitions/wellknown/homeserver.yaml @@ -16,8 +16,9 @@ description: |- Used by clients to discover homeserver information. type: object properties: - base_url: - type: string - description: The base URL for the homeserver for client-server connections. + base_url: + type: string + description: The base URL for the homeserver for client-server connections. + example: https://matrix.example.com required: - base_url diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml index eb0e0baf..a8f7c31c 100644 --- a/api/client-server/definitions/wellknown/identity_server.yaml +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -16,8 +16,9 @@ description: |- Used by clients to discover identity server information. type: object properties: - base_url: - type: string - description: The base URL for the identity server for client-server connections. + base_url: + type: string + description: The base URL for the identity server for client-server connections. + example: https://identity.example.com required: - base_url diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index 8d19f38a..24e190f9 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server server discovery API" + title: "Matrix Client-Server Server Discovery API" version: "1.0.0" host: localhost:8008 schemes: @@ -26,7 +26,7 @@ paths: get: summary: Gets Matrix server discovery information about the domain. description: |- - Gets discovery information about the domain. The file may include + Gets discovery information about the domain. The file may include additional keys, which MUST follow the Java package naming convention, e.g. ``com.example.myapp.property``. This ensures property names are suitably namespaced for each application and reduces the risk of @@ -37,7 +37,7 @@ paths: operationId: getWellknown responses: 200: - description: Server discovery information + description: Server discovery information. examples: application/json: { "m.homeserver": { @@ -61,6 +61,6 @@ paths: required: - m.homeserver 404: - description: No server discovery information available + description: No server discovery information available. tags: - Server administration diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6d564524..d2b7aa61 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -219,12 +219,12 @@ Well-known URI ++++++++++++++ The ``.well-known`` method uses a JSON file at a predetermined location to -specify parameter values. The flow for this method is as follows: +specify parameter values. The flow for this method is as follows: 1. Extract the server name from the user's Matrix ID by splitting the Matrix ID at the first colon. -2. Extract the DNS name from the server name. -3. Make a GET request to ``https://dns_name/.well-known/matrix/client``. +2. Extract the hostname from the server name. +3. Make a GET request to ``https://hostname/.well-known/matrix/client``. a. If the returned status code is 404, then ``IGNORE``. b. If the returned status code is not 200, or the response body is empty, @@ -233,17 +233,17 @@ specify parameter values. The flow for this method is as follows: i. If the content cannot be parsed, then ``FAIL_PROMPT``. - d. Extract the ``base_url`` value from the ``m.homeserver`` property. This + d. Extract the ``base_url`` value from the ``m.homeserver`` property. This value is to be used as the base URL of the homeserver. i. If this value is not provided, then ``FAIL_PROMPT``. e. Validate the homeserver base URL: - i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. + i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. ii. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the ``/_matrix/client/versions`` - endpoint, and parsing and validating the data. If any step in the + endpoint, and parsing and validating the data. If any step in the validation fails, then ``FAIL_ERROR``. Validation is done as a simple check against configuration errors, before sending sensitive information such as a user's password to the server. @@ -251,7 +251,7 @@ specify parameter values. The flow for this method is as follows: f. If the ``m.identity_server`` property is present, extract the ``base_url`` value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using - ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the + ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the ``m.identity_server`` property is present, but does not have a ``base_url`` value, then ``FAIL_ERROR``. From a264120b387a52d8506057148b681d1faf938c1c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 14 Aug 2018 18:06:03 -0400 Subject: [PATCH 018/240] put server discovery as its own section --- specification/client_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d2b7aa61..d775f2c0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -183,7 +183,7 @@ headers to be returned by servers on all requests are: Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization Server Discovery -~~~~~~~~~~~~~~~~ +---------------- In order to allow users to connect to a Matrix server without needing to explicitly specify the homeserver's URL or other parameters, clients SHOULD use @@ -216,7 +216,7 @@ In this section, the following terms are used with specific meanings: what to do next. Well-known URI -++++++++++++++ +~~~~~~~~~~~~~~ The ``.well-known`` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: From de961fb7d6c37bf9404e07a91c7e60db64465425 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 11:59:58 -0600 Subject: [PATCH 019/240] Improve wording on push gateways --- api/client-server/pusher.yaml | 11 +++++------ api/push-gateway/push_notifier.yaml | 6 +++--- specification/modules/push.rst | 5 ++--- specification/push_gateway.rst | 5 +++++ 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 0e9cf641..34050d3f 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -226,12 +226,11 @@ paths: format: type: string description: |- - The format to send notifications in to Push Gateways. If - unset or unrecognized, the homeserver should populate as - many fields as it can in the push notification. If set to - ``"event_id_only"``, the homeserver should only send the - absolute minimum amount of information possible to the push - gateway by not including optional fields. + The format to send notifications in to Push Gateways if the + ``kind`` is ``http``. The details about what fields the + homeserver should send to the push gateway are defined in the + `Push Gateway Specification`_. Currently the only format + available is 'event_id_only'. append: type: boolean description: |- diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 9f57b00a..4a6cb8f7 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -145,9 +145,9 @@ paths: type: object title: EventContent description: |- - The ``content`` field from the event, if present. If the - event had no content field or the pusher wishes to not include - it, this field is omitted. + The ``content`` field from the event, if present. The pusher + may omit this if the event had no content or for any other + reason. counts: type: object title: Counts diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e6a7acf5..e9ee8c90 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -65,9 +65,6 @@ APNS or Google's GCM. This happens as follows: notifications. 5. The Push Provider sends the notification to the device. -Homeservers may optionally support email notifications or other push kinds -of push, identified by the ``kind`` field of the pusher configuration. - Definitions for terms used in this section are below: Push Provider @@ -625,3 +622,5 @@ shouldn't be sent in the push itself where possible. Instead, Push Gateways should send a "sync" command to instruct the client to get new events from the homeserver directly. + +.. _`Push Gateway Specification`: ../push_gateway/unstable.html diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index 29a41bf7..e4a9d6ea 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -67,4 +67,9 @@ This describes the format used by "HTTP" pushers to send notifications of events to Push Gateways. If the endpoint returns an HTTP error code, the homeserver SHOULD retry for a reasonable amount of time using exponential backoff. +When pushing notifications for events, the hoemserver is expected to include all of +the event-related fields in the ``/notify`` request. When the homeserver is performing +a push where the ``format`` is ``"event_id_only"``, only the ``event_id``, ``room_id``, +``counts``, and ``devices`` are required to be populated. + {{push_notifier_push_http_api}} From fde48e7ee85369809955494bd9aa4c8df6c159c6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 15:12:36 -0600 Subject: [PATCH 020/240] Specify how room versioning works This is the spec PR for https://github.com/matrix-org/matrix-doc/issues/1425 Room version upgrades are not part of MSC1425. Documented aspects: * room_version on the create event * creating a room with a specific version (useful for testing) * make_join behaviour * error code documentation * grammar of room versions Based upon https://docs.google.com/document/d/1urKgReoHqxX8R_XtySB17dPi-DZcKhqTEL2_s895Wz0/edit --- api/client-server/create_room.yaml | 12 +++++-- api/server-server/joins.yaml | 33 +++++++++++++++++++ event-schemas/schema/m.room.create | 3 ++ .../appendices/identifier_grammar.rst | 31 +++++++++++++++++ specification/client_server_api.rst | 7 ++++ 5 files changed, 84 insertions(+), 2 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 66b5578a..1795d547 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -137,13 +137,21 @@ paths: type: string description: The invitee's third party identifier. 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: title: CreationContent type: object description: |- Extra keys to be added to the content of the ``m.room.create``. - The server will clobber the following keys: ``creator``. Future - versions of the specification may allow the server to clobber + The server will clobber the following keys: ``creator``, ``room_version``. + Future versions of the specification may allow the server to clobber other keys. initial_state: type: array diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 14142945..f054f1e0 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -45,6 +45,15 @@ paths: description: The user ID the join event will be for. required: true 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: 200: description: |- @@ -138,6 +147,30 @@ paths: ["$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}": put: summary: Submit a signed join event to a resident server diff --git a/event-schemas/schema/m.room.create b/event-schemas/schema/m.room.create index a07ab90f..d12b9ccd 100644 --- a/event-schemas/schema/m.room.create +++ b/event-schemas/schema/m.room.create @@ -11,6 +11,9 @@ properties: m.federate: description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist. type: boolean + room_version: + description: The version of the room. Defaults to ``"1"`` if the key does not exist. + type: string required: - creator type: object diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 7156c7d5..fc89f031 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -41,6 +41,37 @@ Examples of valid server names are: * ``[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 ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 58f68f25..bd9b8dca 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -148,6 +148,13 @@ Some requests have unique error codes: :``M_SERVER_NOT_TRUSTED``: 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: The client-server API typically uses ``HTTP PUT`` to submit requests with a From 7751750396c2496d3f3e2bfbaf2dc6efe8df9c9a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:23:33 -0600 Subject: [PATCH 021/240] changelog --- changelogs/client_server/newsfragments/1516.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1516.feature diff --git a/changelogs/client_server/newsfragments/1516.feature b/changelogs/client_server/newsfragments/1516.feature new file mode 100644 index 00000000..8e9b26df --- /dev/null +++ b/changelogs/client_server/newsfragments/1516.feature @@ -0,0 +1 @@ +Add support for Room Versions. From ae02e8834d99099d6f5933e52840e042836e3867 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:25:04 -0600 Subject: [PATCH 022/240] changelog --- changelogs/client_server/newsfragments/1506.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1506.feature diff --git a/changelogs/client_server/newsfragments/1506.feature b/changelogs/client_server/newsfragments/1506.feature new file mode 100644 index 00000000..62ad1260 --- /dev/null +++ b/changelogs/client_server/newsfragments/1506.feature @@ -0,0 +1 @@ +Document and improve client interaction with pushers. From 25d01aa4312b64131edd3097d687df3902093eff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:33:09 -0600 Subject: [PATCH 023/240] Dedicate a section on how to use access tokens Fixes https://github.com/matrix-org/matrix-doc/issues/1042. --- specification/client_server_api.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 58f68f25..27cd9a0f 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -191,10 +191,6 @@ previously obtained credentials in the form of an ``access_token`` query parameter or through an Authorization Header of ``Bearer $access_token``. An access token is typically obtained via the `Login`_ or `Registration`_ processes. -When credentials are required but missing or invalid, the HTTP call will -return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or -``M_UNKNOWN_TOKEN`` respectively. - .. NOTE:: This specification does not mandate a particular format for the access @@ -202,6 +198,19 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or to choose an appropriate format. Server implementors may like to investigate `macaroons `_. +Using access tokens +~~~~~~~~~~~~~~~~~~~ + +Access tokens may be provided in two ways, both of which the homeserver MUST +support: + +1. Via a query string parameter, ``access_token=TheTokenHere``. +#. Via a request header, ``Authorization: Bearer TheTokenHere``. + +When credentials are required but missing or invalid, the HTTP call will +return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or +``M_UNKNOWN_TOKEN`` respectively. + Relationship between access tokens and devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b159f218576aec308745283b3ffdcb4a4561bdd5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:34:23 -0600 Subject: [PATCH 024/240] changelog --- changelogs/client_server/newsfragments/1517.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1517.clarification diff --git a/changelogs/client_server/newsfragments/1517.clarification b/changelogs/client_server/newsfragments/1517.clarification new file mode 100644 index 00000000..b16928c1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1517.clarification @@ -0,0 +1 @@ +Clarify how access tokens are meant to be supplied to the homeserver. \ No newline at end of file From ca87876f1ba2a16f88a60ae9880d1db54ddf496b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:37:52 -0600 Subject: [PATCH 025/240] Clarify that the Authorization header is preferred --- specification/client_server_api.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 27cd9a0f..e64572ab 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -207,6 +207,11 @@ support: 1. Via a query string parameter, ``access_token=TheTokenHere``. #. Via a request header, ``Authorization: Bearer TheTokenHere``. +Clients are encouraged to use the ``Authorization`` header where possible +to prevent the access token being leaked in access/HTTP logs. The query +string should only be used in cases where the ``Authorization`` header is +unaccessible for the client. + When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or ``M_UNKNOWN_TOKEN`` respectively. From d6c54b0278bbf284c1232878fec41f24d9c9b468 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:39:01 -0600 Subject: [PATCH 026/240] unaccessible isn't a word --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e64572ab..7cd14f7f 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -210,7 +210,7 @@ support: Clients are encouraged to use the ``Authorization`` header where possible to prevent the access token being leaked in access/HTTP logs. The query string should only be used in cases where the ``Authorization`` header is -unaccessible for the client. +inaccessible for the client. When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or From 45c68e323a17f3e6b25b1c21038a5a6d600b3e03 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 17:25:30 -0600 Subject: [PATCH 027/240] Add general clarity to the /createRoom endpoint This commit does a number of things: * Minor formatting/alignment changes * Document the room_alias response key. This could be deprecated now, or forfeited, if needed. * Remove the guest_can_join parameter - it is not actually supported * Document the previously undocumented power_level_content_override parameter * Clarify that the room_id is required on the response * More clearly spell out which events are created as part of the request * Clarify how the room alias becomes the canonical alias * Clarify how the `visibility` may be used to determine a default preset to apply * Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value References: * Preset being inferred by the visibility: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/synapse/handlers/room.py#L172-L177 * Power level content overrides: * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198 * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359 * Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370 * `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315 Fixes https://github.com/matrix-org/matrix-doc/issues/1243 Fixes https://github.com/matrix-org/matrix-doc/issues/1471 Inspired by https://github.com/matrix-org/matrix-doc/issues/1213 --- api/client-server/create_room.yaml | 67 ++++++++++++++----- event-schemas/power_level_content_schema.yaml | 56 ++++++++++++++++ event-schemas/schema/m.room.power_levels | 44 +----------- 3 files changed, 107 insertions(+), 60 deletions(-) create mode 100644 event-schemas/power_level_content_schema.yaml diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 66b5578a..be99c4ab 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -39,16 +39,20 @@ paths: apply the events implied by the request in the following order: 0. A default ``m.room.power_levels`` event, giving the room creator - (and not other members) permission to send state events. + (and not other members) permission to send state events. Overridden + by the ``power_level_content_override`` parameter. - 1. Events set by the ``preset``. + 1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, + ``m.room.history_visibility``, and ``m.room.guest_access`` state events. 2. Events listed in ``initial_state``, in the order that they are listed. - 3. Events implied by ``name`` and ``topic``. + 3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic`` + state events). - 4. Invite events implied by ``invite`` and ``invite_3pid``. + 4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with + ``membership: invite`` and ``m.room.third_party_invite``). The available presets do the following with respect to room state: @@ -60,6 +64,9 @@ paths: ``public_chat`` ``public`` ``shared`` ``forbidden`` ======================== ============== ====================== ================ ========= + The server will create a ``m.room.create`` event in the room with the + requesting user as the creator, alongside other keys provided in the + ``creation_content``. operationId: createRoom security: - accessToken: [] @@ -70,14 +77,14 @@ paths: schema: type: object example: { - "preset": "public_chat", - "room_alias_name": "thepub", - "name": "The Grand Duke Pub", - "topic": "All about happy hour", - "creation_content": { - "m.federate": false - } + "preset": "public_chat", + "room_alias_name": "thepub", + "name": "The Grand Duke Pub", + "topic": "All about happy hour", + "creation_content": { + "m.federate": false } + } properties: visibility: type: string @@ -89,6 +96,11 @@ paths: ``private`` visibility if this key is not included. NB: This should not be confused with ``join_rules`` which also uses the word ``public``. + + If no ``preset`` is specificed, the server may use the visbility + to determine which preset to use. A visbility of ``public`` + equates to a preset of ``public_chat`` and ``private`` visibility + equates to a preset of ``private_chat``. room_alias_name: type: string description: |- @@ -98,6 +110,9 @@ paths: created the room. For example, if this was set to "foo" and sent to the homeserver "example.com" the complete room alias would be ``#foo:example.com``. + + The complete room alias will become the canonical alias for + the room. name: type: string description: |- @@ -145,6 +160,14 @@ paths: The server will clobber the following keys: ``creator``. Future versions of the specification may allow the server to clobber other keys. + properties: + "m.federate": + type: boolean + description: |- + Whether users on other servers can join this room. Defaults + to ``true`` or what the server specifies. Setting this to + ``false`` may prevent users from being invited as part of + this room creation request if they reside on other servers. initial_state: type: array description: |- @@ -181,10 +204,14 @@ paths: This flag makes the server set the ``is_direct`` flag on the ``m.room.member`` events sent to the users in ``invite`` and ``invite_3pid``. See `Direct Messaging`_ for more information. - guest_can_join: - type: boolean + power_level_content_override: + title: Power Level Event Content description: |- - Allows guests to join the room. See `Guest Access`_ for more information. + The power level content to override in the default power level + event. This object is applied on top of the generated power + level event prior to it being sent to the room. Defaults + to overriding nothing. + $ref: "definitions/event-schemas/power_level_content_schema.yaml" responses: 200: description: Information about the newly created room. @@ -196,10 +223,17 @@ paths: type: string description: |- The created room's ID. + room_alias: + type: string + description: |- + The complete room alias for the room, if a room alias was created + for the room. + required: ['room_id'] examples: application/json: { - "room_id": "!sefiuhWgwghwWgh:example.com" - } + "room_id": "!sefiuhWgwghwWgh:example.com", + "room_alias": "#thepub:example.com" + } 400: description: |- @@ -218,6 +252,5 @@ paths: ``M_INVALID_ROOM_STATE``). schema: "$ref": "definitions/errors/error.yaml" - tags: - Room creation diff --git a/event-schemas/power_level_content_schema.yaml b/event-schemas/power_level_content_schema.yaml new file mode 100644 index 00000000..5859d56e --- /dev/null +++ b/event-schemas/power_level_content_schema.yaml @@ -0,0 +1,56 @@ +# 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. +properties: + ban: + description: The level required to ban a user. Defaults to 50 if unspecified. + type: number + events: + additionalProperties: + type: number + description: The level required to send specific event types. This is a mapping from event type to power level required. + title: Event power levels + type: object + events_default: + description: |- + The default level required to send message events. Can be + overridden by the ``events`` key. Defaults to 0 if unspecified. + type: number + invite: + description: The level required to invite a user. Defaults to 50 if unspecified. + type: number + kick: + description: The level required to kick a user. Defaults to 50 if unspecified. + type: number + redact: + description: The level required to redact an event. Defaults to 50 if unspecified. + type: number + state_default: + description: |- + The default level required to send state events. Can be overridden + by the ``events`` key. Defaults to 50 if unspecified, but 0 if + there is no ``m.room.power_levels`` event at all. + type: number + users: + additionalProperties: + type: number + description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. + title: User power levels + type: object + users_default: + description: |- + The default power level for every user in the room, unless their + ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if + unspecified. + type: number +type: object \ No newline at end of file diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index 13a44c70..174ada82 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -43,49 +43,7 @@ description: |- properties: content: - properties: - ban: - description: The level required to ban a user. Defaults to 50 if unspecified. - type: number - events: - additionalProperties: - type: number - description: The level required to send specific event types. This is a mapping from event type to power level required. - title: Event power levels - type: object - events_default: - description: |- - The default level required to send message events. Can be - overridden by the ``events`` key. Defaults to 0 if unspecified. - type: number - invite: - description: The level required to invite a user. Defaults to 50 if unspecified. - type: number - kick: - description: The level required to kick a user. Defaults to 50 if unspecified. - type: number - redact: - description: The level required to redact an event. Defaults to 50 if unspecified. - type: number - state_default: - description: |- - The default level required to send state events. Can be overridden - by the ``events`` key. Defaults to 50 if unspecified, but 0 if - there is no ``m.room.power_levels`` event at all. - type: number - users: - additionalProperties: - type: number - description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. - title: User power levels - type: object - users_default: - description: |- - The default power level for every user in the room, unless their - ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if - unspecified. - type: number - type: object + $ref: "../power_level_content_schema.yaml" state_key: description: A zero-length string. pattern: '^$' From ef7570e62d59d2feecc2da28504dc9b32f298f94 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 17:29:06 -0600 Subject: [PATCH 028/240] Changelog --- changelogs/client_server/newsfragments/1518.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1518.clarification diff --git a/changelogs/client_server/newsfragments/1518.clarification b/changelogs/client_server/newsfragments/1518.clarification new file mode 100644 index 00000000..3e2adea3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1518.clarification @@ -0,0 +1 @@ +Document additional parameters on the ``/createRoom`` API. \ No newline at end of file From 2eab07ade4ffe0a619e315436ceb947124ec6566 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 16 Aug 2018 11:45:20 -0600 Subject: [PATCH 029/240] Fix header in server-server API --- specification/server_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 5f791a70..b5676b78 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -606,7 +606,7 @@ the events it is missing. {{backfill_ss_http_api}} Retrieving events ----------------- +----------------- In some circumstances, a homeserver may be missing a particular event or information about the room which cannot be easily determined from backfilling. These APIs provide From ba51d5960ecbc7b820235ad75765c06ccd4da379 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 16 Aug 2018 11:44:48 -0600 Subject: [PATCH 030/240] r0.1.0 release of the Push Gateway specification Because this is the first release, it has several moving parts to it: * The version variables have been defined. * The towncrier changelog has been prepared for future modifications. * The templating has been updated to better support future versions of the specification. * A release process document has been created. --- api/push-gateway/push_notifier.yaml | 2 +- changelogs/push_gateway.rst | 6 +++ .../push_gateway/newsfragments/.gitignore | 1 + changelogs/push_gateway/pyproject.toml | 30 ++++++++++++ meta/releasing_a_spec.md | 47 +++++++++++++++++++ scripts/gendoc.py | 6 +++ .../templating/matrix_templates/sections.py | 5 ++ scripts/templating/matrix_templates/units.py | 5 +- specification/push_gateway.rst | 19 +++++++- specification/targets.yaml | 2 +- 10 files changed, 117 insertions(+), 6 deletions(-) create mode 100644 changelogs/push_gateway.rst create mode 100644 changelogs/push_gateway/newsfragments/.gitignore create mode 100644 changelogs/push_gateway/pyproject.toml create mode 100644 meta/releasing_a_spec.md diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 4a6cb8f7..21c1ea29 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/push/v1 +basePath: /_matrix/push/%PUSH_GATEWAY_MAJOR_VERSION% consumes: - application/json produces: diff --git a/changelogs/push_gateway.rst b/changelogs/push_gateway.rst new file mode 100644 index 00000000..33a7683c --- /dev/null +++ b/changelogs/push_gateway.rst @@ -0,0 +1,6 @@ +r0.1.0 +====== + +The first release of the Push Gateway specification. This release contains +a single endpoint, ``/notify``, that pushers may use to send push notifications +to clients. diff --git a/changelogs/push_gateway/newsfragments/.gitignore b/changelogs/push_gateway/newsfragments/.gitignore new file mode 100644 index 00000000..b722e9e1 --- /dev/null +++ b/changelogs/push_gateway/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelogs/push_gateway/pyproject.toml b/changelogs/push_gateway/pyproject.toml new file mode 100644 index 00000000..dad1bc04 --- /dev/null +++ b/changelogs/push_gateway/pyproject.toml @@ -0,0 +1,30 @@ +[tool.towncrier] + filename = "../push_gateway.rst" + directory = "newsfragments" + issue_format = "`#{issue} `_" + title_format = "{version}" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "new" + name = "New Endpoints" + showcontent = true + + [[tool.towncrier.type]] + directory = "feature" + name = "Backwards Compatible Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "clarification" + name = "Spec Clarifications" + showcontent = true diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md new file mode 100644 index 00000000..cd7033fc --- /dev/null +++ b/meta/releasing_a_spec.md @@ -0,0 +1,47 @@ +# How to release a specification + +There are several specifications that belong to matrix, such as the client-server +specification, server-server specification, and identity server specification. Each +of these gets released independently of each other with their own version numbers. + +Once a specification is ready for release, a branch should be created to track the +changes in. This should be the name of the specification (as it appears in the directory +structure of this project) followed by a forward slash and the version being released, +followed by `_updates`. For example, if the Client-Server Specification was getting +an r0.4.0 release, the branch name would be `client_server/r0.4.0_updates`. + +*Note*: Historical releases prior to this process may or may not have an appropriate +release branch. Releases after this document came into place will have an appropriate +branch. + +The remainder of the process is as follows: +1. Activate your Python 3 virtual environment. +1. Having checked out the new release branch, navigate your way over to `./changelogs`. +1. Follow the release instructions provided in the README.md located there. +1. Update the changelog section of the specification you're releasing to make a reference + to the new version. +1. Update any version/link references across all specifications. +1. Update the index to list the version correctly. +1. Add the changes to the matrix-org/matrix.org repository (for historic tracking). + * This is done by making a PR to the `unstyled_docs/spec` folder for the version and + specification you're releasing. +1. Commit the changes and PR them to master. +1. Tag the release with the format `client_server/r0.4.0`. +1. Perform a release on GitHub to tag the release. +1. Yell from the mountaintop to the world about the new release. + +### Creating a release for a brand-new specification + +Some specifications may not have ever had a release, and therefore need a bit more work +to become ready. + +1. Activate your Python 3 virtual environment. +1. Having checked out the new release branch, navigate your way over to `./changelogs`. +1. Follow the "new changelog" instructions provided in the README.md located there. +1. Open the specification RST file and make some changes: + * Using a released specification as a template, update the changelog section. + * Use the appropriate changelog variable in the RST. +1. Create/define the appropriate variables in `gendoc.py`. +1. Update `targets.yml`. +1. Update any version/link references across all specifications. +1. Follow the regular release process. diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 16c40af5..042e3d9d 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -518,6 +518,10 @@ if __name__ == '__main__': "--server_release", "-s", action="store", default="unstable", help="The server-server release tag to generate, e.g. r1.2" ) + parser.add_argument( + "--push_gateway_release", "-p", action="store", default="unstable", + help="The push gateway release tag to generate, e.g. r1.2" + ) parser.add_argument( "--list_targets", action="store_true", help="Do not update the specification. Instead print a list of targets.", @@ -542,6 +546,8 @@ if __name__ == '__main__': "%CLIENT_MAJOR_VERSION%": "r0", "%SERVER_RELEASE_LABEL%": args.server_release, "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), + "%PUSH_GATEWAY_MAJOR_VERSION%": "v1", + "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release, } exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions)) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 1a93c723..65ed7f6d 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -31,6 +31,11 @@ class MatrixSections(Sections): def render_client_server_changelog(self): changelogs = self.units.get("changelogs") return changelogs["client_server"] + + # TODO: We should make this a generic variable instead of having to add functions all the time. + def render_push_gateway_changelog(self): + changelogs = self.units.get("changelogs") + return changelogs["push_gateway"] def _render_events(self, filterFn, sortFn): template = self.env.get_template("events.tmpl") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..c400b691 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -754,6 +754,7 @@ class MatrixUnits(Units): def load_apis(self, substitutions): cs_ver = substitutions.get("%CLIENT_RELEASE_LABEL%", "unstable") fed_ver = substitutions.get("%SERVER_RELEASE_LABEL%", "unstable") + push_gw_ver = substitutions.get("%PUSH_GATEWAY_RELEASE_LABEL%", "unstable") # we abuse the typetable to return this info to the templates return TypeTable(rows=[ @@ -774,8 +775,8 @@ class MatrixUnits(Units): "unstable", "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( - "`Push Gateway API `_", - "unstable", + "`Push Gateway API `_", + push_gw_ver, "Push notifications for Matrix events", ), ]) diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e4a9d6ea..e4623887 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -1,4 +1,5 @@ .. 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. @@ -21,13 +22,27 @@ the homeserver. This is managed by a distinct entity called the Push Gateway. .. contents:: Table of Contents .. sectnum:: -Specification version ---------------------- +Changelog +--------- + +.. topic:: Version: %PUSH_GATEWAY_RELEASE_LABEL% +{{push_gateway_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. +For the full historical changelog, see +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/push_gateway.rst + +Other versions of this specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following other versions are also available, in reverse chronological order: + +- `HEAD `_: Includes all changes since the latest versioned release. +- `r0.1.0 `_ + Overview -------- diff --git a/specification/targets.yaml b/specification/targets.yaml index 53957e0a..db869330 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -25,7 +25,7 @@ targets: push_gateway: files: - push_gateway.rst - version_label: unstable + version_label: "%PUSH_GATEWAY_RELEASE_LABEL%" appendices: files: - appendices.rst From c891e4a957d4e004517c3fbe5978da4764b7555b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 16 Aug 2018 12:39:47 -0600 Subject: [PATCH 031/240] Require the push gateway URL to be of a specific path --- api/client-server/pusher.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 34050d3f..3bedf866 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -222,7 +222,9 @@ paths: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send - notifications to. + notifications to. MUST be an HTTPS URL with a path pointing + to ``/_matrix/push/v1/notify``. + example: "https://push-gateway.location.here/_matrix/push/v1/notify" format: type: string description: |- From 17a0dcc7d396a1ce9ca55141a5491e47b62c1f62 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Thu, 16 Aug 2018 23:11:07 +0100 Subject: [PATCH 032/240] add newsfragment for #1176 --- changelogs/client_server/newsfragments/1176.new | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1176.new diff --git a/changelogs/client_server/newsfragments/1176.new b/changelogs/client_server/newsfragments/1176.new new file mode 100644 index 00000000..41e30799 --- /dev/null +++ b/changelogs/client_server/newsfragments/1176.new @@ -0,0 +1 @@ +Specify how to control the power level required for ``@room`` \ No newline at end of file From 5b30d33b89541d5398901fe73eeac73dc1a29cc2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 02:51:41 -0600 Subject: [PATCH 033/240] Simpler language --- api/client-server/pusher.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 3bedf866..d232baf9 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -222,8 +222,8 @@ paths: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send - notifications to. MUST be an HTTPS URL with a path pointing - to ``/_matrix/push/v1/notify``. + notifications to. MUST be an HTTPS URL with a path of + ``/_matrix/push/v1/notify``. example: "https://push-gateway.location.here/_matrix/push/v1/notify" format: type: string From e7aed3da269387a28ed43b79c9d3eef66436845c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:16:39 -0600 Subject: [PATCH 034/240] Remove poll/unpoll from presence --- .../definitions/event-schemas/m.presence.yaml | 31 +------------------ specification/server_server_api.rst | 8 +---- 2 files changed, 2 insertions(+), 37 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index bebf8211..6d83b967 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -16,8 +16,6 @@ type: object title: Presence EDU description: |- An EDU representing presence updates for users of the sending homeserver. - Can also be used to request additional presence updates for users of the - receiving homeserver. allOf: - $ref: ../edu.yaml - type: object @@ -35,7 +33,7 @@ allOf: type: array description: |- A list of presence updates that the receiving server is likely - to be interested in, or is subscribed to. + to be interested in. items: type: object title: User Presence Update @@ -67,31 +65,4 @@ allOf: Defaults to false. example: true required: ['user_id', 'presence', 'last_active_ago'] - poll: - type: array - description: |- - New user IDs that the sending server would like to subscribe to the - presence of. The sending server should not include users it has already - requested to be subscribed to. - - The receiving server should ensure the sending server has reasonable - interest in subscribing to the provided users. The receiver may ignore - a request to subscribe to a user the sender does not have reasonable - interest in. Reasonable interest may be residing in a room with the user, - being subscribed to a presence list, or some other requirement. - - If non-empty, the receiving server should immediately send the presence - updates to the sender for the users requested. - items: - type: string - example: ["@alice:elsewhere.org"] - unpoll: - type: array - description: |- - New user IDs the sending server is no longer interested in receiving - presence updates for. The sending server should not include users it - has previously requested to be unsubscribed from. - items: - type: string - example: ["@bob:elsewhere.org"] required: ['push'] diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index d5177a04..6cc04d95 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -841,13 +841,7 @@ EDUs. There are no PDUs or Federation Queries involved. Servers should only send presence updates for users that the receiving server would be interested in. This can include the receiving server sharing a room with a given user, or a user on the receiving server has added one of the -sending server's users to their presence list. - -Servers may also request additional users by including them in the ``poll`` -array on an ``m.presence`` update. The receiving server may ignore users -requested in this array. The receiving server should maintain a list of -subscribed users for the sending server, which is appended to by the ``poll`` -array and deleted from by the ``unpoll`` array. +sending server's users to their presence list. .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence From ff1afaa8f7a4a5828d46a60d27ece5de985e8de3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:18:45 -0600 Subject: [PATCH 035/240] Add a note about how presence lists work --- specification/server_server_api.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 6cc04d95..236d90f5 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -843,6 +843,12 @@ would be interested in. This can include the receiving server sharing a room with a given user, or a user on the receiving server has added one of the sending server's users to their presence list. +Clients may define lists of users that they are interested in via "Presence +Lists" through the `Client-Server API`_. When users are added to a presence +list, a ``m.presence_invite`` EDU is sent to them. The user may then accept +or deny their involvement in the list by sending either an ``m.presence_accept`` +or ``m.presence_deny`` EDU back. + .. TODO-doc - Explain the timing-based round-trip reduction mechanism for presence messages @@ -855,7 +861,7 @@ sending server's users to their presence list. {{definition_ss_event_schemas_m_presence_accept}} -{{definition_ss_event_schemas_m_presence_accept}} +{{definition_ss_event_schemas_m_presence_deny}} Querying for information ------------------------ From 549a25cad9b73df38d84b33e1837bf161f78b18b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:33:40 -0600 Subject: [PATCH 036/240] Add a mention about how currently_active works Reference: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/presence.py#L66-L68 --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 6d83b967..011db2ca 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -62,6 +62,8 @@ allOf: type: boolean description: |- Whether or not the user is currently using a device of theirs. + For example, if the user's ``last_active_ago`` was within the + last few minutes, they may be considered ``currently_active``. Defaults to false. example: true required: ['user_id', 'presence', 'last_active_ago'] From 766402a7025112569ddfe1efdc257513ff7d7ddf Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:34:08 -0600 Subject: [PATCH 037/240] Use strict types for the presence EDUs --- .../definitions/event-schemas/m.presence.accept.yaml | 3 ++- .../definitions/event-schemas/m.presence.deny.yaml | 3 ++- .../definitions/event-schemas/m.presence.invite.yaml | 3 ++- api/server-server/definitions/event-schemas/m.presence.yaml | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence.accept.yaml index 3b80ac44..72f932d2 100644 --- a/api/server-server/definitions/event-schemas/m.presence.accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.accept.yaml @@ -22,7 +22,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_accept'] description: The string ``m.presence_accept`` example: "m.presence_accept" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.deny.yaml b/api/server-server/definitions/event-schemas/m.presence.deny.yaml index 1383866c..3264a5af 100644 --- a/api/server-server/definitions/event-schemas/m.presence.deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.deny.yaml @@ -31,7 +31,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_deny'] description: The string ``m.presence_deny`` example: "m.presence_deny" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.invite.yaml b/api/server-server/definitions/event-schemas/m.presence.invite.yaml index eeb00ae3..8ae84872 100644 --- a/api/server-server/definitions/event-schemas/m.presence.invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.invite.yaml @@ -21,7 +21,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence_invite'] description: The string ``m.presence_invite`` example: "m.presence_invite" content: diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 011db2ca..f9e0499b 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -21,7 +21,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.presence'] description: The string ``m.presence`` example: "m.presence" content: From 96896fe5d6515a98f196556845f4e25fe48615d7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:34:50 -0600 Subject: [PATCH 038/240] Add a strict type the m.typing EDU --- api/server-server/definitions/event-schemas/m.typing.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index d4fa2f81..101d8d79 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -20,7 +20,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.typing'] description: The string ``m.typing`` example: "m.typing" content: From 44d1f8dbe5bf5826357d1d86d01c4897d3c83acd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:46:11 -0600 Subject: [PATCH 039/240] s/timeline/event graph --- specification/server_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f19f41a6..150e69e0 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -900,8 +900,8 @@ Receipts -------- Receipts are EDUs used to communicate a marker for a given event. Currently the -only kind of receipt supported is a "read receipt", or where in the timeline a -user has read up to. +only kind of receipt supported is a "read receipt", or where in the event graph +the user has read up to. Read receipts for events events that a user sent do not need to be sent. It is implied that by sending the event the user has read up to the event. From c492fe43b5d42f7f9d14228973e12b8a744ce3b8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:46:31 -0600 Subject: [PATCH 040/240] Add strict typing to the m.receipt EDU; Fix description of event_ids --- api/server-server/definitions/event-schemas/m.receipt.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index b8638427..210988f9 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -24,7 +24,8 @@ allOf: - type: object properties: edu_type: - type: string + type: enum + enum: ['m.receipt'] description: The string ``m.receipt`` example: "m.receipt" content: @@ -46,8 +47,7 @@ allOf: event_ids: type: array description: |- - The event ID that the user has read up to. Must be exactly - one element in length. + The extremity event IDs that the user has read up to. minItems: 1 maxItems: 1 items: From 6612dbecf182399af05403bc60097819382476ab Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 17 Aug 2018 11:54:14 -0400 Subject: [PATCH 041/240] tweak wording for validation --- specification/client_server_api.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d775f2c0..1a566aa0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -242,11 +242,13 @@ specify parameter values. The flow for this method is as follows: i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. ii. Clients SHOULD validate that the URL points to a valid homeserver - before accepting it by connecting to the ``/_matrix/client/versions`` - endpoint, and parsing and validating the data. If any step in the - validation fails, then ``FAIL_ERROR``. Validation is done as a simple - check against configuration errors, before sending sensitive - information such as a user's password to the server. + before accepting it by connecting to the |/_matrix/client/versions|_ + endpoint, ensuring that it does not return an error, and parsing and + validating that the data conforms with the expected response + format. If any step in the validation fails, then + ``FAIL_ERROR``. Validation is done as a simple check against + configuration errors, in order to ensure that the discovered address + points to a valid homeserver. f. If the ``m.identity_server`` property is present, extract the ``base_url`` value for use as the base URL of the identity server. @@ -1649,5 +1651,8 @@ have to wait in milliseconds before they can try again. .. |/user//account_data/| replace:: ``/user//account_data/`` .. _/user//account_data/: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type +.. |/_matrix/client/versions| replace:: ``/_matrix/client/versions`` +.. _/_matrix/client/versions: #get-matrix-client-versions + .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types From f5dc0eaed23e6e9dea0ea61f6a2ebefff5ade34a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 17 Aug 2018 12:00:13 -0400 Subject: [PATCH 042/240] document msisdn-related endpoints in IS (#1507) * add msisdn endpoints in Identity Server spec * add in CS endpoints that use the IS msisdn endpoints --- api/client-server/administrative_contact.yaml | 20 +- api/client-server/registration.yaml | 95 +++++++- api/identity/phone_associations.yaml | 203 ++++++++++++++++++ .../client_server/newsfragments/1507.new | 1 + specification/identity_service_api.rst | 5 + 5 files changed, 316 insertions(+), 8 deletions(-) create mode 100644 api/identity/phone_associations.yaml create mode 100644 changelogs/client_server/newsfragments/1507.new diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 8f0319d5..1cf66fe1 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -66,7 +66,7 @@ paths: medium: type: string description: The medium of the third party identifier. - enum: ["email"] + enum: ["email", "msisdn"] address: type: string description: The third party identifier address. @@ -143,7 +143,21 @@ paths: validation tokens when adding an email address to an account. This API's parameters and response is identical to that of the HS API |/register/email/requestToken|_ endpoint. - operationId: requestTokenTo3PID + operationId: requestTokenTo3PIDEmail responses: 200: - description: An email was sent to the given address + description: An email was sent to the given address. + "/account/3pid/msisdn/requestToken": + post: + summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account. + description: |- + Proxies the identity server API ``validate/msisdn/requestToken``, but + first checks that the given phone number is **not** already associated + with an account on this Home Server. This API should be used to request + validation tokens when adding a phone number to an account. This API's + parameters and response is identical to that of the HS API + |/register/msisdn/requestToken|_ endpoint. + operationId: requestTokenTo3PIDMSISDN + responses: + 200: + description: An SMS message was sent to the given phone number. diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 6ae4ddd3..56da9add 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -196,11 +196,9 @@ paths: description: |- Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated - with an account on this Home Server. Note that, for consistency, - this API takes JSON objects, though the Identity Server API takes - ``x-www-form-urlencoded`` parameters. See the Identity Server API for + with an account on this Home Server. See the Identity Server API for further information. - operationId: requestTokenToRegister + operationId: requestTokenToRegisterEmail parameters: - in: body name: body @@ -252,6 +250,71 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + "/register/msisdn/requestToken": + post: + summary: Requests a validation token be sent to the given phone number for the purpose of registering an account + description: |- + Proxies the identity server API ``validate/msisdn/requestToken``, but + first checks that the given phone number is not already associated + with an account on this Home Server. See the Identity Server API for + further information. + operationId: requestTokenToRegisterMSISDN + parameters: + - in: body + name: body + schema: + type: object + properties: + id_server: + type: string + description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default. + example: "id.matrix.org" + client_secret: + type: string + description: Client-generated secret string used to protect this session. + example: "this_is_my_secret_string" + country: + type: string + description: |- + The two-letter uppercase ISO country code that the number in + ``phone_number`` should be parsed as if it were dialled from. + phone_number: + type: string + description: The phone number. + example: "example@example.com" + send_attempt: + type: number + description: Used to distinguish protocol level retries from requests to re-send the SMS message. + example: 1 + required: ["client_secret", "country", "phone_number", "send_attempt"] + responses: + 200: + description: |- + An SMS message has been sent to the specified phone number. + Note that this may be an SMS message containing the validation token or it may be informing + the user of an error. + examples: + application/json: {} + schema: + type: object + 400: + description: |- + Part of the request was invalid. This may include one of the following error codes: + + * ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server. + However, if the home server has the ability to send SMS message, it is recommended that the server + instead send an SMS message to the user with instructions on how to reset their password. + This prevents malicious parties from being able to determine if a given phone number + has an account on the Home Server in question. + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server + that is not trusted by this Home Server. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + schema: + "$ref": "definitions/errors/error.yaml" "/account/password": post: summary: "Changes a user's password." @@ -319,10 +382,32 @@ paths: .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken - operationId: requestTokenToResetPassword + operationId: requestTokenToResetPasswordEmail responses: 200: description: An email was sent to the given address + "/account/password/msisdn/requestToken": + post: + summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. + description: |- + Proxies the identity server API ``validate/msisdn/requestToken``, but + first checks that the given phone number **is** associated with an account + on this Home Server. This API should be used to request + validation tokens when authenticating for the + `account/password` endpoint. This API's parameters and response are + identical to that of the HS API |/register/msisdn/requestToken|_ except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given email address could be found. The server may instead send an + SMS message to the given address prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. + + .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` + + .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken + operationId: requestTokenToResetPasswordMSISDN + responses: + 200: + description: An SMS message was sent to the given phone number. "/account/deactivate": post: summary: "Deactivate a user's account." diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml new file mode 100644 index 00000000..c2cc6cfe --- /dev/null +++ b/api/identity/phone_associations.yaml @@ -0,0 +1,203 @@ +# 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 Identity Service Phone Number Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/api/v1 +produces: + - application/json +paths: + "/validate/msisdn/requestToken": + post: + summary: Request a token for validating a phone number. + description: |- + Create a session for validating a phone number. + + The identity service will send an SMS message containing a token. If + that token is presented to the identity service in the future, it + indicates that that user was able to read the SMS for that phone + number, and so we validate ownership of the phone number. + + Note that Home Servers offer APIs that proxy this API, adding + additional behaviour on top, for example, + ``/register/msisdn/requestToken`` is designed specifically for use when + registering an account and therefore will inform the user if the phone + number given is already registered on the server. + + Note: for backwards compatibility with older versions of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: msisdnRequestToken + parameters: + - in: body + name: body + schema: + type: object + example: { + "client_secret": "monkeys_are_GREAT", + "country": "GB", + "phone_number": "07700900001", + "send_attempt": 1 + } + properties: + client_secret: + type: string + description: A unique string used to identify the validation attempt. + country: + type: string + description: |- + The two-letter uppercase ISO country code that the number in + ``phone_number`` should be parsed as if it were dialled from. + phone_number: + type: string + description: The phone number to validate. + send_attempt: + type: integer + description: |- + Optional. If specified, the server will only send an SMS if + the ``send_attempt`` is a number greater than the most recent + one which it has seen (or if it has never seen one), scoped + to that ``country`` + ``phone_number`` + ``client_secret`` + triple. This is to avoid repeatedly sending the same SMS in + the case of request retries between the POSTing user and the + identity service. The client should increment this value if + they desire a new SMS (e.g. a reminder) to be sent. + next_link: + type: string + description: |- + Optional. When the validation is completed, the identity + service will redirect the user to this URL. + required: ["client_secret", "country", "phone_number"] + responses: + 200: + description: + Session created. + examples: + application/json: { + "sid": "1234" + } + schema: + type: object + properties: + sid: + type: string + description: The session ID. + 400: + description: | + An error ocurred. Some possible errors are: + + - ``M_INVALID_ADDRESS``: The phone number provided was invalid. + - ``M_SEND_ERROR``: The validation SMS could not be sent. + "/validate/msisdn/submitToken": + post: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the phone number is considered to + have been validated. This does not publish any information publicly, or + associate the phone number address with any Matrix user + ID. Specifically, calls to ``/lookup`` will not show a binding. + + Note: for backwards compatibility with older versions of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: msisdnSubmitTokenPost + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret that was supplied to the ``requestToken`` call. + token: + type: string + description: The token generated by the ``requestToken`` call and sent to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + get: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the phone number address is + considered to have been validated. This does not publish any + information publicly, or associate the phone number with any Matrix + user ID. Specifically, calls to ``/lookup`` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: msisdnSubmitTokenGet + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the ``requestToken`` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the ``requestToken`` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the ``requestToken`` call and sent to the user. + x-example: atoken + responses: + "200": + description: Phone number is validated. + "3xx": + description: |- + Phone number address is validated, and the ``next_link`` parameter + was provided to the ``requestToken`` call. The user must be + redirected to the URL provided by the ``next_link`` parameter. + "4xx": + description: + Validation failed. diff --git a/changelogs/client_server/newsfragments/1507.new b/changelogs/client_server/newsfragments/1507.new new file mode 100644 index 00000000..6cc46870 --- /dev/null +++ b/changelogs/client_server/newsfragments/1507.new @@ -0,0 +1 @@ +``POST /account/3pid/msisdn/requestToken``, ``POST /register/msisdn/requestToken``, and ``POST /account/password/msisdn/requestToken`` \ No newline at end of file diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index cb079593..3b037caf 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -119,6 +119,11 @@ Email associations {{email_associations_is_http_api}} +Phone number associations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +{{phone_associations_is_http_api}} + General ~~~~~~~ From c2ed79bd1a37bf85b377c25722f3002dec8d075b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 17 Aug 2018 17:07:03 +0100 Subject: [PATCH 043/240] Sentence case for headings --- meta/documentation_style.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index e60c7847..c6bb62bf 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -32,6 +32,12 @@ complete specification to be merged correctly. These characters are: If you find yourself using ``^`` or beyond, you should rethink your document layout if possible. +Correct capitalisation for long section names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Headings should start with a capital letter, and use lower-case otherwise. + + TODOs ----- From 750d4f9fdaaafac8b52c05828f2675d03c10df51 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 10:53:47 -0600 Subject: [PATCH 044/240] Rename the presence EDU files to be accurate to their types; Misc cleanup of titles --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- .../{m.presence.accept.yaml => m.presence_accept.yaml} | 2 +- .../{m.presence.deny.yaml => m.presence_deny.yaml} | 2 +- .../{m.presence.invite.yaml => m.presence_invite.yaml} | 2 +- api/server-server/definitions/event-schemas/m.receipt.yaml | 2 +- api/server-server/definitions/event-schemas/m.typing.yaml | 2 +- .../matrix_templates/templates/schema-definition.tmpl | 2 +- scripts/templating/matrix_templates/units.py | 1 - 8 files changed, 7 insertions(+), 8 deletions(-) rename api/server-server/definitions/event-schemas/{m.presence.accept.yaml => m.presence_accept.yaml} (97%) rename api/server-server/definitions/event-schemas/{m.presence.deny.yaml => m.presence_deny.yaml} (98%) rename api/server-server/definitions/event-schemas/{m.presence.invite.yaml => m.presence_invite.yaml} (97%) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index f9e0499b..8d4ef6e8 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence EDU +title: ``m.presence`` EDU description: |- An EDU representing presence updates for users of the sending homeserver. allOf: diff --git a/api/server-server/definitions/event-schemas/m.presence.accept.yaml b/api/server-server/definitions/event-schemas/m.presence_accept.yaml similarity index 97% rename from api/server-server/definitions/event-schemas/m.presence.accept.yaml rename to api/server-server/definitions/event-schemas/m.presence_accept.yaml index 72f932d2..4c39989b 100644 --- a/api/server-server/definitions/event-schemas/m.presence.accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_accept.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite Accept EDU +title: ``m.presence_accept`` EDU description: |- An EDU representing approval for the observing user to subscribe to the presence of the the observed user. diff --git a/api/server-server/definitions/event-schemas/m.presence.deny.yaml b/api/server-server/definitions/event-schemas/m.presence_deny.yaml similarity index 98% rename from api/server-server/definitions/event-schemas/m.presence.deny.yaml rename to api/server-server/definitions/event-schemas/m.presence_deny.yaml index 3264a5af..1b9bff7d 100644 --- a/api/server-server/definitions/event-schemas/m.presence.deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_deny.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite Deny EDU +title: ``m.presence_deny`` EDU description: |- An EDU representing a declination or revocation for the observing user to subscribe to the presence of the observed user. diff --git a/api/server-server/definitions/event-schemas/m.presence.invite.yaml b/api/server-server/definitions/event-schemas/m.presence_invite.yaml similarity index 97% rename from api/server-server/definitions/event-schemas/m.presence.invite.yaml rename to api/server-server/definitions/event-schemas/m.presence_invite.yaml index 8ae84872..4cdc58eb 100644 --- a/api/server-server/definitions/event-schemas/m.presence.invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Presence Invite EDU +title: ``m.presence_invite`` EDU description: |- An EDU representing a request to subscribe to a user's presence. allOf: diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index 210988f9..58f47e3a 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Receipt EDU +title: ``m.receipt`` EDU description: |- An EDU representing receipt updates for users of the sending homeserver. When receiving receipts, the server should only update entries that are diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index 101d8d79..34b39529 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: Typing Notification EDU +title: ``m.typing`` EDU description: A typing notification EDU for a user in a room. allOf: - $ref: ../edu.yaml diff --git a/scripts/templating/matrix_templates/templates/schema-definition.tmpl b/scripts/templating/matrix_templates/templates/schema-definition.tmpl index 42a7ae47..e2be12e8 100644 --- a/scripts/templating/matrix_templates/templates/schema-definition.tmpl +++ b/scripts/templating/matrix_templates/templates/schema-definition.tmpl @@ -1,6 +1,6 @@ {% import 'tables.tmpl' as tables -%} -``{{definition.title}}`` Schema +``{{definition.title}}`` schema {{(11 + definition.title | length) * title_kind}} {% if 'description' in definition %} diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index c1481430..90a87cd4 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -49,7 +49,6 @@ SWAGGER_DEFINITIONS = { os.path.join(matrix_doc_dir, "api/identity/definitions"): "is", os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push", os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss", - os.path.join(matrix_doc_dir, "api/server-server/definitions/presence"): "ss_presence", } EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples") EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema") From a4015d5c273ba308475d40bb5311d279fa6cdac9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 10:58:20 -0600 Subject: [PATCH 045/240] Spelling --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 8d4ef6e8..b9c5f754 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -56,7 +56,7 @@ allOf: type: integer format: int64 description: |- - The number of milliseconds that have ellapsed since the user + The number of milliseconds that have elapsed since the user last did something. example: 5000 currently_active: From 5b5b4cfbed2941e342dc06678d39bf00ec50d0f7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 13:38:38 -0600 Subject: [PATCH 046/240] Explicitly say how appservices should detect state events Fixes https://github.com/matrix-org/matrix-doc/issues/1014 --- api/application-service/application_service.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 42c0c0cf..64064cbd 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -32,6 +32,10 @@ paths: description: |- This API is called by the homeserver when it wants to push an event (or batch of events) to the application service. + + The application service should take care to ensure that it handles + state events by the presence of a ``state_key``, not by the event + type. operationId: sendTransaction parameters: - in: path @@ -44,7 +48,7 @@ paths: x-example: "35" - in: body name: body - description: A list of events + description: A list of events. schema: type: object example: { From fd101b6ac967e692e24183942f5651e4bf451a76 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 13:39:17 -0600 Subject: [PATCH 047/240] Misc language changes --- specification/application_service_api.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..3666df33 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -1,4 +1,5 @@ .. 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. @@ -39,7 +40,7 @@ This version of the specification is generated from Application Services -------------------- Application services are passive and can only observe events from a given -homeserver. They can inject events into rooms they are participating in. +homeserver (HS). They can inject events into rooms they are participating in. They cannot prevent events from being sent, nor can they modify the content of the event being sent. In order to observe events from a homeserver, the homeserver needs to be configured to pass certain types of traffic to the @@ -217,7 +218,8 @@ need to be able to adjust the ``origin_server_ts`` value to do this. Inputs: - Application service token (``as_token``) - - Desired timestamp + - Desired timestamp in milliseconds since the unix epoch + Notes: - This will only apply when sending events. From 7caad61b86adc8ba44b9711a3f6aa91e46ec392e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 13:40:05 -0600 Subject: [PATCH 048/240] Clearly state how the users namespace relates to interest in events Fixes https://github.com/matrix-org/matrix-doc/issues/1307 --- specification/application_service_api.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 3666df33..5fe0aede 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -69,7 +69,13 @@ Registration Application services register "namespaces" of user IDs, room aliases and room IDs. These namespaces are represented as regular expressions. An application service is said to be "interested" in a given event if one of the IDs in the event match -the regular expression provided by the application service. An application +the regular expression provided by the application service, such as the room having +an alias or ID in the relevant namespaces. Similarly, the application service is +said to be interested in a given event if one of the application service's namespaced +users is the target of the event, or is a joined member of the room where the event +occurred. + +An application service can also state whether they should be the only ones who can manage a specified namespace. This is referred to as an "exclusive" namespace. An exclusive namespace prevents humans and other application From 857bcc0fe7613fa8d4623ba4ee0ee509eb528953 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 13:49:24 -0600 Subject: [PATCH 049/240] Encourage appservices to use the Authorization header This also throws in a mention about how to handle a request with a lack of user_id. The request samples now encourage the use of the header over the query string, and have had their sample values added for some readability. Fixes https://github.com/matrix-org/matrix-doc/issues/1296 Fixes https://github.com/matrix-org/matrix-doc/issues/1424 --- specification/application_service_api.rst | 36 +++++++++++++---------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..7119bd5a 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -192,22 +192,28 @@ they wish to be acting on behalf of. For real users, this would require additional permissions granting the AS permission to masquerade as a matrix user. Inputs: - - Application service token (``access_token``) + - Application service token (``as_token``) - User ID in the AS namespace to act as. Notes: - - This will apply on all aspects of the CS API, except for Account Management. + - This will apply on all aspects of the Client-Server API, except for Account Management. - The ``as_token`` is inserted into ``access_token`` which is usually where the - client token is. This is done on purpose to allow application services to - reuse client SDKs. + client token is, such as via the query string or ``Authorization`` header. This + is done on purpose to allow application services to reuse client SDKs. + - The ``access_token`` should be supplied through the ``Authorization`` header where + possible to prevent the token appearing in HTTP request logs by accident. -:: +The application service may specify the virtual user to act as through use of a +``user_id`` query string parameter on the request. The user specified in the query +string must be covered by one of the application service's ``user`` namespaces. If +the parameter is missing, the homeserver is to assume the application service intends +to act as the user implied by the ``sender_localpart`` property of the registration. + +An example request would be:: - /path?access_token=$token&user_id=$userid + GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org + Authorization: Bearer YourApplicationServiceTokenHere - Query Parameters: - access_token: The application service token - user_id: The desired user ID to act as. Timestamp massaging +++++++++++++++++++ @@ -223,11 +229,10 @@ Notes: :: - /path?access_token=$token&ts=$timestamp + PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 + Authorization: Bearer YourApplicationServiceTokenHere - Query Parameters added to the send event APIs only: - access_token: The application service token - ts: The desired timestamp + Content: The event to send, as per the Client-Server API. Server admin style permissions ++++++++++++++++++++++++++++++ @@ -250,12 +255,13 @@ including the AS token on a ``/register`` request, along with a login type of :: - /register?access_token=$as_token + POST /_matrix/client/%CLIENT_MAJOR_VERSION%/register + Authorization: Bearer YourApplicationServiceTokenHere Content: { type: "m.login.application_service", - username: "" + username: "_irc_example" } Application services which attempt to create users or aliases *outside* of From 205b326e4a393eb5f32d72f3154f7ea33096d8ba Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:03:30 -0600 Subject: [PATCH 050/240] Add a note that application services cannot /sync normally Fixes https://github.com/matrix-org/matrix-doc/issues/1144 --- specification/application_service_api.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..1f1c8b5b 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -264,6 +264,14 @@ normal users who attempt to create users or aliases *inside* an application service-defined namespace will receive the same ``M_EXCLUSIVE`` error code, but only if the application service has defined the namespace as ``exclusive``. +Using ``/sync`` and ``/events`` ++++++++++++++++++++++++++++++++ + +Application services wishing to use ``/sync`` or ``/events`` from the Client-Server +API MUST do so with a virtual user (provide a ``user_id`` via the query string). It +is expectected that the application service use the transactions pushed to it to +handle events rather than syncing with the user implied by ``sender_localpart``. + ID conventions ~~~~~~~~~~~~~~ .. TODO-spec From 954498bf7877af3d67b9d08096e0cddfbe3360b5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:13:56 -0600 Subject: [PATCH 051/240] Recommend that application services use an underscore for namespacing Fixes https://github.com/matrix-org/matrix-doc/issues/689 --- specification/application_service_api.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..778d2e81 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -83,7 +83,7 @@ regular expressions and look like: users: - exclusive: true - regex: @irc.freenode.net_.* + regex: @_irc.freenode.net_.* The registration is represented by a series of key-value pairs, which this @@ -105,12 +105,17 @@ traffic to the AS is: aliases: [] # Namespaces of room aliases which should be delegated to the AS rooms: [] # Namespaces of room ids which should be delegated to the AS +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:: If the homeserver in question has multiple application services, each ``as_token`` and ``id`` MUST be unique per application service as these are used to identify the application service. The homeserver MUST enforce this. - Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 069a2f74811d489e763fc152cbe386f733dec83b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:22:06 -0600 Subject: [PATCH 052/240] Split the query user and room APIs out to their own files --- .../application_service.yaml | 115 ------------------ api/application-service/query_room.yaml | 86 +++++++++++++ api/application-service/query_user.yaml | 83 +++++++++++++ specification/application_service_api.rst | 4 + 4 files changed, 173 insertions(+), 115 deletions(-) create mode 100644 api/application-service/query_room.yaml create mode 100644 api/application-service/query_user.yaml diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 42c0c0cf..e5e22c9b 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -92,121 +92,6 @@ paths: } schema: type: object - "/rooms/{roomAlias}": - get: - summary: Query if a room alias should exist on the application service. - description: |- - This endpoint is invoked by the homeserver on an application service to query - the existence of a given room alias. The homeserver will only query room - aliases inside the application service's ``aliases`` namespace. The - homeserver will send this request when it receives a request to join a - room alias within the application service's namespace. - operationId: queryRoomByAlias - parameters: - - in: path - name: roomAlias - type: string - description: The room alias being queried. - required: true - x-example: "#magicforest:example.com" - responses: - 200: - description: |- - The application service indicates that this room alias exists. The - application service MUST have created a room and associated it with - the queried room alias using the client-server API. Additional - information about the room such as its name and topic can be set - before responding. - examples: - application/json: { - } - schema: - type: object - 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: |- - The application service indicates that this room alias does not exist. - Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/users/{userId}": - get: - summary: Query if a user should exist on the application service. - description: |- - This endpoint is invoked by the homeserver on an application service to query - the existence of a given user ID. The homeserver will only query user IDs - inside the application service's ``users`` namespace. The homeserver will - send this request when it receives an event for an unknown user ID in - the application service's namespace. - operationId: queryUserById - parameters: - - in: path - name: userId - type: string - description: The user ID being queried. - required: true - x-example: "@alice:example.com" - responses: - 200: - description: |- - The application service indicates that this user exists. The application - service MUST create the user using the client-server API. - examples: - application/json: { - } - schema: - type: object - 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: |- - The application service indicates that this user does not exist. - Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the application service supports. diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml new file mode 100644 index 00000000..e898f103 --- /dev/null +++ b/api/application-service/query_room.yaml @@ -0,0 +1,86 @@ +# 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: + "/rooms/{roomAlias}": + get: + summary: Query if a room alias should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given room alias. The homeserver will only query room + aliases inside the application service's ``aliases`` namespace. The + homeserver will send this request when it receives a request to join a + room alias within the application service's namespace. + operationId: queryRoomByAlias + parameters: + - in: path + name: roomAlias + type: string + description: The room alias being queried. + required: true + x-example: "#magicforest:example.com" + responses: + 200: + description: |- + The application service indicates that this room alias exists. The + application service MUST have created a room and associated it with + the queried room alias using the client-server API. Additional + information about the room such as its name and topic can be set + before responding. + examples: + application/json: { + } + schema: + type: object + 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: |- + The application service indicates that this room alias does not exist. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml new file mode 100644 index 00000000..4f699ad6 --- /dev/null +++ b/api/application-service/query_user.yaml @@ -0,0 +1,83 @@ +# 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: + "/users/{userId}": + get: + summary: Query if a user should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given user ID. The homeserver will only query user IDs + inside the application service's ``users`` namespace. The homeserver will + send this request when it receives an event for an unknown user ID in + the application service's namespace. + operationId: queryUserById + parameters: + - in: path + name: userId + type: string + description: The user ID being queried. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: |- + The application service indicates that this user exists. The application + service MUST create the user using the client-server API. + examples: + application/json: { + } + schema: + type: object + 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: |- + The application service indicates that this user does not exist. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..cde22a89 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -172,6 +172,10 @@ application services MUST implement these APIs. These APIs are defined below. {{application_service_as_http_api}} +{{query_user_as_http_api}} + +{{query_room_as_http_api}} + .. _create the user: `sect:asapi-permissions`_ From 95b2b7c2bcf5249c190e3ee4b56fe9c34b8041f0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:30:42 -0600 Subject: [PATCH 053/240] Move query APIs to the right heading Fixes https://github.com/matrix-org/matrix-doc/issues/1325 Addresses some of https://github.com/matrix-org/matrix-doc/issues/1532 --- specification/application_service_api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index cde22a89..824139f0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -163,6 +163,10 @@ this request (e.g. to join a room alias). the application service about information about the entity such as room ID to room alias mappings. +{{query_user_as_http_api}} + +{{query_room_as_http_api}} + HTTP APIs +++++++++ @@ -172,10 +176,6 @@ application services MUST implement these APIs. These APIs are defined below. {{application_service_as_http_api}} -{{query_user_as_http_api}} - -{{query_room_as_http_api}} - .. _create the user: `sect:asapi-permissions`_ From 0863c5452e95518f7047d6b9ced3e7e7141885d4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:31:21 -0600 Subject: [PATCH 054/240] Take out the false third party network endpoints Fixes https://github.com/matrix-org/matrix-doc/issues/800 --- specification/application_service_api.rst | 73 +---------------------- 1 file changed, 3 insertions(+), 70 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 824139f0..534f1ac0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -268,78 +268,11 @@ normal users who attempt to create users or aliases *inside* an application service-defined namespace will receive the same ``M_EXCLUSIVE`` error code, but only if the application service has defined the namespace as ``exclusive``. -ID conventions -~~~~~~~~~~~~~~ -.. TODO-spec - - Giving HSes the freedom to namespace still feels like the Right Thing here. - - Exposing a public API provides the consistency which was the main complaint - against namespacing. - - This may have knock-on effects for the AS registration API. E.g. why don't - we let ASes specify the *URI* regex they want? - -This concerns the well-defined conventions for mapping 3P network IDs to matrix -IDs, which we expect clients to be able to do by themselves. - -User IDs -++++++++ -Matrix users may wish to directly contact a virtual user, e.g. to send an email. -The URI format is a well-structured way to represent a number of different ID -types, including: - -- MSISDNs (``tel``) -- Email addresses (``mailto``) -- IRC nicks (``irc`` - https://tools.ietf.org/html/draft-butcher-irc-url-04) -- XMPP (XEP-0032) -- SIP URIs (RFC 3261) - -As a result, virtual user IDs SHOULD relate to their URI counterpart. This -mapping from URI to user ID can be expressed in a number of ways: - -- Expose a C-S API on the HS which takes URIs and responds with user IDs. -- Munge the URI with the user ID. - -Exposing an API would allow HSes to internally map user IDs however they like, -at the cost of an extra round trip (of which the response can be cached). -Munging the URI would allow clients to apply the mapping locally, but would force -user X on service Y to always map to the same munged user ID. Considering the -exposed API could just be applying this munging, there is more flexibility if -an API is exposed. - -:: - - GET /_matrix/app/%CLIENT_MAJOR_VERSION%/user?uri=$url_encoded_uri - - Returns 200 OK: - { - user_id: - } - -Room Aliases -++++++++++++ -We may want to expose some 3P network rooms so Matrix users can join them directly, -e.g. IRC rooms. We don't want to expose every 3P network room though, e.g. -``mailto``, ``tel``. Rooms which are publicly accessible (e.g. IRC rooms) can be -exposed as an alias by the application service. Private rooms -(e.g. sending an email to someone) should not -be exposed in this way, but should instead operate using normal invite/join semantics. -Therefore, the ID conventions discussed below are only valid for public rooms which -expose room aliases. - -Matrix users may wish to join XMPP rooms (e.g. using XEP-0045) or IRC rooms. In both -cases, these rooms can be expressed as URIs. For consistency, these "room" URIs -SHOULD be mapped in the same way as "user" URIs. - -:: - - GET /_matrix/app/%CLIENT_MAJOR_VERSION%/alias?uri=$url_encoded_uri +Event fields +~~~~~~~~~~~~ - Returns 200 OK: - { - alias: - } +.. TODO-TravisR: Fix this section to be a general "3rd party networks" section -Event fields -++++++++++++ We recommend that any events that originated from a remote network should include an ``external_url`` field in their content to provide a way for Matrix clients to link into the 'native' client from which the event originated. From 60b8e72a67cb81b868cc74640d35455cd23c8bd1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:44:46 -0600 Subject: [PATCH 055/240] Minor text changes to the query APIs; Keep OpenMarket copyright The bulk of these APIs were copied from OpenMarket's work - we should preserve the copyright header. --- api/application-service/query_room.yaml | 6 +++--- api/application-service/query_user.yaml | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index e898f103..7a5a7e54 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -1,3 +1,4 @@ +# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -39,7 +40,7 @@ paths: - in: path name: roomAlias type: string - description: The room alias being queried. + description: The URL encoded room alias being queried. required: true x-example: "#magicforest:example.com" responses: @@ -51,8 +52,7 @@ paths: information about the room such as its name and topic can be set before responding. examples: - application/json: { - } + application/json: {} schema: type: object 401: diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 4f699ad6..4d1e9f44 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -1,3 +1,4 @@ +# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -33,13 +34,13 @@ paths: the existence of a given user ID. The homeserver will only query user IDs inside the application service's ``users`` namespace. The homeserver will send this request when it receives an event for an unknown user ID in - the application service's namespace. + the application service's namespace, such as a room invite. operationId: queryUserById parameters: - in: path name: userId type: string - description: The user ID being queried. + description: The URL encoded user ID being queried. required: true x-example: "@alice:example.com" responses: @@ -48,8 +49,7 @@ paths: The application service indicates that this user exists. The application service MUST create the user using the client-server API. examples: - application/json: { - } + application/json: {} schema: type: object 401: From ab3272045e43679d42e05120ea251db7c7dda62c Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 5 Jun 2018 15:12:25 +0200 Subject: [PATCH 056/240] add missing v1 to m.olm in /keys/upload --- api/client-server/keys.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 6e995c2c..457311cf 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -194,7 +194,7 @@ paths: "user_id": "@alice:example.com", "device_id": "JLAFKJWSCS", "algorithms": [ - "m.olm.curve25519-aes-sha256", + "m.olm.v1.curve25519-aes-sha256", "m.megolm.v1.aes-sha" ], "keys": { From e210f8b05005f17dfe957d9bae01a2c0dd1e84cf Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:08:00 +0200 Subject: [PATCH 057/240] add e2e messaging algorithms section intro This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1f778bc2..08138270 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -228,6 +228,28 @@ A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public part of a one time key once it has given that key to another user. +Messaging Algorithms +-------------------- + +Messaging Algorithm Names +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Messaging algorithm names use the extensible naming scheme used throughout this +specification. Algorithm names that start with ``m.`` are reserved for +algorithms defined by this specification. Implementations wanting to experiment +with new algorithms are encouraged to pick algorithm names that start with +their domain to reduce the risk of collisions. + +Algorithm names should be short and meaningful, and should list the primitives +used by the algorithm so that it is easier to see if the algorithm is using a +broken primitive. + +A name of ``m.olm.v1`` is too short: it gives no information about the primitives +in use, and is difficult to extend for different primitives. However a name of +``m.olm.v1.ecdh-curve25519-hdkfsha256.hmacsha256.hkdfsha256-aes256-cbc-hmac64sha256`` +is too long despite giving a more precise description of the algorithm: it adds +to the data transfer overhead and sacrifices clarity for human readers without +adding any useful extra information. Protocol definitions -------------------- From 33802dbbafd0be45ad5abb1e4eb5285fd57a1a04 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:10:36 +0200 Subject: [PATCH 058/240] add olm messaging algorithm subsection This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 08138270..1a58ee31 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -251,6 +251,76 @@ is too long despite giving a more precise description of the algorithm: it adds to the data transfer overhead and sacrifices clarity for human readers without adding any useful extra information. +``m.olm.v1.curve25519-aes-sha2`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The name ``m.olm.v1.curve25519-aes-sha2`` corresponds to version 1 of the Olm +ratchet, as defined by the `Olm specification`_. This uses: + +* Curve25519 for the initial key agreement. +* HKDF-SHA-256 for ratchet key derivation. +* Curve25519 for the root key ratchet. +* HMAC-SHA-256 for the chain key ratchet. +* HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. + +Devices that support Olm must include "m.olm.v1.curve25519-aes-sha2" in their +list of supported messaging algorithms, must list a Curve25519 device key, and +must publish Curve25519 one-time keys. + +An event encrypted using Olm has the following format: + +.. code:: json + + { + "type": "m.room.encrypted", + "content": { + "algorithm": "m.olm.v1.curve25519-aes-sha2", + "sender_key": "", + "ciphertext": { + "": { + "type": 0, + "body": "" + } } } } + +``ciphertext`` is a mapping from device Curve25519 key to an encrypted payload +for that device. ``body`` is a Base64-encoded Olm message body. ``type`` is an +integer indicating the type of the message body: 0 for the initial pre-key +message, 1 for ordinary messages. + +Olm sessions will generate messages with a type of 0 until they receive a +message. Once a session has decrypted a message it will produce messages with +a type of 1. + +When a client receives a message with a type of 0 it must first check if it +already has a matching session. If it does then it will use that session to +try to decrypt the message. If there is no existing session then the client +must create a new session and use the new session to decrypt the message. A +client must not persist a session or remove one-time keys used by a session +until it has successfully decrypted a message using that session. + +Messages with type 1 can only be decrypted with an existing session. If there +is no matching session, the client should show this as an invalid message. + +The plaintext payload is of the form: + +.. code:: json + + { + "type": "", + "content": "", + "room_id": "", + } + +The type and content of the plaintext message event are given in the payload. + +We include the room ID in the payload, because otherwise the homeserver would +be able to change the room a message was sent in. + +.. TODO: claimed_keys + +Clients must confirm that the ``sender_key`` belongs to the user that sent the +message. TODO: how? + Protocol definitions -------------------- @@ -310,6 +380,7 @@ Example response: .. _ed25519: http://ed25519.cr.yp.to/ .. _curve25519: https://cr.yp.to/ecdh.html +.. _`Olm specification`: http://matrix.org/docs/spec/olm.html .. _`Signing JSON`: ../appendices.html#signing-json From 07e3de3c61cbb5b379477de5856829a449e33ff1 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:12:31 +0200 Subject: [PATCH 059/240] add megolm messaging algorithm subsection This was written by Richard van der Hoff. --- specification/modules/end_to_end_encryption.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1a58ee31..e2cb54e5 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -321,6 +321,17 @@ be able to change the room a message was sent in. Clients must confirm that the ``sender_key`` belongs to the user that sent the message. TODO: how? +``m.megolm.v1.aes-sha2`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The name ``m.megolm.v1.aes-sha2`` corresponds to version 1 of the Megolm +ratchet, as defined by the `Megolm specification`_. This uses: + +* HMAC-SHA-256 for the hash ratchet. +* HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. +* Ed25519 for message authenticity. + + Protocol definitions -------------------- @@ -381,6 +392,7 @@ Example response: .. _ed25519: http://ed25519.cr.yp.to/ .. _curve25519: https://cr.yp.to/ecdh.html .. _`Olm specification`: http://matrix.org/docs/spec/olm.html +.. _`Megolm specification`: http://matrix.org/docs/spec/megolm.html .. _`Signing JSON`: ../appendices.html#signing-json From 2686b990806e59cce7cad07fcc4d03ea7eba13d5 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:23:32 +0200 Subject: [PATCH 060/240] fix json indent --- specification/modules/end_to_end_encryption.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index e2cb54e5..68e030e1 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -274,13 +274,16 @@ An event encrypted using Olm has the following format: { "type": "m.room.encrypted", "content": { - "algorithm": "m.olm.v1.curve25519-aes-sha2", + "algorithm": "m.olm.v1.curve25519-aes-sha2", "sender_key": "", "ciphertext": { "": { "type": 0, "body": "" - } } } } + } + } + } + } ``ciphertext`` is a mapping from device Curve25519 key to an encrypted payload for that device. ``body`` is a Base64-encoded Olm message body. ``type`` is an From 8afc82c14b70d23f7133470ed9304b2031e3a55b Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 11:48:20 +0200 Subject: [PATCH 061/240] fix /keys/claim request example It didn't correspond to the example response. --- api/client-server/keys.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 457311cf..55f8a5a5 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -247,7 +247,7 @@ paths: description: algorithm example: "signed_curve25519" example: - "@alice:example.com": { "JLAFKJWSCS": "curve25519" } + "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } required: - one_time_keys responses: From 10c3307427808da03aed24165b17c4911486b3b0 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 15:18:59 +0200 Subject: [PATCH 062/240] document device_one_time_keys_count in /sync/ response fix #1157 --- api/client-server/sync.yaml | 8 ++++++++ specification/modules/end_to_end_encryption.rst | 11 +++++++++++ 2 files changed, 19 insertions(+) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 34659dd0..4b44c20e 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -253,6 +253,14 @@ paths: description: |- Information on end-to-end device updates, as specified in |device_lists_sync|_. + device_one_time_keys_count: + title: One-time keys count + type: object + additionalProperties: + type: integer + description: |- + Information on end-to-end encryption keys, as specified + in |device_lists_sync|_. examples: application/json: { "next_batch": "s72595_4483_1934", diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 68e030e1..b030ab64 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -355,6 +355,9 @@ specified). The client is expected to use |/keys/query|_ or |/keys/changes|_ for the equivalent functionality after an initial sync, as documented in `Tracking the device list for a user`_. +It also adds a ``one_time_keys_count`` property. Note the spelling difference +with the ``one_time_key_counts`` property in the |/keys/upload|_ response. + .. todo: generate this from a swagger definition? .. device_lists: { changed: ["@user:server", ... ]}, @@ -364,6 +367,9 @@ Parameter Type Description ============ =========== ===================================================== device_lists DeviceLists Optional. Information on e2e device updates. Note: only present on an incremental sync. +|device_otk| {string: Optional. For each key algorithm, the number of + integer} unclaimed one-time keys currently held on the server + for this device. ============ =========== ===================================================== ``DeviceLists`` @@ -388,6 +394,10 @@ Example response: "@alice:example.com", ], }, + "device_one_time_keys_count": { + "curve25519": 10, + "signed_curve25519": 20 + } } .. References @@ -400,6 +410,7 @@ Example response: .. _`Signing JSON`: ../appendices.html#signing-json .. |m.olm.v1.curve25519-aes-sha2| replace:: ``m.olm.v1.curve25519-aes-sha2`` +.. |device_otk| replace:: device_one_time_keys_count .. |/keys/upload| replace:: ``/keys/upload`` .. _/keys/upload: #post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-upload From a28f243ed7fe9b4677fc5d970ff4ae494bdc2ba8 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 15:44:17 +0200 Subject: [PATCH 063/240] document left parameter of device_lists in sync response fix #1171 --- specification/modules/end_to_end_encryption.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index b030ab64..3bcfbd2d 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -379,6 +379,8 @@ Parameter Type Description ========= ========= ============================================= changed [string] List of users who have updated their device identity keys since the previous sync response. +left [string] List of users with whom we do not share any encrypted rooms + anymore since the previous sync response. ========= ========= ============================================= @@ -393,6 +395,9 @@ Example response: "changed": [ "@alice:example.com", ], + "left": [ + "@bob:example.com", + ], }, "device_one_time_keys_count": { "curve25519": 10, From 8274f91b0b121205584bbf53878720ea9b365cc3 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 17:35:38 +0200 Subject: [PATCH 064/240] document device verification This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 3bcfbd2d..dbd6cb43 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -228,6 +228,54 @@ A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public part of a one time key once it has given that key to another user. +Device verification +------------------- + +Before Alice sends Bob encrypted data, or trusts data received from him, she +may want to verify that she is actually communicating with him, rather than a +man-in-the-middle. This verification process requires an out-of-band channel: +there is no way to do it within Matrix without trusting the administrators of +the homeservers. + +In Matrix, the basic process for device verification is for Alice to verify +that the public Ed25519 signing key she received via ``/keys/query`` for Bob's +device corresponds to the private key in use by Bob's device. For now, it is +recommended that clients provide mechanisms by which the user can see: + +1. The public part of their device's Ed25519 signing key, encoded using + `unpadded Base64`_. + +2. The list of devices in use for each user in a room, along with the public + Ed25519 signing key for each device, again encoded using unpadded Base64. + +Alice can then meet Bob in person, or contact him via some other trusted +medium, and ask him to read out the Ed25519 key shown on his device. She +compares this with the value shown for his device on her client. + +Device verification may reach one of several conclusions. For example: + +* Alice may "accept" the device. This means that she is satisfied that the + device belongs to Bob. She can then encrypt sensitive material for that + device, and knows that messages received were sent from that device. + +* Alice may "reject" the device. She will do this if she knows or suspects + that Bob does not control that device (or equivalently, does not trust + Bob). She will not send sensitive material to that device, and cannot trust + messages apparently received from it. + +* Alice may choose to skip the device verification process. She is not able + to verify that the device actually belongs to Bob, but has no reason to + suspect otherwise. The encryption protocol continues to protect against + passive eavesdroppers. + +.. NOTE:: + + Once the signing key has been verified, it is then up to the encryption + protocol to verify that a given message was sent from a device holding that + Ed25519 private key, or to encrypt a message so that it may only be + decrypted by such a device. For the Olm protocol, this is documented at + https://matrix.org/git/olm/about/docs/signing.rst. + Messaging Algorithms -------------------- From 76071bae988ff3f3dea5c7b6e7b6210f84ebe3c1 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 17:55:54 +0200 Subject: [PATCH 065/240] explain how to verify sender_key ownership --- specification/modules/end_to_end_encryption.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index dbd6cb43..078b3f99 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -360,6 +360,9 @@ The plaintext payload is of the form: "type": "", "content": "", "room_id": "", + "keys": { + "ed25519": "" + } } The type and content of the plaintext message event are given in the payload. @@ -367,10 +370,12 @@ The type and content of the plaintext message event are given in the payload. We include the room ID in the payload, because otherwise the homeserver would be able to change the room a message was sent in. -.. TODO: claimed_keys - -Clients must confirm that the ``sender_key`` belongs to the user that sent the -message. TODO: how? +Clients must confirm that the ``sender_key`` and the ``ed25519`` field value +under the ``keys`` property match the keys returned by |/keys/query|_ for +the given user, and must also verify the signature of the payload. Without +this check, a client cannot be sure that the sender device owns the private +part of the ed25519 key it claims to have in the Olm payload. +This is crucial when the ed25519 key corresponds to a verified device. ``m.megolm.v1.aes-sha2`` ~~~~~~~~~~~~~~~~~~~~~~~~ From 669605b24a2e09066ffaafc82ecb701737cfe508 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 19:53:05 +0200 Subject: [PATCH 066/240] add Olm missing properties --- specification/modules/end_to_end_encryption.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 078b3f99..50a14f72 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -360,6 +360,11 @@ The plaintext payload is of the form: "type": "", "content": "", "room_id": "", + "sender": "", + "recipient": "", + "recipient_keys": { + "ed25519": "" + }, "keys": { "ed25519": "" } @@ -370,6 +375,12 @@ The type and content of the plaintext message event are given in the payload. We include the room ID in the payload, because otherwise the homeserver would be able to change the room a message was sent in. +Other properties are included in order to prevent an attacker from publishing +someone else's curve25519 keys as their own and subsequently claiming to have +sent messages which they didn't. +``sender`` must correspond to the user who sent the event, ``recipient`` to +the local user, and ``recipient_keys`` to the local ed25519 key. + Clients must confirm that the ``sender_key`` and the ``ed25519`` field value under the ``keys`` property match the keys returned by |/keys/query|_ for the given user, and must also verify the signature of the payload. Without From 68b78dc5d8dd11233a8230dd1d34c5f4cd26b17f Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 20:56:37 +0200 Subject: [PATCH 067/240] complete Megolm documentation --- .../modules/end_to_end_encryption.rst | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 50a14f72..5ea84a3f 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -327,7 +327,7 @@ An event encrypted using Olm has the following format: "ciphertext": { "": { "type": 0, - "body": "" + "body": "" } } } @@ -398,6 +398,53 @@ ratchet, as defined by the `Megolm specification`_. This uses: * HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. * Ed25519 for message authenticity. +Devices that support Megolm must support Olm, and include "m.megolm.v1.aes-sha2" in +their list of supported messaging algorithms. + +An event encrypted using Megolm has the following format: + +.. code:: json + + { + "type": "m.room.encrypted", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "sender_key": "", + "device_id": "", + "session_id": "", + "ciphertext": "" + } + } + +The encrypted payload can contain any message event. The plaintext is of the form: + +.. code:: json + + { + "type": "", + "content": "", + "room_id": "" + } + +Clients must guard against replay attacks by keeping track of the ratchet indices +of Megolm sessions. They should reject messages with a ratchet index that they +have already decrypted. Care should be taken in order to avoid false positives, as a +client may decrypt the same event twice as part of its normal processing. + +As with Olm events, clients must confirm that the ``sender_key`` belongs to the user +who sent the message. The same reasoning applies, but the sender ed25519 key has to be +inferred from the ``keys.ed25519`` property of the event which established the Megolm +session. + +In order to enable end-to-end encryption in a room, clients can send a +``m.room.encryption`` state event specifying ``m.megolm.v1.aes-sha2`` as its +``algorithm`` property. + +When creating a Megolm session in a room, clients must share the corresponding session +key using Olm with the intended recipients, so that they can decrypt future messages +encrypted using this session. A ``m.room_key`` event is used to do this. Clients +must also handle ``m.room_key`` events sent by other devices in order to decrypt their +messages. Protocol definitions -------------------- From e5005b2d0f6ee756dab5e80df448ce6de9afcc6a Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 20:58:18 +0200 Subject: [PATCH 068/240] document E2E events This was written by Richard van der Hoff. --- event-schemas/examples/m.room.encrypted | 17 ++++++++++ event-schemas/examples/m.room.encryption | 10 ++++++ event-schemas/examples/m.room_key | 9 +++++ event-schemas/schema/m.room.encrypted | 34 +++++++++++++++++++ event-schemas/schema/m.room.encryption | 24 +++++++++++++ event-schemas/schema/m.room_key | 24 +++++++++++++ .../modules/end_to_end_encryption.rst | 12 +++++++ 7 files changed, 130 insertions(+) create mode 100644 event-schemas/examples/m.room.encrypted create mode 100644 event-schemas/examples/m.room.encryption create mode 100644 event-schemas/examples/m.room_key create mode 100644 event-schemas/schema/m.room.encrypted create mode 100644 event-schemas/schema/m.room.encryption create mode 100644 event-schemas/schema/m.room_key diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted new file mode 100644 index 00000000..a0360963 --- /dev/null +++ b/event-schemas/examples/m.room.encrypted @@ -0,0 +1,17 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg2yyOwAtHaZTwyNg37afzg8f3r9IsN9rH4RNFg7MaZencUJe4qvELiDiopUjy5wYVDAtqdBzer5bWRD9ldxp1FLgbQvBcjkkywYjCsmsq6+hArILd9oAQZnGKn/qLsK+5uNX3PaWzDRC9wZPQvWYYPCTov3jCwXKTPsLKIiTrcCXDqMvnn8m+T3zF1/I2zqxg158tnUwWWIw51UO", + "device_id": "RJYKSTBOIE", + "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" + }, + "event_id": "$WLGTSEFSEF:localhost", + "origin_server_ts": 1476648761524, + "sender": "@example:localhost", + "type": "m.room.encrypted", + "unsigned": { + "age": 158, + "transaction_id": "m1476648745605.19" + } +} diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption new file mode 100644 index 00000000..25b1271f --- /dev/null +++ b/event-schemas/examples/m.room.encryption @@ -0,0 +1,10 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2" + }, + "event_id": "$WLGTSEFJJKJ:localhost", + "origin_server_ts": 1476648761524, + "sender": "@example:localhost", + "state_key": "", + "type": "m.room.encryption" +} diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key new file mode 100644 index 00000000..2348e47d --- /dev/null +++ b/event-schemas/examples/m.room_key @@ -0,0 +1,9 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEYbf8q5V1G7D/0GHj81JbEFsaE8JOHXJCyIqUGU9svVEi52SAGiC4lpID43TAeGfYc64rUsBx5ovhZl8WrdszLxld29I+7H9e8GZt/NVd/ZQEBBfOv3vrgoODT3WpJiWZ7VEIjL6gspKkkRTDcmwYU6Eff+A11iJ2tEC9njtCeNfTrK7XUIPoXkHWmEjPwqdSQi9pqVb1OYRKT7un7WFJzo0WEw8xjo6wyEolSikaBr3/o8FhoIMIA9KvbjR4y1WDg" + }, + "type": "m.room_key" +} diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted new file mode 100644 index 00000000..cf3e4b4a --- /dev/null +++ b/event-schemas/schema/m.room.encrypted @@ -0,0 +1,34 @@ +--- +allOf: + # this is a bit of a lie; if the event is sent as a to-device event it won't + # have the room event fields. We really ought to use different event types :/ + - $ref: core-event-schema/room_event.yaml + +description: |- + This event type is used when sending encrypted events. It can be used either + within a room (in which case it will have all of the `Room Event fields`_), or + as a `to-device`_ event. + +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm used to encrypt this event. The + value of this field determines which other properties will be + present. + ciphertext: + type: + - object + - string + description: |- + Normally required. The encrypted content of the event. + required: + - algorithm + type: object + type: + enum: + - m.room.encrypted + type: string +type: object diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption new file mode 100644 index 00000000..14778efa --- /dev/null +++ b/event-schemas/schema/m.room.encryption @@ -0,0 +1,24 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: Defines how messages sent in this room should be encrypted. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm to be used to encrypt messages sent in this + room. For example, ``m.megolm.v1.aes-sha2``. + required: + - algorithm + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.encryption + type: string +type: object diff --git a/event-schemas/schema/m.room_key b/event-schemas/schema/m.room_key new file mode 100644 index 00000000..f5e4ac29 --- /dev/null +++ b/event-schemas/schema/m.room_key @@ -0,0 +1,24 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to exchange keys for end-to-end encryption. Typically + it is encrypted as an ``m.room.encrypted`` event. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm the keys in this event are to be used + with. The value of this field determines which other properties will + be present. + required: + - algorithm + type: object + type: + enum: + - m.room_key + type: string +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 5ea84a3f..c43f81c4 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -449,6 +449,18 @@ messages. Protocol definitions -------------------- +Events +~~~~~~ + +{{m_room_encryption_event}} + +{{m_room_encrypted_event}} + +{{m_room_key_event}} + +Key management API +~~~~~~~~~~~~~~~~~~ + {{keys_cs_http_api}} From 3a8d13df602bb97f1c2a580c33eda487c02f0540 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 21:25:41 +0200 Subject: [PATCH 069/240] add missing m.room.encryption properties --- event-schemas/examples/m.room.encryption | 4 +++- event-schemas/schema/m.room.encryption | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption index 25b1271f..4c6342bb 100644 --- a/event-schemas/examples/m.room.encryption +++ b/event-schemas/examples/m.room.encryption @@ -1,6 +1,8 @@ { "content": { - "algorithm": "m.megolm.v1.aes-sha2" + "algorithm": "m.megolm.v1.aes-sha2", + "rotation_period_ms": 604800000, + "rotation_period_msgs": 100 }, "event_id": "$WLGTSEFJJKJ:localhost", "origin_server_ts": 1476648761524, diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption index 14778efa..b990a13b 100644 --- a/event-schemas/schema/m.room.encryption +++ b/event-schemas/schema/m.room.encryption @@ -10,6 +10,16 @@ properties: description: |- The encryption algorithm to be used to encrypt messages sent in this room. For example, ``m.megolm.v1.aes-sha2``. + rotation_period_ms: + type: integer + description: |- + How long the session should be used before changing it. ``604800000`` + (a week) is the recommended default. + rotation_period_msgs: + type: integer + description: |- + How many messages should be sent before changing the session. ``100`` is the + recommended default. required: - algorithm type: object From c60109d235a1bba80f4ee003274484e3cbc8d781 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 31 Jul 2018 18:59:09 +0200 Subject: [PATCH 070/240] complete m.room_key documentation --- event-schemas/examples/m.room_key | 2 +- event-schemas/schema/m.room_key | 19 +++++++++++++++---- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key index 2348e47d..51249199 100644 --- a/event-schemas/examples/m.room_key +++ b/event-schemas/examples/m.room_key @@ -3,7 +3,7 @@ "algorithm": "m.megolm.v1.aes-sha2", "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEYbf8q5V1G7D/0GHj81JbEFsaE8JOHXJCyIqUGU9svVEi52SAGiC4lpID43TAeGfYc64rUsBx5ovhZl8WrdszLxld29I+7H9e8GZt/NVd/ZQEBBfOv3vrgoODT3WpJiWZ7VEIjL6gspKkkRTDcmwYU6Eff+A11iJ2tEC9njtCeNfTrK7XUIPoXkHWmEjPwqdSQi9pqVb1OYRKT7un7WFJzo0WEw8xjo6wyEolSikaBr3/o8FhoIMIA9KvbjR4y1WDg" + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." }, "type": "m.room_key" } diff --git a/event-schemas/schema/m.room_key b/event-schemas/schema/m.room_key index f5e4ac29..ef8c51c0 100644 --- a/event-schemas/schema/m.room_key +++ b/event-schemas/schema/m.room_key @@ -4,18 +4,29 @@ allOf: description: |- This event type is used to exchange keys for end-to-end encryption. Typically - it is encrypted as an ``m.room.encrypted`` event. + it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event. properties: content: properties: algorithm: type: string + enum: ["m.megolm.v1.aes-sha2"] description: |- - The encryption algorithm the keys in this event are to be used - with. The value of this field determines which other properties will - be present. + The encryption algorithm the key in this event is to be used with. + room_id: + type: string + description: The room where the key is used. + session_id: + type: string + description: The ID of the session that the key is for. + session_key: + type: string + description: The key to be exchanged. required: - algorithm + - room_id + - session_id + - session_key type: object type: enum: From 8732378da2e734dae5616e496eb932e0ffc991bc Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 22:02:53 +0200 Subject: [PATCH 071/240] add required room ids --- event-schemas/examples/m.room.encrypted | 1 + event-schemas/examples/m.room.encryption | 1 + event-schemas/examples/m.room_key | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted index a0360963..0e7e677a 100644 --- a/event-schemas/examples/m.room.encrypted +++ b/event-schemas/examples/m.room.encrypted @@ -7,6 +7,7 @@ "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" }, "event_id": "$WLGTSEFSEF:localhost", + "room_id": "!Cuyf34gef24t:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", "type": "m.room.encrypted", diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption index 4c6342bb..08f15239 100644 --- a/event-schemas/examples/m.room.encryption +++ b/event-schemas/examples/m.room.encryption @@ -7,6 +7,7 @@ "event_id": "$WLGTSEFJJKJ:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", + "room_id": "!Cuyf34gef24t:localhost", "state_key": "", "type": "m.room.encryption" } diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key index 51249199..53f83e52 100644 --- a/event-schemas/examples/m.room_key +++ b/event-schemas/examples/m.room_key @@ -1,7 +1,7 @@ { "content": { "algorithm": "m.megolm.v1.aes-sha2", - "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", + "room_id": "!Cuyf34gef24t:localhost", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." }, From 661176cb3a4c4952edd9c9bf022fabbf82bc4a1d Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 22:39:45 +0200 Subject: [PATCH 072/240] Olm m.room.encrypted example --- ...room.encrypted => m.room.encrypted#megolm} | 8 ++---- event-schemas/examples/m.room.encrypted#olm | 14 ++++++++++ event-schemas/schema/m.room.encrypted | 28 ++++++++++++++----- 3 files changed, 37 insertions(+), 13 deletions(-) rename event-schemas/examples/{m.room.encrypted => m.room.encrypted#megolm} (57%) create mode 100644 event-schemas/examples/m.room.encrypted#olm diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted#megolm similarity index 57% rename from event-schemas/examples/m.room.encrypted rename to event-schemas/examples/m.room.encrypted#megolm index 0e7e677a..1f9b7520 100644 --- a/event-schemas/examples/m.room.encrypted +++ b/event-schemas/examples/m.room.encrypted#megolm @@ -1,7 +1,7 @@ { "content": { "algorithm": "m.megolm.v1.aes-sha2", - "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg2yyOwAtHaZTwyNg37afzg8f3r9IsN9rH4RNFg7MaZencUJe4qvELiDiopUjy5wYVDAtqdBzer5bWRD9ldxp1FLgbQvBcjkkywYjCsmsq6+hArILd9oAQZnGKn/qLsK+5uNX3PaWzDRC9wZPQvWYYPCTov3jCwXKTPsLKIiTrcCXDqMvnn8m+T3zF1/I2zqxg158tnUwWWIw51UO", + "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", "device_id": "RJYKSTBOIE", "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" @@ -10,9 +10,5 @@ "room_id": "!Cuyf34gef24t:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", - "type": "m.room.encrypted", - "unsigned": { - "age": 158, - "transaction_id": "m1476648745605.19" - } + "type": "m.room.encrypted" } diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted#olm new file mode 100644 index 00000000..abb23c31 --- /dev/null +++ b/event-schemas/examples/m.room.encrypted#olm @@ -0,0 +1,14 @@ +{ + "type": "m.room.encrypted", + "sender": "@example:localhost", + "content": { + "algorithm": "m.olm.v1.curve25519-aes-sha2", + "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", + "ciphertext": { + "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { + "type": 0, + "body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..." + } + } + } +} diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index cf3e4b4a..664b10cf 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -1,8 +1,6 @@ --- allOf: - # this is a bit of a lie; if the event is sent as a to-device event it won't - # have the room event fields. We really ought to use different event types :/ - - $ref: core-event-schema/room_event.yaml + - $ref: core-event-schema/event.yaml description: |- This event type is used when sending encrypted events. It can be used either @@ -14,16 +12,32 @@ properties: properties: algorithm: type: string + enum: + - m.olm.curve25519-aes-sha256 + - m.megolm.v1.aes-sha description: |- The encryption algorithm used to encrypt this event. The value of this field determines which other properties will be present. ciphertext: - type: - - object - - string + oneOf: + - type: string + - type: object + additionalProperties: + type: object + title: CiphertextInfo + properties: + body: + type: string + description: The encrypted payload. + type: + type: integer + description: The Olm message type. description: |- - Normally required. The encrypted content of the event. + The encrypted content of the event. Either the encrypted payload + itself, in the case of a Megolm event, or a map from the recipient + Curve25519 identity key to ciphertext information, in the case of an + Olm event. For more details, see `Messaging Algorithms`_. required: - algorithm type: object From 248786681ec9d446481b2c529f587ace18d4274c Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 19 Jul 2018 19:50:05 +0200 Subject: [PATCH 073/240] fix typo --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index c43f81c4..1bc6a232 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -159,7 +159,7 @@ It is therefore expected that each client will maintain a list of devices for a number of users (in practice, typically each user with whom we share an encrypted room). Furthermore, it is likely that this list will need to be persisted between invocations of the client application (to preserve device -verification data and to alert Alice if Bob suddently gets a new +verification data and to alert Alice if Bob suddenly gets a new device). Alice's client can maintain a list of Bob's devices via the following From 4e0f107ef7207fde8bd9feafdd3bea88caad89b8 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 19 Jul 2018 19:57:47 +0200 Subject: [PATCH 074/240] document changed field behavior in e2e sync extension --- .../modules/end_to_end_encryption.rst | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1bc6a232..194d2567 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -176,9 +176,10 @@ process: flag. #. During its normal processing of responses to |/sync|_, Alice's client - inspects the |device_lists|_ field. If it is tracking the device lists of - any of the listed users, then it marks the device lists for those users - outdated, and initiates another request to |/keys/query|_ for them. + inspects the ``changed`` property of the |device_lists|_ field. If it is + tracking the device lists of any of the listed users, then it marks the + device lists for those users outdated, and initiates another request to + |/keys/query|_ for them. #. Periodically, Alice's client stores the ``next_batch`` field of the result from |/sync|_ in persistent storage. If Alice later restarts her client, it @@ -214,6 +215,18 @@ process: that the first request's results are ignored (possibly by cancelling the request). +.. Note:: + + When Bob and Alice share a room, with Bob tracking Alice's devices, she may leave + the room and then add a new device. Bob will not be notified of this change, + as he doesn't share a room anymore with Alice. When they start sharing a + room again, Bob has an out-of-date list of Alice's devices. In order to address + this issue, Bob's homeserver will add Alice's user ID to the ``changed`` property of + the ``device_lists`` field, thus Bob will update his list of Alice's devices as part + of his normal processing. Note that Bob can also be notified when he stops sharing + any room with Alice by inspecting the ``left`` property of the ``device_lists`` + field, and as a result should remove her from its list of tracked users. + .. |device_lists| replace:: ``device_lists`` .. _`device_lists`: `device_lists_sync`_ @@ -500,12 +513,20 @@ device_lists DeviceLists Optional. Information on e2e device updates. Note: ========= ========= ============================================= Parameter Type Description ========= ========= ============================================= -changed [string] List of users who have updated their device identity keys - since the previous sync response. +changed [string] List of users who have updated their device identity keys, + or who now share an encrypted room with the client since + the previous sync response. left [string] List of users with whom we do not share any encrypted rooms anymore since the previous sync response. ========= ========= ============================================= +.. NOTE:: + + For optimal performance, Alice should be added to ``changed`` in Bob's sync only + when she adds a new device, or when Alice and Bob now share a room but didn't + share any room previously. However, for the sake of simpler logic, a server + may add Alice to ``changed`` when Alice and Bob share a new room, even if they + previously already shared a room. Example response: From eb8ea0e85a9771a0d4fa0d279e6700321763de47 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 26 Jul 2018 10:44:42 +0200 Subject: [PATCH 075/240] remove warning pointing at outdated doc --- specification/modules/end_to_end_encryption.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 194d2567..213d09a5 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -21,12 +21,6 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be created whose conversation contents is not decryptable or interceptable on any of the participating homeservers. -.. WARNING:: - - End to end encryption is being worked on and will be coming soon. This - section is incomplete. You can read more about what's underway at - http://matrix.org/speculator/spec/drafts%2Fe2e/client_server/unstable.html#end-to-end-encryption. - Key Distribution ---------------- Encryption and Authentication in Matrix is based around public-key From 6c44233c42e79e5f0552f6d3288fec98be1fa146 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 26 Jul 2018 11:38:17 +0200 Subject: [PATCH 076/240] require megolm algorithm in m.room.encryption --- event-schemas/schema/m.room.encryption | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption index b990a13b..d7c4d429 100644 --- a/event-schemas/schema/m.room.encryption +++ b/event-schemas/schema/m.room.encryption @@ -7,9 +7,11 @@ properties: properties: algorithm: type: string + enum: + - "m.megolm.v1.aes-sha2" description: |- The encryption algorithm to be used to encrypt messages sent in this - room. For example, ``m.megolm.v1.aes-sha2``. + room. rotation_period_ms: type: integer description: |- From f853856f2173792d1f9307ec77a460ccde708f35 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 4 Aug 2018 14:59:09 +0200 Subject: [PATCH 077/240] add missing m.room.encrypted event properties --- event-schemas/schema/m.room.encrypted | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index 664b10cf..6825be1d 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -38,8 +38,21 @@ properties: itself, in the case of a Megolm event, or a map from the recipient Curve25519 identity key to ciphertext information, in the case of an Olm event. For more details, see `Messaging Algorithms`_. + sender_key: + type: string + description: The Curve25519 key of the sender. + device_id: + type: string + description: The ID of the sending device. Required with Megolm. + session_id: + type: string + description: |- + The ID of the session used to encrypt the message. Required with + Megolm. required: - algorithm + - sender_key + - ciphertext type: object type: enum: From b2316ba782c098a123c8f51261c56dbb5dee24bf Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 16 Aug 2018 13:00:32 +0200 Subject: [PATCH 078/240] enforce unique namespacing in new algorithms experiments --- specification/modules/end_to_end_encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 213d09a5..7dfe8993 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -292,8 +292,8 @@ Messaging Algorithm Names Messaging algorithm names use the extensible naming scheme used throughout this specification. Algorithm names that start with ``m.`` are reserved for algorithms defined by this specification. Implementations wanting to experiment -with new algorithms are encouraged to pick algorithm names that start with -their domain to reduce the risk of collisions. +with new algorithms must be uniquely globally namespaced following Java's package +naming conventions. Algorithm names should be short and meaningful, and should list the primitives used by the algorithm so that it is easier to see if the algorithm is using a From 8ba19b51ab36b0fdd62084e8798ddd58c4804e14 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 16 Aug 2018 13:04:29 +0200 Subject: [PATCH 079/240] complete Olm documentation --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 7dfe8993..b224126d 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -357,7 +357,7 @@ client must not persist a session or remove one-time keys used by a session until it has successfully decrypted a message using that session. Messages with type 1 can only be decrypted with an existing session. If there -is no matching session, the client should show this as an invalid message. +is no matching session, the client must treat this as an invalid message. The plaintext payload is of the form: From 9430f2c7f9a2b31de29ed08f8a5260706546cfe9 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Fri, 17 Aug 2018 15:12:14 +0200 Subject: [PATCH 080/240] room ID is included in Megolm plaintext, not Olm --- specification/modules/end_to_end_encryption.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index b224126d..fa461cc2 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -366,7 +366,6 @@ The plaintext payload is of the form: { "type": "", "content": "", - "room_id": "", "sender": "", "recipient": "", "recipient_keys": { @@ -379,9 +378,6 @@ The plaintext payload is of the form: The type and content of the plaintext message event are given in the payload. -We include the room ID in the payload, because otherwise the homeserver would -be able to change the room a message was sent in. - Other properties are included in order to prevent an attacker from publishing someone else's curve25519 keys as their own and subsequently claiming to have sent messages which they didn't. @@ -433,6 +429,9 @@ The encrypted payload can contain any message event. The plaintext is of the for "room_id": "" } +We include the room ID in the payload, because otherwise the homeserver would +be able to change the room a message was sent in. + Clients must guard against replay attacks by keeping track of the ratchet indices of Megolm sessions. They should reject messages with a ratchet index that they have already decrypted. Care should be taken in order to avoid false positives, as a From 98e2e8de71e27b2394762f647d699ac7af1aa17a Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 18 Aug 2018 11:40:48 +0200 Subject: [PATCH 081/240] changelog --- changelogs/client_server/newsfragments/1284.clarification | 1 + changelogs/client_server/newsfragments/1284.feature.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1284.clarification create mode 100644 changelogs/client_server/newsfragments/1284.feature.rst diff --git a/changelogs/client_server/newsfragments/1284.clarification b/changelogs/client_server/newsfragments/1284.clarification new file mode 100644 index 00000000..7bc92f47 --- /dev/null +++ b/changelogs/client_server/newsfragments/1284.clarification @@ -0,0 +1 @@ +Clarify ``changed`` field behaviour in device tracking process diff --git a/changelogs/client_server/newsfragments/1284.feature.rst b/changelogs/client_server/newsfragments/1284.feature.rst new file mode 100644 index 00000000..c658142e --- /dev/null +++ b/changelogs/client_server/newsfragments/1284.feature.rst @@ -0,0 +1,7 @@ +End-to-end encryption for group chats: + + - Olm and Megolm messaging algorithms. + - ``m.room.encrypted``, ``m.room.encryption``, ``m.room_key`` events. + - Device verification process. + - ``device_one_time_keys_count`` sync parameter. + - ``device_lists:left`` sync parameter. From 206f78cb48ba5f247a705e6d5e0bc0737c7d7e5f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 20 Aug 2018 09:21:15 +0100 Subject: [PATCH 082/240] Rename 1284.feature.rst to 1284.feature --- .../newsfragments/{1284.feature.rst => 1284.feature} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{1284.feature.rst => 1284.feature} (100%) diff --git a/changelogs/client_server/newsfragments/1284.feature.rst b/changelogs/client_server/newsfragments/1284.feature similarity index 100% rename from changelogs/client_server/newsfragments/1284.feature.rst rename to changelogs/client_server/newsfragments/1284.feature From e712466dca3370e6ca40755e3575da46a5cac87f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 10:44:28 -0600 Subject: [PATCH 083/240] Improve description for currently_active --- .../definitions/event-schemas/m.presence.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index b9c5f754..7a1dba60 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -62,10 +62,10 @@ allOf: currently_active: type: boolean description: |- - Whether or not the user is currently using a device of theirs. - For example, if the user's ``last_active_ago`` was within the - last few minutes, they may be considered ``currently_active``. - Defaults to false. + True if the user is likely to be interacting with their + client. This may be indicated by the user having a + ``last_active_ago`` within the last few minutes. Defaults + to false. example: true required: ['user_id', 'presence', 'last_active_ago'] required: ['push'] From fca1c0b7f874e079ab2321834e969833ec50d85b Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Aug 2018 18:06:26 +0100 Subject: [PATCH 084/240] Guests should support /context and /event --- specification/modules/guest_access.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/modules/guest_access.rst b/specification/modules/guest_access.rst index 4e04aa0d..d579da83 100644 --- a/specification/modules/guest_access.rst +++ b/specification/modules/guest_access.rst @@ -50,6 +50,8 @@ The following API endpoints are allowed to be accessed by guest accounts for retrieving events: * `GET /rooms/:room_id/state <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state>`_ +* `GET /rooms/:room_id/context/:event_id <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-context-eventid>`_ +* `GET /rooms/:room_id/event/:event_id <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-event-eventid>`_ * `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype-statekey>`_ * `GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_ * `GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_ From 8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 11:03:26 -0600 Subject: [PATCH 085/240] Don't try and be fancy about titles --- api/server-server/definitions/event-schemas/m.presence.yaml | 2 +- .../definitions/event-schemas/m.presence_accept.yaml | 2 +- .../definitions/event-schemas/m.presence_deny.yaml | 2 +- .../definitions/event-schemas/m.presence_invite.yaml | 2 +- api/server-server/definitions/event-schemas/m.receipt.yaml | 2 +- api/server-server/definitions/event-schemas/m.typing.yaml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.presence.yaml b/api/server-server/definitions/event-schemas/m.presence.yaml index 7a1dba60..7f47add4 100644 --- a/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/api/server-server/definitions/event-schemas/m.presence.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence`` EDU +title: m.presence description: |- An EDU representing presence updates for users of the sending homeserver. allOf: diff --git a/api/server-server/definitions/event-schemas/m.presence_accept.yaml b/api/server-server/definitions/event-schemas/m.presence_accept.yaml index 4c39989b..3ba78b47 100644 --- a/api/server-server/definitions/event-schemas/m.presence_accept.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_accept.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_accept`` EDU +title: m.presence_accept description: |- An EDU representing approval for the observing user to subscribe to the presence of the the observed user. diff --git a/api/server-server/definitions/event-schemas/m.presence_deny.yaml b/api/server-server/definitions/event-schemas/m.presence_deny.yaml index 1b9bff7d..2eb6feec 100644 --- a/api/server-server/definitions/event-schemas/m.presence_deny.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_deny.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_deny`` EDU +title: m.presence_deny description: |- An EDU representing a declination or revocation for the observing user to subscribe to the presence of the observed user. diff --git a/api/server-server/definitions/event-schemas/m.presence_invite.yaml b/api/server-server/definitions/event-schemas/m.presence_invite.yaml index 4cdc58eb..a584897b 100644 --- a/api/server-server/definitions/event-schemas/m.presence_invite.yaml +++ b/api/server-server/definitions/event-schemas/m.presence_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.presence_invite`` EDU +title: m.presence_invite description: |- An EDU representing a request to subscribe to a user's presence. allOf: diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml index 58f47e3a..7f13ebee 100644 --- a/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.receipt`` EDU +title: m.receipt description: |- An EDU representing receipt updates for users of the sending homeserver. When receiving receipts, the server should only update entries that are diff --git a/api/server-server/definitions/event-schemas/m.typing.yaml b/api/server-server/definitions/event-schemas/m.typing.yaml index 34b39529..ccbecf53 100644 --- a/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/api/server-server/definitions/event-schemas/m.typing.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: ``m.typing`` EDU +title: m.typing description: A typing notification EDU for a user in a room. allOf: - $ref: ../edu.yaml From 4ab64e11afea8ea92fab88b63c8b2d0baec46ab8 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Aug 2018 18:20:20 +0100 Subject: [PATCH 086/240] Add news frag --- changelogs/client_server/newsfragments/1542.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1542.feature diff --git a/changelogs/client_server/newsfragments/1542.feature b/changelogs/client_server/newsfragments/1542.feature new file mode 100644 index 00000000..7e94bdc5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1542.feature @@ -0,0 +1 @@ +Guests can now call /context and /event to fetch events From c8ba2e098c5ec847c6799d37fa0476ff0867dc2c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:09:17 -0600 Subject: [PATCH 087/240] Wording improvements for appservices --- api/application-service/application_service.yaml | 6 +++--- specification/application_service_api.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 64064cbd..d8f43ed6 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -33,9 +33,9 @@ paths: This API is called by the homeserver when it wants to push an event (or batch of events) to the application service. - The application service should take care to ensure that it handles - state events by the presence of a ``state_key``, not by the event - type. + 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 diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 5fe0aede..5f502969 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -224,7 +224,7 @@ need to be able to adjust the ``origin_server_ts`` value to do this. Inputs: - Application service token (``as_token``) - - Desired timestamp in milliseconds since the unix epoch + - Desired timestamp (in milliseconds since the unix epoch) Notes: - This will only apply when sending events. From 7d14309b630e91054dc3dca515c03feababb2a6a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:21:19 -0600 Subject: [PATCH 088/240] Move the power level event schema to where it was --- api/client-server/create_room.yaml | 7 +-- event-schemas/power_level_content_schema.yaml | 56 ------------------- event-schemas/schema/m.room.power_levels | 44 ++++++++++++++- 3 files changed, 46 insertions(+), 61 deletions(-) delete mode 100644 event-schemas/power_level_content_schema.yaml diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index be99c4ab..ef207f07 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -208,10 +208,9 @@ paths: title: Power Level Event Content description: |- The power level content to override in the default power level - event. This object is applied on top of the generated power - level event prior to it being sent to the room. Defaults - to overriding nothing. - $ref: "definitions/event-schemas/power_level_content_schema.yaml" + event. This object is applied on top of the generated `m.room.power_levels`_ + event content prior to it being sent to the room. Defaults to + overriding nothing. responses: 200: description: Information about the newly created room. diff --git a/event-schemas/power_level_content_schema.yaml b/event-schemas/power_level_content_schema.yaml deleted file mode 100644 index 5859d56e..00000000 --- a/event-schemas/power_level_content_schema.yaml +++ /dev/null @@ -1,56 +0,0 @@ -# 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. -properties: - ban: - description: The level required to ban a user. Defaults to 50 if unspecified. - type: number - events: - additionalProperties: - type: number - description: The level required to send specific event types. This is a mapping from event type to power level required. - title: Event power levels - type: object - events_default: - description: |- - The default level required to send message events. Can be - overridden by the ``events`` key. Defaults to 0 if unspecified. - type: number - invite: - description: The level required to invite a user. Defaults to 50 if unspecified. - type: number - kick: - description: The level required to kick a user. Defaults to 50 if unspecified. - type: number - redact: - description: The level required to redact an event. Defaults to 50 if unspecified. - type: number - state_default: - description: |- - The default level required to send state events. Can be overridden - by the ``events`` key. Defaults to 50 if unspecified, but 0 if - there is no ``m.room.power_levels`` event at all. - type: number - users: - additionalProperties: - type: number - description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. - title: User power levels - type: object - users_default: - description: |- - The default power level for every user in the room, unless their - ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if - unspecified. - type: number -type: object \ No newline at end of file diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index 174ada82..13a44c70 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -43,7 +43,49 @@ description: |- properties: content: - $ref: "../power_level_content_schema.yaml" + properties: + ban: + description: The level required to ban a user. Defaults to 50 if unspecified. + type: number + events: + additionalProperties: + type: number + description: The level required to send specific event types. This is a mapping from event type to power level required. + title: Event power levels + type: object + events_default: + description: |- + The default level required to send message events. Can be + overridden by the ``events`` key. Defaults to 0 if unspecified. + type: number + invite: + description: The level required to invite a user. Defaults to 50 if unspecified. + type: number + kick: + description: The level required to kick a user. Defaults to 50 if unspecified. + type: number + redact: + description: The level required to redact an event. Defaults to 50 if unspecified. + type: number + state_default: + description: |- + The default level required to send state events. Can be overridden + by the ``events`` key. Defaults to 50 if unspecified, but 0 if + there is no ``m.room.power_levels`` event at all. + type: number + users: + additionalProperties: + type: number + description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. + title: User power levels + type: object + users_default: + description: |- + The default power level for every user in the room, unless their + ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if + unspecified. + type: number + type: object state_key: description: A zero-length string. pattern: '^$' From 6c7a93d2f517b99cad4cf5e5dd734b3ce181d96a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:21:43 -0600 Subject: [PATCH 089/240] Move description about which preset to use when none is specified --- api/client-server/create_room.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index ef207f07..48325cf9 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -96,11 +96,6 @@ paths: ``private`` visibility if this key is not included. NB: This should not be confused with ``join_rules`` which also uses the word ``public``. - - If no ``preset`` is specificed, the server may use the visbility - to determine which preset to use. A visbility of ``public`` - equates to a preset of ``public_chat`` and ``private`` visibility - equates to a preset of ``private_chat``. room_alias_name: type: string description: |- @@ -198,6 +193,11 @@ paths: description: |- Convenience parameter for setting various default state events based on a preset. + + If unspecified, the server should use the ``visibility`` to determine + which preset to use. A visbility of ``public`` equates to a preset of + ``public_chat`` and ``private`` visibility equates to a preset of + ``private_chat``. is_direct: type: boolean description: |- From 1fd7c9946103665d9b87934b437cba45c8894287 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:21:55 -0600 Subject: [PATCH 090/240] Clarify that the creation event can have other keys in it --- api/client-server/create_room.yaml | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 48325cf9..576fc4c0 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -151,18 +151,10 @@ paths: title: CreationContent type: object description: |- - Extra keys to be added to the content of the ``m.room.create``. - The server will clobber the following keys: ``creator``. Future - versions of the specification may allow the server to clobber - other keys. - properties: - "m.federate": - type: boolean - description: |- - Whether users on other servers can join this room. Defaults - to ``true`` or what the server specifies. Setting this to - ``false`` may prevent users from being invited as part of - this room creation request if they reside on other servers. + Extra keys, such as ``m.federate``, to be added to the content + of the `m.room.create`_ event. The server will clobber the following + keys: ``creator``. Future versions of the specification may allow + the server to clobber other keys. initial_state: type: array description: |- From 7e6ca5fef8b267dc2c3e22b92172aece36ac5c07 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:23:17 -0600 Subject: [PATCH 091/240] Take out the room_alias response field The argument is that this isn't really needed at this time. --- api/client-server/create_room.yaml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 576fc4c0..cb0df80c 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -214,16 +214,10 @@ paths: type: string description: |- The created room's ID. - room_alias: - type: string - description: |- - The complete room alias for the room, if a room alias was created - for the room. required: ['room_id'] examples: application/json: { - "room_id": "!sefiuhWgwghwWgh:example.com", - "room_alias": "#thepub:example.com" + "room_id": "!sefiuhWgwghwWgh:example.com" } 400: description: |- From 8dc6f092efe90b9e5562f0bd1ac7cc196930a2ea Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:27:29 -0600 Subject: [PATCH 092/240] Define the type of the power_level_content_override field --- api/client-server/create_room.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index cb0df80c..f9aec519 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -198,6 +198,7 @@ paths: ``invite_3pid``. See `Direct Messaging`_ for more information. power_level_content_override: title: Power Level Event Content + type: object description: |- The power level content to override in the default power level event. This object is applied on top of the generated `m.room.power_levels`_ From 13a1628f59f8279d1a5889830a3514a6fec9c3a9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:34:52 -0600 Subject: [PATCH 093/240] Improve wording about how masquerading works --- specification/application_service_api.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 7119bd5a..4a29a1d8 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -185,18 +185,17 @@ homeserver. Identity assertion ++++++++++++++++++ The client-server API infers the user ID from the ``access_token`` provided in -every request. It would be an annoying amount of book-keeping to maintain tokens -for every virtual user. It would be preferable if the application service could -use the CS API with its own ``as_token`` instead, and specify the virtual user -they wish to be acting on behalf of. For real users, this would require -additional permissions granting the AS permission to masquerade as a matrix user. +every request. To avoid the application service from having to keep track of each +user's access token, the application service should identify itself to the Client-Server +API by providing its ``as_token`` instead for the ``access_token`` alongside the +user the application service would like to masquerade as. Inputs: - Application service token (``as_token``) - User ID in the AS namespace to act as. Notes: - - This will apply on all aspects of the Client-Server API, except for Account Management. + - This applies to all aspects of the Client-Server API, except for Account Management. - The ``as_token`` is inserted into ``access_token`` which is usually where the client token is, such as via the query string or ``Authorization`` header. This is done on purpose to allow application services to reuse client SDKs. From a320c58e42664bbd558f0177bce7c4fa9d1c4cef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:36:26 -0600 Subject: [PATCH 094/240] A path parameter is obviously URL encoded --- api/application-service/query_room.yaml | 2 +- api/application-service/query_user.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index 7a5a7e54..b885cb86 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -40,7 +40,7 @@ paths: - in: path name: roomAlias type: string - description: The URL encoded room alias being queried. + description: The room alias being queried. required: true x-example: "#magicforest:example.com" responses: diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 4d1e9f44..0431b5e4 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -40,7 +40,7 @@ paths: - in: path name: userId type: string - description: The URL encoded user ID being queried. + description: The user ID being queried. required: true x-example: "@alice:example.com" responses: From 5b73a0174dec6889d00aba7488ffd79df9c319dc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 14:05:23 -0600 Subject: [PATCH 095/240] Clarify what the release branch is used for, and how it should be named --- meta/releasing_a_spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index cd7033fc..078d7178 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -5,10 +5,10 @@ specification, server-server specification, and identity server specification. E of these gets released independently of each other with their own version numbers. Once a specification is ready for release, a branch should be created to track the -changes in. This should be the name of the specification (as it appears in the directory -structure of this project) followed by a forward slash and the version being released, -followed by `_updates`. For example, if the Client-Server Specification was getting -an r0.4.0 release, the branch name would be `client_server/r0.4.0_updates`. +changes in and to hold potential future hotfixes. This should be the name of the +specification (as it appears in the directory structure of this project) followed +by "release-" and the release version. For example, if the Client-Server Specification +was getting an r0.4.0 release, the branch name would be `client_server/release-r0.4.0`. *Note*: Historical releases prior to this process may or may not have an appropriate release branch. Releases after this document came into place will have an appropriate From e141f61df3a1d8305b3644ba516a1260f41744ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 14:05:48 -0600 Subject: [PATCH 096/240] Update release instructions to reference symlinks, what files to update, etc --- meta/releasing_a_spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index 078d7178..3a9da893 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -21,12 +21,13 @@ The remainder of the process is as follows: 1. Update the changelog section of the specification you're releasing to make a reference to the new version. 1. Update any version/link references across all specifications. -1. Update the index to list the version correctly. +1. Ensure the `targets.yml` file lists the version correctly. +1. Commit the changes and PR them to master. +1. Tag the release with the format `client_server/r0.4.0`. 1. Add the changes to the matrix-org/matrix.org repository (for historic tracking). * This is done by making a PR to the `unstyled_docs/spec` folder for the version and specification you're releasing. -1. Commit the changes and PR them to master. -1. Tag the release with the format `client_server/r0.4.0`. + * Don't forget to symlink the new release as `latest`. 1. Perform a release on GitHub to tag the release. 1. Yell from the mountaintop to the world about the new release. From e500e2502a176fee35315753edf0eb688456ba92 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 09:38:01 -0600 Subject: [PATCH 097/240] Document the maximum value for depth Implements the proposal for https://github.com/matrix-org/matrix-doc/issues/1230 --- api/server-server/definitions/unsigned_pdu.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml index ab281224..64991d22 100644 --- a/api/server-server/definitions/unsigned_pdu.yaml +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -78,7 +78,10 @@ properties: required: ['sha256'] depth: type: integer - description: The maximum depth of the ``prev_events``, plus one. + description: |- + The maximum depth of the ``prev_events``, plus one. Must be less than the + maximum value for an integer (2^63 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. example: 12 auth_events: type: array From 339a2748e806a8a42925afd0384521cafbd57d2d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 09:49:41 -0600 Subject: [PATCH 098/240] Take out groups for now; Move namespace mention Groups aren't landing in the spec yet, so we shouldn't include them yet. --- specification/application_service_api.rst | 31 +++++------------------ 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 9e84339f..258f80c0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -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 occurred. -An application -service can also state whether they should be the only ones who +An application service can also state whether they should be the only ones who can manage a specified namespace. This is referred to as an "exclusive" namespace. An exclusive namespace prevents humans and other application services from creating/deleting entities in that namespace. Typically, @@ -91,7 +90,6 @@ regular expressions and look like: users: - exclusive: true regex: "@_irc.freenode.net_.*" - group_id: "+irc:matrix.org" Application services may define the following namespaces (with none being explicitly required): @@ -115,22 +113,11 @@ Each individual namespace MUST declare the following fields: | regex | **Required** A regular expression defining which values this namespace includes. | +------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -An application service's users and regex field MUST begin with an underscore (``_``), in -order to provide a visually clear distinction between AS users and regular -users. An optional ``group_id`` field may be added to the ``users`` namespace: - -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Description | -+==================+============================================================================================================================================================================================================================================================================+ -| group_id | An existing group that all matching user IDs will be considered a part of. Users who are joined to this group through an application service are not to be listed when querying for the group's members, however the group should be listed when querying a user's groups. | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. WARNING:: - - Users that are matched by ``group_id`` should not be publicly listed by - Homeservers. The intention is to differentiate users, perhaps with a flair, - rather than having a list of people to spam. - +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 specification will present as YAML. See below for the possible options along @@ -174,12 +161,6 @@ An example registration file for an IRC-bridging application service is below: 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:: If the homeserver in question has multiple application services, each ``as_token`` and ``id`` MUST be unique per application service as these are From 389fa87e6e65a39b50748817d55d4c71f2f9e965 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 12:10:40 -0600 Subject: [PATCH 099/240] English --- specification/application_service_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 4a29a1d8..502472a0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -187,8 +187,8 @@ Identity assertion The client-server API infers the user ID from the ``access_token`` provided in every request. To avoid the application service from having to keep track of each user's access token, the application service should identify itself to the Client-Server -API by providing its ``as_token`` instead for the ``access_token`` alongside the -user the application service would like to masquerade as. +API by providing its ``as_token`` for the ``access_token`` alongside the user the +application service would like to masquerade as. Inputs: - Application service token (``as_token``) From 1102fc59b2dd248c5f53cb8fbf08b7577928165d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 12:13:19 -0600 Subject: [PATCH 100/240] Spelling --- specification/application_service_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 87f15b00..602aaa92 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -286,7 +286,7 @@ Using ``/sync`` and ``/events`` Application services wishing to use ``/sync`` or ``/events`` from the Client-Server API MUST do so with a virtual user (provide a ``user_id`` via the query string). It -is expectected 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``. Event fields From 2d8a321b4629859d15b938b9bf9463dfa2569604 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 31 Jul 2018 17:27:50 +0200 Subject: [PATCH 101/240] document key sharing and m.room_key_request --- .../m.room_key_request#cancel_request | 8 +++ .../examples/m.room_key_request#request | 14 +++++ event-schemas/schema/m.room_key_request | 59 +++++++++++++++++++ .../modules/end_to_end_encryption.rst | 18 ++++++ 4 files changed, 99 insertions(+) create mode 100644 event-schemas/examples/m.room_key_request#cancel_request create mode 100644 event-schemas/examples/m.room_key_request#request create mode 100644 event-schemas/schema/m.room_key_request diff --git a/event-schemas/examples/m.room_key_request#cancel_request b/event-schemas/examples/m.room_key_request#cancel_request new file mode 100644 index 00000000..c6eb25de --- /dev/null +++ b/event-schemas/examples/m.room_key_request#cancel_request @@ -0,0 +1,8 @@ +{ + "content": { + "action": "cancel_request", + "requesting_device_id": "RJYKSTBOIE", + "request_id": "1495474790150.19" + }, + "type": "m.room_key_request" +} diff --git a/event-schemas/examples/m.room_key_request#request b/event-schemas/examples/m.room_key_request#request new file mode 100644 index 00000000..8557f08e --- /dev/null +++ b/event-schemas/examples/m.room_key_request#request @@ -0,0 +1,14 @@ +{ + "content": { + "body": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU" + }, + "action": "request", + "requesting_device_id": "RJYKSTBOIE", + "request_id": "1495474790150.19" + }, + "type": "m.room_key_request" +} diff --git a/event-schemas/schema/m.room_key_request b/event-schemas/schema/m.room_key_request new file mode 100644 index 00000000..6893dd78 --- /dev/null +++ b/event-schemas/schema/m.room_key_request @@ -0,0 +1,59 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to request keys for end-to-end encryption. It is sent as an + unencrypted `to-device`_ event. +properties: + content: + properties: + body: + description: Information about the requested key. + properties: + algorithm: + type: string + description: |- + The encryption algorithm the requested key in this event is to be used + with. + room_id: + type: string + description: The room where the key is used. + sender_key: + type: string + description: |- + The Curve25519 key of the device which initiated the session originally. + session_id: + type: string + description: The ID of the session holding the key. + required: + - algorithm + - room_id + - session_id + - sender_key + type: object + title: RequestedKeyInfo + action: + enum: + - request + - cancel_request + type: string + requesting_device_id: + description: ID of the device requesting the key. + type: string + request_id: + description: |- + A random string uniquely identifying the request for a key. If the key is + requested multiple times, it should be reused. It should also reused in order + to cancel a request. + type: string + required: + - action + - requesting_device_id + - request_id + type: object + type: + enum: + - m.room_key_request + type: string +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index fa461cc2..e235e2e9 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -283,6 +283,20 @@ Device verification may reach one of several conclusions. For example: decrypted by such a device. For the Olm protocol, this is documented at https://matrix.org/git/olm/about/docs/signing.rst. +Key sharing +----------- + +If Bob has an encrypted conversation with Alice on his computer, and then logs in +through his phone for the first time, he may want to have access to the previously +exchanged messages. To address this issue, events exist for requesting and sending +keys from device to device. + +.. NOTE:: + + Key sharing can be a big attack vector, thus it must be done very carefully. + A reasonable stategy is for a user's client to only send keys requested by the + verified devices of the same user. + Messaging Algorithms -------------------- @@ -464,6 +478,10 @@ Events {{m_room_key_event}} +{{m_room_key_request_event}} + +{{m_forwarded_room_key_event}} + Key management API ~~~~~~~~~~~~~~~~~~ From 019c290fa2e4aef1e0b98aad358d5a35fef45c50 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 1 Aug 2018 00:25:31 +0200 Subject: [PATCH 102/240] document m.forwarded_room_key --- event-schemas/examples/m.forwarded_room_key | 14 +++++ event-schemas/schema/m.forwarded_room_key | 58 +++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 event-schemas/examples/m.forwarded_room_key create mode 100644 event-schemas/schema/m.forwarded_room_key diff --git a/event-schemas/examples/m.forwarded_room_key b/event-schemas/examples/m.forwarded_room_key new file mode 100644 index 00000000..8ab85c48 --- /dev/null +++ b/event-schemas/examples/m.forwarded_room_key @@ -0,0 +1,14 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ] + }, + "type": "m.room_key" +} diff --git a/event-schemas/schema/m.forwarded_room_key b/event-schemas/schema/m.forwarded_room_key new file mode 100644 index 00000000..02d91f4e --- /dev/null +++ b/event-schemas/schema/m.forwarded_room_key @@ -0,0 +1,58 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to forward keys for end-to-end encryption. Typically + it is encrypted as an ``m.room.encrypted`` event. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm the key in this event is to be used with. + room_id: + type: string + description: The room where the key is used. + sender_key: + type: string + description: |- + The Curve25519 key of the device which initiated the session originally. + session_id: + type: string + description: The ID of the session holding the key. + session_key: + type: string + description: The key to be exchanged. + sender_claimed_ed25519_key: + type: string + description: |- + The Ed25519 key of the device which initiated the session originally. + It is 'claimed' because the receiving device has no way to tell that the + original room_key actually came from a device which owns the private part of + this key unless they have done device verification. + forwarding_curve25519_key_chain: + type: array + items: + type: string + description: |- + Chain of Curve25519 keys. It starts out empty, but each time the + key is forwarded to another device, the previous sender in the chain is added + to the end of the list. For example, if the key is forwarded from A to B to + C, this field is empty between A and B, and contains A's Curve25519 key between + B and C. + required: + - algorithm + - room_id + - session_id + - session_key + - sender_claimed_ed25519_key + - forwarding_curve25519_key_chain + - sender_key + type: object + type: + enum: + - m.forwarded_room_key + type: string +type: object From 7355d23ea50820f120e73ea5d56b8ed17f7fcdd2 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 21 Aug 2018 21:53:02 +0200 Subject: [PATCH 103/240] add key sharing changelog --- changelogs/client_server/newsfragments/1465.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1465.feature diff --git a/changelogs/client_server/newsfragments/1465.feature b/changelogs/client_server/newsfragments/1465.feature new file mode 100644 index 00000000..61a7ed39 --- /dev/null +++ b/changelogs/client_server/newsfragments/1465.feature @@ -0,0 +1 @@ +Share room encryption keys between devices From 9835c98544249c65612072f1030908001e266687 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 19:27:48 -0600 Subject: [PATCH 104/240] Document how mentions (pills) work Implements the proposal over at https://github.com/matrix-org/matrix-doc/issues/1067 Includes some specification for how matrix.to is structured, and how it is intended to be replaced. --- .../appendices/identifier_grammar.rst | 32 +++++++- specification/modules/mentions.rst | 73 +++++++++++++++++++ specification/targets.yaml | 1 + 3 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 specification/modules/mentions.rst diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 7156c7d5..013afa79 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -1,5 +1,5 @@ .. Copyright 2016 Openmarket Ltd. -.. Copyright 2017 New Vector Ltd. +.. Copyright 2017, 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. @@ -252,3 +252,33 @@ domain). .. TODO-spec - Need to specify precise grammar for Room Aliases. https://matrix.org/jira/browse/SPEC-391 + +matrix.to navigation +++++++++++++++++++++ + +.. NOTE: + This namespacing is in place pending a ``matrix://`` (or similar) URI scheme. + +Rooms, users, aliases, and groups may be represented as a "matrix.to" URI. +This URI can be used to reference particular objects in a given context, such +as mentioning a user in a message or linking someone to a particular point +in the room's history (a permalink). + +A matrix.to URI has the following format, based upon the specification defined +in RFC 3986: + + https://matrix.to/#// + +The identifier may be a room ID, room alias, user ID, or group ID. The extra +parameter is only used in the case of permalinks where an event ID is referenced. +The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/`` +followed by the identifier. + +Examples of matrix.to URIs are: + +* Room: ``https://matrix.to/#/!somewhere:domain.com`` +* Room alias: ``https://matrix.to/#/#somewhere:domain.com`` +* Permalink by room: ``https://matrix.to/#/!somewhere:domain.com/$event:example.org`` +* Permalink by room alias: ``https://matrix.to/#/#somewhere:domain.com/$event:example.org`` +* User: ``https://matrix.to/#/@alice:example.org`` +* Group: ``https://matrix.to/#/+example:domain.com`` diff --git a/specification/modules/mentions.rst b/specification/modules/mentions.rst new file mode 100644 index 00000000..e7483ae4 --- /dev/null +++ b/specification/modules/mentions.rst @@ -0,0 +1,73 @@ +.. 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. + +User, room, and group mentions +============================== + +.. _module:mentions: + +This module allows users to mention other users, rooms, and groups within +a room message. This is achieved by including a `matrix.to URI`_ in the HTML +body of an `m.room.message`_ event. This module does not have any server-specific +behaviour to it. + +Mentions apply only to `m.room.message`_ events where the ``msgtype`` is ``m.text``, +``m.emote``, or ``m.notice``. The ``format`` for the event must be ``org.matrix.custom.html`` +and therefore requires a ``formatted_body``. + +To make a mention, reference the entity being mentioned in the ``formatted_body`` +using an anchor, like so:: + + { + "body": "Hello Alice!", + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "formatted_body": "Hello Alice!" + } + + +Client behaviour +---------------- + +In addition to using the appropriate ``matrix.to URI`` for the mention, +clients should use the following guidelines when making mentions: + +* When mentioning users, use the user's potentially ambigious display name for + the anchor's text. If the user does not have a display name, use the user's + ID. + +* When mentioning rooms, use the canonical alias for the room. If the room + does not have a canonical alias, prefer one of the aliases listed on the + room. If no alias can be found, fall back to the room ID. In all cases, + use the alias/room ID being linked to as the anchor's text. + +* When referencing groups, use the group ID as the anchor's text. + +The text component of the anchor should be used in the event's ``body`` where +the mention would normally be represented, as shown in the example above. + +Clients should display mentions differently from other elements. For example, +this may be done by changing the background color of the mention to indicate +that it is different from a normal link. + +If the current user is mentioned in a message (either by a mention as defined +in this module or by a push rule), the client should show that mention differently +from other mentions, such as by using a red background color to signify to the +user that they were mentioned. + +When clicked, the mention should navigate the user to the appropriate room, group, +or user information. + + +.. _`matrix.to URI`: ../appendices.html#matrix-to-navigation \ No newline at end of file diff --git a/specification/targets.yaml b/specification/targets.yaml index 5480bbc5..ced20436 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/report_content.rst - modules/third_party_networks.rst - modules/openid.rst + - modules/mentions.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] From ef41b5c2bf5acf349493279ce19851de7542d04e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 12:48:37 -0600 Subject: [PATCH 105/240] Server ACLs Implements the proposal for https://github.com/matrix-org/matrix-doc/issues/1383 --- event-schemas/examples/m.room.server_acl | 14 +++++ event-schemas/schema/m.room.server_acl | 69 ++++++++++++++++++++++++ specification/modules/server_acls.rst | 66 +++++++++++++++++++++++ specification/server_server_api.rst | 26 +++++++++ specification/targets.yaml | 1 + 5 files changed, 176 insertions(+) create mode 100644 event-schemas/examples/m.room.server_acl create mode 100644 event-schemas/schema/m.room.server_acl create mode 100644 specification/modules/server_acls.rst diff --git a/event-schemas/examples/m.room.server_acl b/event-schemas/examples/m.room.server_acl new file mode 100644 index 00000000..86da2093 --- /dev/null +++ b/event-schemas/examples/m.room.server_acl @@ -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" +} diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl new file mode 100644 index 00000000..ed64038c --- /dev/null +++ b/event-schemas/schema/m.room.server_acl @@ -0,0 +1,69 @@ +--- +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 are recommended to be + added to the denied hosts list. + + 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. + + .. 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. +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. + 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 one or more characters. + + **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 one or more characters. + + 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 diff --git a/specification/modules/server_acls.rst b/specification/modules/server_acls.rst new file mode 100644 index 00000000..72892fce --- /dev/null +++ b/specification/modules/server_acls.rst @@ -0,0 +1,66 @@ +.. 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 malicous 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. + +.. 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. + +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. \ No newline at end of file diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index dbde8b10..439b35f9 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -929,6 +929,32 @@ described in the `Client-Server API`_, being sure to use the ``allow_remote`` 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 -------------- diff --git a/specification/targets.yaml b/specification/targets.yaml index 5480bbc5..acf4b6ac 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/report_content.rst - modules/third_party_networks.rst - modules/openid.rst + - modules/server_acls.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] From 7ec3cc4343a30c41176c50bb208d57fc698663a5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:21:21 -0600 Subject: [PATCH 106/240] General improvements to the push rules module This commit does a few things: * Add 3 undocumented push rules to the spec for encrypted events and at-room notifications. * Require unrecognized conditions to not match, ensuring that future conditions do not cause clients to accidentally notify users. * Clarify that push rules should be enabled when created. * Document a new condition required for at-room notifications. Fixes https://github.com/matrix-org/matrix-doc/issues/1163 Fixes https://github.com/matrix-org/matrix-doc/issues/1034 Fixes https://github.com/matrix-org/matrix-doc/issues/676 Fixes https://github.com/matrix-org/matrix-doc/issues/1033 Relates to https://github.com/matrix-org/matrix-doc/issues/1101 --- api/client-server/pushrules.yaml | 4 +- specification/modules/push.rst | 118 ++++++++++++++++++++++++++++++- 2 files changed, 119 insertions(+), 3 deletions(-) diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index ceb9954b..e23c9189 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -343,6 +343,8 @@ paths: This endpoint allows the creation, modification and deletion of pushers for this user ID. The behaviour of this endpoint varies depending on the values in the JSON body. + + When creating push rules, they MUST be enabled by default. operationId: setPushRule security: - accessToken: [] @@ -424,7 +426,7 @@ paths: required: ["actions"] responses: 200: - description: The pusher was set. + description: The push rule was created/updated. examples: application/json: { } diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e9ee8c90..94683436 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -124,7 +124,7 @@ There are different "kinds" of push rules and each rule has an associated priority. Every push rule MUST have a ``kind`` and ``rule_id``. The ``rule_id`` is a unique string within the kind of rule and its' scope: ``rule_ids`` do not need to be unique between rules of the same kind on different devices. Rules may -have extra keys depending on the value of ``kind``.The different kinds of rule +have extra keys depending on the value of ``kind``. The different kinds of rule in descending order of priority are: Override Rules ``override`` @@ -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 ^^^^^^^^^^^^^^^^^^^^^ @@ -428,7 +463,38 @@ Definition: "value": false } ] - }, + } + +``.m.rule.encrypted_room_one_to_one`` +``````````````````````````` +Matches any encrypted event sent in a room with exactly two members. + +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 + } + ] + } ``.m.rule.room_one_to_one`` ``````````````````````````` @@ -446,6 +512,11 @@ Definition: { "kind": "room_member_count", "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.encrypted" } ], "actions": [ @@ -489,6 +560,34 @@ Definition: ] } +``.m.rule.encrypted`` +``````````````````` +Matches all encrypted events. + +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 ++++++++++ @@ -523,6 +622,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 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``: The notification power level to require the sender to have. 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 a specific + 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 ~~~~~~~~~~~~~~~ From ab0be0457199e65d115ed3eb6fd46ba94f591d1a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:24:53 -0600 Subject: [PATCH 107/240] Fix titles --- specification/modules/push.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 94683436..408eabe6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -370,7 +370,7 @@ 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. @@ -466,7 +466,7 @@ Definition: } ``.m.rule.encrypted_room_one_to_one`` -``````````````````````````` +````````````````````````````````````` Matches any encrypted event sent in a room with exactly two members. Definition: @@ -561,7 +561,7 @@ Definition: } ``.m.rule.encrypted`` -``````````````````` +````````````````````` Matches all encrypted events. Definition: From bce324818b8e1a41e1ee313f6944ca3e03d27d40 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:26:27 -0600 Subject: [PATCH 108/240] Changelog --- changelogs/client_server/newsfragments/1551.clarification | 1 + changelogs/client_server/newsfragments/1551.feature | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1551.clarification create mode 100644 changelogs/client_server/newsfragments/1551.feature diff --git a/changelogs/client_server/newsfragments/1551.clarification b/changelogs/client_server/newsfragments/1551.clarification new file mode 100644 index 00000000..06eac4da --- /dev/null +++ b/changelogs/client_server/newsfragments/1551.clarification @@ -0,0 +1 @@ +Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match. diff --git a/changelogs/client_server/newsfragments/1551.feature b/changelogs/client_server/newsfragments/1551.feature new file mode 100644 index 00000000..dfce0f0a --- /dev/null +++ b/changelogs/client_server/newsfragments/1551.feature @@ -0,0 +1 @@ +Add new push rules for encrypted events and ``@room`` notifications. From a95d7092eb3bf4e02cbd1aabc31548462d6376c2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:27:48 -0600 Subject: [PATCH 109/240] Changelog --- changelogs/client_server/newsfragments/1550.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1550.feature diff --git a/changelogs/client_server/newsfragments/1550.feature b/changelogs/client_server/newsfragments/1550.feature new file mode 100644 index 00000000..f04fa9ae --- /dev/null +++ b/changelogs/client_server/newsfragments/1550.feature @@ -0,0 +1 @@ +Add server ACLs as an option for controlling federation in a room. From dc94820450bcbd907e99bbae99e7c5b1df5380d5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:28:55 -0600 Subject: [PATCH 110/240] Changelog --- changelogs/client_server/newsfragments/1547.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1547.feature diff --git a/changelogs/client_server/newsfragments/1547.feature b/changelogs/client_server/newsfragments/1547.feature new file mode 100644 index 00000000..76346f23 --- /dev/null +++ b/changelogs/client_server/newsfragments/1547.feature @@ -0,0 +1 @@ +Add a common standard for user, room, and group mentions in messages. From bbd33c146131939790e6939e881bfd46b971bd62 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 23 Aug 2018 13:29:04 -0600 Subject: [PATCH 111/240] Move appservice transaction API to the right section Part of https://github.com/matrix-org/matrix-doc/issues/1532 --- .../application_service.yaml | 70 ------------- api/application-service/transactions.yaml | 98 +++++++++++++++++++ specification/application_service_api.rst | 2 + 3 files changed, 100 insertions(+), 70 deletions(-) create mode 100644 api/application-service/transactions.yaml diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index bc6e45d5..8fcfa006 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -26,76 +26,6 @@ consumes: 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": [ - { - "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}": get: summary: Retrieve metadata about a specific protocol that the application service supports. diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml new file mode 100644 index 00000000..9388d3c5 --- /dev/null +++ b/api/application-service/transactions.yaml @@ -0,0 +1,98 @@ +# 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: "/" +consumes: + - application/json +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": [ + { + "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 \ No newline at end of file diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 08e3b062..09e38e91 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -155,6 +155,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 on retries, as the AS may have already processed the events. +{{transactions_as_http_api}} + Querying ++++++++ From 6a91ea9c85a597f0ac89fce9e99f57be4be388da Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 23 Aug 2018 13:31:33 -0600 Subject: [PATCH 112/240] Specify that application services receive events in the CSAPI format Fixes https://github.com/matrix-org/matrix-doc/issues/1269 This is also supposed to fix the 'age' problem, however that is a larger problem with the event schemas that is reserved for a future PR/commit. Reference: https://github.com/matrix-org/matrix-doc/issues/1294 Reference: https://github.com/matrix-org/matrix-doc/issues/1524 --- api/application-service/transactions.yaml | 38 +++++------------------ 1 file changed, 7 insertions(+), 31 deletions(-) diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml index 9388d3c5..8735cc8f 100644 --- a/api/application-service/transactions.yaml +++ b/api/application-service/transactions.yaml @@ -21,8 +21,6 @@ schemes: - https - http basePath: "/" -consumes: - - application/json produces: - application/json paths: @@ -53,37 +51,16 @@ paths: 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" - } + {"$ref": "../../event-schemas/examples/m.room.member"}, + {"$ref": "../../event-schemas/examples/m.room.message#m.text"} ] } - description: "Transaction informations" + description: Transaction information properties: events: type: array - description: A list of events + description: |- + A list of events, formatted as per the Client-Server API. items: type: object title: Event @@ -92,7 +69,6 @@ paths: 200: description: The transaction was processed successfully. examples: - application/json: { - } + application/json: {} schema: - type: object \ No newline at end of file + type: object From 9eda1a697143249a03da6bbf02674263f74e5929 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 23 Aug 2018 15:07:55 -0600 Subject: [PATCH 113/240] Move the third party network API to it's own section --- .../application_service.yaml | 240 ---------------- api/application-service/protocols.yaml | 267 ++++++++++++++++++ specification/application_service_api.rst | 20 ++ 3 files changed, 287 insertions(+), 240 deletions(-) create mode 100644 api/application-service/protocols.yaml diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index bc6e45d5..8a32c95b 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -96,243 +96,3 @@ paths: } schema: type: object - "/_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: Retreive 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: |- - Retreive 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: |- - Retreive 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 diff --git a/api/application-service/protocols.yaml b/api/application-service/protocols.yaml new file mode 100644 index 00000000..376e66c0 --- /dev/null +++ b/api/application-service/protocols.yaml @@ -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: Retreive 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: |- + Retreive 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: |- + Retreive 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 diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 08e3b062..c5f8be72 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -180,6 +180,26 @@ this request (e.g. to join a room alias). {{query_room_as_http_api}} +Third party networks +++++++++++++++++++++ + +Application services may declare which protocols they support via their registration +file. 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. + +Each protocol may have several "locations". 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. + +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}} + + HTTP APIs +++++++++ From 2d43ff123400a54f087a30179af7cb5077ab8cf5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 10:22:10 -0600 Subject: [PATCH 114/240] Update third party network schemas Some information was missed when this was reviewed. This commit adds some additional documentation for how these objects interact with each other. --- .../definitions/location.yaml | 8 +- .../definitions/protocol.yaml | 88 +++++++++++++------ .../definitions/protocol_metadata.yaml | 2 + api/application-service/definitions/user.yaml | 6 +- 4 files changed, 72 insertions(+), 32 deletions(-) diff --git a/api/application-service/definitions/location.yaml b/api/application-service/definitions/location.yaml index 4967ef61..5a0f92c8 100644 --- a/api/application-service/definitions/location.yaml +++ b/api/application-service/definitions/location.yaml @@ -19,12 +19,14 @@ properties: protocol: description: The protocol ID that the third party location is a part of. type: string - example: irc + example: "irc" fields: description: Information used to identify this third party location. type: object - example: - "network": "freenode" + example: { + "network": "freenode", "channel": "#matrix" + } +required: ['alias', 'protocol', 'fields'] title: Location type: object \ No newline at end of file diff --git a/api/application-service/definitions/protocol.yaml b/api/application-service/definitions/protocol.yaml index 231e8288..851091d6 100644 --- a/api/application-service/definitions/protocol.yaml +++ b/api/application-service/definitions/protocol.yaml @@ -11,41 +11,60 @@ # 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. +title: Protocol +type: object properties: 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 items: type: string description: Field used to identify a third party user. example: ["network", "nickname"] 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 items: type: string description: Field used to identify a third party location. example: ["network", "channel"] icon: - description: An icon representing the third party protocol. + description: A content URI representing an icon for the third party protocol. type: string example: "mxc://example.org/aBcDeFgH" 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 - properties: - fieldname: - title: Field Type - description: Definition of valid values for a field. - type: object - properties: - regexp: - description: A regular expression for validation of a field's value. - type: string - placeholder: - description: An placeholder serving as a valid example of the field value. - type: string + additionalProperties: + title: Field Type + description: Definition of valid values for a field. + type: object + properties: + regexp: + 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 + placeholder: + description: An placeholder serving as a valid example of the field value. + type: string + required: ['regexp', 'placeholder'] + required: ['fieldname'] example: { "network": { "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", @@ -63,17 +82,32 @@ properties: instances: description: |- A list of objects representing independent instances of configuration. - For instance multiple networks on IRC if multiple are bridged by the - same bridge. + For example, multiple networks on IRC if multiple are provided by the + same application service. type: array items: type: object - example: { - "desc": "Freenode", - "icon": "mxc://example.org/JkLmNoPq", - "fields": { - "network": "freenode.net", - } - } -title: Protocol -type: object \ No newline at end of file + 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: { + "network": "freenode" + } + network_id: + type: string + description: A unique identifier across all instances. + example: "freenode" + required: ['desc', 'fields', 'network_id'] +required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances'] diff --git a/api/application-service/definitions/protocol_metadata.yaml b/api/application-service/definitions/protocol_metadata.yaml index 2b2c8f4e..e7bf45da 100644 --- a/api/application-service/definitions/protocol_metadata.yaml +++ b/api/application-service/definitions/protocol_metadata.yaml @@ -36,6 +36,7 @@ example: { }, "instances": [ { + "network_id": "freenode", "desc": "Freenode", "icon": "mxc://example.org/JkLmNoPq", "fields": { @@ -59,6 +60,7 @@ example: { }, "instances": [ { + "network_id": "gitter", "desc": "Gitter", "icon": "mxc://example.org/zXyWvUt", "fields": {} diff --git a/api/application-service/definitions/user.yaml b/api/application-service/definitions/user.yaml index a7b2287e..258e7c13 100644 --- a/api/application-service/definitions/user.yaml +++ b/api/application-service/definitions/user.yaml @@ -21,11 +21,13 @@ properties: protocol: description: The protocol ID that the third party location is a part of. type: string - example: gitter + example: "gitter" fields: description: Information used to identify this third party location. type: object - example: + example: { "user": "jim" + } +required: ['userid', 'protocol', 'fields'] title: User type: object \ No newline at end of file From 017d6db7370f87b5b72e9ce19d6f8962462ab525 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 11:07:30 -0600 Subject: [PATCH 115/240] Document third party network/protocol directories (for appservices) Fixes https://github.com/matrix-org/matrix-doc/issues/869 --- .../appservice_room_directory.yaml | 87 +++++++++++++++++++ api/client-server/list_public_rooms.yaml | 20 ++++- api/server-server/public_rooms.yaml | 14 +++ specification/application_service_api.rst | 12 +++ 4 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 api/client-server/appservice_room_directory.yaml diff --git a/api/client-server/appservice_room_directory.yaml b/api/client-server/appservice_room_directory.yaml new file mode 100644 index 00000000..0225ecd8 --- /dev/null +++ b/api/client-server/appservice_room_directory.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 diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 72a12060..d1abc68e 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -194,8 +194,26 @@ paths: description: |- A string to search for in the room metadata, e.g. name, 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: { - "limit": 10, "filter": {"generic_search_term": "foo"}} + "limit": 10, + "filter": { + "generic_search_term": "foo" + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } responses: 200: description: A list of the rooms on the server. diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml index d162568f..b7691023 100644 --- a/api/server-server/public_rooms.yaml +++ b/api/server-server/public_rooms.yaml @@ -49,6 +49,20 @@ paths: A pagination token from a previous call to this endpoint to fetch more rooms. 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: 200: description: The public room list for the homeserver. diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index c5f8be72..9d467e87 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -218,6 +218,9 @@ Application services can use a more powerful version of the client-server API by identifying itself as an application service to the homeserver. +Endpoints defined in this section MUST be supported by homeservers in the +client-server API as accessible only by application services. + Identity assertion ++++++++++++++++++ The client-server API infers the user ID from the ``access_token`` provided in @@ -314,6 +317,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 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 ~~~~~~~~~~~~ From 9b19fc27def683ec1f64014aa1686096cf7ee716 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 11:09:55 -0600 Subject: [PATCH 116/240] changelog --- changelogs/client_server/newsfragments/1554.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1554.feature diff --git a/changelogs/client_server/newsfragments/1554.feature b/changelogs/client_server/newsfragments/1554.feature new file mode 100644 index 00000000..ec7ffe71 --- /dev/null +++ b/changelogs/client_server/newsfragments/1554.feature @@ -0,0 +1 @@ +Add third party network room directories, as provided by application services. From 811998735cf2af6ea12ee27427b929ffa3491d93 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 15:51:23 -0600 Subject: [PATCH 117/240] Define common error codes in the Identity Service API Fixes https://github.com/matrix-org/matrix-doc/issues/1407 --- specification/identity_service_api.rst | 69 ++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 3b037caf..fb08f637 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -56,6 +56,75 @@ is left as an exercise for the client. 3PID types are described in `3PID Types`_ Appendix. +API Standards +------------- + +The mandatory baseline for identity service communication in Matrix is exchanging +JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls +use a Content-Type of ``application/json``. In addition, strings MUST be encoded as +UTF-8. + +Any errors which occur at the Matrix API level MUST return a "standard error response". +This is a JSON object which looks like: + +.. code:: json + + { + "errcode": "", + "error": "" + } + +The ``error`` string will be a human-readable error message, usually a sentence +explaining what went wrong. The ``errcode`` string will be a unique string +which can be used to handle an error message e.g. ``M_FORBIDDEN``. There may be +additional keys depending on the error, but the keys ``error`` and ``errcode`` +MUST always be present. + +Some standard error codes are below: + +:``M_NOT_FOUND``: + The resource requested could not be located. + +:``M_MISSING_PARAMS``: + The request was missing one or more parameters. + +:``M_INVALID_PARAM``: + The request contained one or more invalid parameters. + +:``M_SESSION_NOT_VALIDATED``: + The session has not been validated. + +:``M_NO_VALID_SESSION``: + A session could not be located for the given parameters. + +:``M_SESSION_EXPIRED``: + The session has expired and must be renewed. + +:``M_INVALID_EMAIL``: + The email address provided was not valid. + +:``M_EMAIL_SEND_ERROR``: + There was an error sending an email. Typically seen when attempting to verify + ownership of a given email address. + +:``M_INVALID_ADDRESS``: + The provided third party address was not valid. + +:``M_SEND_ERROR``: + There was an error sending a notification. Typically seen when attempting to + verify ownership of a given third party address. + +:``M_UNRECOGNIZED``: + The request contained an unrecognised value, such as an unknown token or medium. + +:``M_THREEPID_IN_USE``: + The third party identifier is already in use by another user. Typically this + error will have an additional ``mxid`` property to indicate who owns the + third party identifier. + +:``M_UNKNOWN``: + An unknown error has occurred. + Privacy ------- From 4abd618147618abc73502f1bd84ee55da5b139e5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 15:53:00 -0600 Subject: [PATCH 118/240] Flag response fields in the Identity Service spec as required --- api/identity/associations.yaml | 9 +++++++++ api/identity/email_associations.yaml | 2 ++ api/identity/invitation_signing.yaml | 1 + api/identity/lookup.yaml | 8 ++++++++ api/identity/phone_associations.yaml | 2 ++ api/identity/pubkey.yaml | 2 ++ api/identity/store_invite.yaml | 1 + 7 files changed, 25 insertions(+) diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 784bb5d6..6d282e8d 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -62,6 +62,7 @@ paths: validated_at: type: integer description: Timestamp indicating the time that the 3pid was validated. + required: ['medium', 'address', 'validated_at'] 400: description: |- The session has not been validated. @@ -158,6 +159,14 @@ paths: signatures: type: object description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures 400: description: |- The association was not published. diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 8431c9e8..c9fb0cd7 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -93,6 +93,7 @@ paths: sid: type: string description: The session ID. + required: ['sid'] 400: description: | An error ocurred. Some possible errors are: @@ -151,6 +152,7 @@ paths: success: type: boolean description: Whether the validation was successful or not. + required: ['success'] get: summary: Validate ownership of an email address. description: |- diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 982dbff7..c595299f 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -71,6 +71,7 @@ paths: token: type: string description: The token for the invitation. + required: ['mxid', 'sender', 'signatures', 'token'] examples: application/json: { "mxid": "@foo:bar.com", diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index bfd2153e..3bc58be5 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -86,6 +86,14 @@ paths: signatures: type: object description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures "/bulk_lookup": post: summary: Lookup Matrix user IDs for a list of 3pids. diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index c2cc6cfe..605dadcc 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -99,6 +99,7 @@ paths: sid: type: string description: The session ID. + required: ['sid'] 400: description: | An error ocurred. Some possible errors are: @@ -157,6 +158,7 @@ paths: success: type: boolean description: Whether the validation was successful or not. + required: ['success'] get: summary: Validate ownership of a phone number. description: |- diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 00796975..45f8b99a 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -80,6 +80,7 @@ paths: valid: type: boolean description: Whether the public key is recognised and is currently valid. + required: ['valid'] "/pubkey/ephemeral/isvalid": get: summary: Check whether a short-term public key is valid. @@ -108,3 +109,4 @@ paths: valid: type: boolean description: Whether the public key is recognised and is currently valid. + required: ['valid'] diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 6b847b5b..d6fae7a7 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -90,6 +90,7 @@ paths: display_name: type: string description: The generated (redacted) display_name. + required: ['token', 'public_keys', 'display_name'] example: application/json: { "token": "sometoken", From dafea96621d6383f6b44d9368024bb95c8ab94a7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 15:53:27 -0600 Subject: [PATCH 119/240] Fix indentation and schema references in the identity service spec --- api/identity/associations.yaml | 69 +++++++++++++++----------- api/identity/email_associations.yaml | 31 +++++++----- api/identity/invitation_signing.yaml | 6 ++- api/identity/lookup.yaml | 35 +++++++------ api/identity/phone_associations.yaml | 33 +++++++----- api/identity/pubkey.yaml | 20 ++++++-- api/identity/store_invite.yaml | 34 +++++++------ schemas/server-signatures.yaml | 24 +++++++++ specification/identity_service_api.rst | 2 +- 9 files changed, 162 insertions(+), 92 deletions(-) create mode 100644 schemas/server-signatures.yaml diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 6d282e8d..4225919b 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -46,10 +46,10 @@ paths: description: Validation information for the session. examples: application/json: { - "medium": "email", - "validated_at": 1457622739026, - "address": "louise@bobs.burgers" - } + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } schema: type: object properties: @@ -72,16 +72,20 @@ paths: ``errcode`` will be ``M_SESSION_EXPIRED``. examples: application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" 404: description: The Session ID or client secret were not found examples: application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" "/bind": post: summary: Publish an association between a session and a Matrix user ID. @@ -102,10 +106,10 @@ paths: schema: type: object example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:matrix.org" - } + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } properties: sid: type: string @@ -122,19 +126,19 @@ paths: description: The association was published. examples: application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" } } + } schema: type: object properties: @@ -159,6 +163,7 @@ paths: signatures: type: object description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + $ref: "../../schemas/server-signatures.yaml" required: - address - medium @@ -176,13 +181,17 @@ paths: ``errcode`` will be ``M_SESSION_EXPIRED``. examples: application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" 404: description: The Session ID or client secret were not found examples: application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index c9fb0cd7..28f5e680 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -51,10 +51,10 @@ paths: schema: type: object example: { - "client_secret": "monkeys_are_GREAT", - "email": "foo@example.com", - "send_attempt": 1 - } + "client_secret": "monkeys_are_GREAT", + "email": "foo@example.com", + "send_attempt": 1 + } properties: client_secret: type: string @@ -85,8 +85,8 @@ paths: Session created. examples: application/json: { - "sid": "1234" - } + "sid": "1234" + } schema: type: object properties: @@ -100,6 +100,13 @@ paths: - ``M_INVALID_EMAIL``: The email address provided was invalid. - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. + examples: + application/json: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" "/validate/email/submitToken": post: summary: Validate ownership of an email address. @@ -123,10 +130,10 @@ paths: schema: type: object example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } properties: sid: type: string @@ -144,8 +151,8 @@ paths: The success of the validation. examples: application/json: { - "success": true - } + "success": true + } schema: type: object properties: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index c595299f..7de62dd4 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -68,6 +68,7 @@ paths: signatures: type: object description: The signature of the mxid, sender, and token. + $ref: "../../schemas/server-signatures.yaml" token: type: string description: The token for the invitation. @@ -85,7 +86,10 @@ paths: } 404: description: Token was not found. - example: { + examples: + application/json: { "errcode": "M_UNRECOGNIZED", "error": "Didn't recognize token" } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 3bc58be5..6f993ac7 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -49,19 +49,18 @@ paths: The association for that 3pid, or the empty object if no association is known. examples: application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, - - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" } } + } schema: type: object properties: @@ -86,6 +85,7 @@ paths: signatures: type: object description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + $ref: "../../schemas/server-signatures.yaml" required: - address - medium @@ -118,9 +118,11 @@ paths: items: type: array title: 3PID mappings + minItems: 2 + maxItems: 2 items: - type: string - title: 3PID medium or address + - type: 3PID Medium + - type: 3PID Address description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position. required: - "threepids" @@ -142,9 +144,12 @@ paths: items: type: array title: 3PID mappings + minItems: 3 + maxItems: 3 items: - type: string - title: 3PID medium or address or the Matrix ID + - type: 3PID Medium + - type: 3PID Address + - type: Matrix User ID description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. required: - "threepids" diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index 605dadcc..f6b1bd45 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -51,11 +51,11 @@ paths: schema: type: object example: { - "client_secret": "monkeys_are_GREAT", - "country": "GB", - "phone_number": "07700900001", - "send_attempt": 1 - } + "client_secret": "monkeys_are_GREAT", + "country": "GB", + "phone_number": "07700900001", + "send_attempt": 1 + } properties: client_secret: type: string @@ -91,8 +91,8 @@ paths: Session created. examples: application/json: { - "sid": "1234" - } + "sid": "1234" + } schema: type: object properties: @@ -106,6 +106,13 @@ paths: - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - ``M_SEND_ERROR``: The validation SMS could not be sent. + examples: + application/json: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" "/validate/msisdn/submitToken": post: summary: Validate ownership of a phone number. @@ -129,10 +136,10 @@ paths: schema: type: object example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } properties: sid: type: string @@ -150,8 +157,8 @@ paths: The success of the validation. examples: application/json: { - "success": true - } + "success": true + } schema: type: object properties: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 45f8b99a..9cb7c74e 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -45,13 +45,25 @@ paths: The public key exists. examples: application/json: { - "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - } + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } schema: type: object properties: public_key: type: string + description: Unpadded Base64 encoded public key. + required: ['public_key'] + 404: + description: + The public key was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" "/pubkey/isvalid": get: summary: Check whether a long-term public key is valid. @@ -72,8 +84,8 @@ paths: The validity of the public key. examples: application/json: { - "valid": true - } + "valid": true + } schema: type: object properties: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index d6fae7a7..1eca7198 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -54,11 +54,11 @@ paths: schema: type: object example: { - "medium": "email", - "address": "foo@bar.baz", - "room_id": "!something:example.tld", - "sender": "@bob:example.com" - } + "medium": "email", + "address": "foo@bar.baz", + "room_id": "!something:example.tld", + "sender": "@bob:example.com" + } properties: medium: type: string @@ -93,13 +93,13 @@ paths: required: ['token', 'public_keys', 'display_name'] example: application/json: { - "token": "sometoken", - "public_keys": [ - "serverpublickey", - "ephemeralpublickey" - ], - "display_name": "f...@b..." - } + "token": "sometoken", + "public_keys": [ + "serverpublickey", + "ephemeralpublickey" + ], + "display_name": "f...@b..." + } 400: description: | An error has occured. @@ -109,7 +109,9 @@ paths: error code will be ``M_UNRECOGNIZED``. examples: application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Binding already known", - "mxid": mxid - } + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": mxid + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/schemas/server-signatures.yaml b/schemas/server-signatures.yaml new file mode 100644 index 00000000..a1855256 --- /dev/null +++ b/schemas/server-signatures.yaml @@ -0,0 +1,24 @@ +# 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. +type: object +example: { + "example.com": { + "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } +} +additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string \ No newline at end of file diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index fb08f637..7bbd8ae8 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -23,7 +23,7 @@ user identifiers. From time to time, it is useful to refer to users by other number. This identity service specification describes how mappings between third-party identifiers and Matrix user identifiers can be established, validated, and used. This description technically may apply to any 3pid, but in -practice has only been applied specifically to email addresses. +practice has only been applied specifically to email addresses and phone numbers. .. contents:: Table of Contents .. sectnum:: From d370a2c6fd0dd91ca43227c91ceeb1c02ad0bccb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 17:11:40 -0600 Subject: [PATCH 120/240] Prepare the identity service and server-server APIs for r0 * Create the changelog scaffolding * Set up the variables for versioning --- api/identity/associations.yaml | 2 +- api/identity/email_associations.yaml | 2 +- api/identity/invitation_signing.yaml | 2 +- api/identity/lookup.yaml | 2 +- api/identity/phone_associations.yaml | 2 +- api/identity/ping.yaml | 2 +- api/identity/pubkey.yaml | 2 +- api/identity/store_invite.yaml | 4 +-- api/server-server/backfill.yaml | 2 +- api/server-server/event_auth.yaml | 2 +- api/server-server/events.yaml | 2 +- api/server-server/invites.yaml | 2 +- api/server-server/joins.yaml | 2 +- api/server-server/keys_query.yaml | 2 +- api/server-server/keys_server.yaml | 2 +- api/server-server/leaving.yaml | 2 +- api/server-server/openid.yaml | 2 +- api/server-server/public_rooms.yaml | 2 +- api/server-server/query.yaml | 2 +- api/server-server/third_party_invite.yaml | 2 +- api/server-server/transactions.yaml | 2 +- api/server-server/version.yaml | 2 +- changelogs/identity_service.rst | 0 .../identity_service/newsfragments/.gitignore | 1 + changelogs/identity_service/pyproject.toml | 30 +++++++++++++++++ changelogs/server_server.rst | 0 .../server_server/newsfragments/.gitignore | 1 + changelogs/server_server/pyproject.toml | 30 +++++++++++++++++ scripts/gendoc.py | 15 ++++++--- .../templating/matrix_templates/sections.py | 8 +++++ scripts/templating/matrix_templates/units.py | 3 +- specification/identity_service_api.rst | 20 ++++++++++-- specification/server_server_api.rst | 32 +++++++++++++------ 33 files changed, 146 insertions(+), 40 deletions(-) create mode 100644 changelogs/identity_service.rst create mode 100644 changelogs/identity_service/newsfragments/.gitignore create mode 100644 changelogs/identity_service/pyproject.toml create mode 100644 changelogs/server_server.rst create mode 100644 changelogs/server_server/newsfragments/.gitignore create mode 100644 changelogs/server_server/pyproject.toml diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 784bb5d6..59185c83 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 8431c9e8..9649f6ef 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 982dbff7..bc06b89a 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index bfd2153e..1dc79d85 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -21,7 +21,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index c2cc6cfe..6d30ee3d 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index 005160a3..b630c733 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -23,7 +23,7 @@ basePath: /_matrix/identity produces: - application/json paths: - "/api/v1": + "/api/%IDENTITY_MAJOR_VERSION%": get: summary: Checks that an Identity server is available at this API endpopint. description: |- diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 00796975..3884b63a 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 6b847b5b..c4056acb 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% produces: - application/json paths: @@ -46,7 +46,7 @@ paths: ``address`` parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on - requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + requests to ``/_matrix/identity/api/%IDENTITY_MAJOR_VERSION%/pubkey/ephemeral/isvalid``. operationId: storeInvite parameters: - in: body diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index 6b3cfaef..5c88f554 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index 8857131f..0248fb1e 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index cf3988a2..0b318373 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% produces: - application/json securityDefinitions: diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml index 6d905e17..d55ccb5b 100644 --- a/api/server-server/invites.yaml +++ b/api/server-server/invites.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 4902ea9e..66a071e5 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/keys_query.yaml b/api/server-server/keys_query.yaml index e616915b..face2bd6 100644 --- a/api/server-server/keys_query.yaml +++ b/api/server-server/keys_query.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/key/v2 +basePath: /_matrix/key/%KEYS_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml index 8734f2ed..d09ba8e2 100644 --- a/api/server-server/keys_server.yaml +++ b/api/server-server/keys_server.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/key/v2 +basePath: /_matrix/key/%KEYS_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index be08acba..739f4962 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/openid.yaml b/api/server-server/openid.yaml index 0eac48c8..942a5d5e 100644 --- a/api/server-server/openid.yaml +++ b/api/server-server/openid.yaml @@ -20,7 +20,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% produces: - application/json paths: diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml index d162568f..be9428a4 100644 --- a/api/server-server/public_rooms.yaml +++ b/api/server-server/public_rooms.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% produces: - application/json securityDefinitions: diff --git a/api/server-server/query.yaml b/api/server-server/query.yaml index dc14724c..af70a9c3 100644 --- a/api/server-server/query.yaml +++ b/api/server-server/query.yaml @@ -20,7 +20,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% produces: - application/json securityDefinitions: diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 5c12247c..9e3bba2c 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 8d810ad5..bb6254e7 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% consumes: - application/json produces: diff --git a/api/server-server/version.yaml b/api/server-server/version.yaml index 19975529..17110f19 100644 --- a/api/server-server/version.yaml +++ b/api/server-server/version.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1 +basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% produces: - application/json paths: diff --git a/changelogs/identity_service.rst b/changelogs/identity_service.rst new file mode 100644 index 00000000..e69de29b diff --git a/changelogs/identity_service/newsfragments/.gitignore b/changelogs/identity_service/newsfragments/.gitignore new file mode 100644 index 00000000..b722e9e1 --- /dev/null +++ b/changelogs/identity_service/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelogs/identity_service/pyproject.toml b/changelogs/identity_service/pyproject.toml new file mode 100644 index 00000000..7a64eb0b --- /dev/null +++ b/changelogs/identity_service/pyproject.toml @@ -0,0 +1,30 @@ +[tool.towncrier] + filename = "../identity_service.rst" + directory = "newsfragments" + issue_format = "`#{issue} `_" + title_format = "{version}" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "new" + name = "New Endpoints" + showcontent = true + + [[tool.towncrier.type]] + directory = "feature" + name = "Backwards Compatible Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "clarification" + name = "Spec Clarifications" + showcontent = true diff --git a/changelogs/server_server.rst b/changelogs/server_server.rst new file mode 100644 index 00000000..e69de29b diff --git a/changelogs/server_server/newsfragments/.gitignore b/changelogs/server_server/newsfragments/.gitignore new file mode 100644 index 00000000..b722e9e1 --- /dev/null +++ b/changelogs/server_server/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelogs/server_server/pyproject.toml b/changelogs/server_server/pyproject.toml new file mode 100644 index 00000000..98478527 --- /dev/null +++ b/changelogs/server_server/pyproject.toml @@ -0,0 +1,30 @@ +[tool.towncrier] + filename = "../server_server.rst" + directory = "newsfragments" + issue_format = "`#{issue} `_" + title_format = "{version}" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "new" + name = "New Endpoints" + showcontent = true + + [[tool.towncrier.type]] + directory = "feature" + name = "Backwards Compatible Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "clarification" + name = "Spec Clarifications" + showcontent = true diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 16c40af5..e2f788cc 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -518,6 +518,10 @@ if __name__ == '__main__': "--server_release", "-s", action="store", default="unstable", help="The server-server release tag to generate, e.g. r1.2" ) + parser.add_argument( + "--identity_release", "-i", action="store", default="unstable", + help="The identity service release tag to generate, e.g. r1.2" + ) parser.add_argument( "--list_targets", action="store_true", help="Do not update the specification. Instead print a list of targets.", @@ -536,12 +540,15 @@ if __name__ == '__main__': substitutions = { "%CLIENT_RELEASE_LABEL%": args.client_release, - # we hardcode a major version of r0. This ends up in the - # example API URLs. When we have released a new major version, - # we'll have to bump it. + # we hardcode the major versions. This ends up in the example + # API URLs. When we have released a new major version, we'll + # have to bump them. "%CLIENT_MAJOR_VERSION%": "r0", + "%SERVER_MAJOR_VERSION%": "v1", + "%IDENTITY_MAJOR_VERSION%": "v1", + "%KEYS_MAJOR_VERSION%": "v2", "%SERVER_RELEASE_LABEL%": args.server_release, - "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), + "%IDENTITY_RELEASE_LABEL%": args.identity_release, } exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions)) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 1a93c723..7c982f80 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -32,6 +32,14 @@ class MatrixSections(Sections): changelogs = self.units.get("changelogs") return changelogs["client_server"] + def render_identity_service_changelog(self): + changelogs = self.units.get("changelogs") + return changelogs["identity_service"] + + def render_server_server_changelog(self): + changelogs = self.units.get("changelogs") + return changelogs["server_server"] + def _render_events(self, filterFn, sortFn): template = self.env.get_template("events.tmpl") examples = self.units.get("event_examples") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..ed8943e0 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -754,6 +754,7 @@ class MatrixUnits(Units): def load_apis(self, substitutions): cs_ver = substitutions.get("%CLIENT_RELEASE_LABEL%", "unstable") fed_ver = substitutions.get("%SERVER_RELEASE_LABEL%", "unstable") + is_ver = substitutions.get("%IDENTITY_RELEASE_LABEL%", "unstable") # we abuse the typetable to return this info to the templates return TypeTable(rows=[ @@ -770,7 +771,7 @@ class MatrixUnits(Units): "unstable", "Privileged server plugins", ), TypeTableRow( - "`Identity Service API `_", + "`Identity Service API `_", "unstable", "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 3b037caf..49d68834 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -28,13 +28,27 @@ practice has only been applied specifically to email addresses. .. contents:: Table of Contents .. sectnum:: -Specification version ---------------------- +Changelog +--------- + +.. topic:: Version: %IDENTITY_RELEASE_LABEL% +{{identity_service_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. +For the full historical changelog, see +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst + + +Other versions of this specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following other versions are also available, in reverse chronological order: + +- `HEAD `_: Includes all changes since the latest versioned release. + General principles ------------------ @@ -138,7 +152,7 @@ associated with a Matrix user ID. At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below:: - POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind + POST https://bar.com:8448/_matrix/federation/%SERVER_MAJOR_VERSION%/3pid/onbind Content-Type: application/json { diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index dbde8b10..ccebc313 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -64,13 +64,27 @@ request. .. contents:: Table of Contents .. sectnum:: -Specification version ---------------------- +Changelog +--------- + +.. topic:: Version: %SERVER_RELEASE_LABEL% +{{server_server_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. +For the full historical changelog, see +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/server_server.rst + + +Other versions of this specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following other versions are also available, in reverse chronological order: + +- `HEAD `_: Includes all changes since the latest versioned release. + Server Discovery ---------------- @@ -118,11 +132,11 @@ Retrieving Server Keys specification due to lack of significance. It may be reviewed `here `_. -Each homeserver publishes its public keys under ``/_matrix/key/v2/server/{keyId}``. -Homeservers query for keys by either getting ``/_matrix/key/v2/server/{keyId}`` +Each homeserver publishes its public keys under ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}``. +Homeservers query for keys by either getting ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` directly or by querying an intermediate notary server using a -``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers -query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and +``/_matrix/key/%KEYS_MAJOR_VERSION%/query/{serverName}/{keyId}`` API. Intermediate notary servers +query the ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys. @@ -138,7 +152,7 @@ Publishing Keys +++++++++++++++ Homeservers publish the allowed TLS fingerprints and signing keys in a JSON -object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of +object at ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{key_id}``. The response contains a list of ``verify_keys`` that are valid for signing federation requests made by the homeserver and for signing events. It contains a list of ``old_verify_keys`` which are only valid for signing events. Finally the response contains a list of TLS @@ -152,7 +166,7 @@ Querying Keys Through Another Server Servers may query another server's keys through a notary server. The notary server may be another homeserver. The notary server will retrieve keys from -the queried servers through use of the ``/_matrix/key/v2/server/{keyId}`` +the queried servers through use of the ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` API. The notary server will additionally sign the response from the queried server before returning the results. @@ -1073,7 +1087,7 @@ that are too long. known hash functions like SHA-256 when none of the keys have been redacted]] .. |/query/directory| replace:: ``/query/directory`` -.. _/query/directory: #get-matrix-federation-v1-query-directory +.. _/query/directory: #get-matrix-federation-%SERVER_MAJOR_VERSION%-query-directory .. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage .. _`Identity Service API`: ../identity_service/unstable.html From 0f28f8327021c43632678d4d54f5753c7cd021ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 17:59:48 -0600 Subject: [PATCH 121/240] Fix client-server event schemas: remove `age`, dedupe fields This commit adds support for event schema examples to have references to help reduce the chance of fields being forgotten. This also helps reduce duplication of fields, allowing for a more consistent spec that uses the same values everywhere. This also removes both `unsigned` and `age` from the examples as per: * https://github.com/matrix-org/matrix-doc/issues/1524 * https://github.com/matrix-org/matrix-doc/issues/630 Finally, this replaces "localhost" in the examples with an example domain. This is really just a nitpick thing on my part where seeing a "real world" domain is preferred. Fixes https://github.com/matrix-org/matrix-doc/issues/1524 Fixes https://github.com/matrix-org/matrix-doc/issues/630 Step towards https://github.com/matrix-org/matrix-doc/issues/1530 --- event-schemas/examples/core/event.json | 6 ++++++ event-schemas/examples/core/room_edu.json | 4 ++++ event-schemas/examples/core/room_event.json | 7 +++++++ event-schemas/examples/core/state_event.json | 4 ++++ event-schemas/examples/m.call.answer | 10 +++------- event-schemas/examples/m.call.candidates | 10 +++------- event-schemas/examples/m.call.hangup | 10 +++------- event-schemas/examples/m.call.invite | 10 +++------- event-schemas/examples/m.direct | 7 ++++--- event-schemas/examples/m.ignored_user_list | 1 + event-schemas/examples/m.presence | 7 ++++--- event-schemas/examples/m.receipt | 18 +++++++++--------- event-schemas/examples/m.room.aliases | 14 +++++--------- event-schemas/examples/m.room.avatar | 14 +++++--------- event-schemas/examples/m.room.canonical_alias | 12 ++++-------- event-schemas/examples/m.room.create | 16 +++++++--------- event-schemas/examples/m.room.encrypted#megolm | 9 +++------ event-schemas/examples/m.room.encrypted#olm | 2 +- event-schemas/examples/m.room.encryption | 11 ++++------- event-schemas/examples/m.room.guest_access | 12 ++++-------- .../examples/m.room.history_visibility | 12 ++++-------- event-schemas/examples/m.room.join_rules | 12 ++++-------- event-schemas/examples/m.room.member | 14 +++++--------- .../examples/m.room.member#invite_room_state | 12 +++--------- .../examples/m.room.member#third_party_invite | 14 ++++---------- event-schemas/examples/m.room.message#m.audio | 12 ++++-------- event-schemas/examples/m.room.message#m.emote | 10 +++------- event-schemas/examples/m.room.message#m.file | 12 ++++-------- event-schemas/examples/m.room.message#m.image | 12 ++++-------- .../examples/m.room.message#m.location | 12 ++++-------- event-schemas/examples/m.room.message#m.notice | 10 +++------- event-schemas/examples/m.room.message#m.text | 10 +++------- event-schemas/examples/m.room.message#m.video | 14 +++++--------- event-schemas/examples/m.room.message.feedback | 10 +++------- event-schemas/examples/m.room.name | 12 ++++-------- event-schemas/examples/m.room.pinned_events | 14 +++++--------- event-schemas/examples/m.room.power_levels | 12 ++++-------- event-schemas/examples/m.room.redaction | 14 ++++---------- .../examples/m.room.third_party_invite | 12 ++++-------- event-schemas/examples/m.room.topic | 12 ++++-------- event-schemas/examples/m.room_key | 5 +++-- event-schemas/examples/m.sticker | 10 +++------- event-schemas/examples/m.tag | 1 + event-schemas/examples/m.typing | 10 +++++----- scripts/templating/matrix_templates/units.py | 2 +- 45 files changed, 175 insertions(+), 279 deletions(-) create mode 100644 event-schemas/examples/core/event.json create mode 100644 event-schemas/examples/core/room_edu.json create mode 100644 event-schemas/examples/core/room_event.json create mode 100644 event-schemas/examples/core/state_event.json diff --git a/event-schemas/examples/core/event.json b/event-schemas/examples/core/event.json new file mode 100644 index 00000000..8a469a5c --- /dev/null +++ b/event-schemas/examples/core/event.json @@ -0,0 +1,6 @@ +{ + "content": { + "key": "value" + }, + "type": "org.example.custom.event" +} diff --git a/event-schemas/examples/core/room_edu.json b/event-schemas/examples/core/room_edu.json new file mode 100644 index 00000000..80575f5d --- /dev/null +++ b/event-schemas/examples/core/room_edu.json @@ -0,0 +1,4 @@ +{ + "$ref": "event.json", + "room_id": "!jEsUZKDJdhlrceRyVU:domain.com" +} diff --git a/event-schemas/examples/core/room_event.json b/event-schemas/examples/core/room_event.json new file mode 100644 index 00000000..fe9ff7ee --- /dev/null +++ b/event-schemas/examples/core/room_event.json @@ -0,0 +1,7 @@ +{ + "$ref": "event.json", + "event_id": "$143273582443PhrSn:domain.com", + "room_id": "!jEsUZKDJdhlrceRyVU:domain.com", + "sender": "@example:domain.com", + "origin_server_ts": 1432735824653 +} diff --git a/event-schemas/examples/core/state_event.json b/event-schemas/examples/core/state_event.json new file mode 100644 index 00000000..910747ee --- /dev/null +++ b/event-schemas/examples/core/state_event.json @@ -0,0 +1,4 @@ +{ + "$ref": "room_event.json", + "state_key": "ArbitraryString" +} diff --git a/event-schemas/examples/m.call.answer b/event-schemas/examples/m.call.answer index f7d14439..a4cfc1e1 100644 --- a/event-schemas/examples/m.call.answer +++ b/event-schemas/examples/m.call.answer @@ -1,5 +1,6 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.call.answer", "content": { "version" : 0, "call_id": "12345", @@ -8,10 +9,5 @@ "type" : "answer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.call.answer", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.call.candidates b/event-schemas/examples/m.call.candidates index 8e6849bb..8f1f807a 100644 --- a/event-schemas/examples/m.call.candidates +++ b/event-schemas/examples/m.call.candidates @@ -1,5 +1,6 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.call.candidates", "content": { "version" : 0, "call_id": "12345", @@ -10,10 +11,5 @@ "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0" } ] - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.call.candidates", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.call.hangup b/event-schemas/examples/m.call.hangup index 42e1f346..295f16e4 100644 --- a/event-schemas/examples/m.call.hangup +++ b/event-schemas/examples/m.call.hangup @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.call.hangup", "content": { "version" : 0, "call_id": "12345" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.call.hangup", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.call.invite b/event-schemas/examples/m.call.invite index 974a5b4c..fa482bd9 100644 --- a/event-schemas/examples/m.call.invite +++ b/event-schemas/examples/m.call.invite @@ -1,5 +1,6 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.call.invite", "content": { "version" : 0, "call_id": "12345", @@ -8,10 +9,5 @@ "type" : "offer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.call.invite", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.direct b/event-schemas/examples/m.direct index 92f13daa..e453dd59 100644 --- a/event-schemas/examples/m.direct +++ b/event-schemas/examples/m.direct @@ -1,9 +1,10 @@ { + "$ref": "core/event.json", "type": "m.direct", "content": { "@bob:example.com": [ - "!abcdefgh:example.com", - "!hgfedcba:example.com" - ] + "!abcdefgh:example.com", + "!hgfedcba:example.com" + ] } } diff --git a/event-schemas/examples/m.ignored_user_list b/event-schemas/examples/m.ignored_user_list index f3a328f7..9963d13a 100644 --- a/event-schemas/examples/m.ignored_user_list +++ b/event-schemas/examples/m.ignored_user_list @@ -1,4 +1,5 @@ { + "$ref": "core/event.json", "type": "m.ignored_user_list", "content": { "ignored_users": { diff --git a/event-schemas/examples/m.presence b/event-schemas/examples/m.presence index 824ffcb7..36093cd9 100644 --- a/event-schemas/examples/m.presence +++ b/event-schemas/examples/m.presence @@ -1,10 +1,11 @@ { + "$ref": "core/event.json", + "sender": "@example:localhost", + "type": "m.presence", "content": { "avatar_url": "mxc://localhost:wefuiwegh8742w", "last_active_ago": 2478593, "presence": "online", "currently_active": false - }, - "sender": "@example:localhost", - "type": "m.presence" + } } diff --git a/event-schemas/examples/m.receipt b/event-schemas/examples/m.receipt index bd0b726c..c52d8540 100644 --- a/event-schemas/examples/m.receipt +++ b/event-schemas/examples/m.receipt @@ -1,13 +1,13 @@ { - "type": "m.receipt", - "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org", - "content": { - "$1435641916114394fHBLK:matrix.org": { - "m.read": { - "@rikj:jki.re": { - "ts": 1436451550453 - } - } + "$ref": "core/room_edu.json", + "type": "m.receipt", + "content": { + "$1435641916114394fHBLK:matrix.org": { + "m.read": { + "@rikj:jki.re": { + "ts": 1436451550453 } + } } + } } diff --git a/event-schemas/examples/m.room.aliases b/event-schemas/examples/m.room.aliases index ca87510e..bb2fe21c 100644 --- a/event-schemas/examples/m.room.aliases +++ b/event-schemas/examples/m.room.aliases @@ -1,12 +1,8 @@ { - "age": 242352, - "content": { - "aliases": ["#somewhere:localhost", "#another:localhost"] - }, - "state_key": "localhost", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", + "$ref": "core/state_event.json", + "state_key": "domain.com", "type": "m.room.aliases", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + "content": { + "aliases": ["#somewhere:domain.com", "#another:domain.com"] + } } diff --git a/event-schemas/examples/m.room.avatar b/event-schemas/examples/m.room.avatar index 2080d96e..9b51e01f 100644 --- a/event-schemas/examples/m.room.avatar +++ b/event-schemas/examples/m.room.avatar @@ -1,5 +1,7 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.avatar", + "state_key": "", "content": { "info": { "h": 398, @@ -7,12 +9,6 @@ "mimetype": "image/jpeg", "size": 31037 }, - "url": "mxc://localhost/JWEIFJgwEIhweiWJE" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.avatar", - "state_key": "", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + "url": "mxc://domain.com/JWEIFJgwEIhweiWJE" + } } diff --git a/event-schemas/examples/m.room.canonical_alias b/event-schemas/examples/m.room.canonical_alias index 59df586d..06c3226c 100644 --- a/event-schemas/examples/m.room.canonical_alias +++ b/event-schemas/examples/m.room.canonical_alias @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.canonical_alias", + "state_key": "", "content": { "alias": "#somewhere:localhost" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.canonical_alias", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.create b/event-schemas/examples/m.room.create index 34dabb53..18127497 100644 --- a/event-schemas/examples/m.room.create +++ b/event-schemas/examples/m.room.create @@ -1,12 +1,10 @@ { - "age": 242352, - "content": { - "creator": "@example:localhost" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", + "$ref": "core/state_event.json", "type": "m.room.create", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + "state_key": "", + "content": { + "creator": "@example:domain.com", + "room_version": "1", + "m.federate": true + } } diff --git a/event-schemas/examples/m.room.encrypted#megolm b/event-schemas/examples/m.room.encrypted#megolm index 1f9b7520..ac542e25 100644 --- a/event-schemas/examples/m.room.encrypted#megolm +++ b/event-schemas/examples/m.room.encrypted#megolm @@ -1,14 +1,11 @@ { + "$ref": "core/room_event.json", + "type": "m.room.encrypted", "content": { "algorithm": "m.megolm.v1.aes-sha2", "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", "device_id": "RJYKSTBOIE", "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" - }, - "event_id": "$WLGTSEFSEF:localhost", - "room_id": "!Cuyf34gef24t:localhost", - "origin_server_ts": 1476648761524, - "sender": "@example:localhost", - "type": "m.room.encrypted" + } } diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted#olm index abb23c31..381651d9 100644 --- a/event-schemas/examples/m.room.encrypted#olm +++ b/event-schemas/examples/m.room.encrypted#olm @@ -1,6 +1,6 @@ { + "$ref": "core/room_event.json", "type": "m.room.encrypted", - "sender": "@example:localhost", "content": { "algorithm": "m.olm.v1.curve25519-aes-sha2", "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption index 08f15239..6158b937 100644 --- a/event-schemas/examples/m.room.encryption +++ b/event-schemas/examples/m.room.encryption @@ -1,13 +1,10 @@ { + "$ref": "core/state_event.json", + "type": "m.room.encryption", + "state_key": "", "content": { "algorithm": "m.megolm.v1.aes-sha2", "rotation_period_ms": 604800000, "rotation_period_msgs": 100 - }, - "event_id": "$WLGTSEFJJKJ:localhost", - "origin_server_ts": 1476648761524, - "sender": "@example:localhost", - "room_id": "!Cuyf34gef24t:localhost", - "state_key": "", - "type": "m.room.encryption" + } } diff --git a/event-schemas/examples/m.room.guest_access b/event-schemas/examples/m.room.guest_access index c636ff39..a6deff8c 100644 --- a/event-schemas/examples/m.room.guest_access +++ b/event-schemas/examples/m.room.guest_access @@ -1,12 +1,8 @@ { - "age": 242353, + "$ref": "core/state_event.json", + "type": "m.room.guest_access", + "state_key": "", "content": { "guest_access": "can_join" - }, - "state_key": "", - "origin_server_ts": 1431961217938, - "event_id": "$WLGTSEFSEG:localhost", - "type": "m.room.guest_access", - "room_id": "!Cuyf34gef24u:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.history_visibility b/event-schemas/examples/m.room.history_visibility index 6fedc5dc..27c4fec3 100644 --- a/event-schemas/examples/m.room.history_visibility +++ b/event-schemas/examples/m.room.history_visibility @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.history_visibility", + "state_key": "", "content": { "history_visibility": "shared" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.history_visibility", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.join_rules b/event-schemas/examples/m.room.join_rules index 39e14fc5..2873be78 100644 --- a/event-schemas/examples/m.room.join_rules +++ b/event-schemas/examples/m.room.join_rules @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.join_rules", + "state_key": "", "content": { "join_rule": "public" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.join_rules", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.member b/event-schemas/examples/m.room.member index 2495145b..ce31ab8f 100644 --- a/event-schemas/examples/m.room.member +++ b/event-schemas/examples/m.room.member @@ -1,14 +1,10 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "state_key": "@alice:domain.com", + "type": "m.room.member", "content": { "membership": "join", - "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto", "displayname": "Alice Margatroid" - }, - "state_key": "@alice:localhost", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.member", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index 1a93b395..54d71ca7 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -1,8 +1,8 @@ { - "age": 242352, + "$ref": "m.room.member", "content": { "membership": "invite", - "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto", "displayname": "Alice Margatroid" }, "invite_room_state": [ @@ -20,11 +20,5 @@ "join_rule": "invite" } } - ], - "state_key": "@alice:localhost", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.member", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + ] } diff --git a/event-schemas/examples/m.room.member#third_party_invite b/event-schemas/examples/m.room.member#third_party_invite index 244e1556..92b5d2ef 100644 --- a/event-schemas/examples/m.room.member#third_party_invite +++ b/event-schemas/examples/m.room.member#third_party_invite @@ -1,13 +1,13 @@ { - "age": 242352, + "$ref": "m.room.member", "content": { "membership": "invite", - "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto", "displayname": "Alice Margatroid", "third_party_invite": { "display_name": "alice", "signed": { - "mxid": "@alice:localhost", + "mxid": "@alice:domain.com", "signatures": { "magic.forest": { "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" @@ -16,11 +16,5 @@ "token": "abc123" } } - }, - "state_key": "@alice:localhost", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.member", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.audio b/event-schemas/examples/m.room.message#m.audio index 367eb954..4ce5a2a8 100644 --- a/event-schemas/examples/m.room.message#m.audio +++ b/event-schemas/examples/m.room.message#m.audio @@ -1,18 +1,14 @@ { - "age": 146, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "Bee Gees - Stayin' Alive", - "url": "mxc://localhost/ffed755USFFxlgbQYZGtryd", + "url": "mxc://domain.com/ffed755USFFxlgbQYZGtryd", "info": { "duration": 2140786, "size": 1563685, "mimetype": "audio/mpeg" }, "msgtype": "m.audio" - }, - "event_id": "$143273582443PhrSn:localhost", - "origin_server_ts": 1432735824653, - "room_id": "!jEsUZKDJdhlrceRyVU:localhost", - "type": "m.room.message", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.emote b/event-schemas/examples/m.room.message#m.emote index 79292ddf..5fecb9a3 100644 --- a/event-schemas/examples/m.room.message#m.emote +++ b/event-schemas/examples/m.room.message#m.emote @@ -1,14 +1,10 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "thinks this is an example emote", "msgtype": "m.emote", "format": "org.matrix.custom.html", "formatted_body": "thinks this is an example emote" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.message", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.file b/event-schemas/examples/m.room.message#m.file index e52c3a94..b518550a 100644 --- a/event-schemas/examples/m.room.message#m.file +++ b/event-schemas/examples/m.room.message#m.file @@ -1,5 +1,6 @@ { - "age": 146, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "something-important.doc", "filename": "something-important.doc", @@ -8,11 +9,6 @@ "size": 46144 }, "msgtype": "m.file", - "url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe" - }, - "event_id": "$143273582443PhrSn:localhost", - "origin_server_ts": 1432735824653, - "room_id": "!jEsUZKDJdhlrceRyVU:localhost", - "type": "m.room.message", - "sender": "@example:localhost" + "url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe" + } } diff --git a/event-schemas/examples/m.room.message#m.image b/event-schemas/examples/m.room.message#m.image index 91e72be2..60402eff 100644 --- a/event-schemas/examples/m.room.message#m.image +++ b/event-schemas/examples/m.room.message#m.image @@ -1,5 +1,6 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "filename.jpg", "info": { @@ -8,12 +9,7 @@ "mimetype": "image/jpeg", "size": 31037 }, - "url": "mxc://localhost/JWEIFJgwEIhweiWJE", + "url": "mxc://domain.com/JWEIFJgwEIhweiWJE", "msgtype": "m.image" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.message", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.location b/event-schemas/examples/m.room.message#m.location index 75363f6f..1461a305 100644 --- a/event-schemas/examples/m.room.message#m.location +++ b/event-schemas/examples/m.room.message#m.location @@ -1,10 +1,11 @@ { - "age": 146, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "Big Ben, London, UK", "geo_uri": "geo:51.5008,0.1247", "info": { - "thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe", + "thumbnail_url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe", "thumbnail_info": { "mimetype": "image/jpeg", "size": 46144, @@ -13,10 +14,5 @@ } }, "msgtype": "m.location" - }, - "event_id": "$143273582443PhrSn:localhost", - "origin_server_ts": 1432735824653, - "room_id": "!jEsUZKDJdhlrceRyVU:localhost", - "type": "m.room.message", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.notice b/event-schemas/examples/m.room.message#m.notice index 978c67e6..78e9dea6 100644 --- a/event-schemas/examples/m.room.message#m.notice +++ b/event-schemas/examples/m.room.message#m.notice @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "This is an example notice", "msgtype": "m.notice" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.message", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.text b/event-schemas/examples/m.room.message#m.text index 48a97db8..ba1fb769 100644 --- a/event-schemas/examples/m.room.message#m.text +++ b/event-schemas/examples/m.room.message#m.text @@ -1,14 +1,10 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.message", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message#m.video b/event-schemas/examples/m.room.message#m.video index 576d80de..304fbfbd 100644 --- a/event-schemas/examples/m.room.message#m.video +++ b/event-schemas/examples/m.room.message#m.video @@ -1,10 +1,11 @@ { - "age": 146, + "$ref": "core/room_event.json", + "type": "m.room.message", "content": { "body": "Gangnam Style", - "url": "mxc://localhost/a526eYUSFFxlgbQYZmo442", + "url": "mxc://domain.com/a526eYUSFFxlgbQYZmo442", "info": { - "thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe", + "thumbnail_url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe", "thumbnail_info": { "mimetype": "image/jpeg", "size": 46144, @@ -18,10 +19,5 @@ "mimetype": "video/mp4" }, "msgtype": "m.video" - }, - "event_id": "$143273582443PhrSn:localhost", - "origin_server_ts": 1432735824653, - "room_id": "!jEsUZKDJdhlrceRyVU:localhost", - "type": "m.room.message", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.message.feedback b/event-schemas/examples/m.room.message.feedback index 16fe0ee0..e146e874 100644 --- a/event-schemas/examples/m.room.message.feedback +++ b/event-schemas/examples/m.room.message.feedback @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.room.message.feedback", "content": { "type": "delivered", "target_event_id": "$WEIGFHFW:localhost" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.message.feedback", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.name b/event-schemas/examples/m.room.name index 87db2008..e77e2b53 100644 --- a/event-schemas/examples/m.room.name +++ b/event-schemas/examples/m.room.name @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.name", + "state_key": "", "content": { "name": "The room name" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.name", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.pinned_events b/event-schemas/examples/m.room.pinned_events index 6f41e97d..10d71a8d 100644 --- a/event-schemas/examples/m.room.pinned_events +++ b/event-schemas/examples/m.room.pinned_events @@ -1,12 +1,8 @@ { - "age": 242352, - "content": { - "pinned": ["$someevent:localhost"] - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", + "$ref": "core/state_event.json", "type": "m.room.pinned_events", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + "state_key": "", + "content": { + "pinned": ["$someevent:domain.com"] + } } diff --git a/event-schemas/examples/m.room.power_levels b/event-schemas/examples/m.room.power_levels index 0c8f8bc5..37c27845 100644 --- a/event-schemas/examples/m.room.power_levels +++ b/event-schemas/examples/m.room.power_levels @@ -1,5 +1,7 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.power_levels", + "state_key": "", "content": { "ban": 50, "events": { @@ -15,11 +17,5 @@ "@example:localhost": 100 }, "users_default": 0 - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.power_levels", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.redaction b/event-schemas/examples/m.room.redaction index e24a8cdb..42bc8411 100644 --- a/event-schemas/examples/m.room.redaction +++ b/event-schemas/examples/m.room.redaction @@ -1,14 +1,8 @@ { - "unsigned": { - "age": 242352 - }, - "content": { - "reason": "Spamming" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", + "$ref": "core/room_event.json", "type": "m.room.redaction", - "room_id": "!Cuyf34gef24t:localhost", "redacts": "$fukweghifu23:localhost", - "sender": "@example:localhost" + "content": { + "reason": "Spamming" + } } diff --git a/event-schemas/examples/m.room.third_party_invite b/event-schemas/examples/m.room.third_party_invite index 3f9d48fe..03f35375 100644 --- a/event-schemas/examples/m.room.third_party_invite +++ b/event-schemas/examples/m.room.third_party_invite @@ -1,5 +1,7 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.third_party_invite", + "state_key": "pc98", "content": { "display_name": "Alice Margatroid", "key_validity_url": "https://magic.forest/verifykey", @@ -8,11 +10,5 @@ "public_key": "def456", "key_validity_url": "https://magic.forest/verifykey" }] - }, - "state_key": "pc98", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.third_party_invite", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room.topic b/event-schemas/examples/m.room.topic index 65daa987..69e5d4f1 100644 --- a/event-schemas/examples/m.room.topic +++ b/event-schemas/examples/m.room.topic @@ -1,12 +1,8 @@ { - "age": 242352, + "$ref": "core/state_event.json", + "type": "m.room.topic", + "state_key": "", "content": { "topic": "A room topic" - }, - "state_key": "", - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.room.topic", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key index 53f83e52..dba497b4 100644 --- a/event-schemas/examples/m.room_key +++ b/event-schemas/examples/m.room_key @@ -1,9 +1,10 @@ { + "$ref": "core/event.json", + "type": "m.room_key", "content": { "algorithm": "m.megolm.v1.aes-sha2", "room_id": "!Cuyf34gef24t:localhost", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." - }, - "type": "m.room_key" + } } diff --git a/event-schemas/examples/m.sticker b/event-schemas/examples/m.sticker index f00e5b23..971cdc90 100644 --- a/event-schemas/examples/m.sticker +++ b/event-schemas/examples/m.sticker @@ -1,5 +1,6 @@ { - "age": 242352, + "$ref": "core/room_event.json", + "type": "m.sticker", "content": { "body": "Landing", "info": { @@ -16,10 +17,5 @@ "size": 73602 }, "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP" - }, - "origin_server_ts": 1431961217939, - "event_id": "$WLGTSEFSEF:localhost", - "type": "m.sticker", - "room_id": "!Cuyf34gef24t:localhost", - "sender": "@example:localhost" + } } diff --git a/event-schemas/examples/m.tag b/event-schemas/examples/m.tag index 53dbc921..0d61d91b 100644 --- a/event-schemas/examples/m.tag +++ b/event-schemas/examples/m.tag @@ -1,4 +1,5 @@ { + "$ref": "core/event.json", "type": "m.tag", "content": { "tags": { diff --git a/event-schemas/examples/m.typing b/event-schemas/examples/m.typing index 1d2c517b..416b9968 100644 --- a/event-schemas/examples/m.typing +++ b/event-schemas/examples/m.typing @@ -1,7 +1,7 @@ { - "type": "m.typing", - "room_id": "!z0mnsuiwhifuhwwfw:matrix.org", - "content": { - "user_ids": ["@alice:matrix.org", "@bob:example.com"] - } + "$ref": "core/room_edu.json", + "type": "m.typing", + "content": { + "user_ids": ["@alice:matrix.org", "@bob:example.com"] + } } diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..9a6f3569 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -792,7 +792,7 @@ class MatrixUnits(Units): logger.info("Reading event example: %s" % filepath) try: with open(filepath, "r") as f: - example = json.load(f) + example = resolve_references(filepath, json.load(f)) examples[filename] = examples.get(filename, []) examples[filename].append(example) if filename != event_name: From 06d43aef173cf4f821c459d04e2d8885bbdfd714 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 18:08:05 -0600 Subject: [PATCH 122/240] Changelog --- changelogs/client_server/newsfragments/1558.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1558.clarification diff --git a/changelogs/client_server/newsfragments/1558.clarification b/changelogs/client_server/newsfragments/1558.clarification new file mode 100644 index 00000000..3482d89c --- /dev/null +++ b/changelogs/client_server/newsfragments/1558.clarification @@ -0,0 +1 @@ +Update all event examples to be accurate representations of their associated events. From c879eb950f9a201e4bc6075b7796598dcd4e3aaf Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sat, 25 Aug 2018 20:38:06 +0900 Subject: [PATCH 123/240] client-server/openid.yaml: Fix a type'o Signed-off-by: Alexey Rusakov --- api/client-server/openid.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/openid.yaml b/api/client-server/openid.yaml index 4b89232e..cb982fb3 100644 --- a/api/client-server/openid.yaml +++ b/api/client-server/openid.yaml @@ -90,7 +90,7 @@ paths: The homeserver domain the consumer should use when attempting to verify the user's identity. expires_in: - type: int + type: integer description: |- The number of seconds before this token expires and a new one must be generated. From 337316445f444e03311916dfe18316b979005123 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 16:55:00 +0200 Subject: [PATCH 124/240] fixup! document m.forwarded_room_key --- event-schemas/schema/m.forwarded_room_key | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.forwarded_room_key b/event-schemas/schema/m.forwarded_room_key index 02d91f4e..3b1c5900 100644 --- a/event-schemas/schema/m.forwarded_room_key +++ b/event-schemas/schema/m.forwarded_room_key @@ -21,7 +21,7 @@ properties: The Curve25519 key of the device which initiated the session originally. session_id: type: string - description: The ID of the session holding the key. + description: The ID of the session that the key is for. session_key: type: string description: The key to be exchanged. From 768f33dc2d5bd9854a932cc83f726c1fe85af8ea Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 16:55:28 +0200 Subject: [PATCH 125/240] fixup! document key sharing and m.room_key_request --- event-schemas/schema/m.room_key_request | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room_key_request b/event-schemas/schema/m.room_key_request index 6893dd78..f495a11d 100644 --- a/event-schemas/schema/m.room_key_request +++ b/event-schemas/schema/m.room_key_request @@ -25,7 +25,7 @@ properties: The Curve25519 key of the device which initiated the session originally. session_id: type: string - description: The ID of the session holding the key. + description: The ID of the session that the key is for. required: - algorithm - room_id From 8ae137e82ee197414ad8f904db441ffc612b87f2 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 17:26:00 +0200 Subject: [PATCH 126/240] fixup! document m.forwarded_room_key --- event-schemas/schema/m.forwarded_room_key | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/m.forwarded_room_key b/event-schemas/schema/m.forwarded_room_key index 3b1c5900..f0beed2b 100644 --- a/event-schemas/schema/m.forwarded_room_key +++ b/event-schemas/schema/m.forwarded_room_key @@ -4,7 +4,8 @@ allOf: description: |- This event type is used to forward keys for end-to-end encryption. Typically - it is encrypted as an ``m.room.encrypted`` event. + it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ + event. properties: content: properties: From 579f5ea928f5bffb74969a9b736113529a0334e0 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 17:26:40 +0200 Subject: [PATCH 127/240] fixup! document key sharing and m.room_key_request --- event-schemas/schema/m.room_key_request | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room_key_request b/event-schemas/schema/m.room_key_request index f495a11d..007d0086 100644 --- a/event-schemas/schema/m.room_key_request +++ b/event-schemas/schema/m.room_key_request @@ -9,7 +9,9 @@ properties: content: properties: body: - description: Information about the requested key. + description: |- + Information about the requested key. Required when ``action`` is + ``request``. properties: algorithm: type: string From f6b5aee3e2e39b028b893da1745f15a56c993c73 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 17:27:18 +0200 Subject: [PATCH 128/240] explain how to use key sharing events --- specification/modules/end_to_end_encryption.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index e235e2e9..26e677dd 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -291,6 +291,17 @@ through his phone for the first time, he may want to have access to the previous exchanged messages. To address this issue, events exist for requesting and sending keys from device to device. +When a device is missing keys to decrypt messages, it can request the keys by +sending `m.room_key_request`_ to-device messages to other devices with +``action`` set to ``request``. If a device wishes to share the keys with that +device, it can forward the keys to the first device by sending an encrypted +`m.forwarded_room_key`_ to-device message. The first device should then send an +`m.room_key_request`_ to-device message with ``action`` set to +``cancel_request`` to the other devices that it had originally sent the key +request to; a device that receives a ``cancel_request`` should disregard any +previously-received ``request`` message with the same ``request_id`` and +``requesting_device_id``. + .. NOTE:: Key sharing can be a big attack vector, thus it must be done very carefully. From faa13aaa40cd0c2cf561f3e1cae5952ffcbe09d0 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 25 Aug 2018 17:28:01 +0200 Subject: [PATCH 129/240] fixup! add key sharing changelog --- changelogs/client_server/newsfragments/1465.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1465.feature b/changelogs/client_server/newsfragments/1465.feature index 61a7ed39..649cf222 100644 --- a/changelogs/client_server/newsfragments/1465.feature +++ b/changelogs/client_server/newsfragments/1465.feature @@ -1 +1 @@ -Share room encryption keys between devices +Share room decryption keys between devices From 295b1322e245bc3cdd020d19691f969f4389e132 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 22:26:23 -0600 Subject: [PATCH 130/240] Add back the unsigned.age property to voip event examples --- event-schemas/examples/m.call.answer | 3 +++ event-schemas/examples/m.call.candidates | 3 +++ event-schemas/examples/m.call.hangup | 3 +++ event-schemas/examples/m.call.invite | 3 +++ 4 files changed, 12 insertions(+) diff --git a/event-schemas/examples/m.call.answer b/event-schemas/examples/m.call.answer index a4cfc1e1..e616ba34 100644 --- a/event-schemas/examples/m.call.answer +++ b/event-schemas/examples/m.call.answer @@ -9,5 +9,8 @@ "type" : "answer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } + }, + "unsigned": { + "age": 1234, } } diff --git a/event-schemas/examples/m.call.candidates b/event-schemas/examples/m.call.candidates index 8f1f807a..4a4e6688 100644 --- a/event-schemas/examples/m.call.candidates +++ b/event-schemas/examples/m.call.candidates @@ -11,5 +11,8 @@ "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0" } ] + }, + "unsigned": { + "age": 1234, } } diff --git a/event-schemas/examples/m.call.hangup b/event-schemas/examples/m.call.hangup index 295f16e4..f88a7308 100644 --- a/event-schemas/examples/m.call.hangup +++ b/event-schemas/examples/m.call.hangup @@ -4,5 +4,8 @@ "content": { "version" : 0, "call_id": "12345" + }, + "unsigned": { + "age": 1234, } } diff --git a/event-schemas/examples/m.call.invite b/event-schemas/examples/m.call.invite index fa482bd9..182a255f 100644 --- a/event-schemas/examples/m.call.invite +++ b/event-schemas/examples/m.call.invite @@ -9,5 +9,8 @@ "type" : "offer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } + }, + "unsigned": { + "age": 1234, } } From 312799ae78a27112077753db9782e9193e12e2a7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 22:30:49 -0600 Subject: [PATCH 131/240] General clarification for mention and how matrix.to URIs are meant to work --- specification/appendices/identifier_grammar.rst | 5 +++++ specification/modules/mentions.rst | 3 ++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 013afa79..0412c065 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -274,6 +274,11 @@ parameter is only used in the case of permalinks where an event ID is referenced The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/`` followed by the identifier. +Clients should not rely on matrix.to URIs falling back to a web server if accessed +and instead should perform some sort of action within the client. For example, if +the user where to click on a matrix.to URI for a room alias, the client may open +a view for the user to participate in the room. + Examples of matrix.to URIs are: * Room: ``https://matrix.to/#/!somewhere:domain.com`` diff --git a/specification/modules/mentions.rst b/specification/modules/mentions.rst index e7483ae4..4501b776 100644 --- a/specification/modules/mentions.rst +++ b/specification/modules/mentions.rst @@ -41,7 +41,8 @@ Client behaviour ---------------- In addition to using the appropriate ``matrix.to URI`` for the mention, -clients should use the following guidelines when making mentions: +clients should use the following guidelines when making mentions in events +to be sent: * When mentioning users, use the user's potentially ambigious display name for the anchor's text. If the user does not have a display name, use the user's From aa294fac064e7bb8e36932a666c529fdd996f2bc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 22:57:52 -0600 Subject: [PATCH 132/240] Define the supported HTML subset for message events Also clarify that `m.notice` messages can support HTML. Fixes https://github.com/matrix-org/matrix-doc/issues/1559 Fixes https://github.com/matrix-org/matrix-doc/issues/1560 --- .../examples/m.room.message#m.notice | 4 +- specification/modules/instant_messaging.rst | 48 +++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.message#m.notice b/event-schemas/examples/m.room.message#m.notice index 978c67e6..876cbbb7 100644 --- a/event-schemas/examples/m.room.message#m.notice +++ b/event-schemas/examples/m.room.message#m.notice @@ -2,7 +2,9 @@ "age": 242352, "content": { "body": "This is an example notice", - "msgtype": "m.notice" + "msgtype": "m.notice", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example notice" }, "origin_server_ts": 1431961217939, "event_id": "$WLGTSEFSEF:localhost", diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index ff87f74b..29d33c55 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -56,6 +56,54 @@ of message being sent. Each type has their own required and optional keys, as outlined below. If a client cannot display the given ``msgtype`` then it SHOULD display the fallback plain text ``body`` key instead. +Some message types support HTML in the event content that clients should prefer +to display if available. Currently ``m.text``, ``m.emote``, and ``m.notice`` +support an additional ``format`` parameter of ``org.matrix.custom.html``. When +this field is present, a ``formatted_body`` with the HTML must be provided. The +plain text version of the HTML should be provided in the ``body``. + +Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML +injection, and similar attacks. The strongly suggested set of HTML tags to permit, +denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``, +``h2``, ``h3``, ``h4``, ``h5``, ``h6``, ``blockquote``, ``p``, ``a``, ``ul``, +``ol``, ``sup``, ``sub``, ``nl``, ``li``, ``b``, ``i``, ``u``, ``strong``, ``em``, +``strike``, ``code``, ``hr``, ``br``, ``div``, ``table``, ``thead``, ``tbody``, +``tr``, ``th``, ``td``, ``caption``, ``pre``, ``span``, ``img``. + +Not all attributes on those tags should be permitted as they may be avenues for +other disruption attempts, such as adding ``onclick`` handlers or excessively +large text. Clients should only permit the attributes listed for the tags below. +Where ``data-mx-bg-color`` and ``data-mx-color`` are listed, clients should +translate the value (a 6-character hex color code) to the appropriate CSS/attributes +for the tag. + + +:``font``: + ``data-mx-bg-color``, ``data-mx-color`` + +:``span``: + ``data-mx-bg-color``, ``data-mx-color`` + +:``a``: + ``name``, ``target``, ``href`` (provided the value is not relative and has a scheme + matching one of: ``https``, ``http``, ``ftp``, ``mailto``, ``magnet``) + +:``img``: + ``width``, ``height``, ``alt``, ``title``, ``src`` (provided it is a Matrix Content + URI) + +:``ol``: + ``start`` + +:``code``: + ``class`` (only classes which start with ``language-`` for syntax highlighting) + + +Additionally, clients should ensure that *all* ``a`` tags get a ``rel="noopener"`` +to prevent the target page from referencing the client's tab/window. + + + {{msgtype_events}} From 3c472f70e3aa0f29aa95c05887d50970a9cb2de5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 22:59:22 -0600 Subject: [PATCH 133/240] Changelog --- changelogs/client_server/newsfragments/1562.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1562.clarification diff --git a/changelogs/client_server/newsfragments/1562.clarification b/changelogs/client_server/newsfragments/1562.clarification new file mode 100644 index 00000000..c46e189d --- /dev/null +++ b/changelogs/client_server/newsfragments/1562.clarification @@ -0,0 +1 @@ +Clarify the supported HTML features for room messages. From e5a7dd1c45a2547efcbaced3aa1ccd06a85b3cdc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 23:00:26 -0600 Subject: [PATCH 134/240] Remove excess commas from JSON --- event-schemas/examples/m.call.answer | 2 +- event-schemas/examples/m.call.candidates | 2 +- event-schemas/examples/m.call.hangup | 2 +- event-schemas/examples/m.call.invite | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/event-schemas/examples/m.call.answer b/event-schemas/examples/m.call.answer index e616ba34..a7b9e883 100644 --- a/event-schemas/examples/m.call.answer +++ b/event-schemas/examples/m.call.answer @@ -11,6 +11,6 @@ } }, "unsigned": { - "age": 1234, + "age": 1234 } } diff --git a/event-schemas/examples/m.call.candidates b/event-schemas/examples/m.call.candidates index 4a4e6688..1a3fdedf 100644 --- a/event-schemas/examples/m.call.candidates +++ b/event-schemas/examples/m.call.candidates @@ -13,6 +13,6 @@ ] }, "unsigned": { - "age": 1234, + "age": 1234 } } diff --git a/event-schemas/examples/m.call.hangup b/event-schemas/examples/m.call.hangup index f88a7308..cf2d6859 100644 --- a/event-schemas/examples/m.call.hangup +++ b/event-schemas/examples/m.call.hangup @@ -6,6 +6,6 @@ "call_id": "12345" }, "unsigned": { - "age": 1234, + "age": 1234 } } diff --git a/event-schemas/examples/m.call.invite b/event-schemas/examples/m.call.invite index 182a255f..069d334e 100644 --- a/event-schemas/examples/m.call.invite +++ b/event-schemas/examples/m.call.invite @@ -11,6 +11,6 @@ } }, "unsigned": { - "age": 1234, + "age": 1234 } } From 0a6c1c4ddaa28a6ce169c1f38f22ddcde7fa0291 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 23:18:43 -0600 Subject: [PATCH 135/240] Ensure the event examples and matrix.org assets are tested Otherwise we go nearly a week without realizing the build is failing due to bad schemas/examples. This also helps us ensure a PR is up to par. This commit is expected to cause a build failure at this time. A future commit will actually fix the project and address concerns raised by the testing. --- .circleci/config.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index 3a0b6032..f79449f3 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -23,9 +23,29 @@ buildswaggerui: &buildswaggerui wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/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 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: docker: - image: uhoreg/matrix-doc-build From be9f6042e527a44cd1b4315a208380adef7e1507 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 23:21:50 -0600 Subject: [PATCH 136/240] Fix encrypted event examples --- event-schemas/examples/m.room.encrypted#megolm | 2 +- event-schemas/examples/m.room.encrypted#olm | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/examples/m.room.encrypted#megolm b/event-schemas/examples/m.room.encrypted#megolm index 1f9b7520..72676318 100644 --- a/event-schemas/examples/m.room.encrypted#megolm +++ b/event-schemas/examples/m.room.encrypted#megolm @@ -1,6 +1,6 @@ { "content": { - "algorithm": "m.megolm.v1.aes-sha2", + "algorithm": "m.megolm.v1.aes-sha256", "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", "device_id": "RJYKSTBOIE", "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted#olm index abb23c31..23f65738 100644 --- a/event-schemas/examples/m.room.encrypted#olm +++ b/event-schemas/examples/m.room.encrypted#olm @@ -2,7 +2,7 @@ "type": "m.room.encrypted", "sender": "@example:localhost", "content": { - "algorithm": "m.olm.v1.curve25519-aes-sha2", + "algorithm": "m.olm.v1.curve25519-aes-sha256", "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", "ciphertext": { "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { From e9e93b0eecad5546efef33d46bdbe214c47d8c31 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 20:51:39 -0600 Subject: [PATCH 137/240] Move `invite_room_state` to the correct place in the client-server API Fixes https://github.com/matrix-org/matrix-doc/issues/1350 --- .../examples/m.room.member#invite_room_state | 32 +++++------ event-schemas/schema/m.room.member | 53 +++++++++++-------- scripts/templating/matrix_templates/units.py | 9 ---- 3 files changed, 47 insertions(+), 47 deletions(-) diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index 1a93b395..965669ad 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -5,22 +5,24 @@ "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", "displayname": "Alice Margatroid" }, - "invite_room_state": [ - { - "type": "m.room.name", - "state_key": "", - "content": { - "name": "Forest of Magic" + "unsigned": { + "invite_room_state": [ + { + "type": "m.room.name", + "state_key": "", + "content": { + "name": "Forest of Magic" + } + }, + { + "type": "m.room.join_rules", + "state_key": "", + "content": { + "join_rule": "invite" + } } - }, - { - "type": "m.room.join_rules", - "state_key": "", - "content": { - "join_rule": "invite" - } - } - ], + ] + }, "state_key": "@alice:localhost", "origin_server_ts": 1431961217939, "event_id": "$WLGTSEFSEF:localhost", diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index 4f4077a7..5fb5356d 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -18,7 +18,9 @@ description: |- The ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise. - This event may also include an ``invite_room_state`` key **outside the** ``content`` **key**. If present, this contains an array of ``StrippedState`` Events. These events provide information on a subset of state events such as the room name. + This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data. + If present, this contains an array of ``StrippedState`` Events. These events provide information + on a subset of state events such as the room name. properties: content: properties: @@ -71,32 +73,37 @@ properties: - signed title: Invite type: object + unsigned: + type: object + title: UnsignedData + description: Contains optional extra information about the event. + properties: + invite_room_state: + description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.' + items: + description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.' + properties: + content: + description: The ``content`` for the event. + title: EventContent + type: object + state_key: + description: The ``state_key`` for the event. + type: string + type: + description: The ``type`` for the event. + type: string + required: + - type + - state_key + - content + title: StrippedState + type: object + type: array required: - membership title: EventContent type: object - invite_room_state: - description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.' - items: - description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.' - properties: - content: - description: The ``content`` for the event. - title: EventContent - type: object - state_key: - description: The ``state_key`` for the event. - type: string - type: - description: The ``type`` for the event. - type: string - required: - - type - - state_key - - content - title: StrippedState - type: object - type: array state_key: description: The ``user_id`` this membership event relates to. type: string diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..81da3f6a 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -875,15 +875,6 @@ class MatrixUnits(Units): Units.prop(json_schema, "properties/content") ) - # This is horrible because we're special casing a key on m.room.member. - # We need to do this because we want to document a non-content object. - if schema["type"] == "m.room.member": - invite_room_state = get_tables_for_schema( - json_schema["properties"]["invite_room_state"]["items"], - ) - schema["content_fields"].extend(invite_room_state) - - # grab msgtype if it is the right kind of event msgtype = Units.prop( json_schema, "properties/content/properties/msgtype/enum" From 5ceb1321107f9ff0760902e4aa4287da59c8510d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 20:52:59 -0600 Subject: [PATCH 138/240] Changelog --- changelogs/client_server/newsfragments/1568.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1568.clarification diff --git a/changelogs/client_server/newsfragments/1568.clarification b/changelogs/client_server/newsfragments/1568.clarification new file mode 100644 index 00000000..4b7a6eaf --- /dev/null +++ b/changelogs/client_server/newsfragments/1568.clarification @@ -0,0 +1 @@ +Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides. From 7d08ef73d09de2e37b9be9d602277c4f336be35b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:19:07 -0600 Subject: [PATCH 139/240] Fix naming of the Filter schemas EventFilter !== Filter Fixes https://github.com/matrix-org/matrix-doc/issues/1509 --- api/client-server/definitions/event_filter.yaml | 2 +- api/client-server/definitions/sync_filter.yaml | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/api/client-server/definitions/event_filter.yaml b/api/client-server/definitions/event_filter.yaml index 1cae3ea9..8c96917f 100644 --- a/api/client-server/definitions/event_filter.yaml +++ b/api/client-server/definitions/event_filter.yaml @@ -11,7 +11,7 @@ # 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. -title: Filter +title: EventFilter properties: limit: description: The maximum number of events to return. diff --git a/api/client-server/definitions/sync_filter.yaml b/api/client-server/definitions/sync_filter.yaml index 69b245a3..33bead26 100644 --- a/api/client-server/definitions/sync_filter.yaml +++ b/api/client-server/definitions/sync_filter.yaml @@ -11,6 +11,8 @@ # 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. +type: object +title: Filter properties: event_fields: description: List of event fields to include. If this list is absent then all @@ -40,6 +42,7 @@ properties: room: title: RoomFilter description: Filters to be applied to room data. + type: object properties: not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms @@ -76,5 +79,3 @@ properties: allOf: - $ref: room_event_filter.yaml description: The per user account data to include for rooms. - type: object -type: object From 97e3dd443b5bc38a8ec166b9ae3642460f960e1c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:20:01 -0600 Subject: [PATCH 140/240] Update room_event_filter.yaml to use the OpenAPI allOf definition This is just maintenance. --- .../definitions/room_event_filter.yaml | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 7d9184b5..9817db0c 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -13,23 +13,23 @@ # limitations under the License. allOf: - $ref: event_filter.yaml -title: RoomEventFilter -properties: - not_rooms: - description: A list of room IDs to exclude. If this list is absent then no rooms - are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` - filter. - items: - type: string - type: array - rooms: - description: A list of room IDs to include. If this list is absent then all rooms - are included. - items: - type: string - type: array - contains_url: - type: boolean +- type: object + title: RoomEventFilter + properties: + not_rooms: + description: A list of room IDs to exclude. If this list is absent then no rooms + are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` + filter. + items: + type: string + type: array + rooms: + description: A list of room IDs to include. If this list is absent then all rooms + are included. + items: + type: string + type: array + contains_url: + type: boolean description: If ``true``, includes only events with a url key in their content. If ``false``, excludes those events. -type: object From 26a7a341f0f56e8ac16edf0b8ee7b57bae26b298 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:20:28 -0600 Subject: [PATCH 141/240] Mark the filter_id in the response of POST /filter as required --- api/client-server/filter.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml index b34da7b6..58d9e55c 100644 --- a/api/client-server/filter.yaml +++ b/api/client-server/filter.yaml @@ -91,7 +91,12 @@ paths: filter_id: type: string description: |- - The ID of the filter that was created. + The ID of the filter that was created. Cannot start + with a ``{`` as this character is used to determine + if the filter provided is inline JSON or a previously + declared filter by homeservers on some APIs. + example: "66696p746572" + required: ['filter_id'] tags: - Room participation "/user/{userId}/filter/{filterId}": From 1cbcaba2c70fa41bc8f478113932fdcd642957af Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:21:27 -0600 Subject: [PATCH 142/240] Clean up examples in filter.yaml Indentation, excess examples. --- api/client-server/filter.yaml | 48 ++++++++++++++++------------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml index 58d9e55c..db215196 100644 --- a/api/client-server/filter.yaml +++ b/api/client-server/filter.yaml @@ -54,37 +54,33 @@ paths: allOf: - $ref: "definitions/sync_filter.yaml" example: { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"] - }, - "timeline": { - "limit": 10, - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - }, - "ephemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - } + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"] }, - "presence": { - "types": ["m.presence"], - "not_senders": ["@alice:example.com"] + "timeline": { + "limit": 10, + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } + "ephemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "presence": { + "types": ["m.presence"], + "not_senders": ["@alice:example.com"] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } responses: 200: description: The filter was created. - examples: - application/json: { - "filter_id": "66696p746572" - } schema: type: object properties: From b68ed5d594d37fa0c76e1592805f64e3030b1ca4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:21:49 -0600 Subject: [PATCH 143/240] Define the default for the contains_url filter param Fixes https://github.com/matrix-org/matrix-doc/issues/1553 --- api/client-server/definitions/room_event_filter.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 9817db0c..c36b3768 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -31,5 +31,5 @@ allOf: type: array contains_url: type: boolean - description: If ``true``, includes only events with a url key in their content. If - ``false``, excludes those events. + description: If ``true``, includes only events with a ``url`` key in their content. If + ``false``, excludes those events. Defaults to ``false``. From b0fbd7be7c4cb3abe80cc5b6218a6de0f6fb1ff8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:24:33 -0600 Subject: [PATCH 144/240] Changelog --- changelogs/client_server/newsfragments/1570.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1570.clarification diff --git a/changelogs/client_server/newsfragments/1570.clarification b/changelogs/client_server/newsfragments/1570.clarification new file mode 100644 index 00000000..dbf8a821 --- /dev/null +++ b/changelogs/client_server/newsfragments/1570.clarification @@ -0,0 +1 @@ +Clarify the object structures and defaults for Filters. From 667fa082af81b612748180e92e5fe8e6aad4aa55 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:30:33 -0600 Subject: [PATCH 145/240] Replace applicable types of 'number' to 'integer' `number` implies/represents a float where `integer` does not. The only remaining `type: number` in the project appear on power levels: those have been left untouched pending clarification. Fixes https://github.com/matrix-org/matrix-doc/issues/746 --- api/client-server/admin.yaml | 3 ++- api/client-server/content-repo.yaml | 9 ++++++--- api/client-server/definitions/public_rooms_response.yaml | 4 ++-- api/client-server/list_public_rooms.yaml | 8 ++++---- api/client-server/notifications.yaml | 2 +- api/client-server/registration.yaml | 4 ++-- api/client-server/search.yaml | 4 ++-- api/client-server/users.yaml | 2 +- event-schemas/schema/core-event-schema/room_event.yaml | 3 ++- 9 files changed, 22 insertions(+), 17 deletions(-) diff --git a/api/client-server/admin.yaml b/api/client-server/admin.yaml index 2fdac82b..09942a10 100644 --- a/api/client-server/admin.yaml +++ b/api/client-server/admin.yaml @@ -105,7 +105,8 @@ paths: type: string description: Most recently seen IP address of the session. last_seen: - type: number + type: integer + format: int64 description: Unix timestamp that the session was last active. user_agent: type: string diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index b3e9517b..5f4e9111 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -259,7 +259,8 @@ paths: description: "The URL to get a preview of" required: true - in: query - type: number + type: integer + format: int64 x-example: 1510610716656 name: ts description: |- @@ -276,7 +277,8 @@ paths: type: object properties: "matrix:image:size": - type: number + type: integer + format: int64 description: |- The byte-size of the image. Omitted if there is no image attached. "og:image": @@ -324,7 +326,8 @@ paths: type: object properties: m.upload.size: - type: number + type: integer + format: int64 description: |- The maximum size an upload can be in bytes. Clients SHOULD use this as a guide when uploading content. diff --git a/api/client-server/definitions/public_rooms_response.yaml b/api/client-server/definitions/public_rooms_response.yaml index fc6ccb44..ab701051 100644 --- a/api/client-server/definitions/public_rooms_response.yaml +++ b/api/client-server/definitions/public_rooms_response.yaml @@ -45,7 +45,7 @@ properties: description: |- The name of the room, if any. num_joined_members: - type: number + type: integer description: |- The number of members joined to the room. room_id: @@ -82,7 +82,7 @@ properties: absence of this token means there are no results before this batch, i.e. this is the first batch. total_room_count_estimate: - type: number + type: integer description: |- An estimate on the total number of public rooms, if the server has an estimate. diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 72a12060..8f0e80d5 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -123,7 +123,7 @@ paths: parameters: - in: query name: limit - type: number + type: integer description: |- Limit the number of results returned. - in: query @@ -173,7 +173,7 @@ paths: type: object properties: limit: - type: number + type: integer description: |- Limit the number of results returned. since: @@ -233,7 +233,7 @@ paths: description: |- The name of the room, if any. num_joined_members: - type: number + type: integer description: |- The number of members joined to the room. room_id: @@ -270,7 +270,7 @@ paths: absence of this token means there are no results before this batch, i.e. this is the first batch. total_room_count_estimate: - type: number + type: integer description: |- An estimate on the total number of public rooms, if the server has an estimate. diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml index e10e5bfd..b450885b 100644 --- a/api/client-server/notifications.yaml +++ b/api/client-server/notifications.yaml @@ -45,7 +45,7 @@ paths: required: false x-example: "xxxxx" - in: query - type: number + type: integer name: limit description: Limit on the number of events to return in this request. required: false diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 56da9add..e4b05629 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -218,7 +218,7 @@ paths: description: The email address example: "example@example.com" send_attempt: - type: number + type: integer description: Used to distinguish protocol level retries from requests to re-send the email. example: 1 required: ["client_secret", "email", "send_attempt"] @@ -283,7 +283,7 @@ paths: description: The phone number. example: "example@example.com" send_attempt: - type: number + type: integer description: Used to distinguish protocol level retries from requests to re-send the SMS message. example: 1 required: ["client_secret", "country", "phone_number", "send_attempt"] diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index e4118c32..0d3a7884 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -179,7 +179,7 @@ paths: description: Mapping of category name to search criteria. properties: count: - type: number + type: integer description: An approximate count of the total number of results found. highlights: type: array @@ -197,7 +197,7 @@ paths: description: The result object. properties: rank: - type: number + type: integer description: A number that describes how closely this result matches the search. Higher is closer. diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index a682b435..fc6d233b 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -47,7 +47,7 @@ paths: description: The term to search for example: "foo" limit: - type: number + type: integer description: The maximum number of results to return (Defaults to 10). example: 10 required: ["search_term"] diff --git a/event-schemas/schema/core-event-schema/room_event.yaml b/event-schemas/schema/core-event-schema/room_event.yaml index a8a23f54..ebf970ad 100644 --- a/event-schemas/schema/core-event-schema/room_event.yaml +++ b/event-schemas/schema/core-event-schema/room_event.yaml @@ -16,7 +16,8 @@ properties: origin_server_ts: description: Timestamp in milliseconds on originating homeserver when this event was sent. - type: number + type: integer + format: int64 unsigned: description: Contains optional extra information about the event. properties: From e75a1836b86b04e0670c8e648055be5d1d0cf54d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:33:43 -0600 Subject: [PATCH 146/240] Changelog --- changelogs/client_server/newsfragments/1571.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1571.clarification diff --git a/changelogs/client_server/newsfragments/1571.clarification b/changelogs/client_server/newsfragments/1571.clarification new file mode 100644 index 00000000..2410baf3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1571.clarification @@ -0,0 +1 @@ +Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions. From 008ebb8c1ac1d1958a3809d3757bbb06c66a9718 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:55:30 -0600 Subject: [PATCH 147/240] Add `account_data` to left rooms in /sync Fixes https://github.com/matrix-org/matrix-doc/issues/1392 --- api/client-server/sync.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 4b44c20e..f1997b61 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -227,6 +227,14 @@ paths: room up to the point when the user left. allOf: - $ref: "definitions/timeline_batch.yaml" + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: "definitions/event_batch.yaml" presence: title: Presence type: object From e8edfba11438a211ec7bcc1cebf1192dffae105b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:57:04 -0600 Subject: [PATCH 148/240] Changelog --- changelogs/client_server/newsfragments/1572.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1572.clarification diff --git a/changelogs/client_server/newsfragments/1572.clarification b/changelogs/client_server/newsfragments/1572.clarification new file mode 100644 index 00000000..7e84098f --- /dev/null +++ b/changelogs/client_server/newsfragments/1572.clarification @@ -0,0 +1 @@ +Clarify that left rooms also have account data in ``/sync``. From e60b44e27fe9e83e5c6edca9e4c778fd244da0fa Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:27:34 -0600 Subject: [PATCH 149/240] Clean up PUT /directory/room Fixes https://github.com/matrix-org/matrix-doc/issues/933 The issue references two problems: a `roomInfo` and lack of a `room_id`. It appears the `room_id` has been fixed since reporting, however the `roomInfo` remained (and is now fixed). --- api/client-server/directory.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index ee42cf84..78ddfa29 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -41,7 +41,7 @@ paths: required: true x-example: "#monkeys:matrix.org" - in: body - name: roomInfo + name: body description: Information about this room alias. required: true schema: @@ -50,24 +50,24 @@ paths: room_id: type: string description: The room ID to set. + required: ['room_id'] example: { - "room_id": "!abnjk1jdasj98:capuchins.com" - } + "room_id": "!abnjk1jdasj98:capuchins.com" + } responses: 200: description: The mapping was created. examples: - application/json: { - } + application/json: {} schema: type: object 409: description: A room alias with that name already exists. examples: application/json: { - "errcode": "M_UNKNOWN", - "error": "Room alias #monkeys:matrix.org already exists." - } + "errcode": "M_UNKNOWN", + "error": "Room alias #monkeys:matrix.org already exists." + } schema: "$ref": "definitions/errors/error.yaml" tags: From ce0befd7d059e1b91389bfa4692cbb4c6dfd2d84 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:28:52 -0600 Subject: [PATCH 150/240] Changelog --- changelogs/client_server/newsfragments/1574.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1574.clarification diff --git a/changelogs/client_server/newsfragments/1574.clarification b/changelogs/client_server/newsfragments/1574.clarification new file mode 100644 index 00000000..8d07ef56 --- /dev/null +++ b/changelogs/client_server/newsfragments/1574.clarification @@ -0,0 +1 @@ +Fix naming of the body field in ``PUT /directory/room``. From d7d28f7e5bf9c263fa0b5d9c04638ec02ae6f6dd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 09:16:30 -0600 Subject: [PATCH 151/240] Remove nl as a supported HTML tag --- specification/modules/instant_messaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 29d33c55..6d1b1b35 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -66,7 +66,7 @@ Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML tags to permit, denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``, ``h2``, ``h3``, ``h4``, ``h5``, ``h6``, ``blockquote``, ``p``, ``a``, ``ul``, -``ol``, ``sup``, ``sub``, ``nl``, ``li``, ``b``, ``i``, ``u``, ``strong``, ``em``, +``ol``, ``sup``, ``sub``, ``li``, ``b``, ``i``, ``u``, ``strong``, ``em``, ``strike``, ``code``, ``hr``, ``br``, ``div``, ``table``, ``thead``, ``tbody``, ``tr``, ``th``, ``td``, ``caption``, ``pre``, ``span``, ``img``. From c7822cc9a8d18ddcdd17473e2369f93bd7a7307c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 09:16:53 -0600 Subject: [PATCH 152/240] Link to the content repo when referencing MXC URIs in images --- specification/modules/instant_messaging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 6d1b1b35..88326999 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -89,8 +89,7 @@ for the tag. matching one of: ``https``, ``http``, ``ftp``, ``mailto``, ``magnet``) :``img``: - ``width``, ``height``, ``alt``, ``title``, ``src`` (provided it is a Matrix Content - URI) + ``width``, ``height``, ``alt``, ``title``, ``src`` (provided it is a `Matrix Content (MXC) URI`_) :``ol``: ``start`` @@ -345,3 +344,4 @@ Clients should sanitise **all displayed keys** for unsafe HTML to prevent Cross- Scripting (XSS) attacks. This includes room names and topics. .. _`E2E module`: `module:e2e`_ +.. _`Matrix Content (MXC) URI`: `module:content`_ \ No newline at end of file From 5bf99aeb349f0af80e7f4b8f3a0c189304054e92 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 09:17:08 -0600 Subject: [PATCH 153/240] Add a note that formatted_body is not forever --- specification/modules/instant_messaging.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 88326999..9de89071 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -102,6 +102,9 @@ Additionally, clients should ensure that *all* ``a`` tags get a ``rel="noopener" to prevent the target page from referencing the client's tab/window. +.. Note:: + A future iteration of the specification will support more powerful and extensible + message formatting options, such as the proposal `MSC1225 `_. {{msgtype_events}} From 89daa3c5ce0c745219d8cdb9e92e693fc24f1663 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 09:17:40 -0600 Subject: [PATCH 154/240] Clarify that clients aren't required to render all the tags This commit also includes minor clarifications to surrounding text. --- specification/modules/instant_messaging.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 9de89071..079a4801 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -98,9 +98,13 @@ for the tag. ``class`` (only classes which start with ``language-`` for syntax highlighting) -Additionally, clients should ensure that *all* ``a`` tags get a ``rel="noopener"`` +Additionally, web clients should ensure that *all* ``a`` tags get a ``rel="noopener"`` to prevent the target page from referencing the client's tab/window. +Tags must not be nested more than 100 levels deep. Clients should only support the subset +of tags they can render, falling back to other representations of the tags where possible. +For example, a client may not be able to render tables correctly and instead could fall +back to rendering tab-delimited text. .. Note:: A future iteration of the specification will support more powerful and extensible From 17bdc0c740612e0476663129617ee11f0026fb86 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 25 Aug 2018 23:21:50 -0600 Subject: [PATCH 155/240] Revert "Fix encrypted event examples" This reverts commit be9f6042e527a44cd1b4315a208380adef7e1507. --- event-schemas/examples/m.room.encrypted#megolm | 2 +- event-schemas/examples/m.room.encrypted#olm | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/examples/m.room.encrypted#megolm b/event-schemas/examples/m.room.encrypted#megolm index 72676318..1f9b7520 100644 --- a/event-schemas/examples/m.room.encrypted#megolm +++ b/event-schemas/examples/m.room.encrypted#megolm @@ -1,6 +1,6 @@ { "content": { - "algorithm": "m.megolm.v1.aes-sha256", + "algorithm": "m.megolm.v1.aes-sha2", "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", "device_id": "RJYKSTBOIE", "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted#olm index 23f65738..abb23c31 100644 --- a/event-schemas/examples/m.room.encrypted#olm +++ b/event-schemas/examples/m.room.encrypted#olm @@ -2,7 +2,7 @@ "type": "m.room.encrypted", "sender": "@example:localhost", "content": { - "algorithm": "m.olm.v1.curve25519-aes-sha256", + "algorithm": "m.olm.v1.curve25519-aes-sha2", "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", "ciphertext": { "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { From 438f5825ae82ff8ac454db26e3076fce6242daf5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 14:55:59 -0600 Subject: [PATCH 156/240] Add more supported encryption algorithms to message events --- event-schemas/schema/m.room.encrypted | 2 ++ 1 file changed, 2 insertions(+) diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index 6825be1d..9c2fa7be 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -14,7 +14,9 @@ properties: type: string enum: - m.olm.curve25519-aes-sha256 + - m.olm.v1.curve25519-aes-sha2 - m.megolm.v1.aes-sha + - m.megolm.v1.aes-sha2 description: |- The encryption algorithm used to encrypt this event. The value of this field determines which other properties will be From 72de8bec5c1703d1e425dd29c6463810d3641a0a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 15:05:56 -0600 Subject: [PATCH 157/240] Remove unused algorithms for encrypted messages --- event-schemas/schema/m.room.encrypted | 2 -- 1 file changed, 2 deletions(-) diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index 9c2fa7be..44b09c3f 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -13,9 +13,7 @@ properties: algorithm: type: string enum: - - m.olm.curve25519-aes-sha256 - m.olm.v1.curve25519-aes-sha2 - - m.megolm.v1.aes-sha - m.megolm.v1.aes-sha2 description: |- The encryption algorithm used to encrypt this event. The From 5fa6b493653cdf831183d994f272e7978fda341d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 15:56:47 -0600 Subject: [PATCH 158/240] Specify the type of filter the search API expects Note: This is badly named until https://github.com/matrix-org/matrix-doc/pull/1570 lands Fixes https://github.com/matrix-org/matrix-doc/issues/598 --- api/client-server/search.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index e4118c32..6feb5778 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -41,7 +41,7 @@ paths: type: string description: |- The point to return events from. If given, this should be a - `next_batch` result from a previous call to this endpoint. + ``next_batch`` result from a previous call to this endpoint. x-example: "YWxsCgpOb25lLDM1ODcwOA" - in: body name: body @@ -95,6 +95,7 @@ paths: # for now :/ description: |- This takes a `filter`_. + $ref: "definitions/room_event_filter.yaml" order_by: title: "Ordering" type: string From 7b7933327a2e66ff360858ae8a98cc754bc44ef7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 15:57:51 -0600 Subject: [PATCH 159/240] Changelog --- changelogs/client_server/newsfragments/1577.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1577.clarification diff --git a/changelogs/client_server/newsfragments/1577.clarification b/changelogs/client_server/newsfragments/1577.clarification new file mode 100644 index 00000000..aec3248f --- /dev/null +++ b/changelogs/client_server/newsfragments/1577.clarification @@ -0,0 +1 @@ +Clarify the filter object schema used in room searching. From be2e0fc9d416348b411c21a8fc394387a1194ebc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 16:12:42 -0600 Subject: [PATCH 160/240] Clarify that ACLs are required to manually deny unsupported hosts --- event-schemas/schema/m.room.server_acl | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl index ed64038c..29a91f4b 100644 --- a/event-schemas/schema/m.room.server_acl +++ b/event-schemas/schema/m.room.server_acl @@ -4,8 +4,8 @@ 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 are recommended to be - added to the denied hosts list. + 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 @@ -27,6 +27,14 @@ description: |- 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:: + Servers that do not uphold the ACLs MUST be manually appended to the denied hosts + list. To accomplish this, events should have their ``prev_events`` inspected for + denied hosts, therefore detecting servers which are not upholding the ACLs. Server + versions can also be used to detect hosts that will not uphold the ACLs, although + this is less effective. 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 From 82be6077ffc941bfce0a26fb4f631618046ea8de Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 16:13:42 -0600 Subject: [PATCH 161/240] Add a note that ACLs don't operate at the auth level; Fix glob definition --- event-schemas/schema/m.room.server_acl | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl index 29a91f4b..9e7ccc3b 100644 --- a/event-schemas/schema/m.room.server_acl +++ b/event-schemas/schema/m.room.server_acl @@ -22,6 +22,11 @@ description: |- #. 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 @@ -51,7 +56,7 @@ properties: 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 one or more characters. + matches zero or more characters and ``?`` matches exactly one character. **This defaults to an empty list when not provided, effectively disallowing every server.** @@ -62,7 +67,7 @@ properties: 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 one or more characters. + matches zero or more characters and ``?`` matches exactly one character. This defaults to an empty list when not provided. items: From 76afef79f8f09809b8dafecc37b7804f52d610e7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 16:14:37 -0600 Subject: [PATCH 162/240] Clarify the rationale and motive for blanket IP banning and port exclusion --- event-schemas/schema/m.room.server_acl | 4 ++++ specification/modules/server_acls.rst | 7 +++++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl index 9e7ccc3b..317031cd 100644 --- a/event-schemas/schema/m.room.server_acl +++ b/event-schemas/schema/m.room.server_acl @@ -51,6 +51,10 @@ properties: 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: |- diff --git a/specification/modules/server_acls.rst b/specification/modules/server_acls.rst index 72892fce..f26b8c6b 100644 --- a/specification/modules/server_acls.rst +++ b/specification/modules/server_acls.rst @@ -17,7 +17,7 @@ Server Access Control Lists (ACLs) for rooms .. _module:server-acls: -In some scenarios room operators may wish to prevent a malicous or untrusted +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. @@ -30,7 +30,10 @@ similar to setting the ``m.federate`` value on the `m.room.create`_ 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. + 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 From d7397ccd563fb886c48944c1f3869e0d617aadc8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 16:21:10 -0600 Subject: [PATCH 163/240] Provide additional rationale for kicking users when they are ACLd --- specification/modules/server_acls.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/modules/server_acls.rst b/specification/modules/server_acls.rst index f26b8c6b..2b2d8f35 100644 --- a/specification/modules/server_acls.rst +++ b/specification/modules/server_acls.rst @@ -47,7 +47,8 @@ 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. +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 ---------------- From 313e6de48bb99afefa8adb18d6dd097a4d88a849 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 27 Aug 2018 23:36:48 +0100 Subject: [PATCH 164/240] tweak wording to spell out that handling legacy/noncompliant servers. --- event-schemas/schema/m.room.server_acl | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl index 317031cd..c6adaf05 100644 --- a/event-schemas/schema/m.room.server_acl +++ b/event-schemas/schema/m.room.server_acl @@ -34,12 +34,14 @@ description: |- permit the use of the ``deny`` list without losing the room. .. WARNING:: - Servers that do not uphold the ACLs MUST be manually appended to the denied hosts - list. To accomplish this, events should have their ``prev_events`` inspected for - denied hosts, therefore detecting servers which are not upholding the ACLs. Server - versions can also be used to detect hosts that will not uphold the ACLs, although - this is less effective. Server ACLs were added in Synapse v0.32.0 although other - server implementations and versions exist in the world. + 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 From bac0392a2d98662b19f32f2955daca145e42a499 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 17:28:08 -0600 Subject: [PATCH 165/240] General clarity for push rule defaults and where to get information Include moving a roaming condition that was under the wrong rule. --- specification/modules/push.rst | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 408eabe6..1972fa17 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -468,6 +468,10 @@ Definition: ``.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: @@ -492,6 +496,11 @@ Definition: { "set_tweak": "highlight", "value": false + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.encrypted" } ] } @@ -512,11 +521,6 @@ Definition: { "kind": "room_member_count", "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.encrypted" } ], "actions": [ @@ -562,7 +566,10 @@ Definition: ``.m.rule.encrypted`` ````````````````````` -Matches all encrypted events. +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: @@ -628,11 +635,11 @@ rule determines its behaviour. The following conditions are defined: Parameters: - * ``key``: The notification power level to require the sender to have. 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 a specific - notification type from the ``notifications`` object in the power level event - content. + * ``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. From 32ac81c5883ba7e7fff2b896a34d6ad7f829e4fd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 17:41:27 -0600 Subject: [PATCH 166/240] Spelling --- api/application-service/protocols.yaml | 6 +++--- api/client-server/third_party_lookup.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/application-service/protocols.yaml b/api/application-service/protocols.yaml index 376e66c0..e6489cc5 100644 --- a/api/application-service/protocols.yaml +++ b/api/application-service/protocols.yaml @@ -127,7 +127,7 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/location/{protocol}": 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: |- Retrieve a list of Matrix portal rooms that lead to the matched third party location. operationId: queryLocationByProtocol @@ -180,7 +180,7 @@ paths: get: summary: Reverse-lookup third party locations given a Matrix room alias. 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. operationId: queryLocationByAlias parameters: @@ -225,7 +225,7 @@ paths: get: summary: Reverse-lookup third party users given a Matrix User ID. 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 parameters: - in: query diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index cba9ce22..3d348df2 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -73,7 +73,7 @@ paths: $ref: definitions/errors/error.yaml "/thirdparty/location/{protocol}": 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: |- Requesting this endpoint with a valid protocol name results in a list of successful mapping results in a JSON array. Each result contains @@ -151,7 +151,7 @@ paths: get: summary: Reverse-lookup third party locations given a Matrix room alias. 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. operationId: queryLocationByAlias security: @@ -181,7 +181,7 @@ paths: get: summary: Reverse-lookup third party users given a Matrix User ID. 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 security: - accessToken: [] From 54032964fc89a356fef1d679d94e6e8bbdeabfc6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 17:41:52 -0600 Subject: [PATCH 167/240] Misc clarity for 3rd party appservice protocols/locations --- specification/application_service_api.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 9d467e87..6e3c5374 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -184,13 +184,14 @@ Third party networks ++++++++++++++++++++ Application services may declare which protocols they support via their registration -file. 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. - -Each protocol may have several "locations". 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. +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. + +Each protocol may have several "locations" (also known as "third party locations" or "3PLs"). +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. 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 From 17e0ef4b91034b0cdb010416225ffac65b4107fc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 17:58:47 -0600 Subject: [PATCH 168/240] Remove empty file and now-empty section from the appservice spec This commit has approval under https://github.com/matrix-org/matrix-doc/pull/1555 although is being included in this branch/PR so the build passes, permitting a merge. --- .../application_service.yaml | 28 ------------------- specification/application_service_api.rst | 9 ------ 2 files changed, 37 deletions(-) delete mode 100644 api/application-service/application_service.yaml diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml deleted file mode 100644 index 67b5b1b5..00000000 --- a/api/application-service/application_service.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# 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: "/" -consumes: - - application/json -produces: - - application/json -paths: diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 48e6896d..51280341 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -246,15 +246,6 @@ application service for filtering. {{protocols_as_http_api}} -HTTP APIs -+++++++++ - -This contains application service APIs which are used by the homeserver. All -application services MUST implement these APIs. These APIs are defined below. - -{{application_service_as_http_api}} - - .. _create the user: `sect:asapi-permissions`_ Client-Server API Extensions From fa96d8629bcce201b1ef32a8b969e0f0ae60343f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 11:36:04 -0600 Subject: [PATCH 169/240] Prepare the appservice spec for an r0 release This puts the scaffolding in place for an r0 release to happen, such as the changelog and version variables. --- changelogs/application_service.rst | 0 .../newsfragments/.gitignore | 1 + changelogs/application_service/pyproject.toml | 30 +++++++++++++++++++ scripts/gendoc.py | 6 ++++ .../templating/matrix_templates/sections.py | 4 +++ scripts/templating/matrix_templates/units.py | 5 ++-- specification/application_service_api.rst | 12 ++++++-- specification/targets.yaml | 2 +- 8 files changed, 55 insertions(+), 5 deletions(-) create mode 100644 changelogs/application_service.rst create mode 100644 changelogs/application_service/newsfragments/.gitignore create mode 100644 changelogs/application_service/pyproject.toml diff --git a/changelogs/application_service.rst b/changelogs/application_service.rst new file mode 100644 index 00000000..e69de29b diff --git a/changelogs/application_service/newsfragments/.gitignore b/changelogs/application_service/newsfragments/.gitignore new file mode 100644 index 00000000..b722e9e1 --- /dev/null +++ b/changelogs/application_service/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelogs/application_service/pyproject.toml b/changelogs/application_service/pyproject.toml new file mode 100644 index 00000000..44d430e8 --- /dev/null +++ b/changelogs/application_service/pyproject.toml @@ -0,0 +1,30 @@ +[tool.towncrier] + filename = "../application_service.rst" + directory = "newsfragments" + issue_format = "`#{issue} `_" + title_format = "{version}" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "new" + name = "New Endpoints" + showcontent = true + + [[tool.towncrier.type]] + directory = "feature" + name = "Backwards Compatible Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "clarification" + name = "Spec Clarifications" + showcontent = true diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 16c40af5..8bd8537f 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -518,6 +518,10 @@ if __name__ == '__main__': "--server_release", "-s", action="store", default="unstable", help="The server-server release tag to generate, e.g. r1.2" ) + parser.add_argument( + "--appservice_release", "-a", action="store", default="unstable", + help="The appservice release tag to generate, e.g. r1.2" + ) parser.add_argument( "--list_targets", action="store_true", help="Do not update the specification. Instead print a list of targets.", @@ -542,6 +546,8 @@ if __name__ == '__main__': "%CLIENT_MAJOR_VERSION%": "r0", "%SERVER_RELEASE_LABEL%": args.server_release, "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), + "%APPSERVICE_MAJOR_VERSION%": "unstable", + "%APPSERVICE_RELEASE_LABEL%": args.appservice_release, } exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions)) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 1a93c723..b3c7d402 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -32,6 +32,10 @@ class MatrixSections(Sections): changelogs = self.units.get("changelogs") return changelogs["client_server"] + def render_application_service_changelog(self): + changelogs = self.units.get("changelogs") + return changelogs["application_service"] + def _render_events(self, filterFn, sortFn): template = self.env.get_template("events.tmpl") examples = self.units.get("event_examples") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..9423dfc8 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -754,6 +754,7 @@ class MatrixUnits(Units): def load_apis(self, substitutions): cs_ver = substitutions.get("%CLIENT_RELEASE_LABEL%", "unstable") fed_ver = substitutions.get("%SERVER_RELEASE_LABEL%", "unstable") + as_ver = substitutions.get("%APPSERVICE_RELEASE_LABEL%", "unstable") # we abuse the typetable to return this info to the templates return TypeTable(rows=[ @@ -766,8 +767,8 @@ class MatrixUnits(Units): fed_ver, "Federation between servers", ), TypeTableRow( - "`Application Service API `_", - "unstable", + "`Application Service API `_", + as_ver, "Privileged server plugins", ), TypeTableRow( "`Identity Service API `_", diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 51280341..97a2c04a 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -30,13 +30,21 @@ irrespective of the underlying homeserver implementation. .. contents:: Table of Contents .. sectnum:: -Specification version ---------------------- +Changelog +--------- + + +.. topic:: Version: unstable +{{application_service_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. +For the full historical changelog, see +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/application_service.rst + + Application Services -------------------- Application services are passive and can only observe events from a given diff --git a/specification/targets.yaml b/specification/targets.yaml index acf4b6ac..42a50e35 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -13,7 +13,7 @@ targets: application_service: files: - application_service_api.rst - version_label: unstable + version_label: "%APPSERVICE_RELEASE_LABEL%" server_server: files: - server_server_api.rst From f01cfa2c7bdd1d43109ac3acfc7b016b661e29db Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 11:39:39 -0600 Subject: [PATCH 170/240] Add security definitions to hs->as endpoints --- .../definitions/security.yaml | 18 ++++++++++++++++++ api/application-service/protocols.yaml | 12 ++++++++++++ api/application-service/query_room.yaml | 4 ++++ api/application-service/query_user.yaml | 4 ++++ api/application-service/transactions.yaml | 4 ++++ 5 files changed, 42 insertions(+) create mode 100644 api/application-service/definitions/security.yaml diff --git a/api/application-service/definitions/security.yaml b/api/application-service/definitions/security.yaml new file mode 100644 index 00000000..bcfc69c0 --- /dev/null +++ b/api/application-service/definitions/security.yaml @@ -0,0 +1,18 @@ +# 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. +homeserverAccessToken: + type: apiKey + description: The ``hs_token`` provided by the application service's registration. + name: access_token + in: query diff --git a/api/application-service/protocols.yaml b/api/application-service/protocols.yaml index e6489cc5..d58710a4 100644 --- a/api/application-service/protocols.yaml +++ b/api/application-service/protocols.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/_matrix/app/unstable/thirdparty/protocol/{protocol}": get: @@ -33,6 +35,8 @@ paths: with specific information about the various third party networks that an application service supports. operationId: getProtocolMetadata + security: + - homeserverAccessToken: [] parameters: - in: path name: protocol @@ -80,6 +84,8 @@ paths: User ID linked to a user on the third party network, given a set of user parameters. operationId: queryUserByProtocol + security: + - homeserverAccessToken: [] parameters: - in: path name: protocol @@ -131,6 +137,8 @@ paths: description: |- Retrieve a list of Matrix portal rooms that lead to the matched third party location. operationId: queryLocationByProtocol + security: + - homeserverAccessToken: [] parameters: - in: path name: protocol @@ -183,6 +191,8 @@ paths: Retrieve an array of third party network locations from a Matrix room alias. operationId: queryLocationByAlias + security: + - homeserverAccessToken: [] parameters: - in: query name: alias @@ -227,6 +237,8 @@ paths: description: |- Retrieve an array of third party users from a Matrix User ID. operationId: queryUserByID + security: + - homeserverAccessToken: [] parameters: - in: query name: userid diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index b885cb86..f388affe 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -25,6 +25,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/rooms/{roomAlias}": get: @@ -36,6 +38,8 @@ paths: homeserver will send this request when it receives a request to join a room alias within the application service's namespace. operationId: queryRoomByAlias + security: + - homeserverAccessToken: [] parameters: - in: path name: roomAlias diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 0431b5e4..5cb8d900 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -25,6 +25,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/users/{userId}": get: @@ -36,6 +38,8 @@ paths: send this request when it receives an event for an unknown user ID in the application service's namespace, such as a room invite. operationId: queryUserById + security: + - homeserverAccessToken: [] parameters: - in: path name: userId diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml index 8735cc8f..53291116 100644 --- a/api/application-service/transactions.yaml +++ b/api/application-service/transactions.yaml @@ -23,6 +23,8 @@ schemes: basePath: "/" produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/transactions/{txnId}": put: @@ -35,6 +37,8 @@ paths: from message events via the presence of a ``state_key``, rather than via the event type. operationId: sendTransaction + security: + - homeserverAccessToken: [] parameters: - in: path name: txnId From 07153c22a941a8de243031b2ef661c4e6e4b6866 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 16:54:53 -0600 Subject: [PATCH 171/240] Misc. cleanup of the appservice spec --- specification/application_service_api.rst | 24 +++++++++++------------ 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 97a2c04a..f3205302 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -48,12 +48,12 @@ https://github.com/matrix-org/matrix-doc/blob/master/changelogs/application_serv Application Services -------------------- Application services are passive and can only observe events from a given -homeserver (HS). They can inject events into rooms they are participating in. +homeserver. They can inject events into rooms they are participating in. They cannot prevent events from being sent, nor can they modify the content of the event being sent. In order to observe events from a homeserver, the homeserver needs to be configured to pass certain types of traffic to the application service. This is achieved by manually configuring the homeserver -with information about the application service (AS). +with information about the application service. Registration ~~~~~~~~~~~~ @@ -187,24 +187,24 @@ events. Each list of events includes a transaction ID, which works as follows: Typical HS ---> AS : Homeserver sends events with transaction ID T. - <--- : AS sends back 200 OK. + <--- : Application Service sends back 200 OK. AS ACK Lost HS ---> AS : Homeserver sends events with transaction ID T. <-/- : AS 200 OK is lost. HS ---> AS : Homeserver retries with the same transaction ID of T. - <--- : AS sends back 200 OK. If the AS had processed these events - already, it can NO-OP this request (and it knows if it is the same - events based on the transaction ID). + <--- : Application Service sends back 200 OK. If the AS had processed these + events already, it can NO-OP this request (and it knows if it is the + same events based on the transaction ID). The events sent to the application service should be linearised, as if they were from the event stream. The homeserver MUST maintain a queue of transactions to -send to the AS. If the application service cannot be reached, the homeserver -SHOULD backoff exponentially until the application service is reachable again. +send to the application service. If the application service cannot be reached, the +homeserver SHOULD backoff exponentially until the application service is reachable again. As application services cannot *modify* the events in any way, these requests can 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 -on retries, as the AS may have already processed the events. +on retries, as the application service may have already processed the events. {{transactions_as_http_api}} @@ -313,7 +313,7 @@ Notes: :: - PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 + PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 Authorization: Bearer YourApplicationServiceTokenHere Content: The event to send, as per the Client-Server API. @@ -334,7 +334,7 @@ users needs API changes in order to: - Have a 'passwordless' user. This involves bypassing the registration flows entirely. This is achieved by -including the AS token on a ``/register`` request, along with a login type of +including the ``as_token`` on a ``/register`` request, along with a login type of ``m.login.application_service`` to set the desired user ID without a password. :: @@ -374,8 +374,6 @@ additional parameters on the ``/publicRooms`` client-server endpoint. Event fields ~~~~~~~~~~~~ -.. TODO-TravisR: Fix this section to be a general "3rd party networks" section - We recommend that any events that originated from a remote network should include an ``external_url`` field in their content to provide a way for Matrix clients to link into the 'native' client from which the event originated. From 6f80db5ddf1a9851cdc3b8f9e167a3e805db28c1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 Aug 2018 17:21:12 -0600 Subject: [PATCH 172/240] Include the "other versions" section of the changelog --- specification/application_service_api.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index f3205302..4b42707d 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -44,6 +44,13 @@ This version of the specification is generated from For the full historical changelog, see https://github.com/matrix-org/matrix-doc/blob/master/changelogs/application_service.rst +Other versions of this specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following other versions are also available, in reverse chronological order: + +- `HEAD `_: Includes all changes since the latest versioned release. + Application Services -------------------- From 39e674ccb355af61bcfef92be4b557f53db46ea4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:27:48 -0600 Subject: [PATCH 173/240] Clarify what matrix.to is and mention that room IDs are not routable Also actually render the warning saying that this scheme is temporary. --- specification/appendices/identifier_grammar.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index eba443e2..e72fdada 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -287,8 +287,10 @@ domain). matrix.to navigation ++++++++++++++++++++ -.. NOTE: +.. NOTE:: This namespacing is in place pending a ``matrix://`` (or similar) URI scheme. + This is **not** meant to be interpreted as an available web service - see + below for more details. Rooms, users, aliases, and groups may be represented as a "matrix.to" URI. This URI can be used to reference particular objects in a given context, such @@ -307,14 +309,19 @@ followed by the identifier. Clients should not rely on matrix.to URIs falling back to a web server if accessed and instead should perform some sort of action within the client. For example, if -the user where to click on a matrix.to URI for a room alias, the client may open +the user were to click on a matrix.to URI for a room alias, the client may open a view for the user to participate in the room. Examples of matrix.to URIs are: -* Room: ``https://matrix.to/#/!somewhere:domain.com`` * Room alias: ``https://matrix.to/#/#somewhere:domain.com`` +* Room: ``https://matrix.to/#/!somewhere:domain.com`` * Permalink by room: ``https://matrix.to/#/!somewhere:domain.com/$event:example.org`` * Permalink by room alias: ``https://matrix.to/#/#somewhere:domain.com/$event:example.org`` * User: ``https://matrix.to/#/@alice:example.org`` * Group: ``https://matrix.to/#/+example:domain.com`` + +.. Note:: + Room ID permalinks are unroutable as there is no reliable domain to send requests + to upon receipt of the permalink. Clients should do their best route Room IDs to + where they need to go, however they should also be aware of `issue #1579 `_. \ No newline at end of file From 439b9d2925b306652a75240173fb9f0aec161dd7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:59:35 -0600 Subject: [PATCH 174/240] Power levels are also integers --- event-schemas/schema/m.room.power_levels | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index 13a44c70..b00d86a9 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -46,10 +46,10 @@ properties: properties: ban: description: The level required to ban a user. Defaults to 50 if unspecified. - type: number + type: integer events: additionalProperties: - type: number + type: integer description: The level required to send specific event types. This is a mapping from event type to power level required. title: Event power levels type: object @@ -57,25 +57,25 @@ properties: description: |- The default level required to send message events. Can be overridden by the ``events`` key. Defaults to 0 if unspecified. - type: number + type: integer invite: description: The level required to invite a user. Defaults to 50 if unspecified. - type: number + type: integer kick: description: The level required to kick a user. Defaults to 50 if unspecified. - type: number + type: integer redact: description: The level required to redact an event. Defaults to 50 if unspecified. - type: number + type: integer state_default: description: |- The default level required to send state events. Can be overridden by the ``events`` key. Defaults to 50 if unspecified, but 0 if there is no ``m.room.power_levels`` event at all. - type: number + type: integer users: additionalProperties: - type: number + type: integer description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. title: User power levels type: object @@ -84,7 +84,7 @@ properties: The default power level for every user in the room, unless their ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if unspecified. - type: number + type: integer type: object state_key: description: A zero-length string. From 4b05194a913e210585febe3df1864d2b6e384eab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:18:14 -0600 Subject: [PATCH 175/240] Fix bad merge --- event-schemas/examples/m.room.member#invite_room_state | 7 ------- 1 file changed, 7 deletions(-) diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index 44f160c2..7055d0a0 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -21,13 +21,6 @@ "join_rule": "invite" } } - }, - { - "type": "m.room.join_rules", - "state_key": "", - "content": { - "join_rule": "invite" - } } ] } From 8e42f3ab3a3de8a7eba1d9f5354a140d45c3ec65 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:26:08 -0600 Subject: [PATCH 176/240] Fix bad merge on brackets --- event-schemas/examples/m.room.member#invite_room_state | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index 7055d0a0..cbd76100 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -21,6 +21,6 @@ "join_rule": "invite" } } - } - ] + ] + } } From cff5b8b205d8b86bacc3ab75171f47f7b427a2dc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:30:46 -0600 Subject: [PATCH 177/240] More versioned links --- specification/server_server_api.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index ccebc313..d04c0407 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1089,9 +1089,9 @@ that are too long. .. |/query/directory| replace:: ``/query/directory`` .. _/query/directory: #get-matrix-federation-%SERVER_MAJOR_VERSION%-query-directory -.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage -.. _`Identity Service API`: ../identity_service/unstable.html -.. _`Client-Server API`: ../client_server/unstable.html +.. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage +.. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html +.. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 From 72c6fa2aaf73af1af9da40c3bdbc31de8369ce7c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:33:03 -0600 Subject: [PATCH 178/240] More versioned links --- specification/modules/push.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e9ee8c90..492e8291 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -623,4 +623,4 @@ should send a "sync" command to instruct the client to get new events from the homeserver directly. -.. _`Push Gateway Specification`: ../push_gateway/unstable.html +.. _`Push Gateway Specification`: ../push_gateway/%PUSH_GATEWAY_RELEASE_LABEL%.html From fc1fdc95afb96d3b74844355d4ceada7a96b9bfa Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 28 Aug 2018 17:29:58 +0100 Subject: [PATCH 179/240] Specify a limit on the number of EDUs and PDUs a transaction can contain --- api/server-server/definitions/transaction.yaml | 2 +- api/server-server/transactions.yaml | 4 ++-- specification/server_server_api.rst | 2 ++ 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index 7df8b646..9833f785 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -31,7 +31,7 @@ properties: example: 1532991320875 pdus: type: array - description: List of persistent updates to rooms. + description: List of persistent updates to rooms. Must not include more than 50 PDUs. items: $ref: "pdu.yaml" required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 8d810ad5..ad10ec0b 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -60,8 +60,8 @@ paths: edus: type: array description: |- - List of ephemeral messages. May be omitted if there are no ephemeral - messages to be sent. + List of ephemeral messages. May be omitted if there are no ephemeral + messages to be sent. Must not include more than 100 EDUs. items: $ref: "definitions/edu.yaml" example: { diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 439b35f9..f281c21a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -262,6 +262,8 @@ of Transaction messages, which are encoded as JSON objects, passed over an HTTP PUT request. A Transaction is meaningful only to the pair of homeservers that exchanged it; they are not globally-meaningful. +Transactions are limited in size; they can have at most 50 PDUs and 100 EDUs. + {{transactions_ss_http_api}} PDUs From ee3b0f42dbc566e911b6fc0c193cb160a653c7e4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 10:34:49 -0600 Subject: [PATCH 180/240] Fix server ACL schema: The type is a string It cannot be an enum otherwise the build starts screaming. --- event-schemas/schema/m.room.server_acl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room.server_acl b/event-schemas/schema/m.room.server_acl index c6adaf05..86d83832 100644 --- a/event-schemas/schema/m.room.server_acl +++ b/event-schemas/schema/m.room.server_acl @@ -85,4 +85,4 @@ properties: type: string type: enum: ['m.room.server_acl'] - type: enum + type: string From 80edda1666063f574c211a0c992ad1ff1ec1dded Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 10:35:54 -0600 Subject: [PATCH 181/240] Actually run the check-docs circle job --- .circleci/config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index f79449f3..22a5a90a 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -78,6 +78,7 @@ workflows: jobs: - build-docs - build-swagger + - check-docs notify: webhooks: From e9579a7840692529f5fd32548cfd1beb22ee1aff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 11:01:43 -0600 Subject: [PATCH 182/240] The `rank` in search results is actually a floating point number This was accidentally changed in https://github.com/matrix-org/matrix-doc/pull/1571 and appears to be the only instance. --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 6594a913..4a5f4515 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -198,7 +198,7 @@ paths: description: The result object. properties: rank: - type: integer + type: number description: A number that describes how closely this result matches the search. Higher is closer. From 17ae84d06443405e2dce679021f80f5fb158779c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 11:05:59 -0600 Subject: [PATCH 183/240] Check the API examples too --- .circleci/config.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index 22a5a90a..77637583 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -29,6 +29,8 @@ checkexamples: &checkexamples source /env/bin/activate cd event-schemas ./check_examples.py + cd ../api + ./check_examples.py genmatrixassets: &genmatrixassets name: Generate/Verify matrix.org assets From 791a2f2b171b4bd7762a7b051317d5790fd678ce Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 12:04:20 -0600 Subject: [PATCH 184/240] Run the validator on the spec --- .circleci/config.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index 77637583..785941c7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -38,9 +38,21 @@ genmatrixassets: &genmatrixassets source /env/bin/activate ./scripts/generate-matrix-org-assets +validateapi: &validateapi + name: Validate OpenAPI specifications + command: | + cd api + npm install + node validator.js -s "client-server" version: 2 jobs: + validate-docs: + docker: + - image: node:alpine + steps: + - checkout + - run: *validateapi check-docs: docker: - image: uhoreg/matrix-doc-build @@ -81,6 +93,7 @@ workflows: - build-docs - build-swagger - check-docs + - validate-docs notify: webhooks: From ad068bcd2269df4c11fb79f7c0ce571332341251 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 12:11:36 -0600 Subject: [PATCH 185/240] Fix the appservice directory visibility type parameter type --- api/client-server/appservice_room_directory.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/appservice_room_directory.yaml b/api/client-server/appservice_room_directory.yaml index 0225ecd8..49393cd4 100644 --- a/api/client-server/appservice_room_directory.yaml +++ b/api/client-server/appservice_room_directory.yaml @@ -62,11 +62,12 @@ paths: x-example: "!somewhere:domain.com" - in: body name: body + required: true schema: type: object properties: visibility: - type: enum + type: string enum: ["public", "private"] description: |- Whether the room should be visible (public) in the directory From 349696fc1d3ce0cfe0bb7b70aeaec3b362573512 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 12:16:29 -0600 Subject: [PATCH 186/240] Test building of the speculator and continuserv --- .circleci/config.yml | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 785941c7..d92b8890 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -45,6 +45,18 @@ validateapi: &validateapi npm install node validator.js -s "client-server" +buildspeculator: &buildspeculator + name: Build Speculator + command: | + cd scripts/speculator + go build + +buildcontinuserv: &buildcontinuserv + name: Build Continuserv + command: | + cd scripts/continuserv + go build + version: 2 jobs: validate-docs: @@ -71,7 +83,6 @@ jobs: - run: name: "Doc build is available at:" command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL - build-swagger: docker: - image: uhoreg/matrix-doc-build @@ -84,6 +95,18 @@ jobs: - run: name: "Swagger UI is available at:" command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL + build-dev-scripts: + docker: + - image: golang:1.8 + steps: + - checkout + - run: + name: Install Dependencies + command: | + go get github.com/hashicorp/golang-lru + go get gopkg.in/fsnotify/fsnotify.v1 + - run: *buildcontinuserv + - run: *buildspeculator workflows: version: 2 From e97a1b4af029a672905ba8c0ff8102ca9c50c9ae Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 12:17:41 -0600 Subject: [PATCH 187/240] Actually add the dev scripts build to the workflow --- .circleci/config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index d92b8890..4a8505b7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -117,6 +117,7 @@ workflows: - build-swagger - check-docs - validate-docs + - build-dev-scripts notify: webhooks: From 132c5b0f48d2e29bbefed62ff1108ae6aba34957 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 12:20:30 -0600 Subject: [PATCH 188/240] Verbose building for go scripts --- .circleci/config.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 4a8505b7..659380b0 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -49,13 +49,13 @@ buildspeculator: &buildspeculator name: Build Speculator command: | cd scripts/speculator - go build + go build -v buildcontinuserv: &buildcontinuserv name: Build Continuserv command: | cd scripts/continuserv - go build + go build -v version: 2 jobs: @@ -103,8 +103,8 @@ jobs: - run: name: Install Dependencies command: | - go get github.com/hashicorp/golang-lru - go get gopkg.in/fsnotify/fsnotify.v1 + go get -v github.com/hashicorp/golang-lru + go get -v gopkg.in/fsnotify/fsnotify.v1 - run: *buildcontinuserv - run: *buildspeculator From c297c6a35d831f52e0518952725c0992858219e1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 13:06:52 -0600 Subject: [PATCH 189/240] Update schemas and auth rules to cover the @ state key restriction Fixes https://github.com/matrix-org/matrix-doc/issues/1305 Also fixes an issue regarding the `_` being restricted previously, which is false. --- event-schemas/schema/core-event-schema/state_event.yaml | 6 +++++- event-schemas/schema/m.room.member | 5 ++++- specification/server_server_api.rst | 5 ++++- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/event-schemas/schema/core-event-schema/state_event.yaml b/event-schemas/schema/core-event-schema/state_event.yaml index 020e9087..71c4137b 100644 --- a/event-schemas/schema/core-event-schema/state_event.yaml +++ b/event-schemas/schema/core-event-schema/state_event.yaml @@ -11,7 +11,11 @@ properties: state_key: description: A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this - key makes this event a State Event. The key MUST NOT start with '_'. + key makes this event a State Event. + + State keys starting with an ``@`` are reserved for referencing user IDs, such + as room members. With the exception of a few events, state events set with a + given user's ID as the state key MUST only be set by that user. type: string required: - state_key diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index 5fb5356d..de14644d 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -105,7 +105,10 @@ properties: title: EventContent type: object state_key: - description: The ``user_id`` this membership event relates to. + description: |- + The ``user_id`` this membership event relates to. In all cases except for when ``membership`` is + ``join``, the user ID sending the event does not need to match the user ID in the ``state_key``, + unlike other events. Regular authorisation rules still apply. type: string type: enum: diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 439b35f9..a66f249c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -450,7 +450,10 @@ The rules are as follows: #. Otherwise, reject. -7. Otherwise, allow. +7. If the ``state_key`` starts with ``@`` and the ``state_key`` does not match + the ``sender``, reject. + +8. Otherwise, allow. .. NOTE:: From 85b9769cd9ea101f7d6b10259a983e0b620c9e61 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 14:06:55 -0600 Subject: [PATCH 190/240] Comment out the timestamp massaging section for now Pending discussion on https://github.com/matrix-org/matrix-doc/issues/1585 --- specification/application_service_api.rst | 31 ++++++++++++----------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 51280341..0da00b87 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -289,26 +289,27 @@ An example request would be:: GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org Authorization: Bearer YourApplicationServiceTokenHere +.. TODO-TravisR: Temporarily take out timestamp massaging while we're releasing r0. + See https://github.com/matrix-org/matrix-doc/issues/1585 +.. Timestamp massaging + +++++++++++++++++++ + The application service may want to inject events at a certain time (reflecting + the time on the network they are tracking e.g. irc, xmpp). Application services + need to be able to adjust the ``origin_server_ts`` value to do this. -Timestamp massaging -+++++++++++++++++++ -The application service may want to inject events at a certain time (reflecting -the time on the network they are tracking e.g. irc, xmpp). Application services -need to be able to adjust the ``origin_server_ts`` value to do this. + Inputs: + - Application service token (``as_token``) + - Desired timestamp (in milliseconds since the unix epoch) -Inputs: - - Application service token (``as_token``) - - Desired timestamp (in milliseconds since the unix epoch) - -Notes: - - This will only apply when sending events. + Notes: + - This will only apply when sending events. -:: + :: - PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 - Authorization: Bearer YourApplicationServiceTokenHere + PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 + Authorization: Bearer YourApplicationServiceTokenHere - Content: The event to send, as per the Client-Server API. + Content: The event to send, as per the Client-Server API. Server admin style permissions ++++++++++++++++++++++++++++++ From 436544b8f8b8b6cf2e05744fa6f9b14ef4db40ed Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 14:19:55 -0600 Subject: [PATCH 191/240] Clarify behaviour of `?set_presence=unavailable` for /sync --- api/client-server/sync.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index f20798c0..21af0d1e 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -83,7 +83,8 @@ paths: polling this API. If this parameter is omitted then the client is automatically marked as online when it uses this API. Otherwise if the parameter is set to "offline" then the client is not marked as - being online when it uses this API. + being online when it uses this API. When set to "unavailable", the + client is marked as being idle. x-example: "offline" - in: query name: timeout From 4df67d9305d53d05fcbb355d9527030d64e6dd64 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 14:20:02 -0600 Subject: [PATCH 192/240] changelog --- changelogs/client_server/newsfragments/780.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/780.feature diff --git a/changelogs/client_server/newsfragments/780.feature b/changelogs/client_server/newsfragments/780.feature new file mode 100644 index 00000000..74725754 --- /dev/null +++ b/changelogs/client_server/newsfragments/780.feature @@ -0,0 +1 @@ +Add more presence options to the ``set_presence`` parameter of ``/sync``. (Thanks @mujx!) From b402608b41ee1e6a73f8e89296ebbfed4bbff3e9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 14:40:14 -0600 Subject: [PATCH 193/240] Don't reference the major version for the push gateway specification If we ever have a v2 endpoint for the push gateway, we'd likely spec it alongside the v1 stuff, updating applicable references elsewhere. --- api/push-gateway/push_notifier.yaml | 2 +- scripts/gendoc.py | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 21c1ea29..4a6cb8f7 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/push/%PUSH_GATEWAY_MAJOR_VERSION% +basePath: /_matrix/push/v1 consumes: - application/json produces: diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 042e3d9d..8745d3e2 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -546,7 +546,6 @@ if __name__ == '__main__': "%CLIENT_MAJOR_VERSION%": "r0", "%SERVER_RELEASE_LABEL%": args.server_release, "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), - "%PUSH_GATEWAY_MAJOR_VERSION%": "v1", "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release, } From dad037170a24219aa76bfdeca2c7b5b6b577b1e8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 15:45:50 -0600 Subject: [PATCH 194/240] Clarify that the requested event is excluded from /state and /state_ids Fixes https://github.com/matrix-org/matrix-doc/issues/1564 --- api/server-server/events.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index cf3988a2..f0b30178 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -50,7 +50,7 @@ paths: 200: description: |- The fully resolved state for the room, including the authorization - chain for the events. + chain for the events, excluding the requested event. schema: type: object properties: @@ -97,7 +97,7 @@ paths: 200: description: |- The fully resolved state for the room, including the authorization - chain for the events. + chain for the events, excluding the requested event. schema: type: object properties: From 6f3b42a457c7fc7973fb07847840143ffc7164e3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 28 Aug 2018 23:56:20 +0100 Subject: [PATCH 195/240] Server names cannot be %-encoded They aren't URLs; it was a thinko to refer to the URL spec for this. --- .../appendices/identifier_grammar.rst | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index fc89f031..d068b768 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -23,13 +23,38 @@ A homeserver is uniquely identified by its server name. This value is used in a number of identifiers, as described below. The server name represents the address at which the homeserver in question can -be reached by other homeservers. The complete grammar is:: +be reached by other homeservers. All valid server names are included by the +following grammar:: - server_name = host [ ":" port] - port = *DIGIT + server_name = host [ ":" port ] -where ``host`` is as defined by `RFC3986, section 3.2.2 -`_. + port = *DIGIT + + host = IPv4address / "[" IPv6address "]" / dns-name + + IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT + + IPv6address = 2*45IPv6char + + IPv6char = DIGIT / %x41-46 / %x61-66 / ":" / "." + ; 0-9, A-F, a-f, :, . + + dns-name = *255dns-char + + dns-char = DIGIT / ALPHA / "-" / "." + +-- in other words, the server name is the hostname, followed by an optional +numeric port specifier. The hostname may be a dotted-quad IPv4 address literal, +an IPv6 address literal surrounded with square brackets, or a DNS name. + +IPv4 literals must be a sequence of four decimal numbers in the +range 0 to 255, separated by ".". IPv6 literals must be as specified by +`RFC3513, section 2.2 `_. + +DNS names for use with Matrix should follow the conventional restrictions for +internet hostnames: they should consist of a series of labels separated by +dots, where each label consists of the alphanumeric characters or +hyphens. Examples of valid server names are: @@ -40,6 +65,20 @@ Examples of valid server names are: * ``[1234:5678::abcd]`` (IPv6 literal) * ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port) +.. Note:: + + This grammar is based on the standard for internet host names, as specified + by `RFC1123, section 2.1 `_, + with an extension for IPv6 literals. + +Server names must be treated case-sensitively: in other words, +``@user:matrix.org`` is a different person from ``@user:MATRIX.ORG``. + +Some recommendations for a choice of server name follow: + +* The length of the complete server name should not exceed 230 characters. +* Server names should not use upper-case characters. + Room Versions ~~~~~~~~~~~~~ @@ -51,7 +90,7 @@ 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 ``-``. +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 ``.`` From 7f9524f8016f4cdfb35c0434cd45619859326f87 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 00:07:36 +0100 Subject: [PATCH 196/240] =?UTF-8?q?s/--/=E2=80=94/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specification/appendices/identifier_grammar.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index d068b768..e686f0c6 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -43,7 +43,7 @@ following grammar:: dns-char = DIGIT / ALPHA / "-" / "." --- in other words, the server name is the hostname, followed by an optional +— in other words, the server name is the hostname, followed by an optional numeric port specifier. The hostname may be a dotted-quad IPv4 address literal, an IPv6 address literal surrounded with square brackets, or a DNS name. From 8679a642b49d865c628ef6f598f374f273e6e8b1 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 00:19:05 +0100 Subject: [PATCH 197/240] clarity --- specification/appendices/identifier_grammar.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index e686f0c6..92db2fec 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -48,13 +48,12 @@ numeric port specifier. The hostname may be a dotted-quad IPv4 address literal, an IPv6 address literal surrounded with square brackets, or a DNS name. IPv4 literals must be a sequence of four decimal numbers in the -range 0 to 255, separated by ".". IPv6 literals must be as specified by +range 0 to 255, separated by ``.``. IPv6 literals must be as specified by `RFC3513, section 2.2 `_. DNS names for use with Matrix should follow the conventional restrictions for internet hostnames: they should consist of a series of labels separated by -dots, where each label consists of the alphanumeric characters or -hyphens. +``.``, where each label consists of the alphanumeric characters or hyphens. Examples of valid server names are: From d91395cf9fe0c368436fd810a11959412b2aa979 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 19:33:45 -0600 Subject: [PATCH 198/240] Document 403 error for sending state events Fixes https://github.com/matrix-org/matrix-doc/issues/1399 --- api/client-server/room_state.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index c04fb803..bda66eb8 100644 --- a/api/client-server/room_state.yaml +++ b/api/client-server/room_state.yaml @@ -87,6 +87,16 @@ paths: type: string description: |- A unique identifier for the event. + 403: + description: |- + The sender doesn't have permission to send the event into the room. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the event." + } tags: - Room participation "/rooms/{roomId}/state/{eventType}": @@ -142,5 +152,15 @@ paths: type: string description: |- A unique identifier for the event. + 403: + description: |- + The sender doesn't have permission to send the event into the room. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the event." + } tags: - Room participation From d1add1f58c983c5ece0994c7d7c3ef80d0841d0a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 19:34:58 -0600 Subject: [PATCH 199/240] Changelog --- changelogs/client_server/newsfragments/1590.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1590.clarification diff --git a/changelogs/client_server/newsfragments/1590.clarification b/changelogs/client_server/newsfragments/1590.clarification new file mode 100644 index 00000000..27999193 --- /dev/null +++ b/changelogs/client_server/newsfragments/1590.clarification @@ -0,0 +1 @@ +Document the 403 error for sending state events. From 120bb8dc8eb3261f71dfc0b27e4b42c76003f808 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:24:24 +0100 Subject: [PATCH 200/240] s/host/hostname/ --- specification/appendices/identifier_grammar.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 92db2fec..1a46ae1a 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -26,11 +26,11 @@ The server name represents the address at which the homeserver in question can be reached by other homeservers. All valid server names are included by the following grammar:: - server_name = host [ ":" port ] + server_name = hostname [ ":" port ] port = *DIGIT - host = IPv4address / "[" IPv6address "]" / dns-name + hostname = IPv4address / "[" IPv6address "]" / dns-name IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT From 08fba5de51b09e3abecf6247218146fa917f9576 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:25:38 +0100 Subject: [PATCH 201/240] Link to grammar rather than duplicating. --- specification/server_server_api.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 439b35f9..910dab1d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -78,14 +78,7 @@ Resolving Server Names ~~~~~~~~~~~~~~~~~~~~~~ Each matrix homeserver is identified by a server name consisting of a hostname -and an optional TLS port. - -.. code:: - - server_name = hostname [ ":" tls_port] - tls_port = *DIGIT - -.. ** +and an optional port, as described by the `grammar <../appendices.html#server-name>`_. If the port is present then the server is discovered by looking up an AAAA or A record for the hostname and connecting to the specified TLS port. If the port From f15eafae7fbc2f38bc8142c7067fbbda4e654b4a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:26:31 +0100 Subject: [PATCH 202/240] Remove trailing spaces --- specification/server_server_api.rst | 34 ++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 439b35f9..b4da5632 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -26,9 +26,9 @@ to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to retrieve historic messages from each other, and to query profile and presence information about users on each other's servers. -The APIs are implemented using HTTPS requests between each of the servers. -These HTTPS requests are strongly authenticated using public key signatures -at the TLS transport layer and using public key signatures in HTTP +The APIs are implemented using HTTPS requests between each of the servers. +These HTTPS requests are strongly authenticated using public key signatures +at the TLS transport layer and using public key signatures in HTTP Authorization headers at the HTTP layer. There are three main kinds of communication that occur between homeservers: @@ -121,7 +121,7 @@ Retrieving Server Keys Each homeserver publishes its public keys under ``/_matrix/key/v2/server/{keyId}``. Homeservers query for keys by either getting ``/_matrix/key/v2/server/{keyId}`` directly or by querying an intermediate notary server using a -``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers +``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys. @@ -590,9 +590,9 @@ To cover this case, the federation API provides a server-to-server analog of the ``/messages`` client API, allowing one homeserver to fetch history from another. This is the ``/backfill`` API. -To request more history, the requesting homeserver picks another homeserver -that it thinks may have more (most likely this should be a homeserver for -some of the existing users in the room at the earliest point in history it +To request more history, the requesting homeserver picks another homeserver +that it thinks may have more (most likely this should be a homeserver for +some of the existing users in the room at the earliest point in history it has currently), and makes a ``/backfill`` request. Similar to backfilling a room's history, a server may not have all the events @@ -669,10 +669,10 @@ homeservers, though most in practice will use just two. The first part of the handshake usually involves using the directory server to request the room ID and join candidates through the |/query/directory|_ API endpoint. In the case of a new user joining a room as a result of a received -invite, the joining user's homeserver could optimise this step away by picking -the origin server of that invite message as the join candidate. However, the +invite, the joining user's homeserver could optimise this step away by picking +the origin server of that invite message as the join candidate. However, the joining server should be aware that the origin server of the invite might since -have left the room, so should be prepared to fall back on the regular join flow +have left the room, so should be prepared to fall back on the regular join flow if this optimisation fails. Once the joining server has the room ID and the join candidates, it then needs @@ -692,7 +692,7 @@ event to a resident homeserver, by using the ``PUT /send_join`` endpoint. The resident homeserver then accepts this event into the room's event graph, and responds to the joining server with the full set of state for the newly-joined room. The resident server must also send the event to other servers -participating in the room. +participating in the room. {{joins_ss_http_api}} @@ -716,8 +716,8 @@ Leaving Rooms (Rejecting Invites) Normally homeservers can send appropriate ``m.room.member`` events to have users leave the room, or to reject local invites. Remote invites from other homeservers -do not involve the server in the graph and therefore need another approach to -reject the invite. Joining the room and promptly leaving is not recommended as +do not involve the server in the graph and therefore need another approach to +reject the invite. Joining the room and promptly leaving is not recommended as clients and servers will interpret that as accepting the invite, then leaving the room rather than rejecting the invite. @@ -829,7 +829,7 @@ EDUs. There are no PDUs or Federation Queries involved. Servers should only send presence updates for users that the receiving server would be interested in. This can include the receiving server sharing a room -with a given user, or a user on the receiving server has added one of the +with a given user, or a user on the receiving server has added one of the sending server's users to their presence list. Clients may define lists of users that they are interested in via "Presence @@ -848,7 +848,7 @@ or ``m.presence_deny`` EDU back. {{definition_ss_event_schemas_m_presence_invite}} -{{definition_ss_event_schemas_m_presence_accept}} +{{definition_ss_event_schemas_m_presence_accept}} {{definition_ss_event_schemas_m_presence_deny}} @@ -881,11 +881,11 @@ that can be made. OpenID ------ -Third party services can exchange an access token previously generated by the +Third party services can exchange an access token previously generated by the `Client-Server API` for information about a user. This can help verify that a user is who they say they are without granting full access to the user's account. -Access tokens generated by the OpenID API are only good for the OpenID API and +Access tokens generated by the OpenID API are only good for the OpenID API and nothing else. {{openid_ss_http_api}} From 78d81188468ba80e2a6d75566a70472d35a81089 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:36:50 +0100 Subject: [PATCH 203/240] Further server_name clarification --- specification/server_server_api.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 910dab1d..d9edfcb3 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -80,18 +80,22 @@ Resolving Server Names Each matrix homeserver is identified by a server name consisting of a hostname and an optional port, as described by the `grammar <../appendices.html#server-name>`_. -If the port is present then the server is discovered by looking up an AAAA or -A record for the hostname and connecting to the specified TLS port. If the port -is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV -record for the hostname. If this record does not exist then the server is -discovered by looking up an AAAA or A record on the hostname and taking the -default fallback port number of 8448. +If the hostname is an IP literal, then that IP address should be used, together +with the given port number, or 8448 if no port is given. + +Otherwise, if the port is present, then an IP address is discovered by looking +up an AAAA or A record for the hostname, and the specified port is used. + +If the hostname is not an IP literal and no port is given, the server is +discovered by first looking up a ``_matrix._tcp`` SRV record for the hostname, +which may give a hostname (to be looked up using AAAA or A queries) and port. +If the SRV record does not exist, then the server is discovered by looking up +an AAAA or A record on the hostname and taking the default fallback port number +of 8448. + Homeservers may use SRV records to load balance requests between multiple TLS endpoints or to failover to another endpoint if an endpoint fails. -If the DNS name is a literal IP address, the port specified or the fallback -port should be used. - When making requests to servers, use the DNS name of the target server in the ``Host`` header, regardless of the host given in the SRV record. For example, if making a request to ``example.org``, and the SRV record resolves to ``matrix. From d493c82e82c49c8f252cb06554a51f7ef136be11 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 10:04:02 +0100 Subject: [PATCH 204/240] even more clarification --- specification/server_server_api.rst | 54 ++++++++++++++++------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index d9edfcb3..8cce792b 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -71,36 +71,40 @@ This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. -Server Discovery +Server discovery ---------------- -Resolving Server Names +Resolving server names ~~~~~~~~~~~~~~~~~~~~~~ Each matrix homeserver is identified by a server name consisting of a hostname -and an optional port, as described by the `grammar <../appendices.html#server-name>`_. - -If the hostname is an IP literal, then that IP address should be used, together -with the given port number, or 8448 if no port is given. - -Otherwise, if the port is present, then an IP address is discovered by looking -up an AAAA or A record for the hostname, and the specified port is used. - -If the hostname is not an IP literal and no port is given, the server is -discovered by first looking up a ``_matrix._tcp`` SRV record for the hostname, -which may give a hostname (to be looked up using AAAA or A queries) and port. -If the SRV record does not exist, then the server is discovered by looking up -an AAAA or A record on the hostname and taking the default fallback port number -of 8448. - -Homeservers may use SRV records to load balance requests between multiple TLS -endpoints or to failover to another endpoint if an endpoint fails. - -When making requests to servers, use the DNS name of the target server in the -``Host`` header, regardless of the host given in the SRV record. For example, -if making a request to ``example.org``, and the SRV record resolves to ``matrix. -example.org``, the ``Host`` header in the request should be ``example.org``. The -port number for target server should not appear in the ``Host`` header. +and an optional port, as described by the `grammar +<../appendices.html#server-name>`_. Server names should be resolved to an IP +address and port using the following process: + +* If the hostname is an IP literal, then that IP address should be used, + together with the given port number, or 8448 if no port is given. + +* Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for the hostname, and the specified port is + used. + +* If the hostname is not an IP literal and no port is given, the server is + discovered by first looking up a ``_matrix._tcp`` SRV record for the + hostname, which may give a hostname (to be looked up using AAAA or A queries) + and port. If the SRV record does not exist, then the server is discovered by + looking up an AAAA or A record on the hostname and taking the default + fallback port number of 8448. + + Homeservers may use SRV records to load balance requests between multiple TLS + endpoints or to failover to another endpoint if an endpoint fails. + +When making requests to servers, use the hostname of the target server in the +``Host`` header, regardless of the any hostname given in the SRV record. For +example, if the server name is ``example.org``, and the SRV record resolves to +``matrix.example.org``, the ``Host`` header in the request should be +``example.org``. The port number for target server should **not** appear in the +``Host`` header. Server implementation ~~~~~~~~~~~~~~~~~~~~~~ From 688c8ebcd348736d97cad2970e2e0b7533a3e103 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 Aug 2018 10:17:20 -0400 Subject: [PATCH 205/240] specify how to handle multiple olm sessions with the same device --- specification/modules/end_to_end_encryption.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index fa461cc2..6f192596 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -391,6 +391,12 @@ this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm payload. This is crucial when the ed25519 key corresponds to a verified device. +If a client has multiple sessions established with another device, it should +use the session from which it last received a message. A client may expire old +sessions by defining a maximum number of olm sessions that it will maintain for +each device, and expiring sessions on a Least Recently Used basis. The maximum +number of olm sessions maintained per device should be at least 4. + ``m.megolm.v1.aes-sha2`` ~~~~~~~~~~~~~~~~~~~~~~~~ From 9d0fec3645fb83647b15eeb9a0819696674b259f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 Aug 2018 10:25:24 -0400 Subject: [PATCH 206/240] add changelog --- changelogs/client_server/newsfragments/1596.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1596.clarification diff --git a/changelogs/client_server/newsfragments/1596.clarification b/changelogs/client_server/newsfragments/1596.clarification new file mode 100644 index 00000000..3dde069f --- /dev/null +++ b/changelogs/client_server/newsfragments/1596.clarification @@ -0,0 +1 @@ +specify how to handle multiple olm sessions with the same device \ No newline at end of file From de36d978397d9056c9e50e46a16998fbc308b627 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 08:53:20 -0600 Subject: [PATCH 207/240] Clarify which event is actually be excluded from /state_ids --- api/server-server/events.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index f0b30178..5a5ce717 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -49,8 +49,8 @@ paths: responses: 200: description: |- - The fully resolved state for the room, including the authorization - chain for the events, excluding the requested event. + The fully resolved state for the room (excluding the requested event), + including the authorization chain for the events. schema: type: object properties: @@ -96,8 +96,8 @@ paths: responses: 200: description: |- - The fully resolved state for the room, including the authorization - chain for the events, excluding the requested event. + The fully resolved state for the room (excluding the requested event), + including the authorization chain for the events. schema: type: object properties: From 5ff244f06b106a72fe209a26e7059922f096bdb1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 09:00:46 -0600 Subject: [PATCH 208/240] More clarification about how /state_ids works --- api/server-server/events.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 5a5ce717..c23163d7 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -49,8 +49,9 @@ paths: responses: 200: description: |- - The fully resolved state for the room (excluding the requested event), - including the authorization chain for the events. + The fully resolved state for the room, prior to considering any state + changes induced by the requested event. Includes the authorization + chain for the events. schema: type: object properties: @@ -96,8 +97,9 @@ paths: responses: 200: description: |- - The fully resolved state for the room (excluding the requested event), - including the authorization chain for the events. + The fully resolved state for the room, prior to considering any state + changes induced by the requested event. Includes the authorization + chain for the events. schema: type: object properties: From 62b1b8b66097f3d8be2f9cc465335f28641d15fb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 09:32:14 -0600 Subject: [PATCH 209/240] Have unsigned.age appear on all room events This is useful for a lot of things, like bridges (appservices), VoIP handling, and clients which generally may wish to do something with the field. Might as well include it on every event, despite the recommendation of https://github.com/matrix-org/matrix-doc/issues/1524 --- event-schemas/examples/core/room_event.json | 5 ++++- event-schemas/examples/m.call.answer | 3 --- event-schemas/examples/m.call.candidates | 3 --- event-schemas/examples/m.call.hangup | 3 --- event-schemas/examples/m.call.invite | 3 --- 5 files changed, 4 insertions(+), 13 deletions(-) diff --git a/event-schemas/examples/core/room_event.json b/event-schemas/examples/core/room_event.json index fe9ff7ee..41837afb 100644 --- a/event-schemas/examples/core/room_event.json +++ b/event-schemas/examples/core/room_event.json @@ -3,5 +3,8 @@ "event_id": "$143273582443PhrSn:domain.com", "room_id": "!jEsUZKDJdhlrceRyVU:domain.com", "sender": "@example:domain.com", - "origin_server_ts": 1432735824653 + "origin_server_ts": 1432735824653, + "unsigned": { + "age": 1234 + } } diff --git a/event-schemas/examples/m.call.answer b/event-schemas/examples/m.call.answer index a7b9e883..a4cfc1e1 100644 --- a/event-schemas/examples/m.call.answer +++ b/event-schemas/examples/m.call.answer @@ -9,8 +9,5 @@ "type" : "answer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } - }, - "unsigned": { - "age": 1234 } } diff --git a/event-schemas/examples/m.call.candidates b/event-schemas/examples/m.call.candidates index 1a3fdedf..8f1f807a 100644 --- a/event-schemas/examples/m.call.candidates +++ b/event-schemas/examples/m.call.candidates @@ -11,8 +11,5 @@ "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0" } ] - }, - "unsigned": { - "age": 1234 } } diff --git a/event-schemas/examples/m.call.hangup b/event-schemas/examples/m.call.hangup index cf2d6859..295f16e4 100644 --- a/event-schemas/examples/m.call.hangup +++ b/event-schemas/examples/m.call.hangup @@ -4,8 +4,5 @@ "content": { "version" : 0, "call_id": "12345" - }, - "unsigned": { - "age": 1234 } } diff --git a/event-schemas/examples/m.call.invite b/event-schemas/examples/m.call.invite index 069d334e..fa482bd9 100644 --- a/event-schemas/examples/m.call.invite +++ b/event-schemas/examples/m.call.invite @@ -9,8 +9,5 @@ "type" : "offer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } - }, - "unsigned": { - "age": 1234 } } From 25b34e1d7bb06188f6ecb9bedef527082a06d4a6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 09:55:43 -0600 Subject: [PATCH 210/240] Mention that ts massaging was in a draft, but not in the release --- specification/application_service_api.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 0da00b87..5b7abf4a 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -311,6 +311,16 @@ An example request would be:: Content: The event to send, as per the Client-Server API. +Timestamp massaging ++++++++++++++++++++ + +Previous drafts of the Application Service API permitted application services +to alter the timestamp of their sent events by providing a ``ts`` query parameter +when sending an event. This API has been excluded from the first release due to +design concerns, however some servers may still support the feature. Please visit +`issue #1585 `_ for more +information. + Server admin style permissions ++++++++++++++++++++++++++++++ From 90fe395aeb51390c16422df1474b9c206b0a7f99 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 10:26:02 -0600 Subject: [PATCH 211/240] Take out the @ state_key restriction from the auth rules This is being handled in https://github.com/matrix-org/matrix-doc/pull/1591 --- specification/server_server_api.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a66f249c..439b35f9 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -450,10 +450,7 @@ The rules are as follows: #. Otherwise, reject. -7. If the ``state_key`` starts with ``@`` and the ``state_key`` does not match - the ``sender``, reject. - -8. Otherwise, allow. +7. Otherwise, allow. .. NOTE:: From 8e88d82a4b66f4b18aa32cd5b8700da786350aaf Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Wed, 29 Aug 2018 19:15:05 +0100 Subject: [PATCH 212/240] fix typo in anchor. fixes #1603 --- specification/modules/send_to_device.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/send_to_device.rst b/specification/modules/send_to_device.rst index 232becae..86288546 100644 --- a/specification/modules/send_to_device.rst +++ b/specification/modules/send_to_device.rst @@ -63,7 +63,7 @@ If the client sends messages to users on remote domains, those messages should be sent on to the remote servers via `federation`_. -.. _`federation`: ../server_server/latest.html#send-to-device-messages +.. _`federation`: ../server_server/latest.html#send-to-device-messaging .. TODO-spec: From c83da453b565a6f1c7c5a4a8c0e4459d5aa19795 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:18:41 -0600 Subject: [PATCH 213/240] s/number/integer --- event-schemas/schema/m.room.power_levels | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index ae4e5589..9bb12993 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -88,10 +88,10 @@ properties: notifications: properties: room: - type: number + type: integer description: The level required to trigger an ``@room`` notification. Defaults to 50 if unspecified. additionalProperties: - type: number + type: integer description: |- The power level requirements for specific notification types. This is a mapping from ``key`` to power level for that notifications key. From 196159be9116f2d82626296bd7eef44ee845f473 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 22:15:38 +0100 Subject: [PATCH 214/240] We should include the Host header if the port was explicit. --- specification/server_server_api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 8cce792b..7239c12d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -100,11 +100,12 @@ address and port using the following process: endpoints or to failover to another endpoint if an endpoint fails. When making requests to servers, use the hostname of the target server in the -``Host`` header, regardless of the any hostname given in the SRV record. For +``Host`` header, regardless of any hostname given in the SRV record. For example, if the server name is ``example.org``, and the SRV record resolves to ``matrix.example.org``, the ``Host`` header in the request should be -``example.org``. The port number for target server should **not** appear in the -``Host`` header. +``example.org``. If an explicit port was given in the server name, it should be +included in the ``Host`` header; otherwise, no port number should be given in +the ``Host`` header. Server implementation ~~~~~~~~~~~~~~~~~~~~~~ From 684d80c4228f87b0268581f3f52660e8fbbbb165 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 17:52:02 -0600 Subject: [PATCH 215/240] Revert changes to 3pid lookup types in the IS spec The validator doesn't know what a "3PID Medium" is, for example, so it throws exceptions. This does reduce clarity in the spec though. --- api/identity/lookup.yaml | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 6f993ac7..f04436ef 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -121,8 +121,11 @@ paths: minItems: 2 maxItems: 2 items: - - type: 3PID Medium - - type: 3PID Address + # TODO: Give real names to these values. Adding a `title` does not work. + #- type: 3PID Medium + #- type: 3PID Address + - type: string + - type: string description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position. required: - "threepids" @@ -147,9 +150,13 @@ paths: minItems: 3 maxItems: 3 items: - - type: 3PID Medium - - type: 3PID Address - - type: Matrix User ID + # TODO: Give real names to these values. Adding a `title` does not work. + #- type: 3PID Medium + #- type: 3PID Address + #- type: Matrix User ID + - type: string + - type: string + - type: string description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. required: - "threepids" From 2a20c11467db2e03851b456ec32bdf456273caab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 17:47:09 -0600 Subject: [PATCH 216/240] Take out the reference to the current version from the changelog --- specification/push_gateway.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e4623887..74f9e35e 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -41,7 +41,6 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. -- `r0.1.0 `_ Overview -------- From a46783eb2460198bef94ad004b99c6bfb247a0ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 17:47:09 -0600 Subject: [PATCH 217/240] Revert "Take out the reference to the current version from the changelog" This reverts commit 2a20c11467db2e03851b456ec32bdf456273caab. --- specification/push_gateway.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index 74f9e35e..e4623887 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -41,6 +41,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. +- `r0.1.0 `_ Overview -------- From c7a228bf7ba1551e0df04e583a0d86644ad1b352 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 19:32:52 -0600 Subject: [PATCH 218/240] Don't make the major version a variable We are likely to want to maintain v1 when we release a v2, so we'll avoid a variable for now. --- api/identity/associations.yaml | 2 +- api/identity/email_associations.yaml | 2 +- api/identity/invitation_signing.yaml | 2 +- api/identity/lookup.yaml | 2 +- api/identity/phone_associations.yaml | 2 +- api/identity/ping.yaml | 2 +- api/identity/pubkey.yaml | 2 +- api/identity/store_invite.yaml | 4 ++-- api/server-server/backfill.yaml | 2 +- api/server-server/event_auth.yaml | 2 +- api/server-server/events.yaml | 2 +- api/server-server/invites.yaml | 2 +- api/server-server/joins.yaml | 2 +- api/server-server/keys_query.yaml | 2 +- api/server-server/keys_server.yaml | 2 +- api/server-server/leaving.yaml | 2 +- api/server-server/openid.yaml | 2 +- api/server-server/public_rooms.yaml | 2 +- api/server-server/query.yaml | 2 +- api/server-server/third_party_invite.yaml | 2 +- api/server-server/transactions.yaml | 2 +- api/server-server/version.yaml | 2 +- scripts/gendoc.py | 3 --- specification/identity_service_api.rst | 2 +- specification/server_server_api.rst | 10 +++++----- 25 files changed, 29 insertions(+), 32 deletions(-) diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index e99ec871..4225919b 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index ef3e01ea..28f5e680 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 3a48485b..7de62dd4 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index c1751644..f04436ef 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -21,7 +21,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index e7991cee..f6b1bd45 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index b630c733..005160a3 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -23,7 +23,7 @@ basePath: /_matrix/identity produces: - application/json paths: - "/api/%IDENTITY_MAJOR_VERSION%": + "/api/v1": get: summary: Checks that an Identity server is available at this API endpopint. description: |- diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 071564d8..9cb7c74e 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index e631d60d..1eca7198 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -19,7 +19,7 @@ host: localhost:8090 schemes: - https - http -basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION% +basePath: /_matrix/identity/api/v1 produces: - application/json paths: @@ -46,7 +46,7 @@ paths: ``address`` parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on - requests to ``/_matrix/identity/api/%IDENTITY_MAJOR_VERSION%/pubkey/ephemeral/isvalid``. + requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. operationId: storeInvite parameters: - in: body diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index 5c88f554..6b3cfaef 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index 0248fb1e..8857131f 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 0b318373..cf3988a2 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 produces: - application/json securityDefinitions: diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml index d55ccb5b..6d905e17 100644 --- a/api/server-server/invites.yaml +++ b/api/server-server/invites.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 66a071e5..4902ea9e 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/keys_query.yaml b/api/server-server/keys_query.yaml index face2bd6..e616915b 100644 --- a/api/server-server/keys_query.yaml +++ b/api/server-server/keys_query.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/key/%KEYS_MAJOR_VERSION% +basePath: /_matrix/key/v2 consumes: - application/json produces: diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml index d09ba8e2..8734f2ed 100644 --- a/api/server-server/keys_server.yaml +++ b/api/server-server/keys_server.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/key/%KEYS_MAJOR_VERSION% +basePath: /_matrix/key/v2 produces: - application/json paths: diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 739f4962..be08acba 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/openid.yaml b/api/server-server/openid.yaml index 942a5d5e..0eac48c8 100644 --- a/api/server-server/openid.yaml +++ b/api/server-server/openid.yaml @@ -20,7 +20,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 produces: - application/json paths: diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml index 98736977..b7691023 100644 --- a/api/server-server/public_rooms.yaml +++ b/api/server-server/public_rooms.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 produces: - application/json securityDefinitions: diff --git a/api/server-server/query.yaml b/api/server-server/query.yaml index af70a9c3..dc14724c 100644 --- a/api/server-server/query.yaml +++ b/api/server-server/query.yaml @@ -20,7 +20,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 produces: - application/json securityDefinitions: diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 9e3bba2c..5c12247c 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index edfecac1..ad10ec0b 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 consumes: - application/json produces: diff --git a/api/server-server/version.yaml b/api/server-server/version.yaml index 17110f19..19975529 100644 --- a/api/server-server/version.yaml +++ b/api/server-server/version.yaml @@ -19,7 +19,7 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/%SERVER_MAJOR_VERSION% +basePath: /_matrix/federation/v1 produces: - application/json paths: diff --git a/scripts/gendoc.py b/scripts/gendoc.py index b7fe8155..8f5b5154 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -548,9 +548,6 @@ if __name__ == '__main__': # API URLs. When we have released a new major version, we'll # have to bump them. "%CLIENT_MAJOR_VERSION%": "r0", - "%SERVER_MAJOR_VERSION%": "v1", - "%IDENTITY_MAJOR_VERSION%": "v1", - "%KEYS_MAJOR_VERSION%": "v2", "%SERVER_RELEASE_LABEL%": args.server_release, "%IDENTITY_RELEASE_LABEL%": args.identity_release, "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release, diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 3aa50c81..3f2eb21d 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -221,7 +221,7 @@ associated with a Matrix user ID. At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below:: - POST https://bar.com:8448/_matrix/federation/%SERVER_MAJOR_VERSION%/3pid/onbind + POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind Content-Type: application/json { diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f91b7179..81fe301b 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -132,8 +132,8 @@ Retrieving Server Keys specification due to lack of significance. It may be reviewed `here `_. -Each homeserver publishes its public keys under ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}``. -Homeservers query for keys by either getting ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` +Each homeserver publishes its public keys under ``/_matrix/key/v2/server/{keyId}``. +Homeservers query for keys by either getting ``/_matrix/key/v2/server/{keyId}`` directly or by querying an intermediate notary server using a ``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and @@ -152,7 +152,7 @@ Publishing Keys +++++++++++++++ Homeservers publish the allowed TLS fingerprints and signing keys in a JSON -object at ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{key_id}``. The response contains a list of +object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of ``verify_keys`` that are valid for signing federation requests made by the homeserver and for signing events. It contains a list of ``old_verify_keys`` which are only valid for signing events. Finally the response contains a list of TLS @@ -166,7 +166,7 @@ Querying Keys Through Another Server Servers may query another server's keys through a notary server. The notary server may be another homeserver. The notary server will retrieve keys from -the queried servers through use of the ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` +the queried servers through use of the ``/_matrix/key/v2/server/{keyId}`` API. The notary server will additionally sign the response from the queried server before returning the results. @@ -1115,7 +1115,7 @@ that are too long. known hash functions like SHA-256 when none of the keys have been redacted]] .. |/query/directory| replace:: ``/query/directory`` -.. _/query/directory: #get-matrix-federation-%SERVER_MAJOR_VERSION%-query-directory +.. _/query/directory: #get-matrix-federation-v1-query-directory .. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage .. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html From f030d19f3c137be7d70319763c16c0eaee78fd39 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 20:57:41 -0600 Subject: [PATCH 219/240] Clean up identity service swagger * Add `consumes` (swagger) * Remove `http` as a supported scheme (the spec specifically says clients MUST use https) * Clarify various descriptions * Full stops * Additional wording * s/older versions/previous drafts - we haven't had a release yet * Indentation on examples --- api/identity/associations.yaml | 20 +++++++++++++------- api/identity/email_associations.yaml | 11 ++++++----- api/identity/invitation_signing.yaml | 19 ++++++++++--------- api/identity/lookup.yaml | 19 +++++++++++++------ api/identity/phone_associations.yaml | 11 +++++++---- api/identity/ping.yaml | 13 +++++++------ api/identity/pubkey.yaml | 7 ++++--- api/identity/store_invite.yaml | 13 ++++++++----- 8 files changed, 68 insertions(+), 45 deletions(-) diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 4225919b..a400bf95 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -18,15 +18,17 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: "/3pid/getValidated3pid": get: summary: Check whether ownership of a 3pid was validated. - description: A client can check whether ownership of a 3pid was validated + description: |- + Determines if a given 3pid has been validated by a user. operationId: getValidated3pid parameters: - in: query @@ -61,7 +63,9 @@ paths: description: The address of the 3pid being looked up. validated_at: type: integer - description: Timestamp indicating the time that the 3pid was validated. + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. required: ['medium', 'address', 'validated_at'] 400: description: |- @@ -78,7 +82,7 @@ paths: schema: $ref: "../client-server/definitions/errors/error.yaml" 404: - description: The Session ID or client secret were not found + description: The Session ID or client secret were not found. examples: application/json: { "errcode": "M_NO_VALID_SESSION", @@ -95,7 +99,7 @@ paths: Future calls to ``/lookup`` for any of the session\'s 3pids will return this association. - Note: for backwards compatibility with older versions of this + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. @@ -132,7 +136,6 @@ paths: "not_before": 1428825849161, "not_after": 4582425849161, "ts": 1428825849161, - "signatures": { "matrix.org": { "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" @@ -162,7 +165,10 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + description: |- + The signatures of the verifying identity services which show that the + association should be trusted, if you trust the verifying identity + services. $ref: "../../schemas/server-signatures.yaml" required: - address diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 28f5e680..dc3cd78e 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -34,13 +35,13 @@ paths: that that user was able to read the email for that email address, and so we validate ownership of the email address. - Note that Home Servers offer APIs that proxy this API, adding + Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, ``/register/email/requestToken`` is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. - Note: for backwards compatibility with older versions of this + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. @@ -58,7 +59,7 @@ paths: properties: client_secret: type: string - description: A unique string used to identify the validation attempt + description: A unique string used to identify the validation attempt. email: type: string description: The email address to validate. @@ -119,7 +120,7 @@ paths: associate the email address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - Note: for backwards compatibility with older versions of this + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 7de62dd4..0b76a773 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -29,7 +30,7 @@ paths: description: |- Sign invitation details. - The identity server will look up ``token`` which was stored in a call + The identity service will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. operationId: blindlySignStuff parameters: @@ -38,24 +39,24 @@ paths: schema: type: object example: { - "mxid": "@foo:bar.com", - "token": "sometoken", - "private_key": "base64encodedkey" - } + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } properties: mxid: type: string description: The Matrix user ID of the user accepting the invitation. token: type: string - description: Token from the call to ``store-invite`` + description: The token from the call to ``store-invite``. private_key: type: string description: The private key, encoded as `Unpadded base64`_. required: ["mxid", "token", "private_key"] responses: 200: - description: The signedjson of the mxid, sender, and token. + description: The signed JSON of the mxid, sender, and token. schema: type: object properties: @@ -85,7 +86,7 @@ paths: "token": "abc123" } 404: - description: Token was not found. + description: The token was not found. examples: application/json: { "errcode": "M_UNRECOGNIZED", diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index f04436ef..1870a31f 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -1,6 +1,7 @@ # Copyright 2016 OpenMarket Ltd # Copyright 2017 Kamax.io # Copyright 2017 New Vector 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. @@ -20,8 +21,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -46,7 +48,7 @@ paths: responses: 200: description: - The association for that 3pid, or the empty object if no association is known. + The association for that 3pid, or an empty object if no association is known. examples: application/json: { "address": "louise@bobs.burgers", @@ -66,10 +68,10 @@ paths: properties: address: type: string - description: The 3pid address of the user being looked up. + description: The 3pid address of the user being looked up, matching the address requested. medium: type: string - description: The literal string "email". + description: A medium from the `3PID Types`_ Appendix, matching the medium requested. mxid: type: string description: The Matrix user ID associated with the 3pid. @@ -126,7 +128,9 @@ paths: #- type: 3PID Address - type: string - type: string - description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position. + description: |- + An array of arrays containing the `3PID Types`_ with the ``medium`` + in first position and the ``address`` in second position. required: - "threepids" responses: @@ -157,6 +161,9 @@ paths: - type: string - type: string - type: string - description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. + description: |- + An array of array containing the `3PID Types`_ with the ``medium`` + in first position, the ``address`` in second position and Matrix user + ID in third position. required: - "threepids" diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index f6b1bd45..836984d0 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -34,13 +35,13 @@ paths: indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number. - Note that Home Servers offer APIs that proxy this API, adding + Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, ``/register/msisdn/requestToken`` is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. - Note: for backwards compatibility with older versions of this + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. @@ -106,6 +107,8 @@ paths: - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - ``M_SEND_ERROR``: The validation SMS could not be sent. + - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an + SMS to the provided country or region. examples: application/json: { "errcode": "M_INVALID_ADDRESS", @@ -125,7 +128,7 @@ paths: associate the phone number address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - Note: for backwards compatibility with older versions of this + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index 005160a3..2788d9d3 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -1,4 +1,5 @@ # Copyright 2018 Kamax Sàrl +# 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. @@ -14,7 +15,7 @@ swagger: "2.0" info: - title: "Matrix Client-Identity Versions API" + title: "Matrix Identity Service Ping API" version: "1.0.0" host: localhost:8090 schemes: @@ -25,19 +26,19 @@ produces: paths: "/api/v1": get: - summary: Checks that an Identity server is available at this API endpopint. + summary: Checks that an Identity Service is available at this API endpoint. description: |- - Checks that an Identity server is available at this API endpopint. + Checks that an Identity Service is available at this API endpoint. - To discover that an Identity server is available at a specific URL, + To discover that an Identity Service is available at a specific URL, this endpoint can be queried and will return an empty object. This is primarly used for auto-discovery and health check purposes - by entities acting as a client for the Identity server. + by entities acting as a client for the Identity Service. operationId: ping responses: 200: - description: An Identity server is ready to serve requests. + description: An Identity Service is ready to serve requests. examples: application/json: {} schema: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 9cb7c74e..6b17e7c6 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -113,8 +114,8 @@ paths: The validity of the public key. examples: application/json: { - "valid": true - } + "valid": true + } schema: type: object properties: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 1eca7198..89d437a4 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -18,16 +18,17 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: "/store-invite": post: - summary: Store pending invitations to a user\'s 3pid. + summary: Store pending invitations to a user's 3pid. description: |- - Store pending invitations to a user\'s 3pid. + Store pending invitations to a user's 3pid. In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in @@ -47,6 +48,8 @@ paths: Also, the generated ephemeral public key will be listed as valid on requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + + Currently, invites may only be issued for 3pids of the ``email`` medium. operationId: storeInvite parameters: - in: body @@ -84,7 +87,7 @@ paths: description: The generated token. public_keys: type: array - description: A list of [server\'s long-term public key, generated ephemeral public key]. + description: A list of [server's long-term public key, generated ephemeral public key]. items: type: string display_name: @@ -111,7 +114,7 @@ paths: application/json: { "errcode": "M_THREEPID_IN_USE", "error": "Binding already known", - "mxid": mxid + "mxid": "@alice:example.com" } schema: $ref: "../client-server/definitions/errors/error.yaml" From bbba7dedd6db353787646c490d3480bc73140470 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:00:47 -0600 Subject: [PATCH 220/240] Clean up identity service RST * Title casing * s/identity server/identity service * Rough column limit enforcement * Add some links (used by future commits) --- specification/identity_service_api.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 7bbd8ae8..e842f877 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -1,6 +1,7 @@ .. Copyright 2016 OpenMarket Ltd .. Copyright 2017 Kamax.io .. Copyright 2017 New Vector 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. @@ -56,7 +57,7 @@ is left as an exercise for the client. 3PID types are described in `3PID Types`_ Appendix. -API Standards +API standards ------------- The mandatory baseline for identity service communication in Matrix is exchanging @@ -146,25 +147,24 @@ Key management An identity service has some long-term public-private keypairs. These are named in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an -association, the Matrix standard JSON signing format is used, as specified in -the server-server API specification under the heading "Signing Events". +association, the standard `Signing JSON`_ algorithm applies. In the event of key compromise, the identity service may revoke any of its keys. An HTTP API is offered to get public keys, and check whether a particular key is valid. -The identity server may also keep track of some short-term public-private +The identity service may also keep track of some short-term public-private keypairs, which may have different usage and lifetime characteristics than the service's long-term keys. {{pubkey_is_http_api}} -Association Lookup +Association lookup ------------------ {{lookup_is_http_api}} -Establishing Associations +Establishing associations ------------------------- The flow for creating an association is session-based. @@ -198,7 +198,7 @@ General {{associations_is_http_api}} -Invitation Storage +Invitation storage ------------------ An identity service can store pending invitations to a user's 3pid, which will @@ -241,10 +241,14 @@ Where the signature is produced using a long-term private key. Ephemeral invitation signing ---------------------------- -To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations. -This is less secure than the client doing it itself, but may be useful where this isn't possible. +To aid clients who may not be able to perform crypto themselves, the identity +service offers some crypto functionality to help in accepting invitations. +This is less secure than the client doing it itself, but may be useful where +this isn't possible. {{invitation_signing_is_http_api}} .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types +.. _`Signing JSON`: ../appendices.html#signing-json +.. _`/3pid/onbind`: ../server_server.html#put-matrix-federation-v1-3pid-onbind From 039cefdbeaedcc3ab51746555c55a9dbb2509613 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:01:14 -0600 Subject: [PATCH 221/240] Say that identity services should be nice to web browsers (CORS/OPTIONS) --- specification/identity_service_api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index e842f877..ea607799 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -137,6 +137,22 @@ should allow a 3pid to be mapped to a Matrix user identity, but not in the other direction (i.e. one should not be able to get all 3pids associated with a Matrix user ID, or get all 3pids associated with a 3pid). +Web browser clients +------------------- + +It is realistic to expect that some clients will be written to be run within a web +browser or similar environment. In these cases, the identity service should respond to +pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all +requests. + +When a client approaches the server with a pre-flight (OPTIONS) request, the server +should respond with the CORS headers for that route. The recommended CORS headers +to be returned by servers on all requests are:: + + Access-Control-Allow-Origin: * + Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS + Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization + Status check ------------ From 0387da51e268ce79f0c27fa6e8cb7ea444ff6515 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:01:28 -0600 Subject: [PATCH 222/240] Clarify how sessions work when establishing associations --- specification/identity_service_api.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index ea607799..ab7c9b0c 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -199,6 +199,12 @@ session, within a 24 hour period since its most recent modification. Any attempts to perform these actions after the expiry will be rejected, and a new session should be created and used instead. +To start a session, the client makes a request to the appropriate ``/requestToken`` +endpoint. The user then receives a validation token which should be provided +to the client. The client then provides the token to the appropriate ``/submitToken`` +endpoint, completing the session. At this point, the client should ``/bind`` the +third party identifier or leave it for another entity to bind. + Email associations ~~~~~~~~~~~~~~~~~~ From dc602b74d2feae8fcc50463c790014bfdf96da9a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:01:49 -0600 Subject: [PATCH 223/240] Reference the server-server specification for /onbind --- specification/identity_service_api.rst | 34 +++----------------------- 1 file changed, 4 insertions(+), 30 deletions(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index ab7c9b0c..f6997ea1 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -227,36 +227,10 @@ An identity service can store pending invitations to a user's 3pid, which will be retrieved and can be either notified on or look up when the 3pid is associated with a Matrix user ID. -At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below:: - - POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind - Content-Type: application/json - - { - "medium": "email", - "address": "foo@bar.baz", - "mxid": "@alice:example.tld", - "invites": [ - { - "medium": "email", - "address": "foo@bar.baz", - "mxid": "@alice:example.tld", - "room_id": "!something:example.tld", - "sender": "@bob:example.tld", - "signed": { - "mxid": "@alice:example.tld", - "signatures": { - "vector.im": { - "ed25519:0": "somesignature" - } - }, - "token": "sometoken" - } - } - ] - } - -Where the signature is produced using a long-term private key. +At a later point, if the owner of that particular 3pid binds it with a Matrix user +ID, the identity service will attempt to make an HTTP POST to the Matrix user's +homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a +long-term private key for the identity service. {{store_invite_is_http_api}} From fd7cb22a282d2f0775212db86804d2ed334e6091 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:22:47 -0600 Subject: [PATCH 224/240] Fix event type example of m.forwarded_room_key --- event-schemas/examples/m.forwarded_room_key | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/examples/m.forwarded_room_key b/event-schemas/examples/m.forwarded_room_key index 8ab85c48..ef1d6180 100644 --- a/event-schemas/examples/m.forwarded_room_key +++ b/event-schemas/examples/m.forwarded_room_key @@ -10,5 +10,5 @@ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ] }, - "type": "m.room_key" + "type": "m.forwarded_room_key" } From b2092922e85ecf633092498dfa840c912d34c7f8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 21:51:26 -0600 Subject: [PATCH 225/240] Don't define a variable for the appservice major version --- scripts/gendoc.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 7b900562..00febdf2 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -550,7 +550,6 @@ if __name__ == '__main__': "%CLIENT_MAJOR_VERSION%": "r0", "%SERVER_RELEASE_LABEL%": args.server_release, "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), - "%APPSERVICE_MAJOR_VERSION%": "unstable", "%APPSERVICE_RELEASE_LABEL%": args.appservice_release, "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release, } From 78487a01ecae59439fec57a078ee29abeaf9362f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 23:11:00 -0600 Subject: [PATCH 226/240] Remove references to initialSync from account data and receipts module Fixes https://github.com/matrix-org/matrix-doc/issues/695 Note: This commit leaves the /join endpoints alone because they say "and /sync" rather than just initialSync --- specification/modules/account_data.rst | 2 +- specification/modules/receipts.rst | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/modules/account_data.rst b/specification/modules/account_data.rst index 1c031ee1..d0ed201a 100644 --- a/specification/modules/account_data.rst +++ b/specification/modules/account_data.rst @@ -31,7 +31,7 @@ The client recieves the account data as events in the ``account_data`` sections of a ``/sync``. These events can also be received in a ``/events`` response or in the -``account_data`` section of a room in ``/initialSync``. ``m.tag`` +``account_data`` section of a room in ``/sync``. ``m.tag`` events appearing in ``/events`` will have a ``room_id`` with the room the tags are for. diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index a6d8cbf7..faba7b62 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -38,11 +38,10 @@ single ``event_id``. Client behaviour ---------------- -In ``/initialSync``, receipts are listed in a separate top level ``receipts`` -key. In ``/sync``, receipts are contained in the ``ephemeral`` block for a -room. New receipts that come down the event streams are deltas which update -existing mappings. Clients should replace older receipt acknowledgements based -on ``user_id`` and ``receipt_type`` pairs. For example:: +In ``/sync``, receipts are listed under the ``ephemeral`` array of events +for a given room. New receipts that come down the event streams are deltas +which update existing mappings. Clients should replace older receipt acknowledgements +based on ``user_id`` and ``receipt_type`` pairs. For example:: Client receives m.receipt: user = @alice:example.com From ab14f33060e372d176dc7c3ed5440193f46e4b81 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 07:58:10 -0600 Subject: [PATCH 227/240] Add link to the client-server ACLs module --- specification/server_server_api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 244a8b82..983da62f 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1111,3 +1111,4 @@ that are too long. .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`Server ACLs`: ../client_server/unstable.html#module-server-acls From 4e90b32348155d6d09864cc66cf8c3b31abc809a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 30 Aug 2018 17:18:07 +0100 Subject: [PATCH 228/240] Set the encoding to UTF-8 on all file I/O Hopefully this will resolve issues with building the spec on systems where the default encoding is somthing other than UTF-8. --- scripts/gendoc.py | 21 ++++++++++---------- scripts/templating/matrix_templates/units.py | 18 ++++++++--------- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 8745d3e2..0719b48f 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -154,7 +154,7 @@ def get_rst(file_info, title_level, title_styles, spec_dir, adjust_titles): # string are file paths to RST blobs if isinstance(file_info, str): log("%s %s" % (">" * (1 + title_level), file_info)) - with open(os.path.join(spec_dir, file_info), "r") as f: + with open(os.path.join(spec_dir, file_info), "r", encoding="utf-8") as f: rst = None if adjust_titles: rst = load_with_adjusted_titles( @@ -186,7 +186,7 @@ def get_rst(file_info, title_level, title_styles, spec_dir, adjust_titles): def build_spec(target, out_filename): log("Building templated file %s" % out_filename) - with open(out_filename, "wb") as outfile: + with open(out_filename, "w", encoding="utf-8") as outfile: for file_info in target["files"]: section = get_rst( file_info=file_info, @@ -195,7 +195,7 @@ def build_spec(target, out_filename): spec_dir=spec_dir, adjust_titles=True ) - outfile.write(section.encode('UTF-8')) + outfile.write(section) """ @@ -223,8 +223,8 @@ def fix_relative_titles(target, filename, out_filename): "^[" + re.escape("".join(title_styles)) + "]{3,}$" ) current_title_style = None - with open(filename, "r") as infile: - with open(out_filename, "w") as outfile: + with open(filename, "r", encoding="utf-8") as infile: + with open(out_filename, "w", encoding="utf-8") as outfile: for line in infile.readlines(): if not relative_title_matcher.match(line): if title_matcher.match(line): @@ -263,8 +263,8 @@ def fix_relative_titles(target, filename, out_filename): def rst2html(i, o, stylesheets): log("rst2html %s -> %s" % (i, o)) - with open(i, "r") as in_file: - with open(o, "w") as out_file: + with open(i, "r", encoding="utf-8") as in_file: + with open(o, "w", encoding="utf-8") as out_file: publish_file( source=in_file, destination=out_file, @@ -280,16 +280,15 @@ def rst2html(i, o, stylesheets): def addAnchors(path): log("add anchors %s" % path) - with open(path, "rb") as f: + with open(path, "r", encoding="utf-8") as f: lines = f.readlines() replacement = r'

\n\1' - with open(path, "wb") as f: + with open(path, "w", encoding="utf-8") as f: for line in lines: - line = line.decode("UTF-8") line = re.sub(r'()', replacement, line.rstrip()) line = re.sub(r'(
)', replacement, line.rstrip()) - f.write((line + "\n").encode('UTF-8')) + f.write(line + "\n") def run_through_template(input_files, set_verbose, substitutions): diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 219299cd..6f9eeaa2 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -125,7 +125,7 @@ def resolve_references(path, schema): if '$ref' in schema: value = schema['$ref'] path = os.path.join(os.path.dirname(path), value) - with open(path) as f: + with open(path, encoding="utf-8") as f: ref = yaml.load(f, OrderedLoader) result = resolve_references(path, ref) del schema['$ref'] @@ -664,11 +664,11 @@ class MatrixUnits(Units): continue filepath = os.path.join(path, filename) logger.info("Reading swagger API: %s" % filepath) - with open(filepath, "r") as f: + with open(filepath, "r", encoding="utf-8") as f: # strip .yaml group_name = filename[:-5].replace("-", "_") group_name = "%s_%s" % (group_name, suffix) - api = yaml.load(f.read(), OrderedLoader) + api = yaml.load(f, OrderedLoader) api = resolve_references(filepath, api) api["__meta"] = self._load_swagger_meta( api, group_name @@ -698,11 +698,11 @@ class MatrixUnits(Units): continue filepath = os.path.join(path, filename) logger.info("Reading swagger definition: %s" % filepath) - with open(filepath, "r") as f: + with open(filepath, "r", encoding="utf-8") as f: # strip .yaml group_name = re.sub(r"[^a-zA-Z0-9_]", "_", filename[:-5]) group_name = "%s_%s" % (prefix, group_name) - definition = yaml.load(f.read(), OrderedLoader) + definition = yaml.load(f, OrderedLoader) definition = resolve_references(filepath, definition) if 'type' not in definition: continue @@ -741,7 +741,7 @@ class MatrixUnits(Units): event_type = filename[:-5] # strip the ".yaml" logger.info("Reading event schema: %s" % filepath) - with open(filepath) as f: + with open(filepath, encoding="utf-8") as f: event_schema = yaml.load(f, OrderedLoader) schema_info = process_data_type( @@ -792,7 +792,7 @@ class MatrixUnits(Units): filepath = os.path.join(path, filename) logger.info("Reading event example: %s" % filepath) try: - with open(filepath, "r") as f: + with open(filepath, "r", encoding="utf-8") as f: example = json.load(f) examples[filename] = examples.get(filename, []) examples[filename].append(example) @@ -830,7 +830,7 @@ class MatrixUnits(Units): def read_event_schema(self, filepath): logger.info("Reading %s" % filepath) - with open(filepath, "r") as f: + with open(filepath, "r", encoding="utf-8") as f: json_schema = yaml.load(f, OrderedLoader) schema = { @@ -942,7 +942,7 @@ class MatrixUnits(Units): title_part = None changelog_lines = [] - with open(path, "r") as f: + with open(path, "r", encoding="utf-8") as f: lines = f.readlines() prev_line = None for line in (tc_lines + lines): From 05b017276c81b2a0ce0edb23b6c5c8990b86557e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 10:23:12 -0600 Subject: [PATCH 229/240] Don't accidentally limit application services to one homeserver --- specification/application_service_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 09ecd4ff..45ee75a9 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -54,8 +54,8 @@ The following other versions are also available, in reverse chronological order: Application Services -------------------- -Application services are passive and can only observe events from a given -homeserver. They can inject events into rooms they are participating in. +Application services are passive and can only observe events from homeserver. +They can inject events into rooms they are participating in. They cannot prevent events from being sent, nor can they modify the content of the event being sent. In order to observe events from a homeserver, the homeserver needs to be configured to pass certain types of traffic to the From ecd3ce39e54dd35eab60b2c8c8da900bfbf34b8b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 10:29:59 -0600 Subject: [PATCH 230/240] Don't generate proposals.rst in Circle CI --- scripts/generate-matrix-org-assets | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/generate-matrix-org-assets b/scripts/generate-matrix-org-assets index ed08f81d..76032850 100755 --- a/scripts/generate-matrix-org-assets +++ b/scripts/generate-matrix-org-assets @@ -8,8 +8,11 @@ cd `dirname $0`/.. mkdir -p assets -# generate specification/proposals.rst -./scripts/proposals.py +if [ "$CIRCLECI" != "true" ] +then + # generate specification/proposals.rst + ./scripts/proposals.py +fi # generate the spec docs ./scripts/gendoc.py -d assets/spec From a48f7b9278d7810b8727e266e566b1a81b9c24c8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 10:49:05 -0600 Subject: [PATCH 231/240] Clarify how external_url is supposed to work Fixes https://github.com/matrix-org/matrix-doc/issues/1624 --- specification/application_service_api.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 5b7abf4a..127b3ade 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -374,13 +374,14 @@ additional parameters on the ``/publicRooms`` client-server endpoint. {{appservice_room_directory_cs_http_api}} -Event fields -~~~~~~~~~~~~ +Referencing messages from a third party network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. TODO-TravisR: Fix this section to be a general "3rd party networks" section +Application services should include an ``external_url`` in the ``content`` of +events it emits to indicate where the message came from. This typically applies +to application services that bridge other networks into Matrix, such as IRC, +where an HTTP URL may be available to reference. -We recommend that any events that originated from a remote network should -include an ``external_url`` field in their content to provide a way for Matrix -clients to link into the 'native' client from which the event originated. -For instance, this could contain the message-ID for emails/nntp posts, or a link -to a blog comment when bridging blog comment traffic in & out of Matrix. +Clients should provide users with a way to access the ``external_url`` if it +is present. Clients should additionally ensure the URL has a scheme of ``https`` +or ``http`` before making use of it. From be5c5660282a74128047aa3ec98df1fcbffe0ca5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:03:42 -0600 Subject: [PATCH 232/240] Version all appservice endpoints and provide a fallback Fixes https://github.com/matrix-org/matrix-doc/issues/1616 --- api/application-service/protocols.yaml | 12 +++++----- api/application-service/query_room.yaml | 2 +- api/application-service/query_user.yaml | 2 +- api/application-service/transactions.yaml | 2 +- specification/application_service_api.rst | 28 +++++++++++++++++++++++ 5 files changed, 37 insertions(+), 9 deletions(-) diff --git a/api/application-service/protocols.yaml b/api/application-service/protocols.yaml index e6489cc5..f1dd39b0 100644 --- a/api/application-service/protocols.yaml +++ b/api/application-service/protocols.yaml @@ -19,13 +19,13 @@ host: localhost:8008 schemes: - https - http -basePath: "/" +basePath: /_matrix/app/v1 consumes: - application/json produces: - application/json paths: - "/_matrix/app/unstable/thirdparty/protocol/{protocol}": + "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the application service supports. description: |- @@ -72,7 +72,7 @@ paths: } schema: $ref: ../client-server/definitions/errors/error.yaml - "/_matrix/app/unstable/thirdparty/user/{protocol}": + "/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix User ID of a corresponding third party user. description: |- @@ -125,7 +125,7 @@ paths: } schema: $ref: ../client-server/definitions/errors/error.yaml - "/_matrix/app/unstable/thirdparty/location/{protocol}": + "/thirdparty/location/{protocol}": get: summary: Retrieve Matrix-side portal rooms leading to a third party location. description: |- @@ -176,7 +176,7 @@ paths: } schema: $ref: ../client-server/definitions/errors/error.yaml - "/_matrix/app/unstable/thirdparty/location": + "/thirdparty/location": get: summary: Reverse-lookup third party locations given a Matrix room alias. description: |- @@ -221,7 +221,7 @@ paths: } schema: $ref: ../client-server/definitions/errors/error.yaml - "/_matrix/app/unstable/thirdparty/user": + "/thirdparty/user": get: summary: Reverse-lookup third party users given a Matrix User ID. description: |- diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index b885cb86..22f15dcf 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: "/" +basePath: /_matrix/app/v1 consumes: - application/json produces: diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 0431b5e4..af7dec5c 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: "/" +basePath: /_matrix/app/v1 consumes: - application/json produces: diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml index 8735cc8f..9bedc502 100644 --- a/api/application-service/transactions.yaml +++ b/api/application-service/transactions.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: "/" +basePath: /_matrix/app/v1 produces: - application/json paths: diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 5b7abf4a..3aa8a8ed 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -169,6 +169,34 @@ An example registration file for an IRC-bridging application service is below: Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Legacy routes ++++++++++++++ + +Previous drafts of the application service specification had a mix of endpoints +that have been used in the wild for a significant amount of time. The application +service specification now defines a version on all endpoints to be more compatible +with the rest of the Matrix specification and the future. + +Homeservers should attempt to use the specified endpoints first when communicating +with application services. However, if the application service receives an http status +code that does not indicate success (ie: 404, 500, 501, etc) then the homeserver +should fall back to the older endpoints for the application service. + +The older endpoints have the exact same request body and response format, they +just belong at a different path. The equivalent path for each is as follows: + +* ``/_matrix/app/v1/transactions/{txnId}`` becomes ``/transactions/{txnId}`` +* ``/_matrix/app/v1/users/{userId}`` becomes ``/users/{userId}`` +* ``/_matrix/app/v1/rooms/{roomAlias}`` becomes ``/rooms/{roomAlias}`` +* ``/_matrix/app/v1/thirdparty/protocol/{protocol}`` becomes ``/_matrix/app/unstable/thirdparty/protocol/{protocol}`` +* ``/_matrix/app/v1/thirdparty/user/{user}`` becomes ``/_matrix/app/unstable/thirdparty/user/{user}`` +* ``/_matrix/app/v1/thirdparty/location/{location}`` becomes ``/_matrix/app/unstable/thirdparty/location/{location}`` +* ``/_matrix/app/v1/thirdparty/user`` becomes ``/_matrix/app/unstable/thirdparty/user`` +* ``/_matrix/app/v1/thirdparty/location`` becomes ``/_matrix/app/unstable/thirdparty/location`` + +Homeservers should periodically try again for the newer endpoints because the +application service may have been updated. + Pushing events ++++++++++++++ From 1a3f11233731d92a9dec01dd8b207c62c27c528e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:07:09 -0600 Subject: [PATCH 233/240] Clarify that the external_url is unsafe --- specification/application_service_api.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 127b3ade..cd65fad7 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -385,3 +385,7 @@ where an HTTP URL may be available to reference. Clients should provide users with a way to access the ``external_url`` if it is present. Clients should additionally ensure the URL has a scheme of ``https`` or ``http`` before making use of it. + +The presence of an ``external_url`` on an event does not necessarily mean the +event was sent from an application service. Clients should be wary of the URL +contained within, as it may not be a legitimate reference to the event's source. From 138419cdd48780e7b9b1e0e41704563eca179805 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:19:55 -0600 Subject: [PATCH 234/240] fix indentation on release process doc --- meta/releasing_a_spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index 3a9da893..ac3d21fa 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -27,7 +27,7 @@ The remainder of the process is as follows: 1. Add the changes to the matrix-org/matrix.org repository (for historic tracking). * This is done by making a PR to the `unstyled_docs/spec` folder for the version and specification you're releasing. - * Don't forget to symlink the new release as `latest`. + * Don't forget to symlink the new release as `latest`. 1. Perform a release on GitHub to tag the release. 1. Yell from the mountaintop to the world about the new release. From 6aacec317867b64a6a00994ad8b222e0666c3e30 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:40:08 -0600 Subject: [PATCH 235/240] Fix power level JSON example --- event-schemas/examples/m.room.power_levels | 1 + 1 file changed, 1 insertion(+) diff --git a/event-schemas/examples/m.room.power_levels b/event-schemas/examples/m.room.power_levels index b09746df..ad741e88 100644 --- a/event-schemas/examples/m.room.power_levels +++ b/event-schemas/examples/m.room.power_levels @@ -20,4 +20,5 @@ "notifications": { "room": 20 } + } } From 31ea4279d1fb776a0734eb47a28368330f895ce4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:53:39 -0600 Subject: [PATCH 236/240] Resolve references in the check_examples script --- event-schemas/check_examples.py | 47 ++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py index f2456d97..be541aa9 100755 --- a/event-schemas/check_examples.py +++ b/event-schemas/check_examples.py @@ -44,16 +44,51 @@ except ImportError as e: raise +def load_file(path): + print("Loading reference: %s" % path) + if not path.startswith("file://"): + raise Exception("Bad ref: %s" % (path,)) + path = path[len("file://"):] + with open(path, "r") as f: + if path.endswith(".json"): + return json.load(f) + else: + # We have to assume it's YAML because some of the YAML examples + # do not have file extensions. + return yaml.load(f) + + +def resolve_references(path, schema): + if isinstance(schema, dict): + # do $ref first + if '$ref' in schema: + value = schema['$ref'] + path = os.path.abspath(os.path.join(os.path.dirname(path), value)) + ref = load_file("file://" + path) + result = resolve_references(path, ref) + del schema['$ref'] + else: + result = {} + + for key, value in schema.items(): + result[key] = resolve_references(path, value) + return result + elif isinstance(schema, list): + return [resolve_references(path, value) for value in schema] + else: + return schema + + def check_example_file(examplepath, schemapath): with open(examplepath) as f: - example = yaml.load(f) + example = resolve_references(examplepath, json.load(f)) with open(schemapath) as f: schema = yaml.load(f) fileurl = "file://" + os.path.abspath(schemapath) schema["id"] = fileurl - resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml}) + resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file}) print ("Checking schema for: %r %r" % (examplepath, schemapath)) try: @@ -85,14 +120,6 @@ def check_example_dir(exampledir, schemadir): raise ValueError("Error validating examples") -def load_yaml(path): - if not path.startswith("file:///"): - raise Exception("Bad ref: %s" % (path,)) - path = path[len("file://"):] - with open(path, "r") as f: - return yaml.load(f) - - if __name__ == '__main__': try: check_example_dir("examples", "schema") From c8a8f13623e8022f1eaa17f5dc76995d3366cbbb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:57:01 -0600 Subject: [PATCH 237/240] Don't check the underlying definitions Otherwise the script will try to find a schema for our templates, which don't exist. --- event-schemas/check_examples.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py index be541aa9..deb0433e 100755 --- a/event-schemas/check_examples.py +++ b/event-schemas/check_examples.py @@ -106,6 +106,9 @@ def check_example_dir(exampledir, schemadir): if filename.startswith("."): # Skip over any vim .swp files. continue + if os.dirname(os.path.join(root, filename)) == "core": + # Skip checking the underlying definitions + continue examplepath = os.path.join(root, filename) schemapath = examplepath.replace(exampledir, schemadir) if schemapath.find("#") >= 0: From 464f4f5f2166608f573afb95a2299381f9ab477b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 12:05:56 -0600 Subject: [PATCH 238/240] Correctly check for the 'core' folder --- event-schemas/check_examples.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py index deb0433e..3e536ec3 100755 --- a/event-schemas/check_examples.py +++ b/event-schemas/check_examples.py @@ -106,7 +106,8 @@ def check_example_dir(exampledir, schemadir): if filename.startswith("."): # Skip over any vim .swp files. continue - if os.dirname(os.path.join(root, filename)) == "core": + cwd = os.path.basename(os.path.dirname(os.path.join(root, filename))) + if cwd == "core": # Skip checking the underlying definitions continue examplepath = os.path.join(root, filename) From 32cde24bcfdc9bc63fef0658b1669e1828cb0a2c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 12:26:24 -0600 Subject: [PATCH 239/240] Fix server-server link in IS spec --- specification/identity_service_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index f6997ea1..e233e4fc 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -247,4 +247,4 @@ this isn't possible. .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types .. _`Signing JSON`: ../appendices.html#signing-json -.. _`/3pid/onbind`: ../server_server.html#put-matrix-federation-v1-3pid-onbind +.. _`/3pid/onbind`: ../server_server/unstable.html#put-matrix-federation-v1-3pid-onbind From 429f30274495bf4fee8c9e0d841db57466fcdfda Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 13:32:53 -0600 Subject: [PATCH 240/240] Add an `age` to the invite room state example --- event-schemas/examples/m.room.member#invite_room_state | 1 + 1 file changed, 1 insertion(+) diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index cbd76100..c99c66c0 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -6,6 +6,7 @@ "displayname": "Alice Margatroid" }, "unsigned": { + "age": 1234, "invite_room_state": [ { "type": "m.room.name",