Add API method to retrieve the SID. Fixes #93

converse.js

@@ -138,6 +138,7 @@
         this.bosh_service_url = undefined; // The BOSH connection manager URL.
         this.cache_otr_key = false;
         this.debug = false;
+        this.expose_rid_and_sid = false;
         this.hide_muc_server = false;
         this.i18n = locales.en;
         this.prebind = false;
@@ -165,6 +166,7 @@
             'cache_otr_key',
             'connection',
             'debug',
+            'expose_rid_and_sid',
             'fullname',
             'hide_muc_server',
             'i18n',
@@ -3586,11 +3588,17 @@
             converse.initialize(settings, callback);
         },
         'getRID': function () {
-            if (typeof converse.connection !== "undefined") {
+            if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
                 return converse.connection.rid;
             }
             return null;
         },
+        'getSID': function () {
+            if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
+                return converse.connection.sid;
+            }
+            return null;
+        },
         'once': function(evt, handler) {
             converse.once(evt, handler);
         },

docs/CHANGES.rst

@@ -4,7 +4,8 @@ Changelog
 Unreleased
 ----------
 
-* Option to display a call button in the chatbox toolbar, to allow third-party libraries to provide a calling feature. [Aupajo]
+* #93 Add API methods exposing the RID and SID values. Can be disabled. [jcbrand]
+* #103 Option to display a call button in the chatbox toolbar, to allow third-party libraries to provide a calling feature. [Aupajo]
 * #108 Japanese Translations [mako09]
 * #111 OTR not working when using converse.js with prebinding. [jseidl, jcbrand]
 * #114 Hewbrew Translations [GreenLunar]

docs/html/_sources/index.txt

@@ -306,7 +306,6 @@ Facebook integration
     this myself. Feedback and patches from people who have succesfully done this
     will be appreciated.
 
-
 Converse.js uses `Strophe.js <http://strophe.im/strophejs>`_ to connect and
 communicate with the XMPP server. One nice thing about Strophe.js is that it
 can be extended via `plugins <http://github.com/strophe/strophejs-plugins>`_.
@@ -748,6 +747,14 @@ For each room on the server a query is made to fetch further details (e.g.
 features, number of occupants etc.), so on servers with many rooms this
 option will create lots of extra connection traffic.
 
+auto_reconnect
+--------------
+
+Default = ``true``
+
+Automatically reconnect to the XMPP server if the connection drops
+unexpectedly.
+
 auto_subscribe
 --------------
 
@@ -763,6 +770,30 @@ a middle man between HTTP and XMPP.
 
 See `here <http://metajack.im/2008/09/08/which-bosh-server-do-you-need>`_ for more information.
 
+cache_otr_key
+-------------
+
+Default = ``false``
+
+Let the `OTR (Off-the-record encryption) <https://otr.cypherpunks.ca>`_ private
+key be cached in your browser's session storage.
+
+The browser's session storage persists across page loads but is deleted once
+the tab or window is closed.
+
+If this option is set to ``false``, a new OTR private key will be generated
+for each page load. While more inconvenient, this is a much more secure option.
+
+This setting can only be used together with ``allow_otr = true``.
+
+
+.. Note :: 
+    A browser window's session storage is accessible by all javascript that
+    is served from the same domain. So if there is malicious javascript served by
+    the same server (or somehow injected via an attacker), then they will be able
+    to retrieve your private key and read your all the chat messages in your
+    current session. Previous sessions however cannot be decrypted.
+
 debug
 -----
 

docs/html/index.html

@@ -114,30 +114,32 @@
 <li><a class="reference internal" href="#allow-muc" id="id33">allow_muc</a></li>
 <li><a class="reference internal" href="#animate" id="id34">animate</a></li>
 <li><a class="reference internal" href="#auto-list-rooms" id="id35">auto_list_rooms</a></li>
