From e2cc52f3d51cb22fe7b645621bc9a3fa6b1a32e9 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 28 Aug 2024 17:10:37 +0100 Subject: [PATCH 01/21] MSC4180: Additional Error Codes for submitToken endpoint --- proposals/4180-submitToken-error-codes.md | 52 +++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 proposals/4180-submitToken-error-codes.md diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4180-submitToken-error-codes.md new file mode 100644 index 00000000000..6a87c97ac68 --- /dev/null +++ b/proposals/4180-submitToken-error-codes.md @@ -0,0 +1,52 @@ +# MSC4180: Additional Error Codes for submitToken endpoint + +The [https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken](POST /_matrix/identity/v2/validate/email/submitToken) and [https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken](POST /_matrix/identity/v2/validate/msisdn/submitToken) endpoints do not specify any particular specifc error codes, instead relying on the common error codes +defined in the identity service API. + +However, these common error codes don't have any codes to signal many errors that can occur in these +APIs: most obviously, that the token the user entered was incorrect. + +This MSC can be considered similar to [https://github.com/matrix-org/matrix-spec-proposals/pull/4178](MSC4178) +although that MSC is for `requestToken` on the C/S API only. + +The [https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken](POST /_matrix/client/v3/account/3pid/email/requestToken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to +be the same as the Identity API's `submitToken` endpoints. This MSC also affects this. + +## Proposal + +Add the following specific error code as a code that can be returned by the two endpoints given above: + * `M_TOKEN_INCORRECT`: Indicates that the token that the user entered to validate the session is incorrect. + +Additionally specify that the following common error codes can be returned: + * `M_INVALID_PARAM`: One of the supplied parameters in not valid. + * `M_SESSION_EXPIRED`: The validation session is question has expired. + +Also change the C/S API's definition of +[https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken](POST +/_matrix/client/v3/account/3pid/email/requestToken) to specify that the entire API is the same, including +response / error codes, rather than just parameters. + +## Potential issues + +None forseen. + +## Alternatives + +None considered. + +## Security considerations + +None forseen. + +## Unstable prefix + +No unstable prefix is deemed necessary. Sydent already sends the common error codes and also sends +`M_NO_VALID_SESSION` if the code is incorrect. Once an identity server (or homeserver) switches to +use the new error code, they may not recognise the error condition correctly until updated to support +the new code. We say that this is acceptable in favour of avoding the complexity of negotiating error +codes with API versions. Since the identity server is generally used via the homeserver now, most +uses of this API will not currently be receiving a sensible error code in this situation anyway. + +## Dependencies + +None From daa21323684d6c87b57b2fc42b28cb0481e35bc0 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 28 Aug 2024 17:16:55 +0100 Subject: [PATCH 02/21] Bah, markdown --- proposals/4180-submitToken-error-codes.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4180-submitToken-error-codes.md index 6a87c97ac68..cadfaa95cf3 100644 --- a/proposals/4180-submitToken-error-codes.md +++ b/proposals/4180-submitToken-error-codes.md @@ -1,15 +1,15 @@ # MSC4180: Additional Error Codes for submitToken endpoint -The [https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken](POST /_matrix/identity/v2/validate/email/submitToken) and [https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken](POST /_matrix/identity/v2/validate/msisdn/submitToken) endpoints do not specify any particular specifc error codes, instead relying on the common error codes +The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) endpoints do not specify any particular specifc error codes, instead relying on the common error codes defined in the identity service API. However, these common error codes don't have any codes to signal many errors that can occur in these APIs: most obviously, that the token the user entered was incorrect. -This MSC can be considered similar to [https://github.com/matrix-org/matrix-spec-proposals/pull/4178](MSC4178) +This MSC can be considered similar to [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178) although that MSC is for `requestToken` on the C/S API only. -The [https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken](POST /_matrix/client/v3/account/3pid/email/requestToken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to +The [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the Identity API's `submitToken` endpoints. This MSC also affects this. ## Proposal @@ -22,8 +22,9 @@ Additionally specify that the following common error codes can be returned: * `M_SESSION_EXPIRED`: The validation session is question has expired. Also change the C/S API's definition of -[https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken](POST -/_matrix/client/v3/account/3pid/email/requestToken) to specify that the entire API is the same, including +[`POST +/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +to specify that the entire API is the same, including response / error codes, rather than just parameters. ## Potential issues From f4fdd0fd296a669c9481d161948ec2379f1cd782 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 28 Aug 2024 17:17:48 +0100 Subject: [PATCH 03/21] Line wrapping --- proposals/4180-submitToken-error-codes.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4180-submitToken-error-codes.md index cadfaa95cf3..9f5a68e3baa 100644 --- a/proposals/4180-submitToken-error-codes.md +++ b/proposals/4180-submitToken-error-codes.md @@ -1,7 +1,9 @@ # MSC4180: Additional Error Codes for submitToken endpoint -The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) endpoints do not specify any particular specifc error codes, instead relying on the common error codes -defined in the identity service API. +The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) +and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) +endpoints do not specify any particular specifc error codes, instead relying on the common error codes defined in the +identity service API. However, these common error codes don't have any codes to signal many errors that can occur in these APIs: most obviously, that the token the user entered was incorrect. @@ -21,11 +23,8 @@ Additionally specify that the following common error codes can be returned: * `M_INVALID_PARAM`: One of the supplied parameters in not valid. * `M_SESSION_EXPIRED`: The validation session is question has expired. -Also change the C/S API's definition of -[`POST -/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) -to specify that the entire API is the same, including -response / error codes, rather than just parameters. +Also change the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +to specify that the entire API is the same, including response / error codes, rather than just parameters. ## Potential issues From 0cdf8c68c475fe29bc3e2f25ea9d64911c371838 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 28 Aug 2024 17:18:54 +0100 Subject: [PATCH 04/21] Typos --- proposals/4180-submitToken-error-codes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4180-submitToken-error-codes.md index 9f5a68e3baa..773c5dc3a3a 100644 --- a/proposals/4180-submitToken-error-codes.md +++ b/proposals/4180-submitToken-error-codes.md @@ -2,7 +2,7 @@ The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) -endpoints do not specify any particular specifc error codes, instead relying on the common error codes defined in the +endpoints do not specify any particular specific error codes, instead relying on the common error codes defined in the identity service API. However, these common error codes don't have any codes to signal many errors that can occur in these @@ -43,7 +43,7 @@ None forseen. No unstable prefix is deemed necessary. Sydent already sends the common error codes and also sends `M_NO_VALID_SESSION` if the code is incorrect. Once an identity server (or homeserver) switches to use the new error code, they may not recognise the error condition correctly until updated to support -the new code. We say that this is acceptable in favour of avoding the complexity of negotiating error +the new code. We say that this is acceptable in favour of avoiding the complexity of negotiating error codes with API versions. Since the identity server is generally used via the homeserver now, most uses of this API will not currently be receiving a sensible error code in this situation anyway. From 7fb14aab26046a97e9dffc3ae3c0bb8cfb1bddff Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 29 Aug 2024 11:08:27 +0100 Subject: [PATCH 05/21] Right MSC number Co-authored-by: Johannes Marbach --- proposals/4180-submitToken-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4180-submitToken-error-codes.md index 773c5dc3a3a..11592e64265 100644 --- a/proposals/4180-submitToken-error-codes.md +++ b/proposals/4180-submitToken-error-codes.md @@ -1,4 +1,4 @@ -# MSC4180: Additional Error Codes for submitToken endpoint +# MSC4183: Additional Error Codes for submitToken endpoint The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) From 725f2ec3925af22372ff868c9b5e8f9226af75e7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 29 Aug 2024 11:09:24 +0100 Subject: [PATCH 06/21] Rename --- ...submitToken-error-codes.md => 4183-submitToken-error-codes.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{4180-submitToken-error-codes.md => 4183-submitToken-error-codes.md} (100%) diff --git a/proposals/4180-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md similarity index 100% rename from proposals/4180-submitToken-error-codes.md rename to proposals/4183-submitToken-error-codes.md From d3832858c8efc0eea24619fdc714486fafaec406 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 29 Aug 2024 11:48:00 +0100 Subject: [PATCH 07/21] Add http status code --- proposals/4183-submitToken-error-codes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 11592e64265..2c935103815 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -19,10 +19,14 @@ be the same as the Identity API's `submitToken` endpoints. This MSC also affects Add the following specific error code as a code that can be returned by the two endpoints given above: * `M_TOKEN_INCORRECT`: Indicates that the token that the user entered to validate the session is incorrect. +HTTP status code 400 should be used for this error. + Additionally specify that the following common error codes can be returned: * `M_INVALID_PARAM`: One of the supplied parameters in not valid. * `M_SESSION_EXPIRED`: The validation session is question has expired. +HTTP status code 400 should also be used for both of these errors. + Also change the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) to specify that the entire API is the same, including response / error codes, rather than just parameters. From 7809cedcb8699cc44a474456d22cc310daa2f4a1 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 2 Oct 2024 11:29:46 +0100 Subject: [PATCH 08/21] Apply suggestions from code review Spelling / grammar fixes Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/4183-submitToken-error-codes.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 2c935103815..a4bb775d312 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -2,14 +2,14 @@ The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) -endpoints do not specify any particular specific error codes, instead relying on the common error codes defined in the +endpoints do not specify any specific error codes, instead relying on the common error codes defined in the identity service API. However, these common error codes don't have any codes to signal many errors that can occur in these APIs: most obviously, that the token the user entered was incorrect. This MSC can be considered similar to [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178) -although that MSC is for `requestToken` on the C/S API only. +although that MSC is for `requestToken` on the C-S API only. The [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the Identity API's `submitToken` endpoints. This MSC also affects this. @@ -32,7 +32,7 @@ to specify that the entire API is the same, including response / error codes, ra ## Potential issues -None forseen. +None foreseen. ## Alternatives @@ -40,7 +40,7 @@ None considered. ## Security considerations -None forseen. +None foreseen. ## Unstable prefix @@ -49,7 +49,7 @@ No unstable prefix is deemed necessary. Sydent already sends the common error co use the new error code, they may not recognise the error condition correctly until updated to support the new code. We say that this is acceptable in favour of avoiding the complexity of negotiating error codes with API versions. Since the identity server is generally used via the homeserver now, most -uses of this API will not currently be receiving a sensible error code in this situation anyway. +users of this API will not currently receive a sensible error code in this situation anyway. ## Dependencies From be435a85416332d0bdf462a584eee4b0d29c5db3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 2 Oct 2024 11:32:05 +0100 Subject: [PATCH 09/21] Word wrap --- proposals/4183-submitToken-error-codes.md | 27 ++++++++++++++--------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index a4bb775d312..319019ef251 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -1,18 +1,22 @@ # MSC4183: Additional Error Codes for submitToken endpoint -The [`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) -and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) -endpoints do not specify any specific error codes, instead relying on the common error codes defined in the -identity service API. +The [`POST +/_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) +and [`POST +/_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) +endpoints do not specify any specific error codes, instead relying on the common error codes defined in the identity +service API. -However, these common error codes don't have any codes to signal many errors that can occur in these -APIs: most obviously, that the token the user entered was incorrect. +However, these common error codes don't have any codes to signal many errors that can occur in these APIs: most +obviously, that the token the user entered was incorrect. -This MSC can be considered similar to [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178) -although that MSC is for `requestToken` on the C-S API only. +This MSC can be considered similar to [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178) although +that MSC is for `requestToken` on the C-S API only. -The [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to -be the same as the Identity API's `submitToken` endpoints. This MSC also affects this. +The [`POST +/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the +Identity API's `submitToken` endpoints. This MSC also affects this. ## Proposal @@ -27,7 +31,8 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also change the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) +Also change the C/S API's definition of [`POST +/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) to specify that the entire API is the same, including response / error codes, rather than just parameters. ## Potential issues From 007d364abc8fdff6e00fd8882f764306db21b897 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 2 Oct 2024 11:43:41 +0100 Subject: [PATCH 10/21] Clearer wording --- proposals/4183-submitToken-error-codes.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 319019ef251..0ff0e090632 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -51,10 +51,11 @@ None foreseen. No unstable prefix is deemed necessary. Sydent already sends the common error codes and also sends `M_NO_VALID_SESSION` if the code is incorrect. Once an identity server (or homeserver) switches to -use the new error code, they may not recognise the error condition correctly until updated to support -the new code. We say that this is acceptable in favour of avoiding the complexity of negotiating error -codes with API versions. Since the identity server is generally used via the homeserver now, most -users of this API will not currently receive a sensible error code in this situation anyway. +use the new error code, clients (including homeservers proxying the IS API) may not recognise the +error condition correctly until updated to support the new code. We say that this is acceptable in +favour of avoiding the complexity of negotiating error codes with API versions. Since the identity +server is generally used via the homeserver now, most users of this API will not currently receive +a sensible error code in this situation anyway. ## Dependencies From 43638f134ff79981c8f7bd41c6bf21e2c20f48b4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 23 Oct 2024 09:59:17 +0100 Subject: [PATCH 11/21] clarify --- proposals/4183-submitToken-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 0ff0e090632..62373337146 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -16,7 +16,7 @@ that MSC is for `requestToken` on the C-S API only. The [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the -Identity API's `submitToken` endpoints. This MSC also affects this. +Identity API's `submitToken` endpoints. Everything this MSC specifies applies to this endpoint in the same way. ## Proposal From 5b8b163c0dccdf6538abce6653205e93ac605730 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 23 Oct 2024 12:34:24 +0100 Subject: [PATCH 12/21] Clarify --- proposals/4183-submitToken-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 62373337146..3719f6370e1 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -33,7 +33,7 @@ HTTP status code 400 should also be used for both of these errors. Also change the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) -to specify that the entire API is the same, including response / error codes, rather than just parameters. +to specify that the endpoint is the same as the I/S API version in all ways, including response / error codes, rather than just parameters. ## Potential issues From c026da70457786c88d1d592c5ebb86159eeed7d0 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 18 Nov 2024 14:52:32 +0000 Subject: [PATCH 13/21] Add note about not reusing error code --- proposals/4183-submitToken-error-codes.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 3719f6370e1..e98543661d7 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -23,6 +23,9 @@ Identity API's `submitToken` endpoints. Everything this MSC specifies applies to Add the following specific error code as a code that can be returned by the two endpoints given above: * `M_TOKEN_INCORRECT`: Indicates that the token that the user entered to validate the session is incorrect. +Note that we deliberately chose not to re-use `M_UNKNOWN_TOKEN` since that refers to an access token, whereas this +refers to a token that the user enters. + HTTP status code 400 should be used for this error. Additionally specify that the following common error codes can be returned: From 70d3e073ee9d466e102a36a96a875ddf4ac7b1e6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 18 Nov 2024 14:58:28 +0000 Subject: [PATCH 14/21] Clarify that we're taking about the submittoken api in requestToken --- proposals/4183-submitToken-error-codes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index e98543661d7..3aa12689edf 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -34,9 +34,9 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also change the C/S API's definition of [`POST +Also change the correspomding submitYoken-like API given in the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) -to specify that the endpoint is the same as the I/S API version in all ways, including response / error codes, rather than just parameters. +to specify that both request and response parameters / error codes are the same as the I/S API version, rather than just parameters, apart from needing an I/S API token. ## Potential issues From 28d1128361adb7b9bab19eedb841aad949c90bcf Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 18 Nov 2024 14:59:28 +0000 Subject: [PATCH 15/21] spelling --- proposals/4183-submitToken-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 3aa12689edf..6094a6febe1 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -34,7 +34,7 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also change the correspomding submitYoken-like API given in the C/S API's definition of [`POST +Also change the corresponding submitYoken-like API given in the C/S API's definition of [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) to specify that both request and response parameters / error codes are the same as the I/S API version, rather than just parameters, apart from needing an I/S API token. From 7c53dc9108e94abf1aa8803178bdfbd1dd2595ed Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 26 Nov 2024 17:59:55 +0000 Subject: [PATCH 16/21] Clearer wording Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/4183-submitToken-error-codes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 6094a6febe1..9075c2e6349 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -34,9 +34,9 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also change the corresponding submitYoken-like API given in the C/S API's definition of [`POST -/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) -to specify that both request and response parameters / error codes are the same as the I/S API version, rather than just parameters, apart from needing an I/S API token. +Also change the `submit_url` field in the response to [`POST +/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken), +to specify that response parameters and error codes are the same as the I/S API version, as well as request parameters. ## Potential issues From 63dcbe095c089f968833dc0800d714e8b40f9e16 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 27 Nov 2024 14:19:10 +0000 Subject: [PATCH 17/21] Add note on POST email submitToken api and how it isn't really a thing in practice --- proposals/4183-submitToken-error-codes.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 9075c2e6349..788f0a9245d 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -18,6 +18,11 @@ The [`POST endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the Identity API's `submitToken` endpoints. Everything this MSC specifies applies to this endpoint in the same way. +Note that the email `submitToken` endpoint ([`POST +/_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)) +is not generally used in practice: Sydent's emails includes a link to click and therefore use the +`GET` version. This proposal updates both for consistency. + ## Proposal Add the following specific error code as a code that can be returned by the two endpoints given above: From af1dc8605f8f80312c3e62a175fa48bb34c5f627 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 29 Nov 2024 09:34:04 +0000 Subject: [PATCH 18/21] Hopefully make more clearer --- proposals/4183-submitToken-error-codes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 788f0a9245d..9ff95157700 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -18,10 +18,10 @@ The [`POST endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the Identity API's `submitToken` endpoints. Everything this MSC specifies applies to this endpoint in the same way. -Note that the email `submitToken` endpoint ([`POST +Note that the `POST` version of the email `submitToken` endpoint ([`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)) -is not generally used in practice: Sydent's emails includes a link to click and therefore use the -`GET` version. This proposal updates both for consistency. +is not generally used in practice (and does not exist on the C/S API): Sydent's emails includes a link to click and +therefore use the `GET` version. This proposal updates both for consistency. ## Proposal From 0f43a510baca29c0546e5cd88b21d0434ab891ce Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 29 Nov 2024 10:53:04 +0000 Subject: [PATCH 19/21] Apply same change to other submitToken endpoints ...from the other requestToken enpoints Also try to further clarify the note about the largely unused POST email submitToken --- proposals/4183-submitToken-error-codes.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 9ff95157700..2e2f497f3c8 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -15,13 +15,15 @@ that MSC is for `requestToken` on the C-S API only. The [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) -endpoint in the C/S API also specifies a `submit_url` response parameter, defining its parameters to be the same as the -Identity API's `submitToken` endpoints. Everything this MSC specifies applies to this endpoint in the same way. +The numerous `requestToken` endpoints (enumerated in the proposal section) in the C/S API also specify a `submit_url` +response parameter, defining their parameters to be the same as the Identity API's `submitToken` endpoints. Everything +this MSC specifies applies to these endpoint in the same way. Note that the `POST` version of the email `submitToken` endpoint ([`POST /_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)) -is not generally used in practice (and does not exist on the C/S API): Sydent's emails includes a link to click and -therefore use the `GET` version. This proposal updates both for consistency. +is not generally used in practice: Sydent's emails includes a link to click instead of the `submit_url` response field and +therefore use the `GET` version. Synapse does not implement the `POST` API for email validation for this reason. This +proposal updates both for consistency. ## Proposal @@ -39,9 +41,16 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also change the `submit_url` field in the response to [`POST -/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken), -to specify that response parameters and error codes are the same as the I/S API version, as well as request parameters. +Also apply the same change to all the `submit_url` fields in the various response to the `POST requestToken` endpoints, ie: + + * [`POST /_matrix/client/v3/register/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * [`POST /_matrix/client/v3/register/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3registerrequesttoken) + * [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) + * [`POST /_matrix/client/v3/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken) + * [`POST /_matrix/client/v3/account/password/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3accountpasswordemailrequesttoken) + * [`POST /_matrix/client/v3/account/password/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3accountpasswordmsisdnrequesttoken) + +...to specify that response parameters and error codes are the same as the I/S API version, as well as request parameters. ## Potential issues From 9c12f64380306ba9771f54600ff2e4b66abe8bcf Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 29 Nov 2024 11:54:29 +0000 Subject: [PATCH 20/21] Remove stray lines, more clarifications & consistency fix --- proposals/4183-submitToken-error-codes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 2e2f497f3c8..0db94d908cc 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -11,10 +11,8 @@ However, these common error codes don't have any codes to signal many errors tha obviously, that the token the user entered was incorrect. This MSC can be considered similar to [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178) although -that MSC is for `requestToken` on the C-S API only. +that MSC is for `requestToken` on the C/S API only. -The [`POST -/_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) The numerous `requestToken` endpoints (enumerated in the proposal section) in the C/S API also specify a `submit_url` response parameter, defining their parameters to be the same as the Identity API's `submitToken` endpoints. Everything this MSC specifies applies to these endpoint in the same way. @@ -27,7 +25,11 @@ proposal updates both for consistency. ## Proposal -Add the following specific error code as a code that can be returned by the two endpoints given above: +Add the following specific error code as a code that can be returned by both +[`POST +/_matrix/identity/v2/validate/email/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) +and [`POST +/_matrix/identity/v2/validate/msisdn/submitToken`](https://spec.matrix.org/v1.11/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken): * `M_TOKEN_INCORRECT`: Indicates that the token that the user entered to validate the session is incorrect. Note that we deliberately chose not to re-use `M_UNKNOWN_TOKEN` since that refers to an access token, whereas this From c630214de45b2b47636ddc7eaede031c81e0bcd8 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 29 Nov 2024 11:57:56 +0000 Subject: [PATCH 21/21] clarify only c/s api Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/4183-submitToken-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4183-submitToken-error-codes.md b/proposals/4183-submitToken-error-codes.md index 0db94d908cc..b75691a121f 100644 --- a/proposals/4183-submitToken-error-codes.md +++ b/proposals/4183-submitToken-error-codes.md @@ -43,7 +43,7 @@ Additionally specify that the following common error codes can be returned: HTTP status code 400 should also be used for both of these errors. -Also apply the same change to all the `submit_url` fields in the various response to the `POST requestToken` endpoints, ie: +Also apply the same change to all the `submit_url` fields in the various response to the `POST requestToken` endpoints in the client-server API, i.e.: * [`POST /_matrix/client/v3/register/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3registeremailrequesttoken) * [`POST /_matrix/client/v3/register/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3registerrequesttoken)