xeps/inbox/muc-avatars.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>XMPP Resources Avatars</title>
  <abstract>This specification describes how to publish and retrieve avatars from XMPP resources.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standard Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0045</spec>
    <spec>XEP-0054</spec>
    <spec>XEP-0068</spec>
    <spec>XEP-0153</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  <author>
    <firstname>Emmanuel Gil</firstname>
    <surname>Peyrot</surname>
    <email>linkmauve@linkmauve.fr</email>
    <jid>linkmauve@linkmauve.fr</jid>
  </author>
  <author>
    <firstname>Timothée</firstname>
    <surname>Jaussoin</surname>
    <email>edhelas@movim.eu</email>
    <jid>edhelas@movim.eu</jid>
  </author>
  <revision>
    <version>0.0.2</version>
    <date>2018-11-03</date>
    <initials>tj</initials>
    <remark><p>Generalise to non-MUC resources.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2018-08-21</date>
    <initials>egp</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>Avatars are small images people often use to identify each other very quickly in chat applications. They are well defined for users, in &xep0084; and &xep0153;, but until now chat rooms and Pubsub nodes all shared a default icon. This extension provides a way for owners to associates an avatar to the XMPP their resources and users to discover that an avatar is associated and display it accordingly.</p>
  <p>XMPP services have traditionally allowed owners to <link url='https://docs.ejabberd.im/tutorials/muc-vcard/'>set a vCard-temp on a MUC</link> using &xep0054;, this extension tries to keep as much of it as possible so existing applications don’t have to be modified too much.</p>
  <p>Some implementations recently chose to advertise those avatars using the existing &xep0153; extension in &lt;presence/&gt;, but it exposed issues in other implementations, and was only available when the user is already present in the room, not before joining it (for example when listing all available rooms).</p>
  <p>A future extension superseding this one could define a method based on &xep0084;, with a PubSub service on the room’s bare JID containing the metadata and data nodes.  Such a specification should also define a compatibility profile similar to &xep0398; for user avatars, enabling the coexistence of both versions until the present one is deemed obsolete.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>This specification SHOULD:</p>
  <ul>
    <li>Allow authorised entities to set an avatar on a MUC, user JID or Pubsub node.</li>
    <li>Allow authorised entities to remove a previously-set avatar on a MUC, user JID or Pubsub node.</li>
    <li>Allow users to discover an avatar is set on a MUC, user JID or Pubsub node.</li>
    <li>Allow users to request the avatar of a MUC, user JID or Pubsub node.</li>
    <li>Let users know that the avatar of a MUC changed while they are present in said MUC.</li>
    <li>Let users know that the avatar of a Pubsub node changed while they are subscribed to this node.</li>
    <li>Let users know that the avatar of a user JID changed while they are subscribed to this user.</li>
    <li>Let users discover the avatar even when not present in the MUC, user JID or Pubsub node.</li>
    <li>Stay as compatible as possible with the current usage of avatars in MUC and user JID.</li>
  </ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Discover the features supported by a service' anchor='disco'>
    <p>Before trying to use avatars, a client must check that the related service that is hosting the rooms or Pubsub nodes does support them.</p>
    <example caption='User’s client discovers the features of a MUC service'><![CDATA[
<iq type='get'
    id='p87Ne'
    from='romeo@montague.example.net/garden'
    to='chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
    <example caption='Room advertises support for vcard-temp'><![CDATA[
<iq type='result'
    id='p87Ne'
    to='romeo@montague.example.net/garden'
    from='chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        type='text'
        name='Shakespearean Chat Service'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='vcard-temp'/>
    ...
  </query>
</iq>]]></example>

    <example caption='User’s client discovers the features of a Pubsub service'><![CDATA[
<iq type='get'
    id='p88Ne'
    from='romeo@montague.example.net/garden'
    to='pubsub.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
    <example caption='Pubsub service advertises support for vcard-temp'><![CDATA[
<iq type='result'
    id='p88Ne'
    to='romeo@montague.example.net/garden'
    from='chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='pubsub'
        type='service'
        name='Shakespearean Pubsub Service'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='vcard-temp'/>
    ...
  </query>
</iq>]]></example>
  </section2>
  <section2 topic='Owner of the resource Publishes Avatar' anchor='owner-publish'>
    <p>Before anyone can see an avatar attached to the resource, an owner or some other priviledged entity must publish a vCard-temp containing the avatar’s data, using the protocol defined in &xep0054;.</p>
    <example caption='Owner’s client publishes avatar to the room'><![CDATA[
<iq type='set'
    id='7fP13'
    from='romeo@montague.example.net/garden'
    to='garden@chat.shakespeare.example.org'>
  <vCard xmlns='vcard-temp'>
    <PHOTO>
      <TYPE>image/svg+xml</TYPE>
      <BINVAL>PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+CiA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIGZpbGw9InJlZCIvPgo8L3N2Zz4K</BINVAL>
    </PHOTO>
  </vCard>
</iq>]]></example>
    <example caption='Room acknowledges publish action'><![CDATA[
<iq type='result'
    id='7fP13'
    to='romeo@montague.example.net/garden'
    from='garden@chat.shakespeare.example.org'/>]]></example>

    <example caption='Owner’s client publishes avatar to the Pubsub node'><![CDATA[
<iq type='set'
    id='7fP14'
    from='romeo@montague.example.net/garden'
    to='pubsub.shakespeare.example.org'>
  <configure node='princely_musings'>
    <vCard xmlns='vcard-temp'>
      <PHOTO>
        <TYPE>image/svg+xml</TYPE>
        <BINVAL>PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+CiA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIGZpbGw9InJlZCIvPgo8L3N2Zz4K</BINVAL>
      </PHOTO>
    </vCard>
  </configure>
</iq>]]></example>
    <example caption='Pubsub node acknowledges publish action'><![CDATA[
<iq type='result'
    id='7fP14'
    to='romeo@montague.example.net/garden'
    from='pubsub.shakespeare.example.org'/>]]></example>

    <p>There is no other action required on the owner’s end.</p>
    <p>If the service doesn’t support support avatars, it must return a service-unavailable error.</p>
    <example caption='Room doesn’t support vCard-temp'><![CDATA[
<iq type='error'
    id='7fP13'
    to='romeo@montague.example.net/garden'
    from='garden@chat.shakespeare.example.org'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>]]></example>
    <p>If the user trying to publish an avatar isn’t allowed to do so, the resource must return a forbidden error, see the <link url='#security'>Security Considerations</link>.</p>
    <example caption='User is not allowed to set vCard-temp'><![CDATA[
<iq type='error'
    id='7fP13'
    to='romeo@montague.example.net/garden'
    from='garden@chat.shakespeare.example.org'>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <text>Only owners are allowed to set avatars.</text>
  </error>
</iq>]]></example>
    <p>The resource should then broadcast a notification that the configuration changed to all users present or subscribed.</p>
    <example caption='Room broadcasts a configuration change'><![CDATA[
<message type='groupchat'
         to='romeo@montague.example.net/garden'
         from='garden@chat.shakespeare.example.org'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <status code='104'/>
  </x>
</message>

<message type='groupchat'
         to='juliet@capulet.example.com/balcony'
         from='garden@chat.shakespeare.example.org'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <status code='104'/>
  </x>
</message>]]></example>

    <p>For Pubsub nodes, the service broadcast a configuration change to all the subscribed users as described in the section 8.2.5.3 of &xep0060;.</p>

    <example caption='User is not allowed to set vCard-temp'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <configuration node='princely_musings'/>
  </event>
</message>]]></example>

    <p>Setting an empty vCard unpublishes the avatar.</p>
    <example caption='Owner’s client removes a room’s avatar'><![CDATA[
<iq type='set'
    id='83tFs'
    from='romeo@montague.example.net/garden'
    to='garden@chat.shakespeare.example.org'>
  <vCard xmlns='vcard-temp'/>
</iq>]]></example>
  </section2>
  <section2 topic='User Discovers the Avatar' anchor='disco-avatar-hash'>
    <p>At any point, whether it is during a join in order to display it in its UI, after having discovered the list of the rooms or Pubsub nodes and to list them with additional information, or when receiving a configuration change notification, a user’s client can discover information about a resource.</p>
    <example caption='User’s client discovers information about a room'><![CDATA[
<iq type='get'
    id='K92am'
    from='juliet@capulet.example.com/balcony'
    to='garden@chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
    <p>If the resource has had <link url='#owner-publish'>an avatar published</link>, it should advertise it in its 'muc#roominfo' or 'pubsub#meta-data' (see the section 5.4 of &xep0060;) extension form, using the &xep0153; hash computation method.</p>
    <example caption='Room advertises its avatar hash'><![CDATA[
<iq type='result'
    id='K92am'
    to='juliet@capulet.example.com/balcony'
    from='garden@chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        type='text'
        name='The Garden'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='vcard-temp'/>
    ...
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#roominfo</value>
      </field>
      ...
      <field var='muc#roominfo_avatarhash'
             type='text-multi'
             label='Avatar hash'>
        <value>a31c4bd04de69663cfd7f424a8453f4674da37ff</value>
      </field>
      ...
    </x>
  </query>
</iq>]]></example>

    <example caption='Pubsub node advertises its avatar hash'><![CDATA[
<iq type='result'
    from='pubsub.shakespeare.lit'
    to='francisco@denmark.lit/barracks'
    id='meta1'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='princely_musings'>
    <identity category='pubsub' type='leaf'/>
    <feature var='http://jabber.org/protocol/pubsub'/>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/pubsub#meta-data</value>
      </field>
      ...
      <field var='pubsub#meta-data_avatarhash'
             type='text-multi'
             label='Avatar hash'>
        <value>a31c4bd04de69663cfd7f424a8453f4674da37ff</value>
      </field>
      ...
    </x>
  </query>
</iq>]]></example>
    <p>This 'muc#roominfo_avatarhash' or 'pubsubmuc#meta-data_avatarhash' are not present when the resource doesn’t have an avatar set.</p>
  </section2>
  <section2 topic='User Retrieves the vCard' anchor='retrieve-vcard'>
    <p>At this point the client knows the hash and can retrieve the resource's vCard-temp.</p>
    <example caption='User’s client retrieves the vCard-temp from a room'><![CDATA[
<iq type='get'
    id='uD10h'
    from='juliet@capulet.example.com/balcony'
    to='garden@chat.shakespeare.example.org'>
  <vCard xmlns='vcard-temp'/>
</iq>]]></example>
    <example caption='Room returns the vCard-temp containing the avatar'><![CDATA[
<iq type='result'
    id='uD10h'
    to='juliet@capulet.example.com/balcony'
    from='garden@chat.shakespeare.example.org'>
  <vCard xmlns='vcard-temp'>
    <PHOTO>
      <TYPE>image/svg+xml</TYPE>
      <BINVAL>PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+CiA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIGZpbGw9InJlZCIvPgo8L3N2Zz4K</BINVAL>
    </PHOTO>
  </vCard>
</iq>]]></example>
    <p>To retrieve the vCard-temp of a Pubsub node the client is then doing a specific request on the Node metadata (see the section 5.4 of &xep0060;).</p>

    <example caption='User’s client retrieves the vCard-temp from a Pubsub node'><![CDATA[
<iq type='get'
    from='francisco@denmark.lit/barracks'
    to='pubsub.shakespeare.lit'
    id='meta1'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='princely_musings'>
    <vCard xmlns='vcard-temp'/>
  </query>
</iq>]]></example>
    <example caption='Pubsub node returns the vCard-temp containing the avatar'><![CDATA[
<iq type='result'
    from='pubsub.shakespeare.lit'
    to='francisco@denmark.lit/barracks'
    id='meta1'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='princely_musings'>
    <vCard xmlns='vcard-temp'>
      <PHOTO>
        <TYPE>image/svg+xml</TYPE>
        <BINVAL>PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+CiA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIGZpbGw9InJlZCIvPgo8L3N2Zz4K</BINVAL>
      </PHOTO>
    </vCard>
  </query>
</iq>]]></example>

    <p>The client then has to decode the &lt;BINVAL/&gt; content from base64, hash it with sha1 and compare it with the advertised hash, and if it matches uses it as the resource avatar under the &lt;TYPE/&gt; media type.</p>
  </section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p>An application MUST support the image/png media type, SHOULD support image/jpeg, image/gif and image/svg+xml, and MAY support additional formats.</p>
  <p>A room or a Pubsub node SHOULD NOT include a 'muc#roominfo_avatarhash' or 'pubsubmuc#meta-data_avatarhash' field if it doesn’t have an avatar set.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <section2 topic='Multiple Stored Version of an Avatar' anchor='multiple'>
    <p>Multiple &lt;PHOTO/&gt; elements may be present in a vCard, in which case they should all represent the same image and the hash field must contain a hash of all of them.</p>
    <example caption='Owner’s client publishes avatar in two different formats'><![CDATA[
<iq type='set'
    id='7fP13'
    from='romeo@montague.example.net/garden'
    to='garden@chat.shakespeare.example.org'>
  <vCard xmlns='vcard-temp'>
    <PHOTO>
      <TYPE>image/svg+xml</TYPE>
      <BINVAL>PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+CiA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIGZpbGw9InJlZCIvPgo8L3N2Zz4K</BINVAL>
    </PHOTO>
    <PHOTO>
      <TYPE>image/png</TYPE>
      <BINVAL>iVBORw0KGgoAAAANSUhEUgAAACAAAAAgAQMAAABJtOi3AAAAB3RJTUUH4ggVERoVAPsrMgAAAAlwSFlzAAALEgAACxIB0t1+/AAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAAEZ0FNQQAAsY8L/GEFAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURf8AAP///0EdNBEAAAABYktHRAH/Ai3eAAAADElEQVQI12NgGNwAAACgAAFhJX1HAAAAAElFTkSuQmCC</BINVAL>
    </PHOTO>
  </vCard>
</iq>]]></example>
    <example caption='Room advertises both hashes'><![CDATA[
<iq type='result'
    id='K92am'
    to='juliet@capulet.example.com/balcony'
    from='garden@chat.shakespeare.example.org'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        type='text'
        name='The Garden'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='vcard-temp'/>
    ...
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#roominfo</value>
      </field>
      ...
      <field var='muc#roominfo_avatarhash'
             type='text-multi'
             label='Avatar hash'>
        <value>a31c4bd04de69663cfd7f424a8453f4674da37ff</value>
        <value>b9b256f999ded52c2fa14fb007c2e5b979450cbb</value>
      </field>
      ...
    </x>
  </query>
</iq>]]></example>
  </section2>
  <section2 topic='Previous Usage of Presence for Avatar Advertising' anchor='presence'>
    <p>Some existing implementations send or expect a presence from the room’s bare JID in order to detect an avatar being published. This had several issues, with existing clients handling that as a presence from a user with an empty nick or downright triggering an error, and was only available if the client was already present in the room, preventing any usecase where it would get displayed before entering the room.</p>
    <p>For those reasons, this XEP doesn’t encourage this way of advertising the presence of an avatar, but for reference it would look like a &xep0153; presence payload:</p>
    <example caption='Room advertises a non-standard vCard update in a presence'><![CDATA[
<presence from='garden@chat.shakespeare.example.org'>
  <x xmlns='vcard-temp:x:update'>
    <photo>a31c4bd04de69663cfd7f424a8453f4674da37ff</photo>
  </x>
</presence>
]]></example>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>A server should take care that only allowed entities can publish a vCard-temp on a MUC, for instance room owners or service administrators.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Field Standartization' anchor='registrar-formtype'>
    <p>The registrar shall add the following field to the 'muc#roominfo' data form:</p>
    <section3 topic='muc#roominfo FORM_TYPE' anchor='registrar-formtype-roominfo'>
      <code caption='Registry Submission'><![CDATA[
<form_type>
  <name>http://jabber.org/protocol/muc#roominfo</name>
  <doc>XEP-XXXX</doc>
  <desc>Form extension for avatar support in a Multi-User Chat (MUC) room.</desc>
  <field
      var='muc#roominfo_avatarhash'
      type='text-multi'
      label='Hash of the vCard-temp avatar of this room'/>
</form_type>
]]></code>
    </section3>
    <section3 topic='pubsub#meta-data FORM_TYPE' anchor='registrar-formtype-roominfo'>
      <code caption='Registry Submission'><![CDATA[
<form_type>
  <name>http://jabber.org/protocol/pubsub#meta-data</name>
  <doc>XEP-XXXX</doc>
  <desc>Form extension for avatar support in a Pubsub node.</desc>
  <field
      var='pubsub#meta-data_avatarhash'
      type='text-multi'
      label='Hash of the vCard-temp avatar of this node'/>
</form_type>
]]></code>
    </section3>
  </section2>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to the Ejabberd developers for their MUC vCard tutorial, and to Sam Whited and Matthew Wild for their feedback.</p>
</section1>
</xep>