feat(fuzz): EncString parser fuzz harness (PRD §11.4)

Adds a cargo-fuzz / libFuzzer harness for the security-critical Bitwarden
"type 2" EncString parser — the §11.4 / M7 groundwork toward the v0.1 tag.
The target feeds arbitrary input to `EncString::parse` and, on success,
asserts the parse → serialize → parse round-trip is stable (catches panics
and parser/serializer disagreement).

- fuzz/: a standalone workspace (own empty [workspace]); root Cargo.toml
  also `exclude`s it. cargo-fuzz needs nightly + a sanitizer runtime, so
  isolating it keeps the CI gates (fmt/clippy/test/deny/headless) and the
  workspace `forbid(unsafe_code)` untouched — the target's `#![no_main]` +
  libFuzzer's internal unsafe live only here.
- docs/fuzzing.md: prerequisites, run command, the ≥24h soak, corpus seeding.
- README pointer + CHANGELOG entry.

Verified: `cargo +nightly fuzz build` compiles; a 30s smoke run did ~2.1M
iterations with no finding. The full ≥24h soak is a maintainer step.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,14 @@ range may break in any release.
 
 ### Added
 
+- **`EncString` parser fuzz harness.** A cargo-fuzz / libFuzzer target
+  (`fuzz/fuzz_targets/enc_string_parse.rs`) for the security-critical Bitwarden
+  "type 2" parser — feeds arbitrary input to `EncString::parse` and asserts the
+  parse → serialize → parse round-trip is stable. Lives in a standalone `fuzz/`
+  workspace (nightly + sanitizer only), so the CI gates are untouched; run with
+  `cargo +nightly fuzz run enc_string_parse` (see `docs/fuzzing.md`). Groundwork
+  toward the PRD §11.4 / M7 `v0.1` gate (the ≥ 24 h soak is a maintainer step).
+
 - **TUI identity create/edit (curated).** The `vault-tui` add/edit form (`a`/`e`)
   now composes identity (type 4) items — the **Type** row cycles `login → secure
   note → card → identity`. To fit the non-scrolling overlay it edits a curated

Cargo.toml

@@ -13,6 +13,9 @@ members = [
     "crates/vault-theme",
     "crates/vault-config",
 ]
+# The cargo-fuzz harness is a standalone workspace (nightly + sanitizer only);
+# keep it out of `cargo <cmd> --workspace` and the CI gates.
+exclude = ["fuzz"]
 
 [workspace.package]
 version = "0.0.1"

README.md

@@ -47,6 +47,9 @@ sibling of the `vault` binary, then `$PATH` (override with
 `$VAULT_AGENT_BIN`; opt out per-call with `--no-auto-spawn`). A spawned
 agent logs to `agent.log` beside the socket.
 
+The security-critical `EncString` parser has a cargo-fuzz harness under `fuzz/`
+(a standalone workspace, run on nightly) — see [`docs/fuzzing.md`](docs/fuzzing.md).
+
 ## Getting started
 
 ```sh

docs/fuzzing.md

@@ -0,0 +1,64 @@
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+
+# Fuzzing the `EncString` parser
+
+Vault fuzzes its security-critical Bitwarden "type 2" `EncString` parser
+(`crates/vault-core/src/enc_string.rs`) with [`cargo-fuzz`] / libFuzzer. The
+parser base64-decodes attacker-influenceable cache and `/sync` strings into
+IV / ciphertext / MAC, so it must never panic and must round-trip cleanly. PRD
+§11.4 requires this harness to run **≥ 24 h with no findings** as part of the
+`v0.1` tag gate (§12 M7).
+
+## Layout
+
+The harness is a **standalone workspace** under `fuzz/`, deliberately kept out of
+the main workspace (the root `Cargo.toml` lists explicit `members` and also
+`exclude = ["fuzz"]`, and `fuzz/Cargo.toml` carries its own empty `[workspace]`).
+That isolation matters: cargo-fuzz needs a nightly toolchain and a sanitizer
+runtime, so the repo's CI gates (`fmt` / `clippy -D warnings` / `test` / `deny` /
+headless builds) never try to build it. The fuzz target is also the one place
+`#![no_main]` and libFuzzer's internal `unsafe` live — outside the workspace's
+`#![forbid(unsafe_code)]`.
+
+- `fuzz/Cargo.toml` — the `vault-fuzz` package.
+- `fuzz/fuzz_targets/enc_string_parse.rs` — the target: parse arbitrary input,
+  and on success assert the parse → serialize → parse round-trip is stable.
+
+## Prerequisites
+
+```sh
+rustup toolchain install nightly
+cargo install cargo-fuzz      # provides `cargo fuzz` (libFuzzer driver)
+```
+
+## Run
+
+```sh
+# from the repo root
+cargo +nightly fuzz run enc_string_parse
+```
+
+Seed the corpus with a real example so libFuzzer starts from valid structure
+(optional but speeds up coverage):
+
+```sh
+mkdir -p fuzz/corpus/enc_string_parse
+printf '2.%s|%s|%s' \
+  "$(head -c16 /dev/zero | base64)" \
+  "$(head -c16 /dev/zero | base64)" \
+  "$(head -c32 /dev/zero | base64)" \
+  > fuzz/corpus/enc_string_parse/seed
+```
+
+### The §11.4 soak
+
+```sh
+# 24 hours (86400 s); findings are written under fuzz/artifacts/
+cargo +nightly fuzz run enc_string_parse -- -max_total_time=86400
+```
+
+A crash or assertion failure drops a reproducer in
+`fuzz/artifacts/enc_string_parse/`; replay it with
+`cargo +nightly fuzz run enc_string_parse fuzz/artifacts/enc_string_parse/<file>`.
+The `corpus/`, `artifacts/`, `target/`, and `coverage/` directories are
+git-ignored.

fuzz/.gitignore

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+target/
+corpus/
+artifacts/
+coverage/
+Cargo.lock

fuzz/Cargo.toml

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[package]
+name = "vault-fuzz"
+version = "0.0.0"
+publish = false
+edition = "2021"
+license = "GPL-3.0-or-later"
+
+# Standalone workspace: cargo-fuzz needs nightly + a sanitizer runtime, so this
+# crate is deliberately kept out of the main workspace (whose `members` list is
+# explicit and whose root `Cargo.toml` also `exclude`s `fuzz`). That way the
+# repo's CI gates — fmt / clippy -D warnings / test / deny / headless builds —
+# never try to build the nightly-only fuzz target.
+[workspace]
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+vault-core = { path = "../crates/vault-core" }
+
+[[bin]]
+name = "enc_string_parse"
+path = "fuzz_targets/enc_string_parse.rs"
+test = false
+doc = false
+bench = false

fuzz/fuzz_targets/enc_string_parse.rs

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+//! Fuzz the security-critical Bitwarden "type 2" `EncString` parser.
+//!
+//! `EncString::parse` base64-decodes attacker-influenceable cache/sync strings
+//! into IV / ciphertext / MAC, so it must never panic and must be internally
+//! consistent. This target feeds arbitrary bytes (as lossy UTF-8) to the parser
+//! and, on a successful parse, asserts the parse → serialize → parse round-trip
+//! is stable — catching both panics and any parser/serializer disagreement.
+//!
+//! Run with `cargo +nightly fuzz run enc_string_parse` (see `docs/fuzzing.md`).
+
+#![no_main]
+
+use libfuzzer_sys::fuzz_target;
+use vault_core::EncString;
+
+fuzz_target!(|data: &[u8]| {
+    let s = String::from_utf8_lossy(data);
+    if let Ok(parsed) = EncString::parse(&s) {
+        // The canonical serialization of a parsed value must itself parse back
+        // to an equal value — the parser and serializer must agree.
+        let reparsed =
+            EncString::parse(&parsed.serialize()).expect("serialize() output must re-parse");
+        assert_eq!(parsed, reparsed, "parse/serialize round-trip diverged");
+    }
+});