Add submit_url field to requestToken responses, clarify HS's can send tokens themselves

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:
@@ -212,34 +230,31 @@ paths:
     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: "../identity/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
@@ -266,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: "../identity/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

api/client-server/definitions/request_token_response.yaml

@@ -0,0 +1,37 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# 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.
+type: object
+properties:
+  sid:
+    type: string
+    description: |-
+      The session ID. Session IDs are opaque strings that must consist entirely
+      of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255
+      characters and they must not be empty.
+    example: "123abc"
+  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"
+required: ['sid']

api/client-server/registration.yaml

@@ -210,35 +210,28 @@ paths:
     post:
       summary: Begins the validation process for an email to be used during registration.
       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. See the Identity Service API for
-        further information.
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. The homeserver
+        has the choice of validating the email address itself, or proxying the
+        request to the ``/validate/email/requestToken`` Identity Service API. The
+        request should be proxied to the domain that is sent by the client in
+        the ``id_server``. It is imperative that the homeserver keep a list of
+        trusted Identity Servers and only proxies to those it trusts.
       operationId: requestTokenToRegisterEmail
       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: "../identity/definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
-            An email has been sent to the specified address.
-            Note that this may be an email containing the validation token or it may be informing
-            the user of an error.
+            An email has been sent to the specified 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 permit the address to be bound.
           schema:
@@ -270,35 +263,28 @@ paths:
     post:
       summary: Requests a validation token be sent to the given phone number for the purpose of registering an 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. See the Identity Service API for
-        further information.
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. The homeserver
+        has the choice of validating the phone number itself, or proxying the
+        request to the ``/validate/msisdn/requestToken`` Identity Service API. The
+        request should be proxied to the domain that is sent by the client in
+        the ``id_server``. It is imperative that the homeserver keep a list of
+        trusted Identity Servers and only proxies to those it trusts.
       operationId: requestTokenToRegisterMSISDN
       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: "../identity/definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: |-
-            An SMS message has been sent to the specified phone number.
-            Note that this may be an SMS message containing the validation token or it may be informing
-            the user of an error.
+            An SMS message has been sent to the specified phone number. Note
+            that this may be an SMS message 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 permit the address to be bound.
           schema:
@@ -383,16 +369,25 @@ paths:
     post:
       summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
       description: |-
-        Proxies the Identity Service API ``validate/email/requestToken``, but
-        first checks that the given email address **is** associated with an account
-        on this homeserver. This API should be used to request
-        validation tokens when authenticating for the
-        `account/password` endpoint. This API's parameters and response are
-        identical to that of the HS API |/register/email/requestToken|_ except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        The homeserver must check that the given email address **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        ``/account/password`` endpoint.
+
+        This API's parameters and response are identical to that of the
+        |/register/email/requestToken|_ endpoint, except that
+        ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
         given email address could be found. The server may instead send an
         email to the given address prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
+        ``M_THREEPID_IN_USE`` may not be returned.
+
+        The homeserver has the choice of validating the email address itself,
+        or proxying the request to the ``/validate/email/requestToken``
+        Identity Service API. The request should be proxied to the domain that
+        is sent by the client in the ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
+
 
         .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
 
@@ -403,22 +398,12 @@ paths:
           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: "../identity/definitions/request_email_validation.yaml"
       responses:
         200:
           description: An email was sent to the given address.
           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
@@ -445,16 +430,24 @@ paths:
     post:
       summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
       description: |-
-        Proxies the Identity Service API ``validate/msisdn/requestToken``, but
-        first checks that the given phone number **is** associated with an account
-        on this homeserver. This API should be used to request
-        validation tokens when authenticating for the
-        `account/password` endpoint. This API's parameters and response are
-        identical to that of the HS API |/register/msisdn/requestToken|_ except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given phone number could be found. The server may instead send an
-        SMS message to the given address prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
+        The homeserver must check that the given phone number **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        ``/account/password`` endpoint.
+
+        This API's parameters and response are identical to that of the
+        |/register/msisdn/requestToken|_ endpoint, except that
+        ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+        given phone number could be found. The server may instead send the SMS
+        to the given phone number prompting the user to create an account.
+        ``M_THREEPID_IN_USE`` may not be returned.
+
+        The homeserver has the choice of validating the phone number itself, or
+        proxying the request to the ``/validate/msisdn/requestToken`` Identity
+        Service API. The request should be proxied to the domain that is sent
+        by the client in the ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
 
         .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
 
@@ -465,22 +458,12 @@ paths:
           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: "../identity/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

api/identity/definitions/request_email_validation.yaml

@@ -45,7 +45,15 @@ properties:
   next_link:
     type: string
     description: |-
-      Optional. When the validation is completed, the identity
-      server will redirect the user to this URL.
+      Optional. When the validation is completed, the identity server will
+      redirect the user to this URL. This option is ignored when submitting
+      3PID validation information through a POST request.
     example: "https://example.org/congratulations.html"
-required: ["client_secret", "email", "send_attempt"]
+  id_server:
+    type: string
+    description: |-
+      The hostname of the identity server to communicate with. May optionally
+      include a port. This parameter is ignored when the homeserver handles
+      3PID verification.
+    example: "id.example.com"
+required: ["client_secret", "email", "send_attempt", "id_server"]