Przeglądaj źródła

Document white- and blacklisting of plugins

JC Brand 8 lat temu
rodzic
commit
2819148669
4 zmienionych plików z 257 dodań i 8 usunięć
  1. 6 0
      demo/embedded.html
  2. 129 0
      demo/index.html
  3. 12 4
      docs/CHANGES.md
  4. 110 4
      docs/source/configuration.rst

+ 6 - 0
demo/embedded.html

@@ -69,6 +69,12 @@
             auto_join_rooms: [
                 'anonymous@conference.nomnom.im',
             ],
+            blacklisted_plugins: [
+                'converse-controlbox',
+                'converse-dragresize',
+                'converse-minimize',
+                'converse-vcard'
+            ],
             notify_all_room_messages: [
                 'anonymous@conference.nomnom.im',
             ],

+ 129 - 0
demo/index.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Converse.js</title>
+    <meta charset="utf-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Converse.js: A free chat client for your website" />
+    <meta name="author" content="JC Brand" />
+    <meta name="keywords" content="xmpp chat webchat converse.js" />
+    <link rel="shortcut icon" type="image/ico" href="css/images/favicon.ico"/>
+    <link type="text/css" rel="stylesheet" media="screen" href="/node_modules/bootstrap/dist/css/bootstrap.min.css" />
+    <link type="text/css" rel="stylesheet" media="screen" href="/node_modules/font-awesome/css/font-awesome.min.css" />
+    <link type="text/css" rel="stylesheet" media="screen" href="/css/theme.min.css" />
+    <link type="text/css" rel="stylesheet" media="screen" href="/css/converse.min.css" />
+    <script type="text/javascript" src="analytics.js"></script>
+    <noscript><p><img src="//stats.opkode.com/piwik.php?idsite=1" style="border:0;" alt="" /></p></noscript>
+    <![if gte IE 9]>
+	<script src="/dist/converse.min.js"></script>
+    <![endif]>
+</head>
+
+<body id="page-top" data-spy="scroll" data-target=".navbar-custom">
+
+    <nav class="navbar navbar-custom navbar-fixed-top" role="navigation">
+        <div class="container">
+            <div class="navbar-header page-scroll">
+                <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse">
+                    <i class="fa fa-bars"></i>
+                </button>
+                <a class="navbar-brand" href="#page-top">
+                    <i class="fa fa-play-circle"></i>  <span class="light">Home</span>
+                </a>
+            </div>
+
+            <!-- Collect the nav links, forms, and other content for toggling -->
+            <div class="collapse navbar-collapse navbar-right navbar-main-collapse">
+                <ul class="nav navbar-nav">
+                    <!-- Hidden li included to remove active class from about link when scrolled up past about section -->
+                    <li class="hidden">
+                        <a href="#page-top"></a>
+                    </li>
+                    <li class="page-scroll">
+                        <a href="#about">About</a>
+                    </li>
+                    <li class="page-scroll">
+                        <a href="#features">Features</a>
+                    </li>
+                    <li class="page-scroll">
+                        <a href="#contact">Contact</a>
+                    </li>
+                    <li>
+                        <a href="/docs/html/manual.html">User Manual</a>
+                    </li>
+                    <li>
+                        <a href="/docs/html/index.html">Documentation</a>
+                    </li>
+                    <li>
+                        <a href="https://github.com/jcbrand/converse.js/releases" class="button" target="_blank">Download</a>
+                    </li>
+                </ul>
+            </div>
+            <!-- /.navbar-collapse -->
+        </div>
+        <!-- /.container -->
+    </nav>
+
+    <section class="intro" class="container">
+        <div class="row">
+            <h1 class="brand-heading"><i class="icon-conversejs"></i> Converse.js</h1>
+            <div class="col-md-8 col-md-offset-2">
+                <p class="intro-text">Demos:</p>
+                <p class="intro-text">
+                    <ul>
+                        <li><a href="/demo/anonymous.html">Anonymous login</a></li>
+                        <li><a href="/demo/embedded.html">A single MUC chatroom embedded into the page</a></li>
+                        <li><a href="/demo/without_bundled_dependencies.html">With dependencies loaded externally as &lt;script&gt; tags</a></li>
+                    </ul>
+                </p>
+            </div>
+        </div>
+    </section>
+</body>
+
+<script>
+    require(['converse'], function (converse) {
+        (function () {
+            /* XXX: This function initializes jquery.easing for the https://conversejs.org
+            * website. This code is only useful in the context of the converse.js
+            * website and converse.js itself is NOT dependent on it.
+            */
+            var $ = converse.env.jQuery;
+            $.extend( $.easing, {
+                easeInOutExpo: function (x, t, b, c, d) {
+                    if (t==0) return b;
+                    if (t==d) return b+c;
+                    if ((t/=d/2) < 1) return c/2 * Math.pow(2, 10 * (t - 1)) + b;
+                    return c/2 * (-Math.pow(2, -10 * --t) + 2) + b;
+                },
+            });
+
+            $(window).scroll(function() {
+                if ($(".navbar").offset().top > 50) {
+                    $(".navbar-fixed-top").addClass("top-nav-collapse");
+                } else {
+                    $(".navbar-fixed-top").removeClass("top-nav-collapse");
+                }
+            });
+            //jQuery for page scrolling feature - requires jQuery Easing plugin
+            $('.page-scroll a').bind('click', function(event) {
+                var $anchor = $(this);
+                $('html, body').stop().animate({
+                    scrollTop: $($anchor.attr('href')).offset().top
+                }, 700, 'easeInOutExpo');
+                event.preventDefault();
+            });
+        })();
+        converse.initialize({
+            // Please use this connection manager only for testing purposes
+            bosh_service_url: 'https://conversejs.org/http-bind/',
+            keepalive: true,
+            message_carbons: true,
+            play_sounds: true,
+            roster_groups: true,
+            show_controlbox_by_default: true,
+        });
+    });
+</script>
+</html>

