document msisdn-related endpoints in IS (#1507)

* add msisdn endpoints in Identity Server spec
* add in CS endpoints that use the IS msisdn endpoints

api/client-server/administrative_contact.yaml

@@ -66,7 +66,7 @@ paths:
                     medium:
                       type: string
                       description: The medium of the third party identifier.
-                      enum: ["email"]
+                      enum: ["email", "msisdn"]
                     address:
                       type: string
                       description: The third party identifier address.
@@ -143,7 +143,21 @@ paths:
         validation tokens when adding an email address to an account. This API's
         parameters and response is identical to that of the HS API
         |/register/email/requestToken|_ endpoint.
-      operationId: requestTokenTo3PID
+      operationId: requestTokenTo3PIDEmail
       responses:
         200:
-          description: An email was sent to the given address
+          description: An email was sent to the given address.
+  "/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.
+      description: |-
+        Proxies the identity server 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
+        |/register/msisdn/requestToken|_ endpoint.
+      operationId: requestTokenTo3PIDMSISDN
+      responses:
+        200:
+          description: An SMS message was sent to the given phone number.

api/client-server/registration.yaml

@@ -196,11 +196,9 @@ paths:
       description: |-
         Proxies the identity server API ``validate/email/requestToken``, but
         first checks that the given email address is not already associated
-        with an account on this Home Server. Note that, for consistency,
+        with an account on this Home Server. See the Identity Server API for
-        this API takes JSON objects, though the Identity Server API takes
-        ``x-www-form-urlencoded`` parameters. See the Identity Server API for
         further information.
-      operationId: requestTokenToRegister
+      operationId: requestTokenToRegisterEmail
       parameters:
         - in: body
           name: body
@@ -252,6 +250,71 @@ paths:
               }
           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