-<li><a class="reference internal" href="#auto-subscribe" id="id36">auto_subscribe</a></li>
-<li><a class="reference internal" href="#bosh-service-url" id="id37">bosh_service_url</a></li>
-<li><a class="reference internal" href="#debug" id="id38">debug</a></li>
-<li><a class="reference internal" href="#fullname" id="id39">fullname</a></li>
-<li><a class="reference internal" href="#hide-muc-server" id="id40">hide_muc_server</a></li>
-<li><a class="reference internal" href="#i18n" id="id41">i18n</a></li>
-<li><a class="reference internal" href="#prebind" id="id42">prebind</a></li>
-<li><a class="reference internal" href="#show-controlbox-by-default" id="id43">show_controlbox_by_default</a></li>
-<li><a class="reference internal" href="#show-call-button" id="id44">show_call_button</a></li>
-<li><a class="reference internal" href="#show-only-online-users" id="id45">show_only_online_users</a></li>
-<li><a class="reference internal" href="#use-vcards" id="id46">use_vcards</a></li>
-<li><a class="reference internal" href="#xhr-custom-status" id="id47">xhr_custom_status</a></li>
-<li><a class="reference internal" href="#xhr-custom-status-url" id="id48">xhr_custom_status_url</a></li>
-<li><a class="reference internal" href="#xhr-user-search" id="id49">xhr_user_search</a></li>
-<li><a class="reference internal" href="#xhr-user-search-url" id="id50">xhr_user_search_url</a></li>
+<li><a class="reference internal" href="#auto-reconnect" id="id36">auto_reconnect</a></li>
+<li><a class="reference internal" href="#auto-subscribe" id="id37">auto_subscribe</a></li>
+<li><a class="reference internal" href="#bosh-service-url" id="id38">bosh_service_url</a></li>
+<li><a class="reference internal" href="#cache-otr-key" id="id39">cache_otr_key</a></li>
+<li><a class="reference internal" href="#debug" id="id40">debug</a></li>
+<li><a class="reference internal" href="#fullname" id="id41">fullname</a></li>
+<li><a class="reference internal" href="#hide-muc-server" id="id42">hide_muc_server</a></li>
+<li><a class="reference internal" href="#i18n" id="id43">i18n</a></li>
+<li><a class="reference internal" href="#prebind" id="id44">prebind</a></li>
+<li><a class="reference internal" href="#show-controlbox-by-default" id="id45">show_controlbox_by_default</a></li>
+<li><a class="reference internal" href="#show-call-button" id="id46">show_call_button</a></li>
+<li><a class="reference internal" href="#show-only-online-users" id="id47">show_only_online_users</a></li>
+<li><a class="reference internal" href="#use-vcards" id="id48">use_vcards</a></li>
+<li><a class="reference internal" href="#xhr-custom-status" id="id49">xhr_custom_status</a></li>
+<li><a class="reference internal" href="#xhr-custom-status-url" id="id50">xhr_custom_status_url</a></li>
+<li><a class="reference internal" href="#xhr-user-search" id="id51">xhr_user_search</a></li>
+<li><a class="reference internal" href="#xhr-user-search-url" id="id52">xhr_user_search_url</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference internal" href="#minification" id="id51">Minification</a><ul>
-<li><a class="reference internal" href="#minifying-javascript-and-css" id="id52">Minifying Javascript and CSS</a></li>
+<li><a class="reference internal" href="#minification" id="id53">Minification</a><ul>
+<li><a class="reference internal" href="#minifying-javascript-and-css" id="id54">Minifying Javascript and CSS</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#translations" id="id53">Translations</a></li>
+<li><a class="reference internal" href="#translations" id="id55">Translations</a></li>
 </ul>
 </div>
 <div class="section" id="quickstart-to-get-a-demo-up-and-running">
@@ -182,7 +184,7 @@ practical.</p>
 <p>You&#8217;ll most likely want to implement some kind of single-signon solution for
 your website, where users authenticate once in your website and then stay
 logged into their XMPP session upon page reload.</p>
-<p>For more info on this, read: <a href="#id54"><span class="problematic" id="id55">`Pre-binding and Single Session Support`_</span></a>.</p>
+<p>For more info on this, read: <a href="#id56"><span class="problematic" id="id57">`Pre-binding and Single Session Support`_</span></a>.</p>
 <p>You might also want to have more fine-grained control of what gets included in
 the minified Javascript file. Read <a class="reference internal" href="#configuration">Configuration</a> and <a class="reference internal" href="#minification">Minification</a> for more info on how to do
 that.</p>
@@ -729,41 +731,66 @@ multi-user chat, then a list of rooms on that server will be fetched.</p>
 features, number of occupants etc.), so on servers with many rooms this
 option will create lots of extra connection traffic.</p>
 </div>
