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

• 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.
• 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.
• 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.
• 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.
• 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)

• 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.
• 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.
• 3. Direct UDP works reliably — tests/direct_udp.rs round-trip, malformed-input, rebinding, expiry, and backend-failure coverage.
• 4. QUIC DATAGRAM works reliably — tests/quic.rs and encrypted runtime forwarding/restart coverage.
• 5. HTTP/3 CONNECT-UDP works — HTTP/3 unit, integration, and runtime tests.
• 6. TLS/TCP fallback works — TLS framing/auth tests and both TLS integration suites.
• 7. Automatic transport selection works — tests/supervisor.rs and tests/reconnect.rs cover order, fallback, retries, and recovery.
• 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.
• 9. Direct UDP has replay and integrity protection — protocol tests plus authenticated flags/replay cases in tests/direct_udp.rs.
• 10. Direct UDP NAT rebinding works — tests/direct_udp.rs::authenticated_source_port_change_updates_return_peer.
• 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.
• 12. The server survives malformed and unauthenticated traffic — tests/direct_udp.rs malformed/auth-rejection cases and encrypted bad-secret integration tests.
• 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.
• 14. TOML configuration is clearly validated — src/config.rs tests and tests/server_capabilities.rs cover role, transport, listener, and datagram boundaries.
• 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.
• 16. Reconnects occur automatically — bounded supervisor backoff and server-restart proof in tests/reconnect.rs and tests/encrypted_runtime.rs.
• 17. Automated integration tests cover multi-client operation — direct, encrypted, and HTTP/3 runtime integration suites.

Required evidence before v1 sign-off

• 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.
• 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.
• 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.
• 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.