wgcloak/docs/IMPLEMENTATION_CHECKLIST.md

Implementation and acceptance checklist

This is a coordinator checklist, not a claim that the items are complete. Mark an item only with code evidence, tests, and an integration result. Record the commit/test command or issue beside each checked item. A feature marked planned in the other documents must remain visibly planned here until proven.

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"; direct UDP then QUIC; 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; certificate and configuration reload; benchmarks; fuzzing; installation docs.

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.