<?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>Invisibility</title>
  <abstract>This specification defines best practices regarding implementation of invisible presence by means of XMPP privacy lists.</abstract>
  &LEGALNOTICE;
  <number>0126</number>
  <status>Active</status>
  <type>Informational</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>N/A</shortname>
  &stpeter;
  <revision>
    <version>1.1</version>
    <date>2005-08-19</date>
    <initials>psa</initials>
    <remark>Corrected order of presence and IQ stanzas to ensure proper processing by server.</remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2004-03-05</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2004-02-10</date>
    <initials>psa</initials>
    <remark>Minor editorial clarifications.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2004-01-22</date>
    <initials>psa</initials>
    <remark>Added client responsibility for sending last available or unavailable presence.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2004-01-21</date>
    <initials>psa</initials>
    <remark>Added more detail to the Security Considerations.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2004-01-08</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>Several popular instant messaging services implement a feature known as invisibility: the ability to remain online yet appear offline to some or all of one's contacts. A number of Jabber servers and clients have also implemented such a feature, using special values of the &PRESENCE; element's 'type' attribute (e.g., &lt;presence type='invisible'/&gt;). Unfortunately, such implementations are not compliant with &xmppcore; and &xmppim;, which specify that only the 'type' attribute values defined in the XML schema for the 'jabber:client' and 'jabber:server' namespaces are allowed in XMPP (and those values do not include "invisible"). However, <cite>RFC 3921</cite> also defines a privacy lists protocol (i.e., the 'jabber:iq:privacy' namespace) that can be used to implement invisibility in an XMPP-compliant manner. This specification documents how to do just that.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>This document addresses the following requirements:</p>
  <ul>
    <li>Enable users to appear visible or invisible to some or all contacts at any time.</li>
    <li>Enable users to selectively change visibility based on roster group, subscription state, or individual JID.</li>
    <li>Do so in an XMPP-compliant manner.</li>
  </ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <p>This document addresses the following use cases:</p>
  <ol>
    <li>Log In as Globally Invisible</li>
    <li>Become Selectively Visible</li>
    <li>Become Globally Visible</li>
    <li>Become Selectively Invisible</li>
    <li>Become Globally Invisible</li>
  </ol>
  <p>These use cases are defined below in "chronological" order by following a scenario in which a user (1) logs in as invisible, (2) becomes selectively visible to certain contacts, (3) becomes visible to all contacts, (4) becomes selectively invisible to certain contacts, and finally (5) becomes invisible to all contacts.</p>
  <section2 topic='Log In as Globally Invisible' anchor='invis-login'>
    <p>If a user wants to log in as invisible, a certain order of events MUST be followed. Specifically, after authenticating but before sending initial presence, the user MUST define (if necessary) and set as active a privacy list that blocks all outbound presence notifications.</p>
    <example caption='User Defines and Sets Global Invisibility Privacy Rule'><![CDATA[
... authentication / session establishment ...

<iq from='bilbo@tolkien.lit/shire' type='set' id='inv1'>
  <query xmlns='jabber:iq:privacy'>
    <list name='invisible'>
      <item action='deny' order='1'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active1'>
  <query xmlns='jabber:iq:privacy'>
    <active name='invisible'/>
  </query>
</iq>
    ]]></example>
    <p>Naturally, the user could have defined this list during a previous session and could simply set the relevant list as active when logging in, rather than defining the list on login. Both steps are shown here for completeness.</p>
    <p>The user may now send initial presence to the server.</p>
    <example caption='User Sends Initial Presence'><![CDATA[
<presence>
  <status>I'm not really here, you understand!</status>
</presence>
    ]]></example>
    <p>Even though the user has sent initial presence, that presence information will not be broadcasted to any of the user's contacts, since the active privacy list blocks all outbound presence notifications.</p>
  </section2>
  <section2 topic='Become Selectively Visible' anchor='vis-select'>
    <p>Let us now suppose that the user tires of being globally invisible, and decides to become visible to some -- but not all -- contacts (not even famous magic rings possess this feature). The 'jabber:iq:privacy' namespace gives the user three options:</p>
    <ul>
      <li>become visible only to specific JIDs</li>
      <li>become visible only to specific roster groups</li>
      <li>become visible based on subscription state</li>
    </ul>
    <p>Examples of these options are shown below.</p>
    <section3 topic='Becoming Visible by JID' anchor='vis-select-jid'>
      <example caption='User Defines and Sets Selective Visibility Privacy Rule (by JID)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv2'>
  <query xmlns='jabber:iq:privacy'>
    <list name='visible-to-Frodo'>
      <item type='jid'
            value='frodo@tolkien.lit'
            action='allow'
            order='1'>
        <presence-out/>
      </item>
      <item action='deny' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active2'>
  <query xmlns='jabber:iq:privacy'>
    <active name='visible-to-Frodo'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list blocks outbound presence notifications to every JID except one.</p>
      <p>In order to ensure synchronization of presence notifications, the client SHOULD now re-send the user's presence for broadcasting to all contacts, which the active rule will block to all but the specified JID:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm not really here, you understand!</status>
