Spec the v2 IS auth APIs

[turt2live]

This is part 2 of many, as shown by #2253

It may be easier to review this commit by commit. See 'docs' status check for what this looks like in the spec.

This PR intentionally does not include terms of service handling to try and keep the PR reviewable.

Specs part of MSC2140.

[richvdh]

I've not had time to read this, but please can it specify the expected behaviour for the various endpoints when no id access token is given, with respect to fallback to v1 apis?

[turt2live]

@richvdh upon reflection, the behaviour is a 400 bad request because the field is required. At least that's how I'm reading the MSC's requirement - @dbkr might want to fight me on that (please do). This is why it's listed as a breaking change.

[richvdh]

ok, but how is a homeserver that supports both cs api 0.5 and cs api 0.6 supposed to behave when it gets a call to /invite (or whatever) without an id_access_token?

[turt2live]

I'm not saying its the right answer, but the answer I have is that the homeserver can't support r0.5 and r0.6

[richvdh]

That sounds like a terrible idea :/

[turt2live]

The right answer is probably amending the MSC to clarify that homeservers can perform calls without it, if they want to. They'd just have to use the (now-deprecated) v1 IS API.

[dbkr]

The MSC does say that, although I would argue here that if a client supplies id_server but not id_access_token, it is respecting r0.5 and not r0.6. Just because the spec mandates that a parameter must be supplied, doesn't mean a server must also mandate it: the server can allow it to be optional in order to be compatible with both r0.5 and r0.6.

[turt2live]

I'll add a note to the spec to clarify that, just to avoid the future question.

[jryans]

This also looks reasonable to me. 😁