Merge pull request #1450 from turt2live/travis/s2s/inviting-rooms

Improve documentation for how non-third party invites work

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.

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"

api/server-server/invites.yaml

@@ -20,16 +20,18 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/federation/v1
+consumes: 
+  - application/json
 produces:
   - application/json
 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 
+        Invites a remote user to a room. Once the event has been  signed by both the inviting
-        signed by both the inviting homeserver and the invited 
+        homeserver and the invited homeserver, it can be sent to all of the servers in the 
-        homeserver, it can be sent to all of the users in the room.
+        room by the inviting homeserver.
       operationId: sendInvite
       parameters:
         - in: path
@@ -41,7 +43,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
@@ -49,15 +51,85 @@ paths:
           type: object
           required: true
           schema:
-            $ref: "definitions/invite_event.yaml"
+            allOf:
+              - $ref: "definitions/invite_event.yaml"
+              - type: object
+                properties:
+                  unsigned:
+                    type: object
+                    title: Unsigned Event Content
+                    description: |-
+                      Information included alongside the event that is not signed. May include more
+                      than what is listed here.
+                    properties:
+                      invite_room_state:
+                        type: array
+                        description: |-
+                          An optional list of simplified events to help the receiver of the invite
+                          identify the room. The recommended events to include are the join rules,
+                          canonical alias, avatar, and name of the room.
+                        items:
+                          type: object
+                          title: Invite Room State Event
+                          properties:
+                            type:
+                              type: string
+                              description: The type of event.
+                              example: "m.room.join_rules"
+                            state_key:
+                              type: string
+                              description: The state key for the event. May be an empty string.
+                              example: ""
+                            content:
+                              type: object
+                              description: The content for the event.
+                            sender:
+                              type: string
+                              description: The sender of the event.
+                              example: "@someone:matrix.org"
+                          required: ['type', 'state_key', 'content', 'sender']
+                        example: [
+                          {
+                            "type": "m.room.join_rules",
+                            "sender": "@someone:matrix.org",
+                            "state_key": "",
+                            "content": {
+                              "join_rule": "public"
+                            }
+                          }
+                        ]
           example: {
             "$ref": "examples/pdu.json",
             "type": "m.room.member",
-            "state_key": "@someone:example.org",
+            "state_key": "@joe:elsewhere.com",
+            "unsigned": {
+              "invite_room_state": [
+                {
+                  "type": "m.room.join_rules",
+                  "sender": "@someone:matrix.org",
+                  "state_key": "",
+                  "content": {
+                    "join_rule": "public"
+                  }
+                },
+                {
+                  "type": "m.room.name",
+                  "sender": "@someone:matrix.org",
+                  "state_key": "",
+                  "content": {
+                    "name": "Cool New Room"
+                  }
+                }
+              ]
+            },
             "content": {
                 "membership": "invite"
             },
-            "unsigned": {}
+            "signatures": {
+              "example.com": {
+                "ed25519:key_version": "SomeSignatureHere"
+              },
+            }
           }
       responses:
         200:
@@ -72,17 +144,66 @@ 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",
+                "event":  {
-                "type": "m.room.member",
+                  "$ref": "examples/pdu.json",
-                "state_key": "@someone:example.org",
+                  "type": "m.room.member",
-                "content": {
+                  "state_key": "@someone:example.org",
-                    "membership": "invite"
+                  "unsigned": {
-                },
+                    "invite_room_state": [
-                "unsigned": {}
+                      {
+                        "type": "m.room.join_rules",
+                        "sender": "@someone:matrix.org",
+                        "state_key": "",
+                        "content": {
+                          "join_rule": "public"
+                        }
+                      },
+                      {
+                        "type": "m.room.name",
+                        "sender": "@someone:matrix.org",
+                        "state_key": "",
+                        "content": {
+                          "name": "Cool New Room"
+                        }
+                      }
+                    ]
+                  },
+                  "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."
+            }

specification/server_server_api.rst

@@ -633,6 +633,11 @@ point in the timeline.
 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}}
 
 Leaving Rooms (Rejecting Invites)