domguard-js

1.0.1 • Public • Published

DOMGuard-js NPM version License: MIT NPM total downloads

A lightweight JavaScript library to sanitize HTML content and prevent XSS attacks.


🚀 Features

  • XSS Protection: Safely sanitize HTML to prevent cross-site scripting (XSS) attacks.
  • HTML Sanitization: Removes potentially harmful elements like <script>, <iframe>, etc.
  • Event Handler Removal: Removes inline event handlers (onclick, onload, etc.) to protect against malicious JavaScript.
  • Cache Support: Caches sanitized HTML for improved performance on repeated usage.
  • Flexible Context Handling: Allows context-based tag whitelisting for better control (input, description, general).
  • ESM and CJS Support: Fully compatible with modern JavaScript module systems.

📦 Installation

You can install domguard-js using your favorite package manager:

# Using pnpm
pnpm add domguard-js

# Using npm
npm install domguard-js

# Using yarn
yarn add domguard-js

🌟 Usage

Here's how to use the library in your project:

Import the library

// CommonJS
const isNumber = require('domguard-js');

// ES Modules
import isNumber from 'domguard-js';

Basic example

const unsafeHTML = '<script>alert("XSS")</script><p>Hello!</p>';
const safeHTML = DOMGuard.sanitizeAndValidate(unsafeHTML);

console.log(safeHTML); //Will return "<p>Hello!</p>"

Using cache for performance

const unsafeHTML = '<script>alert("XSS")</script><p>Hello!</p>';
const safeHTML = DOMGuard.sanitizeWithCache(unsafeHTML);

console.log(safeHTML); //Will return "<p>Hello!</p>"

---

## 🔧 API

### `DOMGuard.sanitizeAndValidate(html, context)`

Sanitizes and validates HTML based on the given context ('input', 'description', 'general').

#### Parameters
- **`html`** (`string`): The HTML string to sanitize.
- **`context`** (`string, optional, default: 'general'`): The context for which the HTML will be sanitized. Options: 'input', 'description', 'general'.

#### Returns

- **`string`:** The sanitized HTML.

### `DOMGuard.sanitizeWithCache(html, context)`

Sanitizes HTML and caches the result for future use.

#### Parameters
- **`html`** (`string`): The HTML string to sanitize.
- **`context`** (`string`): The context for which the HTML will be sanitized. Options: 'input', 'description', 'general'.

#### Returns

- **`string`:** The sanitized HTML, fetched from cache if previously sanitized.

### `DOMGuard.containsDangerousEvents(html)`

Checks if the HTML contains dangerous inline event handlers (like onclick, onload).

#### Parameters
- **`html`** (`string`): The HTML string to sanitize.

#### Returns

- **`boolean`:** Returns true if the HTML contains dangerous events, otherwise false.

---

## 🛠️ Development

If you want to contribute or run the project locally, follow these steps:

### Clone the repository

git clone https://github.com/angelabenavente/domguard-js.git cd domguard-js


### Install dependencies

npm install


### Run tests

npm run test


### Lint the code

npm run eslint


---

## 🧪 Testing

This project uses [Jest](https://jestjs.io/) for testing. To run the test suite, simply use:

npm run test


Example output:

PASS ./index.test.js ✓ should allow specific tags for the "input" context (2 ms) ✓ should allow specific tags for the "description" context ...


Feel free to add more test cases in the `test` file.

## 🔄 Changelog

See [CHANGELOG.md](https://github.com/angelabenavente/domguard-js/blob/main/CHANGELOG.md) for a detailed history of changes.

---

## 💡 Contributing

Contributions are welcome! If you'd like to contribute, please follow these steps:

1.  Fork the repository.
2.  Create a new branch for your feature or bugfix.
3.  Submit a pull request with a clear description of the changes.

See [CONTRIBUTING.md](https://github.com/angelabenavente/domguard-js/blob/main/CONTRIBUTING.md) for more details.

---

## 📜 License

This project is licensed under the [MIT License](https://github.com/angelabenavente/domguard-js/blob/main/LICENSE). Created with ❤️ by [Ángela Benavente](https://github.com/angelabenavente).

---

## 🌍 Links

- **GitHub Repository:** [https://github.com/angelabenavente/domguard-js](https://github.com/angelabenavente/domguard-js)

- **NPM Package:** [https://www.npmjs.com/package/domguard-js](https://www.npmjs.com/package/domguard-js)

Package Sidebar

Install

npm i domguard-js

Weekly Downloads

6

Version

1.0.1

License

MIT

Unpacked Size

18.1 kB

Total Files

8

Last publish

Collaborators

  • angelabenavente