wgcloak/docs/IMPLEMENTATION_CHECKLIST.md

Implementation and acceptance checklist

This is a coordinator checklist, not a claim that v1 is signed off. The current runtime has code paths for all four carriers, configured auto selection, client reconnect backoff, and local control commands. Mark an acceptance item only with code evidence, tests, and an integration result; record the test command or issue beside each checked item.

Milestones 1–6

• 1 — authenticated direct relay: local UDP listener; direct UDP handshake; HMAC-authenticated data; replay window; keepalive/expiry; one backend UDP socket per authenticated client; multi-client isolation; TOML; logs and basic stats.
• 2 — QUIC DATAGRAM: certificate loading and hostname verification; client challenge/response; datagrams; keepalive/MTU; reconnect; multi-client handling without core API redesign.
• 3 — automatic selection: mode = "auto"; configured order across direct UDP, QUIC, HTTP/3, and TLS/TCP; bounded probes/retries; auth rejection stops probing; jittered reconnect; status reports selected transport.
• 4 — HTTP/3 CONNECT-UDP: standard CONNECT-UDP/HTTP Datagram semantics; authentication; backend mapping; reuse QUIC infrastructure where practical.
• 5 — TLS/TCP fallback: TLS listener; client authentication; bounded big-endian length framing; bidirectional datagram reconstruction; fallback integration; expected head-of-line behavior documented.
• 6 — operational polish: Unix control socket; status/stats/reconnect commands; config validation; systemd units; capability guidance; benchmarks; fuzzing; installation docs. Config and certificate/key reload are not implemented; the control command explicitly reports reload as unsupported.

v1 completion criteria (spec §89)

• 1. Multiple clients concurrently reach one UDP backend.
• 2. No WireGuard-specific logic exists.
• 3. Direct UDP works reliably.
• 4. QUIC DATAGRAM works reliably.
• 5. HTTP/3 CONNECT-UDP works.
• 6. TLS/TCP fallback works.
• 7. Automatic transport selection works.
• 8. Authentication is enforced on every public transport.
• 9. Direct UDP has replay and integrity protection.
• 10. Direct UDP NAT rebinding works.
• 11. Sessions expire and clean up correctly.
• 12. The server survives malformed and unauthenticated traffic.
• 13. The daemon runs unprivileged except optional bind capability.
• 14. TOML configuration is clearly validated.
• 15. Meaningful status and statistics are available.
• 16. Reconnects occur automatically.
• 17. Automated integration tests cover multi-client operation.

Required evidence before v1 sign-off

• Unit tests cover parsing, malformed input, auth, key derivation, replay, config validation, and timeout logic.
• Integration tests cover direct client/server, concurrent clients, source-port change, auth rejection, restart/reconnect, backend outage, oversized datagrams, and expiry; later transports have equivalent coverage.
• Fuzz targets exercise direct packets, TCP frames, and auth messages.
• cargo test, formatting, linting, and any documented integration/bench commands pass from a clean checkout.
• Review confirms no payload/secret logging, no unsafe privilege grant, and no accidental WireGuard/routing/firewall coupling.