</presence>
      ]]></example>
    </section3>
    <section3 topic='Becoming Visible by Roster Group' anchor='vis-select-roster'>
      <example caption='User Defines and Sets Selective Visibility Privacy Rule (by Roster Group)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv3'>
  <query xmlns='jabber:iq:privacy'>
    <list name='visible-to-Bagginses'>
      <item type='group'
            value='Bagginses'
            action='allow'
            order='1'>
        <presence-out/>
      </item>
      <item action='deny' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active3'>
  <query xmlns='jabber:iq:privacy'>
    <active name='visible-to-Bagginses'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list blocks outbound presence notifications to every JID except those in a certain roster group. In order to ensure synchronization of presence notifications, the client SHOULD now re-send the user's presence for broadcasting to all contacts, which the active rule will block to all but those JIDs in the specified roster group:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm not really here, you understand!</status>
</presence>
      ]]></example>
    </section3>
    <section3 topic='Becoming Visible by Subscription Type' anchor='vis-select-sub'>
      <p>Becoming visible or invisible by subscription type is probably much less likely than becoming visible by JID or roster group; however, it is described here for the sake of completeness.</p>
      <example caption='User Defines and Sets Selective Visibility Privacy Rule (by Subscription State)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv4'>
  <query xmlns='jabber:iq:privacy'>
    <list name='visible-to-both'>
      <item type='subscription'
            value='both'
            action='allow'
            order='1'>
        <presence-out/>
      </item>
      <item action='deny' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active4'>
  <query xmlns='jabber:iq:privacy'>
    <active name='visible-to-both'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list blocks outbound presence notifications to every JID except those that are in the user's roster with a subscription type of "both".</p>
      <p>In order to ensure synchronization of presence notifications, the client SHOULD now re-send the user's presence for broadcasting to all contacts, which the active rule will block to all but those JIDs with the specified subscription type:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm not really here, you understand!</status>
</presence>
      ]]></example>
    </section3>
  </section2>
  <section2 topic='Become Globally Visible' anchor='vis-global'>
    <p>Let us now suppose that the user wants to become visible to all those who are subscribed to his presence. This easy to do by defining and setting as active a new privacy list (here again, the privacy list may have been defined previously).</p>
    <example caption='User Defines and Sets Global Visibility Privacy Rule'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv5'>
  <query xmlns='jabber:iq:privacy'>
    <list name='visible'>
      <item action='allow' order='1'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active5'>
  <query xmlns='jabber:iq:privacy'>
    <active name='visible'/>
  </query>
</iq>
    ]]></example>
    <p>Because globally allowing outbound presence notifications is most likely the default behavior of any server, a more straightforward way to become globally visible is to decline the use of any active rule (the equivalent, as it were, of taking off a magic invisibility ring):</p>
    <example caption='User Declines the Use of Any Active Rule'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='active6'>
  <query xmlns='jabber:iq:privacy'>
    <active/>
  </query>
</iq>
    ]]></example>
    <p>In order to ensure synchronization of presence notifications, the client SHOULD now re-send the user's presence for broadcasting to all contacts, which the active rule will block to all but the specified JID:</p>
    <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm back!</status>