+        first checks that the given phone number is not already associated
+        with an account on this Home Server. See the Identity Server API for
+        further information.
+      operationId: requestTokenToRegisterMSISDN
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              id_server:
+                type: string
+                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.
+                example: "id.matrix.org"
+              client_secret:
+                type: string
+                description: Client-generated secret string used to protect this session.
+                example: "this_is_my_secret_string"
+              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.
+                example: "example@example.com"
+              send_attempt:
+                type: number
+                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
+        400:
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
+              However, if the home server has the ability to send SMS message, it is recommended that the server
+              instead send an SMS message to the user with instructions on how to reset their password.
+              This prevents malicious parties from being able to determine if a given phone number
+              has an account on the Home Server in question.
+            * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
+              that is not trusted by this Home Server.
+          examples:
+            application/json: {
+                "errcode": "M_THREEPID_IN_USE",
+                "error": "The specified address is already in use"
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
   "/account/password":
     post:
       summary: "Changes a user's password."
@@ -319,10 +382,32 @@ paths:
         .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
 
         .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
-      operationId: requestTokenToResetPassword
+      operationId: requestTokenToResetPasswordEmail
       responses:
         200:
           description: An email was sent to the given address
+  "/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
+        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
+        SMS message to the given address prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
+
+        .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
+      operationId: requestTokenToResetPasswordMSISDN
+      responses:
+        200:
+          description: An SMS message was sent to the given phone number.
   "/account/deactivate":
     post:
       summary: "Deactivate a user's account."

api/identity/phone_associations.yaml

@@ -0,0 +1,203 @@
+# 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 Identity Service Phone Number Associations API"
+  version: "1.0.0"
+host: localhost:8090
+schemes:
+  - https
+  - http
+basePath: /_matrix/identity/api/v1
+produces:
+  - application/json
+paths:
+  "/validate/msisdn/requestToken":
+    post:
+      summary: Request a token for validating a phone number.
+      description: |-
+        Create a session for validating a phone number.
+
+        The identity service will send an SMS message containing a token. If
+        that token is presented to the identity service in the future, it
+        indicates that that user was able to read the SMS for that phone
+        number, and so we validate ownership of the phone number.
+
+        Note that Home Servers offer APIs that proxy this API, adding
+        additional behaviour on top, for example,
+        ``/register/msisdn/requestToken`` is designed specifically for use when
+        registering an account and therefore will inform the user if the phone
+        number given is already registered on the server.
+
+        Note: for backwards compatibility with older versions of this
+        specification, the parameters may also be specified as
+        ``application/x-form-www-urlencoded`` data. However, this usage is
+        deprecated.
+      operationId: msisdnRequestToken
+      parameters:
+        - in: body
+          name: body
+          schema:
+            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.
+              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:
+            Session created.
+          examples:
+            application/json: {
+                "sid": "1234"
+              }
+          schema:
+            type: object
+            properties:
+              sid:
+                type: string
+                description: The session ID.
+        400:
+          description: |
+            An error ocurred. Some possible errors are:
+
+            - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
+            - ``M_SEND_ERROR``: The validation SMS could not be sent.
+  "/validate/msisdn/submitToken":
+    post:
+      summary: Validate ownership of a phone number.
+      description: |-
+        Validate ownership of a phone number.
+
+        If the three parameters are consistent with a set generated by a
+        ``requestToken`` call, ownership of the phone number is considered to
+        have been validated. This does not publish any information publicly, or
+        associate the phone number address with any Matrix user
+        ID. Specifically, calls to ``/lookup`` will not show a binding.
+
+        Note: for backwards compatibility with older versions of this
+        specification, the parameters may also be specified as
+        ``application/x-form-www-urlencoded`` data. However, this usage is
+        deprecated.
+      operationId: msisdnSubmitTokenPost
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "sid": "1234",
+                "client_secret": "monkeys_are_GREAT",
+                "token": "atoken"
+              }
+            properties:
+              sid:
+                type: string
+                description: The session ID, generated by the ``requestToken`` call.
+              client_secret:
+                type: string
+                description: The client secret that was supplied to the ``requestToken`` call.
+              token:
+                type: string
+                description: The token generated by the ``requestToken`` call and sent to the user.
+            required: ["sid", "client_secret", "token"]
+      responses:
+        200:
+          description:
+            The success of the validation.
+          examples:
+            application/json: {
+                "success": true
+              }
+          schema:
+            type: object
+            properties:
+              success:
+                type: boolean
+                description: Whether the validation was successful or not.
+    get:
+      summary: Validate ownership of a phone number.
+      description: |-
+        Validate ownership of a phone number.
+
+        If the three parameters are consistent with a set generated by a
+        ``requestToken`` call, ownership of the phone number address is
+        considered to have been validated. This does not publish any
+        information publicly, or associate the phone number with any Matrix
+        user ID. Specifically, calls to ``/lookup`` will not show a binding.
+
+        Note that, in contrast with the POST version, this endpoint will be
+        used by end-users, and so the response should be human-readable.
+      operationId: msisdnSubmitTokenGet
+      parameters:
+        - in: query
+          type: string
+          name: sid
+          required: true
+          description: The session ID, generated by the ``requestToken`` call.
+          x-example: 1234
+        - in: query
+          type: string
+          name: client_secret
+          required: true
+          description: The client secret that was supplied to the ``requestToken`` call.
+          x-example: monkeys_are_GREAT
+        - in: query
+          type: string
+          name: token
+          required: true
+          description: The token generated by the ``requestToken`` call and sent to the user.
+          x-example: atoken
+      responses:
+        "200":
+          description: Phone number is validated.
+        "3xx":
+          description: |-
+            Phone number address is validated, and the ``next_link`` parameter
+            was provided to the ``requestToken`` call. The user must be
+            redirected to the URL provided by the ``next_link`` parameter.
+        "4xx":
+          description:
+            Validation failed.

changelogs/client_server/newsfragments/1507.new

@@ -0,0 +1 @@
+``POST /account/3pid/msisdn/requestToken``, ``POST /register/msisdn/requestToken``, and ``POST /account/password/msisdn/requestToken``

specification/identity_service_api.rst

@@ -119,6 +119,11 @@ Email associations
 
 {{email_associations_is_http_api}}
 
+Phone number associations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+{{phone_associations_is_http_api}}
+
 General
 ~~~~~~~