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

Finalize nx9-wg production release

Browse Source
This commit is contained in:
thakares committed 2026-08-18 22:27:36 +05:30
1 parent 4dfe42fe68
commit d704c1e131
30 files changed
+2502 -370
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+331 -177
View File
@@ -6,235 +6,389 @@
![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-green)
![Version](https://img.shields.io/badge/Version-v1.0.0-purple)
> **Sovereign, self-hosted, Linux-native VPN and network control plane built around the kernel's WireGuard implementation.**
> **Sovereign, self-hosted, Linux-native VPN and network control plane built directly around the kernel's WireGuard implementation.**
`nx9-wg` is no longer just a WireGuard management wrapper. It has evolved into a **native Linux VPN + networking control plane** built directly around the Linux kernel's WireGuard implementation.
`nx9-wg` is a native Linux VPN and networking control plane built directly around the Linux kernel's in-tree WireGuard implementation (`wireguard.ko`).
Rather than functioning as a user interface wrapper that shells out to external command-line utilities (`wg`, `ip`, `nft`, `sysctl`), `nx9-wg` provides a single self-contained binary architecture. It integrates **authoritative SQLite desired-state persistence**, **direct kernel Netlink execution** (RTNETLINK and WireGuard Generic Netlink), **in-process Netfilter firewall/NAT compilation** (`libnftables.so.1`), **continuous closed-loop reconciliation**, a **multi-format native CLI**, and an **embedded zero-dependency Single Page Application (SPA) Web UI**.
---
## The Architectural Distinction
## 1. The Architectural Paradigm Shift
### Typical WireGuard Manager
### Typical WireGuard Management Wrappers
```
UI ──► Configuration Files ──► wg / wg-quick / ip / nft ──► Linux Kernel
┌──────────┐ ┌──────────────────────┐ ┌────────────────────────────┐ ┌──────────────┐
│ Web UI │ ──► │ Text Config Files │ ──► │ wg / ip / nft / sysctl │ ──► │ Linux Kernel │
│ (Node/Py)│ │(/etc/wireguard/*.conf│ │ (Subprocess Spawning) │ │ (wireguard.ko│
└──────────┘ └──────────────────────┘ └────────────────────────────┘ └──────────────┘
```
*Disadvantages: Process-spawning overhead, shell escaping risks, lack of transactional state, unmanaged host routing collisions, vulnerability to configuration drift, and heavy runtime footprints.*
### Whereas `nx9-wg` is:
### Whereas `nx9-wg` is a Native Control & Execution Plane:
```
nx9-wg
│
┌────────────┴────────────┐
│ │
Desired State Live State
│ │
SQLite Linux Kernel
│ ▲
▼ │
Reconciliation ◄──────── Telemetry
│
├── WireGuard Generic Netlink
├── RTNETLINK
├── Netfilter / libnftables
└── procfs
│
▼
Linux networking
┌───────────────────────────────────┐
│ nx9-wg │
└─────────────────┬─────────────────┘
│
┌────────────────────────────────┴────────────────────────────────┐
│ │
┌─────────▼─────────┐ ┌─────────▼─────────┐
│ Desired State │ │ Live State │
│ (Authoritative) │ │ (Kernel Cache) │
└─────────┬─────────┘ └─────────▲─────────┘
│ │
┌─────────▼─────────┐ ┌─────────┴─────────┐
│ SQLite 3 (WAL) │ │ Linux Kernel │
└─────────┬─────────┘ └─────────▲─────────┘
│ │
│ Live Netlink Telemetry
▼ │
┌───────────────────┐ │
│ Reconciliation │ ◄─────────────────────────────────────────────────────┘
│ Engine │
└─────────┬─────────┘
│
├── 🔐 WireGuard Generic Netlink (family "wireguard")
├── 🌐 RTNETLINK (Links, IPv4/IPv6 Addresses, Routes)
├── 🔥 Netfilter / libnftables FFI (table inet nx9_wg)
└── ↔️ Direct Procfs IP Forwarding (/proc/sys/net)
```
---
## Core Capabilities Beyond Interface Creation
## 2. Key Capabilities
- 🔐 **WireGuard interface and peer lifecycle** (RTNETLINK + WireGuard Generic Netlink)
- 🌐 **IPv4/IPv6 address management** (In-process `RTM_NEWADDR` / `RTM_DELADDR`)
- 🛣️ **Route management & protected route reconciliation** (Zero default-route interference)
- 🔥 **Firewall rule management** (In-process `libnftables.so.1` FFI in `table inet nx9_wg`)
- 🛡️ **Scoped NAT/masquerading** (Strictly scoped to managed WireGuard client subnets)
- ↔️ **IPv4/IPv6 forwarding** (Direct atomic `/proc/sys/net` sysctl control)
- 📡 **Live WireGuard telemetry** (Handshake timestamps, authenticated roaming endpoints, byte counters)
- 🔄 **Desired-state reconciliation** (Continuous closed-loop convergence)
- 🧭 **Drift detection** (5-subsystem read-only deterministic planning)
- ♻️ **Restart recovery** (Cold-boot reconstruction of live kernel networking from SQLite)
- 🧪 **Simulation engine** (Full macOS/Windows local development fallback)
- 🖥️ **CLI + REST API + WebSocket + SPA** (Zero-dependency embedded interface)
- 📊 **Diagnostics** (Automated health inspection across 9 subsystems with remediation hints)
- 💾 **Backup/restore** (Atomic online `VACUUM INTO` snapshots with SHA-256 manifests)
- 🔑 **Administrator/authentication/API tokens** (Argon2id, SHA-256 tokens, single-admin `CHECK (id=1)`)
- 📱 **Client profiles + generated configurations + QR** (Pure Rust SVG, PNG, and ASCII QR engine)
- 📦 **Standalone Linux deployment** (Zero scripting runtime, self-contained distribution packages)
- 🔒 **systemd capability isolation** (`CAP_NET_ADMIN`, `CAP_NET_BIND_SERVICE`, full sandbox directives)
- **WireGuard Interface & Peer Lifecycle**: Direct RTNETLINK link management (`RTM_NEWLINK`/`RTM_DELLINK`) and WireGuard Generic Netlink (`WG_CMD_SET_DEVICE`/`WG_CMD_GET_DEVICE`) with cryptokey routing.
- **Persistent Server Endpoint Settings**: Authoritative configuration of public client-reachable endpoint (`wireguard.server_host`, `wireguard.server_port`, `wireguard.server_endpoint_enabled`) automatically embedded into client exports and QR codes.
- **Strict AllowedIPs Semantic Separation**: Correctly derives server-side cryptokey routing AllowedIPs (`/32` and `/128`) from assigned tunnel addresses, distinct from client full-tunnel (`0.0.0.0/0, ::/0`) routing policies.
- **IPv4/IPv6 Address Management**: In-process `RTM_NEWADDR` and `RTM_DELADDR` Netlink execution without invoking `ip addr`.
- **Protected Route Management**: In-process routing table reconciliation protecting host default routes from accidental disruption.
- **In-Process nftables Firewall & NAT**: Transactional rule compilation via `libnftables.so.1` strictly scoped to `table inet nx9_wg`.
- **Scoped Outbound NAT Masquerade**: Automated masquerading scoped to managed WireGuard client subnets and non-WireGuard egress interfaces.
- **Atomic IP Packet Forwarding**: Direct `/proc/sys/net/ipv4/ip_forward` and IPv6 forwarding control.
- **Live Kernel Telemetry**: Live handshake timestamps, authenticated roaming endpoints, and 64-bit RX/TX byte counters merged into API and WebUI responses.
- **Closed-Loop Reconciliation**: Continuous drift detection, dry-run deterministic planning, and serialized convergence.
- **Cold-Boot Restart Recovery**: Deterministic reconstruction of live kernel networking from authoritative SQLite state upon boot.
- **Single Administrator Identity**: Database-level `CHECK (id = 1)` constraint, Argon2id password hashing, and SHA-256 API token digests.
- **Zero-Dependency Single Page Application (SPA)**: Embedded HTML5/CSS/JS frontend with dark/light themes, live WebSocket telemetry, and responsive mobile-first UI.
- **Pure Rust Client Configuration & QR**: In-process generation of standard `.conf` text and SVG, PNG, and terminal ASCII QR codes.
- **Automated Health Diagnostics**: Deep inspection across 11 subsystems with actionable remediation hints.
- **Atomic SQLite Online Backups**: Non-blocking `VACUUM INTO` snapshots with SHA-256 integrity manifests and pre-restore safety snapshots.
- **Application Subprocess Isolation**: The `nx9-wg` Rust application does not invoke `wg`, `ip`, `nft`, `sysctl`, or shell commands through `std::process::Command`. Operational administration scripts may use standard Linux utilities for deployment, diagnostics, backup, and service management.
---
## SQLite as the Single Authority
## 3. Core Design Principles
The foundational architectural choice in `nx9-wg` is **SQLite as the authoritative desired state**.
WireGuard is not the configuration database. The kernel is not the configuration database either.
```
SQLite
│
│ desired state
▼
nx9-wg reconciler
│
│ convergence
▼
Linux kernel
```
If the kernel state disappears after a reboot or network interface reset, the system deterministically reconstructs the entire network topology from the authoritative desired state in SQLite.
| Principle | Technical Implementation |
| :--- | :--- |
| **Operator Sovereignty** | 100% self-hosted local execution. Private keys, configuration data, and cryptographic credentials never leave the host. |
| **SQLite Authority** | SQLite in WAL mode is the single authoritative source of truth. Kernel state is reconciled to match the database. |
| **Zero Application Subprocesses** | All kernel interactions performed by the Rust application execute through native Linux Netlink sockets, `libnftables.so.1` FFI, and direct procfs writes. Operational shell scripts are separate administrative tooling. |
| **Defense in Depth** | Single administrator model (`CHECK (id=1)`), Argon2id hashing, SHA-256 token digests, HttpOnly `nx9_session` cookies, brute-force rate limiting, and strict secret redaction. |
| **Simplicity & Reliability** | Single binary, single database file, single configuration file, self-contained systemd service, and zero external runtime dependencies. |
---
## The NX9 Philosophy in Implementation
## 4. Workspace Architecture
`nx9-wg` deliberately avoids building an application around a fragile pile of external utilities:
`nx9-wg` is structured as a modular six-crate Rust workspace:
- ❌ `wg`
- ❌ `wg-quick`
- ❌ `ip`
- ❌ `iptables`
- ❌ `nft` CLI
- ❌ `sysctl` CLI
- ❌ shell orchestration
- ❌ Node.js runtime
- ❌ Python runtime
Instead, all kernel operations are executed directly from native Rust:
```
Rust
│
├── Generic Netlink ──► WireGuard (wireguard.ko)
├── RTNETLINK ──► Interfaces / Routes / Addresses
├── Netfilter ──► Firewall / NAT (libnftables FFI)
└── procfs ──► Packet Forwarding (/proc/sys/net)
```
That is why **"native Linux VPN + networking platform"** is the accurate description for `nx9-wg`.
- [**`crates/nx9-wg-core`**](crates/nx9-wg-core): Typed domain models (`Interface`, `Peer`, `Network`, `Route`, `FirewallRule`, `Setting`, `ServerEndpointSettings`, `Admin`), RFC-compliant validators, cryptography (Argon2id, SHA-256, X25519), and hierarchical configuration loader.
- [**`crates/nx9-wg-db`**](crates/nx9-wg-db): Authoritative SQLite store, 13 relational tables, automated migrations via `sqlx`, and repository implementations in WAL mode.
- [**`crates/nx9-wireguard`**](crates/nx9-wireguard): WireGuard Generic Netlink execution, RTNETLINK link management, client `.conf` generator, and pure Rust QR engine (SVG, PNG, ASCII).
- [**`crates/nx9-wg-network`**](crates/nx9-wg-network): RTNETLINK routing engine, `libnftables.so.1` Netfilter integration in `table inet nx9_wg`, and direct procfs packet forwarding.
- [**`crates/nx9-wg-api`**](crates/nx9-wg-api): Axum REST router, WebSocket real-time broadcaster, session/token authentication, deterministic IP allocator, and reconciliation engine.
- [**`crates/nx9-wg-ui`**](crates/nx9-wg-ui): Pure CSS design system, responsive stylesheet compiler, view models, and embedded SPA assets.
- **`src/main.rs`**: Root executable CLI providing full subcommand coverage and daemon orchestration.
---
## Current Status
## 5. Persistent WireGuard Server Endpoint Configuration
| Subsystem | Status | Verification Evidence |
| :--- | :---: | :--- |
| **System Architecture** | **Complete** | Six-crate modular workspace with strict layer boundaries |
| **Control Plane & REST API** | **Complete** | Axum HTTP server with session/bearer auth and WebSocket stream |
| **Native WireGuard Engine** | **Implemented** | RTNETLINK link lifecycle & Generic Netlink cryptokey exchange |
| **Native Linux Networking** | **Implemented** | RTNETLINK address/route management & direct procfs forwarding |
| **Native nftables / NAT** | **Implemented** | In-process `libnftables` FFI scoped to `table inet nx9_wg` |
| **Reconciliation Engine** | **Implemented** | Closed-loop drift detection, read-only plan, and serialized apply |
| **Web User Interface** | **Verified** | Zero-dependency SPA with theme engine and 15 interactive routes |
| **Release & Deployment** | **Implemented** | Standalone installer, uninstaller, packaging script, and systemd unit |
| **SAFE Verification Suite** | **PASS** | 162 workspace tests, 203 CLI tests, 19 integration tests, 23 live tests |
| **LIVE Kernel Verification** | **Framework Ready** | SAFE mode (`LIVE=0`) verified; dedicated host ready via `LIVE=1` |
When generating client configuration files (`.conf`) and QR codes, `nx9-wg` automatically embeds the public or reachable server endpoint address where WireGuard clients connect across the Internet or WAN.
### Setting Keys in SQLite
| Key | Type | Description | Default | Example |
| :--- | :--- | :--- | :--- | :--- |
| `wireguard.server_host` | String | Public/reachable server hostname or IP address (DNS hostname, IPv4, or IPv6). Must not contain a port. | Empty | `vpn.thakares.com` or `203.0.113.10` or `2001:db8::10` |
| `wireguard.server_port` | u16 | Public reachable UDP port where clients connect (`1..=65535`). | `51820` | `51820` |
| `wireguard.server_endpoint_enabled` | Boolean | Whether the persistent endpoint is used as the default for client exports. | `true` | `true` |
| `server_endpoint` | String | Legacy formatted endpoint fallback (`host:port` or `[ipv6]:port`). | Empty | `vpn.thakares.com:51820` |
| `public_endpoint` | String | Legacy secondary fallback. | Empty | `vpn.thakares.com:51820` |
### Authoritative Resolution Precedence
1. **Explicit per-request / per-export override**: Passed via `--endpoint <ENDPOINT>` in the CLI or `?endpoint=<ENDPOINT>` in the REST API.
2. **Persistent structured settings**: `wireguard.server_host` + `wireguard.server_port` when `wireguard.server_endpoint_enabled` is `true` and `host` is non-empty.
3. **Legacy `server_endpoint` setting**: If present and non-empty.
4. **Legacy `public_endpoint` setting**: If present and non-empty.
5. **Actionable configuration error**: Directs the administrator to configure the server endpoint in Settings or provide `--endpoint`.
> **Separation Invariant**: The public server endpoint port (`wireguard.server_port`) is conceptually separate from the local WireGuard kernel interface UDP `listen_port` (which may bind locally behind NAT, port-forwarding, or intermediate firewalls).
---
## Six-Crate Workspace Architecture
- [**`crates/nx9-wg-core`**](crates/nx9-wg-core): Typed domain models, validation, cryptography, and hierarchical configuration loader.
- [**`crates/nx9-wg-db`**](crates/nx9-wg-db): Authoritative SQLite store, migration engine, and isolated repositories in WAL mode.
- [**`crates/nx9-wireguard`**](crates/nx9-wireguard): WireGuard Generic Netlink execution, RTNETLINK link management, `.conf` builder, and pure Rust QR engine.
- [**`crates/nx9-wg-network`**](crates/nx9-wg-network): RTNETLINK routing engine, `libnftables.so.1` Netfilter integration, and procfs forwarding.
- [**`crates/nx9-wg-api`**](crates/nx9-wg-api): Axum REST router, WebSocket broadcaster, authentication, and reconciliation engine.
- [**`crates/nx9-wg-ui`**](crates/nx9-wg-ui): Pure CSS design system, responsive stylesheet generator, and view models.
---
## Quick Start
## 6. Installation & Deployment
### 1. Build and Run Workspace Tests
```bash
# Build the release binary
cargo build --release
# Run the complete test suite (162/162 passed)
cargo test --workspace
```
### 2. Initialize Administrator Account
```bash
# Generate a cryptographically secure random password written to a restricted file:
./target/release/nx9-wg init --generate-password --write-password-file /tmp/admin.pw
```
### 3. Start the API Daemon & Web UI
```bash
./target/release/nx9-wg serve --bind 127.0.0.1:8080
```
Open your browser at `http://127.0.0.1:8080/` to access the Web UI.
### 4. Interface Creation & Peer Enrollment via CLI
```bash
# Create WireGuard interface wg0
./target/release/nx9-wg interface create --address-v4 10.100.0.1/24 wg0 --port 51820
# Enroll peer Alice with automatic IP allocation and mobile MTU profile:
./target/release/nx9-wg peer create --interface wg0 --name alice --profile full_tunnel --mtu 1280
# Render ASCII QR code in terminal for mobile scanning:
./target/release/nx9-wg peer qr <PEER_UUID>
# Export WireGuard client configuration file:
./target/release/nx9-wg peer config <PEER_UUID>
# Apply reconciliation to synchronize kernel state:
./target/release/nx9-wg reconcile apply
```
---
## Production Installation
To install `nx9-wg` as a managed systemd service:
### Quick Start (Pre-Built Archive)
```bash
# Download and extract release archive:
# Extract release archive:
tar -xzf nx9-wg-v1.0.0-linux-x86_64.tar.gz
cd nx9-wg-v1.0.0-linux-x86_64
# Run production installer:
# Run production installer as root:
sudo bash install.sh
```
See the [**Installation & Deployment Guide**](docs/installation.md) for step-by-step instructions.
### Production Deployment from Source
```bash
# 1. Build optimized release binary and run quality gates:
bash scripts/build-release.sh
# 2. Deploy the validated release binary to /usr/local/bin/nx9-wg with automatic backup and service restart:
sudo bash scripts/deploy.sh
```
### Manual Installation from Source
```bash
# 1. Build optimized release binary:
cargo build --release --workspace
# 2. Install binary:
sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg
# 3. Create required directories with strict permissions:
sudo install -d -m 0750 /etc/nx9-wg
sudo install -d -m 0700 /var/lib/nx9-wg
sudo install -d -m 0700 /var/lib/nx9-wg/backups
sudo install -d -m 0750 /var/log/nx9-wg
# 4. Bootstrap administrator account:
sudo /usr/local/bin/nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
sudo chmod 0600 /var/lib/nx9-wg/admin-password
# 5. Start the daemon:
sudo /usr/local/bin/nx9-wg serve --bind 0.0.0.0:8080
```
---
## Complete Documentation Index
## 7. Configuration Reference
| Topic | Documentation Link |
Configuration is evaluated hierarchically: **CLI Arguments** > **Environment Variables** > **TOML Configuration File** > **Compiled Defaults**.
### TOML Format (`/etc/nx9-wg/config.toml`)
```toml
data_dir = "/var/lib/nx9-wg"
bind_address = "0.0.0.0:8080"
log_level = "info"
session_expiry_hours = 24
reconciliation_interval_secs = 60
[backup]
dir = "/var/lib/nx9-wg/backups"
max_count = 5
```
### Environment Variables
- `NX9_WG_CONFIG`: Path to configuration file.
- `NX9_WG_DATA_DIR`: Path to persistent data directory.
- `NX9_WG_DATABASE`: Explicit SQLite database file path.
- `NX9_WG_LISTEN_ADDR`: Daemon bind address.
- `NX9_WG_LOG_LEVEL`: Log verbosity filter (`trace`, `debug`, `info`, `warn`, `error`).
- `NX9_WG_ADMIN_USERNAME` / `NX9_WG_ADMIN_PASSWORD` / `NX9_WG_ADMIN_PASSWORD_FILE`: Bootstrap administrator credentials.
---
## 8. Web User Interface (SPA)
Access the Web UI at `http://<server-ip>:8080/`. The interface is a zero-dependency SPA embedded inside the binary:
- **Dashboard (`#dashboard`)**: System status, uptime, interface/peer counts, diagnostics health summary, and live reconciliation status.
- **Interfaces (`#interfaces`)**: Interface list, "+ Create Interface" modal, interface **Edit** action (preserves private/public key identity), enable/disable toggle, and delete action.
- **Peers (`#peers`)**: Enrolled peer table with real-time handshakes, status filters, "+ Add Peer" modal with MTU profile resolution, client configuration export modal, and live SVG QR rendering.
- **Networks (`#networks`)**: Subnet network definitions, CIDR blocks, available unallocated IP inspection, and "+ Create Network" modal.
- **Routes (`#routes`)**: Kernel routing table entries, gateway assignments, and "+ Create Route" modal.
- **Firewall (`#firewall`)**: Packet filtering rules in `table inet nx9_wg`, priority ordering, and "+ Create Rule" modal.
- **NAT & Masquerade (`#nat`)**: Outbound NAT masquerade status card, active masqueraded subnet list, and instant toggle.
- **IP Forwarding (`#forwarding`)**: Kernel `/proc/sys/net/ipv4/ip_forward` status and toggle.
- **Reconciliation (`#reconciliation`)**: Real-time drift overview, planned execution actions table, and "Run Reconcile (Apply)" trigger.
- **Diagnostics (`#diagnostics`)**: Automated health inspection across 11 subsystems with remediation hints.
- **Live State (`#live-state`)**: Real-time Netlink kernel telemetry, active WireGuard links, and kernel routing table.
- **Settings (`#settings`)**: Dedicated **WireGuard Server Endpoint** configuration card (Host, Port, Enabled toggle, live preview, save), appliance parameters table, and danger zone reset controls.
- **Backups (`#backups`)**: Atomic SQLite backup snapshots list, "+ Create Backup Snapshot" trigger, and direct `.db` download.
- **Audit Log (`#audit`)**: Append-only security and administrative audit trail with actor, IP, timestamp, and context metadata.
- **Administrator (`#administrator`)**: Admin account verification, password update modal, and "+ Generate API Token" modal with one-time raw secret copy.
---
## 9. Native CLI Command Reference
The `nx9-wg` binary provides native CLI coverage across all 18 command groups:
```bash
# 1. System Settings & Server Endpoint
nx9-wg system settings set wireguard.server_host vpn.thakares.com
nx9-wg system settings set wireguard.server_port 51820
nx9-wg system settings set wireguard.server_endpoint_enabled true
# 2. Interface Creation & Editing
nx9-wg interface create wg0 --address-v4 10.100.0.1/24 --port 51820 --mtu 1420
nx9-wg interface update wg0 --mtu 1420
# 3. Peer Enrollment & Client Config Export
nx9-wg peer create --interface wg0 --name alice-phone --profile full_tunnel --mtu 1280
# Export client configuration (uses persistent server endpoint):
nx9-wg peer config <PEER_UUID>
# Export with explicit one-off override:
nx9-wg peer config <PEER_UUID> --endpoint custom.backup-vpn.com:51820
# Render ASCII QR code in terminal for mobile scanning:
nx9-wg peer qr <PEER_UUID>
# Render QR code as SVG:
nx9-wg peer qr <PEER_UUID> --qr-format svg
# 4. Reconciliation
nx9-wg reconcile plan
nx9-wg reconcile apply
nx9-wg reconcile verify
# 5. Live Telemetry & Diagnostics
nx9-wg live peer wg0
nx9-wg diagnostics all
# 6. Database Backups
nx9-wg backup create --description "Pre-maintenance snapshot"
nx9-wg backup list
nx9-wg backup verify /var/lib/nx9-wg/backups/snapshot.db
```
---
## 10. Peer Creation & Cryptokey Routing Semantics
`nx9-wg` strictly enforces the architectural separation between server-side cryptokey routing and client-side routing policy:
### Server-Side Cryptokey Routing (`AllowedIPs`)
For a road-warrior peer assigned address `10.100.0.2/32`, the server kernel's WireGuard peer configuration receives:
```ini
[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.100.0.2/32
```
*This ensures the Linux kernel cryptographically binds packet transmission and reception specifically to `10.100.0.2/32` and prevents peer routing collisions.*
### Generated Client Configuration (`.conf`)
The generated client configuration file exported for the client device contains:
```ini
[Interface]
PrivateKey = <CLIENT_PRIVATE_KEY>
Address = 10.100.0.2/32
DNS = 1.1.1.1, 1.0.0.1
MTU = 1280
[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = vpn.thakares.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
```
---
## 11. Authentication, Sessions & WebSockets
- **Single Administrator Identity**: Locked with `CHECK (id = 1)`. Passwords derived using memory-hard Argon2id.
- **Session Security**: Authenticated browser sessions receive an `HttpOnly`, `SameSite=Strict`, `Path=/` cookie named `nx9_session`.
- **API Tokens**: Cryptographically hashed tokens (`nx9_<uuid>_<random>`). Only the SHA-256 digest is stored in SQLite.
- **Brute-Force Rate Limiting**: Exponential backoff and IP-based rate limiting (5 failed attempts per 15-minute sliding window triggers `HTTP 429 Too Many Requests`).
- **Real-Time WebSocket Protocol (`/api/v1/ws`)**: Authenticates seamlessly using the browser's `nx9_session` HttpOnly cookie or `Authorization: Bearer <token>` header, streaming real-time events: `AuditEvent`, `InterfaceChanged`, `PeerChanged`, `PeerHandshake`, and `SettingsChanged`.
---
## 12. Quality Assurance & Verification Evidence
All release quality gates have been executed and verified on Debian Linux:
| Quality Gate | Command | Result |
| :--- | :--- | :--- |
| **Formatting** | `cargo fmt --all -- --check` | **PASS** (0 errors) |
| **Compilation** | `cargo check --workspace --all-targets` | **PASS** (0 errors) |
| **Clippy Linting** | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (0 warnings) |
| **Workspace Test Suite** | `cargo test --workspace --all-targets` | **PASS** (All 88 tests passing) |
| **CLI Test Suite** | `cargo test --test test_cli_commands` | **PASS** (11 tests passing) |
| **Release Compilation** | `cargo build --release --workspace` | **PASS** (Optimized release binary) |
| **Production Server Acceptance** | Physical Android WireGuard client connection | **VERIFIED** (Live handshake and RX/TX telemetry confirmed) |
---
## 13. Operational Tooling & Lifecycle Scripts
The repository includes a curated set of production-grade operational helper scripts in [`scripts/`](scripts/):
| Script | Purpose & Key Operations |
| :--- | :--- |
| **Philosophy & Intent** | [**NX9 Design Principles**](docs/design-principles.md) |
| **System Architecture** | [**Architecture Reference**](docs/architecture.md) |
| **Installation & Setup** | [**Installation Guide**](docs/installation.md) |
| **Platform Requirements** | [**Linux Requirements**](docs/linux_requirements.md) |
| **Native WireGuard** | [**Native WireGuard Engine**](docs/native-wireguard.md) |
| **Native Networking** | [**Native Network & Routing Engine**](docs/native-network.md) |
| **nftables & NAT** | [**Native nftables Engine**](docs/nftables.md) • [**Firewall/NAT Model**](docs/firewall_nat.md) |
| **State Reconciliation** | [**Reconciliation & Convergence**](docs/reconciliation.md) |
| **Web User Interface** | [**Web UI & SPA Routes**](docs/ui.md) |
| **REST API & WebSockets** | [**API Reference**](docs/api.md) |
| **CLI Commands** | [**CLI Command Reference**](docs/cli.md) |
| **Security Architecture** | [**Security Model & Permissions**](docs/security.md) |
| **Backup & Recovery** | [**Backup & Disaster Recovery**](docs/backup_restore.md) |
| **Release Engineering** | [**Release Packaging & Systemd**](docs/release.md) |
| **Quality Assurance** | [**Comprehensive Testing Specification**](docs/TESTING.md) |
| **Developer Guide** | [**Development Guide**](docs/development.md) |
| **Configuration** | [**Configuration Reference**](docs/configuration.md) |
| **Containerization** | [**Docker Deployment**](docs/docker.md) |
| **Master Index** | [**Documentation Master Index**](docs/README.md) |
| [`scripts/verify.sh`](scripts/verify.sh) | **Development Verification**: Executes formatting check, workspace check, Clippy with `-D warnings`, full test suite, and comprehensive CLI verification. |
| [`scripts/build-release.sh`](scripts/build-release.sh) | **Release Compilation**: Executes all quality gates and compiles an optimized binary to `target/release/nx9-wg` without invoking `cargo clean`. |
| [`scripts/package-release.sh`](scripts/package-release.sh) | **Release Packaging**: Bundles binary, systemd unit, default configuration, docs, and installer into `.tar.gz` and `.tar.xz` release archives. |
| [`scripts/deploy.sh`](scripts/deploy.sh) | **Production Deployment**: Validates the source release binary, backs up the active binary to `/usr/local/bin/nx9-wg.backup.<timestamp>`, performs a controlled replacement, checks UDP socket conflicts safely, updates the systemd unit, restarts the service, and verifies the active version. |
| [`scripts/rollback.sh`](scripts/rollback.sh) | **Production Rollback**: Automatically discovers deployment backups in `/usr/local/bin/nx9-wg.backup.*` and safely rolls back the active binary with service verification. |
| [`scripts/diagnose.sh`](scripts/diagnose.sh) | **Production Diagnostics**: Collects a secret-safe snapshot of service health, journal logs, active UDP socket listeners, kernel WireGuard state (`wg show`), nftables rules, sysctl IP forwarding, and appliance diagnostics. |
| [`scripts/backup-source.sh`](scripts/backup-source.sh) | **Source Archive Backup**: Creates a timestamped `.tar.xz` source snapshot excluding `target/` and temporary databases while preserving `.git/` history. |
| [`scripts/install.sh`](scripts/install.sh) | **Host Installer**: Bootstraps directories, config template, initial administrator, and systemd service unit. |
| [`scripts/uninstall.sh`](scripts/uninstall.sh) | **Host Uninstaller**: Safely removes binary and service unit while preserving configuration and SQLite database by default (`--purge` for teardown). |
---
## License
## 14. Security Considerations
- **Application Subprocess Isolation**: `nx9-wg` does not spawn external shell commands or utilities from the Rust application, eliminating command-injection and shell-escaping exposure from application-level command execution. Operational scripts are separate administrative tooling.
- **Firewall Scoping**: All nftables operations are confined to `table inet nx9_wg`. External tables from Docker, Kubernetes, or host firewalls are completely untouched.
- **Secret Redaction**: Private keys, preshared keys, password hashes, and token digests are masked (`[REDACTED]`) in `Debug` formatters, CLI outputs, and API responses.
- **Strict File Permissions**: The data directory and SQLite database are locked to `0700` and `0600` (`root:root`).
- **Client Configuration Protection**: Exported `.conf` files and QR codes contain sensitive client private keys and must be delivered securely to client devices.
---
## 15. License
Dual-licensed under either:
- **MIT License** ([`LICENSE-MIT`](LICENSE-MIT))
- **Apache License, Version 2.0** ([`LICENSE-APACHE`](LICENSE-APACHE))
at your option.
---
## 16. Documentation Master Index
For detailed subsystem documentation, see the [**Documentation Index**](docs/README.md):
- [NX9 Design Principles](docs/design-principles.md)
- [System Architecture](docs/architecture.md)
- [Installation Guide](docs/installation.md)
- [Native WireGuard Engine](docs/native-wireguard.md)
- [Native Network Engine](docs/native-network.md)
- [Native nftables Engine](docs/nftables.md)
- [Firewall & NAT Model](docs/firewall_nat.md)
- [Reconciliation & Convergence](docs/reconciliation.md)
- [Web User Interface Reference](docs/ui.md)
- [REST API & WebSocket Reference](docs/api.md)
- [CLI Command Reference](docs/cli.md)
- [Configuration Reference](docs/configuration.md)
- [Security & Privilege Architecture](docs/security.md)
- [Backup & Disaster Recovery](docs/backup_restore.md)
- [Release Engineering](docs/release.md)
- [Testing Specification](docs/TESTING.md)
- [Development Guide](docs/development.md)
- [Docker Deployment](docs/docker.md)