hast-util-sanitize

Sanitize HAST.

Installation

npm install hast-util-sanitize

Usage

Dependencies:

var h = require('hastscript');
var u = require('unist-builder');
var sanitize = require('hast-util-sanitize');
var toHTML = require('hast-util-to-html');

Transform:

var tree = h('div', {
  onmouseover: 'alert("alpha")'
}, [
  h('a', {
    href: 'jAva script:alert("bravo")',
    onclick: 'alert("charlie")'
  }, 'delta'),
  u('text', '\n'),
  h('script', 'alert("charlie")'),
  u('text', '\n'),
  h('img', {src: 'x', onerror: 'alert("delta")'}),
  u('text', '\n'),
  h('iframe', {src: 'javascript:alert("echo")'}),
  u('text', '\n'),
  h('math', h('mi', {
    'xlink:href': 'data:x,<script>alert("foxtrot")</script>'
  }))
]);

Compile:

var unsanitized = toHTML(tree);
var sanitized = toHTML(sanitize(tree));

Unsanitized:

<div onmouseover="alert(&#x22;alpha&#x22;)"><a href="jAva script:alert(&#x22;bravo&#x22;)" onclick="alert(&#x22;charlie&#x22;)">delta</a>
<script>alert("charlie")</script>
<img src="x" onerror="alert(&#x22;delta&#x22;)">
<iframe src="javascript:alert(&#x22;echo&#x22;)"></iframe>
<math><mi xlink:href="data:x,&#x3C;script&#x3E;alert(&#x22;foxtrot&#x22;)&#x3C;/script&#x3E;"></mi></math></div>

Sanitized:

<div><a>delta</a>

<img src="x">

</div>

API

`sanitize(node[, schema])`

Sanitize the given HAST tree.

Parameters

node (HASTNode).
schema (Schema, optional).

Returns

HASTNode — A new node.

`Schema`

Configuration. If not given, defaults to GitHub style sanitation. If any top-level key isn’t given, it defaults to GH’s style too.

For a thorough sample, see the packages github.json.

To extend the standard schema with a few changes, clone github.json like so:

var h = require('hastscript');
var merge = require('deepmerge');
var gh = require('hast-util-sanitize/lib/github');

var schema = merge(gh, {attributes: {'*': ['className']}});

var tree = sanitize(h('div', {className: ['foo']}));
// `tree` still has `className`.

`attributes`

Map of tag-names to allowed attributes (Object.<Array.<string>>).

The special '*' key sets attributes allowed on all elements.

One special value, namely 'data*', can be used to allow all data properties.

"attributes": {
  "a": [
    "href"
  ],
  "img": [
    "src",
    "longDesc"
  ],
  // ...
  "*": [
    "abbr",
    "accept",
    "acceptCharset",
    // ...
    "vspace",
    "width",
    "itemProp"
  ]
}

`tagNames`

List of allowed tag-names (Array.<string>).

"tagNames": [
  "h1",
  "h2",
  "h3",
  // ...
  "strike",
  "summary",
  "details"
]

`protocols`

Map of protocols to support for attributes (Object.<Array.<string>>).

"protocols": {
  "href": [
    "http",
    "https",
    "mailto"
  ],
  // ...
  "longDesc": [
    "http",
    "https"
  ]
}

`ancestors`

Map of tag-names to their required ancestral elements (Object.<Array.<string>>).

"ancestors": {
  "li": [
    "ol",
    "ul"
  ],
  // ...
  "tr": [
    "table"
  ]
}

`clobber`

List of allowed attribute-names which can clobber (Array.<string>).

"clobber": [
  "name",
  "id"
]

`clobberPrefix`

Prefix (string) to use before potentially clobbering properties.

"clobberPrefix": "user-content"

`strip`

Tag-names to strip from the tree (Array.<string>).

By default, unsafe elements are replaced by their content. Some elements, should however be entirely stripped from the tree.

"strip": [
  "script"
]

mattcreager/hast-util-sanitize