WTFnet/docs/requirement_docs_v0.3.md

Below are repo-ready v0.3.0 docs. They’re written to match your current implemented feature set (v0.2 mostly done: sys/ports/neigh/certs/geoip/probe/dns/http/tls/discover/diag/calc). They also respect your decision to NOT include in v0.3.0:

• shell completions / man pages
• the “smart one-shot doctor” command
• extra output ergonomics for automation

And they target the real gaps / next upgrades you still have: HTTP/3, deeper HTTP timing, TLS extras, richer trace, ports conns, better cert baseline/diff, and optionally LLMNR/NBNS discovery (currently missing).

---

1) docs/RELEASE_v0.3.0.md

# WTFnet v0.3.0 — Release Plan

Binary name in examples: `wtfn` (current CLI examples use this form).  
Project scope: Linux (Debian/Ubuntu) + Windows first-class.

## 0. Summary

v0.3.0 focuses on improving **diagnostic depth and fidelity** of existing commands rather than adding a "smart doctor" workflow.

Major upgrades in this release:
- richer traceroute output and per-hop statistics
- HTTP timing breakdown accuracy (connect/tls stages)
- optional HTTP/3 support (best-effort)
- TLS diagnostics upgrades (OCSP stapling indicator, richer certificate parsing)
- ports connections view and summaries
- improved cert baseline/diff for system roots
- optional discovery expansion (LLMNR/NBNS)

---

## 1. Goals

### G1. Make existing outputs more trustworthy
- Replace placeholder timing fields with real measured values where feasible.
- Improve trace reliability and readability.

### G2. Expand diagnostics depth, not workflow complexity
- Keep subcommands explicit (no `doctor`, no guided flow).
- Focus on "give me evidence" tools.

### G3. Keep v0.2 compatibility
- Add flags and fields in an additive way.
- Keep default behavior safe and bounded.

---

## 2. Non-goals (explicitly out of scope)

- No `wtfn doctor ...` / one-shot diagnosis command (move to v0.4+).
- No shell completion scripts or man page generation.
- No new output modes like JSONL streaming / schema negotiation changes (stay stable).
- No OS-native TLS verifier in v0.3.0 (optional future enhancement).

---

## 3. Feature scope

### 3.1 probe trace: richer output (MUST)
Current: trace exists best-effort.
Target improvements:
- `--rdns`: reverse DNS lookup per hop (best-effort; cached; time-bounded)
- `--per-hop <n>`: send N probes per hop (default 3) to compute:
  - avg/min/max RTT per hop
  - loss % per hop
- `--icmp` and `--udp` modes remain best-effort; document privilege requirements
- Keep `--geoip` integration: hop IP → Country/ASN

Acceptance:
- output includes per-hop loss and stable hop formatting
- JSON output contains hop arrays with RTT series

---

### 3.2 HTTP timing breakdown accuracy (MUST)
Current: `dns_ms` + `ttfb_ms` exist, but connect/tls are placeholders.
Target:
- implement `connect_ms` and `tls_ms` (best-effort) for HTTP/1.1 and HTTP/2
- keep total duration correct and stable
- when measurement unavailable (library limitation), report:
  - `null` + add warning, never fake numbers

Acceptance:
- `wtfn http head|get` JSON contains:
  - `dns_ms`, `connect_ms`, `tls_ms`, `ttfb_ms`, `total_ms`
- on timeout / failure, partial timing must still be meaningful.

---

### 3.3 HTTP/3 (optional feature flag) (SHOULD)
Current: HTTP/3 not implemented.
Target:
- add `--http3` support behind Cargo feature `http3`
- behavior:
  - `--http3-only`: fail if HTTP/3 cannot be used
  - `--http3`: try HTTP/3, fallback to HTTP/2 unless `--http3-only`
- provide clear error classes:
  - UDP blocked, QUIC handshake timeout, TLS/ALPN mismatch, etc.

Acceptance:
- builds without `http3` feature still work
- with feature enabled, HTTP/3 works on at least one known compatible endpoint

---

### 3.4 TLS extras: OCSP + richer cert parsing (MUST)
Current: `tls handshake/verify/cert/alpn` exists.
Target:
- show OCSP stapling presence (if exposed by library)
- richer certificate parsing for leaf and intermediates:
  - SANs (DNS/IP)
  - key usage / extended key usage (best-effort)
  - signature algorithm (best-effort)
