wgcloak/docs/DEVELOPMENT_STATE.md

Development state

Checkpoint: 2026-09-19. Branch: main. HEAD: 49ec9d8 (docs: refresh development checkpoint). The working tree is not clean: this checkout contains concurrent implementation, documentation, benchmark, fuzz, and integration-test changes. No commit was created for this checkpoint.

Implemented behavior

• The package provides a reusable Rust library and thin binary. Integration tests use the library rather than path-including production modules.
• Client and server runtimes support authenticated direct UDP, QUIC DATAGRAM, HTTP/3 CONNECT-UDP with HTTP Datagrams, and TLS/TCP length-framed fallback. TLS client connections use normal certificate-chain and hostname verification. Shared-secret authentication precedes encrypted backend-session activation.
• auto follows configured transport order, uses bounded probes/retries, stops on authentication rejection, and reconnects with jittered 250 ms–30 s backoff. Successful connections reset the backoff.
• Enabled server listeners run concurrently, reject incompatible UDP bind conflicts, isolate backend UDP sockets per authenticated session, enforce admission limits, and publish aggregate status/statistics.
• The Unix control socket uses a private runtime directory and 0600 socket permissions. It refuses active sockets, removes only verified stale sockets, parses/serializes newline-delimited JSON structurally, limits concurrent clients, and bounds idle/oversized requests. status, stats, shutdown, and client-only reconnect are supported. reload explicitly reports unsupported.
• Secret-file loading opens one descriptor, uses Linux O_NOFOLLOW and O_NONBLOCK, validates a regular file and permissions from that descriptor, and reads the opened descriptor. Secret contents are not logged.
• Systemd templates run as an unprivileged user with hardening enabled; CAP_NET_BIND_SERVICE is documented as an optional, narrowly scoped aid for ports below 1024. No WireGuard, TUN/TAP, routing, or firewall management is implemented.
• tests/encrypted_runtime.rs covers daemon-level QUIC/TLS forwarding, authentication rejection, cancellation, session identity, and QUIC restart reconnect. tests/server_capabilities.rs covers the server datagram capability boundary.
• A deterministic Criterion target exists in benches/protocol_transports.rs for protocol/framing/HTTP Datagram/replay microbenchmarks. The repository also contains four isolated cargo-fuzz targets under fuzz/ for direct packets, TLS frames, HTTP/3 parsing, and TOML parsing.

Current worktree inventory

Modified files include Cargo.toml, Cargo.lock, README.md, docs/OPERATIONS.md, both advanced/minimal server examples, both systemd templates, runtime/config/control/server/transport sources, and related tests. Untracked assets include benches/, fuzz/, docs/BENCHMARKS.md, docs/FUZZING.md, tests/encrypted_runtime.rs, and tests/server_capabilities.rs. docs/DEVELOPMENT_STATE.md and docs/IMPLEMENTATION_CHECKLIST.md are also modified by this reconciliation. Treat these as shared worktree state; do not discard them with a cleanup command.

Verification performed in this worktree

The following checks passed:

• cargo fmt --all -- --check
• cargo check --all-targets
• cargo clippy --all-targets -- -D warnings
• cargo test --tests -- --test-threads=1 — 95 tests passed
• cargo bench --bench protocol_transports --no-run
• cargo check --manifest-path fuzz/Cargo.toml

cargo-fuzz is not installed on this host, so no fuzzing session or sanitizer run is claimed. No network/loopback benchmark was run; only deterministic benchmark compilation was checked. These gates ran against the shared dirty worktree, not a clean checkout.

Remaining work

Required before an unconditional release sign-off:

1. Re-run the documented gates from the final clean checkout after concurrent changes are integrated and reviewed.
2. Install/use cargo-fuzz and run bounded smoke sessions for each target; retain the compile-only result as the current evidence until then.
3. Make and test a final practical datagram-size-cap decision. The benchmark analysis recommends 1200 bytes, while configuration still permits the larger protocol-bound ceiling.

Optional or explicitly out of scope for the current prototype:

• Config and certificate/key reload remain unsupported; the control command reports this explicitly. Spec language makes certificate reload desirable but optional and does not require full hot reload for the first milestone.
• A network benchmark remains opt-in work because its results depend on host scheduling, kernel buffers, MTU, and runtime conditions. The deterministic microbenchmarks are present and compile.
• A measured benchmark report and sanitizer fuzz report are release artifacts, not evidence currently available from this host.

First three recovery/release tasks

1. Review and commit the shared implementation/docs/bench/fuzz work as one coherent checkpoint, then repeat the full gates from that clean checkout.
2. Run the four cargo-fuzz targets for bounded smoke sessions and record the toolchain/host results in the fuzzing notes.
3. Decide whether to enforce the documented 1200-byte practical cap or retain the protocol-bound configurable ceiling, then add the corresponding boundary evidence and update the acceptance checklist.