Add documentation on security considerations

docs/source/development.rst

@@ -16,9 +16,6 @@ Converse.js itself composed of plugins, and exposes an API with which you can
 create and register your own plugins. This is the recommended way to customize
 or add new functionality to converse.js.
 
-Table of Contents
-=================
-
 .. toctree::
    :maxdepth: 2
 

docs/source/index.rst

@@ -48,6 +48,7 @@ Table of Contents
    setup
    configuration
    development
+   security
    theming
    translations
    troubleshooting

docs/source/security.rst

+.. raw:: html
+
+    <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
+ 
+=======================
+Security considerations
+=======================
+
+.. note::
+    Converse.js comes with no warranty of any kind and the authors are not liable for any damages.
+
+The data-structures of Converse.js encapsulate sensitive user data such as
+XMPP account details (in case of manual login) and personal conversations.
+
+In an environment where, besides Converse.js, other untrusted 3rd party scripts
+might also be running, it's important to guard against malicious or invasive
+access to user data and/or the API.
+
+The threat model
+================
+
+The following threat model is considered:
+
+Malicious 3rd party scripts served through compromised side-channels, such as ad-networks,
+which attempt to access Converse.js's API and/or data-structures in order to personify users
+or to pilfer their data.
+
+Mitigating measures
+===================
+
+As of version 3.0.0, the following actions were taken to harden Converse.js against attacks:
+
+Separate code/data into public and private parts
+------------------------------------------------
+
+1. Encapsulate Converse.js's data structures into a private closured object (named ``_converse``).
+2. Split the API into public and private parts.
+
+TODO: Merge ``converse-core.js`` and ``converse-api.js``, so that the ``_converse`` object can't be accessed outside of a plugin.
+
+Restrict access to private code/data
+------------------------------------
+
+3. Only plugins are allowed to access the private API and the closured ``_converse`` object.
+4. TODO: Whitelist plugins that have access to the private API and closured ``_converse`` object.
+5. TODO: Prevent the removal of registered plugins (otherwise the whitelist could be circumvented).
+6. TODO: Throw an unrecoverable error when multiple plugins try to register under the
+   same name (otherwise the whitelist could be circumvented).
+
+.. note::
+    Care should be taken when using a custom build of Converse.js where some
+    of the core plugins contained in the default build are omitted. In this case
+    the omitted plugins should also be removed from the whitelist, otherwise
+    malicious plugins could be registered under their names.
+
+Addititional measures
+=====================
+
+Besides the measures mentioned above, integrators and hosts can also take
+further security precautions.
+
+The most effective is to avoid serving untrusted 3rd party Javascript (e.g.
+advertisements and analytics).
+
+Another option is to forego the use of a global ``converse`` object (which
+exposes the public API) and instead to encapsulate it inside a private closure,
+in order to keep it inaccessible to other scripts.
+
+
+Other considerations
+====================
+
+Locally cached data
+-------------------
+
+Besides the "hot" data stored in Backbone models and collections, which are all
+encapsulated in the private ``_converse`` object, there is also the cached data
+stored in the browser's ``sessionStorage`` and ``localStorage`` stores.
+
+Examples of sensitive cached data are chat messages and the contacts roster,
+both which are in session storage, which means that the cache is cleared as
+soon as the last tab or window is closed. User credentials are not cached at
+all.
+
+Perhaps the ability to encrypt this cached data could be added in future
+versions of Converse.js, if there is sufficient demand for it.
+
+However to date no significant mitigation or hardening measures have been taken to
+secure this cached data.
+
+Therefore, the best defence as website host is to avoid serving Converse.js with
+untrusted 3rd party code, and the best defence as an end-user is to avoid chatting
+on websites that host untrusted 3rd party code. The most common examples of such
+being advertising and analytics scripts.
+