+ 12 - 4
docs/CHANGES.md

@@ -4,21 +4,29 @@
 - Case insensitive matching of moderation commands. [jcbrand]
 - Add `/subject` as alias to `/topic` [jcbrand]
 - `allow_chat_pending_contacts` now defaults to `true` [jcbrand]
-- *Breaking change*: Callbacks for `converse.on` now no longer receive an event
-  object as first parameter. [jcbrand]
+- *Breaking change*: Callbacks for `converse.on` now no longer receive an
+  event object as first parameter. [jcbrand]
 - Use lodash instead of underscore.js [jcbrand]
 - Improved roster filter UX. [jcbrand]
 - Render the login form again upon authfail. [jcbrand]
-- New promises API: [waitUntil](https://conversejs.org/docs/html/developer_api.html#waituntil) [jcbrand]
+- New promises API: [waitUntil](https://conversejs.org/docs/html/developer_api.html#waituntil)
+  [jcbrand]
 - New configuration setting:
   [show_chatstate_notifications](https://conversejs.org/docs/html/configuration.html#show-chatstate-notifications)
   [jcbrand]
+- New configuration setting:
+  [whitelisted_plugins](https://conversejs.org/docs/html/configuration.html#whitelisted-plugins)
+  [jcbrand]
+- New configuration setting:
+  [blacklisted_plugins](https://conversejs.org/docs/html/configuration.html#blacklisted-plugins)
+  [jcbrand]
 - The API now no longer returns wrapped chatboxes (or rooms) but instead a
   Backbone.View object. This means the API of the returned object has changed.
   You're still able to do everything from before but now also much more.
   [jcbrand]
 - Allow JIDs not on the roster to be invited to a chatroom. [jcbrand]
-- Bugfix. 'TypeError: this.sendConfiguration(...).then is not a function' when an instant room is created. [jcbrand]
+- Bugfix. 'TypeError: this.sendConfiguration(...).then is not a function' when
+  an instant room is created. [jcbrand]
 - Ensure consistent behavior from `show_controlbox_by_default` [jcbrand]
 - #694 The `notification_option` wasn't being used consistently. [jcbrand]
 - #770 Allow setting contact attrs on chats.open [Ape]

+ 110 - 4
docs/source/configuration.rst

@@ -330,7 +330,7 @@ You can either specify a simple list of room JIDs, in which case your nickname
 will be taken from your JID, or you can specify a list of maps, where each map
 specifies the room's JID and the nickname that should be used.
 
-For example:
+For example::
 
     `[{'jid': 'room@example.org', 'nick': 'WizardKing69' }]`
 
@@ -411,7 +411,9 @@ accepts, refer to the
 
 As an example, suppose you want to restrict the supported SASL authentication
 mechanisms, then you'd pass in the ``mechanisms`` as a ``connection_options``
-``key:value`` pair::
+``key:value`` pair:
+
+.. code-block:: javascript 
 
         converse.initialize({
             connection_options: {
@@ -582,7 +584,8 @@ state. The only defined states are:
 * dnd -- The entity or resource is busy (dnd = "Do Not Disturb").
 * xa -- The entity or resource is away for an extended period (xa = "eXtended Away").
 
-Read the [relevant section in the XMPP spec](https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show) for more info.
+Read the `relevant section in the XMPP spec <https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show>`_
+for more info.
 
 What used to happen in converse.js when the `offline` state was chosen, is
 that a presence stanza with a `type` of `unavailable` was sent out.
@@ -1068,7 +1071,9 @@ Allows you to show or hide buttons on the chat boxes' toolbars.
 
 * *call*:
     Provides a button with a picture of a telephone on it.
-    When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.::
+    When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.
+
+    .. code-block:: javascript
 
         converse.listen.on('callButtonClicked', function(data) {
             console.log('Strophe connection is', data.connection);
@@ -1109,6 +1114,107 @@ support.
 .. note::
     Converse.js does not yet support "keepalive" with websockets.
 
+blacklisted_plugins
+-------------------
+
+* Default: ``[]``
+
+A list of plugin names that are blacklisted and will therefore not be
+initialized once ``converse.initialize`` is called, even if the same plugin is
+whitelisted.
+
+From Converse.js 3.0 onwards most of the API is available only to plugins and
+all plugins need to be whitelisted first.
+
+The usecase for blacklisting is generally to disable removed core plugins
+(which are automatically whitelisted) to prevent other (potentially malicious)
+plugins from registering themselves under those names.
+
+The core, and by default whitelisted, plugins are::
+
+    converse-bookmarks
+    converse-chatview
+    converse-controlbox
+    converse-core
+    converse-dragresize
+    converse-headline
+    converse-mam
+    converse-minimize
+    converse-muc
+    converse-notification
+    converse-otr
+    converse-ping
+    converse-register
+    converse-rosterview
+    converse-vcard
+
+An example from `the embedded room demo <https://conversejs.org/demo/embedded.html>`_
+
+.. code-block:: javascript 
+
+    require(['converse-core', 'converse-muc-embedded'], function (converse) {
+        converse.initialize({
+            // other settings removed for brevity
+            blacklisted_plugins: [
+                'converse-controlbox',
+                'converse-dragresize',
+                'converse-minimize',
+                'converse-vcard'
+            ],
+        });
+    });
+
+
+whitelisted_plugins
+-------------------
+
+* Default: ``[]``
+
+A list of plugin names that are whitelisted and will therefore be
+initialized once ``converse.initialize`` is called.
+
+From Converse.js 3.0 onwards most of the API is available only to plugins and
+all plugins need to be whitelisted first.
+
+This is done to prevent malicious scripts from using the API to trick users or
+to read their conversations.
+
+By default all the core plugins are already whitelisted.
+
+These are::
+
+    converse-bookmarks
+    converse-chatview
+    converse-controlbox
+    converse-core
+    converse-dragresize
+    converse-headline
+    converse-mam
+    converse-minimize
+    converse-muc
+    converse-notification
+    converse-otr
+    converse-ping
+    converse-register
+    converse-rosterview
+    converse-vcard
+
+If you are using a custom build which excludes some core plugins, then you 
+should blacklist them so that malicious scripts can't register their own
+plugins under those names. See `blacklisted_plugins`_ for more info.
+
+An example from `the embedded room demo <https://conversejs.org/demo/embedded.html>`_
+
+.. code-block:: javascript 
+
+    require(['converse-core', 'converse-muc-embedded'], function (converse) {
+        converse.initialize({
+            // other settings removed for brevity
+            whitelisted_plugins: ['converse-muc-embedded']
+        });
+    });
+
+
 xhr_custom_status
 -----------------