matrix-org / matrix-org/matrix-spec
Email invite flow uses unspecced `org.matrix.web_client_location` parameter
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
This whole thing is woefully unspecced:
* Synapse supports an `email.invite_client_location` configuration setting (see [email settings](https://matrix-org.github.io/synapse/v1.72/usage/configuration/config_documentation.html#email)). Typically it is set to something like `https://develop.element.io`.
* When a client sends a third-party invite, Synapse passes that location as an unspecced `org.matrix.web_client_location` parameter to [`POST /_matrix/identity/v2/store-invite`](https://spec.matrix.org/v1.5/identity-service-api/#post_matrixidentityv2store-invite)
* Sydent includes the location (or a default of `https://app.element.io`) in the email that is sent to the invited users, along with an entirely unspecified fragment string (including the room id, a callback URI called `signurl` whose purpose I don't entirely understand, but in practice is the confusingly-named `/_matrix/identity/api/v1/sign-ed25519` (https://github.com/matrix-org/sydent/issues/533), and other details of the room).
Given that this forms part of the interface between homeservers and identity servers , the `org.matrix.web_client_location` parameter should be part of the spec. Better yet, it should be specced *without* the `org.matrix` prefix.
The spec also needs to include details of what the expected behaviour of the target location should be. What parameters are passed, and what is the target client expected to do with them? In particular, what is `signurl`?
Contributor guide
Research direction
Start with the Matrix identity service API's POST /_matrix/identity/v2/store-invite section and Synapse's email.invite_client_location configuration. Review Sydent's email behavior and the linked sign-ed25519 discussion to establish the current parameters and the purpose of signurl. Done should define the parameter, target-location inputs, client behavior, and signurl semantics in the specification.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100