From c960aebd115aa0ad354b41cabbe20d6ea3ec3027 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 16 Aug 2024 13:32:04 +0100 Subject: [PATCH 1/6] Add proposal for unsupported 3pid error code --- .../4178-threepid-medium-not-supported.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 proposals/4178-threepid-medium-not-supported.md diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md new file mode 100644 index 00000000000..6ba2be39ab1 --- /dev/null +++ b/proposals/4178-threepid-medium-not-supported.md @@ -0,0 +1,36 @@ +# MSC0000: Error code for Third Party Medium Not Supported + +Homeservers may not always support adding email addresses or phone numbers to a user's account, +however, there is no error code to signal this situation. Synapse currently returns `M_UNKNOWN` +which leads to bad, untranslatable error messages. + +## Proposal + +Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both +[`/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +and +[`/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), +defined to mean that the homeserver does not support adding a third party identifier of that medium. + +## Potential issues + +None forseen + +## Alternatives + +A better UX would be for servers to advertise what third party identifiers that support adding so that clients can +inform users before they try to do so. This should be in addition rather than as alternative though: the clearest +possible API will come from having both. + +## Security considerations + +None forseen + +## Unstable prefix + +This is sufficiently simple that proving it on a large scale is unnecessary. The code should not be used in the open +before the MSC has been accepted. + +## Dependencies + +None From 8fe16bfc08a1c85f60efff66e8c3515575f3f1a3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 16 Aug 2024 13:34:38 +0100 Subject: [PATCH 2/6] Update number --- proposals/4178-threepid-medium-not-supported.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md index 6ba2be39ab1..dca1e0e13b1 100644 --- a/proposals/4178-threepid-medium-not-supported.md +++ b/proposals/4178-threepid-medium-not-supported.md @@ -1,4 +1,4 @@ -# MSC0000: Error code for Third Party Medium Not Supported +# MSC4178: Error code for Third Party Medium Not Supported Homeservers may not always support adding email addresses or phone numbers to a user's account, however, there is no error code to signal this situation. Synapse currently returns `M_UNKNOWN` From 4e64f32c9a36b085daf56f67057ea7e9437a4040 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2024 15:17:36 +0100 Subject: [PATCH 3/6] Add another error code --- proposals/4178-threepid-medium-not-supported.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md index dca1e0e13b1..555d7f13ec8 100644 --- a/proposals/4178-threepid-medium-not-supported.md +++ b/proposals/4178-threepid-medium-not-supported.md @@ -1,17 +1,25 @@ -# MSC4178: Error code for Third Party Medium Not Supported +# MSC4178: Error codes for requestToken -Homeservers may not always support adding email addresses or phone numbers to a user's account, +There are a number of ways that sending a token to validate a third party identifier can go wrong. +The requestToken API, however, has a very limited number of error codes that it can return. + +Firstly, homeservers may not always support adding email addresses or phone numbers to a user's account, however, there is no error code to signal this situation. Synapse currently returns `M_UNKNOWN` which leads to bad, untranslatable error messages. +Secondly, the supplied third party identifier may be invalid. + ## Proposal -Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both +Firstly, Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both [`/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) and [`/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), defined to mean that the homeserver does not support adding a third party identifier of that medium. +Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party identifier parameter +was not a valid identifier for that medium (eg. not a valid phone number). + ## Potential issues None forseen From 3cc801e7d97275269b446d03107039c982b76d8e Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 19 Aug 2024 18:29:27 +0100 Subject: [PATCH 4/6] Uncontroversial wording changes --- proposals/4178-threepid-medium-not-supported.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md index 555d7f13ec8..e3133806b7b 100644 --- a/proposals/4178-threepid-medium-not-supported.md +++ b/proposals/4178-threepid-medium-not-supported.md @@ -12,9 +12,9 @@ Secondly, the supplied third party identifier may be invalid. ## Proposal Firstly, Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both -[`/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +[`POST /account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) and -[`/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), +[`POST /account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), defined to mean that the homeserver does not support adding a third party identifier of that medium. Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party identifier parameter @@ -22,17 +22,17 @@ was not a valid identifier for that medium (eg. not a valid phone number). ## Potential issues -None forseen +None foreseen. ## Alternatives -A better UX would be for servers to advertise what third party identifiers that support adding so that clients can +A better UX would be for servers to advertise what third party identifiers they support adding so that clients can inform users before they try to do so. This should be in addition rather than as alternative though: the clearest possible API will come from having both. ## Security considerations -None forseen +None foreseen. ## Unstable prefix From ed432ab8987b075c4906c6f72356d4fcfe7aa4bd Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2024 18:30:12 +0100 Subject: [PATCH 5/6] Clarity Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/4178-threepid-medium-not-supported.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md index e3133806b7b..37ecfa26f42 100644 --- a/proposals/4178-threepid-medium-not-supported.md +++ b/proposals/4178-threepid-medium-not-supported.md @@ -17,8 +17,8 @@ and [`POST /account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), defined to mean that the homeserver does not support adding a third party identifier of that medium. -Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party identifier parameter -was not a valid identifier for that medium (eg. not a valid phone number). +Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party address +was not valid for that medium (eg. not a valid phone number). ## Potential issues From f6c6fe66a831bacedc9e658f8e8130597c5a5e60 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2024 18:32:50 +0100 Subject: [PATCH 6/6] Specify HTTP status code --- proposals/4178-threepid-medium-not-supported.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/4178-threepid-medium-not-supported.md b/proposals/4178-threepid-medium-not-supported.md index 37ecfa26f42..6496b5dadb7 100644 --- a/proposals/4178-threepid-medium-not-supported.md +++ b/proposals/4178-threepid-medium-not-supported.md @@ -20,6 +20,8 @@ defined to mean that the homeserver does not support adding a third party identi Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party address was not valid for that medium (eg. not a valid phone number). +For both of these codes, HTTP status code 400 should be used. + ## Potential issues None foreseen.