Registry / auth-security / hast-util-sanitize

hast-util-sanitize

library5.0.2jsnpmunverified

hast-util-sanitize is a JavaScript utility designed to make HAST (Hypertext Abstract Syntax Tree) nodes safe by removing potentially dangerous user-generated content, primarily to prevent Cross-Site Scripting (XSS) vulnerabilities. Currently at version 5.0.2, the package is actively maintained as part of the unified ecosystem, with a steady release cadence addressing features and breaking changes. It provides a robust, extensible schema, defaulting to GitHub's sanitation rules, allowing developers to customize allowed elements, attributes, and attribute values. This makes it a crucial tool for applications handling untrusted HTML input, either directly or through higher-level wrappers like rehype-sanitize. Its focus on direct HAST manipulation allows for fine-grained control over the sanitization process.

auth-security serialization web-framework

npm install hast-util-sanitize

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-SANITIZE

hast-util-sanitize

auth-securityjavascriptv5.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sanitize

✓ import { sanitize } from 'hast-util-sanitize'

✗ const sanitize = require('hast-util-sanitize').sanitize

The package is ESM-only since v5.0.0. CommonJS `require` will fail.

defaultSchema

✓ import { defaultSchema } from 'hast-util-sanitize'

✗ const defaultSchema = require('hast-util-sanitize').defaultSchema

The package is ESM-only since v5.0.0. CommonJS `require` will fail.

Schema (type)

✓ import type { Schema } from 'hast-util-sanitize'

Importing types is standard TypeScript practice. The `type` keyword is recommended for clarity.

Demonstrates sanitizing a HAST tree containing various XSS attack vectors using the default GitHub-style schema, showing the transformation from unsafe to safe HTML.

import {h} from 'hastscript'; import {sanitize} from 'hast-util-sanitize'; import {toHtml} from 'hast-util-to-html'; import {u} from 'unist-builder'; const unsafe = 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>'})) ]); // Sanitize the unsafe HAST tree const safe = sanitize(unsafe); console.log('Unsafe HTML:'); console.log(toHtml(unsafe)); console.log('\nSafe HTML:'); console.log(toHtml(safe));

Debug

Known issues

breakingVersion 5.0.0 changed the package to be ESM-only and requires Node.js 16 or higher. Direct CommonJS `require()` statements will no longer work.

fix

Migrate your project to use ES modules (`import`/`export`) or ensure you are in an environment that transpiles ESM correctly. Update your Node.js version to 16+.

affects: >=5.0.0

breakingWith version 5.0.0, the package now uses the `exports` field in `package.json`. This means direct imports of internal paths (e.g., `hast-util-sanitize/lib/some-internal-module`) are no longer supported and will lead to errors.

fix

Always use the public API paths, typically `hast-util-sanitize` for named exports, and avoid relying on internal file structures.

affects: >=5.0.0

breakingVersion 3.0.0 introduced TypeScript types. While beneficial, this was a potentially breaking change if your project or its dependents relied on implicit type behavior or conflicting type definitions.

fix

Ensure your TypeScript configuration is compatible, and review any custom type declarations that might now conflict with the official types.

affects: >=3.0.0

gotchaIn version 5.0.1, the default schema was updated to remove `rel` and `target` attributes from certain elements, which might affect link behavior if you were implicitly relying on these attributes being preserved by default.

fix

If `rel` or `target` attributes are essential for specific elements (e.g., `a` tags), you must explicitly add them back to your custom schema by extending `defaultSchema`.

affects: >=5.0.1

gotchaWhile `hast-util-sanitize` provides robust XSS protection with its default (GitHub-like) schema, custom schemas can reintroduce vulnerabilities if not carefully constructed. Always audit your custom schema against known attack vectors.

fix

Thoroughly review any modifications made to `defaultSchema` or entirely custom schemas to ensure they do not permit dangerous elements, attributes, or protocols.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/hast-util-sanitize/index.js from /path/to/your/file.js not supported. hast-util-sanitize is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" and which has no 'exports' field. Instead, change the require of index.js in /path/to/your/file.js to a dynamic import() which is available in all CommonJS modules.

Attempting to `require()` hast-util-sanitize in a CommonJS module or environment when the package is ESM-only.

fix

Refactor your code to use `import { sanitize } from 'hast-util-sanitize';` in an ES module context (e.g., by setting `"type": "module"` in your `package.json` or using `.mjs` files). If stuck in CommonJS, consider dynamic import: `const { sanitize } = await import('hast-util-sanitize');`.

Cannot find module 'hast-util-sanitize/lib/some-internal-api' or similar path.

Attempting to import from an internal, non-public path within the package, which is disallowed due to the `exports` field in `package.json` since v5.0.0.

fix

Always import symbols directly from the main package entry point: `import { someExport } from 'hast-util-sanitize';`. Do not rely on deep imports into `lib/` or other internal directories.

Upgrade

Version history

5.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/syntax-tree/hast-util-sanitize ↗

packagehttps://www.npmjs.com/package/hast-util-sanitize ↗