[WIP] MSC1956: Integrations API (base)

[turt2live]

Rendered
See matrix-org/matrix-spec#296
Discussion room: #msc-integrations-api:t2bot.io

Note: Currently this proposal is not ready for review in its entirety. The actual contents of the Integrations API are not yet fully defined, and other proposals must get approved before this proposal can officially work through the process. This is being opened now to have a reference number for all things Integrations API though.

Feedback on whether the concept of an Integrations API makes sense is welcome though, even if the final contents are still well within the draft status.

Required proposals:

• MSC1951 - Custom emoji and sticker packs
• MSC1957 - Integration manager discovery
• MSC1958 - Widget architecture changes
• MSC1959 - Sticker picker API
• MSC1960 - OpenID information exchange for widgets
• MSC1961 - Integration manager authentication APIs
• MSC2140 - Terms of Service handling
• MSC2315 - Selecting 'none' as an integration manager

---

This is being contributed under the hat of "author of Dimension":

Signed-off-by: Travis Ralston <[email protected]>

[turt2live]

note to self: it's a bit cross cutting, but a read of https://sandstorm.io/how-it-works is a good idea

[turt2live]

Include #2192 (if it stays relevant)

[turt2live]

add #2315

[turt2live]

note to self: reference the following diagrams (if needed):

• Standard auth dance: https://gist.githubusercontent.com/turt2live/db2639a61bfa0a5a4bc3bdc23013db1d/raw/553a4abc3c6555652897d5e4fb948854178eb474/integration-manager-auth.md
• Widget auth dance (expected): https://gist.githubusercontent.com/turt2live/f1b59ba26bf629dce0edf344b6b99d70/raw/f6d313e46f21d828d6ec898836404c07d17198e2/widget-auth-exchange.md
• Widget auth dance (whitelisted, current): https://gist.githubusercontent.com/turt2live/9e3c2924540ef6e19401dc1991695192/raw/3b66f0203f28d91231c12aafa36c155222cab161/widget-auth-today.md

Also, the dances need better names. Currently we have:

• OpenID dance - the dance to get a subject from the homeserver
• OpenID exchange dance - the dance for a widget to get an OpenID subject/authentication token
• Terms dance - the dance after an authentication token is acquired to check for unaccepted policies
• Auth dance - the combination of the three dances, plus the integration manager's internal operations dance

[turt2live]

TODO: Add a ready state to widget postMessage API so that widgets don't have to rely on the capabilities request taking an amount of time.

[KB1RD]

From reading the code of https://github.com/matrix-org/matrix-widget-api, it seems like these errors have only a message field that contains human-readable text. This could be problematic since the error message is not defined in the spec, so it's impossible for a widget to know what the error is. For example, the string Invalid request - missing event type isn't standardized anywhere, so it can't be differentiated from Cannot send state events of this type unless the widget knows exactly what these strings will be ahead of time (which are specific to that particular library).

It may be helpful to define standard error types (like the error codes in the C2S API) to categorize these errors. Ex, M_WIDGET_MISSING_PARAM or M_WIDGET_DENIED for the above errors.

[ghost]

Hi @turt2live If this proposal is blocked because others need to be merged first, please if you don't mind, add the "blocked" label to organize things better.

[richvdh]

I believe this is an attempt to fix matrix-org/matrix-spec#296, though I am somewhat confused.

(edit: oh, it is. It's linked from the description, though using a different link)