detonate 0.1.5

Prove an injected web payload actually EXECUTES (alert(1) fires), not just reflects: a shared XSS-execution oracle over a jsdet sandbox.
Documentation
# Technical Specification: detonate

## 1. Overview & Architecture

`detonate` is an execution oracle for reflected cross-site scripting (XSS) payloads. It resolves whether a reflected HTTP response contains JavaScript that auto-executes under browser semantics.

```
                    ┌────────────────────────┐
                    │     HTML Response      │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ HTML5 Spec Parser      │
                    │ (html5ever / scraper)  │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ extract_executable_js  │
                    │ (filter data blocks &  │
                    │  interaction handlers) │
                    └─────┬────────────┬─────┘
                          │            │
            ┌─────────────▼──┐      ┌──▼─────────────┐
            │ Engine::Jsdet  │      │ Engine::Chrome │
            │ QuickJS-WASM   │      │ Headless DOM   │
            └─────────────┬──┘      └──┬─────────────┘
                          │            │
                    ┌─────▼────────────▼─────┐
                    │     ExecutionProof     │
                    │ (sinks, executed, err) │
                    └────────────────────────┘
```

### Engine Modes

1. **`Engine::Jsdet` (Default)**:
   - Uses QuickJS compiled to WebAssembly (`jsdet-core`, `jsdet-browser`).
   - Runs in-process with a simulated DOM/browser bridge (`BrowserBridge`).
   - Fast (<1ms per fragment), lightweight, strictly bounded by WebAssembly fuel and memory caps.

2. **`Engine::Chrome` (Opt-in / Fallback)**:
   - Drives real headless Chrome/Chromium via `--headless=new --dump-dom`.
   - Serves an instrumented harness from an ephemeral HTTP server (`127.0.0.1:0`).
   - Validates **mutation XSS (mXSS)** vectors where DOM re-serialization (e.g. `innerHTML` reassignment) mutates inert markup into executing script.
   - Falls back to `Engine::Jsdet` when no Chrome binary is detected on `$PATH`.

---

## 2. Invariants & Guarantees

### False-Positive Resistance
- **Spec-Compliant Extraction**: Uses `scraper` (HTML5 tree building) to ignore `<script>` tags inside HTML comments (`<!-- -->`), `<textarea>`, `<title>`, `<style>`, or element attribute values.
- **Data Block Filtering (`is_js_type`)**: Filters out non-executable script blocks with `type` attributes such as `text/plain`, `application/json`, `importmap`, `speculationrules`, `text/html`, and `text/template`.
- **Auto-Firing Handler Restriction**: Only auto-firing event handlers (`onerror`, `onload`, `ontoggle`, `onpageshow`, `onfocusin`, `onanimation*`, `onbegin`, `onend`, `onrepeat`) are extracted. Interaction handlers (`onclick`, `onmouseover`) are excluded because they require user actions.
- **Iframe `javascript:` Navigation**: Only `javascript:` URIs inside auto-navigating frame tags (`<iframe>`, `<frame>`) are extracted. `<a>` href links are excluded.

### Resource Boundedness & Cleanup
- **Jsdet Sandbox**: Execution is bounded by fuel limit and memory ceiling (`detonation_config()`). Sandbox traps (`while(1){}` or OOM) return `ExecutionProof::failed(...)` with `fragments_run` preserved.
- **Chrome Engine**: Chrome execution is bounded by a 15-second deadline (`CHROME_TIMEOUT`). Standard output is asynchronously drained on a background thread to prevent OS pipe deadlock on large DOM dumps.
- **Process Group Isolation**: Chrome processes are spawned in a dedicated process group (`setpgid`). Upon completion or timeout, the entire process group is signaled (`SIGKILL`) to prevent lingering renderer/GPU helper processes.

### Loud Failure Reporting (Law 10 Compliance)
- Operational failures (missing browser binary, HTTP harness bind failure, sandbox traps, browser launch timeouts) return an `ExecutionProof` with `executed: false` AND `error: Some(reason)`.
- Callers check `proof.failed_to_run()` to distinguish an infra failure from a safe, non-executing payload.

---

## 3. Core Types & API Contract

### `ExecutionProof`
```rust
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
pub struct ExecutionProof {
    pub executed: bool,
    pub sink: Option<String>,
    pub message: Option<String>,
    pub sinks: Vec<SinkHit>,
    pub fragments_run: usize,
    pub error: Option<String>,
}
```

- `proves(expected: &str) -> bool`: Returns `true` if `executed` is `true` AND `message` matches `expected`.
- `failed_to_run() -> bool`: Returns `true` if `error` is `Some(...)`.

### `SinkHit`
```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SinkHit {
    pub kind: String,
    pub detail: String,
}
```

Recognized sink categories:
- Dialog: `alert`, `confirm`, `prompt`
- Network: `network` (`fetch`, `sendBeacon`, `XMLHttpRequest`)
- Code execution: `eval` (`eval`, `Function`)
- DOM write: `dom-write` (`document.write`, `document.writeln`, `element.innerHTML`)
- Window / Navigation: `popup` (`window.open`), `redirect` (`location`), `cookie`, `storage`

### Vector Catalogs
- `EXEC_PRESERVING_VECTORS`: Self-validating execution-preserving XSS evasion vectors.
- `MUTATION_XSS_VECTORS`: Self-validating browser-only mXSS vectors (`mutation::MUTATION_XSS_VECTORS`).
- `BREAKOUT_VECTORS`: Self-validating context-breakout vectors (`breakout::BREAKOUT_VECTORS`).

---

## 4. CLI Interface

### Usage
```bash
detonate --url <URL> [--body-file <FILE>] [--expect <ARG>] [--engine jsdet|chrome]
detonate vectors [--marker <MARKER>]
```

### Exit Codes
- `0`: Execution proven (`executed: true` and `--expect` matched if provided).
- `3`: Execution completed successfully, but no matching execution was proven (`executed: false` or `--expect` mismatch).
- `2`: Usage error, invalid CLI flags, or file IO error.