From fdea3e34a864aa55e5fe48f797741e64f6d19c52 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 12 Sep 2019 13:30:51 +0100 Subject: [PATCH 01/28] wip --- temp | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 temp diff --git a/temp b/temp new file mode 100644 index 00000000000..e69de29bb2d From 7096092da901a1e3feda3341c213727f1608a1cb Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 12 Sep 2019 13:52:52 +0100 Subject: [PATCH 02/28] init --- proposals/2290-separate-threepid-bind-hs.md | 190 ++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 proposals/2290-separate-threepid-bind-hs.md diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md new file mode 100644 index 00000000000..a62e5b39820 --- /dev/null +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -0,0 +1,190 @@ +# Separate Endpoints for Binding Threepids + +On the Client Server API there is currently a single API for binding a +threepid (an email or a phone number): [POST +/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). +Depending on whether the `bind` flag is `true` or `false`, the threepid will +be bound to either a user's account on the homeserver, or both the homeserver +and an identity server. + +A threepid can be bound to an identity server to allow other users to find +their Matrix ID using their email address or phone number. A threepid can +also be bound to a user's account on the homeserver. This allows that +threepid to be used for message notifications, login, password reset, and +other important functions. + +Typically, when using the `POST /_matrix/client/r0/account/3pid` endpoint, +the identity server handles the verification -- either by sending an email to +the email address, or a SMS message to the phone number. Once completed, the +homeserver would check with the identity server that verification had indeed +happened, and if so, the threepid would be bound (again, either to the +homeserver, or the homeserver and identity server simultaneously). + +Now, consider the fact that the identity server used in this process is +provided by the user, using the endpoint's `id_server` parameter. If the user were +to supply a malicious identity server that would immediately answer "yes" to +any threepid validation, then the user could add any threepid to their +account on the homeserver (which is likely not something homeserver admins want). + +To solve this problem, we propose adding a second endpoint that is only used +for binding to an identity server of the user's choice. This endpoint will +not bind the threepid to the user's account on the homeserver, only on the +identity server. + +In addition, the existing binding endpoint will lose the ability to bind +threepids to an identity server, by removing its `bind` flag. Instead, it +will solely be used to bind to the user's account on the homeserver. + +To be clear, the above issue is not a long-standing security issue. Indeed it +is not a problem in any released version of Synapse, as Synapse keeps a list +of "trusted identity servers" that acts a whitelist for what identity servers +a user can specify. + +Synapse is soon to lose this whitelist however, as part of lessening the +reliance of homeservers on identity servers. This cannot be done while the +homeserver is still trusting an identity server for validation of threepids. +If the endpoints are split, the homeserver will handle the validation of +threepids being added to user accounts, and identity servers will validate +threepids being added to their own database. + +One may question why clients don't just contact an identity server directly +to bind a threepid, bypassing the implications of binding through a +homeserver. While this will work, binds should still occur through a +homeserver such that the homeserver can keep track of which binds were made, +which is important when a user wishes to deactivate their account (and remove +all of their bindings made on different identity servers). + +A bind could be made on an identity server, which could then tell the +homeserver that a validation occured, but then there are security +considerations about how to authenticate an identity server in that instance +(and prevent people pretending to be identity servers and telling homeservers +about hundreds of fake binds to a user's account). + +This MSC obseletes +[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt +with changing the rules of the `bind` flag. Since this flag is being removed, +the MSC is no longer relevant. + +## Proposal + +A new endpoint will be added to the Client Server API: `POST /_matrix/client/r0/account/3pid/identity/bind`, and requires authentication. + +The endpoint definition is the same as `POST +/_matrix/client/r0/account/3pid`, minus the `bind` flag. + +An example of binding a threepid to an identity server with this new endpoint: + +First the client must request the threepid be validated by its chosen identity server. + +``` +POST https://identity.server/_matrix/identity/v2/validate/email/requestToken + +{ + "client_secret": "don'tT3ll", + "email": "bob@example.com", + "send_attempt": 1 +} +``` + +Once an email has been sent, the user clicks the link in the email, which +notifies the identity server that the email has been verified. + +Next, the client completes the bind by calling the new endpoint on the homeserver: + +``` +POST https://home.server/_matrix/client/r0/account/3pid/identity/bind + +{ + "three_pid_creds": { + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "don'tT3ll" + } +} +``` + +The homeserver will then make a bind request on behalf of the user to the +specified identity server. The homeserver will record if the bind was +successful and notify the user. + +And for completeness, here is an example of binding a threepid to the +homeserver only, using the old endpoint: + +The homeserver is validating the threepid in this instance, so the client +must use the `/requestToken` endpoint of the homeserver: + +``` +POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken + +{ + "client_secret": "don'tT3ll", + "email": "bob@example.com", + "send_attempt": 1, +} +``` + +Once an email has been sent, the user clicks the link in the email, which +notifies the homeserver that the email has been verified. + +The client then sends a request to the old endpoint to bind the threepid to +user's account. + +``` +POST /_matrix/client/r0/account/3pid + +{ + "three_pid_creds": { + "sid": "abc123987", + "client_secret": "don'tT3ll" + } +} +``` + +The threepid will then be bound to the user's account. + +Users will be able to perform binds to an identity server for a threepid even if that threepid has not been bound to the user's account on the homeserver before. + +The achieve the above flow, some changes need to be made to existing +endpoints as well. This MSC requests that the `id_server` and +`id_access_token` parameters be removed from the Client-Server API's [POST +/_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +endpoint, as this endpoint is now only intended for the homeserver to send +emails from. Additionally, the same parameters will be removed from the [POST +/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid)endpoint's +`three_pid_creds` parameter as an identity server is no longer required to +perform verification. + +This MSC also requests that the text "It is imperative that the homeserver +keep a list of trusted Identity Servers and only proxies to those that it +trusts." be removed from all parts of the spec, as the homeserver should no +longer need to trust any identity servers. + +## Tradeoffs + +It may be possible to reduce the two calls per flow into a single endpoint, +but the current asynchronous approach makes it easy for a client to send a +request, go offline, have the threepid be validated, and then come online +again to finalize the validation afterwards. + +## Backwards compatibility + +TODO + +## Security considerations + +Reducing the homeserver's trust in identity servers should be a boost to security and improve decentralisation in the Matrix ecosystem to boot. + +Caution should be taken for homeserver developers to be sure not to continue +to use user-provided identity servers for any sensitive tasks once it removes +the concept of a trusted identity server. + +## Conclusion + +This MSC helps reduce the homeserver's trust in an identity server even +further to the point where it is only used for binding addresses for lookup - +which was the original intention of the Identity Service API. + +Additionally, by clearly separating the threepid bind endpoint into two +endpoints that each have a clear intention, the concept of threepid binding +becomes a lot easier to reason about. From f5b10c689fc0f83705f161dcae20ce4be9c79715 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 12 Sep 2019 15:55:50 +0100 Subject: [PATCH 03/28] cleanup --- proposals/2290-separate-threepid-bind-hs.md | 68 +++++++++++---------- temp | 0 2 files changed, 37 insertions(+), 31 deletions(-) delete mode 100644 temp diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index a62e5b39820..95e90192f79 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -1,22 +1,22 @@ # Separate Endpoints for Binding Threepids -On the Client Server API there is currently a single API for binding a +On the Client Server API there is currently a single endpoint for binding a threepid (an email or a phone number): [POST /_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver and an identity server. -A threepid can be bound to an identity server to allow other users to find +For context a threepid can be bound to an identity server to allow other users to find their Matrix ID using their email address or phone number. A threepid can -also be bound to a user's account on the homeserver. This allows that +also be bound to a user's account on the homeserver. This allows the threepid to be used for message notifications, login, password reset, and other important functions. Typically, when using the `POST /_matrix/client/r0/account/3pid` endpoint, the identity server handles the verification -- either by sending an email to -the email address, or a SMS message to the phone number. Once completed, the -homeserver would check with the identity server that verification had indeed +an email address, or a SMS message to a phone number. Once completed, the +homeserver will check with the identity server that verification had indeed happened, and if so, the threepid would be bound (again, either to the homeserver, or the homeserver and identity server simultaneously). @@ -28,7 +28,7 @@ account on the homeserver (which is likely not something homeserver admins want) To solve this problem, we propose adding a second endpoint that is only used for binding to an identity server of the user's choice. This endpoint will -not bind the threepid to the user's account on the homeserver, only on the +not bind the threepid to the user's account on the homeserver, only the identity server. In addition, the existing binding endpoint will lose the ability to bind @@ -67,12 +67,12 @@ the MSC is no longer relevant. ## Proposal -A new endpoint will be added to the Client Server API: `POST /_matrix/client/r0/account/3pid/identity/bind`, and requires authentication. - -The endpoint definition is the same as `POST +A new endpoint will be added to the Client Server API: `POST +/_matrix/client/r0/account/3pid/identity/bind`, and will require +authentication. The endpoint definition is the same as `POST /_matrix/client/r0/account/3pid`, minus the `bind` flag. -An example of binding a threepid to an identity server with this new endpoint: +An example of binding a threepid to **an identity server only** with this new endpoint is as follows: First the client must request the threepid be validated by its chosen identity server. @@ -104,11 +104,15 @@ POST https://home.server/_matrix/client/r0/account/3pid/identity/bind } ``` -The homeserver will then make a bind request on behalf of the user to the -specified identity server. The homeserver will record if the bind was -successful and notify the user. +The homeserver will then make a bind request to the specified identity server +on behalf of the user. The homeserver will record if the bind was successful +and notify the user. + +The threepid has now been binded on the user's identity server without +causing that threepid to be used for password resets or any other +homeserver-related functions. -And for completeness, here is an example of binding a threepid to the +For completeness, here is an example of binding a threepid to the homeserver only, using the old endpoint: The homeserver is validating the threepid in this instance, so the client @@ -125,10 +129,10 @@ POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken ``` Once an email has been sent, the user clicks the link in the email, which -notifies the homeserver that the email has been verified. +notifies the homeserver that the threepid has been verified. -The client then sends a request to the old endpoint to bind the threepid to -user's account. +The client then sends a request to the old endpoint on the homeserver to bind +the threepid to user's account. ``` POST /_matrix/client/r0/account/3pid @@ -143,15 +147,16 @@ POST /_matrix/client/r0/account/3pid The threepid will then be bound to the user's account. -Users will be able to perform binds to an identity server for a threepid even if that threepid has not been bound to the user's account on the homeserver before. - -The achieve the above flow, some changes need to be made to existing -endpoints as well. This MSC requests that the `id_server` and -`id_access_token` parameters be removed from the Client-Server API's [POST +The achieve the above flows, some changes need to be made to existing +endpoints. This MSC requests that the `id_server` and `id_access_token` +parameters be removed from the Client-Server API's [POST /_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) -endpoint, as this endpoint is now only intended for the homeserver to send -emails from. Additionally, the same parameters will be removed from the [POST -/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid)endpoint's +and [POST +/_matrix/client/r0/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +endpoints, as these endpoints are now only intended for the homeserver to +send validation requests from. Additionally, the same parameters will be +removed from the [POST +/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint's `three_pid_creds` parameter as an identity server is no longer required to perform verification. @@ -173,18 +178,19 @@ TODO ## Security considerations -Reducing the homeserver's trust in identity servers should be a boost to security and improve decentralisation in the Matrix ecosystem to boot. +Reducing the homeserver's trust in identity servers should be a boost to +security and improve decentralisation in the Matrix ecosystem to boot. Caution should be taken for homeserver developers to be sure not to continue to use user-provided identity servers for any sensitive tasks once it removes -the concept of a trusted identity server. +the concept of a trusted identity server list. ## Conclusion -This MSC helps reduce the homeserver's trust in an identity server even +This MSC helps to minimize the homeserver's trust in an identity server even further to the point where it is only used for binding addresses for lookup - -which was the original intention of the Identity Service API. +which was the original intention of identity servers to begin with. Additionally, by clearly separating the threepid bind endpoint into two -endpoints that each have a clear intention, the concept of threepid binding -becomes a lot easier to reason about. +endpoints that each have a clear intention, the concept of attaching +threepids to a Matrix user becomes a lot easier to reason about. diff --git a/temp b/temp deleted file mode 100644 index e69de29bb2d..00000000000 From 5193c319e7b0250d5a6a74e66d04a9f4cfaa76f1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 13 Sep 2019 11:49:31 +0100 Subject: [PATCH 04/28] Cleaner API endpoints --- proposals/2290-separate-threepid-bind-hs.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 95e90192f79..69ed4827e0a 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -2,7 +2,7 @@ On the Client Server API there is currently a single endpoint for binding a threepid (an email or a phone number): [POST -/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver and an identity server. @@ -13,7 +13,7 @@ also be bound to a user's account on the homeserver. This allows the threepid to be used for message notifications, login, password reset, and other important functions. -Typically, when using the `POST /_matrix/client/r0/account/3pid` endpoint, +Typically, when using the `/account/3pid` endpoint, the identity server handles the verification -- either by sending an email to an email address, or a SMS message to a phone number. Once completed, the homeserver will check with the identity server that verification had indeed @@ -68,9 +68,10 @@ the MSC is no longer relevant. ## Proposal A new endpoint will be added to the Client Server API: `POST -/_matrix/client/r0/account/3pid/identity/bind`, and will require -authentication. The endpoint definition is the same as `POST -/_matrix/client/r0/account/3pid`, minus the `bind` flag. +/account/3pid/identity/bind`, and will require authentication. The endpoint +definition is the same as [POST +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), +minus the `bind` flag. An example of binding a threepid to **an identity server only** with this new endpoint is as follows: @@ -150,13 +151,13 @@ The threepid will then be bound to the user's account. The achieve the above flows, some changes need to be made to existing endpoints. This MSC requests that the `id_server` and `id_access_token` parameters be removed from the Client-Server API's [POST -/_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST -/_matrix/client/r0/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) endpoints, as these endpoints are now only intended for the homeserver to send validation requests from. Additionally, the same parameters will be removed from the [POST -/_matrix/client/r0/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint's +/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint's `three_pid_creds` parameter as an identity server is no longer required to perform verification. From cb7c072edb042ce02046ad4fdaa1af112e85f066 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 14:42:21 +0100 Subject: [PATCH 05/28] Two new endpoints instead of one --- proposals/2229-rebind-existing-3pid.md | 2 + proposals/2290-separate-threepid-bind-hs.md | 92 ++++++++++++--------- 2 files changed, 55 insertions(+), 39 deletions(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 83883c7850a..4c709326ca0 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -1,5 +1,7 @@ # Allowing 3PID Owners to Rebind +## Note: This MSC has been made obselete by MSC2290. + ``` 3PID noun diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 69ed4827e0a..0d2b9f2d0a3 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -2,7 +2,7 @@ On the Client Server API there is currently a single endpoint for binding a threepid (an email or a phone number): [POST -/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). +/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid). Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver and an identity server. @@ -26,26 +26,23 @@ to supply a malicious identity server that would immediately answer "yes" to any threepid validation, then the user could add any threepid to their account on the homeserver (which is likely not something homeserver admins want). -To solve this problem, we propose adding a second endpoint that is only used -for binding to an identity server of the user's choice. This endpoint will -not bind the threepid to the user's account on the homeserver, only the -identity server. +To be clear, this is not a long-standing security issue. It is not a problem +in any released version of Synapse, as Synapse keeps a list of "trusted +identity servers" that acts a whitelist for what identity servers a user can +specify. -In addition, the existing binding endpoint will lose the ability to bind -threepids to an identity server, by removing its `bind` flag. Instead, it -will solely be used to bind to the user's account on the homeserver. +The requirement for homeservers to keep this whitelist is soon to be lost +however, as part of lessening the reliance of homeservers on identity +servers. This cannot be done while the homeserver is still trusting an +identity server for validation of threepids. If the endpoints are split, the +homeserver will handle the validation of threepids being added to user +accounts, and identity servers will validate threepids being added to their +own database. -To be clear, the above issue is not a long-standing security issue. Indeed it -is not a problem in any released version of Synapse, as Synapse keeps a list -of "trusted identity servers" that acts a whitelist for what identity servers -a user can specify. - -Synapse is soon to lose this whitelist however, as part of lessening the -reliance of homeservers on identity servers. This cannot be done while the -homeserver is still trusting an identity server for validation of threepids. -If the endpoints are split, the homeserver will handle the validation of -threepids being added to user accounts, and identity servers will validate -threepids being added to their own database. +To solve this problem, we propose adding two new endpoints. One that is only +used for binding to user's account, and another that is only for binding to +an identity server of the user's choice. The existing binding endpoint will +be deprecated. One may question why clients don't just contact an identity server directly to bind a threepid, bypassing the implications of binding through a @@ -62,18 +59,21 @@ about hundreds of fake binds to a user's account). This MSC obseletes [MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt -with changing the rules of the `bind` flag. Since this flag is being removed, -the MSC is no longer relevant. +with changing the rules of the `bind` flag on the original endpoint. Since +that endpoint is being deprecated, the MSC is no longer relevant. ## Proposal -A new endpoint will be added to the Client Server API: `POST -/account/3pid/identity/bind`, and will require authentication. The endpoint -definition is the same as [POST -/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), -minus the `bind` flag. +Two new endpoints will be added to the Client Server API: `POST +/account/3pid/bind` and `POST /account/3pid/add`. Both will require +authentication. The request parameters of `POST /account/3pid/bind` are the +same as [POST +/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid), +minus the `bind` flag. The request parameters of `POST /account/3pid/add` +will simply consist of a JSON body containing `client_secret` and `sid`. -An example of binding a threepid to **an identity server only** with this new endpoint is as follows: +An example of binding a threepid to **an identity server only** with this new +endpoint is as follows: First the client must request the threepid be validated by its chosen identity server. @@ -93,7 +93,7 @@ notifies the identity server that the email has been verified. Next, the client completes the bind by calling the new endpoint on the homeserver: ``` -POST https://home.server/_matrix/client/r0/account/3pid/identity/bind +POST https://home.server/_matrix/client/r0/account/3pid/bind { "three_pid_creds": { @@ -109,8 +109,8 @@ The homeserver will then make a bind request to the specified identity server on behalf of the user. The homeserver will record if the bind was successful and notify the user. -The threepid has now been binded on the user's identity server without -causing that threepid to be used for password resets or any other +The threepid has now been binded on the user's requested identity server +without causing that threepid to be used for password resets or any other homeserver-related functions. For completeness, here is an example of binding a threepid to the @@ -136,7 +136,7 @@ The client then sends a request to the old endpoint on the homeserver to bind the threepid to user's account. ``` -POST /_matrix/client/r0/account/3pid +POST /_matrix/client/r0/account/3pid/bind { "three_pid_creds": { @@ -151,15 +151,20 @@ The threepid will then be bound to the user's account. The achieve the above flows, some changes need to be made to existing endpoints. This MSC requests that the `id_server` and `id_access_token` parameters be removed from the Client-Server API's [POST -/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST -/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-msisdn-requesttoken) endpoints, as these endpoints are now only intended for the homeserver to -send validation requests from. Additionally, the same parameters will be -removed from the [POST -/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint's -`three_pid_creds` parameter as an identity server is no longer required to -perform verification. +send validation requests from. + +Additionally, the [POST +/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) +endpoint is deprecated as the two new endpoints replace its functionality. +The `bind` endpoint will also be removed, with the endpoint functioning as if +`bind` was `false`. Allowing an endpoint to add a threepid to both the +identity server and homeserver at the same time requires one to trust the +other, which is the exact behaviour we're trying to eliminate. Doing this +also helps backward compatibility, as explained below. This MSC also requests that the text "It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those that it @@ -175,7 +180,16 @@ again to finalize the validation afterwards. ## Backwards compatibility -TODO +Old matrix clients will continue to use the `/account/3pid` endpoint. As this +MSC removes the `bind` parameter and forces `/account/3pid` calls to act as +if `bind` was set to `false`, old clients will still be able to add 3pids, +but they will only be added to the homeserver, not the identity server. New +homeservers will ignore any `id_server` information passed to this endpoint. + +New matrix clients running with old homeservers should try their desired +endpoint (either `/account/3pid/add` or `/account/3pid/bind`) and on +receiving a HTTP `404` error code, should either attempt to use +`/account/3pid` with the `bind` parameter or give up, at their discretion. ## Security considerations From 5b259bfb52e38ecf849ab1ce064efc449a37281f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 14:47:38 +0100 Subject: [PATCH 06/28] Fix homeserver binding example --- proposals/2290-separate-threepid-bind-hs.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 0d2b9f2d0a3..17a044207ee 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -31,13 +31,12 @@ in any released version of Synapse, as Synapse keeps a list of "trusted identity servers" that acts a whitelist for what identity servers a user can specify. -The requirement for homeservers to keep this whitelist is soon to be lost -however, as part of lessening the reliance of homeservers on identity -servers. This cannot be done while the homeserver is still trusting an -identity server for validation of threepids. If the endpoints are split, the -homeserver will handle the validation of threepids being added to user -accounts, and identity servers will validate threepids being added to their -own database. +Synapse is soon to lose this whitelist however, as part of lessening the +reliance of homeservers on identity servers. This cannot be done while the +homeserver is still trusting an identity server for validation of threepids. +If the endpoints are split, the homeserver will handle the validation of +threepids being added to user accounts, and identity servers will validate +threepids being added to their own database. To solve this problem, we propose adding two new endpoints. One that is only used for binding to user's account, and another that is only for binding to @@ -139,10 +138,8 @@ the threepid to user's account. POST /_matrix/client/r0/account/3pid/bind { - "three_pid_creds": { - "sid": "abc123987", - "client_secret": "don'tT3ll" - } + "sid": "abc123987", + "client_secret": "don'tT3ll" } ``` From 1fc1e3c6cecf7c49753316958696ac5065f45fec Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 14:49:30 +0100 Subject: [PATCH 07/28] run on sentence --- proposals/2290-separate-threepid-bind-hs.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 17a044207ee..5bd5129bb1b 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -135,7 +135,7 @@ The client then sends a request to the old endpoint on the homeserver to bind the threepid to user's account. ``` -POST /_matrix/client/r0/account/3pid/bind +POST https://home.server/_matrix/client/r0/account/3pid/add { "sid": "abc123987", @@ -177,11 +177,11 @@ again to finalize the validation afterwards. ## Backwards compatibility -Old matrix clients will continue to use the `/account/3pid` endpoint. As this +Old matrix clients will continue to use the `/account/3pid` endpoint. This MSC removes the `bind` parameter and forces `/account/3pid` calls to act as -if `bind` was set to `false`, old clients will still be able to add 3pids, -but they will only be added to the homeserver, not the identity server. New -homeservers will ignore any `id_server` information passed to this endpoint. +if `bind` was set to `false`. Old clients will still be able to add 3pids to +the homeserver, but not the identity server. New homeservers must ignore any +`id_server` information passed to this endpoint. New matrix clients running with old homeservers should try their desired endpoint (either `/account/3pid/add` or `/account/3pid/bind`) and on From 196f27efb2ebff9f64e3ebef5c3aa387edc49dfb Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 16 Sep 2019 15:22:05 +0100 Subject: [PATCH 08/28] Update proposals/2290-separate-threepid-bind-hs.md Co-Authored-By: Matthew Hodgson --- proposals/2290-separate-threepid-bind-hs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 5bd5129bb1b..d692207d212 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -145,7 +145,7 @@ POST https://home.server/_matrix/client/r0/account/3pid/add The threepid will then be bound to the user's account. -The achieve the above flows, some changes need to be made to existing +To achieve the above flows, some changes need to be made to existing endpoints. This MSC requests that the `id_server` and `id_access_token` parameters be removed from the Client-Server API's [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-email-requesttoken) From 7b656e9013adeefb4fd70d84b41aed93edc85d1b Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 16 Sep 2019 15:24:43 +0100 Subject: [PATCH 09/28] Update proposals/2290-separate-threepid-bind-hs.md Co-Authored-By: Matthew Hodgson --- proposals/2290-separate-threepid-bind-hs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index d692207d212..6e34f954b40 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -108,7 +108,7 @@ The homeserver will then make a bind request to the specified identity server on behalf of the user. The homeserver will record if the bind was successful and notify the user. -The threepid has now been binded on the user's requested identity server +The threepid has now been bound on the user's requested identity server without causing that threepid to be used for password resets or any other homeserver-related functions. From f36ed9a27195233c12edb6271207f09935735e01 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 15:26:07 +0100 Subject: [PATCH 10/28] typos --- proposals/2290-separate-threepid-bind-hs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 6e34f954b40..6187efdded1 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -131,8 +131,8 @@ POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken Once an email has been sent, the user clicks the link in the email, which notifies the homeserver that the threepid has been verified. -The client then sends a request to the old endpoint on the homeserver to bind -the threepid to user's account. +The client then sends a request to the endpoint on the homeserver to bind +the threepid to a user's account. ``` POST https://home.server/_matrix/client/r0/account/3pid/add From f06ba491fefc9168a869d6ae09734afdded160ad Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 15:49:31 +0100 Subject: [PATCH 11/28] Assign meaning to bind and add --- proposals/2290-separate-threepid-bind-hs.md | 61 +++++++++++---------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 6187efdded1..de844e470d2 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -7,18 +7,20 @@ Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver and an identity server. -For context a threepid can be bound to an identity server to allow other users to find -their Matrix ID using their email address or phone number. A threepid can -also be bound to a user's account on the homeserver. This allows the -threepid to be used for message notifications, login, password reset, and -other important functions. - -Typically, when using the `/account/3pid` endpoint, -the identity server handles the verification -- either by sending an email to -an email address, or a SMS message to a phone number. Once completed, the -homeserver will check with the identity server that verification had indeed -happened, and if so, the threepid would be bound (again, either to the -homeserver, or the homeserver and identity server simultaneously). +For context a threepid can be bound to an identity server to allow other +users to find their Matrix ID using their email address or phone number. A +threepid can also be added to a user's account on the homeserver. This allows +the threepid to be used for message notifications, login, password reset, and +other important functions. We use the term `add` when talking about adding a +threepid to a homeserver, and `bind` when binding a threepid to an identity +server. This terminology will be used throughout the rest of this proposal. + +Typically, when using the `/account/3pid` endpoint, the identity server +handles the verification -- either by sending an email to an email address, +or a SMS message to a phone number. Once completed, the homeserver will check +with the identity server that verification had indeed happened, and if so, +the threepid would be either added to the homeserver, or added to the +homeserver and bound to the identity server simultaneously. Now, consider the fact that the identity server used in this process is provided by the user, using the endpoint's `id_server` parameter. If the user were @@ -36,12 +38,13 @@ reliance of homeservers on identity servers. This cannot be done while the homeserver is still trusting an identity server for validation of threepids. If the endpoints are split, the homeserver will handle the validation of threepids being added to user accounts, and identity servers will validate -threepids being added to their own database. +threepids being bound to themselves. -To solve this problem, we propose adding two new endpoints. One that is only -used for binding to user's account, and another that is only for binding to -an identity server of the user's choice. The existing binding endpoint will -be deprecated. +To solve this problem, we propose adding two new endpoints. `POST +/account/3pid/add` that is only used for adding to user's account on a +homeserver, and `POST /account/3pid/bind` that is only for binding to an +identity server of the user's choice. The existing binding endpoint (`POST +/account/3pid`) will be deprecated. One may question why clients don't just contact an identity server directly to bind a threepid, bypassing the implications of binding through a @@ -50,11 +53,11 @@ homeserver such that the homeserver can keep track of which binds were made, which is important when a user wishes to deactivate their account (and remove all of their bindings made on different identity servers). -A bind could be made on an identity server, which could then tell the -homeserver that a validation occured, but then there are security +A verification could occur on an identity server, which could then tell the +homeserver that a validation happened, but then there are security considerations about how to authenticate an identity server in that instance (and prevent people pretending to be identity servers and telling homeservers -about hundreds of fake binds to a user's account). +about hundreds of fake threepid additions to a user's account). This MSC obseletes [MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt @@ -71,8 +74,8 @@ same as [POST minus the `bind` flag. The request parameters of `POST /account/3pid/add` will simply consist of a JSON body containing `client_secret` and `sid`. -An example of binding a threepid to **an identity server only** with this new -endpoint is as follows: +An example of binding a threepid to an identity server with this new endpoint +is as follows: First the client must request the threepid be validated by its chosen identity server. @@ -112,8 +115,8 @@ The threepid has now been bound on the user's requested identity server without causing that threepid to be used for password resets or any other homeserver-related functions. -For completeness, here is an example of binding a threepid to the -homeserver only, using the old endpoint: +For completeness, here is an example of adding a threepid to the homeserver +only, using the `/account/3pid/add` endpoint: The homeserver is validating the threepid in this instance, so the client must use the `/requestToken` endpoint of the homeserver: @@ -131,7 +134,7 @@ POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken Once an email has been sent, the user clicks the link in the email, which notifies the homeserver that the threepid has been verified. -The client then sends a request to the endpoint on the homeserver to bind +The client then sends a request to the endpoint on the homeserver to add the threepid to a user's account. ``` @@ -143,7 +146,7 @@ POST https://home.server/_matrix/client/r0/account/3pid/add } ``` -The threepid will then be bound to the user's account. +The threepid has now been added to the user's account. To achieve the above flows, some changes need to be made to existing endpoints. This MSC requests that the `id_server` and `id_access_token` @@ -180,8 +183,8 @@ again to finalize the validation afterwards. Old matrix clients will continue to use the `/account/3pid` endpoint. This MSC removes the `bind` parameter and forces `/account/3pid` calls to act as if `bind` was set to `false`. Old clients will still be able to add 3pids to -the homeserver, but not the identity server. New homeservers must ignore any -`id_server` information passed to this endpoint. +the homeserver, but not bind to the identity server. New homeservers must +ignore any `id_server` information passed to this endpoint. New matrix clients running with old homeservers should try their desired endpoint (either `/account/3pid/add` or `/account/3pid/bind`) and on @@ -203,6 +206,6 @@ This MSC helps to minimize the homeserver's trust in an identity server even further to the point where it is only used for binding addresses for lookup - which was the original intention of identity servers to begin with. -Additionally, by clearly separating the threepid bind endpoint into two +Additionally, by clearly separating the original threepid endpoint into two endpoints that each have a clear intention, the concept of attaching threepids to a Matrix user becomes a lot easier to reason about. From 4bc005ac84fa632d6ab933378445142206b6aa65 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 16:27:16 +0100 Subject: [PATCH 12/28] Remove threepid explanation --- proposals/2290-separate-threepid-bind-hs.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index de844e470d2..0da607978f6 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -5,15 +5,10 @@ threepid (an email or a phone number): [POST /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid). Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver -and an identity server. - -For context a threepid can be bound to an identity server to allow other -users to find their Matrix ID using their email address or phone number. A -threepid can also be added to a user's account on the homeserver. This allows -the threepid to be used for message notifications, login, password reset, and -other important functions. We use the term `add` when talking about adding a -threepid to a homeserver, and `bind` when binding a threepid to an identity -server. This terminology will be used throughout the rest of this proposal. +and an identity server. Note that we use the term `add` when talking about +adding a threepid to a homeserver, and `bind` when binding a threepid to an +identity server. This terminology will be used throughout the rest of this +proposal. Typically, when using the `/account/3pid` endpoint, the identity server handles the verification -- either by sending an email to an email address, From af2467606e6a67d418414794df4ecc7a9f9f80b2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 16 Sep 2019 18:01:21 +0100 Subject: [PATCH 13/28] parameter, not endpoint --- proposals/2290-separate-threepid-bind-hs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 0da607978f6..a28f6d9357a 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -155,7 +155,7 @@ send validation requests from. Additionally, the [POST /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint is deprecated as the two new endpoints replace its functionality. -The `bind` endpoint will also be removed, with the endpoint functioning as if +The `bind` parameter will also be removed, with the endpoint functioning as if `bind` was `false`. Allowing an endpoint to add a threepid to both the identity server and homeserver at the same time requires one to trust the other, which is the exact behaviour we're trying to eliminate. Doing this From 2a5531075460547b02c6d5c9916f21d8a6d5137a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 11:43:56 +0100 Subject: [PATCH 14/28] Clarify why MSC2229 was made obselete --- proposals/2229-rebind-existing-3pid.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 4c709326ca0..1bfb5106c13 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -2,6 +2,15 @@ ## Note: This MSC has been made obselete by MSC2290. +MSC2290 provides two separate API endpoints, one for adding a 3PID to the +homeserver, and another for binding to an identity server. These new +endpoints will allow the homeserver to enforce rules on emails that already +exist on the homeserver, only when modifying homeserver email, while only +needing to forward requests when binding to an identity server. This removes +the problem MSC2229 is trying to solve, and it is thus made obselete. + +--- + ``` 3PID noun From c57250b3935c675e3cb0d17c973be50bc32cbd5d Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 17 Sep 2019 11:48:50 +0100 Subject: [PATCH 15/28] Apply suggestions from code review Co-Authored-By: Travis Ralston --- proposals/2290-separate-threepid-bind-hs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index a28f6d9357a..8999d14351f 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -35,7 +35,7 @@ If the endpoints are split, the homeserver will handle the validation of threepids being added to user accounts, and identity servers will validate threepids being bound to themselves. -To solve this problem, we propose adding two new endpoints. `POST +To solve this problem, it is proposed to add two new endpoints. `POST /account/3pid/add` that is only used for adding to user's account on a homeserver, and `POST /account/3pid/bind` that is only for binding to an identity server of the user's choice. The existing binding endpoint (`POST @@ -155,7 +155,7 @@ send validation requests from. Additionally, the [POST /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint is deprecated as the two new endpoints replace its functionality. -The `bind` parameter will also be removed, with the endpoint functioning as if +The `bind` parameter is to be removed, with the endpoint functioning as if `bind` was `false`. Allowing an endpoint to add a threepid to both the identity server and homeserver at the same time requires one to trust the other, which is the exact behaviour we're trying to eliminate. Doing this From 0b67f34578c29e016195dca487a1d949b8561545 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 12:10:32 +0100 Subject: [PATCH 16/28] Address review comments --- proposals/2290-separate-threepid-bind-hs.md | 117 +++++++++----------- 1 file changed, 53 insertions(+), 64 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index a28f6d9357a..644be55b46b 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -1,8 +1,15 @@ # Separate Endpoints for Binding Threepids +*Note: This MSC obseletes +[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt +with changing the rules of the `bind` flag on [POST +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). +That endpoint is being deprecated as part of this MSC, thus MSC2229 is no +longer relevant.* + On the Client Server API there is currently a single endpoint for binding a threepid (an email or a phone number): [POST -/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid). +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). Depending on whether the `bind` flag is `true` or `false`, the threepid will be bound to either a user's account on the homeserver, or both the homeserver and an identity server. Note that we use the term `add` when talking about @@ -28,46 +35,30 @@ in any released version of Synapse, as Synapse keeps a list of "trusted identity servers" that acts a whitelist for what identity servers a user can specify. -Synapse is soon to lose this whitelist however, as part of lessening the -reliance of homeservers on identity servers. This cannot be done while the -homeserver is still trusting an identity server for validation of threepids. -If the endpoints are split, the homeserver will handle the validation of -threepids being added to user accounts, and identity servers will validate -threepids being bound to themselves. - -To solve this problem, we propose adding two new endpoints. `POST -/account/3pid/add` that is only used for adding to user's account on a -homeserver, and `POST /account/3pid/bind` that is only for binding to an -identity server of the user's choice. The existing binding endpoint (`POST -/account/3pid`) will be deprecated. - -One may question why clients don't just contact an identity server directly -to bind a threepid, bypassing the implications of binding through a -homeserver. While this will work, binds should still occur through a -homeserver such that the homeserver can keep track of which binds were made, -which is important when a user wishes to deactivate their account (and remove -all of their bindings made on different identity servers). - -A verification could occur on an identity server, which could then tell the -homeserver that a validation happened, but then there are security -considerations about how to authenticate an identity server in that instance -(and prevent people pretending to be identity servers and telling homeservers -about hundreds of fake threepid additions to a user's account). - -This MSC obseletes -[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt -with changing the rules of the `bind` flag on the original endpoint. Since -that endpoint is being deprecated, the MSC is no longer relevant. +The concept of this whitelist is being removed in this MSC however, as part +of lessening the reliance of homeservers on identity servers. This cannot be +done while the homeserver is still trusting an identity server for validation +of threepids. If the endpoints are split, the homeserver will handle the +validation of threepids being added to user accounts, and identity servers +will validate threepids being bound to themselves. ## Proposal -Two new endpoints will be added to the Client Server API: `POST -/account/3pid/bind` and `POST /account/3pid/add`. Both will require -authentication. The request parameters of `POST /account/3pid/bind` are the -same as [POST +To solve this problem, two new endpoints will be added to the Client Server +API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Both will +require authentication and be rate-limited. The request parameters of `POST +/account/3pid/bind` are the same as [POST /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid), -minus the `bind` flag. The request parameters of `POST /account/3pid/add` -will simply consist of a JSON body containing `client_secret` and `sid`. +minus the `bind` flag, and the contents of `three_pid_creds` have been +brought to the top level of the request body. The request parameters of `POST +/account/3pid/add` will simply consist of a JSON body containing +`client_secret` and `sid`. + +The homeserver should prevent a threepid being added to a user's account if +it already part of another user's account. However, the homeserver should not +check for existing threepids when binding to an identity server. Identity +servers do not enforce this requirement and neither should the proxying +homeserver. An example of binding a threepid to an identity server with this new endpoint is as follows: @@ -93,12 +84,10 @@ Next, the client completes the bind by calling the new endpoint on the homeserve POST https://home.server/_matrix/client/r0/account/3pid/bind { - "three_pid_creds": { - "id_server": "example.org", - "id_access_token": "abc123_OpaqueString", - "sid": "abc123987", - "client_secret": "don'tT3ll" - } + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "don'tT3ll" } ``` @@ -161,17 +150,25 @@ identity server and homeserver at the same time requires one to trust the other, which is the exact behaviour we're trying to eliminate. Doing this also helps backward compatibility, as explained below. -This MSC also requests that the text "It is imperative that the homeserver -keep a list of trusted Identity Servers and only proxies to those that it -trusts." be removed from all parts of the spec, as the homeserver should no -longer need to trust any identity servers. +The text "It is imperative that the homeserver keep a list of trusted +Identity Servers and only proxies to those that it trusts." is to be removed +from all parts of the spec, as the homeserver should no longer need to trust +any identity servers. ## Tradeoffs -It may be possible to reduce the two calls per flow into a single endpoint, -but the current asynchronous approach makes it easy for a client to send a -request, go offline, have the threepid be validated, and then come online -again to finalize the validation afterwards. +One may question why clients don't just contact an identity server directly +to bind a threepid, bypassing the implications of binding through a +homeserver. While this will work, binds should still occur through a +homeserver such that the homeserver can keep track of which binds were made, +which is important when a user wishes to deactivate their account (and remove +all of their bindings made on different identity servers). + +A verification could occur on an identity server, which could then tell the +homeserver that a validation happened, but then there are security +considerations about how to authenticate an identity server in that instance +(and prevent people pretending to be identity servers and telling homeservers +about hundreds of fake threepid additions to a user's account). ## Backwards compatibility @@ -191,16 +188,8 @@ receiving a HTTP `404` error code, should either attempt to use Reducing the homeserver's trust in identity servers should be a boost to security and improve decentralisation in the Matrix ecosystem to boot. -Caution should be taken for homeserver developers to be sure not to continue -to use user-provided identity servers for any sensitive tasks once it removes -the concept of a trusted identity server list. - -## Conclusion - -This MSC helps to minimize the homeserver's trust in an identity server even -further to the point where it is only used for binding addresses for lookup - -which was the original intention of identity servers to begin with. - -Additionally, by clearly separating the original threepid endpoint into two -endpoints that each have a clear intention, the concept of attaching -threepids to a Matrix user becomes a lot easier to reason about. +Some endpoints of the Client Server API allow a user to provide an +`id_server` parameter. Caution should be taken for homeserver developers to +stop using these user-provided identity servers for any sensitive tasks, such +as password reset or account registration, if it removes the concept of a +trusted identity server list. From 1e69a7f3f21e70877248d5168cdca5627b9ea69d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 15:02:41 +0100 Subject: [PATCH 17/28] be assertive --- proposals/2290-separate-threepid-bind-hs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 75fce27a1b2..df60bd831d9 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -133,8 +133,8 @@ POST https://home.server/_matrix/client/r0/account/3pid/add The threepid has now been added to the user's account. To achieve the above flows, some changes need to be made to existing -endpoints. This MSC requests that the `id_server` and `id_access_token` -parameters be removed from the Client-Server API's [POST +endpoints. The `id_server` and `id_access_token` parameters are to be removed +from the Client-Server API's [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-msisdn-requesttoken) From 169174e00be3be405a79a2a7b62347c5ff0f0e13 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 17:01:18 +0100 Subject: [PATCH 18/28] Suggest the use of a unstable flag --- proposals/2290-separate-threepid-bind-hs.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index df60bd831d9..26cbbeb76db 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -172,17 +172,19 @@ about hundreds of fake threepid additions to a user's account). ## Backwards compatibility +A new flag will be added to `/versions`' unstable_features section, +`m.separate_add_and_bind`. If this flag is present and set to `true`, then +clients should use the new API endpoints to carry out threepid adds and +binds. If this flag is not present or set to `false`, clients should use +`/account/3pid`, being aware that they can only bind threepids to the +homeserver, not the identity server. + Old matrix clients will continue to use the `/account/3pid` endpoint. This MSC removes the `bind` parameter and forces `/account/3pid` calls to act as if `bind` was set to `false`. Old clients will still be able to add 3pids to the homeserver, but not bind to the identity server. New homeservers must ignore any `id_server` information passed to this endpoint. -New matrix clients running with old homeservers should try their desired -endpoint (either `/account/3pid/add` or `/account/3pid/bind`) and on -receiving a HTTP `404` error code, should either attempt to use -`/account/3pid` with the `bind` parameter or give up, at their discretion. - ## Security considerations Reducing the homeserver's trust in identity servers should be a boost to From 53519f98d0986371e99812f4e7acba89a552036c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 17:01:45 +0100 Subject: [PATCH 19/28] Pin a spec version when we link to it --- proposals/2290-separate-threepid-bind-hs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 26cbbeb76db..3a15a52cb4e 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -48,7 +48,7 @@ To solve this problem, two new endpoints will be added to the Client Server API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Both will require authentication and be rate-limited. The request parameters of `POST /account/3pid/bind` are the same as [POST -/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid), +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), minus the `bind` flag, and the contents of `three_pid_creds` have been brought to the top level of the request body. The request parameters of `POST /account/3pid/add` will simply consist of a JSON body containing @@ -135,14 +135,14 @@ The threepid has now been added to the user's account. To achieve the above flows, some changes need to be made to existing endpoints. The `id_server` and `id_access_token` parameters are to be removed from the Client-Server API's [POST -/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-email-requesttoken) +/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST -/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) endpoints, as these endpoints are now only intended for the homeserver to send validation requests from. Additionally, the [POST -/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid) endpoint is deprecated as the two new endpoints replace its functionality. The `bind` parameter is to be removed, with the endpoint functioning as if `bind` was `false`. Allowing an endpoint to add a threepid to both the From e50bb3df25bedc3eb776888c2eb2ce393482e045 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 17:04:40 +0100 Subject: [PATCH 20/28] Mention that homeserver's should remember binds done through them --- proposals/2290-separate-threepid-bind-hs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 3a15a52cb4e..85803bafb5a 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -93,7 +93,9 @@ POST https://home.server/_matrix/client/r0/account/3pid/bind The homeserver will then make a bind request to the specified identity server on behalf of the user. The homeserver will record if the bind was successful -and notify the user. +and notify the user. The homeserver will remember this bind and the identity +server it occurred on so that it can perform an unbind later if the user +requests it or their account is deactivated. The threepid has now been bound on the user's requested identity server without causing that threepid to be used for password resets or any other From 87d641c7c12c2cdd50a7e197cc438a5da409e05b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 17 Sep 2019 17:20:57 +0100 Subject: [PATCH 21/28] Describe what the IS and HS are doing in the examples --- proposals/2290-separate-threepid-bind-hs.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 85803bafb5a..0e6004ab51a 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -75,6 +75,10 @@ POST https://identity.server/_matrix/identity/v2/validate/email/requestToken } ``` +The identity server must send an email to the specified address, including a +link to a URL on the identity server which will accept the validation session +ID, the given client_secret, and a randomly-generated token. + Once an email has been sent, the user clicks the link in the email, which notifies the identity server that the email has been verified. @@ -117,6 +121,10 @@ POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken } ``` +Here the homeserver must send an email to the specified address, including a +link to a URL on the homeserver which will accept the validation session ID, +the given client_secret, and a randomly-generated token. + Once an email has been sent, the user clicks the link in the email, which notifies the homeserver that the threepid has been verified. @@ -132,7 +140,9 @@ POST https://home.server/_matrix/client/r0/account/3pid/add } ``` -The threepid has now been added to the user's account. +The homeserver checks the threepid validation session referred to by the +given ID and client_secret was validated, and if so adds the threepid to the +user's account. To achieve the above flows, some changes need to be made to existing endpoints. The `id_server` and `id_access_token` parameters are to be removed From bd64ffc442127774a9f34631a3960be43dd975d8 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 18 Sep 2019 11:57:26 +0100 Subject: [PATCH 22/28] Homeservers shouldn't proxy to user-provided identity servers anymore --- proposals/2290-separate-threepid-bind-hs.md | 42 ++++++++++++--------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 0e6004ab51a..34712d23421 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -145,27 +145,33 @@ given ID and client_secret was validated, and if so adds the threepid to the user's account. To achieve the above flows, some changes need to be made to existing -endpoints. The `id_server` and `id_access_token` parameters are to be removed -from the Client-Server API's [POST -/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) -and [POST -/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) -endpoints, as these endpoints are now only intended for the homeserver to -send validation requests from. - -Additionally, the [POST +endpoints. The [POST /account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid) endpoint is deprecated as the two new endpoints replace its functionality. The `bind` parameter is to be removed, with the endpoint functioning as if `bind` was `false`. Allowing an endpoint to add a threepid to both the identity server and homeserver at the same time requires one to trust the other, which is the exact behaviour we're trying to eliminate. Doing this -also helps backward compatibility, as explained below. - -The text "It is imperative that the homeserver keep a list of trusted -Identity Servers and only proxies to those that it trusts." is to be removed -from all parts of the spec, as the homeserver should no longer need to trust -any identity servers. +also helps backward compatibility, as explained in [Backwards +compatibility](#backwards-compatibility). + +The `id_server` and `id_access_token` parameters are to be removed +from all of the Client-Server API's `requestToken` endpoints. That is: + +* [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +* [POST /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +* [POST /register/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-email-requesttoken) +* [POST /register/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-msisdn-requesttoken) +* [POST /account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-email-requesttoken) +* [POST /account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-msisdn-requesttoken) + +Either the homeserver itself or a service that the homeserver delegates to +should be handling the sending of validation messages, not a user-provided +server. Any mention of the homeserver being able to proxy to an identity +server in the above endpoint descriptions, as well as the text "It is +imperative that the homeserver keep a list of trusted Identity Servers and +only proxies to those that it trusts." is to be removed from all parts of the +spec, as the homeserver should no longer need to trust any identity servers. ## Tradeoffs @@ -204,6 +210,6 @@ security and improve decentralisation in the Matrix ecosystem to boot. Some endpoints of the Client Server API allow a user to provide an `id_server` parameter. Caution should be taken for homeserver developers to -stop using these user-provided identity servers for any sensitive tasks, such -as password reset or account registration, if it removes the concept of a -trusted identity server list. +stop using these user-provided identity servers for any sensitive tasks where +possible, such as password reset or account registration, if it removes the +concept of a trusted identity server list. From 40420d963387bfddf2f8efa6d8b0ad45584e74ec Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 19 Sep 2019 11:50:16 +0100 Subject: [PATCH 23/28] Update proposals/2290-separate-threepid-bind-hs.md Co-Authored-By: Kitsune Ral --- proposals/2290-separate-threepid-bind-hs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 34712d23421..b361d0e1011 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -55,7 +55,7 @@ brought to the top level of the request body. The request parameters of `POST `client_secret` and `sid`. The homeserver should prevent a threepid being added to a user's account if -it already part of another user's account. However, the homeserver should not +it's already part of another user's account. However, the homeserver should not check for existing threepids when binding to an identity server. Identity servers do not enforce this requirement and neither should the proxying homeserver. From 9311e899414401121501b87b0e95bb031542e620 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 25 Sep 2019 01:32:35 +0200 Subject: [PATCH 24/28] Update proposals/2229-rebind-existing-3pid.md Co-Authored-By: Hubert Chathi --- proposals/2229-rebind-existing-3pid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 1bfb5106c13..398e65139a4 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -1,6 +1,6 @@ # Allowing 3PID Owners to Rebind -## Note: This MSC has been made obselete by MSC2290. +## Note: This MSC has been made obsolete by MSC2290. MSC2290 provides two separate API endpoints, one for adding a 3PID to the homeserver, and another for binding to an identity server. These new From 219ebff6d39837d3982982483f1e114d8f77f832 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 26 Sep 2019 10:37:10 +0200 Subject: [PATCH 25/28] typo fix Co-Authored-By: Hubert Chathi --- proposals/2290-separate-threepid-bind-hs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index b361d0e1011..fad547c421e 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -1,6 +1,6 @@ # Separate Endpoints for Binding Threepids -*Note: This MSC obseletes +*Note: This MSC obsoletes [MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt with changing the rules of the `bind` flag on [POST /account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). From 1a51a2476849cc7f08d5d880a6564e74fa10f181 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 26 Sep 2019 17:16:44 +0100 Subject: [PATCH 26/28] UIAA on /account/3pid/add --- proposals/2290-separate-threepid-bind-hs.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index b361d0e1011..a1c7f09ed14 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -45,8 +45,15 @@ will validate threepids being bound to themselves. ## Proposal To solve this problem, two new endpoints will be added to the Client Server -API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Both will -require authentication and be rate-limited. The request parameters of `POST +API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Binding to an +identity server will require standard authentication, whereas adding a 3pid +to a user account will require [User-Interactive +Authentication](https://matrix.org/docs/spec/client_server/r0.5.0#user-interactive-authentication-api). +The latter is to prevent someone from adding a 3pid (which can be used to +reset passwords) to someone who's left their account open on a public +computer, without needing their password to do so. + +Both endpoints will be rate-limited. The request parameters of `POST /account/3pid/bind` are the same as [POST /account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), minus the `bind` flag, and the contents of `three_pid_creds` have been From ec7e795112ddc5a4d6fb498be996784e9c0ee8b4 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 26 Sep 2019 17:20:40 +0100 Subject: [PATCH 27/28] reflow --- proposals/2290-separate-threepid-bind-hs.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index 95f810e9df8..aa71fb3570f 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -70,7 +70,8 @@ homeserver. An example of binding a threepid to an identity server with this new endpoint is as follows: -First the client must request the threepid be validated by its chosen identity server. +First the client must request the threepid be validated by its chosen +identity server. ``` POST https://identity.server/_matrix/identity/v2/validate/email/requestToken @@ -89,7 +90,8 @@ ID, the given client_secret, and a randomly-generated token. Once an email has been sent, the user clicks the link in the email, which notifies the identity server that the email has been verified. -Next, the client completes the bind by calling the new endpoint on the homeserver: +Next, the client completes the bind by calling the new endpoint on the +homeserver: ``` POST https://home.server/_matrix/client/r0/account/3pid/bind From 46e7137252088f7fe6b12d2ccd713d3b07f4e33b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 26 Sep 2019 17:51:51 +0100 Subject: [PATCH 28/28] Don't remove id_server and id_access_token --- proposals/2290-separate-threepid-bind-hs.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md index aa71fb3570f..8c8996993bb 100644 --- a/proposals/2290-separate-threepid-bind-hs.md +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -164,8 +164,10 @@ other, which is the exact behaviour we're trying to eliminate. Doing this also helps backward compatibility, as explained in [Backwards compatibility](#backwards-compatibility). -The `id_server` and `id_access_token` parameters are to be removed -from all of the Client-Server API's `requestToken` endpoints. That is: +Either the homeserver itself or a service that the homeserver delegates to +should be handling the sending of validation messages, not a user-provided +server. Any mention of the homeserver being able to proxy to an identity +server in the below endpoint descriptions: * [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) * [POST /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) @@ -174,13 +176,10 @@ from all of the Client-Server API's `requestToken` endpoints. That is: * [POST /account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-email-requesttoken) * [POST /account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-msisdn-requesttoken) -Either the homeserver itself or a service that the homeserver delegates to -should be handling the sending of validation messages, not a user-provided -server. Any mention of the homeserver being able to proxy to an identity -server in the above endpoint descriptions, as well as the text "It is -imperative that the homeserver keep a list of trusted Identity Servers and -only proxies to those that it trusts." is to be removed from all parts of the -spec, as the homeserver should no longer need to trust any identity servers. +As well as the text "It is imperative that the homeserver keep a list of +trusted Identity Servers and only proxies to those that it trusts." is to be +removed from all parts of the spec, as the homeserver should no longer need +to trust any identity servers. ## Tradeoffs