Merge pull request #1636 from turt2live/travis/c2s/id-server

Clean up and flesh out all three editions of the /requestToken API

api/client-server/administrative_contact.yaml

@@ -185,29 +185,109 @@ paths:
         - User data
   "/account/3pid/email/requestToken":
     post:
-      summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account
+      summary: Begins the validation process for an email address for association with the user's account.
       description: |-
-        Proxies the identity server API ``validate/email/requestToken``, but
+        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 Home Server. This API should be used to request
+        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 is identical to that of the HS API
+        parameters and response are identical to that of the |/register/email/requestToken|_
-        |/register/email/requestToken|_ endpoint.
+        endpoint.
       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 service to communicate with. May
+                      optionally include a port.
+                    example: "id.example.com"
+                required: ['id_server']
       responses:
         200:
           description: An email was sent to the given address.
+          schema:
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "Third party identifier already in use"
+            }
   "/account/3pid/msisdn/requestToken":
     post:
-      summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account.
+      summary: Begins the validation process for a phone number for association with the user's account.
       description: |-
-        Proxies the identity server API ``validate/msisdn/requestToken``, but
+        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 Home Server. This API should be used to request
         validation tokens when adding a phone number to an account. This API's
-        parameters and response is identical to that of the HS API
+        parameters and response are identical to that of the |/register/msisdn/requestToken|_
-        |/register/msisdn/requestToken|_ endpoint.
+        endpoint.
       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 service to communicate with. May
+                      optionally include a port.
+                    example: "id.example.com"
+                required: ['id_server']
       responses:
         200:
           description: An SMS message was sent to the given phone number.
+          schema:
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "Third party identifier already in use"
+            }

api/client-server/registration.yaml

@@ -202,111 +202,106 @@ paths:
         - User data
   "/register/email/requestToken":
     post:
-      summary: Requests a validation token be sent to the given email address for the purpose of registering an account
+      summary: Begins the validation process for an email to be used during registration.
       description: |-
-        Proxies the identity server API ``validate/email/requestToken``, but
+        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 Home Server. See the Identity Server API for
+        with an account on this homeserver. See the Identity Service API for
         further information.
       operationId: requestTokenToRegisterEmail
       parameters:
         - in: body
           name: body
+          required: true
           schema:
-            type: object
+            allOf:
-            properties:
+              - $ref: "../identity/definitions/request_email_validation.yaml"
-              id_server:
+              - type: object
-                type: string
+                properties:
-                description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
+                  id_server:
-                example: "id.matrix.org"
+                    type: string
-              client_secret:
+                    description: |-
-                type: string
+                      The hostname of the identity service to communicate with. May
-                description: Client-generated secret string used to protect this session
+                      optionally include a port.
-                example: "this_is_my_secret_string"
+                    example: "id.example.com"
-              email:
+                required: ['id_server']
-                type: string
-                description: The email address
-                example: "example@example.com"
-              send_attempt:
-                type: integer
-                description: Used to distinguish protocol level retries from requests to re-send the email.
-                example: 1
-            required: ["client_secret", "email", "send_attempt"]
       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.
-          examples:
-            application/json: {}
           schema:
-            type: object
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: The homeserver does not permit the address to be bound.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
         400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
 
             * ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server.
-              However, if the home server has the ability to send email, it is recommended that the server
+              However, if the homeserver has the ability to send email, it is recommended that the server
               instead send an email to the user with instructions on how to reset their password.
               This prevents malicious parties from being able to determine if a given email address
-              has an account on the Home Server in question.
+              has an account on the homeserver in question.
             * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
-              that is not trusted by this Home Server.
+              that is not trusted by this homeserver.
           examples:
             application/json: {
-                "errcode": "M_THREEPID_IN_USE",
+              "errcode": "M_THREEPID_IN_USE",
-                "error": "The specified address is already in use"
+              "error": "The specified address is already in use"
-              }
+            }
           schema:
             "$ref": "definitions/errors/error.yaml"
   "/register/msisdn/requestToken":
     post:
       summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
       description: |-
-        Proxies the identity server API ``validate/msisdn/requestToken``, but
+        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 Home Server. See the Identity Server API for
+        with an account on this homeserver. See the Identity Service API for
         further information.
       operationId: requestTokenToRegisterMSISDN
       parameters:
         - in: body
           name: body
+          required: true
           schema:
