thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release v1.1.0

Browse Source
This commit is contained in:
thakares committed 2026-09-02 15:19:19 +05:30
1 parent 34227efd2b
commit edc710cbd2
46 files changed
+5324 -190
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/ARCHITECTURE.md
+54 -1
View File
@@ -102,5 +102,58 @@ flowchart TD
1. **Subprocess Isolation**: Zero invocations of `std::process::Command` or shell scripts across the entire production codebase.
2. **Persistence Authority**: SQLite remains the single authoritative source of truth. Kernel state is continuously reconciled to match database state.
3. **Firewall Isolation**: All nftables operations are confined to `table inet nx9_wg`. Unmanaged host tables are untouched.
4. **Route Safety**: Default gateway routes and host networking routes are protected against accidental deletion or flushing.
4. **Route Safety**: Default gateway routes and physical host networking routes are protected against accidental deletion or flushing.
5. **Secret Redaction**: Private keys, preshared keys, password hashes, and token hashes are masked in `Debug` formatters, CLI outputs, and API responses.
---
## 4. Interface Roles & Upstream Architecture
`nx9-wg` implements explicit `InterfaceRole` categorization across domain models, Netlink device configuration, and reconciliation:
```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ Linux Host Network │
│ │
│ ┌────────────────────────────────┐ ┌──────────────────────────────────┐ │
│ │ Primary Overlay (wg0) │ │ Optional Upstream (proton0) │ │
│ │ Role: Overlay │ │ Role: Upstream │ │
│ │ Local Listen Port: 51820 │ │ Local Listen Port: Auto (Dyn) │ │
│ │ Peers: 1..N Clients (Mobile) │ │ Peers: Exactly 1 Provider Peer │ │
│ │ Cryptokey AllowedIPs: /32 │ │ Cryptokey AllowedIPs: 0/0, ::0 │ │
│ └────────────────────────────────┘ └──────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────┐ ┌──────────────────────────────────┐ │
│ │ Private Overlay Clients │ │ Remote Provider Endpoint │ │
│ │ (10.100.0.0/24 Subnet) │ │ (37.19.199.155:51820) │ │
│ └────────────────────────────────┘ └──────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ Physical WAN Default Route (eno2) │ │
│ │ Gateway: 192.168.1.1 (FIB Unchanged) │ │
│ └────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────────────┘
```
### A. Role Discriminator & Invariants
- **`InterfaceRole::Overlay`**: The primary private WireGuard overlay network. Exactly one instance exists (`wg0`). It binds to an explicit listen port (`51820`), hosts enrolled client peers, and is protected from deletion or disabling.
- **`InterfaceRole::Upstream`**: Optional third-party WireGuard VPN interfaces (e.g. `proton0`). Zero or more instances may exist concurrently. Each Upstream interface connects NX9-WG to an external service provider through exactly one provider peer.
### B. Optional Local Listen Port & Ephemeral Kernel Binding
- `Interface.listen_port` is modeled as `Option<u16>`.
- Standard third-party `.conf` imports (e.g. ProtonVPN) omit `[Interface] ListenPort`. NX9-WG preserves `listen_port = None` without defaulting to `51820`.
- In `configure_device`, omitting the `WireguardAttribute::ListenPort` Netlink attribute signals the Linux kernel to assign an ephemeral dynamic UDP port automatically.
- This prevents local UDP port contention and allows `wg0` (51820) and `proton0` (dynamic) to coexist without `-EADDRINUSE` errors.
- Dynamic kernel ports produce 0 false drift actions in the reconciliation engine when desired `listen_port` is `None`.
### C. Cryptokey Routing vs. Linux FIB Default Routes
- An Upstream provider peer often specifies `AllowedIPs = 0.0.0.0/0, ::/0` in its `.conf`.
- In WireGuard, `AllowedIPs` defines the device-level cryptokey packet routing filter; it does **not** install a Linux kernel route.
- NX9-WG preserves `0.0.0.0/0, ::/0` on the `proton0` WireGuard device without modifying the server's Linux FIB default gateway (`192.168.1.1`).
- The provider endpoint (`37.19.199.155:51820`) remains reachable via the host physical WAN interface.
### D. NAT Masquerade Isolation
- Outbound NAT masquerading compiled into `table inet nx9_wg` is strictly scoped to Overlay client subnets (`10.100.0.0/24`).
- Upstream tunnel addresses (`10.2.0.2/32`) are not treated as client subnets and do not trigger unsolicited global masquerading.