Merge 49132bd3bd into 1a82fca4eb

proposals/3662-widget-share-api.md

@@ -0,0 +1,80 @@
+# 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.
+
+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 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
+
+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.
+