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/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));
 }));