xss-defender/README.md

A standalone library for XSS sanitization and detection.

# XssDefender

> **Надёжная защита от XSS‑атак для современных веб‑приложений на TypeScript**

[![npm](https://img.shields.io/npm/v/xss-defender.svg)](https://www.npmjs.com/package/xss-defender)
[![build](https://github.com/IgnIVertiKalCaD/xss-defender/actions/workflows/test.yml/badge.svg)](https://github.com/your‑org/xss‑defender/actions)

XssDefender — это лёгкая TypeScript‑библиотека для детектирования и нейтрализации XSS‑векторов, включая Unicode‑обфусцированные скрипты, `javascript:`‑URL, `data:`‑URI, CSS‑`expression()` и десятки других приёмов, которые остаются актуальными и завтра.

## Ключевые особенности

- **Глубокая эвристика** — расширенные регулярные выражения ловят даже нестандартные и смешанные регистром вставки.
- **Гибкая конфигурация** — разрешайте только нужные теги/атрибуты, управляйте логированием.
- **Безопасность по умолчанию** — если тег не разрешён, он будет либо удалён, либо закодирован.
- **Полная типизация** — написано на TypeScript, API удобно использовать в Node .js и браузере.
- **Продуманное логирование** — лаконичное или подробное, чтобы быстро разбирать реальные инциденты.
- **Высокое покрытие тестами** — десятки edge‑кейсов уже в репозитории.

## Установка

```bash
npm i xss-defender
# или
yarn add xss-defender
```

Библиотека не имеет внешних зависимостей и легко встраивается в любую сборку.

## Быстрый старт

```ts
import { XssDefender } from "xss-defender";

const defender = new XssDefender();

defender.sanitizeString(`<script>alert('XSS')</script>`);
// => ""

defender.hasXssRisks("<img src=x onerror=alert(1)>");
// => true
```

### Кастомная конфигурация

```ts
import {
  XssDefender,
  DEFAULT_SANITIZATION_CONFIG,
  SanitizationConfig,
} from "xss-defender";

const config: Partial<SanitizationConfig> = {
  ...DEFAULT_SANITIZATION_CONFIG,
  allowedTags: ["p", "a"],
  allowedAttributes: ["href"],
  stripIgnoreTag: true,
  enableLogging: true,
  logFormat: "detailed",
};

const defender = new XssDefender(config);
```

## API

| Метод                              | Описание                                                             |
| ---------------------------------- | -------------------------------------------------------------------- |
| `sanitizeString(value)`            | Возвращает очищенную строку. `null/undefined/""` → `""`.             |
| `hasXssRisks(value)`               | `true`, если в строке найден потенциальный XSS.                      |
| `sanitizeObject(obj)`              | Рекурсивно проходит по объекту/массиву и очищает все строковые поля. |
| `sanitizeHtmlForElement(el, html)` | Безопасно устанавливает `innerHTML` DOM‑элемента.                    |
| `checkUrlParams(params)`           | Анализирует URL‑параметры: `{ isSafe, issues[] }`.                   |
| `setConfig(partial)`               | Патч‑обновление конфигурации на лету.                                |
| `getConfig()`                      | Текущая конфигурация (readonly).                                     |

### Параметры конфигурации

| Поле                | Тип                      | По умолчанию                                   | Значение                                                          |
| ------------------- | ------------------------ | ---------------------------------------------- | ----------------------------------------------------------------- |
| `allowedTags`       | `string[]`               | список распространённых безопасных тегов       | Какие теги оставить живыми.                                       |
| `allowedAttributes` | `string[]`               | `["id","class","style","href","target","src"]` | Разрешённые атрибуты для разрешённых тегов.                       |
| `stripIgnoreTag`    | `boolean`                | `false`                                        | `true` — вырезать запрещённые теги, `false` — HTML‑кодировать их. |
| `enableLogging`     | `boolean`                | `false`                                        | Включить консольное логирование.                                  |
| `logFormat`         | `'simple' \| 'detailed'` | `'simple'`                                     | Формат логов.                                                     |

> **Совет:** оставляйте `stripIgnoreTag = true`, если очищаете данные перед вставкой в DOM. Кодирование полезно при хранении/отображении «как есть».

## Проверка URL‑параметров

```ts
const { isSafe, issues } = defender.checkUrlParams({
  search: "<script>alert(1)</script>",
  page: "2",
});

if (!isSafe) {
  console.warn("Опасные параметры!", issues);
}
```

## Работа с React/Vue/Angular

`sanitizeString` подходит для любого UI‑фреймворка. Просто пропускайте туда данные, полученные от пользователя или API, прежде чем показать их в `dangerouslySetInnerHTML` / `v-html` / `innerHTML`.

## Тесты

```bash
npm test
```

В репозитории лежат **spec**‑тесты на Jest (см. `spec/core/xss-defender.spec.ts`). Они демонстрируют работу со сложными нагрузками: смешанный регистр, скрытые комментарии, Unicode‑экранирование.

## План развития

- 🔍 **Расширяемые паттерны** — возможность добавлять/отключать собственные регулярки.
- ⚙️ **Web‑Worker режим** для тяжёлых потоков очистки.
- 🧩 **Плагины** (например, отчёты Sentry).

Ваши PR и идеи приветствуются!

## Вклад и поддержка

1. Сделайте fork и создайте ветку `feature/<название>`.
2. Запустите `npm i` и `npm test` — убедитесь, что все тесты зелёные.
3. Оформите PR с описанием мотивации и изменений.

Перед отправкой не забудьте добавить/обновить тесты для новых сценариев.

## Лицензия

MIT © 2025 — Вы.