checkpoint: implement wgcloak v1 foundations

README.md

@@ -0,0 +1,98 @@
+# wgcloak
+
+wgcloak is a Linux userspace relay for opaque UDP datagrams. It is intended to
+carry WireGuard traffic, but does not configure, inspect, or depend on
+WireGuard: the same relay can carry any UDP application.
+
+The design keeps four concerns separate:
+
+```text
+local UDP application -> tunnel core -> selected transport -> tunnel core
+                                                     -> backend UDP application
+```
+
+The server gives each authenticated client its own backend UDP socket. The
+application payload is not decoded or rewritten.
+
+## Status
+
+This checkout is specification-first and under active implementation. The
+milestone and v1 acceptance checklist is in
+[`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md). A
+transport is available only when its code, tests, and integration criteria are
+verified; the documentation intentionally does not imply that all four
+transports are already present.
+
+Target v1 transport order:
+
+1. direct UDP (Milestone 1)
+2. QUIC DATAGRAM (Milestone 2)
+3. HTTP/3 CONNECT-UDP (Milestone 4)
+4. TLS/TCP framed fallback (Milestone 5)
+
+## Build and install
+
+Rust and Cargo are required. From the repository root:
+
+```bash
+cargo test
+cargo build --release
+```
+
+For a host installation (choose a reviewed release artifact):
+
+```bash
+sudo install -Dm755 target/release/wgcloak /usr/local/bin/wgcloak
+sudo install -d -m0750 /etc/wgcloak
+```
+
+The binary name and subcommands are the intended interface from `spec.md`:
+
+```bash
+wgcloak client --config /etc/wgcloak/client.toml
+wgcloak server --config /etc/wgcloak/server.toml
+wgcloak check-config --config /etc/wgcloak/client.toml
+wgcloak generate-secret
+```
+
+Run `wgcloak --help` against the built binary to confirm the commands in the
+current build. QUIC, HTTP/3, control commands, and certificate reload are
+milestone-gated; see the checklist before deploying them.
+
+## Configuration
+
+Copy and edit one of the safe, placeholder-only examples:
+
+- [`examples/client.minimal.toml`](examples/client.minimal.toml)
+- [`examples/client.advanced.toml`](examples/client.advanced.toml)
+- [`examples/server.minimal.toml`](examples/server.minimal.toml)
+- [`examples/server.advanced.toml`](examples/server.advanced.toml)
+
+Put real secrets in separate files, owned by the service account, mode `0600`.
+Do not commit them. See [`docs/OPERATIONS.md`](docs/OPERATIONS.md) and
+[`docs/SECURITY.md`](docs/SECURITY.md).
+
+## Run with systemd
+
+The templates in [`packaging/systemd/`](packaging/systemd/) assume a dedicated
+`wgcloak` user, `/usr/bin/wgcloak`, and configuration under `/etc/wgcloak/`.
+Review paths and transport support before installing them. The server template
+includes hardening and a commented optional `CAP_NET_BIND_SERVICE` setting for
+ports below 1024; normal operation does not require `CAP_NET_ADMIN` or
+`CAP_SYS_ADMIN`.
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): process, data path, and ownership boundaries.
+- [`docs/PROTOCOL.md`](docs/PROTOCOL.md): direct packet model and transport contracts.
+- [`docs/OPERATIONS.md`](docs/OPERATIONS.md): files, control socket, lifecycle, and deployment.
+- [`docs/SECURITY.md`](docs/SECURITY.md): threat model, secrets, privileges, and non-goals.
+- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md): checks for common startup and connectivity failures.
+- [`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md): milestones 1–6 and all 17 v1 criteria.
+
+## Explicit non-goals
+
+wgcloak does not configure WireGuard, create TUN/TAP devices, change routes or
+firewalls, fragment application datagrams, spoof browser/TLS fingerprints, or
+provide clustering, roaming, a GUI, Windows/macOS support, or multiple client
+tunnels in v1.