DOMGuard-js

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)