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: d69decd5c7/synapse/federation/federation_server.py (L339)

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

@@ -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."
+            }

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