wgcloak/docs/IMPLEMENTATION_CHECKLIST.md

# Implementation and acceptance checklist

This is an evidence-based coordinator checklist. A checked item identifies
current code and tests; it is not a claim that the dirty worktree is an
unconditionally released artifact. The latest evidence was collected on
2026-09-19 with serial integration tests.

## Milestones 1–6

- [x] **1 — authenticated direct relay:** `src/transport/direct_udp.rs` and
  `src/protocol/*` implement the handshake, HMAC data, replay, keepalive,
  expiry, backend mapping, and statistics. Evidence: `tests/direct_udp.rs`
  covers round trip/auth rejection, concurrent clients, malformed traffic,
  source-port change, expiry, and backend failure; `tests/runtime_lifecycle.rs`
  covers daemon control/session cleanup.
- [x] **2 — QUIC DATAGRAM:** `src/transport/quic.rs` performs certificate and
  hostname verification, challenge authentication, datagrams, limits, and
  reconnect support. Evidence: `tests/quic.rs` and the QUIC cases in
  `tests/encrypted_runtime.rs` cover round trip, bad secret, hostname mismatch,
  multiple clients, cancellation, and server restart.
- [x] **3 — automatic selection:** `src/client/supervisor.rs` and runtime
  selection implement configured order, bounded probes/retries, auth-stop, and
  jittered reconnect. Evidence: `tests/supervisor.rs`, `tests/reconnect.rs`,
  and `tests/http3_runtime.rs`.
- [x] **4 — HTTP/3 CONNECT-UDP:** `src/transport/http3.rs` uses extended
  CONNECT and HTTP Datagrams with authentication and backend session mapping.
  Evidence: `tests/http3.rs`, `tests/http3_integration.rs`, and the daemon
  relay/isolation cases in `tests/http3_runtime.rs`.
- [x] **5 — TLS/TCP fallback:** `src/transport/tls_tcp.rs` implements TLS,
  authenticated bounded u16-BE framing, and bidirectional datagrams. Evidence:
  `tests/tls_tcp.rs`, `tests/integration_transports.rs`, and TLS cases in
  `tests/encrypted_runtime.rs`; the TLS/TCP head-of-line tradeoff is documented
  in `docs/PROTOCOL.md`.
- [ ] **6 — operational polish:** Control, validation, hardened systemd units,
  capability guidance, deterministic benchmark assets, and fuzz targets are
  present (`src/control.rs`, `tests/control.rs`, `packaging/systemd/`,
  `benches/`, `fuzz/`). Leave this milestone open until final clean-checkout
  gates, bounded cargo-fuzz runs, and the practical datagram cap decision are
  recorded. Config/certificate reload remains explicitly unsupported.

## v1 completion criteria (spec §89)

- [x] 1. Multiple clients concurrently reach one UDP backend —
  `tests/direct_udp.rs::concurrent_clients_use_independent_backend_sockets`,
  `tests/encrypted_runtime.rs`, and `tests/http3_runtime.rs`.
- [x] 2. No WireGuard-specific logic exists — source/runtime scope is generic
  UDP relay code; WireGuard is documented only as a non-goal in `README.md` and
  `docs/SECURITY.md`.
- [x] 3. Direct UDP works reliably — `tests/direct_udp.rs` round-trip,
  malformed-input, rebinding, expiry, and backend-failure coverage.
- [x] 4. QUIC DATAGRAM works reliably — `tests/quic.rs` and encrypted runtime
  forwarding/restart coverage.
- [x] 5. HTTP/3 CONNECT-UDP works — HTTP/3 unit, integration, and runtime tests.
- [x] 6. TLS/TCP fallback works — TLS framing/auth tests and both TLS integration
  suites.
- [x] 7. Automatic transport selection works — `tests/supervisor.rs` and
  `tests/reconnect.rs` cover order, fallback, retries, and recovery.
- [x] 8. Authentication is enforced on every public transport — bad-secret
  cases in `tests/direct_udp.rs`, `tests/quic.rs`, `tests/http3_integration.rs`,
  `tests/tls_tcp.rs`, and `tests/encrypted_runtime.rs`.
- [x] 9. Direct UDP has replay and integrity protection — protocol tests plus
  authenticated flags/replay cases in `tests/direct_udp.rs`.
- [x] 10. Direct UDP NAT rebinding works —
  `tests/direct_udp.rs::authenticated_source_port_change_updates_return_peer`.
- [x] 11. Sessions expire and clean up correctly — direct expiry, transport
  cancellation, HTTP/3 close, and lifecycle cases across `tests/direct_udp.rs`,
  `tests/http3_integration.rs`, `tests/http3_runtime.rs`, and
  `tests/encrypted_runtime.rs`.
- [x] 12. The server survives malformed and unauthenticated traffic —
  `tests/direct_udp.rs` malformed/auth-rejection cases and encrypted bad-secret
  integration tests.
- [x] 13. The daemon runs unprivileged except optional privileged-port
  capability — `User=wgcloak`, hardening, and commented narrow
  `CAP_NET_BIND_SERVICE` guidance in both `packaging/systemd/*.service` files.
- [x] 14. TOML configuration is clearly validated — `src/config.rs` tests and
  `tests/server_capabilities.rs` cover role, transport, listener, and datagram
  boundaries.
- [x] 15. Meaningful status and statistics are available — `src/control.rs`,
  `tests/control.rs`, `tests/runtime_lifecycle.rs`, and aggregate-stat tests in
  `tests/http3_runtime.rs`.
- [x] 16. Reconnects occur automatically — bounded supervisor backoff and
  server-restart proof in `tests/reconnect.rs` and `tests/encrypted_runtime.rs`.
- [x] 17. Automated integration tests cover multi-client operation — direct,
  encrypted, and HTTP/3 runtime integration suites.

## Required evidence before v1 sign-off

- [x] Unit tests cover parsing, malformed input, authentication, key
  derivation, replay, config validation, timeout logic, control limits, and
  secret-file safety. Evidence: library tests plus `tests/control.rs` and
  config secret tests.
- [x] Integration tests cover direct client/server, concurrent clients,
  source-port change, auth rejection, restart/reconnect, backend outage,
  oversized datagrams, expiry, and equivalent encrypted transport coverage.
- [x] Fuzz targets exist for direct packets, TLS frames, HTTP/3 parsing, and
  TOML parsing, and `cargo check --manifest-path fuzz/Cargo.toml` passes.
  No fuzzing execution or sanitizer result is claimed because `cargo-fuzz` is
  not installed on the current host.
- [ ] `cargo test`, formatting, linting, and documented integration/bench
  commands pass from a clean checkout. Current dirty-worktree evidence is:
  `cargo fmt --all -- --check`, `cargo check --all-targets`, strict all-target
  Clippy, serial `cargo test --tests -- --test-threads=1` (95 passed), and
  `cargo bench --bench protocol_transports --no-run`.
- [x] Review confirms no payload/secret logging, no unsafe privilege grant,
  and no accidental WireGuard/routing/firewall coupling. Evidence:
  `docs/SECURITY.md`, hardened systemd templates, source audit, and the
  authentication/control/secret-file tests. This review does not waive the
  clean-checkout and fuzz-execution items above.