fix: allow configuring the XSS protection behavior

[dennissterzenbach]

I tried different ways on how to implement this and thought about the ideas previously discussed in the issue #846.
After some fiddling around I decided to keep things quite simple here, to get this off and rolling for everyone.

The basic concept includes the following:

• keep util.xss() usages unchanged
• allow to disable xss protection completely
• allow to control xss library's behavior using its public interfaces

Note: This still means, that the current default behavior will remain unchanged, but users will be able to gain control over it and have alternative options. See below.

To achieve things I basically did the following:

1. replaced the xss export in util.js with a dynamic getter using Object.defineProperty, because this allows to exchange the XSS protection algorithms behind it, while keeping that an internal detail

2. add configuration options to Timeline, which allow to:
   a) disable XSS protection completely and
   b) optionally also change the xss library's behavior using its XSS.IFilterXSSOptions

3. hand these configuration options to a setup function at instanciation time, to define how that particular Timeline instance will behave with regards to XSS filtering

4. if someone disabled the xss protection, that makes Timelien log a warning, because... the protection is in for good reason, so why should you disable it completely (other than you know what you are doing)!?

The "disabled" must be set explictly, otherwise the xss protection will remain in place.
The protection also defaults to the current state, using the xss filter with no option at all.

This solution might not be perfect, because the dynamic getter could impact performance; also this solution does not account for treating XSS differently for loading screen, item contents, groups etc.

However I think this is at least a good intermediate solution. This might also be worth shipping, because it is a relief for both: us and the people out there, as they now have the option to get control over the XSS protection.

Here's the examples I used to verify its behavior:

With Options set to:

  ...
  xss: {
    disabled: false,
    filterOptions: {
      whiteList: { p: ['class', 'data-from-template'], div: 'class' },
    },
  },

CASE 1:

  template: function (item, element, data) {
    return `<div class="not-xss-filtered-html" data-from-template="yes">${item.content}</div>`;
  }

output keeps the element, but only the class attribute passes through:

<div class="not-xss-filtered-html">This is the item.content</div>

CASE 2:

  template: function (item, element, data) {
    return `<p class="not-xss-filtered-html" data-from-template="yes">${item.content}</p>`;
  }

output keeps element and both attributes:

<p class="not-xss-filtered-html" data-from-template="yes">This is the item.content</p>

CASE 3:

  template: function (item, element, data) {
    return `<span class="not-xss-filtered-html" data-from-template="yes">${item.content}</span>`;
  }

output is esacped, because span is no valid element:

<span class="not-xss-filtered-html" data-from-template="yes">This is the item.content</span>

With Options set to:

  ...
  xss: {
    disabled: true,
  },

The startup of Timeline produces a console warning:

You disabled XSS protection for vis-Timeline. I sure hope you know what you're doing!

[yotamberk]

Wow! Thanks for the PR. this is definitely better solution than the current application.
Thanks for the contribution of code!

[vis-bot]

🎉 This PR is included in version 7.4.7 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[jladbury]

Adding the xss option via setOptions does not seem to work. Is that intentional?

Background: hitherto I have initialised a timeline like this:
timeline = new vis.Timeline(document.getElementById(presentation.name))
timeline.setOptions(visOptions);
timeline.setItems(data.items);

Doing this, even when xss was set in visOptions, it did not take effect.
I can circumvent this by initialising the timeline as follows:
timeline = new vis.Timeline(document.getElementById(presentation.name),{},visOptions);

[melloware]

Also nice to have is we should have a disableWarnings boolean option to turn off all warnings generated by the Timeline. If I want to disable XSS entirely i don't want my user's panicking that they see the alert You disabled XSS protection for vis-Timeline. I sure hope you know what you're doing! but I know exactly why I am disabling it.

[dennissterzenbach]

Yes, it is intended to only accept manipulating the xss protection upon instantiation.
This is to avoid side effects you could cause by overriding the protection via setOptions.

[daattali]

The documentation for the xss feature does not mention that it can only be set during initialization. It should be mentioned.