Merge branch 'master' into travis/s2s/backfill

api/application-service/application_service.yaml

@@ -214,7 +214,7 @@ paths:
         This API is called by the homeserver when it wants to present clients
         with specific information about the various third party networks that
         an application service supports.
-      operationId: queryMetadata
+      operationId: getProtocolMetadata
       parameters:
         - in: path
           name: protocol
@@ -270,7 +270,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the application
@@ -321,7 +321,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the application

api/application-service/definitions/protocol_metadata.yaml

@@ -13,6 +13,8 @@
 # limitations under the License.
 type: object
 description: Dictionary of supported third party protocols.
+additionalProperties:
+  $ref: protocol.yaml
 example: {
   "irc": {
     "user_fields": ["network", "nickname"],

api/application-service/definitions/user.yaml

@@ -27,5 +27,5 @@ properties:
     type: object
     example:
       "user": "jim"
-title: Location
+title: User
 type: object

api/client-server/third_party_lookup.yaml

@@ -34,7 +34,9 @@ paths:
         Fetches the overall metadata about protocols supported by the
         homeserver. Includes both the available protocols and all fields
         required for queries against each protocol.
-      operationId: queryMetadata
+      operationId: getProtocols
+      security:
+        - accessToken: []
       responses:
         200:
           description: The protocols supported by the homeserver.
@@ -45,7 +47,9 @@ paths:
       summary: Retrieve metadata about a specific protocol that the homeserver supports.
       description: |-
         Fetches the metadata from the homeserver about a particular third party protocol.
-      operationId: queryMetadata
+      operationId: getProtocolMetadata
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -80,6 +84,8 @@ paths:
         identifier. It should attempt to canonicalise the identifier as much
         as reasonably possible given the network type.
       operationId: queryLocationByProtocol
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -113,6 +119,8 @@ paths:
         Retrieve a Matrix User ID linked to a user on the third party service, given
         a set of user parameters.
       operationId: queryUserByProtocol
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: protocol
@@ -122,7 +130,7 @@ paths:
           required: true
           x-example: irc
         - in: query
-          name: field1, field2...
+          name: fields...
           type: string
           description: |-
             One or more custom fields that are passed to the AS to help identify the user.
@@ -146,12 +154,15 @@ paths:
         Retreive an array of third party network locations from a Matrix room
         alias.
       operationId: queryLocationByAlias
+      security:
+        - accessToken: []
       parameters:
         - in: query
           name: alias
           type: string
           description: The Matrix room alias to look up.
           required: true
+          x-example: "#matrix:matrix.org"
       responses:
         200:
           description: |-
@@ -172,12 +183,15 @@ paths:
       description: |-
         Retreive an array of third party users from a Matrix User ID.
       operationId: queryUserByID
+      security:
+        - accessToken: []
       parameters:
         - in: query 
           name: userid
           type: string
           description: The Matrix User ID to look up.
           required: true
+          x-example: "@bob:matrix.org"
       responses:
         200:
           description: |-

api/openapi_extensions.md

@@ -0,0 +1,23 @@
+# OpenAPI Extensions
+
+For some functionality that is not directly provided by the OpenAPI v2
+specification, some extensions have been added that are to be consistent
+across the specification. The defined extensions are listed below. Extensions
+should not break parsers, however if extra functionality is required, aware
+parsers should be able to take advantage of the added syntax.
+
+## Extensible Query Parameters
+
+<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->
+
+If a unknown amount of query parameters can be added to a request, the `name`
+must be `fields...`, with the trailing ellipses representing the possibility
+of more fields.
+
+Example:
+
+```
+  - in: query
+    name: fields...
+    type: string
+```

api/server-server/definitions/keys.yaml

@@ -20,50 +20,62 @@ properties:
   server_name:
     type: string
     description: DNS name of the homeserver.
-    required: true # TODO: Verify
+    required: true
     example: "example.org"
   verify_keys:
     type: object
-    description: Public keys of the homeserver for verifying digital signatures.
+    description: |-
-    required: true # TODO: Verify
+      Public keys of the homeserver for verifying digital signatures. 
+      
+      The object's key is the algorithm and version combined (``ed25519`` being the 
+      algorithm and ``abc123`` being the version in the example below). Together,
+      this forms the Key ID. The version must have characters matching the regular
+      expression ``[a-zA-Z0-9_]``.
+    required: true
     additionalProperties:
       type: object
       title: Verify Key
       example: {
-        "ed25519:auto2": {
+        "ed25519:abc123": {
-          "key": "Base+64+Encoded+Signature+Verification+Key"
+          "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
         }
       }
       properties:
         key:
           type: string
-          description: The key
+          description: The `Unpadded Base64`_ encoded key.
           required: true
-          example: "Base+64+Encoded+Signature+Verification+Key"
+          example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
   old_verify_keys:
     type: object
-    description: The public keys that the server used to use and when it stopped using them.
+    description: |-
+      The public keys that the server used to use and when it stopped using them. 
+      
+      The object's key is the algorithm and version combined (``ed25519`` being the 
+      algorithm and ``0ldK3y`` being the version in the example below). Together,
+      this forms the Key ID. The version must have characters matching the regular
+      expression ``[a-zA-Z0-9_]``.
     additionalProperties:
       type: object
       title: Old Verify Key
       example: {
-        "ed25519:auto1": {
+        "ed25519:0ldK3y": {
-          "expired_ts": 922834800000,
+          "expired_ts": 1532645052628,
-          "key": "Base+64+Encoded+Signature+Verification+Key"
+          "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
         }
       }
       properties:
         expired_ts:
           type: integer
           format: int64
-          description: The expiration time.
+          description: POSIX timestamp in milliseconds for when this key expired.
           required: true
-          example: 922834800000
+          example: 1532645052628
         key:
           type: string
-          description: The key.
+          description: The `Unpadded Base64`_ encoded key.
           required: true
-          example: "Base+64+Encoded+Signature+Verification+Key"
+          example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
   signatures:
     type: object
     description: Digital signatures for this object signed using the ``verify_keys``.
@@ -72,7 +84,7 @@ properties:
       title: Signed Server
       example: {
         "example.org": {
-          "ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
+          "ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
         }
       }
       additionalProperties:
@@ -80,17 +92,19 @@ properties:
         name: Encoded Signature Verification Key
   tls_fingerprints:
     type: array
-    description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_.
+    description: Hashes of X.509 TLS certificates used by this server.
     items:
       type: object
       title: TLS Fingerprint
       properties:
         sha256:
           type: string
-          description: The encoded fingerprint.
+          description: The `Unpadded Base64`_ encoded fingerprint.
-          example: Base+64+Encoded+SHA-256-Fingerprint
+          example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
   valid_until_ts:
     type: integer
     format: int64
-    description: POSIX timestamp when the list of valid keys should be refreshed.
+    description: |-
+      POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
+      timestamp are no longer valid.
     example: 1052262000000

api/server-server/definitions/keys_query_response.yaml

@@ -15,13 +15,13 @@ type: object
 description: Server keys
 example: {
   "server_keys": [{
-    $ref: "../examples/server_key.json"
+    $ref: "../examples/server_key_notary_signed.json"
   }]
 }
 properties:
   server_keys:
     type: array
     title: Server Keys
-    description: The server keys.
+    description: The queried server's keys, signed by the notary server.
     items:
       $ref: "keys.yaml"

api/server-server/definitions/transaction.yaml

@@ -25,8 +25,10 @@ properties:
   origin_server_ts:
     type: integer
     format: int64
-    description: Timestamp in milliseconds on originating homeserver when this transaction started.
+    description: |-
-    example: 1234567890
+      POSIX timestamp in milliseconds on originating homeserver when this 
+      transaction started.
+    example: 1532991320875
   pdus:
     type: array
     description: List of persistent updates to rooms.

api/server-server/events.yaml

@@ -27,7 +27,7 @@ paths:
     get:
       summary: Get all the state of a given room
       description: |-
-        Retrieves a snapshot of the entire current state of the given room.
+        Retrieves a snapshot of a room's state at a given event.
       operationId: getRoomState
       parameters:
         - in: path
@@ -36,11 +36,81 @@ paths:
           description: The room ID to get state for.
           required: true
           x-example: "!abc123:matrix.org"
+        - in: query
+          name: event_id
+          type: string
+          description: An event ID in the room to retrieve the state at.
+          required: true
+          x-example: "$helloworld:matrix.org"
       responses:
         200:
-          description: The room state for the room (kept under ``pdus``).
+          description: |-
+            The fully resolved state for the room, including the authorization
+            chain for the events.
           schema:
-            $ref: "definitions/transaction.yaml"
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: |-
+                  The full set of authorization events that make up the state
+                  of the room, and their authorization events, recursively.
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              pdus:
+                type: array
+                description: |-
+                  The fully resolved state of the room at the given event.
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+            required: ['auth_chain', 'pdus']
+  "/state_ids/{roomId}":
+    get:
+      summary: Get all the state event IDs of a given room
+      description: |-
+        Retrieves a snapshot of a room's state at a given event, in the form of
+        event IDs. This performs the same function as calling ``/state/{roomId}``,
+        however this returns just the event IDs rather than the full events.
+      operationId: getRoomStateIds
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get state for.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: query
+          name: event_id
+          type: string
+          description: An event ID in the room to retrieve the state at.
+          required: true
+          x-example: "$helloworld:matrix.org"
+      responses:
+        200:
+          description: |-
+            The fully resolved state for the room, including the authorization
+            chain for the events.
+          schema:
+            type: object
+            properties:
+              auth_chain_ids:
+                type: array
+                description: |-
+                  The full set of authorization events that make up the state
+                  of the room, and their authorization events, recursively.
+                items:
+                  type: string
+                example: ["$an_event:domain.com"]
+              pdu_ids:
+                type: array
+                description: |-
+                  The fully resolved state of the room at the given event.
+                items:
+                  type: string
+                example: ["$an_event:domain.com"]
+            required: ['auth_chain_ids', 'pdu_ids']
   "/event/{eventId}":
     get:
       summary: Get a single event

api/server-server/examples/server_key.json

@@ -1,23 +1,23 @@
 {
     "server_name": "example.org",
     "verify_keys": {
-        "ed25519:auto2": {
+        "ed25519:abc123": {
-        "key": "Base+64+Encoded+Signature+Verification+Key"
+            "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
         }
     },
     "old_verify_keys": {
-        "ed25519:auto1": {
+        "ed25519:0ldk3y": {
-        "expired_ts": 922834800000,
+        "expired_ts": 1532645052628,
-            "key": "Base+64+Encoded+Old+Verify+Key"
+            "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
         }
     },
     "signatures": {
         "example.org": {
-        "ed25519:auto2": "Base+64+Encoded+Signature"
+            "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
         }
     },
     "tls_fingerprints": [{
-        "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
+        "sha256": "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
     }],
-    "valid_until_ts": 1052262000000
+    "valid_until_ts": 1652262000000
 }

api/server-server/examples/server_key_notary_signed.json

@@ -0,0 +1,11 @@
+{
+    "$ref": "server_key.json",
+    "signatures": {
+        "example.org": {
+            "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
+        },
+        "notary.server.com": {
+            "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
+        }
+    }
+}

api/server-server/joins.yaml

@@ -29,7 +29,6 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a join event to get into the room.
-        This is part of the `Joining Rooms`_ handshake.
       operationId: makeJoin
       parameters:
         - in: path
@@ -95,7 +94,9 @@ paths:
                     type: array
                     description: |-
                       An event reference list containing the authorization events that would
-                      allow the member to join the room.
+                      allow the member to join the room. This should normally be the 
+                      ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
+                      events.
                     items:
                       type: array
                       maxItems: 2
@@ -128,7 +129,12 @@ paths:
               "state_key": "@someone:example.org",
               "content": {
                   "membership": "join"
-              }
+              },
+              "auth_events": [
+                ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
+                ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
+                ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
+              ]
             }
   "/send_join/{roomId}/{eventId}":
     put:
@@ -250,27 +256,30 @@ paths:
                 title: Room State
                 description: The state for the room.
                 properties:
+                  origin:
+                    type: string
+                    description: The resident server's DNS name.
                   auth_chain:
                     type: array
                     description: The auth chain.
                     items:
                       type: object
-                      properties: {}
+                      schema:
-                      # TODO: Verify schema
+                        $ref: "definitions/pdu.yaml"
                   state:
                     type: array
                     description: The room state.
                     items:
                       type: object
-                      properties: {}
+                      schema:
-                      # TODO: Verify schema
+                        $ref: "definitions/pdu.yaml"
-                required: ["auth_chain", "state"]
+                required: ["auth_chain", "state", "origin"]
           examples:
             application/json: [
               200,
               {
-                # TODO: Use the appropriate refs (see TODOs in schema)
+                "origin": "matrix.org",
-                "auth_chain": [],
+                "auth_chain": [{"$ref": "examples/pdu.json"}],
-                "state": []
+                "state": [{"$ref": "examples/pdu.json"}]
               }
             ]

api/server-server/keys_query.yaml

@@ -25,49 +25,61 @@ produces:
 paths:
   "/query/{serverName}/{keyId}":
     get:
-      summary: Retrieve a server key.
+      summary: Query for another server's keys
-      description: Retrieve a server key.
+      description: |-
+        Query for another server's keys. The receiving (notary) server must
+        sign the keys returned by the queried server.
       operationId: perspectivesKeyQuery
       parameters:
         - in: path
           name: serverName
           type: string
-          description: Server name.
+          description: The server's DNS name to query
           required: true
           x-example: matrix.org
         - in: path
           name: keyId
           type: string
-          description: Key ID.
+          description: |-
-          required: true
+            **Deprecated**. Servers should not use this parameter and instead
-          x-example: TODO # No examples in spec so far
+            opt to return all keys, not just the requested one. The key ID to 
+            look up.
+          required: false
+          x-example: "ed25519:abc123"
         - in: query
           name: minimum_valid_until_ts
           type: integer
           format: int64
-          description: Minimum Valid Until Milliseconds.
+          description: |-
-          required: true # TODO: Verify 
+            A millisecond POSIX timestamp in milliseconds indicating when the returned 
+            certificates will need to be valid until to be useful to the requesting server.
+
+            If not supplied, the current time as determined by the notary server is used.
+          required: false
           x-example: 1234567890
       responses:
         200:
-          description: The keys for the server
+          description: |-
+            The keys for the server, or an empty array if the server could not be reached
+            and no cached keys were available.
           schema:
             $ref: "definitions/keys_query_response.yaml"
   "/query":
     post:
-      summary: Retrieve a server key
+      summary: Query for several server's keys
-      description: Retrieve a server key.
+      description: |-
+        Query for keys from multiple servers in a batch format. The receiving (notary)
+        server must sign the keys returned by the queried servers.
       operationId: bulkPerspectivesKeyQuery
       parameters:
         - in: body
           name: body
           schema:
             type: object
-            # TODO: Improve example
             example: {
               "server_keys": {
-                "{server_name}": {
+                "example.org": {
-                  "{key_id}": {
+                  "ed25519:abc123": {
                     "minimum_valid_until_ts": 1234567890
                   }
                 }
@@ -76,7 +88,16 @@ paths:
             properties:
               server_keys:
                 type: object
-                description: The query criteria.
+                description: |-
+                  The query criteria. The outer ``string`` key on the object is the
+                  server name (eg: ``matrix.org``). The inner ``string`` key is the
+                  Key ID to query for the particular server. If no key IDs are given
+                  to be queried, the notary server should query for all keys. If no
+                  servers are given, the notary server must return an empty ``server_keys``
+                  array in the response.
+
+                  The notary server may return multiple keys regardless of the Key IDs
+                  given.
                 additionalProperties:
                   type: object
                   name: ServerName
@@ -84,16 +105,25 @@ paths:
                   additionalProperties:
                     type: object
                     title: Query Criteria
-                    description: The server keys to query.
+                    description: The server key IDs to query.
                     properties:
                       minimum_valid_until_ts:
                         type: integer
                         format: int64
-                        description: Minimum Valid Until MS.
+                        description: |-
+                          A millisecond POSIX timestamp in milliseconds indicating when
+                          the returned certificates will need to be valid until to be 
+                          useful to the requesting server.
+
+                          If not supplied, the current time as determined by the notary
+                          server is used.
                         example: 1234567890
             required: ['server_keys']
       responses:
         200:
-          description: The keys for the server.
+          description: |-
+            The keys for the queried servers, signed by the notary server. Servers which
+            are offline and have no cached keys will not be included in the result. This
+            may result in an empty array.
           schema:
             $ref: "definitions/keys_query_response.yaml"

api/server-server/keys_server.yaml

@@ -25,18 +25,37 @@ produces:
 paths:
   "/server/{keyId}":
     get:
-      summary: Get the server's key
+      summary: Get the homeserver's public key(s)
-      description: Get the server's key.
+      description: |-
+        Gets the homeserver's published TLS fingerprints and signing keys.
+        The homeserver may have any number of active keys and may have a
+        number of old keys.
+
+        Intermediate notary servers should cache a response for half of its
+        lifetime to avoid serving a stale response. Originating servers should
+        avoid returning responses that expire in less than an hour to avoid
+        repeated reqests for a certificate that is about to expire. Requesting
+        servers should limit how frequently they query for certificates to
+        avoid flooding a server with requests.
+
+        If the server fails to respond to this request, intermediate notary
+        servers should continue to return the last response they received
+        from the server so that the signatures of old events can still be
+        checked.
       operationId: getServerKey
       parameters:
         - in: path
           name: keyId
           type: string
-          description: Key ID
+          description: |-
+            **Deprecated**. Servers should not use this parameter and instead
+            opt to return all keys, not just the requested one. The key ID to 
+            look up.
           required: false
-          x-example: TODO # No examples in the spec so far
+          x-example: "ed25519:abc123"
+          deprecated: true
       responses:
         200:
-          description: The server's keys.
+          description: The homeserver's keys
           schema:
             $ref: "definitions/keys.yaml"

api/server-server/leaving.yaml

@@ -0,0 +1,266 @@
+# 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.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Leave Room API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/make_leave/{roomId}/{userId}":
+    get:
+      summary: Get information required to make a leave event for a room
+      description: |-
+        Asks the receiving server to return information that the sending
+        server will need to prepare a leave event to get out of the room.
+      operationId: makeLeave
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID that is about to be left.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: userId
+          type: string
+          description: The user ID the leave event will be for.
+          required: true
+          x-example: "@someone:example.org"
+      responses:
+        200:
+          description: |-
+            An unsigned event that the sending server may use as a template
+            for when it calls ``/send_leave``.
+          schema:
+            allOf:
+              - $ref: "definitions/unsigned_pdu.yaml"
+              - type: object
+                properties:
+                  # Note: we override a bunch of parameters to change their descriptions
+                  sender:
+                    type: string
+                    description: The user ID of the leaving member.
+                    example: "@someone:example.org"
+                  origin:
+                    type: string
+                    description: The name of the resident homeserver.
+                    example: "matrix.org"    
+                  origin_server_ts:
+                    type: integer
+                    format: int64
+                    description: A timestamp added by the resident homeserver.
+                    example: 1234567890
+                  type:
+                    type: string
+                    description: The value ``m.room.member``.
+                    example: "m.room.member"
+                  state_key:
+                    type: string
+                    description: The user ID of the leaving member.
+                    example: "@someone:example.org"
+                  content:
+                    type: object
+                    title: Membership Event Content
+                    description: The content of the event.
+                    example: {"membership": "leave"}
+                    properties:
+                      membership:
+                        type: string
+                        description: The value ``leave``.
+                        example: "leave"
+                    required: ['membership']
+                  auth_events:
+                    type: array
+                    description: |-
+                      An event reference list containing the authorization events that would
+                      allow the member to leave the room. This should normally be the 
+                      ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
+                      events.
+                    items:
+                      type: array
+                      maxItems: 2
+                      minItems: 2
+                      items:
+                        - type: string
+                          title: Event ID
+                          example: "$abc123:matrix.org"
+                        - type: object
+                          title: Event Hash
+                          example: {
+                            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+                          }
+                          properties:
+                            sha256:
+                              type: string
+                              description: The event hash.
+                              example: abase64encodedsha256hashshouldbe43byteslong
+                          required: ['sha256']
+                  redacts:
+                    type: string
+                    description: Not used.
+                required:
+                  # Every other field is already flagged as required by the $ref
+                  - state_key
+          examples:
+            application/json: {
+              "$ref": "examples/unsigned_pdu.json",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "content": {
+                  "membership": "leave"
+              },
+              "auth_events": [
+                ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
+                ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
+                ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
+              ]
+            }
+        403:
+          description: |-
+            The request is not authorized. This could mean that the user is not in the room.
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "User is not in the room."
+            }
+  "/send_leave/{roomId}/{eventId}":
+    put:
+      summary: Submit a signed leave event to a resident server
+      description: |-
+        Submits a signed leave event to the resident server for it
+        to accept it into the room's graph.
+      operationId: sendLeave
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID that is about to be left.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID for the leave event.
+          required: true
+          x-example: "$abc123:example.org"
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            allOf:
+              - $ref: "definitions/pdu.yaml"
+              - type: object
+                properties:
+                  # Note: we override a bunch of parameters to change their descriptions
+                  sender:
+                    type: string
+                    description: The user ID of the leaving member.
+                    example: "@someone:example.org"
+                  origin:
+                    type: string
+                    description: The name of the leaving homeserver.
+                    example: "matrix.org"    
+                  origin_server_ts:
+                    type: integer
+                    format: int64
+                    description: A timestamp added by the leaving homeserver.
+                    example: 1234567890
+                  type:
+                    type: string
+                    description: The value ``m.room.member``.
+                    example: "m.room.member"
+                  state_key:
+                    type: string
+                    description: The user ID of the leaving member.
+                    example: "@someone:example.org"
+                  content:
+                    type: object
+                    title: Membership Event Content
+                    description: The content of the event.
+                    example: {"membership": "leave"}
+                    properties:
+                      membership:
+                        type: string
+                        description: The value ``leave``.
+                        example: "leave"
+                    required: ['membership']
+                  depth:
+                    type: integer
+                    description: This field must be present but is ignored; it may be 0.
+                    example: 12
+                  auth_events:
+                    type: array
+                    description: |-
+                      An event reference list containing the authorization events that would
+                      allow the member to leave the room.
+                    items:
+                      type: array
+                      maxItems: 2
+                      minItems: 2
+                      items:
+                        - type: string
+                          title: Event ID
+                          example: "$abc123:matrix.org"
+                        - type: object
+                          title: Event Hash
+                          example: {
+                            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+                          }
+                          properties:
+                            sha256:
+                              type: string
+                              description: The event hash.
+                              example: abase64encodedsha256hashshouldbe43byteslong
+                          required: ['sha256']
+                  redacts:
+                    type: string
+                    description: Not used.
+                required:
+                  # Every other field is already flagged as required by the $ref
+                  - state_key
+          example: {
+            "$ref": "examples/pdu.json",
+            "type": "m.room.member",
+            "state_key": "@someone:example.org",
+            "content": {
+                "membership": "leave"
+            }
+          }
+      responses:
+        200:
+          description: |-
+            An empty response to indicate the event was accepted into the graph by
+            the receiving homeserver.
+          schema:
+            type: array
+            minItems: 2
+            maxItems: 2
+            items:
+              - type: integer
+                description: The value ``200``.
+                example: 200
+              - type: object
+                title: Empty Object
+                description: An empty object.
+          examples:
+            application/json: [200, {}]

api/server-server/transactions.yaml

@@ -30,16 +30,18 @@ paths:
         Push messages representing live activity to another server. The destination name
         will be set to that of the receiving server itself. Each embedded PDU in the
         transaction body will be processed.
+
+        The sending server must wait and retry for a 200 OK response before sending a
+        transaction with a different ``txnId`` to the receiving server.
       operationId: sendTransaction
       parameters:
         - in: path
           name: txnId
           type: string
-          # TODO: "Overrides any ID given in the JSON body" - What does this mean?
           description: |-
-            The transaction ID. Overrides any ID given in the JSON body.
+            The transaction ID.
           required: true
-          x-example: TODO # No examples in the spec so far
+          x-example: S0meTransacti0nId
         - in: body
           name: body
           type: object
@@ -51,7 +53,9 @@ paths:
                 properties:
                   edus:
                     type: array
-                    description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
+                    description: |-
+                      List of ephemeral messages. May be omitted if there are no ephemeral 
+                      messages to be sent.
                     items:
                       $ref: "definitions/edu.yaml"
           example: {
@@ -60,5 +64,47 @@ paths:
           }
       responses:
         200:
-          # TODO: Spec this (and figure out what it is)
+          description: |-
-          description: TODO
+            The result of processing the transaction. The server is to use this response even in
+            the event of one or more PDUs failing to be processed.
+          schema:
+            type: array
+            minItems: 2
+            maxItems: 2
+            items:
+              - type: integer
+                description: The value ``200``.
+                example: 200
+              - type: object
+                title: PDU Processing Results
+                description: The results for the processing of each PDU in the transaction.
+                properties:
+                  pdus:
+                    type: object
+                    description: |-
+                      The PDUs from the original transaction. The string key represents the ID of the
+                      PDU (event) that was processed.
+                    additionalProperties:
+                      type: object
+                      title: PDU Processing Result
+                      description: Information about how the PDU was handled.
+                      properties:
+                        error:
+                          type: string
+                          description: |-
+                            A human readable description about what went wrong in processing this PDU.
+                            If no error is present, the PDU can be considered successfully handled.
+                          example: "You are not allowed to send a message to this room."
+                required: ['pdus']
+          examples:
+            application/json: [
+              200,
+              {
+                "pdus": {
+                  "$successful_event:domain.com": {},
+                  "$failed_event:example.org": {
+                    "error": "You are not allowed to send a message to this room."
+                  }
+                }
+              }
+            ]

specification/server_server_api.rst

@@ -106,15 +106,17 @@ Server implementation
 Retrieving Server Keys
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Version 2
+.. NOTE::
-+++++++++
+  There was once a "version 1" of the key exchange. It has been removed from the
+  specification due to lack of significance. It may be reviewed `here
+  <https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1>`_.
 
-Each homeserver publishes its public keys under ``/_matrix/key/v2/server/``.
+Each homeserver publishes its public keys under ``/_matrix/key/v2/server/{keyId}``.
-Homeservers query for keys by either getting ``/_matrix/key/v2/server/``
+Homeservers query for keys by either getting ``/_matrix/key/v2/server/{keyId}``
 directly or by querying an intermediate notary server using a
-``/_matrix/key/v2/query`` API. Intermediate notary servers query the
+``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers 
-``/_matrix/key/v2/server/`` API on behalf of another server and sign the
+query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and
-response with their own key. A server may query multiple notary servers to
+sign the response with their own key. A server may query multiple notary servers to
 ensure that they all report the same public keys.
 
 This approach is borrowed from the `Perspectives Project`_, but modified to
@@ -126,113 +128,33 @@ server by querying other servers.
 .. _Perspectives Project: https://web.archive.org/web/20170702024706/https://perspectives-project.org/
 
 Publishing Keys
-^^^^^^^^^^^^^^^
++++++++++++++++
 
 Homeservers publish the allowed TLS fingerprints and signing keys in a JSON
 object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of
 ``verify_keys`` that are valid for signing federation requests made by the
-server and for signing events. It contains a list of ``old_verify_keys`` which
+homeserver and for signing events. It contains a list of ``old_verify_keys`` which
 are only valid for signing events. Finally the response contains a list of TLS
-certificate fingerprints to validate any connection made to the server.
+certificate fingerprints to validate any connection made to the homeserver.
-
-A server may have multiple keys active at a given time. A server may have any
-number of old keys. It is recommended that servers return a single JSON
-response listing all of its keys whenever any ``key_id`` is requested to reduce
-the number of round trips needed to discover the relevant keys for a server.
-However a server may return different responses for a different ``key_id``.
-
-The ``tls_certificates`` field contains a list of hashes of the X.509 TLS
-certificates currently used by the server. The list must include SHA-256 hashes
-for every certificate currently in use by the server. These fingerprints are
-valid until the millisecond POSIX timestamp in ``valid_until_ts``.
-
-The ``verify_keys`` can be used to sign requests and events made by the server
-until the millisecond POSIX timestamp in ``valid_until_ts``. If a homeserver
-receives an event with a ``origin_server_ts`` after the ``valid_until_ts`` then
-it should request that ``key_id`` for the originating server to check whether
-the key has expired.
-
-The ``old_verify_keys`` can be used to sign events with an ``origin_server_ts``
-before the ``expired_ts``. The ``expired_ts`` is a millisecond POSIX timestamp
-of when the originating server stopped using that key.
-
-Intermediate notary servers should cache a response for half of its remaining
-lifetime to avoid serving a stale response. Originating servers should avoid
-returning responses that expire in less than an hour to avoid repeated requests
-for a certificate that is about to expire. Requesting servers should limit how
-frequently they query for certificates to avoid flooding a server with
-requests.
-
-If a server goes offline intermediate notary servers should continue to return
-the last response they received from that server so that the signatures of old
-events sent by that server can still be checked.
 
 {{keys_server_ss_http_api}}
 
 
 Querying Keys Through Another Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++
 
-Servers may offer a query API ``/_matrix/key/v2/query/`` for getting the keys
+Servers may query another server's keys through a notary server. The notary
-for another server. This API can be used to GET a list of JSON objects for a
+server may be another homeserver. The notary server will retrieve keys from
-given server or to POST a bulk query for a number of keys from a number of
+the queried servers through use of the ``/_matrix/key/v2/server/{keyId}``
-servers. Either way the response is a list of JSON objects containing the
+API. The notary server will additionally sign the response from the queried
-JSON published by the server under ``/_matrix/key/v2/server/`` signed by
+server before returning the results.
-both the originating server and by this server.
 
-The ``minimum_valid_until_ts`` is a millisecond POSIX timestamp indicating
+Notary servers can return keys for servers that are offline or having issues
-when the returned certificate will need to be valid until to be useful to the
+serving their own keys by using cached responses. Keys can be queried from
-requesting server. This can be set using the maximum ``origin_server_ts`` of
+multiple servers to mitigate against DNS spoofing.
-a batch of events that a requesting server is trying to validate. This allows
-an intermediate notary server to give a prompt cached response even if the
-originating server is offline.
-
-This API can return keys for servers that are offline by using cached responses
-taken from when the server was online. Keys can be queried from multiple
-servers to mitigate against DNS spoofing.
 
 {{keys_query_ss_http_api}}
 
-Version 1
-+++++++++
-.. WARNING::
-  Version 1 of key distribution is obsolete.
-
-
-Homeservers publish their TLS certificates and signing keys in a JSON object
-at ``/_matrix/key/v1``.
-
-==================== =================== ======================================
- Key                  Type                Description
-==================== =================== ======================================
-``server_name``      String              DNS name of the homeserver.
-``verify_keys``      Object              Public keys of the homeserver for
-                                         verifying digital signatures.
-``signatures``       Object              Digital signatures for this object
-                                         signed using the ``verify_keys``.
-``tls_certificate``  String              The X.509 TLS certificate used by this
-                                         this server encoded as `Unpadded Base64`_.
-==================== =================== ======================================
-
-.. code:: json
-
-    {
-        "server_name": "example.org",
-        "signatures": {
-            "example.org": {
-                "ed25519:auto": "Base+64+Encoded+Signature"
-            }
-        },
-        "tls_certificate": "Base+64+Encoded+DER+Encoded+X509+TLS+Certificate",
-        "verify_keys": {
-            "ed25519:auto": "Base+64+Encoded+Signature+Verification+Key"
-        }
-    }
-
-When fetching the keys for a server the client should check that the TLS
-certificate in the JSON matches the TLS server certificate for the connection
-and should check that the JSON signatures are correct for the supplied
-``verify_keys``.
 
 Transactions
 ------------
@@ -242,41 +164,7 @@ of Transaction messages, which are encoded as JSON objects, passed over an HTTP
 PUT request. A Transaction is meaningful only to the pair of homeservers that
 exchanged it; they are not globally-meaningful.
 
-Each transaction has:
+{{transactions_ss_http_api}}
- - An opaque transaction ID, unique among transactions from the same origin.
- - A timestamp (UNIX epoch time in milliseconds) generated by its origin
-   server.
- - An origin and destination server name.
- - A list of PDUs and EDUs - the actual message payload that the Transaction
-   carries.
-
-Transaction Fields
-~~~~~~~~~~~~~~~~~~
-
-==================== =================== ======================================
- Key                  Type                Description
-==================== =================== ======================================
-``origin``           String              **Required**. ``server_name`` of homeserver sending
-                                         this transaction.
-``origin_server_ts`` Integer             **Required**. Timestamp in milliseconds on
-                                         originating homeserver when this
-                                         transaction started.
-``pdus``             List of Objects     **Required**. List of persistent updates to rooms.
-``edus``             List of Objects     List of ephemeral messages. May be omitted
-                                         if there are no ephemeral messages to
-                                         be sent.
-==================== =================== ======================================
-
-Example:
-
-.. code:: json
-
- {
-  "origin_server_ts": 1404835423000,
-  "origin": "matrix.org",
-  "pdus": [...],
-  "edus": [...]
- }
 
 PDUs
 ----
@@ -681,16 +569,8 @@ All these URLs are name-spaced within a prefix of::
 
   /_matrix/federation/v1/...
 
-
-{{transactions_ss_http_api}}
-
-{{events_ss_http_api}}
-
 {{query_general_ss_http_api}}
 
-
-{{joins_ss_http_api}}
-
 Joining Rooms
 -------------
 
@@ -742,94 +622,34 @@ homeservers, though most in practice will use just two.
   <---------- join response
 
 The first part of the handshake usually involves using the directory server to
-request the room ID and join candidates. This is covered in more detail on the
+request the room ID and join candidates through the |/query/directory|_
-directory server documentation, below. In the case of a new user joining a
+API endpoint. In the case of a new user joining a room as a result of a received
-room as a result of a received invite, the joining user's homeserver could
+invite, the joining user's homeserver could optimise this step away by picking 
-optimise this step away by picking the origin server of that invite message as
+the origin server of that invite message as the join candidate. However, the 
-the join candidate. However, the joining server should be aware that the origin
+joining server should be aware that the origin server of the invite might since
-server of the invite might since have left the room, so should be prepared to
+have left the room, so should be prepared to fall back on the regular join flow 
-fall back on the regular join flow if this optimisation fails.
+if this optimisation fails.
 
 Once the joining server has the room ID and the join candidates, it then needs
 to obtain enough information about the room to fill in the required fields of
 the ``m.room.member`` event. It obtains this by selecting a resident from the
-candidate list, and requesting the ``make_join`` endpoint using a ``GET``
+candidate list, and using the ``GET /make_join`` endpoint. The resident server
-request, specifying the room ID and the user ID of the new member who is
+will then reply with enough information for the joining server to fill in the
-attempting to join.
+event.
 
-The resident server replies to this request with a JSON-encoded object having a
+The joining server is expected to add or replace the ``origin``, ``origin_server_ts``,
-single key called ``event``; within this is an object whose fields contain some
+and ``event_id`` on the templated event received by the resident server. This
-of the information that the joining server will need. Despite its name, this
+event is then signed by the joining server.
-object is not a full event; notably it does not need to be hashed or signed by
-the resident homeserver. The required fields are:
-
-======================== ============ =========================================
- Key                      Type         Description
-======================== ============ =========================================
-``type``                 String       The value ``m.room.member``.
-``auth_events``          List         An event-reference list containing the
-                                      authorization events that would allow 
-                                      this member to join.
-``content``              Object       The event content.
-``depth``                Integer      (this field must be present but is 
-                                      ignored; it may be 0)
-``origin``               String       The name of the resident homeserver.
-``origin_server_ts``     Integer      A timestamp added by the resident
-                                      homeserver.
-``prev_events``          List         An event-reference list containing the
-                                      immediate predecessor events.
-``room_id``              String       The room ID of the room.
-``sender``               String       The user ID of the joining member.
-``state_key``            String       The user ID of the joining member.
-======================== ============ =========================================
-
-The ``content`` field itself must be an object, containing:
-
-======================== ============ =========================================
- Key                      Type         Description
-======================== ============ =========================================
-``membership``           String       The value ``join``.
-======================== ============ =========================================
-
-The joining server now has sufficient information to construct the real join
-event from these protoevent fields. It copies the values of most of them,
-adding (or replacing) the following fields:
-
-======================== ============ =========================================
- Key                      Type         Description
-======================== ============ =========================================
-``event_id``             String       A new event ID specified by the joining
-                                      homeserver.
-``origin``               String       The name of the joining homeserver.
-``origin_server_ts``     Integer      A timestamp added by the joining
-                                      homeserver.
-======================== ============ =========================================
-
-This will be a true event, so the joining server should apply the event-signing
-algorithm to it, resulting in the addition of the ``hashes`` and ``signatures``
-fields.
 
 To complete the join handshake, the joining server must now submit this new
-event to an resident homeserver, by using the ``send_join`` endpoint. This is
+event to a resident homeserver, by using the ``PUT /send_join`` endpoint.
-invoked using the room ID and the event ID of the new member event.
 
 The resident homeserver then accepts this event into the room's event graph,
 and responds to the joining server with the full set of state for the
-newly-joined room. This is returned as a two-element list, whose first element
+newly-joined room. The resident server must also send the event to other servers
-is the integer 200, and whose second element is an object which contains the
+participating in the room. 
-following keys:
 
-======================== ============ =========================================
+{{joins_ss_http_api}}
- Key                      Type         Description
-======================== ============ =========================================
-``auth_chain``           List         A list of events giving all of the events
-                                      in the auth chains for the join event and
-                                      the events in ``state``.
-``state``                List         A complete list of the prevailing state
-                                      events at the instant just before
-                                      accepting the new ``m.room.member``
-                                      event.
-======================== ============ =========================================
 
 .. TODO-spec
   - (paul) I don't really understand why the full auth_chain events are given
@@ -865,11 +685,41 @@ the events it is missing.
 
 {{backfill_ss_http_api}}
 
+Retriving events
+----------------
+
+In some circumstances, a homeserver may be missing a particular event or information
+about the room which cannot be easily determined from backfilling. These APIs provide
+homeservers with the option of getting events and the state of the room at a given
+point in the timeline.
+
+{{events_ss_http_api}}
+
 Inviting to a room
 ------------------
 
 {{invites_ss_http_api}}
 
+Leaving Rooms (Rejecting Invites)
+---------------------------------
+
+Normally homeservers can send appropriate ``m.room.member`` events to have users
+leave the room, or to reject local invites. Remote invites from other homeservers
+do not involve the server in the graph and therefore need another approach to 
+reject the invite. Joining the room and promptly leaving is not recommended as 
+clients and servers will interpret that as accepting the invite, then leaving the
+room rather than rejecting the invite.
+
+Similar to the `Joining Rooms`_ handshake, the server which wishes to leave the
+room starts with sending a ``/make_leave`` request to a resident server. In the
+case of rejecting invites, the resident server may be the server which sent the
+invite. After receiving a template event from ``/make_leave``, the leaving server
+signs the event and replaces the ``event_id`` with it's own. This is then sent to
+the resident server via ``/send_leave``. The resident server will then send the
+event to other servers in the room.
+
+{{leaving_ss_http_api}}
+
 Third-party invites
 -------------------
 
@@ -1295,6 +1145,9 @@ 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]]
 
+.. |/query/directory| replace:: ``/query/directory``
+.. _/query/directory: #get-matrix-federation-v1-query-directory
+
 .. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
 .. _`Identity Service API`: ../identity_service/unstable.html
 .. _`Client-Server API`: ../client_server/unstable.html#m-room-member