From f873bae0cc0339cd9b275d755b1534772f8757a1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 16:46:10 -0600 Subject: [PATCH] Improve documentation for how non-third party invites work The details are fairly straightforward. An `event` has been added to the response body because that's what Synapse returns, despite the spec saying otherwise until now: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/federation/federation_server.py#L339 --- .../definitions/invite_event.yaml | 3 +- api/server-server/definitions/pdu.yaml | 2 +- api/server-server/invites.yaml | 63 ++++++++++++++----- specification/server_server_api.rst | 5 ++ 4 files changed, 55 insertions(+), 18 deletions(-) diff --git a/api/server-server/definitions/invite_event.yaml b/api/server-server/definitions/invite_event.yaml index 9cef8061..d196339a 100644 --- a/api/server-server/definitions/invite_event.yaml +++ b/api/server-server/definitions/invite_event.yaml @@ -47,7 +47,7 @@ allOf: title: Membership Event Content description: |- The content of the event, matching what is available in the - `Client-Server API`_. + `Client-Server API`_. Must include a ``membership`` of ``invite``. example: {"membership": "invite"} properties: membership: @@ -85,4 +85,3 @@ allOf: required: # Every other field is already flagged as required by the $ref - state_key - - unsigned # TODO: apparently this is required? Verify. diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml index a5da57c0..bb14ede2 100644 --- a/api/server-server/definitions/pdu.yaml +++ b/api/server-server/definitions/pdu.yaml @@ -36,7 +36,7 @@ allOf: signatures: type: object description: |- - Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_. + Signatures for the PDU, following the algorithm specified in `Signing Events`_. example: { "example.com": { "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml index a5d21938..4a0a610e 100644 --- a/api/server-server/invites.yaml +++ b/api/server-server/invites.yaml @@ -25,11 +25,11 @@ produces: paths: "/invite/{roomId}/{eventId}": put: - summary: Invites a user to a room + summary: Invites a remote user to a room description: |- - Invites a remote user to a room. Once 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. + Invites a remote user to a room. Once the event has been signed by both the inviting + homeserver and the invited homeserver, it can be sent to all of the servers in the + room by the inviting homeserver. operationId: sendInvite parameters: - in: path @@ -41,7 +41,7 @@ paths: - in: path name: eventId type: string - description: The event ID for the invite event. + description: The event ID for the invite event, generated by the inviting server. required: true x-example: "$abc123:example.org" - in: body @@ -53,11 +53,15 @@ paths: example: { "$ref": "examples/pdu.json", "type": "m.room.member", - "state_key": "@someone:example.org", + "state_key": "@joe:elsewhere.com", "content": { "membership": "invite" }, - "unsigned": {} + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } } responses: 200: @@ -72,17 +76,46 @@ paths: - type: integer description: The value ``200``. example: 200 - - $ref: "definitions/invite_event.yaml" + - type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: "definitions/invite_event.yaml" + required: ['event'] examples: application/json: [ 200, { - "$ref": "examples/pdu.json", - "type": "m.room.member", - "state_key": "@someone:example.org", - "content": { - "membership": "invite" - }, - "unsigned": {} + "event": { + "$ref": "examples/pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } + } + } } ] + 403: + description: |- + The invite is not allowed. This could be for a number of reasons, including: + + * The sender is not allowed to send invites to the target user/homeserver. + * The homeserver does not permit anyone to invite its users. + * The homeserver refuses to participate in the room. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f1825f27..9d48f113 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -879,6 +879,11 @@ that requested by the requester in the ``v`` parameter). Inviting to a room ------------------ +When a user on a given homeserver invites another user on the same homeserver, +the homeserver may sign the membership event itself and skip the process defined +here. However, when a user invites another user on a different homeserver, a request +to that homeserver to have the event signed and verified must be made. + {{invites_ss_http_api}} Third-party invites