Email invite flow uses unspecced org.matrix.web_client_location parameter

[richvdh]

This whole thing is woefully unspecced:

• Synapse supports an email.invite_client_location configuration setting (see email settings). 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
• 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, 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?

[richvdh]

It's also worth noting that the text of the email invite (see template) specifically mentions "Element", so an alternative perspective on this is:

• This is a thing that is only supported by the matrix.org or vector.im deployments of Sydent, to choose different Element deployments.
• As such, the format of the invite link is a private matter between Element-web and the operators of the matrix.org and vector.im deployments of Sydent
• If other people want to do something similar, they have to host their own Sydent, with different email templates, which allows them to both change the text of the email and the format of the invite link.

But in that case:

• The org.matrix.web_client_location should still be documented somewhere so that homeservers other than Synapse can use it.
• There is no guarantee that a user of a given homeserver will choose to use the matrix.org or vector.im deployments, and therefore a homeserver admin has no way of knowing how the target identity server will translate the org.matrix.web_client_location parameter into a link.

(For the record, this parameter appears to have been added in matrix-org/sydent#326.)