From af961321e9577efa8fe6eecebe96a5a5c6831e56 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 14 Sep 2017 19:13:36 +0100 Subject: [PATCH] Specify remote invite --- specification/server_server_api.rst | 61 +++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index cb76c3d5..3f8a2c60 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -749,6 +749,64 @@ that requested by the requestor in the ``v`` parameter). Specify (or remark that it is unspecified) how the server handles divergent history. DFS? BFS? Anything weirder? +Inviting to a room +------------------ + +When a user wishes to invite an other user to a local room and this other user +is on a different server, the inviting server will send a request to the invited +server:: + + PUT .../invite/{roomId}/{eventId} + +The required fields in the JSON body are: + +==================== ======== ============ + Key Type Description +==================== ======== ============ +``room_id`` String The room ID of the room. Must be the same as the + room ID specified in the path. +``event_id`` String The ID of the event. Must be the same as the event + ID specified in the path. +``type`` String The value ``m.room.member``. +``auth_events`` List An event-reference list containing the IDs of the + authorization events that would allow this member + to be invited in the room. +``content`` Object The content of the event. +``depth`` Integer The depth of the event. +``origin`` String The name of the inviting homeserver. +``origin_server_ts`` Integer A timestamp added by the inviting homeserver. +``prev_events`` List An event-reference list containing the IDs of the + immediate predecessor events. +``sender`` String The Matrix ID of the user who sent the original + `m.room.third_party_invite`. +``state_key`` String The Matrix ID of the invited user. +``signatures`` Object The signature of the event from the origin server. +``unsigned`` Object An object containing the properties that aren't + part of the signature's computation. +==================== ======== ============ + +Where the ``content`` key contains the content for the ``m.room.member`` event +specified in the `Client-Server API`_. Note that the ``membership`` property of +the content must be ``invite``. + +Upon receiving this request, the invited homeserver will append its signature to +the event and respond to the request with the following JSON body:: + + [ + 200, + "event": {...} + ] + +Where ``event`` contains the event signed by both homeservers, using the same +JSON keys as the initial request on ``/invite/{roomId}/{eventId}``. Note that, +except for the ``signatures`` object (which now contains an additional signature), +all of the event's keys remain the same as in the event initially provided. + +This response format is due to a typo in Synapse, the first implementation of +Matrix's APIs, and is preserved to maintain compatibility. + +Now that the event has been signed by both the inviting homeserver and the +invited homeserver, it can be sent to all of the users in the room. Authentication -------------- @@ -1143,5 +1201,8 @@ that are too long. [[TODO(markjh) We might want to allow the server to omit the output of well known hash functions like SHA-256 when none of the keys have been redacted]] + +.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage +.. _`Client-Server API`: ../client_server/unstable.html#m-room-member .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64