@benedictleejh/nuxt-sanitise-html

Nuxt Sanitise HTML

Nuxt module for sanitising HTML, as a safe replacement for using v-html, protecting against XSS attacks through sanitising HTML inputs.

• ✨  Release Notes

Features

• Adds v-sanitise-html directive as a safe replacement for v-html
• Supports sanitisation profiles to allow configuration as needed for different use cases
• Supports configuring hooks for advanced sanitisation needs

Setup

Install the module from NPM using your package manager of choice, e.g. pnpm

pnpm add -D @benedictleejh/nuxt-sanitise-html

Then add the module to your Nuxt config file:

export default defineNuxtConfig({
  modules: ['@benedictleejh/nuxt-sanitise-html'],
})

Usage

Basic

The module works without any configuration needed. Just use v-sanitise-html instead of v-html when you need to sanitise HTML input. This uses DOMPurify's default configuration for sanitisation.

<script setup lang="ts">
const xssAttack = `<p>Hello<script>alert('This is an XSS attack!')</` + `script> World</p>`
</script>

<template>
  <div v-sanitise-html="xssAttack" />
</template>

The output HTML would be:

<p>HelloWorld</p>

You can setup different sanitisaton configurations (profiles) in app config (app.config.ts) using the sanitiseHtml key.

export default defineAppConfig({
  sanitiseHtml: {
    profiles: {
      profileName: {
        config: {
          allowedTags: [
            'h1'
          ]
        }
      }
    }
  }
})

The profile names can be used as arguments to v-sanitise-html to use that profile instead of the default profile.

<script setup lang="ts">
const xssAttack = `<p>Hello<script>alert('This is an XSS attack!')</` + `script> World</p>`
</script>

<template>
  <div v-sanitise-html:profileName="xssAttack" />
</template>

You can also override the profile used when calling v-sanitise-html without arguments by simply setting up a profile with the name default.

export default defineAppConfig({
  sanitiseHtml: {
    profiles: {
      // This profile is now used when using `v-sanitise-html` without arguments
      default: {
        config: {
          allowedTags: [
            'h1'
          ]
        }
      }
    }
  }
})

Profiles consist of 2 parts: the configuration, which is DOMPurify's configuration but with the keys renamed to camelCase, and the hooks. Please see DOMPurify documentation for more details the configuration. For the hooks configuration object, the keys are the DOMPurify entry point names, and the values are either a hook function or an array of hook functions.

export default defineAppConfig({
  sanitiseHtml: {
    profiles: {
      profileName: {
        config: {
          allowedTags: [
            'h1'
          ],
          ...
        },

        hooks: {
           beforeSanitizeAttributes: (currentNode) => {
            // Do something with the node
          },

          afterSanitizeAttributes: [
            (currentNode) => {
              // Do something with the node
            },

            (currentNode) => {
              // Do another with the node
            }
          ],
          ...
        }
      }
    }
  }
})

Contribution

This repo follows GitLab Flow as a branching model. All PRs should be made against development and not main.

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release