rehype-sanitize

The default configuration of rehype-sanitize is safe, but improper usage can lead to Cross-Site Scripting (XSS) attacks.

Crucial Rule: Always use rehype-sanitize after the last potentially unsafe operation. Any plugin or transformation executed after rehype-sanitize is not covered by the sanitization and could introduce unsafe HTML.

DOM clobbering is an attack where malicious HTML uses id or name attributes to overshadow properties in the global window scope. rehype-sanitize mitigates this by prefixing every id and name attribute with 'user-content-'.

Note that this will break existing links to those IDs. To fix this, you should either rewrite your links to include the prefix or use a client-side script to intercept hash changes and scroll to the prefixed elements (similar to how GitHub handles it).

// Example of how rehype-sanitize changes attributes
// Input:
// <a name="old"></a>
// <h1 id="current">Current</h1>

// Output after .use(rehypeSanitize):
// <a name="user-content-old"></a>
// <h1 id="user-content-current">Current</h1>

rehype-sanitize is an ESM-only package. Use the following commands depending on your environment:

Node.js (version 16+):

npm install rehype-sanitize

Deno (via esm.sh):

import rehypeSanitize from 'https://esm.sh/rehype-sanitize@6'

Browsers (via esm.sh):

<script type="module">
  import rehypeSanitize from 'https://esm.sh/rehype-sanitize@6?bundle'
</script>

To sanitize HTML, integrate rehypeSanitize into a unified pipeline. The plugin works by transforming a hast (HTML Abstract Syntax Tree) and dropping any elements or attributes not explicitly allowed by the schema. By default, it uses a schema that follows GitHub's sanitation style.

Example workflow using rehype-parse, rehype-sanitize, and rehype-stringify:

import rehypeParse from 'rehype-parse'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeSanitize)
  .use(rehypeStringify)
  .process(await read('index.html'))

console.log(String(file))

You can pass a custom schema to rehypeSanitize to define which nodes and properties are allowed. This schema follows the Schema definition from hast-util-sanitize.

Note: This is an advanced configuration that requires knowledge of syntax trees.

// Usage pattern
.use(rehypeSanitize, customSchema)

Node.js Compatibility

rehype-sanitize@^6 is compatible with Node.js 16.

Plugin Compatibility

This plugin is compatible with:

• rehype-parse version 3+
• rehype-stringify version 3+
• rehype version 5+
• unified version 6+

The package exports the following primary members:

• defaultSchema: The default configuration schema that follows GitHub-style sanitation.
• rehypeSanitize: The main plugin function used in unified().use().

The default export of rehype-sanitize is a plugin for unified (and by extension rehype). You can use it by calling .use(rehypeSanitize) on your unified instance. You can optionally provide a custom schema to override the default sanitization rules.

import { unified } from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import rehypeSanitize from 'rehype-sanitize'

const processor = unified()
  .use(rehypeParse)
  .use(rehypeSanitize) // Uses defaultSchema
  .use(rehypeStringify)

const html = '<img src=x onerror=alert(1)>'
const result = await processor.process(html)
console.log(result.toString()) // Output will be sanitized

You can import defaultSchema directly from rehype-sanitize. This schema is exported from hast-util-sanitize and defines the default allowed elements, attributes, and protocols for sanitization.

import { defaultSchema } from 'rehype-sanitize'