88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
---
|
|
id: fuzz-target-payload-codec
|
|
name: Fuzz target — `payload_codec` (core payload encode/decode invariants)
|
|
status: pending
|
|
depends_on: [fuzz-scaffold]
|
|
scope: moderate
|
|
risk: low
|
|
impact: component
|
|
level: implementation
|
|
tags: [wave-7, fuzzing]
|
|
---
|
|
|
|
## Description
|
|
|
|
The §3.1 target: `payload_codec`, driving core's payload surface
|
|
(`alkstore/src/payload.rs` — `encode_payload`, `payload_as::<T>`) —
|
|
already-`pub` API, no exposure needed.
|
|
|
|
- **`fuzz_targets/payload_codec.rs`** — the thin `fuzz_target!`
|
|
wrapper (3-line pattern) delegating to
|
|
`alkstore_fuzz_shared::payload_codec::fuzz_payload_codec(data)`;
|
|
the `[[bin]]` entry lands in `fuzz/Cargo.toml`.
|
|
- **`shared/src/payload_codec.rs`** — the invariant logic, with the
|
|
`#[cfg(test)]` corpus-replay module (the gate). Input: raw `&[u8]`
|
|
plus `arbitrary`-derived `serde_json::Value`s (the
|
|
`JsonValue` bounded-depth helper from the scaffold). Invariants
|
|
(§3.1, verbatim):
|
|
- **no-panic on any byte sequence** (the baseline);
|
|
- **typed-failure partition**: every decode failure is
|
|
`Error::Codec` — no other variant, no panic (the ADR-023 §1
|
|
fallibility pin, demonstrated across the input space);
|
|
- **deep-input loudness**: serde_json's recursion limit surfaces as
|
|
typed `Codec`, never a stack overflow;
|
|
- **Value round-trip**: `encode_payload(v)` → `payload_as::<Value>`
|
|
yields `v` for every arbitrary `Value` (canonicalization is
|
|
serde_json's, pinned-not-regressed);
|
|
- **typed round-trip**: for a representative typed-payload set,
|
|
`encode(Value::from(t))` decodes back to `t` (the ADR-020 §4
|
|
decode side).
|
|
- **Seeds** (§3.1's list, via `gen_fuzz_seeds.py` gaining the
|
|
`payload_codec` function): valid JSON of every Value variant,
|
|
truncations, deep nesting at and past the recursion limit, non-UTF-8
|
|
bytes, trailing garbage, oversized numbers, duplicate keys, the
|
|
`Null`-decode shape (ADR-023 §1's empty-byte-store corruption note).
|
|
Corpus committed under `fuzz/corpus/payload_codec/`; the
|
|
`fuzz/.gitignore` gains the `!corpus/payload_codec` negation.
|
|
- **`fuzz/README.md`** targets-table row.
|
|
- `shared`'s manifest gains `alkstore` (path) if the scaffold didn't
|
|
already carry it, plus `serde_json` + `arbitrary`.
|
|
|
|
Campaign flags are the campaign task's concern (`-max_len=65536
|
|
-dict=json.dict` starting point, §7); this task lands target + seeds +
|
|
replay.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `fuzz_targets/payload_codec.rs` + `shared/src/payload_codec.rs`
|
|
exist; `cargo fuzz build` builds the target (nightly, ASAN)
|
|
- [ ] All five §3.1 invariants implemented in `shared` and exercised by
|
|
both the fuzz path and the `#[cfg(test)]` replay module
|
|
- [ ] Seed corpus committed (`fuzz/corpus/payload_codec/`), generated
|
|
by `python3 fuzz/gen_fuzz_seeds.py` (deterministic — re-running
|
|
is a no-op diff); gitignore negation in place
|
|
- [ ] `cargo test --manifest-path fuzz/shared/Cargo.toml` green
|
|
(replays the committed corpus through the invariants)
|
|
- [ ] `shared` clippy/fmt gates green
|
|
(`cargo clippy --manifest-path fuzz/shared/Cargo.toml
|
|
--all-targets -- -D warnings`, `fmt --check`)
|
|
- [ ] Root workspace gates still green
|
|
|
|
## References
|
|
|
|
- docs/research/fuzzing.md §3.1 (target spec), §4 (wave-1 scope), §7
|
|
(flags)
|
|
- docs/architecture/decisions/020-payload-encoding.md §4 (the encoding
|
|
posture the round-trips pin)
|
|
- docs/architecture/decisions/023-fourth-review-round.md §1 (encode
|
|
fallibility)
|
|
- /workspace/@alkdev/alksocks/fuzz/shared/src/datagram_codec.rs (the
|
|
invariant-module + replay-test pattern)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |