add fuzz targets for varint and frame decode (closes M0) (#19)

* feature: added fuzz tests

* added nightly flag for fuzz build

Author: RomanEmreis

.agents/skills/protocol_testing/SKILL.md

@@ -53,14 +53,41 @@ Every codec (varint, frame) needs three test classes:
 | Malformed rejection | Known-bad byte sequences must return an error, not panic |
 | Boundary conditions | Max varint value, empty payload, max frame length |
 
-## Fuzzing (future)
+## Fuzzing
+
+Fuzz targets live in `crates/istok-core/fuzz/fuzz_targets/` and are built with
+`cargo fuzz` (nightly required). Currently covering:
+- `fuzz_varint_decode` — `varint::decode`
+- `fuzz_frame_decode` — `h3_frame::decode_frame_header`
+
+To run locally (`+nightly` is required — cargo-fuzz uses `-Z` flags):
+```sh
+cd crates/istok-core
+cargo +nightly fuzz run fuzz_varint_decode
+cargo +nightly fuzz run fuzz_frame_decode
+```
+
+Runs indefinitely until `Ctrl+C`. Corpus is saved in `fuzz/corpus/` and seeds future runs.
+
+For a time-bounded run (CI-style):
+```sh
+ASAN_OPTIONS="detect_odr_violation=0:quarantine_size_mb=1:malloc_context_size=0" \
+cargo +nightly fuzz run fuzz_varint_decode -- -max_total_time=30 -max_len=8 -rss_limit_mb=256
+```
 
-Fuzz targets will live in `fuzz/` and cover:
-- Frame decoding (`Frame::parse`)
-- QPACK decoding (once M2 is active)
+Use `max_len=8` for varint (QUIC varint max is 8 bytes) and `max_len=16` for frame
+decode (type varint + length varint = up to 16 bytes).
 
 Rule: crashes are bugs. The engine must never panic on arbitrary input.
 
+### Adding a new fuzz target
+
+1. Add a `fuzz_targets/<name>.rs` file (see existing targets for the one-liner pattern).
+2. Add a `[[bin]]` entry to `crates/istok-core/fuzz/Cargo.toml`.
+3. **The fuzz `Cargo.toml` must have `[workspace]` at the top** — without it, Cargo
+   treats the fuzz crate as part of the parent workspace and `cargo fuzz` fails.
+   This is already present; do not remove it when editing the file.
+
 ## Anti-patterns
 
 - Real `tokio::time::sleep` or `tokio::net` in unit tests — use the mock harness.

.github/workflows/ci.yml

@@ -51,3 +51,26 @@ jobs:
         run: cargo build -p istok-core --no-default-features --locked
       - name: Build istok-core with alloc only
         run: cargo build -p istok-core --no-default-features --features alloc --locked
+
+  fuzz:
+    name: Fuzz (build + short run)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - name: Install cargo-fuzz
+        run: cargo install cargo-fuzz
+      - name: Build fuzz targets
+        working-directory: crates/istok-core
+        run: cargo +nightly fuzz build
+      - name: Fuzz varint decode (30s)
+        working-directory: crates/istok-core
+        env:
+          ASAN_OPTIONS: "detect_odr_violation=0:quarantine_size_mb=1:malloc_context_size=0"
+        run: cargo +nightly fuzz run fuzz_varint_decode -- -max_total_time=30 -max_len=8 -rss_limit_mb=256
+      - name: Fuzz frame decode (30s)
+        working-directory: crates/istok-core
+        env:
+          ASAN_OPTIONS: "detect_odr_violation=0:quarantine_size_mb=1:malloc_context_size=0"
+        run: cargo +nightly fuzz run fuzz_frame_decode -- -max_total_time=30 -max_len=16 -rss_limit_mb=256

.gitignore

@@ -20,5 +20,10 @@ target
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
 
+# Fuzz corpus and crash artifacts — local only
+crates/istok-core/fuzz/corpus/
+crates/istok-core/fuzz/artifacts/
+crates/istok-core/fuzz/coverage/
+
 # Local agent task handoff — never committed
 .agents/TASK.md

crates/istok-core/fuzz/Cargo.lock

@@ -0,0 +1,26 @@
+[workspace]
+
+[package]
+name = "istok-core-fuzz"
+version = "0.0.0"
+edition = "2024"
+publish = false
+
+[package.metadata]
+cargo-fuzz = true
+
+# libfuzzer-sys provides the fuzz_target! macro and links against libFuzzer.
+# Requires a nightly toolchain — run via `cargo fuzz build` / `cargo fuzz run`.
+[dependencies]
+libfuzzer-sys = "0.4"
+istok-core = { path = ".." }
+
+[[bin]]
+name = "fuzz_varint_decode"
+path = "fuzz_targets/fuzz_varint_decode.rs"
+doc = false
+
+[[bin]]
+name = "fuzz_frame_decode"
+path = "fuzz_targets/fuzz_frame_decode.rs"
+doc = false

crates/istok-core/fuzz/Cargo.toml

@@ -0,0 +1,10 @@
+#![no_main]
+
+use istok_core::codec::h3_frame;
+use libfuzzer_sys::fuzz_target;
+
+// Invariant: decode_frame_header must never panic on arbitrary input.
+// Any byte sequence must produce Ok or Err, never a panic.
+fuzz_target!(|data: &[u8]| {
+    let _ = h3_frame::decode_frame_header(data);
+});

crates/istok-core/fuzz/fuzz_targets/fuzz_frame_decode.rs

@@ -0,0 +1,10 @@
+#![no_main]
+
+use istok_core::codec::varint;
+use libfuzzer_sys::fuzz_target;
+
+// Invariant: decode must never panic on arbitrary input.
+// Any byte sequence must produce Ok or Err, never a panic.
+fuzz_target!(|data: &[u8]| {
+    let _ = varint::decode(data);
+});

crates/istok-core/fuzz/fuzz_targets/fuzz_varint_decode.rs

@@ -15,7 +15,7 @@ Varint and H3 frame codecs with tests. QPACK excluded (see M2).
 - [x] varint codec + tests
 - [x] H3 frame codec + tests
 - [x] SETTINGS payload encoding (M0: empty) + tests
-- [ ] fuzz target(s) for frame/varint parsing (optional in v0 CI)
+- [x] fuzz target(s) for frame/varint parsing (optional in v0 CI)
 
 ### DoD checklist