From 88b35d1be5e016958878af6890286023b31aa272 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 9 Aug 2018 08:30:50 -0600 Subject: [PATCH 01/50] Clarify how third party invites work This adds several diagrams to the Client-Server API about how invites are handled, including what the server is expected to do. This helps implementors know what they are supposed to do in the common cases, and infer where needed to get the more complex cases correct. Although lacking in some areas, this is how third party invites work today. A link to the now-improved client-server documentation for third party invites has been added to the server-server specification. The existing server-server specification needed no further changes on the subject. Fixes https://github.com/matrix-org/matrix-doc/issues/1366 --- api/identity/pubkey.yaml | 2 +- specification/modules/third_party_invites.rst | 205 +++++++++++++----- specification/server_server_api.rst | 4 + 3 files changed, 158 insertions(+), 53 deletions(-) diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 00796975..5ea6341f 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -56,7 +56,7 @@ paths: get: summary: Check whether a long-term public key is valid. description: |- - Check whether a long-term public key is valid. + Check whether a long-term public key is valid. The request must be idempotent. operationId: isPubKeyValid parameters: - in: query diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 9ea0eb0b..a9b06258 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -40,6 +40,7 @@ with ``content.membership`` = ``invite``, as well as a ``content.third_party_invite`` property which contains proof that the invitee does indeed own that third party identifier. + Events ------ @@ -55,41 +56,79 @@ A client asks a server to invite a user by their third party identifier. Server behaviour ---------------- -All homeservers MUST verify the signature in the event's -``content.third_party_invite.signed`` object. - -When a homeserver inserts an ``m.room.member`` ``invite`` event into the graph -because of an ``m.room.third_party_invite`` event, -that homesever MUST validate that the public -key used for signing is still valid, by checking ``key_validity_url`` from the ``m.room.third_party_invite``. It does -this by making an HTTP GET request to ``key_validity_url``: - -.. TODO: Link to identity server spec when it exists +Upon receipt of an ``/invite``, the server is expected to look up the third party +identifier with the provided identity server. If the lookup yields a result for +a Matrix User ID then the normal invite process can be initiated. This process +ends up looking like this: + +:: + + +---------+ +-------------+ +-----------------+ + | Client | | Homeserver | | IdentityServer | + +---------+ +-------------+ +-----------------+ + | | | + | POST /invite | | + |------------------------------------>| | + | | | + | | GET /lookup | + | |--------------------------------------------------->| + | | | + | | User ID result | + | |<---------------------------------------------------| + | | | + | | Invite process for the discovered User ID | + | |------------------------------------------ | + | | | | + | |<----------------------------------------- | + | | | + | Complete the /invite request | | + |<------------------------------------| | + | | | + + +However, if the lookup does not yield a bound User ID, the homeserver must store +the invite on the identity server and emit a valid ``m.room.third_party_invite`` +event to the room. This process ends up looking like this: + +:: + + +---------+ +-------------+ +-----------------+ + | Client | | Homeserver | | IdentityServer | + +---------+ +-------------+ +-----------------+ + | | | + | POST /invite | | + |------------------------------------>| | + | | | + | | GET /lookup | + | |-------------------------------------------------------------->| + | | | + | | "no users" result | + | |<--------------------------------------------------------------| + | | | + | | POST /store-invite | + | |-------------------------------------------------------------->| + | | | + | | Information needed for the m.room.third_party_invite | + | |<--------------------------------------------------------------| + | | | + | | Emit m.room.third_party_invite to the room | + | |------------------------------------------- | + | | | | + | |<------------------------------------------ | + | | | + | Complete the /invite request | | + |<------------------------------------| | + | | | -Schema:: - => GET $key_validity_url?public_key=$public_key - <= HTTP/1.1 200 OK - { - "valid": true|false - } - - -Example:: - - key_validity_url = https://identity.server/is_valid - public_key = ALJWLAFQfqffQHFqFfeqFUOEHf4AIHfefh4 - => GET https://identity.server/is_valid?public_key=ALJWLAFQfqffQHFqFfeqFUOEHf4AIHfefh4 - <= HTTP/1.1 200 OK - { - "valid": true - } +All homeservers MUST verify the signature in the event's +``content.third_party_invite.signed`` object. -with the querystring -?public_key=``public_key``. A JSON object will be returned. -The invitation is valid if the object contains a key named ``valid`` which is -``true``. Otherwise, the invitation MUST be rejected. This request is -idempotent and may be retried by the homeserver. +The third party user will then need to verify their identity, which results in +a call from the Identity Server to the homeserver that bound the third party +identifier to a user. The homeserver then exchanges the ``m.room.third_party_invite`` +event in the room for a complete ``m.room.member`` event for ``membership: invite`` +for the user that has bound the third party identifier. If a homeserver is joining a room for the first time because of an ``m.room.third_party_invite``, the server which is already participating in the @@ -102,26 +141,85 @@ No other homeservers may reject the joining of the room on the basis of the room. They may, however, indicate to their clients that a member's' membership is questionable. -For example: - -#. Room R has two participating homeservers, H1, H2 - -#. User A on H1 invites a third party identifier to room R - -#. H1 asks the identity server for a binding to a Matrix user ID, and has none, - so issues an ``m.room.third_party_invite`` event to the room. - -#. When the third party user validates their identity, their homeserver H3 - is notified and attempts to issue an ``m.room.member`` event to participate - in the room. - -#. H3 validates the signature given to it by the identity server. - -#. H3 then asks H1 to join it to the room. H1 *must* validate the ``signed`` - property *and* check ``key_validity_url``. - -#. Having validated these things, H1 writes the invite event to the room, and H3 - begins participating in the room. H2 *must* accept this event. +For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, and an +identity server IS, the full sequence for a third party invite would look like +the following. This diagram assumes H1 and H2 are residents of the room while +H3 is attempting to join. + +:: + + +-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+ + | UserA | | ThirdPartyUser | | H1 | | H2 | | H3 | | IS | + +-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+ + | | | | | | + | POST /invite for ThirdPartyUser | | | | + |----------------------------------->| | | | + | | | | | | + | | | GET /lookup | | | + | | |---------------------------------------------------------------------------------------------->| + | | | | | | + | | | | Lookup results (empty object) | + | | |<----------------------------------------------------------------------------------------------| + | | | | | | + | | | POST /store-invite | | | + | | |---------------------------------------------------------------------------------------------->| + | | | | | | + | | | | Token, keys, etc for third party invite | + | | |<----------------------------------------------------------------------------------------------| + | | | | | | + | | | (Federation) Emit m.room.third_party_invite | | | + | | |----------------------------------------------->| | | + | | | | | | + | Complete /invite request | | | | + |<-----------------------------------| | | | + | | | | | | + | | Verify identity | | | | + | |-------------------------------------------------------------------------------------------------------------------->| + | | | | | | + | | | | | POST /3pid/onbind | + | | | | |<---------------------------| + | | | | | | + | | | PUT /exchange_third_party_invite/:roomId | | + | | |<-----------------------------------------------------------------| | + | | | | | | + | | | Verify the request | | | + | | |------------------- | | | + | | | | | | | + | | |<------------------ | | | + | | | | | | + | | | (Federation) Emit m.room.member for invite | | | + | | |----------------------------------------------->| | | + | | | | | | + | | | | Accept event | | + | | | |------------- | | + | | | | | | | + | | | |<------------ | | + | | | | | | + | | | (Federation) Emit the m.room.member event sent to H2 | | + | | |----------------------------------------------------------------->| | + | | | | | | + | | | Complete /exchange_third_party_invite/:roomId request | | + | | |----------------------------------------------------------------->| | + | | | | | | + | | | | | Participate in the room | + | | | | |------------------------ | + | | | | | | | + | | | | |<----------------------- | + | | | | | | + + +Note that when H1 sends the ``m.room.member`` event to H2 and H3 it does not +have to block on either server's receipt of the event. Likewise, H1 may complete +the ``/exchange_third_party_invite/:roomId`` request at the same time as sending +the ``m.room.member`` event to H2 and H3. Additionally, H3 may complete the +``/3pid/onbind`` request it got from IS at any time - the completion is not shown +in the diagram. + +H1 MUST verify the request from H3 to ensure the ``signed`` property is correct +as well as the ``key_validity_url`` as still being valid. This is done by making +a request to the `Identity Server /isvalid`_ endpoint, using the provided URL +rather than constructing a new one. The query string and response for the provided +URL must match the Identity Server specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -158,3 +256,6 @@ There is some risk of denial of service attacks by flooding homeservers or identity servers with many requests, or much state to store. Defending against these is left to the implementer's discretion. + + +.. _`Identity Server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 472aca12..b8df0b47 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -734,6 +734,10 @@ event to other servers in the room. Third-party invites ------------------- +.. NOTE:: + More information about third party invites is available in the `Client-Server API`_ + under the Third Party Invites module. + When an user wants to invite another user in a room but doesn't know the Matrix ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). From a556e33eb9d606efeea321466678ba1ed2c3c379 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 13 Aug 2018 16:59:36 -0600 Subject: [PATCH 02/50] Spec /3pid/onbind Fixes https://github.com/matrix-org/matrix-doc/issues/1422 --- api/server-server/third_party_invite.yaml | 123 ++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 754a3282..2225bf1a 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -190,3 +190,126 @@ paths: type: object description: An empty object example: {} + "/3pid/onbind": + put: + summary: |- + Notifies the server that a third party identifier has been bound to one + of its users. + description: |- + Used by Identity Servers to notify the homeserver that one of its users + has bound a third party identifier successfully, including any pending + room invites the Identity Server has been made aware of. + operationId: onBindThirdPartyIdentifier + parameters: + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + medium: + type: string + description: |- + The type of third party identifier. Currently only "email" is + a possible value. + example: "email" + address: + type: string + description: |- + The third party identifier itself. For example, an email address. + example: "alice@domain.com" + mxid: + type: string + description: The user that is now bound to the third party identifier. + example: "@alice:matrix.org" + invites: + type: array + description: |- + A list of pending invites that the third party identifier has received. + items: + type: object + title: Third Party Invite + properties: + medium: + type: string + description: |- + The type of third party invite issues. Currently only + "email" is used. + example: "email" + address: + type: string + description: |- + The third party identifier that received the invite. + example: "alice@domain.com" + mxid: + type: string + description: The now-bound user ID that received the invite. + example: "@alice:matrix.org" + room_id: + type: string + description: The room ID the invite is valid for. + example: "!somewhere:example.org" + sender: + type: string + description: The user ID that sent the invite. + example: "@bob:matrix.org" + # TODO (TravisR): Make this reusable when doing IS spec changes + # also make sure it isn't lying about anything, like the key version + signed: + type: object + title: Identity Server Signatures + description: |- + Signature from the Identity Server using a long-term private + key. + properties: + mxid: + type: string + description: |- + The user ID that has been bound to the third party + identifier. + example: "@alice:matrix.org" + token: + type: string + # TODO: What is this actually? + description: A token. + example: "Hello World" + signatures: + type: object + title: Identity Server Signature + description: |- + The signature from the identity server. The ``string`` key + is the identity server's domain name, such as vector.im + additionalProperties: + type: object + title: Identity Server Domain Signature + description: The signature for the identity server. + properties: + "ed25519:0": + type: string + description: The signature. + example: "SomeSignatureGoesHere" + required: ['ed25519:0'] + example: { + "vector.im": { + "ed25519:0": "SomeSignatureGoesHere" + } + } + required: ['mxid', 'token', 'signatures'] + required: + - medium + - address + - mxid + - room_id + - sender + - signed + required: ['medium', 'address', 'mxid', 'invites'] + responses: + 200: + description: The homeserver has processed the notification. + examples: + application/json: {} + schema: + type: object + description: An empty object + example: {} From 3de50cbc7f9b9187b426108f810eab9516586560 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 09:49:09 -0600 Subject: [PATCH 03/50] Clarify how /isvalid is meant to always be truthful --- api/identity/pubkey.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 5ea6341f..1cd7b94c 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -56,7 +56,8 @@ paths: get: summary: Check whether a long-term public key is valid. description: |- - Check whether a long-term public key is valid. The request must be idempotent. + Check whether a long-term public key is valid. The response should always + be the same, provided the key exists. operationId: isPubKeyValid parameters: - in: query From 1bc0f63bfb26f7f60f034c6bdcf38b901005516b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:03:48 -0600 Subject: [PATCH 04/50] Clarify the homeserver's behaviour for user searching The homeserver can implement its own algorithm, but is suggested to ensure the requesting user can reasonably see the other users. The text is intentionally left vague for whether or not the API is local users only to give the homeserver some flexibility in this area. General cleanup is also included in this commit. Fixes https://github.com/matrix-org/matrix-doc/issues/1108 --- api/client-server/users.yaml | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index a682b435..ef527a23 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -31,8 +31,13 @@ paths: post: summary: Searches the user directory. description: |- - This API performs a server-side search over all users registered on the server. - It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms. + Performs a search for users on the homeserver. The homeserver may + determine which subset of users are searched, however the homeserver + is encouraged to only consider users the requesting user shares a + room with and those who reside in public rooms. + + The search is performed case-insensitively on user IDs and display + names. operationId: searchUserDirectory security: - accessToken: [] @@ -48,7 +53,7 @@ paths: example: "foo" limit: type: number - description: The maximum number of results to return (Defaults to 10). + description: The maximum number of results to return. Defaults to 10. example: 10 required: ["search_term"] responses: @@ -56,15 +61,15 @@ paths: description: The results of the search. examples: application/json: { - "results": [ - { - "user_id": "@foo:bar.com", - "display_name": "Foo", - "avatar_url": "mxc://bar.com/foo" - } - ], - "limited": false - } + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } schema: type: object required: ["results", "limited"] From e926b4a84011332a698189ec421993d4d5605388 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 21:05:09 -0600 Subject: [PATCH 05/50] Changelog --- changelogs/client_server/newsfragments/1569.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1569.clarification diff --git a/changelogs/client_server/newsfragments/1569.clarification b/changelogs/client_server/newsfragments/1569.clarification new file mode 100644 index 00000000..83185e02 --- /dev/null +++ b/changelogs/client_server/newsfragments/1569.clarification @@ -0,0 +1 @@ +Clarify the homeserver's behaviour for searching users. From 55c0b968b5aaa86c9c37415dded849b060f47f24 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:22:14 -0600 Subject: [PATCH 06/50] Fix event schemas for /sync This commit clarifies the required keys for each type of event that appears in sync, fixes the core event schema not declaring 'content' as required, and includes a mention that events may not have a room_id when appearing in /sync. Fixes https://github.com/matrix-org/matrix-doc/issues/595 Fixes https://github.com/matrix-org/matrix-doc/issues/909 --- .../definitions/event_batch.yaml | 5 +- .../definitions/room_event_batch.yaml | 27 +++++++++ .../definitions/state_event_batch.yaml | 28 +++++++++ .../definitions/timeline_batch.yaml | 7 ++- api/client-server/sync.yaml | 9 +-- .../schema/core-event-schema/event.yaml | 1 + .../schema/core-event-schema/room_event.yaml | 39 ++---------- .../core-event-schema/sync_room_event.yaml | 60 +++++++++++++++++++ .../core-event-schema/sync_state_event.yaml | 35 +++++++++++ 9 files changed, 167 insertions(+), 44 deletions(-) create mode 100644 api/client-server/definitions/room_event_batch.yaml create mode 100644 api/client-server/definitions/state_event_batch.yaml create mode 100644 event-schemas/schema/core-event-schema/sync_room_event.yaml create mode 100644 event-schemas/schema/core-event-schema/sync_state_event.yaml diff --git a/api/client-server/definitions/event_batch.yaml b/api/client-server/definitions/event_batch.yaml index 21377a41..d169c355 100644 --- a/api/client-server/definitions/event_batch.yaml +++ b/api/client-server/definitions/event_batch.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. @@ -13,10 +14,10 @@ # limitations under the License. properties: events: - description: List of events + description: List of events. items: allOf: - - $ref: event.yaml + - $ref: event-schemas/schema/core-event-schema/event.yaml type: object type: array type: object diff --git a/api/client-server/definitions/room_event_batch.yaml b/api/client-server/definitions/room_event_batch.yaml new file mode 100644 index 00000000..7367198f --- /dev/null +++ b/api/client-server/definitions/room_event_batch.yaml @@ -0,0 +1,27 @@ +# 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: + events: + description: List of events. + items: + allOf: + - $ref: event-schemas/schema/core-event-schema/sync_room_event.yaml + type: object + required: + - event_id + #- room_id - Not in /sync + - sender + - origin_server_ts + type: array +type: object diff --git a/api/client-server/definitions/state_event_batch.yaml b/api/client-server/definitions/state_event_batch.yaml new file mode 100644 index 00000000..db01ecb1 --- /dev/null +++ b/api/client-server/definitions/state_event_batch.yaml @@ -0,0 +1,28 @@ +# 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: + events: + description: List of events. + items: + allOf: + - $ref: event-schemas/schema/core-event-schema/sync_state_event.yaml + type: object + required: + - event_id + #- room_id - Not in /sync + - sender + - origin_server_ts + - state_key + type: array +type: object diff --git a/api/client-server/definitions/timeline_batch.yaml b/api/client-server/definitions/timeline_batch.yaml index ce613ac4..abf93830 100644 --- a/api/client-server/definitions/timeline_batch.yaml +++ b/api/client-server/definitions/timeline_batch.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. @@ -12,14 +13,14 @@ # See the License for the specific language governing permissions and # limitations under the License. allOf: -- $ref: event_batch.yaml +- $ref: room_event_batch.yaml properties: limited: description: True if the number of events returned was limited by the ``limit`` - on the filter + on the filter. type: boolean prev_batch: description: A token that can be supplied to the ``from`` parameter of the - rooms/{roomId}/messages endpoint + rooms/{roomId}/messages endpoint. type: string type: object diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 4b44c20e..6a1d4f60 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -134,7 +134,7 @@ paths: ``timeline``, if ``since`` is not given, or ``full_state`` is true). allOf: - - $ref: "definitions/event_batch.yaml" + - $ref: "definitions/state_event_batch.yaml" timeline: title: Timeline type: object @@ -202,7 +202,7 @@ paths: delta against the archived ``state`` not the ``invite_state``. allOf: - - $ref: "definitions/event_batch.yaml" + - $ref: "definitions/state_event_batch.yaml" leave: title: Left rooms type: object @@ -218,7 +218,7 @@ paths: description: |- The state updates for the room up to the start of the timeline. allOf: - - $ref: "definitions/event_batch.yaml" + - $ref: "definitions/state_event_batch.yaml" timeline: title: Timeline type: object @@ -261,6 +261,8 @@ paths: description: |- Information on end-to-end encryption keys, as specified in |device_lists_sync|_. + required: + - next_batch examples: application/json: { "next_batch": "s72595_4483_1934", @@ -312,7 +314,6 @@ paths: { "sender": "@alice:example.com", "type": "m.room.message", - "age": 124524, "txn_id": "1234", "content": { "body": "I am a fish", diff --git a/event-schemas/schema/core-event-schema/event.yaml b/event-schemas/schema/core-event-schema/event.yaml index 7a060283..0fe5ac6c 100644 --- a/event-schemas/schema/core-event-schema/event.yaml +++ b/event-schemas/schema/core-event-schema/event.yaml @@ -10,5 +10,6 @@ properties: type: string required: - type + - content title: Event type: object diff --git a/event-schemas/schema/core-event-schema/room_event.yaml b/event-schemas/schema/core-event-schema/room_event.yaml index a8a23f54..007372a5 100644 --- a/event-schemas/schema/core-event-schema/room_event.yaml +++ b/event-schemas/schema/core-event-schema/room_event.yaml @@ -1,45 +1,14 @@ allOf: -- $ref: event.yaml +- $ref: sync_room_event.yaml description: In addition to the Event fields, Room Events have the following additional fields. properties: - event_id: - description: The globally unique event identifier. - type: string room_id: - description: The ID of the room associated with this event. - type: string - sender: - description: Contains the fully-qualified ID of the user who *sent* - this event. + description: |- + The ID of the room associated with this event. Will not be present on events + that arrive through ``/sync``, despite being required everywhere else. type: string - origin_server_ts: - description: Timestamp in milliseconds on originating homeserver - when this event was sent. - type: number - unsigned: - description: Contains optional extra information about the event. - properties: - age: - description: The time in milliseconds that has elapsed since the event was - sent. This field is generated by the local homeserver, and may be incorrect - if the local time on at least one of the two servers is out of sync, which can - cause the age to either be negative or greater than it actually is. - type: integer - redacted_because: - description: Optional. The event that redacted this event, if any. - title: Event - type: object - transaction_id: - description: The client-supplied transaction ID, if the client being given - the event is the same one which sent it. - type: string - title: UnsignedData - type: object required: -- event_id - room_id -- sender -- origin_server_ts title: Room Event type: object diff --git a/event-schemas/schema/core-event-schema/sync_room_event.yaml b/event-schemas/schema/core-event-schema/sync_room_event.yaml new file mode 100644 index 00000000..300dfb2b --- /dev/null +++ b/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -0,0 +1,60 @@ +# 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. + +# Note: this is technically not a core event schema, however it is included here +# to keep things sane. The short story is that /sync doesn't require a room_id to +# be on events, so we give it a whole event structure as a base for room_event. +# This base doesn't declare a room_id, which instead appears in the room_event. + +allOf: +- $ref: event.yaml +description: In addition to the Event fields, Room Events have the following additional + fields. +properties: + event_id: + description: The globally unique event identifier. + type: string + sender: + description: Contains the fully-qualified ID of the user who *sent* + this event. + type: string + origin_server_ts: + description: Timestamp in milliseconds on originating homeserver + when this event was sent. + type: number + unsigned: + description: Contains optional extra information about the event. + properties: + age: + description: The time in milliseconds that has elapsed since the event was + sent. This field is generated by the local homeserver, and may be incorrect + if the local time on at least one of the two servers is out of sync, which can + cause the age to either be negative or greater than it actually is. + type: integer + redacted_because: + description: Optional. The event that redacted this event, if any. + title: Event + type: object + transaction_id: + description: The client-supplied transaction ID, if the client being given + the event is the same one which sent it. + type: string + title: UnsignedData + type: object +required: +- event_id +- sender +- origin_server_ts +title: Room Event +type: object diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml new file mode 100644 index 00000000..a073caac --- /dev/null +++ b/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -0,0 +1,35 @@ +# 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. + +# See sync_room_event.yaml for why this file is here. + +allOf: +- $ref: sync_room_event.yaml +description: In addition to the Room Event fields, State Events have the following + additional fields. +properties: + prev_content: + description: Optional. The previous ``content`` for this event. If there is no + previous content, this key will be missing. + title: EventContent + type: object + 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 '_'. + type: string +required: +- state_key +title: State Event +type: object From fd47184ce37d4b6c387ed5d884c11946e560d20a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:23:38 -0600 Subject: [PATCH 07/50] Changelog --- changelogs/client_server/newsfragments/1573.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1573.clarification diff --git a/changelogs/client_server/newsfragments/1573.clarification b/changelogs/client_server/newsfragments/1573.clarification new file mode 100644 index 00000000..74efa28f --- /dev/null +++ b/changelogs/client_server/newsfragments/1573.clarification @@ -0,0 +1 @@ +Clarify the event fields used in the ``/sync`` response. From bb515d15a40470fc2c9a9290428b8fcf675ec0c1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:55:54 -0600 Subject: [PATCH 08/50] Clarify which collation to use for user directory searching --- api/client-server/users.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index ef527a23..619263ff 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -37,7 +37,8 @@ paths: room with and those who reside in public rooms. The search is performed case-insensitively on user IDs and display - names. + names preferably using a collation determined based upon the + ``Accept-Language`` header provided in the request, if present. operationId: searchUserDirectory security: - accessToken: [] From f2332d242aeb079e77396bd6bd8c5d7f2a629b7e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 18:58:16 -0600 Subject: [PATCH 09/50] Add some SHOULDs and MUSTs to the user directory requirements --- api/client-server/users.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml index 619263ff..8a60a7bc 100644 --- a/api/client-server/users.yaml +++ b/api/client-server/users.yaml @@ -33,8 +33,10 @@ paths: description: |- Performs a search for users on the homeserver. The homeserver may determine which subset of users are searched, however the homeserver - is encouraged to only consider users the requesting user shares a - room with and those who reside in public rooms. + MUST at a minimum consider the users the requesting user shares a + room with and those who reside in public rooms (known to the homeserver). + The search MUST consider local users to the homeserver, and SHOULD + query remote users as part of the search. The search is performed case-insensitively on user IDs and display names preferably using a collation determined based upon the From efef3412a0278d1dff714a8fe9c157369e4db2ff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:07:32 -0600 Subject: [PATCH 10/50] Take out the underscore restriction from state events It's not needed anymore, and we should remove it while we're in the area. Includes other misc changes to the schema layout. --- .../schema/core-event-schema/state_event.yaml | 14 +------------- .../schema/core-event-schema/sync_room_event.yaml | 3 +-- .../schema/core-event-schema/sync_state_event.yaml | 2 +- 3 files changed, 3 insertions(+), 16 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..37d4426f 100644 --- a/event-schemas/schema/core-event-schema/state_event.yaml +++ b/event-schemas/schema/core-event-schema/state_event.yaml @@ -1,19 +1,7 @@ allOf: - $ref: room_event.yaml +- $ref: sync_state_event.yaml description: In addition to the Room Event fields, State Events have the following additional fields. -properties: - prev_content: - description: Optional. The previous ``content`` for this event. If there is no - previous content, this key will be missing. - title: EventContent - type: object - 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 '_'. - type: string -required: -- state_key title: State Event type: object diff --git a/event-schemas/schema/core-event-schema/sync_room_event.yaml b/event-schemas/schema/core-event-schema/sync_room_event.yaml index 300dfb2b..fbbf154f 100644 --- a/event-schemas/schema/core-event-schema/sync_room_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -26,8 +26,7 @@ properties: description: The globally unique event identifier. type: string sender: - description: Contains the fully-qualified ID of the user who *sent* - this event. + description: Contains the fully-qualified ID of the user who sent this event. type: string origin_server_ts: description: Timestamp in milliseconds on originating homeserver diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml index a073caac..30af9698 100644 --- a/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -27,7 +27,7 @@ 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. type: string required: - state_key From 0b7b3bfcb0c2da63ef0eff799e83bbaf00ce40f0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 29 Aug 2018 11:20:33 +0100 Subject: [PATCH 11/50] Reindent auth rules section RST expects sub lists to be indented by three or more spaces. By doing so we can then rely on `#.` for automatic numbering. --- specification/server_server_api.rst | 112 ++++++++++++++-------------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 9440f2f2..c67bea3d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -359,100 +359,100 @@ The rules are as follows: 1. If type is ``m.room.create``, allow if and only if it has no previous events - *i.e.* it is the first event in the room. -2. If type is ``m.room.member``: +#. If type is ``m.room.member``: - a. If ``membership`` is ``join``: + a. If ``membership`` is ``join``: - i. If the only previous event is an ``m.room.create`` - and the ``state_key`` is the creator, allow. + i. If the only previous event is an ``m.room.create`` + and the ``state_key`` is the creator, allow. - #. If the ``sender`` does not match ``state_key``, reject. + #. If the ``sender`` does not match ``state_key``, reject. - #. If the user's current membership state is ``invite`` or ``join``, - allow. + #. If the user's current membership state is ``invite`` or ``join``, + allow. - #. If the ``join_rule`` is ``public``, allow. + #. If the ``join_rule`` is ``public``, allow. - #. Otherwise, reject. + #. Otherwise, reject. - b. If ``membership`` is ``invite``: + #. If ``membership`` is ``invite``: - i. If the ``sender``'s current membership state is not ``join``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. - #. If *target user*'s current membership state is ``join`` or ``ban``, - reject. + #. If *target user*'s current membership state is ``join`` or ``ban``, + reject. - #. If the ``sender``'s power level is greater than or equal to the *invite - level*, allow. + #. If the ``sender``'s power level is greater than or equal to the *invite + level*, allow. - #. Otherwise, reject. + #. Otherwise, reject. - c. If ``membership`` is ``leave``: + #. If ``membership`` is ``leave``: - i. If the ``sender`` matches ``state_key``, allow if and only if that user's - current membership state is ``invite`` or ``join``. + i. If the ``sender`` matches ``state_key``, allow if and only if that user's + current membership state is ``invite`` or ``join``. - #. If the ``sender``'s current membership state is not ``join``, reject. + #. If the ``sender``'s current membership state is not ``join``, reject. - #. If the *target user*'s current membership state is ``ban``, and the - ``sender``'s power level is less than the *ban level*, reject. + #. If the *target user*'s current membership state is ``ban``, and the + ``sender``'s power level is less than the *ban level*, reject. - #. If the ``sender``'s power level is greater than or equal to the *kick - level*, and the *target user*'s power level is less than the - ``sender``'s power level, allow. + #. If the ``sender``'s power level is greater than or equal to the *kick + level*, and the *target user*'s power level is less than the + ``sender``'s power level, allow. - #. Otherwise, reject. + #. Otherwise, reject. - d. If ``membership`` is ``ban``: + #. If ``membership`` is ``ban``: - i. If the ``sender``'s current membership state is not ``join``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. - #. If the ``sender``'s power level is greater than or equal to the *ban - level*, and the *target user*'s power level is less than the - ``sender``'s power level, allow. + #. If the ``sender``'s power level is greater than or equal to the *ban + level*, and the *target user*'s power level is less than the + ``sender``'s power level, allow. - #. Otherwise, reject. + #. Otherwise, reject. - e. Otherwise, the membership is unknown. Reject. + #. Otherwise, the membership is unknown. Reject. -3. If the ``sender``'s current membership state is not ``join``, reject. +#. If the ``sender``'s current membership state is not ``join``, reject. -4. If the event type's *required power level* is greater than the ``sender``'s power +#. If the event type's *required power level* is greater than the ``sender``'s power level, reject. -5. If type is ``m.room.power_levels``: +#. If type is ``m.room.power_levels``: - a. If there is no previous ``m.room.power_levels`` event in the room, allow. + a. If there is no previous ``m.room.power_levels`` event in the room, allow. - b. For each of the keys ``users_default``, ``events_default``, - ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as - each entry being changed under the ``events`` or ``users`` keys: + #. For each of the keys ``users_default``, ``events_default``, + ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as + each entry being changed under the ``events`` or ``users`` keys: - i. If the current value is higher than the ``sender``'s current power level, - reject. + i. If the current value is higher than the ``sender``'s current power level, + reject. - #. If the new value is higher than the ``sender``'s current power level, - reject. + #. If the new value is higher than the ``sender``'s current power level, + reject. - c. For each entry being changed under the ``users`` key, other than the - ``sender``'s own entry: + #. For each entry being changed under the ``users`` key, other than the + ``sender``'s own entry: - i. If the current value is equal to the ``sender``'s current power level, - reject. + i. If the current value is equal to the ``sender``'s current power level, + reject. - d. Otherwise, allow. + #. Otherwise, allow. -6. If type is ``m.room.redaction``: +#. If type is ``m.room.redaction``: - a. If the ``sender``'s power level is greater than or equal to the *redact - level*, allow. + a. If the ``sender``'s power level is greater than or equal to the *redact + level*, allow. - #. If the ``sender`` of the event being redacted is the same as the - ``sender`` of the ``m.room.redaction``, allow. + #. If the ``sender`` of the event being redacted is the same as the + ``sender`` of the ``m.room.redaction``, allow. - #. Otherwise, reject. + #. Otherwise, reject. -7. Otherwise, allow. +#. Otherwise, allow. .. NOTE:: From 86b5486445cbe5fc8d7092b2aba30486850da9a8 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 29 Aug 2018 11:32:14 +0100 Subject: [PATCH 12/50] Add missing clauses to and fix authorization rules They are still missing third party invites. --- specification/server_server_api.rst | 39 +++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index c67bea3d..e6e4625c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -356,20 +356,36 @@ the state of the room. The rules are as follows: -1. If type is ``m.room.create``, allow if and only if it has no - previous events - *i.e.* it is the first event in the room. +1. If type is ``m.room.create``: + + a. Reject if it has any previous events + b. Reject if the domain of the ``room_id`` does not match the domain of the + ``sender``. + c. Reject if ``content.room_version`` key is an unrecognized version + d. Otherwise, allow. + +#. Reject if event does not have a ``m.room.create`` in its ``auth_events`` + +#. If type is ``m.room.aliases``: + + a. Reject if event has no ``state_key`` + b. Allow if and only if sender's domain matches ``state_key`` #. If type is ``m.room.member``: - a. If ``membership`` is ``join``: + a. Reject if no ``state_key`` key or ``membership`` key in ``content``. + + #. If ``membership`` is ``join``: i. If the only previous event is an ``m.room.create`` and the ``state_key`` is the creator, allow. #. If the ``sender`` does not match ``state_key``, reject. - #. If the user's current membership state is ``invite`` or ``join``, - allow. + #. If the ``sender`` is banned, reject. + + #. If the ``join_rule`` is ``invite`` then allow if membership state + is ``invite`` or ``join``. #. If the ``join_rule`` is ``public``, allow. @@ -420,9 +436,16 @@ The rules are as follows: #. If the event type's *required power level* is greater than the ``sender``'s power level, reject. +#. If the event has a ``state_key`` that starts with an ``@`` and does not match + the ``sender``, reject. + #. If type is ``m.room.power_levels``: - a. If there is no previous ``m.room.power_levels`` event in the room, allow. + a. If ``users`` key in ``content`` is not a dictionary with keys that are + valid user IDs with values that are integers (or a string that is an + integer), reject. + + #. If there is no previous ``m.room.power_levels`` event in the room, allow. #. For each of the keys ``users_default``, ``events_default``, ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as @@ -447,8 +470,8 @@ The rules are as follows: a. If the ``sender``'s power level is greater than or equal to the *redact level*, allow. - #. If the ``sender`` of the event being redacted is the same as the - ``sender`` of the ``m.room.redaction``, allow. + #. If the domain of the ``event_id`` of the event being redacted is the same + as the domain of the ``event_id`` of the ``m.room.redaction``, allow. #. Otherwise, reject. From 5d40af7ecff9f862fddb79ec2243e1b4167f1795 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 29 Aug 2018 13:24:02 +0100 Subject: [PATCH 13/50] Update rules on which events to add to `auth_events` --- specification/server_server_api.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 9440f2f2..a2a2274d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -299,8 +299,15 @@ following subset of the room state: - The ``m.room.create`` event. - The current ``m.room.power_levels`` event, if any. -- The current ``m.room.join_rules`` event, if any. - The sender's current ``m.room.member`` event, if any. +- If type is ``m.room.member``: + + - The target's current ``m.room.member`` event, if any. + - If ``join`` or ``invite`` then the current ``m.room.join_rules`` event, + if any. + - If ``invite`` with ``third_party_invite`` in ``content``, then add + ``m.room.third_party_invite`` with state_key of ``token`` in ``signed`` + field of ``third_party_invite``, if any. {{definition_ss_pdu}} From 073ebb051b84ead1be988c5dec03fb11ceddc356 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 29 Aug 2018 13:08:07 +0100 Subject: [PATCH 14/50] Spec third party invites in auth rules --- specification/server_server_api.rst | 37 +++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e6e4625c..f2d14738 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -342,6 +342,7 @@ be inserted. The types of state events that affect authorization are: - ``m.room.member`` - ``m.room.join_rules`` - ``m.room.power_levels`` +- ``m.room.third_party_invite`` Servers should not create new events that reference unauthorized events. However, any event that does reference an unauthorized event is not itself @@ -393,7 +394,33 @@ The rules are as follows: #. If ``membership`` is ``invite``: - i. If the ``sender``'s current membership state is not ``join``, reject. + i. If ``content`` has ``third_party_invite`` key: + + #. Reject if *target user* is banned. + + #. Reject if ``content.third_party_invite`` does not have a + ``signed`` key. + + #. Reject if ``signed`` does not have ``mxid`` and ``token`` keys. + + #. Reject if ``mxid`` does not match ``state_key`` + + #. Reject if no ``m.room.third_party_invite`` event in + current state with ``state_key`` matching ``token``. + + #. Reject if ``sender`` does not match ``sender`` of third party + invite. + + #. If any signature in ``signed`` matches any public key in third + party invite, allow. The public keys are in ``content`` of + third party invite under: + + #. A single public key in ``public_key`` field + #. A list of public keys in ``public_keys`` field + + #. Otherwise, reject. + + #. If the ``sender``'s current membership state is not ``join``, reject. #. If *target user*'s current membership state is ``join`` or ``ban``, reject. @@ -433,6 +460,11 @@ The rules are as follows: #. If the ``sender``'s current membership state is not ``join``, reject. +#. If type is ``m.room.third_party_invite``: + + a. Allow if and only if ``sender``'s current power level is greater than + or equal to the *invite level*. + #. If the event type's *required power level* is greater than the ``sender``'s power level, reject. @@ -489,9 +521,6 @@ The rules are as follows: the kick *and* ban levels, *and* greater than the target user's power level. -.. TODO-spec - - I think there is some magic about 3pid invites too. Retrieving event authorization information ++++++++++++++++++++++++++++++++++++++++++ From d921b81c703d8845dc6ea5894880d47564e90a21 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 29 Aug 2018 14:17:52 +0100 Subject: [PATCH 15/50] Reject events with superfluous auth_events entries --- specification/server_server_api.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f2d14738..fb221357 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -365,6 +365,12 @@ The rules are as follows: c. Reject if ``content.room_version`` key is an unrecognized version d. Otherwise, allow. +#. Reject if event has ``auth_events`` that: + + a. have duplicate entries for a given ``type`` and ``state_key`` pair + #. have entries whose ``type`` and ``state_key`` don't match those + specified by the algorithm described previously. + #. Reject if event does not have a ``m.room.create`` in its ``auth_events`` #. If type is ``m.room.aliases``: From ec20c43220d0683d7f25514cbe0e8a2ddd4a43d8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 10:55:34 -0600 Subject: [PATCH 16/50] Specify the minimum CSP for media Fixes https://github.com/matrix-org/matrix-doc/issues/1066 --- specification/modules/content_repo.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index 0f1a9944..f6da38ff 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -33,6 +33,11 @@ recipient's local homeserver, which must first transfer the content from the origin homeserver using the same API (unless the origin and destination homeservers are the same). +When serving content, the server MUST provide a ``Content-Security-Policy`` +header. The policy may be more restrictive, however the minimum policy is +``default-src 'none'; script-src 'none'; plugin-types application/pdf; +style-src 'unsafe-inline'; object-src 'self';``. + Client behaviour ---------------- From 348b549f9f7694a39be0c6f83200332b179788e5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 11:19:37 -0600 Subject: [PATCH 17/50] Add the other fields the server is expected to keep on events Fixes https://github.com/matrix-org/matrix-doc/issues/839 Reference: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/events/utils.py#L44-L91 --- specification/client_server_api.rst | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b377cbb8..cbe7d24a 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1328,16 +1328,30 @@ the following list: - ``state_key`` - ``prev_content`` - ``content`` +- ``hashes`` +- ``signatures`` +- ``depth`` +- ``prev_events`` +- ``prev_state`` +- ``auth_events`` +- ``origin`` +- ``origin_server_ts`` +- ``membership`` + +.. Note: + Some of the keys, such as ``hashes``, will appear on the federation-formatted + event and therefore the client may not be aware of them. The content object should also be stripped of all keys, unless it is one of one of the following event types: -- ``m.room.member`` allows key ``membership`` -- ``m.room.create`` allows key ``creator`` -- ``m.room.join_rules`` allows key ``join_rule`` +- ``m.room.member`` allows key ``membership``. +- ``m.room.create`` allows key ``creator``. +- ``m.room.join_rules`` allows key ``join_rule``. - ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``, ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``. -- ``m.room.aliases`` allows key ``aliases`` +- ``m.room.aliases`` allows key ``aliases``. +- ``m.room.history_visibility`` allows key ``history_visibility``. The server should add the event causing the redaction to the ``unsigned`` property of the redacted event, under the ``redacted_because`` key. When a From 86f616bb31041a6b49f6239adc9193c60cb4b46f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 11:20:51 -0600 Subject: [PATCH 18/50] Changelog --- changelogs/client_server/newsfragments/1602.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1602.clarification diff --git a/changelogs/client_server/newsfragments/1602.clarification b/changelogs/client_server/newsfragments/1602.clarification new file mode 100644 index 00000000..def503cb --- /dev/null +++ b/changelogs/client_server/newsfragments/1602.clarification @@ -0,0 +1 @@ +Add the other keys that redactions are expected to preserve. From 2234e0b0978283f6c26ac4b0da71519a72e1e085 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 12:38:15 -0600 Subject: [PATCH 19/50] Mention that clients should not be producing invalid HTML Fixes https://github.com/matrix-org/matrix-doc/issues/1595 --- specification/modules/instant_messaging.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 079a4801..f3deb220 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -106,6 +106,11 @@ of tags they can render, falling back to other representations of the tags where For example, a client may not be able to render tables correctly and instead could fall back to rendering tab-delimited text. +In addition to not rendering unsafe HTML, clients should not emit unsafe HTML in events. +Likewise, clients should not generate HTML that is not needed, such as extra paragraph tags +surrounding text due to Rich Text Editors. HTML included in events should otherwise be valid, +such as having appropriate closing tags, valid attributes, and generally valid structure. + .. Note:: A future iteration of the specification will support more powerful and extensible message formatting options, such as the proposal `MSC1225 `_. From 60b97fcf26158f2ab05af4c98dc03d9df9dd6b30 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 12:39:25 -0600 Subject: [PATCH 20/50] Changelog --- changelogs/client_server/newsfragments/1605.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1605.clarification diff --git a/changelogs/client_server/newsfragments/1605.clarification b/changelogs/client_server/newsfragments/1605.clarification new file mode 100644 index 00000000..ce9f967d --- /dev/null +++ b/changelogs/client_server/newsfragments/1605.clarification @@ -0,0 +1 @@ +Clarify that clients should not be generating invalid HTML for formatted events. From 9bc14703058adc3558d83f16fadcdf5f92cf8c3a Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 26 Aug 2018 20:25:05 +0900 Subject: [PATCH 21/50] Elaborate the structure of m.tag events ...and corresponding structures in tag-related CS API calls Signed-off-by: Alexey Rusakov --- api/client-server/tags.yaml | 27 +++++++++++++++++++++++---- event-schemas/schema/m.tag | 10 +++++++++- 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index b7bafab6..10809572 100644 --- a/api/client-server/tags.yaml +++ b/api/client-server/tags.yaml @@ -60,13 +60,23 @@ paths: type: object properties: tags: - title: Tags type: object + additionalProperties: + title: Tag + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range ``[0,1]`` describing a relative + position of the room under the given tag. + additionalProperties: true examples: application/json: { "tags": { - "m.favourite": {}, - "u.Work": {"order": "1"}, + "m.favourite": {"order": 0.1}, + "u.Work": {"order": 0.7}, "u.Customers": {} } } @@ -110,8 +120,17 @@ paths: Extra data for the tag, e.g. ordering. schema: type: object + properties: + order: + type: number + format: float + description: |- + A number in a range ``[0,1]`` describing a relative + position of the room under the given tag. + additionalProperties: true example: { - "order": "1"} + "order": 0.25 + } responses: 200: description: diff --git a/event-schemas/schema/m.tag b/event-schemas/schema/m.tag index 80d3f9dd..8da093bd 100644 --- a/event-schemas/schema/m.tag +++ b/event-schemas/schema/m.tag @@ -18,7 +18,15 @@ "description": "The tags on the room and their contents.", "additionalProperties": { "title": "Tag", - "type": "object" + "type": "object", + "properties": { + "order": { + "type": "number", + "format": "float", + "description": + "A number in a range ``[0,1]`` describing a relative position of the room under the given tag." + } + } } } } From c03f2f8d79ac9f589249890382a204ad1158972b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:53:55 -0600 Subject: [PATCH 22/50] Minor touchups to the room tagging API Fixes some of https://github.com/matrix-org/matrix-doc/issues/1565 --- api/client-server/tags.yaml | 34 ++++++++++++++++------------------ event-schemas/examples/m.tag | 2 +- specification/modules/tags.rst | 2 +- 3 files changed, 18 insertions(+), 20 deletions(-) diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 10809572..081d8a84 100644 --- a/api/client-server/tags.yaml +++ b/api/client-server/tags.yaml @@ -43,14 +43,14 @@ paths: required: true description: |- The id of the user to get tags for. The access token must be - authorized to make requests for this user id. + authorized to make requests for this user ID. x-example: "@alice:example.com" - in: path type: string name: roomId required: true description: |- - The id of the room to get tags for. + The ID of the room to get tags for. x-example: "!726s6s6q:example.com" responses: 200: @@ -74,12 +74,12 @@ paths: additionalProperties: true examples: application/json: { - "tags": { - "m.favourite": {"order": 0.1}, - "u.Work": {"order": 0.7}, - "u.Customers": {} - } + "tags": { + "m.favourite": {"order": 0.1}, + "u.Work": {"order": 0.7}, + "u.Customers": {} } + } tags: - User data "/user/{userId}/rooms/{roomId}/tags/{tag}": @@ -97,14 +97,14 @@ paths: required: true description: |- The id of the user to add a tag for. The access token must be - authorized to make requests for this user id. + authorized to make requests for this user ID. x-example: "@alice:example.com" - in: path type: string name: roomId required: true description: |- - The id of the room to add a tag to. + The ID of the room to add a tag to. x-example: "!726s6s6q:example.com" - in: path type: string @@ -112,7 +112,7 @@ paths: required: true description: |- The tag to add. - x-example: "work" + x-example: "u.work" - in: body name: body required: true @@ -138,8 +138,7 @@ paths: schema: type: object examples: - application/json: { - } + application/json: {} tags: - User data delete: @@ -156,14 +155,14 @@ paths: required: true description: |- The id of the user to remove a tag for. The access token must be - authorized to make requests for this user id. + authorized to make requests for this user ID. x-example: "@alice:example.com" - in: path type: string name: roomId required: true description: |- - The id of the room to remove a tag from. + The ID of the room to remove a tag from. x-example: "!726s6s6q:example.com" - in: path type: string @@ -171,15 +170,14 @@ paths: required: true description: |- The tag to remove. - x-example: "work" + x-example: "u.work" responses: 200: description: - The tag was successfully removed + The tag was successfully removed. schema: type: object examples: - application/json: { - } + application/json: {} tags: - User data diff --git a/event-schemas/examples/m.tag b/event-schemas/examples/m.tag index 53dbc921..e5564a4b 100644 --- a/event-schemas/examples/m.tag +++ b/event-schemas/examples/m.tag @@ -2,7 +2,7 @@ "type": "m.tag", "content": { "tags": { - "u.work": {"order": 1} + "u.work": {"order": 0.9} } } } diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index f965c2e8..739ead2c 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -39,7 +39,7 @@ with an ``order`` of ``0.2`` would be displayed before a room with an ``order`` of ``0.7``. If a room has a tag without an ``order`` key then it should appear after the rooms with that tag that have an ``order`` key. -The name of a tag MUST not exceed 255 bytes. +The name of a tag MUST NOT exceed 255 bytes. The tag namespace is defined as follows: From 30ff020ac75d480d3025748fc803546bb784c415 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:57:05 -0600 Subject: [PATCH 23/50] Changelog --- changelogs/client_server/newsfragments/1606.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1606.clarification diff --git a/changelogs/client_server/newsfragments/1606.clarification b/changelogs/client_server/newsfragments/1606.clarification new file mode 100644 index 00000000..f65ed257 --- /dev/null +++ b/changelogs/client_server/newsfragments/1606.clarification @@ -0,0 +1 @@ +Clarify the room tag structure (thanks @KitsuneRal!) From bd9348101333894e5086b7218a773c9c8f4c471e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 23:18:10 -0600 Subject: [PATCH 24/50] Reference that transaction IDs may be used to echo Fixes https://github.com/matrix-org/matrix-doc/issues/1462 --- specification/modules/instant_messaging.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 079a4801..f96a4326 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -167,9 +167,14 @@ message which they receive from the event stream. The echo of the same message from the event stream is referred to as "remote echo". Both echoes need to be identified as the same message in order to prevent duplicate messages being displayed. Ideally this pairing would occur transparently to the user: the UI -would not flicker as it transitions from local to remote. Flickering cannot be -fully avoided in the current client-server API. Two scenarios need to be -considered: +would not flicker as it transitions from local to remote. Flickering can be +reduced through clients making use of the transaction ID they used to send +a particular event. The transaction ID used will be included in the event's +``unsigned`` data as ``transaction_id`` when it arrives through the event stream. + +Clients unable to make use of the transaction ID are more likely to experience +flickering due to the following two scenarios, however the effect can be mitigated +to a degree: - The client sends a message and the remote echo arrives on the event stream *after* the request to send the message completes. From 3d99c8b5a8344523af29791e374908227da3692f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 23:19:18 -0600 Subject: [PATCH 25/50] Changelog --- changelogs/client_server/newsfragments/1619.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1619.clarification diff --git a/changelogs/client_server/newsfragments/1619.clarification b/changelogs/client_server/newsfragments/1619.clarification new file mode 100644 index 00000000..fa06e969 --- /dev/null +++ b/changelogs/client_server/newsfragments/1619.clarification @@ -0,0 +1 @@ +Add a note that clients may use the transaction ID to avoid flickering when doing local echo. From 5c2b8e35693c311e77781e78b7b3dbfdc1fae244 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 30 Aug 2018 17:03:16 +0100 Subject: [PATCH 26/50] Explain how to handle rejeceted events --- specification/server_server_api.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 244a8b82..4c40d6dc 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -472,6 +472,24 @@ The rules are as follows: I think there is some magic about 3pid invites too. +Rejection ++++++++++ + +If an event is rejected it should neither be relayed to clients nor be included +as a prev event in any new events generated by the server. Subsequent events +from other servers that reference rejected events should be allowed if they +still pass the auth rules. The state used in the checks should be calculated as +normal, except not updating with the rejected event where it is a state event. + +If an event in an incoming transaction is rejected, this should not cause the +transaction request to be responded to with an error response. + +.. NOTE:: + + This means that events may be included in the room DAG even though they + should be rejected. + + Retrieving event authorization information ++++++++++++++++++++++++++++++++++++++++++ From 440841d1ffd0f3d4398019da26e61e7340cd12ef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 12:13:21 -0600 Subject: [PATCH 27/50] Recommend a CSP rather than require it. --- changelogs/client_server/newsfragments/1600.feature | 1 + specification/modules/content_repo.rst | 7 +++---- 2 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1600.feature diff --git a/changelogs/client_server/newsfragments/1600.feature b/changelogs/client_server/newsfragments/1600.feature new file mode 100644 index 00000000..142a67b2 --- /dev/null +++ b/changelogs/client_server/newsfragments/1600.feature @@ -0,0 +1 @@ +Recommend that servers set a Content Security Policy for the content repository. diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index f6da38ff..51cf999a 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -33,10 +33,9 @@ recipient's local homeserver, which must first transfer the content from the origin homeserver using the same API (unless the origin and destination homeservers are the same). -When serving content, the server MUST provide a ``Content-Security-Policy`` -header. The policy may be more restrictive, however the minimum policy is -``default-src 'none'; script-src 'none'; plugin-types application/pdf; -style-src 'unsafe-inline'; object-src 'self';``. +When serving content, the server SHOULD provide a ``Content-Security-Policy`` +header. The recommended policy is ``default-src 'none'; script-src 'none'; +plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';``. Client behaviour ---------------- From b8f2c721dc9bfbd44b6545c96a99755b490e58a7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 12:22:50 -0600 Subject: [PATCH 28/50] Clarify which attributes should be valid --- specification/modules/instant_messaging.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index f3deb220..d6cc9f09 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -109,7 +109,8 @@ back to rendering tab-delimited text. In addition to not rendering unsafe HTML, clients should not emit unsafe HTML in events. Likewise, clients should not generate HTML that is not needed, such as extra paragraph tags surrounding text due to Rich Text Editors. HTML included in events should otherwise be valid, -such as having appropriate closing tags, valid attributes, and generally valid structure. +such as having appropriate closing tags, appropriate attributes (considering the custom ones +defined in this specification), and generally valid structure. .. Note:: A future iteration of the specification will support more powerful and extensible From 4630c067213c3c30b2a96c8c0383166e6ac8f56f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 11:24:36 -0600 Subject: [PATCH 29/50] Appservice r0.1.0 changelog --- changelogs/application_service.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/changelogs/application_service.rst b/changelogs/application_service.rst index e69de29b..9d098837 100644 --- a/changelogs/application_service.rst +++ b/changelogs/application_service.rst @@ -0,0 +1,7 @@ +r0.1.0 +====== + +This is the first release of the Application Service specification. It +includes support for application services being able to interact with +homeservers and bridge third party networks, such as IRC, over to Matrix +in a standard and accessible way. From 5e6a2c30a2171366049fbde23c0b55711b2b1b79 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 15:00:14 -0600 Subject: [PATCH 30/50] Comment out the part where identity services can revoke their keys They can't because otherwise 3rd party invites can be rejected by homeservers, as per https://github.com/matrix-org/matrix-doc/issues/1633 --- specification/identity_service_api.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index cb079593..d438f2c7 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -80,9 +80,11 @@ 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". -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. +.. TODO: Actually allow identity services to revoke all keys + See: https://github.com/matrix-org/matrix-doc/issues/1633 +.. 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 keypairs, which may have different usage and lifetime characteristics than the From 356626845ccadabdb5d9239eb80e010c505bde40 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 15:00:52 -0600 Subject: [PATCH 31/50] Remove unhelpful arrow from the 3rd party invite sequence dance This doesn't add anything in terms of clarity. --- specification/modules/third_party_invites.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index a9b06258..0af81844 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -190,10 +190,6 @@ H3 is attempting to join. | | | (Federation) Emit m.room.member for invite | | | | | |----------------------------------------------->| | | | | | | | | - | | | | Accept event | | - | | | |------------- | | - | | | | | | | - | | | |<------------ | | | | | | | | | | | (Federation) Emit the m.room.member event sent to H2 | | | | |----------------------------------------------------------------->| | From 1f6499d563ab26af66f80a0d946cc0c07aa87176 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 15:01:20 -0600 Subject: [PATCH 32/50] Fix typo --- specification/modules/third_party_invites.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 0af81844..248b9ba9 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -138,7 +138,7 @@ validate that the public key used for signing is still valid, by checking No other homeservers may reject the joining of the room on the basis of ``key_validity_url``, this is so that all homeservers have a consistent view of -the room. They may, however, indicate to their clients that a member's' +the room. They may, however, indicate to their clients that a member's membership is questionable. For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, and an From 98a445890ced148d6b9dd54e631401d092d4e477 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 13:25:01 -0600 Subject: [PATCH 33/50] Render a warning if the spec is unstable Fixes https://github.com/matrix-org/matrix-doc/issues/1499 This is done by using magic variables in the RST. The magic variables are generated based on the substitutions available, making them available for use at build-time. Magic variables were chosen because it allows people to continue working on the spec and release process without having to worry about removing a chunk of text from the top of the file. Originally, this was attempted by using jinja2 if-statements, however the substitutions are replaced *after* the template is executed, so the condition would never match. The format of the variable is to make the templating happy. Using colons or percent signs results in the templator thinking something else is going on, and then complaining about format. --- scripts/templating/matrix_templates/sections.py | 7 +++++++ scripts/templating/matrix_templates/units.py | 16 ++++++++++++++++ specification/application_service_api.rst | 2 ++ specification/client_server_api.rst | 2 ++ specification/identity_service_api.rst | 2 ++ specification/push_gateway.rst | 2 ++ specification/server_server_api.rst | 2 ++ 7 files changed, 33 insertions(+) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 4c07649d..f4c015c7 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -207,6 +207,13 @@ class MatrixSections(Sections): apis = self.units.get("apis") return template.render(apis=apis) + def render_unstable_warnings(self): + rendered = {} + blocks = self.units.get("unstable_warnings") + for var, text in blocks.items(): + rendered["unstable_warning_block_" + var] = text + return rendered + def render_swagger_definition(self): rendered = {} template = self.env.get_template("schema-definition.tmpl") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 94b535b5..11a9d441 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -971,6 +971,22 @@ class MatrixUnits(Units): return changelogs + def load_unstable_warnings(self, substitutions): + warning = """ +.. WARNING:: + You are viewing an unstable version of this specification. Unstable + specifications may change at any time without notice. To view the + current specification, please `click here `_. +""" + warnings = {} + for var in substitutions.keys(): + key = var[1:-1] # take off the surrounding %-signs + if substitutions.get(var, "unstable") == "unstable": + warnings[key] = warning + else: + warnings[key] = "" + return warnings + def load_spec_targets(self): with open(TARGETS, "r") as f: diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 69d39d21..8af10df8 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -16,6 +16,8 @@ Application Service API ======================= +{{unstable_warning_block_APPSERVICE_RELEASE_LABEL}} + The Matrix client-server API and server-server APIs provide the means to implement a consistent self-contained federated messaging fabric. However, they provide limited means of implementing custom server-side behaviour in Matrix diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b377cbb8..070d9de9 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -15,6 +15,8 @@ Client-Server API ================= +{{unstable_warning_block_CLIENT_RELEASE_LABEL}} + The client-server API provides a simple lightweight API to let clients send messages, control rooms and synchronise conversation history. It is designed to support both lightweight clients which store no state and lazy-load data from diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 81ff0ede..86170bd8 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -18,6 +18,8 @@ Identity Service API ==================== +{{unstable_warning_block_IDENTITY_RELEASE_LABEL}} + The Matrix client-server and server-server APIs are largely expressed in Matrix user identifiers. From time to time, it is useful to refer to users by other ("third-party") identifiers, or "3pid"s, e.g. their email address or phone diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e4623887..a77d43db 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -16,6 +16,8 @@ Push Gateway API ================ +{{unstable_warning_block_PUSH_GATEWAY_RELEASE_LABEL}} + Clients may want to receive push notifications when events are received at the homeserver. This is managed by a distinct entity called the Push Gateway. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 3bbfa12c..e059d560 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -17,6 +17,8 @@ Federation API ============== +{{unstable_warning_block_SERVER_RELEASE_LABEL}} + .. WARNING:: This API is unstable and will change without warning or discussion while we work towards a r0 release (scheduled for August 2018). From ebb044674f0b83d41ce4c1a323a813162f3821f8 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 09:51:17 +0100 Subject: [PATCH 34/50] Remove duplicated explanation about event rejection --- specification/server_server_api.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 4c40d6dc..2677cf3a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -345,17 +345,6 @@ be inserted. The types of state events that affect authorization are: - ``m.room.join_rules`` - ``m.room.power_levels`` -Servers should not create new events that reference unauthorized events. -However, any event that does reference an unauthorized event is not itself -automatically considered unauthorized. - -Unauthorized events that appear in the event graph do *not* have any effect on -the state of the room. - -.. Note:: This is in contrast to redacted events which can still affect the - state of the room. For example, a redacted ``join`` event will still - result in the user being considered joined. - The rules are as follows: 1. If type is ``m.room.create``, allow if and only if it has no From 6c8a45c165f72884bfc53a90566d77c495529ee0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 09:57:00 +0100 Subject: [PATCH 35/50] Full stops --- specification/server_server_api.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e6e4625c..a69273eb 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -358,18 +358,18 @@ The rules are as follows: 1. If type is ``m.room.create``: - a. Reject if it has any previous events + a. Reject if it has any previous events. b. Reject if the domain of the ``room_id`` does not match the domain of the ``sender``. - c. Reject if ``content.room_version`` key is an unrecognized version + c. Reject if ``content.room_version`` key is an unrecognized version. d. Otherwise, allow. -#. Reject if event does not have a ``m.room.create`` in its ``auth_events`` +#. Reject if event does not have a ``m.room.create`` in its ``auth_events``. #. If type is ``m.room.aliases``: - a. Reject if event has no ``state_key`` - b. Allow if and only if sender's domain matches ``state_key`` + a. Reject if event has no ``state_key``. + b. Allow if and only if sender's domain matches ``state_key``. #. If type is ``m.room.member``: From f3aea32a243c04e79f52304273ab0050ed967872 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 09:59:45 +0100 Subject: [PATCH 36/50] Be consistent with 'If..., reject' --- specification/server_server_api.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a69273eb..a72f5dc6 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -358,22 +358,23 @@ The rules are as follows: 1. If type is ``m.room.create``: - a. Reject if it has any previous events. - b. Reject if the domain of the ``room_id`` does not match the domain of the - ``sender``. - c. Reject if ``content.room_version`` key is an unrecognized version. + a. If it has any previous events, reject. + b. If the domain of the ``room_id`` does not match the domain of the + ``sender``, reject. + c. If ``content.room_version`` key is an unrecognised version, reject. d. Otherwise, allow. -#. Reject if event does not have a ``m.room.create`` in its ``auth_events``. +#. If event does not have a ``m.room.create`` in its ``auth_events``, reject. #. If type is ``m.room.aliases``: - a. Reject if event has no ``state_key``. - b. Allow if and only if sender's domain matches ``state_key``. + a. If event has no ``state_key``, reject + b. If sender's domain doesn't matches ``state_key``, reject. + c. Otherwise, allow. #. If type is ``m.room.member``: - a. Reject if no ``state_key`` key or ``membership`` key in ``content``. + a. If no ``state_key`` key or ``membership`` key in ``content``, reject. #. If ``membership`` is ``join``: From f4706c888986e3e20aa9c4a7b4a3bd77d8812c4b Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 10:06:26 +0100 Subject: [PATCH 37/50] Require creator field --- specification/server_server_api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a72f5dc6..54b6e07c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -362,7 +362,8 @@ The rules are as follows: b. If the domain of the ``room_id`` does not match the domain of the ``sender``, reject. c. If ``content.room_version`` key is an unrecognised version, reject. - d. Otherwise, allow. + d. If ``content`` has no ``creator`` field, reject. + e. Otherwise, allow. #. If event does not have a ``m.room.create`` in its ``auth_events``, reject. From 59f86ec8f2a3b7b07b742ccf5706b44d30c65767 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 10:07:53 +0100 Subject: [PATCH 38/50] Reindent as RST requires sublists to be three spaces --- specification/server_server_api.rst | 128 ++++++++++++++-------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 54b6e07c..b82901be 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -358,80 +358,80 @@ The rules are as follows: 1. If type is ``m.room.create``: - a. If it has any previous events, reject. - b. If the domain of the ``room_id`` does not match the domain of the - ``sender``, reject. - c. If ``content.room_version`` key is an unrecognised version, reject. - d. If ``content`` has no ``creator`` field, reject. - e. Otherwise, allow. + a. If it has any previous events, reject. + b. If the domain of the ``room_id`` does not match the domain of the + ``sender``, reject. + c. If ``content.room_version`` key is an unrecognised version, reject. + d. If ``content`` has no ``creator`` field, reject. + e. Otherwise, allow. #. If event does not have a ``m.room.create`` in its ``auth_events``, reject. #. If type is ``m.room.aliases``: - a. If event has no ``state_key``, reject - b. If sender's domain doesn't matches ``state_key``, reject. - c. Otherwise, allow. + a. If event has no ``state_key``, reject + b. If sender's domain doesn't matches ``state_key``, reject. + c. Otherwise, allow. #. If type is ``m.room.member``: - a. If no ``state_key`` key or ``membership`` key in ``content``, reject. + a. If no ``state_key`` key or ``membership`` key in ``content``, reject. - #. If ``membership`` is ``join``: + #. If ``membership`` is ``join``: - i. If the only previous event is an ``m.room.create`` - and the ``state_key`` is the creator, allow. + i. If the only previous event is an ``m.room.create`` + and the ``state_key`` is the creator, allow. - #. If the ``sender`` does not match ``state_key``, reject. + #. If the ``sender`` does not match ``state_key``, reject. - #. If the ``sender`` is banned, reject. + #. If the ``sender`` is banned, reject. - #. If the ``join_rule`` is ``invite`` then allow if membership state - is ``invite`` or ``join``. + #. If the ``join_rule`` is ``invite`` then allow if membership state + is ``invite`` or ``join``. - #. If the ``join_rule`` is ``public``, allow. + #. If the ``join_rule`` is ``public``, allow. - #. Otherwise, reject. + #. Otherwise, reject. - #. If ``membership`` is ``invite``: + #. If ``membership`` is ``invite``: - i. If the ``sender``'s current membership state is not ``join``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. - #. If *target user*'s current membership state is ``join`` or ``ban``, - reject. + #. If *target user*'s current membership state is ``join`` or ``ban``, + reject. - #. If the ``sender``'s power level is greater than or equal to the *invite - level*, allow. + #. If the ``sender``'s power level is greater than or equal to the *invite + level*, allow. - #. Otherwise, reject. + #. Otherwise, reject. - #. If ``membership`` is ``leave``: + #. If ``membership`` is ``leave``: - i. If the ``sender`` matches ``state_key``, allow if and only if that user's - current membership state is ``invite`` or ``join``. + i. If the ``sender`` matches ``state_key``, allow if and only if that user's + current membership state is ``invite`` or ``join``. - #. If the ``sender``'s current membership state is not ``join``, reject. + #. If the ``sender``'s current membership state is not ``join``, reject. - #. If the *target user*'s current membership state is ``ban``, and the - ``sender``'s power level is less than the *ban level*, reject. + #. If the *target user*'s current membership state is ``ban``, and the + ``sender``'s power level is less than the *ban level*, reject. - #. If the ``sender``'s power level is greater than or equal to the *kick - level*, and the *target user*'s power level is less than the - ``sender``'s power level, allow. + #. If the ``sender``'s power level is greater than or equal to the *kick + level*, and the *target user*'s power level is less than the + ``sender``'s power level, allow. - #. Otherwise, reject. + #. Otherwise, reject. - #. If ``membership`` is ``ban``: + #. If ``membership`` is ``ban``: - i. If the ``sender``'s current membership state is not ``join``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. - #. If the ``sender``'s power level is greater than or equal to the *ban - level*, and the *target user*'s power level is less than the - ``sender``'s power level, allow. + #. If the ``sender``'s power level is greater than or equal to the *ban + level*, and the *target user*'s power level is less than the + ``sender``'s power level, allow. - #. Otherwise, reject. + #. Otherwise, reject. - #. Otherwise, the membership is unknown. Reject. + #. Otherwise, the membership is unknown. Reject. #. If the ``sender``'s current membership state is not ``join``, reject. @@ -443,39 +443,39 @@ The rules are as follows: #. If type is ``m.room.power_levels``: - a. If ``users`` key in ``content`` is not a dictionary with keys that are - valid user IDs with values that are integers (or a string that is an - integer), reject. + a. If ``users`` key in ``content`` is not a dictionary with keys that are + valid user IDs with values that are integers (or a string that is an + integer), reject. - #. If there is no previous ``m.room.power_levels`` event in the room, allow. + #. If there is no previous ``m.room.power_levels`` event in the room, allow. - #. For each of the keys ``users_default``, ``events_default``, - ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as - each entry being changed under the ``events`` or ``users`` keys: + #. For each of the keys ``users_default``, ``events_default``, + ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as + each entry being changed under the ``events`` or ``users`` keys: - i. If the current value is higher than the ``sender``'s current power level, - reject. + i. If the current value is higher than the ``sender``'s current power level, + reject. - #. If the new value is higher than the ``sender``'s current power level, - reject. + #. If the new value is higher than the ``sender``'s current power level, + reject. - #. For each entry being changed under the ``users`` key, other than the - ``sender``'s own entry: + #. For each entry being changed under the ``users`` key, other than the + ``sender``'s own entry: - i. If the current value is equal to the ``sender``'s current power level, - reject. + i. If the current value is equal to the ``sender``'s current power level, + reject. - #. Otherwise, allow. + #. Otherwise, allow. #. If type is ``m.room.redaction``: - a. If the ``sender``'s power level is greater than or equal to the *redact - level*, allow. + a. If the ``sender``'s power level is greater than or equal to the *redact + level*, allow. - #. If the domain of the ``event_id`` of the event being redacted is the same - as the domain of the ``event_id`` of the ``m.room.redaction``, allow. + #. If the domain of the ``event_id`` of the event being redacted is the same + as the domain of the ``event_id`` of the ``m.room.redaction``, allow. - #. Otherwise, reject. + #. Otherwise, reject. #. Otherwise, allow. From 1a45bc4a8591365fd0ab8616d0194a49e21a4913 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 10:24:51 +0100 Subject: [PATCH 39/50] Reword --- specification/server_server_api.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a2a2274d..29d104d9 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -303,11 +303,12 @@ following subset of the room state: - If type is ``m.room.member``: - The target's current ``m.room.member`` event, if any. - - If ``join`` or ``invite`` then the current ``m.room.join_rules`` event, - if any. - - If ``invite`` with ``third_party_invite`` in ``content``, then add - ``m.room.third_party_invite`` with state_key of ``token`` in ``signed`` - field of ``third_party_invite``, if any. + - If membership is ``join`` or ``invite``, the current ``m.room.join_rules`` + event, if any. + - If membership is ``invite`` and ``content`` contains a + ``third_party_invite`` property, the current + ``m.room.third_party_invite`` with state_key matching + ``content.third_party_invite.signed.token``, if any. {{definition_ss_pdu}} From 3c53e1910d87750ef1b8844298dc1e720aba6620 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 10:51:59 +0100 Subject: [PATCH 40/50] Fixup --- specification/server_server_api.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f2d14738..a9c2b1fb 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -396,27 +396,27 @@ The rules are as follows: i. If ``content`` has ``third_party_invite`` key: - #. Reject if *target user* is banned. + #. If *target user* is banned, reject. - #. Reject if ``content.third_party_invite`` does not have a - ``signed`` key. + #. If ``content.third_party_invite`` does not have a + ``signed`` key, reject. - #. Reject if ``signed`` does not have ``mxid`` and ``token`` keys. + #. If ``signed`` does not have ``mxid`` and ``token`` keys, reject. - #. Reject if ``mxid`` does not match ``state_key`` + #. If ``mxid`` does not match ``state_key``, reject. - #. Reject if no ``m.room.third_party_invite`` event in - current state with ``state_key`` matching ``token``. + #. If no ``m.room.third_party_invite`` event in current state with + ``state_key`` matching ``token``, reject. - #. Reject if ``sender`` does not match ``sender`` of third party - invite. + #. If ``sender`` does not match ``sender`` of third party invite, + reject. - #. If any signature in ``signed`` matches any public key in third - party invite, allow. The public keys are in ``content`` of - third party invite under: + #. If any signature in ``signed`` matches any public key in the + ``m.room.third_party_invite``, allow. The public keys are in + ``content`` of ``m.room.third_party_invite`` as: - #. A single public key in ``public_key`` field - #. A list of public keys in ``public_keys`` field + #. A single public key in the ``public_key`` field. + #. A list of public keys in the ``public_keys`` field. #. Otherwise, reject. From d63184ebacc9ff16a620152fb9b057405fd91326 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 10:59:42 +0100 Subject: [PATCH 41/50] Fixup --- specification/server_server_api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index b82901be..4b099e11 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -361,7 +361,8 @@ The rules are as follows: a. If it has any previous events, reject. b. If the domain of the ``room_id`` does not match the domain of the ``sender``, reject. - c. If ``content.room_version`` key is an unrecognised version, reject. + c. If ``content.room_version`` is present and is not a recognised version, + reject. d. If ``content`` has no ``creator`` field, reject. e. Otherwise, allow. @@ -369,7 +370,7 @@ The rules are as follows: #. If type is ``m.room.aliases``: - a. If event has no ``state_key``, reject + a. If event has no ``state_key``, reject. b. If sender's domain doesn't matches ``state_key``, reject. c. Otherwise, allow. From a1aedb386a5ce8ca20bbc2bd79de35262306eb88 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 11:04:44 +0100 Subject: [PATCH 42/50] Actually use proper sentences like a proper adult --- specification/server_server_api.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a9c2b1fb..c225874e 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -405,15 +405,15 @@ The rules are as follows: #. If ``mxid`` does not match ``state_key``, reject. - #. If no ``m.room.third_party_invite`` event in current state with - ``state_key`` matching ``token``, reject. + #. If there is no ``m.room.third_party_invite`` event in the + current room state with ``state_key`` matching ``token``, reject. - #. If ``sender`` does not match ``sender`` of third party invite, - reject. + #. If ``sender`` does not match ``sender`` of the + ``m.room.third_party_invite``, reject. #. If any signature in ``signed`` matches any public key in the - ``m.room.third_party_invite``, allow. The public keys are in - ``content`` of ``m.room.third_party_invite`` as: + ``m.room.third_party_invite`` event, allow. The public keys are + in ``content`` of ``m.room.third_party_invite`` as: #. A single public key in the ``public_key`` field. #. A list of public keys in the ``public_keys`` field. From 4d653748d60abfb631ed1c8fbbd3c5a19eca7721 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 11:17:58 +0100 Subject: [PATCH 43/50] Add note back in --- specification/server_server_api.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 2677cf3a..19f0fb78 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -478,6 +478,12 @@ transaction request to be responded to with an error response. This means that events may be included in the room DAG even though they should be rejected. +.. NOTE:: + + This is in contrast to redacted events which can still affect the + state of the room. For example, a redacted ``join`` event will still + result in the user being considered joined. + Retrieving event authorization information ++++++++++++++++++++++++++++++++++++++++++ From d91dc6fbf628dc2e021abb5cc89d92cd6b3a2c89 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 11:20:26 +0100 Subject: [PATCH 44/50] Fixup --- 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 29d104d9..727ac493 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -303,11 +303,11 @@ following subset of the room state: - If type is ``m.room.member``: - The target's current ``m.room.member`` event, if any. - - If membership is ``join`` or ``invite``, the current ``m.room.join_rules`` - event, if any. + - If ``membership`` is ``join`` or ``invite``, the current + ``m.room.join_rules`` event, if any. - If membership is ``invite`` and ``content`` contains a ``third_party_invite`` property, the current - ``m.room.third_party_invite`` with state_key matching + ``m.room.third_party_invite`` event with ``state_key`` matching ``content.third_party_invite.signed.token``, if any. {{definition_ss_pdu}} From b6ed25e4b4b2810f2a09582d9dce45821f967a33 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 11:32:29 +0100 Subject: [PATCH 45/50] Fix incorrect indent --- 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 fbf48393..5eacba8a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -434,7 +434,7 @@ The rules are as follows: #. A single public key in the ``public_key`` field. #. A list of public keys in the ``public_keys`` field. - #. Otherwise, reject. + #. Otherwise, reject. #. If the ``sender``'s current membership state is not ``join``, reject. From 080845ac1c50dcc3479c819abced912aa20a8cd5 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 31 Aug 2018 11:53:21 +0100 Subject: [PATCH 46/50] Add link to previous section --- specification/server_server_api.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e5bff698..74704faf 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -308,6 +308,8 @@ creating a new event in this room should populate the new event's | E4 +.. _`auth events selection`: + The ``auth_events`` field of a PDU identifies the set of events which give the sender permission to send the event. The ``auth_events`` for the ``m.room.create`` event in a room is empty; for other events, it should be the @@ -384,7 +386,7 @@ The rules are as follows: a. have duplicate entries for a given ``type`` and ``state_key`` pair #. have entries whose ``type`` and ``state_key`` don't match those - specified by the algorithm described previously. + specified by the `auth events selection`_ algorithm described above. #. If event does not have a ``m.room.create`` in its ``auth_events``, reject. From fc037b3a7210863814444e545aaaa542702a0c7f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:33:30 -0600 Subject: [PATCH 47/50] Fix merge --- event-schemas/schema/core-event-schema/sync_room_event.yaml | 3 ++- event-schemas/schema/core-event-schema/sync_state_event.yaml | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/core-event-schema/sync_room_event.yaml b/event-schemas/schema/core-event-schema/sync_room_event.yaml index fbbf154f..8006148f 100644 --- a/event-schemas/schema/core-event-schema/sync_room_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -31,7 +31,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: diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml index 30af9698..1b6ce9b2 100644 --- a/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -28,6 +28,10 @@ properties: 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. + + 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 From 2f824df8dd72454909087ccfafcb6bf9c778d1e0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:43:29 -0600 Subject: [PATCH 48/50] Define the real event types on the invite_state --- api/client-server/sync.yaml | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 0f096e13..9422abb4 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -202,8 +202,29 @@ paths: the room then the current state will be given as a delta against the archived ``state`` not the ``invite_state``. - allOf: - - $ref: "definitions/state_event_batch.yaml" + properties: + events: + description: The StrippedState events that form the invite state. + 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 leave: title: Left rooms type: object From e3ad253dcaeb184e64147d1f4ecbd4e06b4c7834 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:44:29 -0600 Subject: [PATCH 49/50] A sender is also required for the invite_state --- api/client-server/sync.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 9422abb4..bb514bbe 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -206,7 +206,9 @@ paths: events: description: The StrippedState events that form the invite state. items: - description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.' + description: |- + A stripped down state event, with only the ``type``, ``state_key``, + ``sender``, and ``content`` keys. properties: content: description: The ``content`` for the event. @@ -218,10 +220,14 @@ paths: type: description: The ``type`` for the event. type: string + sender: + description: The ``sender`` for the event. + type: string required: - type - state_key - content + - sender title: StrippedState type: object type: array From ab00630ebc3c6aa73c2d7573e5e8a197e7bc6a28 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:49:24 -0600 Subject: [PATCH 50/50] Don't include a second unstable warning in the s2s spec for now --- specification/server_server_api.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e059d560..3bbfa12c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -17,8 +17,6 @@ Federation API ============== -{{unstable_warning_block_SERVER_RELEASE_LABEL}} - .. WARNING:: This API is unstable and will change without warning or discussion while we work towards a r0 release (scheduled for August 2018).