From dfaed5b525ef046f372553fec3b9b4bc156dc1ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 18:18:08 -0600 Subject: [PATCH 01/10] Clean up and flesh out all three editions of the /requestToken API Fixes https://github.com/matrix-org/matrix-doc/issues/1634 Addresses some of https://github.com/matrix-org/matrix-doc/issues/1396 --- api/client-server/administrative_contact.yaml | 88 +++++++++- api/client-server/registration.yaml | 163 +++++++++++------- .../definitions/request_email_validation.yaml | 47 +++++ .../request_msisdn_validation.yaml | 54 ++++++ api/identity/definitions/sid.yaml | 20 +++ api/identity/email_associations.yaml | 45 +---- api/identity/phone_associations.yaml | 51 +----- 7 files changed, 306 insertions(+), 162 deletions(-) create mode 100644 api/identity/definitions/request_email_validation.yaml create mode 100644 api/identity/definitions/request_msisdn_validation.yaml create mode 100644 api/identity/definitions/sid.yaml diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 541df43c86e..1523b2fa343 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -185,29 +185,105 @@ 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 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 is identical to that of the client-server API |/register/email/requestToken|_ 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 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: |- + The homeserver was unable to location a user with the third party identifier + alrady bound, or the request was invalid. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Third party identifier not found" + } "/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 is identical to that of the client-server API |/register/msisdn/requestToken|_ 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 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: |- + The homeserver was unable to location a user with the third party identifier + alrady bound, or the request was invalid. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Third party identifier not found" + } diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index e4b05629187..f32b9019760 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -192,111 +192,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 - 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" - email: - 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"] + 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 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", - "error": "The specified address is already in use" - } + "errcode": "M_THREEPID_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 - 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: 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"] + 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 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: @@ -310,9 +305,9 @@ paths: that is not trusted by this Home Server. examples: application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "The specified address is already in use" - } + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } schema: "$ref": "definitions/errors/error.yaml" "/account/password": @@ -368,7 +363,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 @@ -383,14 +378,32 @@ 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 + schema: + $ref: "../identity/definitions/sid.yaml" "/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 @@ -405,9 +418,27 @@ 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" "/account/deactivate": post: summary: "Deactivate a user's account." @@ -495,7 +526,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. diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml new file mode 100644 index 00000000000..bed8f572fe6 --- /dev/null +++ b/api/identity/definitions/request_email_validation.yaml @@ -0,0 +1,47 @@ +# 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: |- + 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. + 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"] diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml new file mode 100644 index 00000000000..c28ff29c470 --- /dev/null +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -0,0 +1,54 @@ +# 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: |- + 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. + 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"] diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml new file mode 100644 index 00000000000..48cc3828acf --- /dev/null +++ b/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'] diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index dc3cd78ebf5..eb6bc11782d 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -50,51 +50,12 @@ paths: - in: body name: body schema: - 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. - 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"] + $ref: "definitions/request_email_validation.yaml" responses: 200: - description: - Session created. - examples: - application/json: { - "sid": "1234" - } + description: Session created. schema: - type: object - properties: - sid: - type: string - description: The session ID. - required: ['sid'] + $ref: "definitions/sid.yaml" 400: description: | An error ocurred. Some possible errors are: diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index 836984d0251..cc5933a8672 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -50,57 +50,12 @@ paths: - 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"] + $ref: "definitions/request_msisdn_validation.yaml" responses: 200: - description: - Session created. - examples: - application/json: { - "sid": "1234" - } + description: Session created. schema: - type: object - properties: - sid: - type: string - description: The session ID. - required: ['sid'] + $ref: "definitions/sid.yaml" 400: description: | An error ocurred. Some possible errors are: From f3181bbedd0846c62077fd9743b7b6115f68f429 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 18:20:50 -0600 Subject: [PATCH 02/10] Changelog --- changelogs/client_server/newsfragments/1636.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1636.clarification diff --git a/changelogs/client_server/newsfragments/1636.clarification b/changelogs/client_server/newsfragments/1636.clarification new file mode 100644 index 00000000000..842cd1f00c7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1636.clarification @@ -0,0 +1 @@ +Include the request and response structures for the various ``/requestToken`` endpoints. From 4bd23a9086b755f556b7ea568c69652fb354db84 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 22:28:50 -0600 Subject: [PATCH 03/10] send_attempt is no longer optional --- .../definitions/request_email_validation.yaml | 15 +++++++-------- .../definitions/request_msisdn_validation.yaml | 7 +++---- 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index bed8f572fe6..805cd1231ba 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -29,14 +29,13 @@ properties: 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. + 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 diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index c28ff29c470..f8e37d3926d 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -36,10 +36,9 @@ properties: 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`` + 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 From a4c2b2b90503bd070b43504774f2a99c6692cc53 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 10:32:30 -0600 Subject: [PATCH 04/10] General clarity and spelling for the requestToken APIs --- api/client-server/administrative_contact.yaml | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 1523b2fa343..e3f96fa3118 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -189,10 +189,10 @@ paths: 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 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 client-server API - |/register/email/requestToken|_ endpoint. + parameters and response is identical to that of the |/register/email/requestToken|_ + endpoint. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -216,7 +216,10 @@ paths: schema: $ref: "../identity/definitions/sid.yaml" 403: - description: The homeserver does not permit the address to be bound. + description: |- + The homeserver does not permit the user from having the third party + identifier as a contact option. This does not prevent the identity + service from binding the third party identifier, however. schema: $ref: "definitions/errors/error.yaml" examples: @@ -226,8 +229,8 @@ paths: } 400: description: |- - The homeserver was unable to location a user with the third party identifier - alrady bound, or the request was invalid. + The homeserver was unable to locate a user with the third party identifier + already bound, or the request was invalid. schema: $ref: "definitions/errors/error.yaml" examples: @@ -243,8 +246,8 @@ paths: 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 client-server API - |/register/msisdn/requestToken|_ endpoint. + parameters and response is identical to that of the |/register/msisdn/requestToken|_ + endpoint. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -268,7 +271,10 @@ paths: schema: $ref: "../identity/definitions/sid.yaml" 403: - description: The homeserver does not permit the address to be bound. + description: |- + The homeserver does not permit the user from having the third party + identifier as a contact option. This does not prevent the identity + service from binding the third party identifier, however. schema: $ref: "definitions/errors/error.yaml" examples: From 63fdd72f737f2ad61b70751ffb9832fef7c76616 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 11:24:35 -0600 Subject: [PATCH 05/10] Fix error description on /account/3pid/email/requestToken --- api/client-server/administrative_contact.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index e3f96fa3118..d2594c958c1 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -229,14 +229,14 @@ paths: } 400: description: |- - The homeserver was unable to locate a user with the third party identifier - already bound, or the request was invalid. + 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_NOT_FOUND", - "error": "Third party identifier not found" + "errcode": "M_THREEPID_IN_USE", + "error": "Third party identifier already in use" } "/account/3pid/msisdn/requestToken": post: From 60dd9231e0ff0114a04ad9f5666ba7527b025164 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 11:26:28 -0600 Subject: [PATCH 06/10] Don't explain how the IS might accept a 3pid The IS is bound to it's own set of specifications, and if the client chose this API then they should be aware of the risks but not necessarily arbitrary alternatives. --- api/client-server/administrative_contact.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index d2594c958c1..0fdbf742ce9 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -218,8 +218,7 @@ paths: 403: description: |- The homeserver does not permit the user from having the third party - identifier as a contact option. This does not prevent the identity - service from binding the third party identifier, however. + identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: @@ -273,8 +272,7 @@ paths: 403: description: |- The homeserver does not permit the user from having the third party - identifier as a contact option. This does not prevent the identity - service from binding the third party identifier, however. + identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: From 5bb7eca8e8d70c91d179793284cf642779af57ff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 11:31:03 -0600 Subject: [PATCH 07/10] English --- api/client-server/administrative_contact.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 0fdbf742ce9..2fba9540383 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -191,7 +191,7 @@ paths: 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 is identical to that of the |/register/email/requestToken|_ + parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. operationId: requestTokenTo3PIDEmail parameters: @@ -245,7 +245,7 @@ paths: 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 |/register/msisdn/requestToken|_ + parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. operationId: requestTokenTo3PIDMSISDN parameters: @@ -282,8 +282,8 @@ paths: } 400: description: |- - The homeserver was unable to location a user with the third party identifier - alrady bound, or the request was invalid. + The homeserver was unable to locate a user with the third party identifier + already bound, or the request was invalid. schema: $ref: "definitions/errors/error.yaml" examples: From 824ce22caaae00a76f8d965f575197995c245903 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 11:41:46 -0600 Subject: [PATCH 08/10] Add additional clarity to the requestToken errors --- api/client-server/administrative_contact.yaml | 8 ++-- api/client-server/registration.yaml | 48 ++++++++++++++++++- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 2fba9540383..ddfbe172594 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -282,12 +282,12 @@ paths: } 400: description: |- - The homeserver was unable to locate a user with the third party identifier - already bound, or the request was invalid. + 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_NOT_FOUND", - "error": "Third party identifier not found" + "errcode": "M_THREEPID_IN_USE", + "error": "Third party identifier already in use" } diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 7b1230cb5f3..b935b4f7c20 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -406,9 +406,31 @@ paths: 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 permit the user from having 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_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. @@ -420,7 +442,7 @@ paths: `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. @@ -449,6 +471,28 @@ paths: description: An SMS message was sent to the given phone number. schema: $ref: "../identity/definitions/sid.yaml" + 403: + description: |- + The homeserver does not permit the user from having 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_NOT_FOUND", + "error": "Phone number not found" + } "/account/deactivate": post: summary: "Deactivate a user's account." From 1261da209dc368de9f59826813dceab747ae391c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 14:38:22 -0600 Subject: [PATCH 09/10] Fix wording for the homeserver not allowing a particular 3pid --- api/client-server/administrative_contact.yaml | 8 ++++---- api/client-server/registration.yaml | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index ddfbe172594..5699a884fbc 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -217,8 +217,8 @@ paths: $ref: "../identity/definitions/sid.yaml" 403: description: |- - The homeserver does not permit the user from having the third party - identifier as a contact option. + The homeserver does not allow the third party identifier as a + contact option. schema: $ref: "definitions/errors/error.yaml" examples: @@ -271,8 +271,8 @@ paths: $ref: "../identity/definitions/sid.yaml" 403: description: |- - The homeserver does not permit the user from having the third party - identifier as a contact option. + The homeserver does not allow the third party identifier as a + contact option. schema: $ref: "definitions/errors/error.yaml" examples: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index b935b4f7c20..9861d9051ad 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -411,8 +411,8 @@ paths: $ref: "../identity/definitions/sid.yaml" 403: description: |- - The homeserver does not permit the user from having the third party - identifier as a contact option. + The homeserver does not allow the third party identifier as a + contact option. schema: $ref: "definitions/errors/error.yaml" examples: @@ -473,8 +473,8 @@ paths: $ref: "../identity/definitions/sid.yaml" 403: description: |- - The homeserver does not permit the user from having the third party - identifier as a contact option. + The homeserver does not allow the third party identifier as a + contact option. schema: $ref: "definitions/errors/error.yaml" examples: From a1f655e5be073416a5e0cc098ffc1eb0dc8c52e4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 14:53:59 -0600 Subject: [PATCH 10/10] Fix more error wording --- api/client-server/registration.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 9861d9051ad..324abbffddc 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -422,8 +422,8 @@ paths: } 400: description: |- - The third party identifier is already in use on the homeserver, or - the request was invalid. + The referenced third party identifier is not recognised by the + homeserver, or the request was invalid schema: $ref: "definitions/errors/error.yaml" examples: @@ -484,8 +484,8 @@ paths: } 400: description: |- - The third party identifier is already in use on the homeserver, or - the request was invalid. + The referenced third party identifier is not recognised by the + homeserver, or the request was invalid schema: $ref: "definitions/errors/error.yaml" examples: