MSC4211: WebXDC on Matrix

proposals/4211-webxdc.md

@@ -0,0 +1,156 @@
+# MSC4211: WebXDC on Matrix
+
+
+In Matrix, users may want to send each other interactive content (for example a game
+in a groupchat, or maybe a collaborative board). Previously, integrations were used 
+to provide such content, but they are not in-band (thus needs another server, which 
+tends to be unmaintained as of now). As such, this proposal aims to resolve this by
+adding [WebXDC](https://webxdc.org/) into the Matrix client ecosystem, with no 
+server-side changes or additions needed.
+
+## Proposal
+
+A common method, with a well-defined API and that isn't locked to the Matrix ecosystem
+(which may be useful for, e.g bridges, which would greatly benefit from such a common 
+system, and even client developers, who can simply rely on pre-existing tooling) and 
+that wouldn't require server administrators to either host another software solution 
+or users to resort to a centralised hub(as integrations) would be highly appreciable.
+
+(Please note that the following simply describes how WebXDC calls transmate to 
+Matrix events. More information is available at WebXDC's own specification)
+
+To start a WebXDC event, a client may start by sending a `m.webxdc.start` event, 
+formatted as such:
+```jsonc
+{
+ "content": {
+ "name": "Storm on Mt. Ooe", // optional, must be a string
+ "url": "mxc://hell.club/WebXDCFileForClients", // MUST be a .xdc file
+ "icon": "mxc://hell.club/AnIconForTheWebXDC", // optional,
+ // content.icon_mime must exist 
+ // iff present
+ "icon_mime": "image/png" // present IFF content.icon is present
+ },
+ "room_id": "!former:hell.club",
+ "event_id": "$WebXDCStart1",
+ "sender": "@yuugi:hell.club",
+ "type": "m.webxdc.start"
+ ...
+}
+```
+where the `content.url` field must be a MXC URI pointing to the WebXDC media.
+Once a user starts, a client can show the event(alongside `content.name`, and 
+`content.icon`/`content.icon_mime`) as an invitation to enter the WebXDC context. 
+
+If so, it MUST set `window.webxdc.selfAddr` and `window.webxdc.selfName` to the 
+user's MXID and name in the room(or the global name stored in the profile API if 
+unavailable, otherwise fallback to the MXID), respectively.
+
+Whenever a client calls the JavaScript `window.webxdc.sendUpdate(update, desc)` 
+function, it MUST send a `m.room.message` with a relation to the original event 
+with `rel_type=m.webxdc`, the `content.body` field being the description if existent,
+and the *required* `m.webxdc.data` containing a JSON-encoded object as a representation 
+of `update`, which must be stored as a string if it contains floating-point numbers,
+like so:
+```js
+// Client tries to send an update
+window.webxdc.sendUpdate(
+ { 
+ payload: {graze: 430, score: 5300},
+ info: window.webxdc.selfName + ' got over the Spellcard!',
+ summary: "Score: 5300"
+ }, 
+ "New Score on Mt. Ooe"
+);
+```
+
+```jsonc
+{
+ "content": {
+ "m.relates_to": { "event_id": "$WebXDCStart1", "rel_type": "m.webxdc" },
+ "body": "Marisa got over the Spellcard!",
+ "m.webxdc.data": {
+ "payload": {
+ "graze": 430,
+ "score": 5300
+ },
+ "info": "Marisa got over the Spellcard!",
+ "summary": "Score: 5300"
+ }
+ },
+ "sender": "@marisa:magic.forest",
+ "room_id": "!former:hell.club",
+ "event_id": "$WebXDCEvent",
+ "type": "m.room.message",
+ ...
+}
+```
+
+Clients receiving such an event(including themselves) must process it with 
+the listener set with `window.webxdc.setUpdateListener`, with the update's 
+`payload` being the `content->m.webxdc.data` object, it's `info`, `document` 
+and `summary` being the `content->m.webxdc.data->info`, `content->m.webxdc.data->document`,
+and `content->m.webxdc.data->summary` fields respectively, the 
+`serial`/`max_serial` fieldd being the current and last event's `origin_server_ts` 
+fields respecticely. They must also check for such events (ideally via the 
+relations API).
+
+The `window.webxdc.sendToChat(message)` function shall send a regular event to the 
+current room with the `content->body` field being set to the `message.text` value, 
+and being sent as the correct type of media if the `media.file` value exists.
+
+
+## Potential issues
+
+Non WebXDC-capable clients currently do not get a fallback for WebXDC start events, 
+which means that such messages will either not display, or will be hidden. Note that 
+this isn't a big issue, since clients that simply do not handle WebXDC generally have 
+no real reason to have the file in the first place.
+
+Handling of floating-point values within events within the spec(which effectively do 
+not allow such things) may be an issue for WebXDC applications which require it.
+
+Servers may be out of sync with the `origin_server_ts`, thus causing conditions where 
+two WebXDC updates `A` and `B`, such that `A` comes before `B`, may be processed in the 
+order `B` *then* `A`.
+
+As it is experimental, this proposal does not provide a mapping between 
+`window.webxdc.joinRealtimeChannel` and a real, Matrix-side construct. The author also 
+doesn't see a good way to make it function alongside the existing event system properly, 
+and recommends waiting until it is stable within the WebXDC API before making an MSC 
+which supports it. As such, clients MUST set the function to the JavaScript `undefined`.
+
+
+## Alternatives
+
+Another way to have interactive content in rooms would be to use an integration manager. 
+However, these would require an additional server to be setup(which are not maintained), 
+and would effectively be limited to the Matrix ecosystem only, instead of being platform-
+agnostic.
+Widgets(MSC1236), while powerful, also suffer from a similar agnosticity problem with 
+other platforms.
+
+## Security considerations
+
+WebXDC still suffers from some issues, due to its nature, which is effectively a packaged web 
+application. As such, client developers will need to be careful to properly conceal secrets
+(like a user's access token), and must follow [the WebXDC constraints](https://webxdc.org/docs/spec/messenger.html#webview-constraints-for-running-apps).
+A malicious user could also use WebXDC as a vector for existing vulnerabilities in, e.g, a
+browser/JavaScript engine, thus being able to break out of sandboxes. Clients must first
+consult the user on whenever they want to start a WebXDC session, and must warn of potential 
+risks, especially with untrusted entities.
+
+
+## Unstable prefix
+
+Until this MSC is merged, client shall replace the following namespaces:
+- `m.webxdc`->`at.kappach.at.webxdc`
+- `m.webxdc.start`->`at.kappach.at.webxdc.start`
+- `m.webxdc.data`->`at.kappach.at.webxdc.data`
+
+As this proposal acts at the event layer, there is no need to ask the server for if it has 
+support for this proposal.
+
+## Dependencies
+
+This MSC is independent of any other unmerged MSCs.