A lightweight JavaScript library to sanitize HTML content and prevent XSS attacks.
- 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.
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
Here's how to use the library in your project:
// CommonJS
const isNumber = require('domguard-js');
// ES Modules
import isNumber from 'domguard-js';
const unsafeHTML = '<script>alert("XSS")</script><p>Hello!</p>';
const safeHTML = DOMGuard.sanitizeAndValidate(unsafeHTML);
console.log(safeHTML); //Will return "<p>Hello!</p>"
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)