- new flags:
  - `--show-extensions` (prints richer X.509 info)
  - `--ocsp` (show stapling info if present)

Acceptance:
- TLS output includes richer leaf cert details when requested
- `--show-chain` remains fast and bounded

---

### 3.5 ports conns: active connection view + summaries (SHOULD)
Current: `ports listen/who`.
Target:
- add `wtfn ports conns`
  - show active TCP connections with:
    - local addr:port
    - remote addr:port
    - state (ESTABLISHED/TIME_WAIT/etc)
    - PID/process name (best-effort)
- add summary mode:
  - `--top <n>` show top remote IPs by count
  - `--by-process` group by process

Acceptance:
- works on Linux + Windows best-effort
- never requires admin by default; if needed, return partial with warnings

---

### 3.6 cert roots: stronger baseline/diff (MUST)
Current: cert roots listing exists; baseline/diff exists.
Target improvements:
- normalize matching key: SHA256 fingerprint
- diff categories:
  - added / removed
  - changed validity (newly expired)
  - subject/issuer changes
- add stable JSON schema for baseline files (include schema version)

Acceptance:
- baseline diff is stable across platforms (best-effort fields allowed)
- diff output is human-friendly and JSON-friendly

---

### 3.7 discover: LLMNR/NBNS (optional) (NICE)
Current: mDNS + SSDP exist; LLMNR/NBNS missing.
Target:
- add `wtfn discover llmnr --duration 3s`
- add `wtfn discover nbns --duration 3s`
- bounded, low-noise, rate-limited

Acceptance:
- best-effort implementation on Windows-first networks
- if unsupported on OS, show "not supported" error with exit code 5 (partial)

---

## 4. Compatibility & behavior rules

- Command names must remain stable.
- Existing flags must retain meaning.
- JSON output fields are additive only.
- Logging remains stderr-only; JSON output remains clean stdout.

---

## 5. Deliverables checklist

MUST:
- trace richer output + per-hop loss stats
- HTTP connect/tls timing best-effort with warnings when unknown
- TLS extras: OCSP indicator + richer x509 parsing
- ports conns basic implementation
- cert baseline/diff improvements

SHOULD:
- HTTP/3 behind feature flag

NICE:
- LLMNR/NBNS discovery

---

## 6. Definition of Done (v0.3.0)

- v0.3.0 builds on Linux (Debian/Ubuntu) + Windows.
- `wtfn probe trace` provides per-hop loss and optional rdns.
- `wtfn http head|get` reports accurate timing breakdown where possible.
- `wtfn tls ...` provides OCSP + SAN/extensions when requested.
- `wtfn ports conns` works best-effort and produces useful output.
- cert baseline/diff is stable and readable.
- No doctor command, no completions, no new output modes.

---

3) docs/WORK_ITEMS_v0.3.0.md (engineering task list)

# WTFnet v0.3.0 — Work Items

This is a practical checklist to execute v0.3.0.

## 1) probe/trace upgrades
- [ ] add `--per-hop <n>` and store RTT samples per hop
- [ ] compute loss% per hop
- [ ] add `--rdns` best-effort reverse lookup (cached + time-bounded)
- [ ] improve hop formatting + JSON schema

## 2) http timing improvements
- [ ] implement `connect_ms` and `tls_ms` timing
- [ ] report `null` + warning when measurement unavailable
- [ ] keep current `dns_ms` and `ttfb_ms`

## 3) optional HTTP/3
- [ ] add `http3` cargo feature + deps
- [ ] implement `--http3` / `--http3-only`
- [ ] define error classification for QUIC failures

## 4) tls extras
- [ ] add OCSP stapling presence indicator (if available)
- [ ] parse SANs and key usage / EKU best-effort
- [ ] add `--show-extensions` and `--ocsp` flags

## 5) ports conns
- [ ] implement `wtfn ports conns`
- [ ] add `--top <n>` and `--by-process`
- [ ] best-effort PID mapping with warnings

## 6) cert baseline/diff improvements
- [ ] baseline schema version
- [ ] match by SHA256 fingerprint
- [ ] diff categories: add/remove/expired/changed

## 7) optional LLMNR/NBNS
- [ ] implement `discover llmnr`
- [ ] implement `discover nbns`
- [ ] bounded collection, low-noise

## 8) docs updates
- [ ] update README roadmap
- [ ] update COMMANDS.md with new flags/commands
- [ ] add RELEASE_v0.3.0.md

---