+<div class="section" id="auto-reconnect">
+<h3><a class="toc-backref" href="#id36">auto_reconnect</a><a class="headerlink" href="#auto-reconnect" title="Permalink to this headline">¶</a></h3>
+<p>Default = <tt class="docutils literal"><span class="pre">true</span></tt></p>
+<p>Automatically reconnect to the XMPP server if the connection drops
+unexpectedly.</p>
+</div>
 <div class="section" id="auto-subscribe">
-<h3><a class="toc-backref" href="#id36">auto_subscribe</a><a class="headerlink" href="#auto-subscribe" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id37">auto_subscribe</a><a class="headerlink" href="#auto-subscribe" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>If true, the user will automatically subscribe back to any contact requests.</p>
 </div>
 <div class="section" id="bosh-service-url">
-<h3><a class="toc-backref" href="#id37">bosh_service_url</a><a class="headerlink" href="#bosh-service-url" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id38">bosh_service_url</a><a class="headerlink" href="#bosh-service-url" title="Permalink to this headline">¶</a></h3>
 <p>Connections to an XMPP server depend on a BOSH connection manager which acts as
 a middle man between HTTP and XMPP.</p>
 <p>See <a class="reference external" href="http://metajack.im/2008/09/08/which-bosh-server-do-you-need">here</a> for more information.</p>
 </div>
+<div class="section" id="cache-otr-key">
+<h3><a class="toc-backref" href="#id39">cache_otr_key</a><a class="headerlink" href="#cache-otr-key" title="Permalink to this headline">¶</a></h3>
+<p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
+<p>Let the <a class="reference external" href="https://otr.cypherpunks.ca">OTR (Off-the-record encryption)</a> private
+key be cached in your browser&#8217;s session storage.</p>
+<p>The browser&#8217;s session storage persists across page loads but is deleted once
+the tab or window is closed.</p>
+<p>If this option is set to <tt class="docutils literal"><span class="pre">false</span></tt>, a new OTR private key will be generated
+for each page load. While more inconvenient, this is a much more secure option.</p>
+<p>This setting can only be used together with <tt class="docutils literal"><span class="pre">allow_otr</span> <span class="pre">=</span> <span class="pre">true</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">A browser window&#8217;s session storage is accessible by all javascript that
+is served from the same domain. So if there is malicious javascript served by
+the same server (or somehow injected via an attacker), then they will be able
+to retrieve your private key and read your all the chat messages in your
+current session. Previous sessions however cannot be decrypted.</p>
+</div>
+</div>
 <div class="section" id="debug">
-<h3><a class="toc-backref" href="#id38">debug</a><a class="headerlink" href="#debug" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id40">debug</a><a class="headerlink" href="#debug" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>If set to true, debugging output will be logged to the browser console.</p>
 </div>
 <div class="section" id="fullname">
-<h3><a class="toc-backref" href="#id39">fullname</a><a class="headerlink" href="#fullname" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id41">fullname</a><a class="headerlink" href="#fullname" title="Permalink to this headline">¶</a></h3>
 <p>If you are using prebinding, can specify the fullname of the currently
 logged in user, otherwise the user&#8217;s vCard will be fetched.</p>
 </div>
 <div class="section" id="hide-muc-server">
-<h3><a class="toc-backref" href="#id40">hide_muc_server</a><a class="headerlink" href="#hide-muc-server" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id42">hide_muc_server</a><a class="headerlink" href="#hide-muc-server" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>Hide the <tt class="docutils literal"><span class="pre">server</span></tt> input field of the form inside the <tt class="docutils literal"><span class="pre">Room</span></tt> panel of the
 controlbox. Useful if you want to restrict users to a specific XMPP server of
 your choosing.</p>
 </div>
 <div class="section" id="i18n">
-<h3><a class="toc-backref" href="#id41">i18n</a><a class="headerlink" href="#i18n" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id43">i18n</a><a class="headerlink" href="#i18n" title="Permalink to this headline">¶</a></h3>
 <p>Specify the locale/language. The language must be in the <tt class="docutils literal"><span class="pre">locales</span></tt> object. Refer to
 <tt class="docutils literal"><span class="pre">./locale/locales.js</span></tt> to see which locales are supported.</p>
 </div>
 <div class="section" id="prebind">