-            type: object
+            allOf:
-            properties:
+              - $ref: "../identity/definitions/request_msisdn_validation.yaml"
-              id_server:
+              - type: object
-                type: string
+                properties:
-                description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
+                  id_server:
-                example: "id.matrix.org"
+                    type: string
-              client_secret:
+                    description: |-
-                type: string
+                      The hostname of the identity service to communicate with. May
-                description: Client-generated secret string used to protect this session.
+                      optionally include a port.
-                example: "this_is_my_secret_string"
+                    example: "id.example.com"
-              country:
+                required: ['id_server']
-                type: string
-                description: |-
-                  The two-letter uppercase ISO country code that the number in
-                  ``phone_number`` should be parsed as if it were dialled from.
-              phone_number:
-                type: string
-                description: The phone number.
-                example: "example@example.com"
-              send_attempt:
-                type: integer
-                description: Used to distinguish protocol level retries from requests to re-send the SMS message.
-                example: 1
-            required: ["client_secret", "country", "phone_number", "send_attempt"]
       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.
-          examples:
-            application/json: {}
           schema:
-            type: object
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: The homeserver does not permit the address to be bound.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
         400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
@@ -320,9 +315,9 @@ paths:
               that is not trusted by this Home Server.
           examples:
             application/json: {
-                "errcode": "M_THREEPID_IN_USE",
+              "errcode": "M_THREEPID_IN_USE",
-                "error": "The specified address is already in use"
+              "error": "The specified address is already in use"
-              }
+            }
           schema:
             "$ref": "definitions/errors/error.yaml"
   "/account/password":
@@ -378,7 +373,7 @@ 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 server API ``validate/email/requestToken``, but
+        Proxies the identity service API ``validate/email/requestToken``, but
         first checks that the given email address **is** associated with an account
         on this Home Server. This API should be used to request
         validation tokens when authenticating for the
@@ -393,21 +388,61 @@ paths:
 
         .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
       operationId: requestTokenToResetPasswordEmail
+      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 service to communicate with. May
+                      optionally include a port.
+                    example: "id.example.com"
+                required: ['id_server']
       responses:
         200:
-          description: An email was sent to the given address
+          description: An email was sent to the given address.
+          schema:
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Email not found"
+            }
   "/account/password/msisdn/requestToken":
     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 server API ``validate/msisdn/requestToken``, but
+        Proxies the identity service API ``validate/msisdn/requestToken``, but
         first checks that the given phone number **is** associated with an account
         on this Home Server. 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 email address could be found. The server may instead send an
+        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.
 
@@ -415,9 +450,49 @@ paths:
 
         .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
       operationId: requestTokenToResetPasswordMSISDN
+      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 service to communicate with. May
+                      optionally include a port.
+                    example: "id.example.com"
+                required: ['id_server']
       responses:
         200:
           description: An SMS message was sent to the given phone number.
+          schema:
+            $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Phone number not found"
+            }
   "/account/deactivate":
     post:
       summary: "Deactivate a user's account."
@@ -505,7 +580,7 @@ paths:
                   be ``true`` when the server replies with 200 OK.
         400:
           description: |-
-            Part of the request was invalid or the username is not available. This may 
+            Part of the request was invalid or the username is not available. This may
             include one of the following error codes:
 
             * ``M_USER_IN_USE`` : The desired username is already taken.

api/identity/definitions/request_email_validation.yaml

@@ -0,0 +1,46 @@
+# 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.
+type: object
+example: {
+  "client_secret": "monkeys_are_GREAT",
+  "email": "foo@example.com",
+  "send_attempt": 1
+}
+properties:
+  client_secret:
+    type: string
+    description: A unique string used to identify the validation attempt.
+    example: "monkeys_are_GREAT"
+  email:
+    type: string
+    description: The email address to validate.
+    example: "alice@example.org"
+  send_attempt:
+    type: integer
+    description: |-
+      The server will only send an email if the ``send_attempt``
+      is a number greater than the most recent one which it has seen,
+      scoped to that ``email`` + ``client_secret`` pair. This is to
+      avoid repeatedly sending the same email in the case of request
+      retries between the POSTing user and the identity service.
+      The client should increment this value if they desire a new
+      email (e.g. a reminder) to be sent.
+    example: 1
+  next_link:
+    type: string
+    description: |-
+      Optional. When the validation is completed, the identity
+      service will redirect the user to this URL.
+    example: "https://example.org/congratulations.html"
+required: ["client_secret", "email", "send_attempt"]

api/identity/definitions/request_msisdn_validation.yaml

