isomorphic-dompurify

What is isomorphic-dompurify?

isomorphic-dompurify is an npm package that provides a way to sanitize HTML both in Node.js and in the browser. It is built on top of DOMPurify, a popular library for sanitizing HTML to prevent XSS (Cross-Site Scripting) attacks. The 'isomorphic' part means it can be used in both server-side and client-side environments seamlessly.

What are isomorphic-dompurify's main functionalities?

Sanitize HTML in Node.js

This feature allows you to sanitize HTML content in a Node.js environment using JSDOM to create a window object. The sanitized HTML is free from any potentially harmful scripts.

const createDOMPurify = require('isomorphic-dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);

const dirty = '<img src=x onerror=alert(1) />';
const clean = DOMPurify.sanitize(dirty);

console.log(clean); // Outputs: <img src="x">

Sanitize HTML in the Browser

This feature allows you to sanitize HTML content directly in the browser. The sanitized HTML is free from any potentially harmful scripts.

import createDOMPurify from 'isomorphic-dompurify';

const DOMPurify = createDOMPurify(window);

const dirty = '<img src=x onerror=alert(1) />';
const clean = DOMPurify.sanitize(dirty);

console.log(clean); // Outputs: <img src="x">

Custom Configuration

This feature allows you to customize the sanitization process by specifying allowed tags and attributes. In this example, only the 'a' tag and 'href' attribute are allowed, removing any potentially harmful scripts.

const createDOMPurify = require('isomorphic-dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);

const dirty = '<a href="javascript:alert(1)">Click me</a>';
const clean = DOMPurify.sanitize(dirty, { ALLOWED_TAGS: ['a'], ALLOWED_ATTR: ['href'] });

console.log(clean); // Outputs: <a>Click me</a>

Other packages similar to isomorphic-dompurify

dompurify

DOMPurify is the core library that isomorphic-dompurify is built upon. It provides the same sanitization capabilities but is not designed to work seamlessly in both Node.js and browser environments without additional setup.

sanitize-html

sanitize-html is another popular library for sanitizing HTML. It offers more configuration options and flexibility compared to isomorphic-dompurify but requires more setup to work in both Node.js and browser environments.

xss

xss is a library specifically designed to filter out XSS attacks. It provides a high level of customization and is very effective at preventing XSS, but it is not as straightforward to use in both Node.js and browser environments as isomorphic-dompurify.

README

Isomorphic DOMPurify

The library makes it possible to seamlessly use DOMPurify on server and client in the same way. It does nothing by itself except providing an isomorphic/universal wrapper around DOMPurify, so all credits go to DOMPurify authors and contributors.

DOMPurify - a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. DOMPurify works with a secure default, but offers a lot of configurability and hooks.

• DOMPurify Demo
• DOMPurify Documentation

Motivation

DOMPurify needs a DOM tree to base on, which is not available in Node by default. To work on the server side, we need a fake DOM to be created and supplied to DOMPurify. It means that DOMPurify initialization logic on the server is not the same as on the client.

This project was born with the idea of encapsulating DOMPurify initialization details and providing an easy way to import the library on both, server and client, for example in Next.js apps.

It was inspired by Isomorphic Unfetch.

Requirements

isomorphic-dompurify	Node.js	Environment
<=0.19.0	>=12	Server
>=0.20.0	>=14	Server
>=1.4.0	>=16	Server
>=1.10.0	>=18	Server

Installation

$ npm i isomorphic-dompurify

Updates

Please note that DOMPurify library doesn't follow Semantic Versioning, so we have to release every change as a minor version because we cannot be 100% sure whether new features are added to patch DOMPurify releases or not.

Usage

Import:

import DOMPurify from "isomorphic-dompurify";

Importing the entire module for the client/browser version is recommended.

Sanitize:

const clean = DOMPurify.sanitize(dirtyString);

or with config:

const clean = DOMPurify.sanitize(dirtyString, { USE_PROFILES: { html: true } });

Known Issues

1. Next.js and Remix are mistakenly trying to use the browser entry point on server, which causes the Window is not defined issue. #228 #214 https://github.com/vercel/next.js/discussions/58142
2. Can't resolve 'canvas' on Next.js serverless app
3. Starting from 0.16.0, there is a dependency conflict which causes ReferenceError: TextEncoder is not defined

License

DOMPurify - Apache 2.0 or MPL 2.0 © 2015 Mario Heiderich

Isomorphic DOMPurify - MIT License © 2020 Konstantin Komelin and contributors