From c529549d0bb08c2ae6d21d8b215ef976d9918609 Mon Sep 17 00:00:00 2001 From: Stephen Paul Weber Date: Wed, 10 Jul 2024 14:38:07 -0500 Subject: [PATCH] XEP-0491: Clarifications based on feedback --- xep-0491.xml | 53 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/xep-0491.xml b/xep-0491.xml index 5d7db08c2..233e23f08 100644 --- a/xep-0491.xml +++ b/xep-0491.xml @@ -1,7 +1,9 @@ - WebXDC"> + WebXDCWebXDC docs: https://webxdc.org/docs/"> + WebXDCWebXDC sendUpdate: https://webxdc.org/docs/spec/sendUpdate.html"> + WebXDCWebXDC selfAddr and selfName: https://webxdc.org/docs/spec/selfAddr_and_selfName.html"> %ents; ]> @@ -19,11 +21,25 @@ XMPP Core XMPP IM + XEP-0335 + XEP-0421 + WebXDC webxdc &singpolyma; + + 0.1.3 + 2024-10-17 + spw + +
    +
  • Clarifications and wording
    • +
  • Better references for WebXDC spec
    • +
+ + 0.1.2 2024-07-03 @@ -53,16 +69,25 @@ -

&webxdc; is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections. In order to use these, the host protocol must define a way to transmit the widgets and the associated state updates.

+

&webxdc; is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections for the sandboxed web content. In order to provide support for &webxdc; widgets, the host protocol (XMPP in our case) must define a way to transmit these widgets and the associated state updates.

+ + +

This specification uses some terminology defined below:

+
    +
  • widget: the WebXDC widget delivered in a zip container as defined by &webxdc;
    • +
  • host application: the XMPP client embedding the widget
    • +
  • peer: the chat partner in a 1:1 chat or one of the participants of a &xep0045; or other group chat
    • +
  • host protocol: the protocol used by the peers to communicate (XMPP in our case)
    • +
-

A widget may be attached to a message using any file-transfer mechanism supported by the client, such as &xep0066; or &xep0385;. The message MUST contain a <thread/> element with a new, unique id.

+

A widget may be attached to a message using any file-transfer mechanism supported by the client, such as &xep0066; or &xep0385;. The message MUST contain a <thread/> element with a new, unique id. Note: including multiple file-transfer mechanisms in the same message may be beneficial for broader compatibility.

018fe972-ea89-7f4b-90f8-729b85b7f32d - application/xdc+zip + application/webxdc+zip Calendar 3032449 2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU= @@ -72,10 +97,13 @@ + https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/calendar.xdc + ]]> -

When a widget needs to communicate an update to other participants, this update may contain the following information:

+

When a widget needs to communicate an update to peers in a chat, this update may contain one or more of the following items as defined in &webxdcSendUpdate;.

@@ -98,7 +126,7 @@
ItemArbitrary JSON serializable value
-

These items, except for the info item, are delivered in a message which MUST have the same <thread> as the message which originally delivered the widget itself, as children of an element <x xmlns="urn:xmpp:webxdc:0"> as defined below.

+

These items are delivered in a message which MUST have the same <thread> as the message which originally delivered the widget itself. The stanza SHOULD contain a x child having the urn:xmpp:webxdc:0 namespace, with these items (except for info) as children, as defined below.

The info item is human-readable and is not needed by the widget itself, thus it is appropriate to transmit it anywhere that it might be visible to all participants, such as in a message body. If this is the only item present, an empty <x> element SHOULD still be included in the message to signal this update came from the widget.

 -

WebXDC widgets get various data injected into them by the host application. One of these worth mentioning is the selfAddr property. When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID. When the chat supports &xep0421; this property SHOULD be set to the local party's occupant id.

+

&webxdcaddrname; widgets get various data injected into them by the host application. One of these worth mentioning is the selfAddr property.

+
    +
  • When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID e.g. xmpp:juliet@capulet.lit
    • +
  • When the chat supports &xep0421; this property SHOULD be set to the local party's occupant-id.
    • +
  • Note that no other type of chat is specified here, and especially that a &xep0045; chat without support for &xep0421; SHOULD NOT use full Jabber ID or room nickname for the property, as it may case inconsistent behaviour in some widgets when the user changes their nickname.
    • +
+ + +

The selfName property defined by &webxdcaddrname; is human readable and may be set to anything useful per that specification. It MAY be set to the local &xep0045; nickname or &xep0172; where relevant.

None

 -

This XEP does not have any specific security considerations, however it is assumed that it will be paired with an implementation of &webxdc; which requires very careful sandboxing.

+

It is assumed that an implementation of this XEP will be paired with an implementation of &webxdc;. Please see &webxdc; for sandboxing and security considerations for your WebXDC implementation.

+

This XEP does not introduce any specific security considerations besides those present in any &webxdc; implementation.

It should be clear to users that their actions inside an embedded widget may be transmitted to other participants.