From 07c9b7c36fd0bf07bfae31aaf2818c4ddecfb43e Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 20 Jan 2022 11:53:47 +0000 Subject: [PATCH 1/3] Add proposal --- proposals/0000-widget-share-api.md | 79 ++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 proposals/0000-widget-share-api.md diff --git a/proposals/0000-widget-share-api.md b/proposals/0000-widget-share-api.md new file mode 100644 index 000000000..5367d651f --- /dev/null +++ b/proposals/0000-widget-share-api.md @@ -0,0 +1,79 @@ +# MSC0000: Allow Widgets to share user MxIds to the client + +[Widgets](https://github.com/matrix-org/matrix-doc/pull/2764) offer the ability to expand +the functionality of clients by calling widget APIs to invoke actions on the client. + +This proposal aims to allow widgets to share the details of users to the client with the +intention that the client can then open a dialogue to create a new room or invite a user. +This is useful for bridge situations where the bridge would like to offer a widget for +searching for users across the remote network, which can then invoke invites or room creation +on the remote side. + +For sharing eventIds or rooms, this is somewhat covered by [MSC2931](https://github.com/matrix-org/matrix-doc/pull/2931/files) + +## Proposal + +To send the information to the client, widgets would use a new `fromWidget` request with +action `mxid_share` which takes the following shape: + +```json5 +{ + "api": "fromWidget", + "widgetId": "20200827_WidgetExample", + "requestid": "generated-id-1234", + "action": "mxid_share", + "data": { + "users": [ + { + "user_id": "@alice:example.com", + "display_name": "Alice", + "avatar_url": "mxc://foo/bar" + } + ], + "action_hint": "invite", // One of invite, create_room + } +} +``` + +The `users` field must contain a set valid Matrix users. The `display_name` and `avatar_url` fields +are optional decoration, which may be used if the requested user does not exist yet (as can be the case with bridges). +The client SHOULD attempt to do it's own lookup of the `user_id`'s profile first and only fall back to the included +profile if the lookup fails. + +If any of the provided `user_id` values are invalid, or if the `users` array is empty then the client MUST ignore +the request. + +The `action_hint` field is optional, and describes to the client the intention of the user. + +- When the `action_hint` is `invite`, the client should prefer to show an invite interface prepopulated with +the user's details. +- When the `action_hint` is `create_room`, the client should create a DM with the included users. +- Otherwise, it is left up to the implementation to decide how to handle the shared information. + + +Since the API proposed here doesn't *mutate* the client in any way, this proposal require a capability to +be negotiated. Information passed from the widget to the client should NEVER be used without the client +consenting to the action (e.g. never autocreate a DM room with a user without prompting) + +## Potential issues + +TODO: Issues? + +## Alternatives + +TODO: Alternatives? + +## Security considerations + +This proposal allows the widget to choose displaynames and avatars for users it provides +to the client, which could be used maliciously to hide the identity of a user in the interface. +It's imperative that the client first tries to determine if a profile already exists, and failing that +the userID of the shared user(s) should be presented so the user of the client can make their +own assessment. + + +## Unstable prefix + +While this MSC is not in a released version of the specification, clients should use +`uk.half-shot.mscXXXX.mxid_share` as the `action` type. + From 9f706d177e0e249c25daf31bd2ed20ec7ae23ed2 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 20 Jan 2022 11:55:33 +0000 Subject: [PATCH 2/3] 3662 --- .../{0000-widget-share-api.md => 3662-widget-share-api.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{0000-widget-share-api.md => 3662-widget-share-api.md} (98%) diff --git a/proposals/0000-widget-share-api.md b/proposals/3662-widget-share-api.md similarity index 98% rename from proposals/0000-widget-share-api.md rename to proposals/3662-widget-share-api.md index 5367d651f..6e9459c73 100644 --- a/proposals/0000-widget-share-api.md +++ b/proposals/3662-widget-share-api.md @@ -1,4 +1,4 @@ -# MSC0000: Allow Widgets to share user MxIds to the client +# MSC3662: Allow Widgets to share user MxIds to the client [Widgets](https://github.com/matrix-org/matrix-doc/pull/2764) offer the ability to expand the functionality of clients by calling widget APIs to invoke actions on the client. From 49132bd3bd3c50e80e435fc1ba9af2e1429bbc50 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 20 Jan 2022 15:50:17 +0000 Subject: [PATCH 3/3] Update 3662-widget-share-api.md --- proposals/3662-widget-share-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3662-widget-share-api.md b/proposals/3662-widget-share-api.md index 6e9459c73..20a68f0bb 100644 --- a/proposals/3662-widget-share-api.md +++ b/proposals/3662-widget-share-api.md @@ -9,7 +9,8 @@ This is useful for bridge situations where the bridge would like to offer a widg searching for users across the remote network, which can then invoke invites or room creation on the remote side. -For sharing eventIds or rooms, this is somewhat covered by [MSC2931](https://github.com/matrix-org/matrix-doc/pull/2931/files) +For navigating to rooms/events, this is somewhat covered by [MSC2931](https://github.com/matrix-org/matrix-doc/pull/2931/files). While that +MSC covers navigating to matrix.to, it does not convey the intended action. ## Proposal