ci+docs: no-sodium Linux lane + frame libsodium as optional (closes #102)

.github/workflows/ci.yml

@@ -50,3 +50,27 @@ jobs:
 
       - name: Test
         run: zig build test
+
+  no-sodium-linux:
+    name: Build + Test (ubuntu, std.crypto / no libsodium)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Deliberately do NOT install libsodium-dev — this lane proves the
+      # std.crypto path builds and tests on Linux with no libsodium present
+      # (regression guard for the optional-libsodium work, meshguard#102).
+
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
+      - name: Build (std.crypto, no libsodium)
+        run: zig build -Dno-sodium=true
+
+      - name: Build ReleaseFast (std.crypto, no libsodium)
+        run: zig build -Dno-sodium=true -Doptimize=ReleaseFast
+
+      - name: Test (std.crypto, no libsodium)
+        run: zig build test -Dno-sodium=true

README.md

@@ -272,7 +272,10 @@ docker compose -f docker-compose.bench.yml up
 
 - **Zig 0.16+**
 - **Linux** (kernel WireGuard module _or_ TUN device support)
-- **libsodium** (`libsodium-dev` for building, `libsodium23` at runtime)
+- **libsodium** — _optional_ AVX2 accelerator, on by default on Linux
+  (`libsodium-dev` to build, `libsodium23` at runtime). Build with
+  `-Dno-sodium=true` / `-Dcrypto-backend=std` to use `std.crypto` instead and drop
+  the dependency entirely (see [Crypto backend](#crypto-backend)).
 - `sudo` or `CAP_NET_ADMIN` for interface creation
 
 ### macOS
@@ -336,6 +339,34 @@ zig build -Dtarget=aarch64-ios -Doptimize=ReleaseFast
 Windows builds automatically bundle `wintun.dll` alongside `meshguard.exe`.
 Android builds produce only `libmeshguard-ffi.so` — the CLI binary, static library, and unit tests are excluded.
 
+### Crypto backend
+
+MeshGuard's **required** crypto primitives — ChaCha20-Poly1305 (AEAD), Ed25519
+(signatures), X25519 (key exchange) — are always available via Zig's `std.crypto`.
+**libsodium is an optional implementation accelerator**, not a dependency: its
+hand-written AVX2 ChaCha20-Poly1305 is ~2× faster than `std.crypto` at MTU/bulk
+sizes on Linux x86_64, so it is auto-selected there. Everywhere else
+(macOS/FreeBSD/Windows/Android/iOS) `std.crypto` is used.
+
+Select the backend with `-Dcrypto-backend` (or the `-Dno-sodium=true` alias):
+
+| Build flag | Backend |
+|---|---|
+| _(default)_ / `-Dcrypto-backend=auto` | libsodium on Linux desktop, `std.crypto` elsewhere |
+| `-Dno-sodium=true` / `-Dcrypto-backend=std` | `std.crypto` everywhere — **no libsodium**, no `libsodium-dev` |
+| `-Dcrypto-backend=sodium` | force libsodium (link must be available for the target) |
+
+```bash
+# Build + test on Linux with zero libsodium dependency:
+zig build -Dno-sodium=true
+zig build test -Dno-sodium=true
+```
+
+The choice is resolved in `build.zig` and passed to the source via `build_options`,
+so the compiled code and the linker always agree. Downstream packages that embed
+MeshGuard from source can pass the same `use_libsodium` option through and never
+touch system libsodium.
+
 ## Status
 
 Core functionality is implemented and under active benchmarking:

docs/guide/getting-started.md

@@ -33,12 +33,12 @@ You can also download binaries directly from the [releases page](https://github.
 
 ## Building from source
 
-Alternatively, build from source with [Zig](https://ziglang.org/download/) 0.15+:
+Alternatively, build from source with [Zig](https://ziglang.org/download/) 0.16+:
 
 | Requirement     | Linux                                            | Windows                            |
 | --------------- | ------------------------------------------------ | ---------------------------------- |
-| **Zig**         | 0.15 or later                                    | 0.15 or later                      |
-| **libsodium**   | `libsodium-dev` for building                     | Not required                       |
+| **Zig**         | 0.16 or later                                    | 0.16 or later                      |
+| **libsodium**   | _optional_ — `libsodium-dev` for the AVX2 accelerator (default); build `-Dno-sodium=true` to use `std.crypto` and skip it | Not required |
 | **OS**          | Kernel WireGuard module _or_ TUN support         | Windows 10+ with Wintun            |
 | **Permissions** | `sudo` or `CAP_NET_ADMIN` for interface creation | Administrator for `meshguard up`   |
 

docs/guide/macos-support.md

@@ -27,14 +27,18 @@ macOS shares most of Linux's POSIX API surface. The gap is much smaller than Win
 
 ### Phase 1: AEAD Backend (Already Done)
 
-The `use_libsodium` flag already handles this:
+The `use_libsodium` flag already handles this. It is resolved in `build.zig`
+(from `-Dcrypto-backend` / `-Dno-sodium=true`) and read by the source via
+`build_options`:
 
 ```zig
 // src/wireguard/tunnel.zig
-const use_libsodium = (builtin.os.tag == .linux and builtin.target.abi != .android);
+const use_libsodium = @import("build_options").use_libsodium;
 ```
 
-For macOS, this evaluates to `false` → uses `std.crypto.aead.chacha_poly.ChaCha20Poly1305`. No changes needed.
+For macOS this is `false` → uses `std.crypto.aead.chacha_poly.ChaCha20Poly1305`.
+No changes needed. (On Linux it defaults to `true`; `-Dno-sodium=true` forces
+`false` there too.)
 
 ### Phase 2: utun Device