# Fuzzing

The repository includes an isolated [`cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz)
crate under `fuzz/`. It depends on the public `wgcloak` library by path and
does not open sockets, read files, or start async runtimes. Each target limits
the input passed to a parser to 64 KiB; payload/frame/datagram copies are
limited to 16 KiB where the API supports a bound.

## Install and run

Install `cargo-fuzz` once, then run a short smoke fuzzing session from the
repository root:

```bash
cargo install cargo-fuzz
cargo fuzz run fuzz_direct_packet -- -max_total_time=30
cargo fuzz run fuzz_tls_frame -- -max_total_time=30
cargo fuzz run fuzz_http3_parser -- -max_total_time=30
cargo fuzz run fuzz_config_toml -- -max_total_time=30
```

The corpus directories under `fuzz/corpus/` contain minimal and malformed
seeds. Add minimized findings there with the target that discovered them.

For a compile-only check when `cargo-fuzz` is unavailable:

```bash
cargo check --manifest-path fuzz/Cargo.toml
```

`cargo-fuzz` uses libFuzzer and sanitizer instrumentation for fuzz builds.
For an explicit sanitizer run, set the sanitizer supported by the local LLVM
toolchain, for example:

```bash
RUSTFLAGS="-Zsanitizer=address" cargo fuzz run fuzz_direct_packet --sanitizer address -- -max_total_time=60
```

## Target invariants

- Direct packet parsing rejects malformed/truncated/oversized input without
  panicking and checks the DATA bound before copying its payload.
- TLS/TCP framing handles arbitrary incremental chunks, rejects oversized
  length headers, and reports truncated final frames without panicking.
- HTTP/3 capsule, context-ID, and authentication message parsers reject
  malformed varints, capsule lengths, contexts, and auth payloads safely.
- TOML parsing accepts only valid UTF-8 input and performs structural parsing
  in memory; the target deliberately does not call validation that could load
  file-backed secrets.