@@ -0,0 +1,53 @@
+# 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.
+type: object
+example: {
+  "client_secret": "monkeys_are_GREAT",
+  "country": "GB",
+  "phone_number": "07700900001",
+  "send_attempt": 1
+}
+properties:
+  client_secret:
+    type: string
+    description: A unique string used to identify the validation attempt.
+    example: "monkeys_are_GREAT"
+  country:
+    type: string
+    description: |-
+      The two-letter uppercase ISO country code that the number in
+      ``phone_number`` should be parsed as if it were dialled from.
+    example: "GB"
+  phone_number:
+    type: string
+    description: The phone number to validate.
+    example: "07700900001"
+  send_attempt:
+    type: integer
+    description: |-
+      The server will only send an SMS if the ``send_attempt`` is a
+      number greater than the most recent one which it has seen,
+      scoped to that ``country`` + ``phone_number`` + ``client_secret``
+      triple. This is to avoid repeatedly sending the same SMS in
+      the case of request retries between the POSTing user and the
+      identity service. The client should increment this value if
+      they desire a new SMS (e.g. a reminder) to be sent.
+    example: 1
+  next_link:
+    type: string
+    description: |-
+      Optional. When the validation is completed, the identity
+      service will redirect the user to this URL.
+    example: "https://example.org/congratulations.html"
+required: ["client_secret", "country", "phone_number", "send_attempt"]

api/identity/definitions/sid.yaml

@@ -0,0 +1,20 @@
+# 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.
+type: object
+properties:
+  sid:
+    type: string
+    description: The session ID.
+    example: "123abc"
+required: ['sid']

api/identity/email_associations.yaml

@@ -50,51 +50,12 @@ paths:
         - in: body
           name: body
           schema:
-            type: object
+            $ref: "definitions/request_email_validation.yaml"
-            example: {
-              "client_secret": "monkeys_are_GREAT",
-              "email": "foo@example.com",
-              "send_attempt": 1
-            }
-            properties:
-              client_secret:
-                type: string
-                description: A unique string used to identify the validation attempt.
-              email:
-                type: string
-                description: The email address to validate.
-              send_attempt:
-                type: integer
-                description: |-
-                  Optional. If specified, the server will only send an email if
-                  the ``send_attempt`` is a number greater than the most recent
-                  one which it has seen (or if it has never seen one), scoped
-                  to that ``email`` + ``client_secret`` pair. This is to avoid
-                  repeatedly sending the same email in the case of request
-                  retries between the POSTing user and the identity
-                  service. The client should increment this value if they
-                  desire a new email (e.g. a reminder) to be sent.
-              next_link:
-                type: string
-                description: |-
-                  Optional. When the validation is completed, the identity
-                  service will redirect the user to this URL.
-            required: ["client_secret", "email"]
       responses:
         200:
-          description:
+          description: Session created.
-            Session created.
-          examples:
-            application/json: {
-              "sid": "1234"
-            }
           schema:
-            type: object
+            $ref: "definitions/sid.yaml"
-            properties:
-              sid:
-                type: string
-                description: The session ID.
-            required: ['sid']
         400:
           description: |
             An error ocurred.  Some possible errors are:

api/identity/phone_associations.yaml

@@ -50,57 +50,12 @@ paths:
         - in: body
           name: body
           schema:
-            type: object
+            $ref: "definitions/request_msisdn_validation.yaml"
-            example: {
-              "client_secret": "monkeys_are_GREAT",
-              "country": "GB",
-              "phone_number": "07700900001",
-              "send_attempt": 1
-            }
-            properties:
-              client_secret:
-                type: string
-                description: A unique string used to identify the validation attempt.
-              country:
-                type: string
-                description: |-
-                  The two-letter uppercase ISO country code that the number in
-                  ``phone_number`` should be parsed as if it were dialled from.
-              phone_number:
-                type: string
-                description: The phone number to validate.
-              send_attempt:
-                type: integer
-                description: |-
-                  Optional. If specified, the server will only send an SMS if
-                  the ``send_attempt`` is a number greater than the most recent
-                  one which it has seen (or if it has never seen one), scoped
-                  to that ``country`` + ``phone_number`` + ``client_secret``
-                  triple. This is to avoid repeatedly sending the same SMS in
-                  the case of request retries between the POSTing user and the
-                  identity service. The client should increment this value if
-                  they desire a new SMS (e.g. a reminder) to be sent.
-              next_link:
-                type: string
-                description: |-
-                  Optional. When the validation is completed, the identity
-                  service will redirect the user to this URL.
-            required: ["client_secret", "country", "phone_number"]
       responses:
         200:
-          description:
+          description: Session created.
-            Session created.
-          examples:
-            application/json: {
-              "sid": "1234"
-            }
           schema:
-            type: object
+            $ref: "definitions/sid.yaml"
-            properties:
-              sid:
-                type: string
-                description: The session ID.
-            required: ['sid']
         400:
           description: |
             An error ocurred. Some possible errors are:

changelogs/client_server/newsfragments/1636.clarification

@@ -0,0 +1 @@
+Include the request and response structures for the various ``/requestToken`` endpoints.