-<h3><a class="toc-backref" href="#id42">prebind</a><a class="headerlink" href="#prebind" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id44">prebind</a><a class="headerlink" href="#prebind" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>Use this option when you want to attach to an existing XMPP connection that was
 already authenticated (usually on the backend before page load).</p>
@@ -776,7 +803,7 @@ values as <tt class="docutils literal"><span class="pre">jid</span></tt>, <tt cl
 <p>Additionally, you have to specify <tt class="docutils literal"><span class="pre">bosh_service_url</span></tt>.</p>
 </div>
 <div class="section" id="show-controlbox-by-default">
-<h3><a class="toc-backref" href="#id43">show_controlbox_by_default</a><a class="headerlink" href="#show-controlbox-by-default" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id45">show_controlbox_by_default</a><a class="headerlink" href="#show-controlbox-by-default" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>The &#8220;controlbox&#8221; refers to the special chatbox containing your contacts roster,
 status widget, chatrooms and other controls.</p>
@@ -786,7 +813,7 @@ the page with class <em>toggle-online-users</em>.</p>
 page load.</p>
 </div>
 <div class="section" id="show-call-button">
-<h3><a class="toc-backref" href="#id44">show_call_button</a><a class="headerlink" href="#show-call-button" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id46">show_call_button</a><a class="headerlink" href="#show-call-button" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>Enable to display a call button on the chatbox toolbar.</p>
 <p>When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.</p>
@@ -800,20 +827,20 @@ page load.</p>
 </div>
 </div>
 <div class="section" id="show-only-online-users">
-<h3><a class="toc-backref" href="#id45">show_only_online_users</a><a class="headerlink" href="#show-only-online-users" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id47">show_only_online_users</a><a class="headerlink" href="#show-only-online-users" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <p>If set to <tt class="docutils literal"><span class="pre">true</span></tt>, only online users will be shown in the contacts roster.
 Users with any other status (e.g. away, busy etc.) will not be shown.</p>
 </div>
 <div class="section" id="use-vcards">
-<h3><a class="toc-backref" href="#id46">use_vcards</a><a class="headerlink" href="#use-vcards" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id48">use_vcards</a><a class="headerlink" href="#use-vcards" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">true</span></tt></p>
 <p>Determines whether the XMPP server will be queried for roster contacts&#8217; VCards
 or not. VCards contain extra personal information such as your fullname and
 avatar image.</p>
 </div>
 <div class="section" id="xhr-custom-status">
-<h3><a class="toc-backref" href="#id47">xhr_custom_status</a><a class="headerlink" href="#xhr-custom-status" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id49">xhr_custom_status</a><a class="headerlink" href="#xhr-custom-status" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
@@ -823,7 +850,7 @@ avatar image.</p>
 remote server.</p>
 </div>
 <div class="section" id="xhr-custom-status-url">
-<h3><a class="toc-backref" href="#id48">xhr_custom_status_url</a><a class="headerlink" href="#xhr-custom-status-url" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id50">xhr_custom_status_url</a><a class="headerlink" href="#xhr-custom-status-url" title="Permalink to this headline">¶</a></h3>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
@@ -835,7 +862,7 @@ message will be made.</p>
 <p>The message itself is sent in the request under the key <tt class="docutils literal"><span class="pre">msg</span></tt>.</p>
 </div>
 <div class="section" id="xhr-user-search">
-<h3><a class="toc-backref" href="#id49">xhr_user_search</a><a class="headerlink" href="#xhr-user-search" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id51">xhr_user_search</a><a class="headerlink" href="#xhr-user-search" title="Permalink to this headline">¶</a></h3>
 <p>Default = <tt class="docutils literal"><span class="pre">false</span></tt></p>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
@@ -852,7 +879,7 @@ message will be made.</p>
 corresponds to a matched user and needs the keys <tt class="docutils literal"><span class="pre">id</span></tt> and <tt class="docutils literal"><span class="pre">fullname</span></tt>.</p>
 </div>
 <div class="section" id="xhr-user-search-url">
