hast-util-sanitize
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechathast utility to make trees safe.
Contents
* [`sanitize(tree[, schema])`](#sanitizetree-schema)
* [`Schema`](#schema)
What is this?
This package is a utility that can make a tree that potentially contains dangerous user content safe for use. It defaults to what GitHub does to clean unsafe markup, but you can change that.When should I use this?
This package is needed whenever you deal with potentially dangerous user content.The plugin
rehype-sanitize
rehype-sanitize wraps this utility to also
sanitize HTML at a higher-level (easier) abstraction.Install
This package is ESM onlyesm. In Node.js (version 14.14+, 16.0+), install with npm:npm install hast-util-sanitize
In Deno with
esm.sh
esmsh:import {sanitize} from 'https://esm.sh/hast-util-sanitize@4'
In browsers with
esm.sh
esmsh:<script type="module">
import {sanitize} from 'https://esm.sh/hast-util-sanitize@4?bundle'
</script>
Use
import {u} from 'unist-builder'
import {h} from 'hastscript'
import {sanitize} from 'hast-util-sanitize'
import {toHtml} from 'hast-util-to-html'
const 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>'}))
])
const unsanitized = toHtml(tree)
const sanitized = toHtml(sanitize(tree))
console.log(unsanitized)
console.log(sanitized)
Unsanitized:
<div onmouseover="alert("alpha")"><a href="jAva script:alert("bravo")" onclick="alert("charlie")">delta</a>
<script>alert("charlie")</script>
<img src="x" onerror="alert("delta")">
<iframe src="javascript:alert("echo")"></iframe>
<math><mi xlink:href="data:x,<script>alert("foxtrot")</script>"></mi></math></div>
Sanitized:
<div><a>delta</a>
<img src="x">
</div>
API
This package exports the identifierssanitize
and defaultSchema
.
There is no default export.sanitize(tree[, schema])
Sanitize a tree.Parameters
tree
(Node
node) — treetree to sanitizeschema
(Schema
schema, optional) — schema defining how to sanitize
Returns
A new, sanitized, tree (Node
node).Schema
Sanitation schema that defines if and how nodes and properties should be
cleaned.
The default schema is exported as defaultSchema
, which defaults to GitHub
style sanitation.
If any top-level key isn’t given, it defaults to GitHub’s style too.For a thorough sample, see the code for
defaultSchema
default-schema.To extend the standard schema with a few changes, clone
defaultSchema
like so:import {h} from 'hastscript'
import deepmerge from 'deepmerge' // You can use `structuredClone` in modern JS.
import {sanitize, defaultSchema} from 'hast-util-sanitize'
const schema = deepmerge(defaultSchema, {attributes: {'*': ['className']}})
const tree = sanitize(h('div', {className: ['foo']}), schema)
// `tree` still has `className`.
console.log(tree)
// {
// type: 'element',
// tagName: 'div',
// properties: {className: ['foo']},
// children: []
// }
attributes
Map of tag names to allowed property namesname
(Record<string, Array<string>>
).The special
'*'
key defines property namesname allowed on all
elementselement.One special value,
'data*'
, can be used to allow all data
properties.attributes: {
a: ['href'],
img: ['src', 'longDesc'],
// …
'*': [
'abbr',
'accept',
'acceptCharset',
// …
'vSpace',
'width',
'itemProp'
]
}
Instead of a single string (such as
type
), which allows any property
valuevalue of that property namename, it’s also possible to provide
an array (such as ['type', 'checkbox']
or ['className', /^hljs-/]
),
where the first entry is the property name, and all other entries are
property values allowed (or regular expressions that are tested with values).
This is how the default GitHub schema allows only disabled checkbox inputs:attributes: {
// …
input: [
['type', 'checkbox'],
['disabled', true]
]
// …
}
This also plays well with properties that accept space- or comma-separated values, such as
class
.
Say you wanted to allow certain classes on span
elements for syntax
highlighting, that can be done like this:// …
span: [
['className', 'token', 'number', 'operator']
]
// …
required
Map of tag names to required property namesname and their default
property valuevalue (Record<string, Record<string, *>>
).
If the defined keys do not exist in an elementelement’s
propertiesproperties, they are added and set to the specified value.Note that properties are first checked based on the schema at
attributes
,
so properties could be removed by that step and then added again through
required
.required: {
input: {type: 'checkbox', disabled: true}
}
tagNames
List of allowed tag names (Array<string>
).tagNames: [
'h1',
'h2',
'h3',
// …
'strike',
'summary',
'details'
]
protocols
Map of protocols to allow in property valuesvalue
(Record<string, Array<string>>
).protocols: {
href: ['http', 'https', 'mailto'],
// …
longDesc: ['http', 'https']
}
ancestors
Map of tag names to their required ancestorancestor elementselement
(Record<string, Array<string>>
).ancestors: {
li: ['ol', 'ul'],
// …
tr: ['table']
}
clobber
List of allowed property namesname which can clobber (Array<string>
).clobber: ['name', 'id']
clobberPrefix
Prefix to use before potentially clobbering property namesname (string
).clobberPrefix: 'user-content-'
strip
Names of elementselement to strip from the treetree
(Array<string>
).By default, unsafe elements are replaced by their childrenchild. Some elements, should however be entirely stripped from the tree.
strip: ['script']
allowComments
Whether to allow commentscomment (boolean
, default: false
).allowComments: true
allowDoctypes
Whether to allow doctypesdoctype (boolean
, default: false
).allowDoctypes: true
Types
This package is fully typed with TypeScript. It exports the additional typeSchema
.Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.Security
By default,hast-util-sanitize
will make everything safe to use.
But when used incorrectly, deviating from the defaults can open you up to a
cross-site scripting (XSS)xss attack.Use
hast-util-sanitize
after the last unsafe thing: everything after it could
be unsafe (but is fine if you do trust it).Related
— rehype plugin
Contribute
Seecontributing.md
contributing in syntax-tree/.github
health for
ways to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.