# Security Policy

## Supported Versions

| Version | Supported |
|---|---|
| 1.1.x | ✅ Active support |
| 1.0.x | ⚠️ Critical fixes only |
| < 1.0 | ❌ End of life |

---

## Reporting a Vulnerability

**Please do not open a public GitHub issue for security vulnerabilities.**

Public disclosure before a fix is available puts all users at risk.

### How to report

Email: **security@your-org.example.com**  
Subject: `[xml-xsd-engine] Security vulnerability report`

Include:
1. A description of the vulnerability
2. Steps to reproduce (minimal XML / code snippet)
3. The potential impact (what an attacker could achieve)
4. Your suggested fix (optional but appreciated)

### What to expect

| Timeframe | Action |
|---|---|
| Within 2 business days | Acknowledgement of your report |
| Within 7 days | Initial assessment and severity triage |
| Within 30 days | Fix released or mitigations documented |
| After fix release | Public disclosure (CVE if applicable) |

We follow [responsible disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html).  
If you respect the embargo period, we will acknowledge your contribution in the release notes.

---

## Known Attack Vectors & Mitigations

This library parses untrusted XML. The following threats are specifically accounted for:

### Billion Laughs (Entity Expansion DoS)

**What it is:** A deeply-nested entity definition that causes exponential string expansion when entities are resolved, consuming gigabytes of memory.

**Example:**
```xml
<!DOCTYPE bomb [
  <!ENTITY a "aaaa...aaaa">
  <!ENTITY b "&a;&a;&a;&a;">
  <!ENTITY c "&b;&b;&b;&b;">
]>
<root>&c;</root>
```

**Mitigation:** Entity expansion is hard-capped at **1 000 000 characters** total across the entire document. Exceeds this → `XmlError(SEC_ENTITY_EXPANSION)` thrown immediately.

---

### XXE — XML External Entity Injection

**What it is:** An attacker embeds a `SYSTEM` entity that resolves to a local file or remote URL, leaking sensitive data.

**Example:**
```xml
<!DOCTYPE foo [
  <!ENTITY xxe SYSTEM "file:///etc/passwd">
]>
<root>&xxe;</root>
```

**Mitigation:** External entity references (`SYSTEM` / `PUBLIC` keywords in DOCTYPE) are **parsed but never resolved**. The raw entity reference is stored as literal text. No file or network I/O is performed. This is unconditional — there is no option to enable external entity resolution.

---

### Deep Nesting (Stack Overflow)

**What it is:** A document with thousands of nested elements designed to exhaust the call stack or heap.

**Mitigation:** The parser is **iterative** (stack-based), not recursive — no call stack growth. Additionally, a configurable `maxDepth` limit (default **500**) throws `XmlError(SEC_MAX_DEPTH)` when exceeded.

---

### Attribute Flooding

**What it is:** An element with thousands of attributes designed to exhaust memory.

**Mitigation:** `maxAttributes` limit (default **256** per element) throws `XmlError(SEC_MAX_ATTRIBUTES)`.

---

### Giant Text Node

**What it is:** A text node containing hundreds of megabytes of data.

**Mitigation:** `maxTextLength` limit (default **10 000 000 characters** per text node) throws `XmlError(SEC_MAX_TEXT_LENGTH)`.

---

### Node Count Bomb

**What it is:** A flat document with millions of elements designed to exhaust memory.

**Mitigation:** `maxNodeCount` limit (default **1 000 000** total nodes across the document) enforced during tokenization.

---

### Malicious Schema (Schema Bomb)

**What it is:** An XSD schema with circular type references or deeply recursive group references designed to hang the compiler.

**Mitigation:**
- `xs:include` cycle guard — each schema URL tracked; duplicates skipped
- `detectCircularTypes()` — topological check available post-compilation
- Schema compilation is iterative, not recursive

---

## Safe Defaults

All security limits are **on by default** with conservative values. No opt-in required.

To tighten limits for high-security environments:

```ts
import { ParseBudget } from 'xml-xsd-engine';

const budget = new ParseBudget({
  bytes:         1_000_000,   // reject anything over 1 MB
  wallTimeMs:    500,          // hard 500 ms timeout
  depth:         20,           // restrict to shallow documents
  nodes:         10_000,       // restrict node count
  maxAttributes: 16,           // restrict attributes per element
});

const doc = budget.parse(untrustedInput);  // throws XmlError(SEC_*) on any violation
```

---

## Threat Model

This library is designed for use in scenarios where:

- XML input originates from **untrusted sources** (user uploads, external APIs, form submissions)
- The parsing process runs in a **server-side Node.js environment**
- **Confidentiality, integrity, and availability** of the host system must be preserved

It is **not** designed for:

- Parsing XML from trusted, controlled sources where performance is paramount and limits are unnecessary
- Browser-side parsing of documents the user themselves have created

---

## Security-Related Error Codes

| Code | Trigger condition |
|---|---|
| `SEC_MAX_DEPTH` | Element nesting exceeds `maxDepth` |
| `SEC_MAX_ATTRIBUTES` | Attributes per element exceeds `maxAttributes` |
| `SEC_MAX_TEXT_LENGTH` | Text node length exceeds `maxTextLength` |
| `SEC_ENTITY_EXPANSION` | Total entity expansion exceeds 1 000 000 chars |
| `SEC_EXTERNAL_ENTITY` | `SYSTEM` / `PUBLIC` entity reference detected in DOCTYPE |

All `SEC_*` errors set `error.isSecurity === true` for easy programmatic filtering.