</presence>
    ]]></example>
  </section2>
  <section2 topic='Become Selectively Invisible' anchor='invis-select'>
    <p>Let us now suppose that the user no longer wants to be globally visible, but desires to be invisible only to some -- but not all -- contacts. As with visibility, here again the 'jabber:iq:privacy' namespace gives the user three options:</p>
    <ul>
      <li>Become invisible only to specific JIDs</li>
      <li>Become invisible only to specific roster groups</li>
      <li>Become invisible based on subscription state</li>
    </ul>
    <p>Examples of these options are shown below.</p>
    <p>In general, the process for becoming selectively invisible is as follows:</p>
    <ol>
      <li>Send unavailable presence to the server.</li>
      <li>Define and set a privacy rule for selective invisibility.</li>
      <li>Send available presence to the server.</li>
    </ol>
    <p>This process is necessary so that the contacts covered by the rule will no longer see the user as available.</p>
    <section3 topic='Becoming Invisible by JID' anchor='invis-select-jid'>
      <p>First, the user sends unavailable presence for broadcasting to all contacts:</p>
      <example caption='User Sends Unavailable Presence'><![CDATA[
<presence type='unavailable'/>
      ]]></example>
      <p>The server then broadcasts that presence to all of the user's contacts.</p>
      <p>Second, the user defines and sets a privacy rule that allows selective invisibility:</p>
      <example caption='User Defines and Sets Selective Invisibility Privacy Rule (by JID)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv6'>
  <query xmlns='jabber:iq:privacy'>
    <list name='invisible-to-Gandalf'>
      <item type='jid'
            value='gandalf@tolkien.lit'
            action='deny'
            order='1'>
        <presence-out/>
      </item>
      <item action='allow' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active7'>
  <query xmlns='jabber:iq:privacy'>
    <active name='invisible-to-Gandalf'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list allows outbound presence notifications to every JID except one.</p>
      <p>In order to appear selectively invisible, the client MUST now re-send the user's presence for broadcasting to all contacts, which the active rule will block to the specified JID:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm back!</status>
</presence>
      ]]></example>
    </section3>
    <section3 topic='Becoming Invisible by Roster Group' anchor='invis-select-roster'>
      <p>First, the user sends unavailable presence for broadcasting to all contacts:</p>
      <example caption='User Sends Unavailable Presence'><![CDATA[
<presence type='unavailable'/>
      ]]></example>
      <p>The server then broadcasts that presence to all of the user's contacts.</p>
      <p>Second, the user defines and sets a privacy rule that allows selective invisibility:</p>
      <example caption='User Defines and Sets Selective Invisibility Privacy Rule (by Roster Group)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv7'>
  <query xmlns='jabber:iq:privacy'>
    <list name='invisible-to-Wizards'>
      <item type='group'
            value='Wizards'
            action='deny'
            order='1'>
        <presence-out/>
      </item>
      <item action='allow' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active8'>
  <query xmlns='jabber:iq:privacy'>
    <active name='invisible-to-Wizards'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list allows outbound presence notifications to every JID except those in a certain roster group.</p>
      <p>In order to appear selectively invisible, the client MUST now re-send the user's presence for broadcasting to all contacts, which the active rule will block to those in the specified roster group:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm back!</status>
</presence>
      ]]></example>
    </section3>
    <section3 topic='Becoming Invisible by Subscription Type' anchor='invis-select-sub'>
      <p>Becoming visible or invisible by subscription type is probably much less likely than becoming visible by JID or roster group; however, it is described here for the sake of completeness.</p>
      <p>First, the user sends unavailable presence for broadcasting to all contacts:</p>
      <example caption='User Sends Unavailable Presence'><![CDATA[
<presence type='unavailable'/>
      ]]></example>
      <p>The server then broadcasts that presence to all of the user's contacts.</p>
      <p>Second, the user defines and sets a privacy rule that allows selective invisibility:</p>
      <example caption='User Defines and Sets Selective Invisibility Privacy Rule (by Subscription State)'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='inv8'>
  <query xmlns='jabber:iq:privacy'>
    <list name='invisible-to-from'>
      <item type='subscription'
            value='from'
            action='deny'
            order='1'>
        <presence-out/>
      </item>
      <item action='allow' order='2'>
        <presence-out/>
      </item>
    </list>
  </query>
</iq>

<iq from='bilbo@tolkien.lit/shire' type='set' id='active9'>
  <query xmlns='jabber:iq:privacy'>
    <active name='invisible-to-from'/>
  </query>
