Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC4178: Additional Error Codes for requestToken endpoint #4178

Merged
merged 6 commits into from
Sep 3, 2024
+46 −0
Merged

MSC4178: Additional Error Codes for requestToken endpoint #4178

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c960aeb
Add proposal for unsupported 3pid error code
dbkr Aug 16, 2024
8fe16bf
Update number
dbkr Aug 16, 2024
4e64f32
Add another error code
dbkr Aug 19, 2024
3cc801e
Uncontroversial wording changes
anoadragon453 Aug 19, 2024
ed432ab
Clarity
dbkr Aug 19, 2024
f6c6fe6
Specify HTTP status code
dbkr Aug 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions proposals/4178-threepid-medium-not-supported.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# MSC4178: Error codes for requestToken

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
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

Firstly, Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both
[`POST /account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken)
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.
Comment on lines +14 to +18
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

slightly wondering if we should extend this to POST /account/3pid/<unknown_medium>/requestToken, but perhaps that's a job for another day.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the whole 3pid management spec could be generalised to arbitrary media, arguably. Might make more sense to do if we ever add another medium.


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).
clokep marked this conversation as resolved.
Show resolved Hide resolved

For both of these codes, HTTP status code 400 should be used.
Comment on lines +14 to +23
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you considered extending this to the identity server endpoints? /_matrix/identity/v2/validate/email/requestToken etc?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't really, although only because the need is more obvious for homeservers which commonly may or may not support verifying certain types of identifier. Happy to add this for ID servers too if we'd rather keep symmetry and do it all in one go.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given FCP has now started, it's probably best to leave this for a future MSC.


## Potential issues

None foreseen.

## Alternatives

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.
clokep marked this conversation as resolved.
Show resolved Hide resolved

## Security considerations

None foreseen.

## 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