Merge branch 'master' into matthew/msc1849

.buildkite/pipeline.yaml

@@ -9,3 +9,8 @@ steps:
     plugins:
       - docker#v3.0.1:
           image: "python:3.6"
+
+  - label: "rebuild matrix.org"
+    trigger: "matrix-dot-org"
+    async: true
+    branches: "master"

CONTRIBUTING.rst

@@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
 server before they can be documented in the specification. This process can take
 some time to complete.
 
-For this reason, we have not found the github pull-request model effective for
-discussing changes to the specification. Instead, we have adopted the workflow
-as described at https://matrix.org/docs/spec/proposals - *please read this for
-details on how to contribute spec changes*.
+Changes to the protocol (new endpoints, ideas, etc) need to go through the
+`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
+such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
+If you're not sure, visit us at `#matrix-spec:matrix.org`_
+and ask.
 
 
 Other changes
@@ -51,32 +52,31 @@ following:
   <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
 
   (If there is any doubt about whether it is the spec or the implementations
-  that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
-  <http://matrix.to/#/#matrix-dev:matrix.org>`_.)
+  that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
 
 * Clarifications to the specification which do not change the behaviour of
   Matrix servers or clients in a way which might introduce compatibility
   problems for existing deployments. This includes anything with the
   `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
   label.
 
-  For example, recommendations for UI behaviour do not require a proposal
-  document. On the other hand, changes to event contents would be best
-  discussed in a proposal document even though no changes would be necessary to
-  server implementations.
+  For example, areas where the specification is unclear do not require a proposal
+  to fix. On the other hand, introducing new behaviour is best represented by a
+  proposal.
 
-For such changes, please do just open a `pull request`_.
+For such changes, please do just open a `pull request`_. If you're not sure if
+your change is covered by the above, please visit `#matrix-spec:matrix.org` and
+ask.
 
-.. _pull request: https://help.github.com/articles/about-pull-requests
+.. _`pull request`: https://help.github.com/articles/about-pull-requests
+.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
 
 
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Currently only changes to the client-server API need to end up in a changelog. The
-other APIs are not yet stable and therefore do not have a changelog. Adding to the
-changelog can only be done after you've opened your pull request, so be sure to do
-that first.
+All API specifications require a changelog entry. Adding to the changelog can only
+be done after you've opened your pull request, so be sure to do that first.
 
 The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
 form of "news fragments". The news fragments for the client-server API are stored
@@ -96,7 +96,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``breaking`` - Used when the change is not backwards compatible.
 
-* ``deprecation`` - Used when deprecating something
+* ``deprecation`` - Used when deprecating something.
 
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with

api/application-service/transactions.yaml

@@ -56,7 +56,7 @@ paths:
             example: {
               "events": [
                 {"$ref": "../../event-schemas/examples/m.room.member"},
-                {"$ref": "../../event-schemas/examples/m.room.message#m.text"}
+                {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
             description: Transaction information

api/client-server/administrative_contact.yaml

@@ -134,9 +134,27 @@ paths:
         200:
           description: The addition was successful.
           examples:
-            application/json: {}
+            application/json: {
+              "submit_url": "https://example.org/path/to/submitToken"
+            }
             schema:
               type: object
+              properties:
+                submit_url:
+                  type: string
+                  description: |-
+                    An optional field containing a URL where the client must
+                    submit the validation token to, with identical parameters
+                    to the Identity Service API's ``POST
+                    /validate/email/submitToken`` endpoint. The homeserver must
+                    send this token to the user (if applicable), who should
+                    then be prompted to provide it to the client.
+
+                    If this field is not present, the client can assume that
+                    verification will happen without the client's involvement
+                    provided the homeserver advertises this specification version
+                    in the ``/versions`` response (ie: r0.5.0).
+                  example: "https://example.org/path/to/submitToken"
         403:
           description: The credentials could not be verified with the identity server.
           examples:
@@ -163,6 +181,14 @@ paths:
           schema:
             type: object
             properties:
+              id_server:
+                type: string
+                description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the ``id_server`` the identifier was added through. If the
+                    homeserver does not know the original ``id_server``, it MUST return
+                    a ``id_server_unbind_result`` of ``no-support``.
+                example: "example.org"
               medium:
                 type: string
                 description: The medium of the third party identifier being removed.
@@ -180,41 +206,55 @@ paths:
             user.
           schema:
             type: object
-            properties: {}
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  # XXX: I don't know why, but the order matters here so that "no-support"
+                  # doesn't become "no- support" by the renderer.
+                  - "no-support"
+                  - "success"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the 3PID from the identity server. ``success`` indicates that the
+                  indentity server has unbound the identifier whereas ``no-support``
+                  indicates that the identity server refuses to support the request
+                  or the homeserver was not able to determine an identity server to
+                  unbind from.
+                example: "success"
+            required:
+              - id_server_unbind_result
       tags:
         - User data
   "/account/3pid/email/requestToken":
     post:
       summary: Begins the validation process for an email address for association with the user's account.
       description: |-
-        Proxies the Identity Service API ``validate/email/requestToken``, but
-        first checks that the given email address is **not** already associated
-        with an account on this homeserver. This API should be used to request
-        validation tokens when adding an email address to an account. This API's
-        parameters and response are identical to that of the |/register/email/requestToken|_
-        endpoint.
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding an email address to an
+        account. This API's parameters and response are identical to that of
+        the |/register/email/requestToken|_ endpoint. The homeserver has the
+        choice of validating the email address itself, or proxying the request
+        to the ``/validate/email/requestToken`` Identity Service API as
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
       operationId: requestTokenTo3PIDEmail
       parameters:
         - in: body
           name: body
           required: true
           schema:
-            allOf:
-              - $ref: "../identity/definitions/request_email_validation.yaml"
-              - type: object
-                properties:
-                  id_server:
-                    type: string
-                    description: |-
-                      The hostname of the identity server to communicate with. May
-                      optionally include a port.
-                    example: "id.example.com"
-                required: ['id_server']
+            $ref: "./definitions/request_email_validation.yaml"
       responses:
         200:
-          description: An email was sent to the given address.
+          description: |-
+            An email was sent to the given address. Note that this may be an
+            email containing the validation token or it may be informing the
+            user of an error.
           schema:
-            $ref: "../identity/definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a
@@ -241,34 +281,28 @@ paths:
     post:
       summary: Begins the validation process for a phone number for association with the user's account.
       description: |-
-        Proxies the Identity Service API ``validate/msisdn/requestToken``, but
-        first checks that the given phone number is **not** already associated
-        with an account on this homeserver. This API should be used to request
-        validation tokens when adding a phone number to an account. This API's
-        parameters and response are identical to that of the |/register/msisdn/requestToken|_
-        endpoint.
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding a phone number to an
+        account. This API's parameters and response are identical to that of
+        the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
+        choice of validating the phone number itself, or proxying the request
+        to the ``/validate/msisdn/requestToken`` Identity Service API as
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
       operationId: requestTokenTo3PIDMSISDN
       parameters:
         - in: body
           name: body
           required: true
           schema:
-            allOf:
-              - $ref: "../identity/definitions/request_msisdn_validation.yaml"
-              - type: object
-                properties:
-                  id_server:
-                    type: string
-                    description: |-
-                      The hostname of the identity server to communicate with. May
-                      optionally include a port.
-                    example: "id.example.com"
-                required: ['id_server']
+            $ref: "./definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: An SMS message was sent to the given phone number.
           schema:
-            $ref: "../identity/definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a