-<h3><a class="toc-backref" href="#id50">xhr_user_search_url</a><a class="headerlink" href="#xhr-user-search-url" title="Permalink to this headline">¶</a></h3>
+<h3><a class="toc-backref" href="#id52">xhr_user_search_url</a><a class="headerlink" href="#xhr-user-search-url" title="Permalink to this headline">¶</a></h3>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
@@ -865,9 +892,9 @@ The query string will be included in the request with <tt class="docutils litera
 </div>
 </div>
 <div class="section" id="minification">
-<h1><a class="toc-backref" href="#id51">Minification</a><a class="headerlink" href="#minification" title="Permalink to this headline">¶</a></h1>
+<h1><a class="toc-backref" href="#id53">Minification</a><a class="headerlink" href="#minification" title="Permalink to this headline">¶</a></h1>
 <div class="section" id="minifying-javascript-and-css">
-<h2><a class="toc-backref" href="#id52">Minifying Javascript and CSS</a><a class="headerlink" href="#minifying-javascript-and-css" title="Permalink to this headline">¶</a></h2>
+<h2><a class="toc-backref" href="#id54">Minifying Javascript and CSS</a><a class="headerlink" href="#minifying-javascript-and-css" title="Permalink to this headline">¶</a></h2>
 <p>Please make sure to read the section <a class="reference internal" href="#development">Development</a> and that you have installed
 all development dependencies (long story short, you can run <tt class="docutils literal"><span class="pre">npm</span> <span class="pre">install</span></tt>
 and then <tt class="docutils literal"><span class="pre">grunt</span> <span class="pre">fetch</span></tt>).</p>
@@ -884,7 +911,7 @@ using <a class="reference external" href="https://github.com/jrburke/almond">alm
 </div>
 </div>
 <div class="section" id="translations">
-<h1><a class="toc-backref" href="#id53">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline">¶</a></h1>
+<h1><a class="toc-backref" href="#id55">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline">¶</a></h1>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">Translations take up a lot of space and will bloat your minified file.

docs/source/index.rst

@@ -781,11 +781,19 @@ key be cached in your browser's session storage.
 The browser's session storage persists across page loads but is deleted once
 the tab or window is closed.
 
-If this options is set to ``false``, a new OTR private key will be generated
+If this option is set to ``false``, a new OTR private key will be generated
 for each page load. While more inconvenient, this is a much more secure option.
 
 This setting can only be used together with ``allow_otr = true``.
 
+
+.. Note :: 
+    A browser window's session storage is accessible by all javascript that
+    is served from the same domain. So if there is malicious javascript served by
+    the same server (or somehow injected via an attacker), then they will be able
+    to retrieve your private key and read your all the chat messages in your
+    current session. Previous sessions however cannot be decrypted.
+
 debug
 -----
 
@@ -793,6 +801,16 @@ Default = ``false``
 
 If set to true, debugging output will be logged to the browser console.
 
+expose_rid_and_sid
+------------------
+
+Allow the prebind tokens, RID (request ID) and SID (session ID), to be exposed
+globally via the API. This allows other scripts served on the same page to use
+these values. 
+
+*Beware*: a malicious script could use these tokens to assume your identity
+and inject fake chat messages.
+
 fullname
 --------
 

spec/converse.js

@@ -17,11 +17,31 @@
         it("has an API method for retrieving the next RID", $.proxy(function () {
             var old_connection = converse.connection;
             converse.connection.rid = '1234';
+            converse.expose_rid_and_sid = false;
+            expect(converse_api.getRID()).toBe(null);
+
+            converse.expose_rid_and_sid = true;
             expect(converse_api.getRID()).toBe('1234');
+
             converse.connection = undefined;
             expect(converse_api.getRID()).toBe(null);
             // Restore the connection
             converse.connection = old_connection;
         }, converse));
+
+        it("has an API method for retrieving the SID", $.proxy(function () {
+            var old_connection = converse.connection;
+            converse.connection.sid = '1234';
+            converse.expose_rid_and_sid = false;
+            expect(converse_api.getSID()).toBe(null);
+
+            converse.expose_rid_and_sid = true;
+            expect(converse_api.getSID()).toBe('1234');
+
+            converse.connection = undefined;
+            expect(converse_api.getSID()).toBe(null);
+            // Restore the connection
+            converse.connection = old_connection;
+        }, converse));
     }, converse, mock, utils));
 }));