</iq>
      ]]></example>
      <p>The foregoing privacy list allows outbound presence notifications to every JID except those that are in the user's roster with a subscription type of "to".</p>
      <p>In order to appear selectively invisible, the client MUST now re-send the user's presence for broadcasting to all contacts, which the active rule will block to those with the specified subscription type:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm back!</status>
</presence>
      ]]></example>
    </section3>
  </section2>
  <section2 topic='Become Globally Invisible' anchor='invis-global'>
    <p>In order to become globally invisible again, the user does the following.</p>
    <p>First, the user sends unavailable presence for broadcasting to all contacts:</p>
    <example caption='User Sends Unavailable Presence'><![CDATA[
<presence type='unavailable'/>
    ]]></example>
    <p>Second, the user sets as active the global invisibility list previously defined:</p>
    <example caption='User Becomes Globally Invisible'><![CDATA[
<iq from='bilbo@tolkien.lit/shire' type='set' id='active10'>
  <query xmlns='jabber:iq:privacy'>
    <active name='invisible'/>
  </query>
</iq>
    ]]></example>
    <p>In order to appear globally invisible, the client MUST now re-send the user's presence for broadcasting to all contacts, which the active rule will block to all contacts:</p>
      <example caption='Client Sends Available Presence'><![CDATA[
<presence>
  <status>I'm not really here, you understand!</status>
</presence>
      ]]></example>
  </section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <p>The foregoing text explains the protocol used to implement invisibility. Naturally, client developers will most likely want to hide these protocol details from the end user. For example, rather than forcing the end user to navigate the details of privacy list management, a client could simply provide a "Go Invisible" button that sets as active the appropriate privacy list.</p>
  <p>Note well that the privacy lists used to implement invisibility SHOULD be active lists and <em>not</em> the default list.</p>
  <p>To help ensure cross-client compatibility, it is RECOMMENDED to use the privacy list names "visible" and "invisible" for simple global visibility and invisibility respectively. It is also RECOMMENDED to use list names of the form "visible-to-GroupName" and "invisible-to-JID" for simple lists that implement visibility or invisibility with regard to roster groups and JIDs. Obviously list names could become rather complex, such as "visible-to-Group1 Group2 Group3". Implementations MUST NOT attempt to derive semantic meaning from privacy list names; these recommendations are provided for ease of use only with regard to basic privacy lists related to visibility/invisibility.</p>
  <p>In general it is probably easiest for users to become visible/invisible either globally or based on roster group, since these models are conceptually simple. Although, naturally, a client developer cannot tell users what to do, it probably best to encourage the use of conceptually simple models for privacy lists.</p>
  <p>Privacy lists can become complex and must be carefully managed by clients. For example, let us imagine that the user is currently applying another active list unrelated to visibility (e.g., a list that blocks communications with a stalker); if the user then clicks "Go Invisible" and the client is not smart, it could overwrite the stalker blocking. Therefore, if the user has an active list that incorporates rules other than those related to visibility/invisibility, the client SHOULD either assume that visibility/invisibility is an overlay on the list currently in use (generating an appropriate privacy list that takes both into account) or prompt the user regarding their intentions. In the absence of privacy lists unrelated to visibility/invisibility, the client may proceed in a less cautious fashion.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>For security concerns related to privacy lists, refer to <cite>RFC 3921</cite>. Care must be taken regarding privacy lists, especially so that visibility/invisibility rules do not overwrite existing rules the user has set for the sake of security and privacy; for details, see the <link url='#impl'>Implementation Notes</link> section of this document.</p>
  <p>It is important to recognize that invisibility can be defeated without more advanced privacy lists than those defined above and an awareness of context on the part of a client. For example, if a user usually logs in as the same resource (e.g., "Home"), a contact can send an IQ request to that resource's full JID using &xep0012;, &xep0030;, &xep0090;, or &xep0092; and receive a reply, thus providing information that reveals the user's availability. In addition, <cite>Last Activity</cite> requests sent by a subscribed contact to the user's bare JID will normally reveal the user's availability as well. To help ensure that the user's invisibility cannot be defeated in this way, the user's client SHOULD add IQ blocking to the relevant privacy list. Finally, the user's client SHOULD NOT return "is-composing" events as defined in &xep0022; or &xep0085;.</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'>
  <p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this specification.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>The XML schema for the 'jabber:iq:privacy' namespace is defined in <cite>RFC 3921</cite>.</p>
</section1>
</xep>
