# Security Policy

---

## Supported Versions

| Version | Supported |
|---------|-----------|
| 1.7.x   | Yes (current) |
| 1.6.x   | Security fixes only |
| < 1.6   | No |

---

## Reporting a Vulnerability

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

Report privately via GitHub Security Advisories:
1. Go to the repository
2. Click **Security** tab
3. Click **Report a vulnerability**

We aim to acknowledge reports within 48 hours and provide a fix within 14 days for critical issues.

---

## Known Attack Surfaces

### XXE — XML External Entity

External entities (`SYSTEM`/`PUBLIC`) are **blocked by default**. Attempting to resolve them produces `SEC_EXTERNAL_ENTITY`.

To enable controlled resolution:
```ts
parseXml(input, {
  entityMap: { myEntity: 'safe replacement' }
});
```

Never pass untrusted external entity resolvers.

### Billion Laughs (Entity Expansion DoS)

Entity expansion is depth-tracked and limited by `maxEntityExpansion` (default 10,000).
Circular entity chains are detected and terminated with `SEC_CIRCULAR_ENTITY`.

### XPath Injection

XPath expressions used in `xs:assert` and identity constraints are compiled from schema, not user input. If you allow user-supplied XPath strings via the plugin API, sanitize them before passing to `xpath()`.

### Denial of Service via Large Documents

Use `ParseBudget` / `ParseOptions` limits:
```ts
parseXml(untrustedInput, {
  maxDepth:      100,
  maxNodeCount:  50_000,
  maxTextLength: 500_000,
  maxAttributes: 64,
});
```

---

## Security-by-Default Summary

| Threat | Mitigation |
|--------|-----------|
| XXE | External entities blocked (opt-in only) |
| Billion Laughs | Entity expansion counter + depth limit |
| Deep nesting stack overflow | `maxDepth` (default 500) |
| Large text node memory | `maxTextLength` (default 10 MB) |
| Attribute flooding | `maxAttributes` (default 256) |
| Node count explosion | `maxNodeCount` (default 1 M) |