wgcloak/docs/IMPLEMENTATION_CHECKLIST.md

# Implementation and acceptance checklist

This evidence-based checklist records the implementation and license baseline
at commit `5767b90` (`release: finalize wgcloak v1 under GPLv3`). The final
documentation closeout is the only work that follows that baseline; the gates
below were run against the committed implementation. Package metadata and
`LICENSE` use SPDX `GPL-3.0-only`. Optional deferred work is called out
explicitly and is not treated as an unimplemented v1 transport.

## 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`.
- [x] **6 — operational polish:** Control, validation, hardened systemd units,
  capability guidance, deterministic benchmark assets, fuzz targets, and
  installation documentation are present (`src/control.rs`, `tests/control.rs`,
  `packaging/systemd/`, `benches/`, `fuzz/`, `README.md`). The configured
  default is 1,200 bytes and the validated project ceiling is 16,384 bytes.
  Oversized-datagram metrics remain visible in aggregate status/statistics;
  `src/server/mod.rs::record_transport_drop` and
  `oversized_transport_error_is_counted_once` cover the latest repaired
  boundary accounting.
  Config/certificate reload remains explicitly unsupported; cargo-fuzz smoke
  execution and environment-sensitive network benchmarking are optional
  deferred validation artifacts.

## 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 the
  1,200-default/16,384-ceiling 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; this is optional deferred validation.
- [x] Release gates passed against the committed `5767b90` implementation
  baseline before this documentation closeout: `cargo fmt --all
  -- --check`, `cargo check --all-targets`, strict all-target Clippy,
  `cargo test --tests -- --test-threads=1` (100 passed),
  `cargo check --manifest-path fuzz/Cargo.toml`, 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. Config/certificate reload remains
  an explicit unsupported optional feature.