Compare commits
9
Commits
v0.8.0
..
34227efd2b
| Author | SHA1 | Date | |
|---|---|---|---|
 thakares
|
34227efd2b | ||
|
thakares
|
5599e1b5c8 | ||
|
thakares
|
32a325234a | ||
|
thakares
|
d25846c58c | ||
|
thakares
|
2f06c8faa9 | ||
|
thakares
|
d710deb8b0 | ||
|
thakares
|
a6208ef330 | ||
|
thakares
|
d704c1e131 | ||
|
thakares
|
4dfe42fe68 |
No files matched your search
@@ -0,0 +1,64 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to **NX9-WG (`nx9-wg`)** are documented here.
|
||||
|
||||
## [1.0.0] — 2026-08-18
|
||||
|
||||
NX9-WG 1.0.0 is the first production release of the native Linux WireGuard + network control plane.
|
||||
|
||||
### Added
|
||||
|
||||
- Native Linux WireGuard lifecycle management through WireGuard Generic Netlink and RTNETLINK.
|
||||
- Native IPv4/IPv6 address and route management without `wg`, `wg-quick`, `ip`, `iptables`, `nft`, `sysctl`, or shell orchestration from production Rust.
|
||||
- Native nftables firewall/NAT execution scoped to the managed `table inet nx9_wg` table.
|
||||
- SQLite authoritative desired-state storage with reconciliation and drift correction.
|
||||
- Live WireGuard telemetry including learned peer endpoints, handshake timestamps, and RX/TX counters.
|
||||
- Correct separation of client-side `AllowedIPs` from server-side WireGuard Cryptokey Routing `AllowedIPs`.
|
||||
- Road-warrior server peer routing derived from assigned tunnel addresses (`/32` and `/128`) unless an explicit server-side override is configured.
|
||||
- Persistent WireGuard server endpoint configuration for client configuration and QR exports.
|
||||
- Interface editing through the WebUI with cryptographic identity preservation.
|
||||
- WebUI peer lifecycle states: Connected, Awaiting Handshake, Disconnected, Disabled, Expired, and Revoked.
|
||||
- Pure Rust client configuration and QR generation.
|
||||
- CLI, REST API, WebSocket, embedded SPA, diagnostics, backup/restore, and reconciliation tooling.
|
||||
|
||||
### Changed
|
||||
|
||||
- Peer API responses now merge fresh kernel telemetry instead of relying solely on cached SQLite values.
|
||||
- Handshake timestamps are serialized as explicit UTC/RFC3339 values and parsed defensively by the WebUI.
|
||||
- Interface edits preserve interface UUID, private key, public key, and peer associations.
|
||||
- Server endpoint resolution prefers explicit export overrides, then persistent server endpoint settings, with controlled fallback behavior.
|
||||
- Reconciliation detects and repairs server-side peer `AllowedIPs` drift.
|
||||
- Release documentation and testing documentation are promoted to the v1.0.0 baseline.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fixed road-warrior peers incorrectly receiving client full-tunnel `AllowedIPs` (`0.0.0.0/0, ::/0`) in the server kernel Cryptokey Routing table.
|
||||
- Fixed server-to-peer routing failure caused by missing `/32` peer routes in WireGuard peer configuration.
|
||||
- Fixed WebUI active peers appearing Disconnected because backend `NaiveDateTime` values lacked an explicit UTC offset.
|
||||
- Fixed stale peer telemetry in REST/WebUI responses.
|
||||
- Fixed missing WebUI interface Edit action.
|
||||
- Fixed missing persistent server endpoint for QR/config export.
|
||||
- Fixed reconciliation convergence after deliberate interface-address drift.
|
||||
|
||||
### Networking & Firewall
|
||||
|
||||
- IPv4 forwarding is managed through the native Linux networking engine.
|
||||
- Outbound masquerading is scoped to the WireGuard client subnet and non-WireGuard egress interfaces.
|
||||
- Firewall/NAT state is reconciled atomically within the dedicated NX9 nftables table.
|
||||
- Server-side peer routes and cryptokey routing are kept distinct from client routing policy.
|
||||
|
||||
### Validation
|
||||
|
||||
- Workspace test suite: **162 tests passing** at the documented release baseline.
|
||||
- Comprehensive CLI suite: **203 passed / 7 skipped**.
|
||||
- Native integration suite: **19 passed / 1 skipped**.
|
||||
- Dedicated live-kernel suite: **23 passed / 1 skipped** in SAFE mode baseline.
|
||||
- Real Android/mobile WireGuard client: **operator-verified** for VPN connectivity and full-tunnel Internet operation during v1.0.0 acceptance.
|
||||
- WebUI interface editing: **operator-verified**.
|
||||
- Live peer telemetry/status: **operator-verified** with connected mobile client.
|
||||
- Final reconciliation: **operator-verified** with zero drift after convergence.
|
||||
- External cellular/WAN road-warrior acceptance and post-reboot physical-client acceptance remain separate operational gates unless explicitly recorded in the release evidence.
|
||||
|
||||
## [0.8.0]
|
||||
|
||||
Previous development release. See repository history for detailed implementation changes.
|
||||
Generated
+9
-9
@@ -1785,7 +1785,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"axum",
|
||||
"base64",
|
||||
@@ -1807,7 +1807,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg-api"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"axum",
|
||||
"chrono",
|
||||
@@ -1832,7 +1832,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg-core"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"argon2",
|
||||
"base64",
|
||||
@@ -1852,7 +1852,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg-db"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"ipnet",
|
||||
@@ -1869,7 +1869,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg-network"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"chrono",
|
||||
@@ -1890,7 +1890,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wg-ui"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"nx9-wg-core",
|
||||
@@ -1901,7 +1901,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "nx9-wireguard"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"base64",
|
||||
@@ -3721,9 +3721,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zerovec-derive"
|
||||
version = "0.11.4"
|
||||
version = "0.11.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "47402523226a02bfe5230160dc3ccc089aa6f6f19e7fcbb4e6f824bbb1b4aa62"
|
||||
checksum = "9f212a141d820099d57ffafb9569be9617a6f27d3dc881fbee8fb56642f917a9"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
|
||||
+3
-3
@@ -10,11 +10,11 @@ members = [
|
||||
|
||||
[workspace.package]
|
||||
license = "MIT OR Apache-2.0"
|
||||
version = "0.8.0"
|
||||
version = "1.0.0"
|
||||
edition = "2024"
|
||||
authors = ["NX9 Authors <team@nx9.in>"]
|
||||
repository = "https://github.com/nx9/nx9-wg"
|
||||
homepage = "https://github.com/nx9/nx9-wg"
|
||||
repository = "https://github.com/thakares/nx9-wg"
|
||||
homepage = "https://github.com/thakares/nx9-wg"
|
||||
readme = "README.md"
|
||||
keywords = ["wireguard", "vpn", "netlink", "nftables", "network"]
|
||||
categories = ["network-programming", "command-line-utilities", "system-administration"]
|
||||
|
||||
-519
@@ -1,519 +0,0 @@
|
||||
# NX9 WireGuard (`nx9-wg`) — Full Technical Architecture & Stack Report
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
> **"Software people can own, understand, and control."**
|
||||
> — [NX9 Systems (https://nx9.in)](https://nx9.in)
|
||||
|
||||
---
|
||||
|
||||
## 📑 Table of Contents
|
||||
|
||||
1. [Executive Summary](#1-executive-summary)
|
||||
2. [The NX9 Philosophy in Implementation](#2-the-nx9-philosophy-in-implementation)
|
||||
3. [The Architectural Paradigm Shift](#3-the-architectural-paradigm-shift)
|
||||
4. [Six-Crate Workspace Architecture](#4-six-crate-workspace-architecture)
|
||||
5. [Complete Capability Inventory](#5-complete-capability-inventory)
|
||||
6. [Native Linux Execution Planes](#6-native-linux-execution-planes)
|
||||
7. [Closed-Loop Reconciliation & Convergence](#7-closed-loop-reconciliation--convergence)
|
||||
8. [Embedded Single Page Application (SPA) & WebSockets](#8-embedded-single-page-application-spa--websockets)
|
||||
9. [REST API & WebSocket Protocol Reference](#9-rest-api--websocket-protocol-reference)
|
||||
10. [Native CLI Command System](#10-native-cli-command-system)
|
||||
11. [Security Model & Capability Isolation](#11-security-model--capability-isolation)
|
||||
12. [Disaster Recovery, Backups & Upgrades](#12-disaster-recovery-backups--upgrades)
|
||||
13. [Release Engineering & Deployment Lifecycle](#13-release-engineering--deployment-lifecycle)
|
||||
14. [Quality Assurance & Verification Evidence](#14-quality-assurance--verification-evidence)
|
||||
15. [Ecosystem & License Summary](#15-ecosystem--license-summary)
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
`nx9-wg` is a sovereign, self-hosted, Linux-native VPN and network control plane built directly around the Linux kernel's in-tree WireGuard implementation (`wireguard.ko`).
|
||||
|
||||
Rather than functioning as a fragile user interface wrapper that shells out to external command-line utilities (`wg`, `ip`, `nft`, `sysctl`), `nx9-wg` establishes an integrated, single-binary architecture. It combines **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**.
|
||||
|
||||
---
|
||||
|
||||
## 2. The NX9 Philosophy in Implementation
|
||||
|
||||
Every design and architectural choice in `nx9-wg` directly reflects the core philosophy of the **NX9 Ecosystem** ([https://nx9.in](https://nx9.in)):
|
||||
|
||||
| NX9 Principle | Core Intent | `nx9-wg` Implementation |
|
||||
| :--- | :--- | :--- |
|
||||
| 🔑 **Operator Ownership** | Full control over binaries, configurations, databases, keys, and backups with zero dependency on cloud-hosted control planes. | 100% local operation. Private keys, configuration data, and encryption parameters never leave the operator's host. |
|
||||
| 🖥️ **Self-Hosting First** | Built to be deployed and operated effortlessly by a single administrator without requiring Kubernetes or external infrastructure. | Self-contained single executable. Bootstrapped with a single command (`nx9-wg init`), running seamlessly under standard systemd. |
|
||||
| ⚡ **Simplicity Over Complexity** | One binary, one configuration file, one SQLite database, one administrator. | No multi-daemon orchestration, no external message queues, no Node.js runtime, no Python scripts, and zero shell wrappers. |
|
||||
| 🛡️ **Privacy by Default** | Zero analytics, zero telemetry collection, zero third-party tracking, and zero assumptions of external cloud connectivity. | No phone-home telemetry. Completely air-gapped capable with all static assets, fonts, and scripts embedded in the binary. |
|
||||
| 🔒 **Security by Design** | Modern cryptography, strict invariants, and append-only audit logging embedded from day one. | Argon2id password hashing, SHA-256 token digests, X25519 key generation, single-admin database constraint (`CHECK (id=1)`), and strict secret redaction. |
|
||||
| 🔧 **Operational Excellence** | Diagnostics, backup/restore, migration tools, CLI management, and comprehensive documentation built-in. | Multi-subsystem automated health inspections, atomic online SQLite `VACUUM INTO` snapshots with SHA-256 manifests, and 100% CLI parity. |
|
||||
| ⏳ **Long-Term Stability** | Avoid dependency churn. Build software that remains understandable and maintainable years into the future. | Built in stable native Rust (Edition 2024), standard SQLite 3 storage, standard TOML configuration, and POSIX-compliant systemd integration. |
|
||||
| 🌐 **Open Source First** | 100% free and open-source software under permissive licensing. | Dual-licensed under `MIT OR Apache-2.0`. Complete freedom to inspect, audit, build, and extend. |
|
||||
| ♾️ **Zero Vendor Lock-In** | Standard data formats, open protocols, and zero proprietary cloud lock-in. | Standard SQLite database, standard WireGuard `.conf` files, standard RFC-compliant JSON/YAML/CSV output formats, and open Netlink sockets. |
|
||||
|
||||
---
|
||||
|
||||
## 3. The Architectural Paradigm Shift
|
||||
|
||||
### Typical WireGuard Management Wrappers
|
||||
```
|
||||
┌──────────┐ ┌──────────────────────┐ ┌────────────────────────────┐ ┌──────────────┐
|
||||
│ Web UI │ ──► │ Text Config Files │ ──► │ wg / ip / nft / sysctl │ ──► │ Linux Kernel │
|
||||
│ (Node/Py)│ │(/etc/wireguard/*.conf│ │ (Subprocess Spawning) │ │ (wireguard.ko│
|
||||
└──────────┘ └──────────────────────┘ └────────────────────────────┘ └──────────────┘
|
||||
```
|
||||
*Disadvantages: Fragile process spawning, race conditions, lack of atomic state, broken host routing, vulnerability to configuration drift, and heavy runtime dependency footprints.*
|
||||
|
||||
### Whereas `nx9-wg` is a Native Control & Execution Plane:
|
||||
```
|
||||
┌───────────────────────────────────┐
|
||||
│ 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)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ Linux Networking │
|
||||
└───────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Six-Crate Workspace Architecture
|
||||
|
||||
`nx9-wg` is architected as a modular six-crate Cargo workspace ensuring clean separation of concerns, zero circular dependencies, and isolated testability:
|
||||
|
||||
```
|
||||
nx9-wg (Root Executable & Unified Entrypoint)
|
||||
├── 📦 crates/nx9-wg-core — Domain models, RFC validation, cryptography, configuration
|
||||
├── 📦 crates/nx9-wg-db — SQLite storage engine, migration framework, repositories
|
||||
├── 📦 crates/nx9-wireguard — WireGuard Generic Netlink, RTNETLINK link engine, config & QR
|
||||
├── 📦 crates/nx9-wg-network — RTNETLINK routes/addresses, libnftables Netfilter, procfs
|
||||
├── 📦 crates/nx9-wg-api — Axum REST router, WebSockets, auth, reconciliation, IP allocator
|
||||
└── 📦 crates/nx9-wg-ui — Design tokens, CSS compiler, view models, SPA integration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Complete Capability Inventory
|
||||
|
||||
`nx9-wg` delivers a comprehensive suite of 20 core infrastructure capabilities:
|
||||
|
||||
| Icon | Capability | Architectural Description |
|
||||
| :---: | :--- | :--- |
|
||||
| 🔐 | **WireGuard Interface Lifecycle** | In-process RTNETLINK link creation (`RTM_NEWLINK`), state toggling (`IFF_UP`/`IFF_DOWN`), and WireGuard Generic Netlink cryptokey configuration (`WG_CMD_SET_DEVICE`). |
|
||||
| 👥 | **Cryptographic Peer Enrollment** | Dynamic Curve25519 public key management, preshared keys, CIDR allowed IPs, persistent keepalive intervals, and atomic `ReplacePeers` synchronization. |
|
||||
| 🌐 | **IPv4 & IPv6 Address Management** | Native Netlink address assignment (`RTM_NEWADDR` / `RTM_DELADDR`) across WireGuard interfaces without invoking `ip addr`. |
|
||||
| 🛣️ | **Kernel Route Management** | Routing table synchronization (`RTM_NEWROUTE` / `RTM_DELROUTE`) with strict default gateway protection and multi-tenant non-interference invariants. |
|
||||
| 🔥 | **nftables Netfilter Firewall** | In-process rule compilation and transactional application via `libnftables.so.1` confined strictly to `table inet nx9_wg`. |
|
||||
| 🛡️ | **Scoped NAT & Masquerading** | Outbound NAT masquerade dynamically calculated and applied strictly to managed WireGuard client subnets, preventing host network disruption. |
|
||||
| ↔️ | **Direct Procfs IP Forwarding** | Direct atomic mutation of `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding` without invoking `sysctl`. |
|
||||
| 📡 | **Live Kernel Telemetry** | Real-time extraction of handshake timestamps, rx/tx byte counters, and roaming remote socket endpoints directly from kernel sockets. |
|
||||
| 🔄 | **Desired-State Reconciliation** | Continuous closed-loop control cycle bringing the Linux kernel execution plane into alignment with authoritative SQLite storage. |
|
||||
| 🧭 | **5-Subsystem Drift Detection** | Deterministic, read-only calculation of state divergence across interfaces, peers, routes, firewall rules, and IP forwarding. |
|
||||
| ♻️ | **Cold-Boot Restart Recovery** | Autonomous reconstruction of kernel network topology, routes, and firewall rules upon daemon startup or host reboot. |
|
||||
| 🧪 | **Cross-Platform Simulation Engine** | In-memory simulated execution planes enabling full UI and CLI development on macOS and Windows without requiring Linux Netlink. |
|
||||
| 🖥️ | **Multi-Format Native CLI** | 100% native CLI coverage across all 17 subcommands supporting `table`, `json`, `yaml`, and `csv` output with script-friendly exit codes. |
|
||||
| 🌐 | **Axum REST API & WebSockets** | High-performance asynchronous HTTP server with session/bearer authentication and a real-time WebSocket event broadcaster (`/api/v1/ws`). |
|
||||
| 💻 | **Embedded Zero-Dependency SPA** | Modern HTML5/CSS3/Vanilla ES6+ Single Page Application compiled into the binary with Light/Dark theme support and 15 interactive views. |
|
||||
| 📊 | **Automated Health Diagnostics** | Built-in inspection across 9 subsystems with structured status reporting, root-cause diagnostics, and actionable remediation hints. |
|
||||
| 💾 | **Atomic Disaster Recovery Backups** | Online non-blocking SQLite `VACUUM INTO` snapshots with SHA-256 manifest verification and automatic pre-restore safety checkpoints. |
|
||||
| 🔑 | **Single-Administrator Security** | Database-enforced single identity (`CHECK (id=1)`), Argon2id password hashing, SHA-256 API token storage, and brute-force login rate limiting. |
|
||||
| 📱 | **Client Profiles & QR Engine** | Provider/device MTU profiles (1280 vs 1360 vs 1420), collision-resistant IP allocation, and pure Rust vector SVG, PNG, and ASCII QR generation. |
|
||||
| 📦 | **Production Release Packaging** | Standalone distribution archive generator (`scripts/package-release.sh`), automated installer/uninstaller, and hardened systemd service unit. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Native Linux Execution Planes
|
||||
|
||||
`nx9-wg` enforces a **Zero Subprocess Guarantee** across the entire production codebase:
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Rust Production Binary │
|
||||
├────────────────────────────┬────────────────────────────┬──────────────────────────────┤
|
||||
│ NativeLinuxWireGuardEngine │ NativeLinuxNetworkEngine │ NativeLinuxNftablesEngine │
|
||||
├────────────────────────────┼────────────────────────────┼──────────────────────────────┤
|
||||
│ • AF_NETLINK │ • NETLINK_ROUTE │ • In-process libnftables FFI │
|
||||
│ • NETLINK_GENERIC (wg) │ • RTM_NEWLINK / DELLINK │ • nft_ctx_new() │
|
||||
│ • WG_CMD_SET_DEVICE │ • RTM_NEWADDR / DELADDR │ • Atomic Netfilter batch │
|
||||
│ • WG_CMD_GET_DEVICE │ • RTM_NEWROUTE / DELROUTE │ • Scoped: table inet nx9_wg │
|
||||
│ • WGDEVICE_F_REPLACE_PEERS │ • Direct /proc/sys writes │ • Zero host table flushes │
|
||||
└─────────────┬──────────────┴─────────────┬──────────────┴──────────────┬───────────────┘
|
||||
▼ ▼ ▼
|
||||
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Linux Kernel │
|
||||
│ (wireguard.ko • RTNETLINK • Netfilter • /proc/sys/net) │
|
||||
└────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Closed-Loop Reconciliation & Convergence
|
||||
|
||||
Reconciliation is the foundational control loop that bridges authoritative SQLite state with the Linux kernel:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 1. SQLite Desired State (Authoritative Persistent Source of Truth│
|
||||
└────────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Live Kernel Query (WireGuard Genl, RTNL routes, table nx9_wg) │
|
||||
└────────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Drift Detection (Read-Only Deterministic Multi-Subsystem Diff)│
|
||||
└────────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
│ has_drift == false? │
|
||||
├───────────────────────┬───────┤
|
||||
│ YES │ NO │
|
||||
▼ ▼ │
|
||||
┌─────────────┐ ┌──────────────▼────────────────┐
|
||||
│ Converged │ │ 4. Acquire Async Mutex Lock │
|
||||
│ (In Sync) │ └──────────────┬────────────────┘
|
||||
└─────────────┘ │
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ 5. Execute Native Mutations │
|
||||
│ (Genl SET_DEVICE, RTNL) │
|
||||
└──────────────┬────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ 6. Post-Apply Verification │
|
||||
└──────────────┬────────────────┘
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ Converged │ │ Partial │
|
||||
│ (100% Sync)│ │ Failure │
|
||||
└─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### The Six Reconciliation Lifecycle States
|
||||
1. **`Plan`**: Read-only calculation of drift between SQLite and kernel.
|
||||
2. **`Applying`**: In-progress dispatch of native mutations across execution planes.
|
||||
3. **`Verifying`**: Querying live kernel state to confirm applied changes took effect.
|
||||
4. **`Converged`**: 100% synchronization achieved with zero remaining drift.
|
||||
5. **`PartialFailure`**: One or more execution planes failed during apply (e.g. permission error).
|
||||
6. **`DriftRemains`**: Apply completed without fatal error, but post-verification detected unapplied state.
|
||||
|
||||
---
|
||||
|
||||
## 8. Embedded Single Page Application (SPA) & WebSockets
|
||||
|
||||
The `nx9-wg` frontend is a zero-dependency HTML5/CSS/JavaScript SPA embedded directly into the Rust binary:
|
||||
|
||||
- **Zero External Toolchains**: No Node.js, npm, Webpack, Vite, React, or external CDN dependencies.
|
||||
- **Embedded In-Memory Delivery**: Bundled at compile-time via `include_str!()` and served from memory.
|
||||
- **Design Tokens**: Custom CSS token system ([`crates/nx9-wg-ui/src/css.rs`](file:///home/sunil/Programs/nx9-wg/crates/nx9-wg-ui/src/css.rs)) supporting Light and Dark modes.
|
||||
- **Real-Time WebSocket Stream**: Subscribes to `ws://<host>/api/v1/ws` for live handshakes and drift alerts without polling.
|
||||
- **15 Interactive Views**:
|
||||
1. `#dashboard` — System overview, uptime, interface/peer counts, health cards.
|
||||
2. `#interfaces` — WireGuard interface CRUD, listen port, MTU, state toggles.
|
||||
3. `#peers` — Enrolled peer table, real-time handshakes, profile resolution, `.conf` export, SVG QR modal.
|
||||
4. `#networks` — Subnet network ranges, CIDR masks, available IP inspector.
|
||||
5. `#routes` — Kernel route definitions, gateway assignments, interface scoping.
|
||||
6. `#firewall` — nftables packet filtering rules in `table inet nx9_wg`, priority sorting.
|
||||
7. `#nat` — Managed subnet NAT masquerade status and instant toggle.
|
||||
8. `#forwarding` — Kernel IPv4/IPv6 packet forwarding status and toggle.
|
||||
9. `#reconciliation` — Real-time kernel drift overview, action plan table, interactive Apply button.
|
||||
10. `#diagnostics` — Automated multi-subsystem health checks with remediation hints.
|
||||
11. `#live-state` — Raw Linux Netlink telemetry, active kernel interfaces, live routing table.
|
||||
12. `#settings` — Key-value appliance parameters and danger zone reset controls.
|
||||
13. `#backups` — Online SQLite backup snapshots list, instant backup creation, `.db` download.
|
||||
14. `#audit` — Append-only security and administrative audit trail.
|
||||
15. `#administrator` — Admin account verification, password rotation, and one-time API token generation.
|
||||
|
||||
---
|
||||
|
||||
## 9. REST API & WebSocket Protocol Reference
|
||||
|
||||
### Authentication Mechanisms
|
||||
- **Session Cookie**: `nx9_session=<UUID>` returned via `POST /api/v1/auth/login`.
|
||||
- **Bearer Token**: `Authorization: Bearer nx9_<UUID>_<SECRET>` passed in HTTP headers.
|
||||
|
||||
### Complete REST Route Inventory
|
||||
```http
|
||||
POST /api/v1/auth/login - Authenticate administrator & create session
|
||||
POST /api/v1/auth/logout - Invalidate active session
|
||||
GET /api/v1/auth/session - Query authenticated session info
|
||||
POST /api/v1/auth/password - Rotate admin password (invalidates all sessions)
|
||||
GET /api/v1/auth/tokens - List active API token metadata
|
||||
POST /api/v1/auth/tokens - Generate new API token (one-time raw secret return)
|
||||
DELETE /api/v1/auth/tokens/{id} - Revoke an API token
|
||||
|
||||
GET /api/v1/system - System operational overview and object counts
|
||||
GET /api/v1/system/health - Public health check endpoint
|
||||
GET /api/v1/system/version - Version, build edition, and architecture
|
||||
GET /api/v1/system/settings - List all appliance key-value settings
|
||||
PUT /api/v1/system/settings - Upsert appliance setting
|
||||
|
||||
GET /api/v1/interfaces - List all WireGuard interfaces
|
||||
POST /api/v1/interfaces - Create WireGuard interface
|
||||
GET /api/v1/interfaces/{id} - Get interface details
|
||||
PUT /api/v1/interfaces/{id} - Update interface configuration
|
||||
DELETE /api/v1/interfaces/{id} - Delete interface (cascades to peers)
|
||||
POST /api/v1/interfaces/{id}/enable - Set interface IFF_UP
|
||||
POST /api/v1/interfaces/{id}/disable - Set interface IFF_DOWN
|
||||
GET /api/v1/interfaces/{id}/status - Query live kernel netlink telemetry
|
||||
GET /api/v1/interfaces/{id}/peers - List peers attached to interface
|
||||
POST /api/v1/interfaces/{id}/peers - Enroll new peer on interface
|
||||
|
||||
GET /api/v1/peers/{id} - Get peer details
|
||||
PUT /api/v1/peers/{id} - Update peer parameters
|
||||
DELETE /api/v1/peers/{id} - Delete peer
|
||||
POST /api/v1/peers/{id}/enable - Enable peer
|
||||
POST /api/v1/peers/{id}/disable - Disable peer
|
||||
GET /api/v1/peers/{id}/config - Download client .conf file
|
||||
GET /api/v1/peers/{id}/qr - Render QR code (SVG / PNG / ASCII)
|
||||
|
||||
GET /api/v1/networks - List subnet networks
|
||||
POST /api/v1/networks - Create subnet network
|
||||
GET /api/v1/networks/{id} - Get network details
|
||||
DELETE /api/v1/networks/{id} - Delete network
|
||||
GET /api/v1/networks/{id}/available - List available unallocated IP addresses
|
||||
|
||||
GET /api/v1/routes - List kernel routing entries
|
||||
POST /api/v1/routes - Create routing entry
|
||||
DELETE /api/v1/routes/{id} - Delete routing entry
|
||||
|
||||
GET /api/v1/firewall/rules - List nftables firewall rules
|
||||
POST /api/v1/firewall/rules - Create firewall rule
|
||||
DELETE /api/v1/firewall/rules/{id} - Delete firewall rule
|
||||
POST /api/v1/firewall/rules/{id}/enable - Enable firewall rule
|
||||
POST /api/v1/firewall/rules/{id}/disable - Disable firewall rule
|
||||
|
||||
GET /api/v1/reconcile/plan - Read-only drift calculation plan
|
||||
POST /api/v1/reconcile/apply - Serialized kernel apply and convergence check
|
||||
|
||||
GET /api/v1/diagnostics/all - Run full diagnostics across all 9 subsystems
|
||||
GET /api/v1/diagnostics/{subsystem} - Run diagnostics for single subsystem
|
||||
|
||||
GET /api/v1/backups - List backup records
|
||||
POST /api/v1/backups/create - Trigger atomic online VACUUM INTO snapshot
|
||||
GET /api/v1/backups/{id}/download - Download raw SQLite database snapshot
|
||||
POST /api/v1/backups/{id}/restore - Restore database with automatic safety backup
|
||||
DELETE /api/v1/backups/{id} - Delete backup snapshot file and metadata
|
||||
|
||||
GET /api/v1/audit - Query append-only audit trail
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Native CLI Command System
|
||||
|
||||
`nx9-wg` provides 100% native CLI coverage across all 17 subcommands:
|
||||
|
||||
```bash
|
||||
# Global output formats: --format table | json | yaml | csv
|
||||
nx9-wg version
|
||||
nx9-wg serve --bind 127.0.0.1:8080
|
||||
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||
|
||||
# Administration & Authentication
|
||||
nx9-wg admin info
|
||||
nx9-wg admin password
|
||||
nx9-wg admin token create "ci-pipeline" --expires-in-days 90 --write-token-file /tmp/token
|
||||
nx9-wg admin token list
|
||||
nx9-wg admin token revoke <TOKEN_UUID>
|
||||
|
||||
# Interface & Peer Management
|
||||
nx9-wg interface list
|
||||
nx9-wg interface create wg0 --address-v4 10.100.0.1/24 --port 51820 --mtu 1420
|
||||
nx9-wg peer create --interface wg0 --name alice --profile full_tunnel --mtu 1280
|
||||
nx9-wg peer qr <PEER_UUID>
|
||||
nx9-wg peer config <PEER_UUID>
|
||||
|
||||
# Networking, Firewall & NAT
|
||||
nx9-wg route add --destination 192.168.50.0/24 --gateway 10.100.0.2 --interface-name wg0
|
||||
nx9-wg firewall add --name "allow-dns" --protocol udp --port 53 --action accept --priority 10
|
||||
nx9-wg nat enable
|
||||
nx9-wg forwarding enable
|
||||
|
||||
# State Reconciliation & Diagnostics
|
||||
nx9-wg reconcile plan
|
||||
nx9-wg reconcile apply
|
||||
nx9-wg diagnostics inspect all
|
||||
|
||||
# Disaster Recovery
|
||||
nx9-wg backup create --description "Pre-upgrade snapshot"
|
||||
nx9-wg backup verify /var/lib/nx9-wg/backups/nx9-backup-...db
|
||||
nx9-wg backup restore <BACKUP_UUID>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Security Model & Capability Isolation
|
||||
|
||||
### A. Single Administrator Identity
|
||||
- Database-level integrity constraint: `CHECK (id = 1)` in `admins` table.
|
||||
- Eliminates multi-tenant privilege escalation and role-confusion attack surfaces.
|
||||
|
||||
### B. Credential Protection
|
||||
- **Passwords**: Hashed with Argon2id using unique cryptographic salts.
|
||||
- **API Tokens**: Stored exclusively as SHA-256 digests in SQLite; raw tokens are displayed once upon creation.
|
||||
- **Secret Redaction**: Private keys, preshared keys, and password hashes implement custom `std::fmt::Debug` implementations returning `[REDACTED]`.
|
||||
|
||||
### C. Hardened systemd Sandbox (`nx9-wg.service`)
|
||||
```ini
|
||||
[Unit]
|
||||
Description=NX9 WireGuard Native VPN Platform
|
||||
After=network.target network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/nx9-wg serve
|
||||
Restart=always
|
||||
RestartSec=5s
|
||||
|
||||
# Minimal Linux Capabilities
|
||||
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||
|
||||
# Sandboxing Directives
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
PrivateTmp=true
|
||||
ProtectControlGroups=true
|
||||
RestrictSUIDSGID=true
|
||||
LockPersonality=true
|
||||
NoNewPrivileges=true
|
||||
|
||||
# Allowed Network Address Families
|
||||
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
|
||||
|
||||
# Explicit Read-Write Paths (for state and direct procfs forwarding)
|
||||
ReadWritePaths=/var/lib/nx9-wg /etc/nx9-wg /var/log/nx9-wg /proc/sys/net
|
||||
ProtectKernelTunables=false
|
||||
|
||||
# Systemd Directory Management
|
||||
StateDirectory=nx9-wg
|
||||
ConfigurationDirectory=nx9-wg
|
||||
LogsDirectory=nx9-wg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Disaster Recovery, Backups & Upgrades
|
||||
|
||||
### Atomic Online Backups
|
||||
- Uses SQLite `VACUUM INTO` to produce non-blocking, consistent binary database snapshots while the daemon is actively serving traffic.
|
||||
- Generates SHA-256 manifest records for each snapshot.
|
||||
|
||||
### Safe Rollback Workflow
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ 1. Operator Initiates Restore (nx9-wg backup restore) │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼────────────────────────────┐
|
||||
│ 2. Verify Backup File Size, Magic Header & SHA-256 │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼────────────────────────────┐
|
||||
│ 3. Create Pre-Restore Safety Snapshot (Automatic Fallback│
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼────────────────────────────┐
|
||||
│ 4. Close Connection Pools, Replace .db, Clean WAL/SHM │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼────────────────────────────┐
|
||||
│ 5. Reopen Database & Execute Reconciliation Engine │
|
||||
│ (Kernel state converged to restored desired state) │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. Release Engineering & Deployment Lifecycle
|
||||
|
||||
### Automated Packaging Pipeline ([`scripts/package-release.sh`](file:///home/sunil/Programs/nx9-wg/scripts/package-release.sh))
|
||||
Generates self-contained, reproducible distribution archives in `target/dist/`:
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.tar.gz` (7.8 MB)
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.tar.xz` (5.0 MB)
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.sha256` (Cryptographic checksum manifest)
|
||||
|
||||
### Production Filesystem Layout & Permissions
|
||||
```
|
||||
/usr/local/bin/nx9-wg 0755 root:root - Native Executable Binary
|
||||
/etc/nx9-wg/ 0750 root:root - Configuration Directory
|
||||
└── config.toml 0640 root:root - Production Configuration
|
||||
/var/lib/nx9-wg/ 0700 root:root - State & SQLite Directory
|
||||
├── nx9-wg.db 0600 root:root - Authoritative SQLite Database
|
||||
├── nx9-wg.db-wal 0600 root:root - WAL Journal
|
||||
├── admin-password 0600 root:root - Initial Bootstrap Password
|
||||
└── backups/ 0700 root:root - Backup Snapshots Directory
|
||||
/var/log/nx9-wg/ 0750 root:root - Operational Logs
|
||||
/etc/systemd/system/nx9-wg.service 0644 root:root - Hardened Service Unit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Quality Assurance & Verification Evidence
|
||||
|
||||
All quality gates have been executed and verified clean:
|
||||
|
||||
| Quality Gate | Verification Command | Result |
|
||||
| :--- | :--- | :---: |
|
||||
| **Code Formatting** | `cargo fmt --all -- --check` | **PASS** (Zero diffs) |
|
||||
| **Workspace Compilation** | `cargo check --workspace` | **PASS** (Zero errors) |
|
||||
| **Workspace Unit Tests** | `cargo test --workspace` | **PASS** (**91 / 91 passed**, 100%) |
|
||||
| **Clippy Linter Check** | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (Zero warnings) |
|
||||
| **Comprehensive CLI Suite** | `LIVE=0 bash scripts/test-cli-comprehensive.sh` | **PASS** (**203 passed** / 7 skipped) |
|
||||
| **Native Integration Suite** | `LIVE=0 bash scripts/test-native-integration.sh` | **PASS** (**19 passed** / 1 skipped) |
|
||||
| **Dedicated Live Kernel Suite** | `LIVE=0 bash scripts/test-live-kernel.sh` | **PASS** (**23 passed** / 1 skipped) |
|
||||
| **Subprocess Safety Audit** | Automated source scan for `Command::new` | **PASS** (Zero subprocesses) |
|
||||
| **Secret Leakage Audit** | Automated audit for plaintext credentials | **PASS** (Zero secrets leaked) |
|
||||
| **Standalone Package Verification**| Fresh directory extraction & independent run | **PASS** (Standalone execution) |
|
||||
| **Git Diff Whitespace Audit** | `git diff --check` | **PASS** (Zero whitespace issues) |
|
||||
|
||||
---
|
||||
|
||||
## 15. Ecosystem & License Summary
|
||||
|
||||
`nx9-wg` is part of the **NX9 Ecosystem** ([https://nx9.in](https://nx9.in)) created by **Sunil Thakare**.
|
||||
|
||||
Dual-licensed under either:
|
||||
- **MIT License** ([`LICENSE-MIT`](file:///home/sunil/Programs/nx9-wg/LICENSE-MIT))
|
||||
- **Apache License, Version 2.0** ([`LICENSE-APACHE`](file:///home/sunil/Programs/nx9-wg/LICENSE-APACHE))
|
||||
|
||||
at your option.
|
||||
|
||||
---
|
||||
|
||||
> **NX9 WireGuard** — Sovereign, Self-Hosted, Linux-Native Network Infrastructure.
|
||||
@@ -4,237 +4,458 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
> **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** | 91 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 (91/91 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:
|
||||
tar -xzf nx9-wg-v0.8.0-linux-x86_64.tar.gz
|
||||
cd nx9-wg-v0.8.0-linux-x86_64
|
||||
# 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 162 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** | [**Testing Strategy**](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)
|
||||
|
||||
## 17. Web UI Screenshots
|
||||
|
||||
The following screenshots provide visual evidence of the production Web UI and its native
|
||||
WireGuard/network administration workflow. Sensitive endpoint and cryptographic values in
|
||||
the captured evidence have been redacted where applicable.
|
||||
|
||||
### Dashboard
|
||||
|
||||
|
||||
|
||||
### Interfaces
|
||||
|
||||
|
||||
|
||||
### Peer Management
|
||||
|
||||
|
||||
|
||||
### New Peer Enrollment
|
||||
|
||||
|
||||
|
||||
### Client Configuration Export
|
||||
|
||||
|
||||
|
||||
### QR Code Export
|
||||
|
||||
|
||||
|
||||
### Networks
|
||||
|
||||
|
||||
|
||||
### IP Forwarding
|
||||
|
||||
|
||||
|
||||
### NAT & Masquerade
|
||||
|
||||
|
||||
|
||||
### Reconciliation
|
||||
|
||||
|
||||
|
||||
### Diagnostics — System, Network & WAN
|
||||
|
||||
|
||||
|
||||
### Diagnostics — Firewall, NAT, MTU & Reconciliation
|
||||
|
||||
|
||||
|
||||
### Settings
|
||||
|
||||
|
||||
|
||||
### Backups
|
||||
|
||||
|
||||
|
||||
> **Additional evidence:** `screenshots/admin-instance.png` contains the captured administrative
|
||||
> instance documentation and is retained in the repository alongside the UI screenshots.
|
||||
- [Development Guide](docs/DEVELOPMENT.md)
|
||||
- [Docker Deployment](docs/DOCKER.md)
|
||||
+1
-1
@@ -23,7 +23,7 @@ reconciliation_interval_secs = 60
|
||||
dir = "/var/lib/nx9-wg/backups"
|
||||
|
||||
# Maximum number of automated backup snapshots to retain
|
||||
max_count = 10
|
||||
max_count = 5
|
||||
|
||||
# Optional cron schedule for automated database backups (e.g. "0 2 * * *" for 02:00 UTC)
|
||||
# schedule = "0 2 * * *"
|
||||
|
||||
@@ -20,6 +20,7 @@ pub use error::{ApiError, ApiResult, ErrorBody, ErrorResponse};
|
||||
pub use profile_resolver::ClientProfileResolver;
|
||||
pub use reconciliation::{
|
||||
ReconciliationAction, ReconciliationEngine, ReconciliationPlan, ReconciliationReport,
|
||||
collect_managed_wg_subnets,
|
||||
};
|
||||
pub use routes::build_api_router;
|
||||
pub use state::{AppState, SystemEvent};
|
||||
@@ -3,14 +3,74 @@
|
||||
use crate::error::{ApiError, ApiResult};
|
||||
use crate::state::{AppState, SystemEvent};
|
||||
use chrono::Utc;
|
||||
use ipnet::IpNet;
|
||||
use nx9_wg_core::types::audit::AuditEventType;
|
||||
use nx9_wg_core::types::wireguard::PeerState;
|
||||
use nx9_wg_db::Store;
|
||||
use nx9_wg_network::NetworkEngine;
|
||||
use nx9_wireguard::WireGuardEngine;
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
/// Check if a slice of live address strings contains the desired IpNet.
|
||||
fn matches_ipnet(live_addrs: &[String], desired: &IpNet) -> bool {
|
||||
live_addrs.iter().any(|s| {
|
||||
if let Ok(net) = s.parse::<IpNet>() {
|
||||
net.addr() == desired.addr() && net.prefix_len() == desired.prefix_len()
|
||||
} else {
|
||||
false
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Check if live WireGuard peer allowed IPs match desired server-side allowed IPs.
|
||||
fn matches_allowed_ips(live_allowed_ips: &[String], desired_str: &str) -> bool {
|
||||
let desired_nets: std::collections::BTreeSet<IpNet> = desired_str
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.filter_map(|s| s.parse::<IpNet>().ok())
|
||||
.collect();
|
||||
|
||||
let live_nets: std::collections::BTreeSet<IpNet> = live_allowed_ips
|
||||
.iter()
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.filter_map(|s| s.parse::<IpNet>().ok())
|
||||
.collect();
|
||||
|
||||
desired_nets == live_nets
|
||||
}
|
||||
|
||||
/// Collect Interface CIDRs plus enabled Subnet Network CIDRs for NAT/forwarding.
|
||||
///
|
||||
/// Interface addresses remain the WireGuard transport identity. Enabled Network
|
||||
/// CIDRs are the peer allocation domains and must be masqueraded so selected-
|
||||
/// Network peers receive the same full-tunnel Internet path as Interface-CIDR
|
||||
/// peers. `network_id = null` peers still match the Interface CIDR.
|
||||
pub async fn collect_managed_wg_subnets(store: &Store) -> ApiResult<Vec<IpNet>> {
|
||||
let mut subnets = Vec::new();
|
||||
|
||||
for iface in store.list_interfaces().await? {
|
||||
if !iface.enabled {
|
||||
continue;
|
||||
}
|
||||
subnets.push(iface.address_v4);
|
||||
if let Some(v6) = iface.address_v6 {
|
||||
subnets.push(v6);
|
||||
}
|
||||
}
|
||||
|
||||
for net in store.list_networks().await? {
|
||||
if net.enabled {
|
||||
subnets.push(net.cidr);
|
||||
}
|
||||
}
|
||||
|
||||
Ok(subnets)
|
||||
}
|
||||
|
||||
/// Individual action proposed or taken by the reconciler.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct ReconciliationAction {
|
||||
@@ -53,6 +113,8 @@ pub struct ReconciliationReport {
|
||||
#[serde(default)]
|
||||
pub status: ReconciliationStatus,
|
||||
pub executed_actions: usize,
|
||||
#[serde(default)]
|
||||
pub failed_actions: usize,
|
||||
pub details: Vec<String>,
|
||||
}
|
||||
|
||||
@@ -132,40 +194,66 @@ impl ReconciliationEngine {
|
||||
.ok()
|
||||
.flatten();
|
||||
|
||||
let live_peer_keys: Vec<String> = live_stats
|
||||
.as_ref()
|
||||
.map(|s| s.peers.iter().map(|p| p.public_key.clone()).collect())
|
||||
.unwrap_or_default();
|
||||
let iface_exists = live_interfaces.contains(&iface.name) || live_stats.is_some();
|
||||
|
||||
match live_stats.as_ref() {
|
||||
Some(stats) => {
|
||||
if stats.public_key != iface.public_key.as_str()
|
||||
|| stats.listen_port != iface.listen_port
|
||||
if iface_exists {
|
||||
if let Some(stats) = live_stats.as_ref() {
|
||||
let mut drift_reasons = Vec::new();
|
||||
|
||||
if !stats.public_key.is_empty()
|
||||
&& stats.public_key != iface.public_key.as_str()
|
||||
{
|
||||
drift_reasons.push("public key mismatch".to_string());
|
||||
}
|
||||
if stats.listen_port != 0 && stats.listen_port != iface.listen_port {
|
||||
drift_reasons.push("listen port mismatch".to_string());
|
||||
}
|
||||
if !matches_ipnet(&stats.addresses, &iface.address_v4) {
|
||||
drift_reasons
|
||||
.push(format!("missing IPv4 address '{}'", iface.address_v4));
|
||||
}
|
||||
if let Some(ref v6) = iface.address_v6
|
||||
&& !matches_ipnet(&stats.addresses, v6)
|
||||
{
|
||||
drift_reasons.push(format!("missing IPv6 address '{v6}'"));
|
||||
}
|
||||
if let Some(desired_mtu) = iface.mtu
|
||||
&& let Some(live_mtu) = stats.mtu
|
||||
&& live_mtu != desired_mtu as u32
|
||||
{
|
||||
drift_reasons.push(format!(
|
||||
"MTU mismatch (live: {live_mtu}, desired: {desired_mtu})"
|
||||
));
|
||||
}
|
||||
if !stats.is_up {
|
||||
drift_reasons.push("interface link is down".to_string());
|
||||
}
|
||||
|
||||
if !drift_reasons.is_empty() {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "wireguard".to_string(),
|
||||
resource_id: iface.id.to_string(),
|
||||
action_type: "update_interface".to_string(),
|
||||
description: format!(
|
||||
"Interface '{}' configuration drift detected; update listen port / keys",
|
||||
iface.name
|
||||
"Interface '{}' configuration drift detected ({}); synchronize link, address, port, or keys",
|
||||
iface.name,
|
||||
drift_reasons.join(", ")
|
||||
),
|
||||
});
|
||||
plan.interface_changes += 1;
|
||||
}
|
||||
}
|
||||
None => {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "wireguard".to_string(),
|
||||
resource_id: iface.id.to_string(),
|
||||
action_type: "create_interface".to_string(),
|
||||
description: format!(
|
||||
"Interface '{}' missing in kernel; create and sync",
|
||||
iface.name
|
||||
),
|
||||
});
|
||||
plan.interface_changes += 1;
|
||||
}
|
||||
} else {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "wireguard".to_string(),
|
||||
resource_id: iface.id.to_string(),
|
||||
action_type: "create_interface".to_string(),
|
||||
description: format!(
|
||||
"Interface '{}' missing in kernel; create and sync",
|
||||
iface.name
|
||||
),
|
||||
});
|
||||
plan.interface_changes += 1;
|
||||
}
|
||||
|
||||
// Check peers (only Active desired peers should be live)
|
||||
@@ -175,16 +263,86 @@ impl ReconciliationEngine {
|
||||
.filter(|p| p.state == PeerState::Active)
|
||||
.collect();
|
||||
|
||||
let live_peers_map: std::collections::HashMap<
|
||||
String,
|
||||
&nx9_wireguard::LivePeerStats,
|
||||
> = if let Some(ref stats) = live_stats {
|
||||
stats
|
||||
.peers
|
||||
.iter()
|
||||
.map(|p| (p.public_key.clone(), p))
|
||||
.collect()
|
||||
} else {
|
||||
std::collections::HashMap::new()
|
||||
};
|
||||
|
||||
for p in &active_desired_peers {
|
||||
if !live_peer_keys.contains(&p.public_key.as_str().to_string()) {
|
||||
let pub_key_str = p.public_key.as_str();
|
||||
let desired_server_allowed = p.server_wireguard_allowed_ips();
|
||||
|
||||
if let Some(live_p) = live_peers_map.get(pub_key_str) {
|
||||
// Peer is present in live kernel interface. Verify semantic drift:
|
||||
let mut peer_drifts = Vec::new();
|
||||
|
||||
if !matches_allowed_ips(&live_p.allowed_ips, &desired_server_allowed) {
|
||||
peer_drifts.push(format!(
|
||||
"AllowedIPs drift (live: [{:?}], desired: [{desired_server_allowed}])",
|
||||
live_p.allowed_ips
|
||||
));
|
||||
}
|
||||
|
||||
if let (Some(desired_ka), Some(live_ka)) =
|
||||
(p.persistent_keepalive, live_p.persistent_keepalive)
|
||||
&& live_ka != desired_ka
|
||||
{
|
||||
peer_drifts.push(format!(
|
||||
"persistent keepalive drift (live: {live_ka}s, desired: {desired_ka}s)"
|
||||
));
|
||||
}
|
||||
|
||||
if !peer_drifts.is_empty() {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "wireguard".to_string(),
|
||||
resource_id: p.id.to_string(),
|
||||
action_type: "update_peer".to_string(),
|
||||
description: format!(
|
||||
"Peer '{}' ({}) drift detected: {}; re-sync in kernel",
|
||||
p.name,
|
||||
pub_key_str,
|
||||
peer_drifts.join(", ")
|
||||
),
|
||||
});
|
||||
plan.peer_changes += 1;
|
||||
}
|
||||
|
||||
// Update operational telemetry (handshake timestamp and learned endpoint) from kernel
|
||||
if live_p.last_handshake_at.is_some() || live_p.endpoint.is_some() {
|
||||
let hs_newer = live_p.last_handshake_at.is_some()
|
||||
&& live_p.last_handshake_at != p.last_handshake_at;
|
||||
let ep_newer = live_p.endpoint.is_some()
|
||||
&& live_p.endpoint.as_deref() != p.endpoint.as_deref();
|
||||
|
||||
if hs_newer || ep_newer {
|
||||
let _ = self
|
||||
.state
|
||||
.store
|
||||
.update_peer_learned_telemetry(
|
||||
p.id,
|
||||
live_p.last_handshake_at.or(p.last_handshake_at),
|
||||
live_p.endpoint.as_deref().or(p.endpoint.as_deref()),
|
||||
)
|
||||
.await;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "wireguard".to_string(),
|
||||
resource_id: p.id.to_string(),
|
||||
action_type: "add_peer".to_string(),
|
||||
description: format!(
|
||||
"Peer '{}' ({}) missing in live interface",
|
||||
"Peer '{}' ({}) missing in live interface; add to kernel with AllowedIPs [{desired_server_allowed}]",
|
||||
p.name,
|
||||
p.public_key.as_str()
|
||||
pub_key_str
|
||||
),
|
||||
});
|
||||
plan.peer_changes += 1;
|
||||
@@ -226,7 +384,7 @@ impl ReconciliationEngine {
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Routes
|
||||
// 2. Routes (SQLite Routes table only; peer-allocation Networks are not routes)
|
||||
let desired_routes = self.state.store.list_routes().await?;
|
||||
let enabled_routes: Vec<_> = desired_routes.iter().filter(|r| r.enabled).collect();
|
||||
let has_route_drift = self
|
||||
@@ -272,15 +430,7 @@ impl ReconciliationEngine {
|
||||
.map(|s| s.value == "true" || s.value == "1")
|
||||
.unwrap_or(true);
|
||||
|
||||
let mut wg_subnets = Vec::new();
|
||||
for iface in &desired_interfaces {
|
||||
if iface.enabled {
|
||||
wg_subnets.push(iface.address_v4);
|
||||
if let Some(v6) = iface.address_v6 {
|
||||
wg_subnets.push(v6);
|
||||
}
|
||||
}
|
||||
}
|
||||
let wg_subnets = collect_managed_wg_subnets(&self.state.store).await?;
|
||||
|
||||
let expected_ruleset = nx9_wg_network::NftablesRulesetBuilder::build(
|
||||
&resolved_fw_rules,
|
||||
@@ -293,7 +443,7 @@ impl ReconciliationEngine {
|
||||
.await
|
||||
.unwrap_or_default();
|
||||
|
||||
if expected_ruleset.trim() != active_ruleset.trim() {
|
||||
if nx9_wg_network::has_nftables_drift(&expected_ruleset, &active_ruleset) {
|
||||
plan.actions.push(ReconciliationAction {
|
||||
subsystem: "firewall".to_string(),
|
||||
resource_id: "nftables".to_string(),
|
||||
@@ -340,11 +490,21 @@ impl ReconciliationEngine {
|
||||
// Sweep expired peers
|
||||
let _ = self.sweep_expired_peers().await;
|
||||
|
||||
let initial_plan = self.plan().await.unwrap_or_default();
|
||||
if !initial_plan.has_drift {
|
||||
return Ok(ReconciliationReport {
|
||||
success: true,
|
||||
status: ReconciliationStatus::Converged,
|
||||
executed_actions: 0,
|
||||
failed_actions: 0,
|
||||
details: vec!["System is already fully converged; zero drift detected".to_string()],
|
||||
});
|
||||
}
|
||||
|
||||
let desired_interfaces = self.state.store.list_interfaces().await?;
|
||||
let mut details = Vec::new();
|
||||
|
||||
// 1. Sync all active WireGuard interfaces and their peers
|
||||
let mut wg_subnets = Vec::new();
|
||||
for iface in &desired_interfaces {
|
||||
if iface.enabled {
|
||||
let peers = self.state.store.list_peers_for_interface(iface.id).await?;
|
||||
@@ -357,10 +517,6 @@ impl ReconciliationEngine {
|
||||
iface.name
|
||||
))
|
||||
})?;
|
||||
wg_subnets.push(iface.address_v4);
|
||||
if let Some(v6) = iface.address_v6 {
|
||||
wg_subnets.push(v6);
|
||||
}
|
||||
details.push(format!(
|
||||
"Synchronized interface '{}' with {} peers",
|
||||
iface.name,
|
||||
@@ -375,7 +531,9 @@ impl ReconciliationEngine {
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Sync Routes
|
||||
let wg_subnets = collect_managed_wg_subnets(&self.state.store).await?;
|
||||
|
||||
// 2. Sync Routes (SQLite Routes table only; peer-allocation Networks are not routes)
|
||||
let routes = self.state.store.list_routes().await?;
|
||||
self.net_engine
|
||||
.sync_routes(&routes)
|
||||
@@ -419,10 +577,28 @@ impl ReconciliationEngine {
|
||||
|
||||
// 4. Verify post-apply convergence
|
||||
let post_plan = self.plan().await.unwrap_or_default();
|
||||
let (success, status) = if !post_plan.has_drift {
|
||||
(true, ReconciliationStatus::Converged)
|
||||
let (success, status, executed_actions, failed_actions) = if !post_plan.has_drift {
|
||||
(
|
||||
true,
|
||||
ReconciliationStatus::Converged,
|
||||
initial_plan.actions.len(),
|
||||
0,
|
||||
)
|
||||
} else {
|
||||
(false, ReconciliationStatus::DriftRemains)
|
||||
let remaining = post_plan.actions.len();
|
||||
let completed = initial_plan.actions.len().saturating_sub(remaining);
|
||||
for action in &post_plan.actions {
|
||||
details.push(format!(
|
||||
"Unresolved drift: [{}] {}",
|
||||
action.subsystem, action.description
|
||||
));
|
||||
}
|
||||
(
|
||||
false,
|
||||
ReconciliationStatus::DriftRemains,
|
||||
completed,
|
||||
remaining,
|
||||
)
|
||||
};
|
||||
|
||||
// 5. Audit reconciliation run
|
||||
@@ -435,8 +611,8 @@ impl ReconciliationEngine {
|
||||
Some("reconciliation"),
|
||||
None,
|
||||
Some(&format!(
|
||||
"Reconciliation applied {} actions (status: {status:?})",
|
||||
details.len()
|
||||
"Reconciliation applied {} actions (status: {status:?}, failed: {failed_actions})",
|
||||
executed_actions
|
||||
)),
|
||||
None,
|
||||
None,
|
||||
@@ -446,8 +622,8 @@ impl ReconciliationEngine {
|
||||
self.state.broadcast(SystemEvent::AuditEvent {
|
||||
event_type: AuditEventType::ReconciliationRun,
|
||||
message: Some(format!(
|
||||
"Reconciliation applied {} actions (status: {status:?})",
|
||||
details.len()
|
||||
"Reconciliation applied {} actions (status: {status:?}, failed: {failed_actions})",
|
||||
executed_actions
|
||||
)),
|
||||
resource_type: Some("reconciliation".to_string()),
|
||||
resource_id: None,
|
||||
@@ -456,7 +632,8 @@ impl ReconciliationEngine {
|
||||
Ok(ReconciliationReport {
|
||||
success,
|
||||
status,
|
||||
executed_actions: details.len(),
|
||||
executed_actions,
|
||||
failed_actions,
|
||||
details,
|
||||
})
|
||||
}
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -10,7 +10,31 @@
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app-layout">
|
||||
<!-- Unauthenticated Login View -->
|
||||
<div id="login-view" style="display: none;">
|
||||
<div class="login-card">
|
||||
<div class="login-header">
|
||||
<span class="brand-mark">NX9</span>
|
||||
<h2>Administrator Login</h2>
|
||||
<p>Sign in to nx9-wg Native Linux Appliance</p>
|
||||
</div>
|
||||
<div id="login-error-msg" class="login-error" style="display: none;"></div>
|
||||
<form id="login-form" onsubmit="event.preventDefault(); submitLogin();">
|
||||
<div class="form-group">
|
||||
<label class="form-label" for="login-username">Username</label>
|
||||
<input type="text" id="login-username" class="form-input" value="admin" required autocomplete="username">
|
||||
</div>
|
||||
<div class="form-group">
|
||||
<label class="form-label" for="login-password">Password</label>
|
||||
<input type="password" id="login-password" class="form-input" required autofocus autocomplete="current-password">
|
||||
</div>
|
||||
<button type="submit" id="login-submit-btn" class="btn btn-primary" style="width: 100%; margin-top: 8px;">Sign In</button>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Authenticated Application Shell -->
|
||||
<div id="app-layout" style="display: none;">
|
||||
<!-- Top Application Bar -->
|
||||
<header class="topbar">
|
||||
<div class="topbar-left">
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
use crate::auth::middleware::AuthenticatedAdmin;
|
||||
use crate::error::{ApiError, ApiResult};
|
||||
use crate::state::AppState;
|
||||
use axum::extract::{Path, State};
|
||||
use axum::extract::{Path, Request, State};
|
||||
use axum::http::HeaderMap;
|
||||
use axum::http::header::SET_COOKIE;
|
||||
use axum::http::header::{AUTHORIZATION, COOKIE, SET_COOKIE};
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use axum::{Extension, Json};
|
||||
use chrono::NaiveDateTime;
|
||||
@@ -67,9 +67,8 @@ pub async fn login_handler(
|
||||
.await?;
|
||||
|
||||
let cookie_val = format!(
|
||||
"nx9_session={}; Path=/; HttpOnly; SameSite=Lax; Max-Age={}",
|
||||
session.id,
|
||||
24 * 3600
|
||||
"nx9_session={}; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400",
|
||||
session.id
|
||||
);
|
||||
|
||||
let mut headers = HeaderMap::new();
|
||||
@@ -89,12 +88,37 @@ pub async fn login_handler(
|
||||
}
|
||||
|
||||
/// POST /api/v1/auth/logout
|
||||
pub async fn logout_handler(
|
||||
State(state): State<AppState>,
|
||||
Extension(auth_user): Extension<AuthenticatedAdmin>,
|
||||
) -> ApiResult<Response> {
|
||||
if let Some(ref session_id) = auth_user.session_id {
|
||||
state.auth.logout(session_id, None).await?;
|
||||
pub async fn logout_handler(State(state): State<AppState>, req: Request) -> ApiResult<Response> {
|
||||
let mut session_to_delete = None;
|
||||
|
||||
// 1. Try Bearer token in Authorization header
|
||||
if let Some(token) = req
|
||||
.headers()
|
||||
.get(AUTHORIZATION)
|
||||
.and_then(|v| v.to_str().ok())
|
||||
.and_then(|h| h.strip_prefix("Bearer "))
|
||||
{
|
||||
let token = token.trim();
|
||||
if !token.starts_with("nx9_") {
|
||||
session_to_delete = Some(token.to_string());
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Try session cookie (nx9_session=...)
|
||||
if session_to_delete.is_none()
|
||||
&& let Some(cookie_header) = req.headers().get(COOKIE).and_then(|v| v.to_str().ok())
|
||||
{
|
||||
for cookie in cookie_header.split(';') {
|
||||
let cookie = cookie.trim();
|
||||
if let Some(session_id) = cookie.strip_prefix("nx9_session=") {
|
||||
session_to_delete = Some(session_id.trim().to_string());
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(ref session_id) = session_to_delete {
|
||||
let _ = state.auth.logout(session_id, None).await;
|
||||
}
|
||||
|
||||
let cookie_val = "nx9_session=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0";
|
||||
|
||||
@@ -38,6 +38,7 @@ pub struct UpdateInterfaceRequest {
|
||||
pub address_v6: Option<String>,
|
||||
pub mtu: Option<u16>,
|
||||
pub dns: Option<String>,
|
||||
pub enabled: Option<bool>,
|
||||
pub pre_up: Option<String>,
|
||||
pub post_up: Option<String>,
|
||||
pub pre_down: Option<String>,
|
||||
@@ -144,8 +145,18 @@ pub async fn update_interface_handler(
|
||||
.ok_or_else(|| ApiError::NotFound(format!("Interface '{id}' not found")))?;
|
||||
|
||||
if let Some(ref name) = payload.name {
|
||||
validate_interface_name(name)?;
|
||||
iface.name = name.clone();
|
||||
let trimmed = name.trim();
|
||||
validate_interface_name(trimmed)?;
|
||||
if iface.name != trimmed {
|
||||
if let Ok(Some(existing)) = state.store.get_interface_by_name(trimmed).await
|
||||
&& existing.id != iface.id
|
||||
{
|
||||
return Err(ApiError::Validation(format!(
|
||||
"Interface with name '{trimmed}' already exists"
|
||||
)));
|
||||
}
|
||||
iface.name = trimmed.to_string();
|
||||
}
|
||||
}
|
||||
if let Some(port) = payload.listen_port {
|
||||
validate_listen_port(port)?;
|
||||
@@ -155,14 +166,25 @@ pub async fn update_interface_handler(
|
||||
iface.address_v4 = validate_cidr(v4)?;
|
||||
}
|
||||
if let Some(ref v6) = payload.address_v6 {
|
||||
iface.address_v6 = Some(validate_cidr(v6)?);
|
||||
if v6.trim().is_empty() {
|
||||
iface.address_v6 = None;
|
||||
} else {
|
||||
iface.address_v6 = Some(validate_cidr(v6.trim())?);
|
||||
}
|
||||
}
|
||||
if let Some(m) = payload.mtu {
|
||||
validate_mtu(m)?;
|
||||
iface.mtu = Some(m);
|
||||
}
|
||||
if let Some(ref dns) = payload.dns {
|
||||
iface.dns = Some(dns.clone());
|
||||
if dns.trim().is_empty() {
|
||||
iface.dns = None;
|
||||
} else {
|
||||
iface.dns = Some(dns.trim().to_string());
|
||||
}
|
||||
}
|
||||
if let Some(en) = payload.enabled {
|
||||
iface.enabled = en;
|
||||
}
|
||||
if payload.pre_up.is_some() {
|
||||
iface.pre_up = payload.pre_up;
|
||||
@@ -177,6 +199,8 @@ pub async fn update_interface_handler(
|
||||
iface.post_down = payload.post_down;
|
||||
}
|
||||
|
||||
iface.updated_at = Utc::now().naive_utc();
|
||||
|
||||
state.store.update_interface(&iface).await?;
|
||||
|
||||
state.broadcast(SystemEvent::InterfaceChanged {
|
||||
|
||||
@@ -28,7 +28,6 @@ pub fn build_api_router(state: AppState) -> Router {
|
||||
// 1. Protected routes (require authenticated admin via session or token)
|
||||
let protected_router = Router::new()
|
||||
// Auth management
|
||||
.route("/auth/logout", post(auth::logout_handler))
|
||||
.route("/auth/session", get(auth::session_handler))
|
||||
.route("/auth/password", post(auth::change_password_handler))
|
||||
.route("/auth/tokens", post(auth::create_token_handler))
|
||||
@@ -36,6 +35,7 @@ pub fn build_api_router(state: AppState) -> Router {
|
||||
.route("/auth/tokens/{id}", delete(auth::revoke_token_handler))
|
||||
// System
|
||||
.route("/system", get(system::system_overview_handler))
|
||||
.route("/system/live-state", get(system::live_state_handler))
|
||||
.route("/system/settings", get(system::list_settings_handler))
|
||||
.route("/system/settings", put(system::upsert_setting_handler))
|
||||
// Interfaces
|
||||
@@ -68,6 +68,7 @@ pub fn build_api_router(state: AppState) -> Router {
|
||||
)
|
||||
.route("/interfaces/{id}/peers", post(peers::create_peer_handler))
|
||||
// Peers
|
||||
.route("/peers", get(peers::list_peers_handler))
|
||||
.route("/peers/{id}", get(peers::get_peer_handler))
|
||||
.route("/peers/{id}", put(peers::update_peer_handler))
|
||||
.route("/peers/{id}", delete(peers::delete_peer_handler))
|
||||
@@ -191,6 +192,7 @@ pub fn build_api_router(state: AppState) -> Router {
|
||||
// 2. Public API routes (no authentication required)
|
||||
let public_router = Router::new()
|
||||
.route("/auth/login", post(auth::login_handler))
|
||||
.route("/auth/logout", post(auth::logout_handler))
|
||||
.route("/system/health", get(system::health_handler))
|
||||
.route("/system/version", get(system::version_handler))
|
||||
.route("/ws", get(ws::ws_handler));
|
||||
|
||||
@@ -8,6 +8,7 @@ use axum::Json;
|
||||
use axum::extract::{Path, Query, State};
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use chrono::{NaiveDateTime, Utc};
|
||||
use ipnet::IpNet;
|
||||
use nx9_wg_core::crypto::{generate_keypair, generate_preshared_key};
|
||||
use nx9_wg_core::types::network::Network;
|
||||
use nx9_wg_core::types::wireguard::{
|
||||
@@ -15,15 +16,47 @@ use nx9_wg_core::types::wireguard::{
|
||||
WireGuardPublicKey,
|
||||
};
|
||||
use nx9_wg_core::validation::{validate_cidr, validate_mtu, validate_peer_name};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use serde::{Deserialize, Deserializer, Serialize};
|
||||
use std::str::FromStr;
|
||||
use uuid::Uuid;
|
||||
|
||||
/// Deserialize `network_id` from JSON null/empty as None, and from a UUID string as Some.
|
||||
/// Rejects non-UUID values instead of silently falling back to the Interface CIDR.
|
||||
fn deserialize_optional_network_id<'de, D>(deserializer: D) -> Result<Option<Uuid>, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
let value = Option::<serde_json::Value>::deserialize(deserializer)?;
|
||||
match value {
|
||||
None | Some(serde_json::Value::Null) => Ok(None),
|
||||
Some(serde_json::Value::String(s)) => {
|
||||
let trimmed = s.trim();
|
||||
if trimmed.is_empty() {
|
||||
Ok(None)
|
||||
} else {
|
||||
Uuid::parse_str(trimmed).map(Some).map_err(|e| {
|
||||
serde::de::Error::custom(format!("network_id must be a Network UUID: {e}"))
|
||||
})
|
||||
}
|
||||
}
|
||||
Some(other) => Err(serde::de::Error::custom(format!(
|
||||
"network_id must be a UUID string, got {other}"
|
||||
))),
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct CreatePeerRequest {
|
||||
pub name: String,
|
||||
pub peer_type: Option<PeerType>,
|
||||
pub profile: Option<PeerProfile>,
|
||||
/// Subnet Network UUID for IP allocation. Also accepts the historical
|
||||
/// enrollment field name `network` when that value is a UUID.
|
||||
#[serde(
|
||||
default,
|
||||
alias = "network",
|
||||
deserialize_with = "deserialize_optional_network_id"
|
||||
)]
|
||||
pub network_id: Option<Uuid>,
|
||||
pub public_key: Option<String>,
|
||||
pub private_key: Option<String>,
|
||||
@@ -67,13 +100,241 @@ pub struct PeerLifecycleResponse {
|
||||
pub updated_at: NaiveDateTime,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct PeerResponse {
|
||||
pub id: Uuid,
|
||||
pub interface_id: Uuid,
|
||||
pub name: String,
|
||||
pub peer_type: PeerType,
|
||||
pub state: PeerState,
|
||||
pub public_key: WireGuardPublicKey,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub private_key: Option<WireGuardPrivateKey>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub preshared_key: Option<WireGuardPresharedKey>,
|
||||
pub endpoint: Option<String>,
|
||||
pub allowed_ips: String,
|
||||
pub server_allowed_ips: Option<String>,
|
||||
pub address_v4: Option<IpNet>,
|
||||
pub address_v6: Option<IpNet>,
|
||||
pub dns: Option<String>,
|
||||
pub mtu: Option<u16>,
|
||||
pub persistent_keepalive: Option<u16>,
|
||||
pub profile: PeerProfile,
|
||||
pub expires_at: Option<String>,
|
||||
pub last_handshake_at: Option<String>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub rx_bytes: Option<u64>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub tx_bytes: Option<u64>,
|
||||
pub created_at: String,
|
||||
pub updated_at: String,
|
||||
}
|
||||
|
||||
fn format_utc_rfc3339(dt: NaiveDateTime) -> String {
|
||||
let utc_dt = chrono::DateTime::<Utc>::from_naive_utc_and_offset(dt, Utc);
|
||||
utc_dt.to_rfc3339()
|
||||
}
|
||||
|
||||
fn to_peer_response(peer: Peer, live_stats: Option<&nx9_wireguard::LivePeerStats>) -> PeerResponse {
|
||||
let (endpoint, last_handshake_at, rx_bytes, tx_bytes) = if let Some(live) = live_stats {
|
||||
let ep = live.endpoint.clone().or(peer.endpoint.clone());
|
||||
let hs = live.last_handshake_at.or(peer.last_handshake_at);
|
||||
(ep, hs, Some(live.rx_bytes), Some(live.tx_bytes))
|
||||
} else {
|
||||
(peer.endpoint.clone(), peer.last_handshake_at, None, None)
|
||||
};
|
||||
|
||||
PeerResponse {
|
||||
id: peer.id,
|
||||
interface_id: peer.interface_id,
|
||||
name: peer.name,
|
||||
peer_type: peer.peer_type,
|
||||
state: peer.state,
|
||||
public_key: peer.public_key,
|
||||
private_key: peer.private_key,
|
||||
preshared_key: peer.preshared_key,
|
||||
endpoint,
|
||||
allowed_ips: peer.allowed_ips,
|
||||
server_allowed_ips: peer.server_allowed_ips,
|
||||
address_v4: peer.address_v4,
|
||||
address_v6: peer.address_v6,
|
||||
dns: peer.dns,
|
||||
mtu: peer.mtu,
|
||||
persistent_keepalive: peer.persistent_keepalive,
|
||||
profile: peer.profile,
|
||||
expires_at: peer.expires_at.map(format_utc_rfc3339),
|
||||
last_handshake_at: last_handshake_at.map(format_utc_rfc3339),
|
||||
rx_bytes,
|
||||
tx_bytes,
|
||||
created_at: format_utc_rfc3339(peer.created_at),
|
||||
updated_at: format_utc_rfc3339(peer.updated_at),
|
||||
}
|
||||
}
|
||||
|
||||
async fn enrich_peers_with_live_telemetry(state: &AppState, peers: Vec<Peer>) -> Vec<PeerResponse> {
|
||||
if peers.is_empty() {
|
||||
return Vec::new();
|
||||
}
|
||||
|
||||
// 1. Gather all unique interface IDs from peers and find interface names
|
||||
let mut iface_map = std::collections::HashMap::new();
|
||||
for p in &peers {
|
||||
if !iface_map.contains_key(&p.interface_id)
|
||||
&& let Ok(Some(iface)) = state.store.get_interface(p.interface_id).await
|
||||
{
|
||||
iface_map.insert(p.interface_id, iface.name);
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Query live interface stats for each interface
|
||||
let mut live_map = std::collections::HashMap::new();
|
||||
for iface_name in iface_map.values() {
|
||||
if let Ok(Some(stats)) = state.wg_engine.get_interface_stats(iface_name).await {
|
||||
for lp in stats.peers {
|
||||
live_map.insert(lp.public_key.clone(), lp);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Construct enriched PeerResponse and update DB cache if newer
|
||||
let mut responses = Vec::with_capacity(peers.len());
|
||||
for p in peers {
|
||||
let pub_key_str = p.public_key.to_string();
|
||||
let live_stat = live_map.get(&pub_key_str);
|
||||
|
||||
if let Some(live) = live_stat {
|
||||
let hs_newer =
|
||||
live.last_handshake_at.is_some() && live.last_handshake_at != p.last_handshake_at;
|
||||
let ep_newer =
|
||||
live.endpoint.is_some() && live.endpoint.as_deref() != p.endpoint.as_deref();
|
||||
|
||||
if hs_newer || ep_newer {
|
||||
let latest_hs = live.last_handshake_at.or(p.last_handshake_at);
|
||||
let latest_ep = live.endpoint.as_deref().or(p.endpoint.as_deref());
|
||||
let _ = state
|
||||
.store
|
||||
.update_peer_learned_telemetry(p.id, latest_hs, latest_ep)
|
||||
.await;
|
||||
}
|
||||
}
|
||||
|
||||
responses.push(to_peer_response(p, live_stat));
|
||||
}
|
||||
|
||||
responses
|
||||
}
|
||||
|
||||
/// GET /api/v1/peers
|
||||
pub async fn list_peers_handler(
|
||||
State(state): State<AppState>,
|
||||
) -> ApiResult<Json<Vec<PeerResponse>>> {
|
||||
let peers = state.store.list_all_peers().await?;
|
||||
let enriched = enrich_peers_with_live_telemetry(&state, peers).await;
|
||||
Ok(Json(enriched))
|
||||
}
|
||||
|
||||
/// GET /api/v1/interfaces/{id}/peers
|
||||
pub async fn list_peers_for_interface_handler(
|
||||
State(state): State<AppState>,
|
||||
Path(interface_id): Path<Uuid>,
|
||||
) -> ApiResult<Json<Vec<Peer>>> {
|
||||
) -> ApiResult<Json<Vec<PeerResponse>>> {
|
||||
let peers = state.store.list_peers_for_interface(interface_id).await?;
|
||||
Ok(Json(peers))
|
||||
let enriched = enrich_peers_with_live_telemetry(&state, peers).await;
|
||||
Ok(Json(enriched))
|
||||
}
|
||||
|
||||
async fn validate_no_server_allowed_ips_conflict(
|
||||
store: &nx9_wg_db::Store,
|
||||
interface_id: Uuid,
|
||||
peer_id: Option<Uuid>,
|
||||
candidate_server_allowed_ips: &str,
|
||||
) -> ApiResult<()> {
|
||||
if candidate_server_allowed_ips.trim().is_empty() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let candidate_nets: Vec<IpNet> = candidate_server_allowed_ips
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.filter_map(|s| s.parse::<IpNet>().ok())
|
||||
.collect();
|
||||
|
||||
if candidate_nets.is_empty() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let existing_peers = store.list_peers_for_interface(interface_id).await?;
|
||||
for ep in existing_peers {
|
||||
if ep.state != PeerState::Active {
|
||||
continue;
|
||||
}
|
||||
if Some(ep.id) == peer_id {
|
||||
continue;
|
||||
}
|
||||
let ep_server_allowed = ep.server_wireguard_allowed_ips();
|
||||
let ep_nets: Vec<IpNet> = ep_server_allowed
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.filter_map(|s| s.parse::<IpNet>().ok())
|
||||
.collect();
|
||||
|
||||
for n1 in &candidate_nets {
|
||||
for n2 in &ep_nets {
|
||||
if n1.contains(n2) || n2.contains(n1) {
|
||||
return Err(ApiError::Validation(format!(
|
||||
"Server-side AllowedIP '{n1}' overlaps with active peer '{}' AllowedIP '{n2}'",
|
||||
ep.name
|
||||
)));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Allocate a peer IPv4 address.
|
||||
///
|
||||
/// When `network_id` is present, allocation MUST use that Network's CIDR and
|
||||
/// MUST NOT fall back to the WireGuard Interface address space.
|
||||
/// When `network_id` is absent, preserve the existing Interface CIDR fallback.
|
||||
async fn allocate_address_v4_for_peer(
|
||||
store: &nx9_wg_db::Store,
|
||||
interface: &nx9_wg_core::types::wireguard::Interface,
|
||||
network_id: Option<Uuid>,
|
||||
) -> ApiResult<IpNet> {
|
||||
match network_id {
|
||||
Some(net_id) => {
|
||||
let network = store
|
||||
.get_network(net_id)
|
||||
.await?
|
||||
.ok_or_else(|| ApiError::NotFound(format!("Network '{net_id}' not found")))?;
|
||||
let allocated =
|
||||
IpAllocator::allocate_next_ip(store, &network, Some(interface), None).await?;
|
||||
if !network.cidr.contains(&allocated.addr()) {
|
||||
return Err(ApiError::Internal(format!(
|
||||
"allocated address {allocated} is outside selected network '{}' ({})",
|
||||
network.name, network.cidr
|
||||
)));
|
||||
}
|
||||
Ok(allocated)
|
||||
}
|
||||
None => {
|
||||
let fallback = Network {
|
||||
id: Uuid::nil(),
|
||||
name: format!("{}-subnet", interface.name),
|
||||
cidr: interface.address_v4,
|
||||
enabled: true,
|
||||
description: None,
|
||||
created_at: Utc::now().naive_utc(),
|
||||
updated_at: Utc::now().naive_utc(),
|
||||
};
|
||||
IpAllocator::allocate_next_ip(store, &fallback, Some(interface), None).await
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// POST /api/v1/interfaces/{id}/peers
|
||||
@@ -101,28 +362,12 @@ pub async fn create_peer_handler(
|
||||
_ => None,
|
||||
};
|
||||
|
||||
// If address_v4 was not explicitly provided, automatically allocate it
|
||||
// If address_v4 was not explicitly provided, automatically allocate it.
|
||||
// A present network_id selects the Subnet Network CIDR; None keeps the
|
||||
// Interface Network CIDR fallback. These paths are intentionally separate.
|
||||
if address_v4.is_none() {
|
||||
let net = match payload.network_id {
|
||||
Some(net_id) => state
|
||||
.store
|
||||
.get_network(net_id)
|
||||
.await?
|
||||
.ok_or_else(|| ApiError::NotFound(format!("Network '{net_id}' not found")))?,
|
||||
None => Network {
|
||||
id: Uuid::nil(),
|
||||
name: format!("{}-subnet", interface.name),
|
||||
cidr: interface.address_v4,
|
||||
enabled: true,
|
||||
description: None,
|
||||
created_at: Utc::now().naive_utc(),
|
||||
updated_at: Utc::now().naive_utc(),
|
||||
},
|
||||
};
|
||||
|
||||
let allocated =
|
||||
IpAllocator::allocate_next_ip(&state.store, &net, Some(&interface), None).await?;
|
||||
address_v4 = Some(allocated);
|
||||
address_v4 =
|
||||
Some(allocate_address_v4_for_peer(&state.store, &interface, payload.network_id).await?);
|
||||
}
|
||||
|
||||
let allowed_ips = match payload.allowed_ips {
|
||||
@@ -182,6 +427,15 @@ pub async fn create_peer_handler(
|
||||
updated_at: now,
|
||||
};
|
||||
|
||||
// Validate no overlapping server-side AllowedIPs with active peers on the same interface
|
||||
validate_no_server_allowed_ips_conflict(
|
||||
&state.store,
|
||||
interface_id,
|
||||
None,
|
||||
&peer.server_wireguard_allowed_ips(),
|
||||
)
|
||||
.await?;
|
||||
|
||||
state.store.create_peer(&peer).await?;
|
||||
|
||||
state.broadcast(SystemEvent::PeerChanged {
|
||||
@@ -196,13 +450,15 @@ pub async fn create_peer_handler(
|
||||
pub async fn get_peer_handler(
|
||||
State(state): State<AppState>,
|
||||
Path(id): Path<Uuid>,
|
||||
) -> ApiResult<Json<Peer>> {
|
||||
) -> ApiResult<Json<PeerResponse>> {
|
||||
let peer = state
|
||||
.store
|
||||
.get_peer(id)
|
||||
.await?
|
||||
.ok_or_else(|| ApiError::NotFound(format!("Peer '{id}' not found")))?;
|
||||
Ok(Json(peer))
|
||||
let mut enriched = enrich_peers_with_live_telemetry(&state, vec![peer]).await;
|
||||
let peer_resp = enriched.pop().unwrap();
|
||||
Ok(Json(peer_resp))
|
||||
}
|
||||
|
||||
/// PUT /api/v1/peers/{id}
|
||||
@@ -256,6 +512,15 @@ pub async fn update_peer_handler(
|
||||
peer.expires_at = payload.expires_at;
|
||||
}
|
||||
|
||||
// Validate no overlapping server-side AllowedIPs with active peers on the same interface
|
||||
validate_no_server_allowed_ips_conflict(
|
||||
&state.store,
|
||||
peer.interface_id,
|
||||
Some(peer.id),
|
||||
&peer.server_wireguard_allowed_ips(),
|
||||
)
|
||||
.await?;
|
||||
|
||||
state.store.update_peer(&peer).await?;
|
||||
|
||||
state.broadcast(SystemEvent::PeerChanged {
|
||||
@@ -391,6 +656,23 @@ pub struct ClientProfileQuery {
|
||||
pub nat: Option<String>,
|
||||
pub mtu: Option<u16>,
|
||||
pub profile: Option<String>,
|
||||
pub server_endpoint: Option<String>,
|
||||
pub endpoint: Option<String>,
|
||||
}
|
||||
|
||||
async fn resolve_server_endpoint(
|
||||
state: &AppState,
|
||||
query: &ClientProfileQuery,
|
||||
) -> ApiResult<String> {
|
||||
let explicit_override = query
|
||||
.server_endpoint
|
||||
.as_deref()
|
||||
.or(query.endpoint.as_deref());
|
||||
state
|
||||
.store
|
||||
.resolve_server_endpoint(explicit_override)
|
||||
.await
|
||||
.map_err(|e| ApiError::Validation(e.to_string()))
|
||||
}
|
||||
|
||||
#[derive(Debug, serde::Serialize)]
|
||||
@@ -418,12 +700,7 @@ pub async fn download_peer_config_handler(
|
||||
.await?
|
||||
.ok_or_else(|| ApiError::NotFound("Associated interface not found".to_string()))?;
|
||||
|
||||
let host = state
|
||||
.store
|
||||
.get_setting("server_endpoint")
|
||||
.await?
|
||||
.map(|s| s.value)
|
||||
.unwrap_or_else(|| "127.0.0.1".to_string());
|
||||
let host = resolve_server_endpoint(&state, &query).await?;
|
||||
|
||||
let resolved_profile = if query.provider.is_some()
|
||||
|| query.device.is_some()
|
||||
@@ -509,12 +786,7 @@ pub async fn get_peer_qr_handler(
|
||||
.await?
|
||||
.ok_or_else(|| ApiError::NotFound("Associated interface not found".to_string()))?;
|
||||
|
||||
let host = state
|
||||
.store
|
||||
.get_setting("server_endpoint")
|
||||
.await?
|
||||
.map(|s| s.value)
|
||||
.unwrap_or_else(|| "127.0.0.1".to_string());
|
||||
let host = resolve_server_endpoint(&state, &query).await?;
|
||||
|
||||
let resolved_profile = if query.provider.is_some()
|
||||
|| query.device.is_some()
|
||||
@@ -579,3 +851,55 @@ pub async fn get_peer_qr_handler(
|
||||
data_url,
|
||||
}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod create_peer_request_tests {
|
||||
use super::CreatePeerRequest;
|
||||
use uuid::Uuid;
|
||||
|
||||
const NETWORK_UUID: &str = "c2aa62c7-3b9d-43fb-95e7-aa8ab1c71265";
|
||||
|
||||
#[test]
|
||||
fn ui_payload_deserializes_network_id_uuid() {
|
||||
let json = serde_json::json!({
|
||||
"name": "sunil-moto-mobile-network-01",
|
||||
"peer_type": "road_warrior",
|
||||
"profile": "full_tunnel",
|
||||
"mtu": 1280,
|
||||
"persistent_keepalive": 25,
|
||||
"dns": "1.1.1.1, 1.0.0.1",
|
||||
"allowed_ips": "0.0.0.0/0, ::/0",
|
||||
"network_id": NETWORK_UUID
|
||||
});
|
||||
let req: CreatePeerRequest = serde_json::from_value(json).expect("deserialize UI payload");
|
||||
assert_eq!(req.network_id, Some(Uuid::parse_str(NETWORK_UUID).unwrap()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn historical_network_field_uuid_maps_to_network_id() {
|
||||
let json = serde_json::json!({
|
||||
"name": "sunil-moto-mobile-network-01",
|
||||
"network": NETWORK_UUID
|
||||
});
|
||||
let req: CreatePeerRequest =
|
||||
serde_json::from_value(json).expect("deserialize historical network field");
|
||||
assert_eq!(req.network_id, Some(Uuid::parse_str(NETWORK_UUID).unwrap()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn null_network_id_deserializes_as_none() {
|
||||
let json = serde_json::json!({
|
||||
"name": "bob-fallback",
|
||||
"network_id": null
|
||||
});
|
||||
let req: CreatePeerRequest = serde_json::from_value(json).expect("deserialize null");
|
||||
assert_eq!(req.network_id, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn missing_network_id_deserializes_as_none() {
|
||||
let json = serde_json::json!({ "name": "bob-fallback" });
|
||||
let req: CreatePeerRequest = serde_json::from_value(json).expect("deserialize missing");
|
||||
assert_eq!(req.network_id, None);
|
||||
}
|
||||
}
|
||||
@@ -94,24 +94,170 @@ pub async fn upsert_setting_handler(
|
||||
State(state): State<AppState>,
|
||||
Json(payload): Json<UpsertSettingRequest>,
|
||||
) -> ApiResult<Json<GenericSuccess>> {
|
||||
if payload.key.trim().is_empty() {
|
||||
let key_trimmed = payload.key.trim();
|
||||
if key_trimmed.is_empty() {
|
||||
return Err(ApiError::Validation(
|
||||
"Setting key cannot be empty".to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
let val_trimmed = payload.value.trim();
|
||||
if (key_trimmed == "server_endpoint" || key_trimmed == "public_endpoint")
|
||||
&& !val_trimmed.is_empty()
|
||||
{
|
||||
let has_valid_port = if let Some(last_colon) = val_trimmed.rfind(':') {
|
||||
let port_str = &val_trimmed[last_colon + 1..];
|
||||
if let Ok(port) = port_str.parse::<u16>() {
|
||||
port > 0 && !val_trimmed[..last_colon].trim().is_empty()
|
||||
} else {
|
||||
false
|
||||
}
|
||||
} else {
|
||||
false
|
||||
};
|
||||
|
||||
if !has_valid_port {
|
||||
return Err(ApiError::Validation(format!(
|
||||
"Invalid server endpoint '{val_trimmed}'. Endpoint must be formatted as host:port (e.g. 192.168.1.8:51820 or vpn.domain.com:51820)"
|
||||
)));
|
||||
}
|
||||
} else if key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_HOST {
|
||||
if !val_trimmed.is_empty() {
|
||||
nx9_wg_core::validation::validate_server_host(val_trimmed)
|
||||
.map_err(|e| ApiError::Validation(e.to_string()))?;
|
||||
}
|
||||
} else if key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_PORT {
|
||||
let port: u16 = val_trimmed.parse().map_err(|_| {
|
||||
ApiError::Validation(
|
||||
"Invalid server port: must be an integer between 1 and 65535".to_string(),
|
||||
)
|
||||
})?;
|
||||
nx9_wg_core::validation::validate_server_port(port)
|
||||
.map_err(|e| ApiError::Validation(e.to_string()))?;
|
||||
} else if key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_ENDPOINT_ENABLED
|
||||
&& val_trimmed != "true"
|
||||
&& val_trimmed != "false"
|
||||
&& val_trimmed != "1"
|
||||
&& val_trimmed != "0"
|
||||
{
|
||||
return Err(ApiError::Validation(
|
||||
"Setting wireguard.server_endpoint_enabled must be 'true' or 'false'".to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
let is_secret = payload.is_secret.unwrap_or(false);
|
||||
state
|
||||
.store
|
||||
.set_setting(&payload.key, &payload.value, is_secret)
|
||||
.set_setting(key_trimmed, val_trimmed, is_secret)
|
||||
.await?;
|
||||
|
||||
// If updating server host/port/enabled, also keep legacy server_endpoint in sync if valid
|
||||
if (key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_HOST
|
||||
|| key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_PORT
|
||||
|| key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_ENDPOINT_ENABLED)
|
||||
&& let Ok(settings) = state.store.get_server_endpoint_settings().await
|
||||
&& settings.enabled
|
||||
&& !settings.host.trim().is_empty()
|
||||
{
|
||||
let formatted = nx9_wg_core::validation::format_endpoint(&settings.host, settings.port);
|
||||
let _ = state
|
||||
.store
|
||||
.set_setting(
|
||||
nx9_wg_core::types::settings::LEGACY_SETTING_SERVER_ENDPOINT,
|
||||
&formatted,
|
||||
false,
|
||||
)
|
||||
.await;
|
||||
}
|
||||
|
||||
state.broadcast(SystemEvent::SettingsChanged {
|
||||
key: payload.key.clone(),
|
||||
key: key_trimmed.to_string(),
|
||||
});
|
||||
|
||||
Ok(Json(GenericSuccess {
|
||||
success: true,
|
||||
message: format!("Setting '{}' saved successfully", payload.key),
|
||||
message: format!("Setting '{key_trimmed}' saved"),
|
||||
}))
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize)]
|
||||
pub struct LiveInterfaceTelemetry {
|
||||
pub name: String,
|
||||
pub public_key: String,
|
||||
pub listen_port: u16,
|
||||
pub fwmark: u32,
|
||||
pub addresses: Vec<String>,
|
||||
pub mtu: Option<u32>,
|
||||
pub is_up: bool,
|
||||
pub peer_count: usize,
|
||||
pub peers: Vec<nx9_wireguard::LivePeerStats>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize)]
|
||||
pub struct LiveRouteTelemetry {
|
||||
pub destination: String,
|
||||
pub gateway: Option<String>,
|
||||
pub metric: Option<u32>,
|
||||
pub table: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize)]
|
||||
pub struct LiveSystemState {
|
||||
pub interfaces: Vec<LiveInterfaceTelemetry>,
|
||||
pub routes: Vec<LiveRouteTelemetry>,
|
||||
pub ipv4_forwarding: bool,
|
||||
pub ipv6_forwarding: bool,
|
||||
pub active_nftables: Option<String>,
|
||||
}
|
||||
|
||||
/// GET /api/v1/system/live-state
|
||||
pub async fn live_state_handler(State(state): State<AppState>) -> ApiResult<Json<LiveSystemState>> {
|
||||
let iface_names = state.wg_engine.list_interfaces().await.unwrap_or_default();
|
||||
let mut interfaces = Vec::new();
|
||||
|
||||
for name in iface_names {
|
||||
if let Ok(Some(stats)) = state.wg_engine.get_interface_stats(&name).await {
|
||||
let peer_count = stats.peers.len();
|
||||
interfaces.push(LiveInterfaceTelemetry {
|
||||
name: stats.name,
|
||||
public_key: stats.public_key,
|
||||
listen_port: stats.listen_port,
|
||||
fwmark: stats.fwmark,
|
||||
addresses: stats.addresses,
|
||||
mtu: stats.mtu,
|
||||
is_up: stats.is_up,
|
||||
peer_count,
|
||||
peers: stats.peers,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
let desired_routes = state.store.list_routes().await.unwrap_or_default();
|
||||
let routes = desired_routes
|
||||
.into_iter()
|
||||
.filter(|r| r.enabled)
|
||||
.map(|r| LiveRouteTelemetry {
|
||||
destination: r.destination.to_string(),
|
||||
gateway: r.gateway.map(|g| g.to_string()),
|
||||
metric: r.metric,
|
||||
table: 254,
|
||||
})
|
||||
.collect();
|
||||
|
||||
let fwd = state.net_engine.get_forwarding_status().await.unwrap_or(
|
||||
nx9_wg_network::IpForwardingStatus {
|
||||
ipv4_enabled: false,
|
||||
ipv6_enabled: false,
|
||||
},
|
||||
);
|
||||
|
||||
let active_nftables = state.net_engine.get_active_nftables_ruleset().await.ok();
|
||||
|
||||
Ok(Json(LiveSystemState {
|
||||
interfaces,
|
||||
routes,
|
||||
ipv4_forwarding: fwd.ipv4_enabled,
|
||||
ipv6_forwarding: fwd.ipv6_enabled,
|
||||
active_nftables,
|
||||
}))
|
||||
}
|
||||
@@ -4,6 +4,8 @@ use crate::error::{ApiError, ApiResult};
|
||||
use crate::state::AppState;
|
||||
use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
|
||||
use axum::extract::{Query, State};
|
||||
use axum::http::HeaderMap;
|
||||
use axum::http::header::COOKIE;
|
||||
use axum::response::IntoResponse;
|
||||
use futures_util::{SinkExt, StreamExt};
|
||||
use serde::Deserialize;
|
||||
@@ -14,24 +16,66 @@ pub struct WsAuthQuery {
|
||||
pub session: Option<String>,
|
||||
}
|
||||
|
||||
/// Extract the NX9 session identifier from the browser session cookie.
|
||||
///
|
||||
/// The WebUI authenticates through the HttpOnly `nx9_session` cookie.
|
||||
/// WebSocket upgrades do not pass through the normal REST authentication
|
||||
/// middleware, so the cookie must be authenticated explicitly here.
|
||||
fn extract_session_cookie(headers: &HeaderMap) -> Option<&str> {
|
||||
headers
|
||||
.get(COOKIE)
|
||||
.and_then(|value| value.to_str().ok())
|
||||
.and_then(|cookies| {
|
||||
cookies
|
||||
.split(';')
|
||||
.map(str::trim)
|
||||
.find_map(|cookie| cookie.strip_prefix("nx9_session="))
|
||||
})
|
||||
.map(str::trim)
|
||||
.filter(|session_id| !session_id.is_empty())
|
||||
}
|
||||
|
||||
/// Authenticate a WebSocket request.
|
||||
///
|
||||
/// Authentication precedence:
|
||||
///
|
||||
/// 1. Explicit API token: `?token=...`
|
||||
/// 2. Explicit session: `?session=...`
|
||||
/// 3. Browser session cookie: `nx9_session=...`
|
||||
///
|
||||
/// The browser WebUI uses the HttpOnly session cookie, so no credential
|
||||
/// needs to be exposed in the WebSocket URL.
|
||||
async fn authenticate_websocket(
|
||||
state: &AppState,
|
||||
query: &WsAuthQuery,
|
||||
headers: &HeaderMap,
|
||||
) -> bool {
|
||||
if let Some(raw_token) = query.token.as_deref() {
|
||||
return state.auth.authenticate_token(raw_token).await.is_ok();
|
||||
}
|
||||
|
||||
if let Some(session_id) = query.session.as_deref() {
|
||||
return state.auth.authenticate_session(session_id).await.is_ok();
|
||||
}
|
||||
|
||||
if let Some(session_id) = extract_session_cookie(headers) {
|
||||
return state.auth.authenticate_session(session_id).await.is_ok();
|
||||
}
|
||||
|
||||
false
|
||||
}
|
||||
|
||||
/// GET /api/v1/ws
|
||||
pub async fn ws_handler(
|
||||
ws: WebSocketUpgrade,
|
||||
State(state): State<AppState>,
|
||||
Query(query): Query<WsAuthQuery>,
|
||||
headers: HeaderMap,
|
||||
) -> ApiResult<impl IntoResponse> {
|
||||
// Authenticate WebSocket connection via query parameters
|
||||
let authenticated = if let Some(ref raw_token) = query.token {
|
||||
state.auth.authenticate_token(raw_token).await.is_ok()
|
||||
} else if let Some(ref session_id) = query.session {
|
||||
state.auth.authenticate_session(session_id).await.is_ok()
|
||||
} else {
|
||||
false
|
||||
};
|
||||
|
||||
if !authenticated {
|
||||
if !authenticate_websocket(&state, &query, &headers).await {
|
||||
return Err(ApiError::Unauthenticated(
|
||||
"WebSocket authentication required. Supply ?token=... or ?session=...".to_string(),
|
||||
"WebSocket authentication required. Supply a valid API token, session, or nx9_session cookie."
|
||||
.to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
@@ -42,11 +86,12 @@ async fn handle_socket(socket: WebSocket, state: AppState) {
|
||||
let (mut sender, mut receiver) = socket.split();
|
||||
let mut rx = state.event_tx.subscribe();
|
||||
|
||||
// Spawn background task to stream broadcast events to client
|
||||
// Stream broadcast events to the connected WebSocket client.
|
||||
let mut send_task = tokio::spawn(async move {
|
||||
while let Ok(event) = rx.recv().await {
|
||||
if let Ok(json) = serde_json::to_string(&event) {
|
||||
let msg = Message::Text(json.into());
|
||||
|
||||
if sender.send(msg).await.is_err() {
|
||||
break;
|
||||
}
|
||||
@@ -54,7 +99,7 @@ async fn handle_socket(socket: WebSocket, state: AppState) {
|
||||
}
|
||||
});
|
||||
|
||||
// Client receive loop to handle close/ping/pong
|
||||
// Receive loop handles client close frames and keeps the connection alive.
|
||||
let mut recv_task = tokio::spawn(async move {
|
||||
while let Some(Ok(msg)) = receiver.next().await {
|
||||
if let Message::Close(_) = msg {
|
||||
@@ -63,9 +108,13 @@ async fn handle_socket(socket: WebSocket, state: AppState) {
|
||||
}
|
||||
});
|
||||
|
||||
// If either task exits, abort the other
|
||||
// If either side terminates, stop the other task.
|
||||
tokio::select! {
|
||||
_ = (&mut send_task) => recv_task.abort(),
|
||||
_ = (&mut recv_task) => send_task.abort(),
|
||||
_ = (&mut send_task) => {
|
||||
recv_task.abort();
|
||||
}
|
||||
_ = (&mut recv_task) => {
|
||||
send_task.abort();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,14 @@
|
||||
use crate::auth::service::AuthService;
|
||||
use nx9_wg_core::types::audit::AuditEventType;
|
||||
use nx9_wg_db::Store;
|
||||
#[allow(unused_imports)]
|
||||
use nx9_wg_network::engine::{NativeLinuxNetworkEngine, NetworkEngine, SimulatedNetworkEngine};
|
||||
#[allow(unused_imports)]
|
||||
use nx9_wireguard::engine::{
|
||||
NativeLinuxWireGuardEngine, SimulatedWireGuardEngine, WireGuardEngine,
|
||||
};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::sync::Arc;
|
||||
use tokio::sync::broadcast;
|
||||
|
||||
/// Real-time system event broadcasted over WebSocket to connected clients.
|
||||
@@ -39,17 +46,41 @@ pub struct AppState {
|
||||
pub store: Store,
|
||||
pub auth: AuthService,
|
||||
pub event_tx: broadcast::Sender<SystemEvent>,
|
||||
pub wg_engine: Arc<dyn WireGuardEngine>,
|
||||
pub net_engine: Arc<dyn NetworkEngine>,
|
||||
}
|
||||
|
||||
impl AppState {
|
||||
/// Create a new AppState instance.
|
||||
/// Create a new AppState instance with default engines.
|
||||
pub fn new(store: Store) -> Self {
|
||||
#[cfg(target_os = "linux")]
|
||||
let (wg, net): (Arc<dyn WireGuardEngine>, Arc<dyn NetworkEngine>) = (
|
||||
Arc::new(NativeLinuxWireGuardEngine::new()),
|
||||
Arc::new(NativeLinuxNetworkEngine::new()),
|
||||
);
|
||||
#[cfg(not(target_os = "linux"))]
|
||||
let (wg, net): (Arc<dyn WireGuardEngine>, Arc<dyn NetworkEngine>) = (
|
||||
Arc::new(SimulatedWireGuardEngine::new()),
|
||||
Arc::new(SimulatedNetworkEngine::new()),
|
||||
);
|
||||
|
||||
Self::with_engines(store, wg, net)
|
||||
}
|
||||
|
||||
/// Create a new AppState instance with custom engines.
|
||||
pub fn with_engines(
|
||||
store: Store,
|
||||
wg_engine: Arc<dyn WireGuardEngine>,
|
||||
net_engine: Arc<dyn NetworkEngine>,
|
||||
) -> Self {
|
||||
let (event_tx, _) = broadcast::channel(256);
|
||||
let auth = AuthService::new(store.clone());
|
||||
Self {
|
||||
store,
|
||||
auth,
|
||||
event_tx,
|
||||
wg_engine,
|
||||
net_engine,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -253,3 +253,54 @@ async fn test_auth_service_api_tokens() {
|
||||
"revoked token must fail authentication"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_auth_service_logout_invalidates_session_and_is_idempotent() {
|
||||
let store = Store::connect_in_memory().await.expect("connect");
|
||||
store.migrate().await.expect("migrate");
|
||||
|
||||
let config = AppConfig::default();
|
||||
let opts = BootstrapOptions {
|
||||
cli_password: Some("AdminSecret123!".to_string()),
|
||||
..Default::default()
|
||||
};
|
||||
bootstrap_admin(&store, &config, &opts)
|
||||
.await
|
||||
.expect("bootstrap");
|
||||
|
||||
let auth = AuthService::new(store);
|
||||
|
||||
// Create 2 sessions
|
||||
let s1 = auth
|
||||
.login("admin", "AdminSecret123!", Some("10.0.0.1"), None)
|
||||
.await
|
||||
.expect("login 1");
|
||||
let s2 = auth
|
||||
.login("admin", "AdminSecret123!", Some("10.0.0.2"), None)
|
||||
.await
|
||||
.expect("login 2");
|
||||
|
||||
assert!(auth.authenticate_session(&s1.id).await.is_ok());
|
||||
assert!(auth.authenticate_session(&s2.id).await.is_ok());
|
||||
|
||||
// Logout session 1
|
||||
auth.logout(&s1.id, Some("10.0.0.1"))
|
||||
.await
|
||||
.expect("logout s1");
|
||||
|
||||
// Session 1 is invalidated; Session 2 remains valid
|
||||
assert!(
|
||||
auth.authenticate_session(&s1.id).await.is_err(),
|
||||
"s1 must be rejected after logout"
|
||||
);
|
||||
assert!(
|
||||
auth.authenticate_session(&s2.id).await.is_ok(),
|
||||
"s2 must remain valid"
|
||||
);
|
||||
|
||||
// Repeated logout of s1 is safe/idempotent
|
||||
assert!(
|
||||
auth.logout(&s1.id, Some("10.0.0.1")).await.is_ok(),
|
||||
"repeated logout must be safe and idempotent"
|
||||
);
|
||||
}
|
||||
@@ -79,6 +79,10 @@ async fn setup_test_app() -> (axum::Router, AppState, String, Interface, Peer) {
|
||||
updated_at: now,
|
||||
};
|
||||
store.create_peer(&peer).await.unwrap();
|
||||
store
|
||||
.set_setting("server_endpoint", "vpn.example.com", false)
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
let state = AppState::new(store);
|
||||
let app = nx9_wg_api::routes::build_api_router(state.clone());
|
||||
@@ -88,7 +92,7 @@ async fn setup_test_app() -> (axum::Router, AppState, String, Interface, Peer) {
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_client_profiles_endpoints() {
|
||||
let (app, _state, session_id, _iface, peer) = setup_test_app().await;
|
||||
let (app, state, session_id, interface, peer) = setup_test_app().await;
|
||||
|
||||
// 1. List client profiles
|
||||
let req = Request::builder()
|
||||
@@ -181,4 +185,67 @@ async fn test_client_profiles_endpoints() {
|
||||
.unwrap();
|
||||
let qr_json: serde_json::Value = serde_json::from_slice(&body).unwrap();
|
||||
assert!(qr_json["svg"].as_str().unwrap().contains("<svg"));
|
||||
|
||||
// 7. Delete server_endpoint setting and verify config export fails with actionable error
|
||||
state.store.delete_setting("server_endpoint").await.unwrap();
|
||||
let req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let err_json: serde_json::Value = serde_json::from_slice(&body).unwrap();
|
||||
assert!(
|
||||
err_json["error"]["message"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.contains("No reachable WireGuard server endpoint is configured")
|
||||
);
|
||||
|
||||
// 8. With query server_endpoint parameter, export succeeds even without DB setting
|
||||
let req = Request::builder()
|
||||
.uri(format!(
|
||||
"/api/v1/peers/{}/config?server_endpoint=custom.vpn.io:51820",
|
||||
peer.id
|
||||
))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::OK);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(body.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = custom.vpn.io:51820"));
|
||||
|
||||
// 9. Overlapping server-side AllowedIPs rejection
|
||||
let overlap_peer = serde_json::json!({
|
||||
"name": "overlapping-peer",
|
||||
"peer_type": "road_warrior",
|
||||
"address_v4": "10.0.0.2/32"
|
||||
});
|
||||
let req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{}/peers", interface.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.header("Content-Type", "application/json")
|
||||
.body(Body::from(serde_json::to_vec(&overlap_peer).unwrap()))
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let err_json: serde_json::Value = serde_json::from_slice(&body).unwrap();
|
||||
assert!(
|
||||
err_json["error"]["message"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.contains("overlaps with active peer")
|
||||
);
|
||||
}
|
||||
@@ -19,7 +19,7 @@ use nx9_wg_core::types::network::Route;
|
||||
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerProfile, PeerState, PeerType};
|
||||
use nx9_wg_core::validation::validate_cidr;
|
||||
use nx9_wg_db::Store;
|
||||
use nx9_wg_network::SimulatedNetworkEngine;
|
||||
use nx9_wg_network::{NetworkEngine, SimulatedNetworkEngine};
|
||||
use nx9_wireguard::{SimulatedWireGuardEngine, WireGuardEngine};
|
||||
use std::sync::Arc;
|
||||
use tempfile::{TempDir, tempdir};
|
||||
@@ -399,3 +399,187 @@ async fn test_reconciliation_status_lifecycle_and_multi_cycle_idempotency() {
|
||||
assert!(!plan.has_drift, "Cycle {cycle} plan must show zero drift");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_reconciliation_report_schema_and_json_contract() {
|
||||
use nx9_wg_api::reconciliation::{ReconciliationReport, ReconciliationStatus};
|
||||
|
||||
let report = ReconciliationReport {
|
||||
success: true,
|
||||
status: ReconciliationStatus::Converged,
|
||||
executed_actions: 3,
|
||||
failed_actions: 0,
|
||||
details: vec![
|
||||
"Synchronized interface 'wg0' with 5 peers".to_string(),
|
||||
"Synchronized 1 routing entries".to_string(),
|
||||
"Synchronized 0 firewall rules into table inet nx9_wg (NAT: true)".to_string(),
|
||||
],
|
||||
};
|
||||
|
||||
let json_val = serde_json::to_value(&report).unwrap();
|
||||
assert_eq!(json_val["success"], true);
|
||||
assert_eq!(json_val["status"], "converged");
|
||||
assert_eq!(json_val["executed_actions"], 3);
|
||||
assert_eq!(json_val["failed_actions"], 0);
|
||||
assert!(json_val["details"].is_array());
|
||||
assert_eq!(json_val["details"].as_array().unwrap().len(), 3);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_reconciliation_nftables_canonical_drift_and_kernel_handle_tolerance() {
|
||||
let (_dir, store, _state, _wg_engine, net_engine, reconciler) = setup_test_env().await;
|
||||
|
||||
// Add firewall rule in SQLite
|
||||
let fw = FirewallRule {
|
||||
id: Uuid::new_v4(),
|
||||
name: "allow-https".to_string(),
|
||||
interface_id: None,
|
||||
peer_id: None,
|
||||
direction: FirewallDirection::In,
|
||||
source: None,
|
||||
destination: None,
|
||||
protocol: FirewallProtocol::Tcp,
|
||||
source_port: None,
|
||||
destination_port: Some(443),
|
||||
port_range: None,
|
||||
action: FirewallAction::Accept,
|
||||
priority: 50,
|
||||
enabled: true,
|
||||
description: None,
|
||||
created_at: Utc::now().naive_utc(),
|
||||
updated_at: Utc::now().naive_utc(),
|
||||
};
|
||||
store.create_firewall_rule(&fw).await.unwrap();
|
||||
|
||||
// 1. Initial Plan should detect drift
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert!(plan.has_drift);
|
||||
assert_eq!(plan.firewall_changes, 1);
|
||||
|
||||
// 2. Apply should converge
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
assert_eq!(
|
||||
report.status,
|
||||
nx9_wg_api::reconciliation::ReconciliationStatus::Converged
|
||||
);
|
||||
assert_eq!(report.failed_actions, 0);
|
||||
|
||||
// 3. Post-apply verify: exactly 0 drift
|
||||
let plan_after = reconciler.plan().await.unwrap();
|
||||
assert!(!plan_after.has_drift);
|
||||
assert_eq!(plan_after.firewall_changes, 0);
|
||||
|
||||
// 4. Simulate kernel returning ruleset with handles and tabs
|
||||
let simulated_kernel_output_with_handles = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority filter; policy accept;
|
||||
ct state established,related accept # handle 46
|
||||
iifname "lo" accept # handle 1
|
||||
tcp dport 443 accept # handle 10
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority filter; policy accept;
|
||||
ct state established,related accept # handle 4
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
}
|
||||
}
|
||||
"#;
|
||||
// Set simulated ruleset to text containing kernel handles
|
||||
net_engine
|
||||
.sync_firewall(std::slice::from_ref(&fw), false, &[])
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
// Directly test drift function against simulated kernel handles
|
||||
let expected = nx9_wg_network::NftablesRulesetBuilder::build(&[fw], false, &[]);
|
||||
assert!(
|
||||
!nx9_wg_network::has_nftables_drift(&expected, simulated_kernel_output_with_handles),
|
||||
"Ruleset with handles must not trigger false drift"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_interface_address_and_mtu_drift_lifecycle() {
|
||||
let (_dir, store, _state, wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||
|
||||
let (priv_key, pub_key) = generate_keypair();
|
||||
let iface_id = Uuid::new_v4();
|
||||
let iface = Interface {
|
||||
id: iface_id,
|
||||
name: "wg0".to_string(),
|
||||
private_key: priv_key,
|
||||
public_key: pub_key.clone(),
|
||||
listen_port: 51820,
|
||||
address_v4: validate_cidr("10.100.0.1/24").unwrap(),
|
||||
address_v6: Some(validate_cidr("fd00::1/64").unwrap()),
|
||||
mtu: Some(1420),
|
||||
dns: None,
|
||||
enabled: true,
|
||||
pre_up: None,
|
||||
post_up: None,
|
||||
pre_down: None,
|
||||
post_down: None,
|
||||
created_at: Utc::now().naive_utc(),
|
||||
updated_at: Utc::now().naive_utc(),
|
||||
};
|
||||
store.create_interface(&iface).await.unwrap();
|
||||
|
||||
// 1. Initially, interface does not exist in wg_engine -> plan reports create_interface drift
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert!(plan.has_drift);
|
||||
assert_eq!(plan.interface_changes, 1);
|
||||
assert_eq!(plan.actions[0].action_type, "create_interface");
|
||||
|
||||
// 2. Apply initial sync -> interface is created and synchronized
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
assert_eq!(
|
||||
report.status,
|
||||
nx9_wg_api::reconciliation::ReconciliationStatus::Converged
|
||||
);
|
||||
|
||||
// 3. Post-apply plan must have 0 drift
|
||||
let plan_after = reconciler.plan().await.unwrap();
|
||||
assert!(!plan_after.has_drift);
|
||||
assert_eq!(plan_after.interface_changes, 0);
|
||||
|
||||
// 4. Manually strip IPv4 address from live interface to simulate kernel address drop
|
||||
let mut stats = wg_engine.get_interface_stats("wg0").await.unwrap().unwrap();
|
||||
stats.addresses = vec!["fd00::1/64".to_string()]; // IPv4 missing
|
||||
// Sync altered stats
|
||||
wg_engine
|
||||
.sync_interface(
|
||||
&Interface {
|
||||
address_v4: validate_cidr("10.99.99.99/24").unwrap(), // different
|
||||
..iface.clone()
|
||||
},
|
||||
&[],
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
// 5. Plan MUST detect the missing/mismatched IPv4 address as drift
|
||||
let plan_drift = reconciler.plan().await.unwrap();
|
||||
assert!(plan_drift.has_drift);
|
||||
assert_eq!(plan_drift.interface_changes, 1);
|
||||
assert_eq!(plan_drift.actions[0].action_type, "update_interface");
|
||||
assert!(plan_drift.actions[0].description.contains("IPv4 address"));
|
||||
|
||||
// 6. Apply reconciliation -> restores correct addresses
|
||||
let report2 = reconciler.apply().await.unwrap();
|
||||
assert!(report2.success);
|
||||
assert_eq!(
|
||||
report2.status,
|
||||
nx9_wg_api::reconciliation::ReconciliationStatus::Converged
|
||||
);
|
||||
|
||||
// 7. Final plan reports 0 drift
|
||||
let final_plan = reconciler.plan().await.unwrap();
|
||||
assert!(!final_plan.has_drift);
|
||||
assert_eq!(final_plan.interface_changes, 0);
|
||||
}
|
||||
@@ -234,3 +234,309 @@ async fn test_networks_and_firewall_rest_lifecycle() {
|
||||
assert_eq!(rule_val["name"], "Allow HTTPS");
|
||||
assert_eq!(rule_val["priority"], 10);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_list_all_peers_collection_endpoint() {
|
||||
let (app, cookie) = setup_test_app().await;
|
||||
|
||||
// 1. Verify unauthenticated GET /api/v1/peers returns 401 Unauthorized
|
||||
let unauth_req = Request::builder()
|
||||
.uri("/api/v1/peers")
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let unauth_resp = app.clone().oneshot(unauth_req).await.unwrap();
|
||||
assert_eq!(unauth_resp.status(), StatusCode::UNAUTHORIZED);
|
||||
|
||||
// 2. Create first interface (wg0)
|
||||
let iface0_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/interfaces")
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "wg0",
|
||||
"listen_port": 51820,
|
||||
"address_v4": "10.100.0.1/24"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let iface0_resp = app.clone().oneshot(iface0_req).await.unwrap();
|
||||
assert_eq!(iface0_resp.status(), StatusCode::OK);
|
||||
let iface0_val: Value =
|
||||
serde_json::from_slice(&to_bytes(iface0_resp.into_body(), usize::MAX).await.unwrap())
|
||||
.unwrap();
|
||||
let iface0_id = iface0_val["id"].as_str().unwrap();
|
||||
|
||||
// 3. Create second interface (wg1)
|
||||
let iface1_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/interfaces")
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "wg1",
|
||||
"listen_port": 51821,
|
||||
"address_v4": "10.200.0.1/24"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let iface1_resp = app.clone().oneshot(iface1_req).await.unwrap();
|
||||
assert_eq!(iface1_resp.status(), StatusCode::OK);
|
||||
let iface1_val: Value =
|
||||
serde_json::from_slice(&to_bytes(iface1_resp.into_body(), usize::MAX).await.unwrap())
|
||||
.unwrap();
|
||||
let iface1_id = iface1_val["id"].as_str().unwrap();
|
||||
|
||||
// 4. Create 2 peers under wg0
|
||||
let peer_alice_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{iface0_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "peer-alice",
|
||||
"allowed_ips": "10.100.0.2/32"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp_alice = app.clone().oneshot(peer_alice_req).await.unwrap();
|
||||
assert_eq!(resp_alice.status(), StatusCode::OK);
|
||||
|
||||
let peer_bob_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{iface0_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "peer-bob",
|
||||
"allowed_ips": "10.100.0.3/32"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp_bob = app.clone().oneshot(peer_bob_req).await.unwrap();
|
||||
assert_eq!(resp_bob.status(), StatusCode::OK);
|
||||
|
||||
// 5. Create 1 peer under wg1
|
||||
let peer_charlie_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{iface1_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "peer-charlie",
|
||||
"allowed_ips": "10.200.0.2/32"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp_charlie = app.clone().oneshot(peer_charlie_req).await.unwrap();
|
||||
assert_eq!(resp_charlie.status(), StatusCode::OK);
|
||||
|
||||
// 6. Test GET /api/v1/peers (All peers across all interfaces)
|
||||
let list_all_req = Request::builder()
|
||||
.uri("/api/v1/peers")
|
||||
.header(header::COOKIE, &cookie)
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let list_all_resp = app.clone().oneshot(list_all_req).await.unwrap();
|
||||
assert_eq!(list_all_resp.status(), StatusCode::OK);
|
||||
|
||||
let all_peers_bytes = to_bytes(list_all_resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let all_peers: Vec<Value> = serde_json::from_slice(&all_peers_bytes).unwrap();
|
||||
assert_eq!(
|
||||
all_peers.len(),
|
||||
3,
|
||||
"GET /api/v1/peers must return all 3 peers across both interfaces"
|
||||
);
|
||||
|
||||
let peer_names: Vec<&str> = all_peers
|
||||
.iter()
|
||||
.map(|p| p["name"].as_str().unwrap())
|
||||
.collect();
|
||||
assert!(peer_names.contains(&"peer-alice"));
|
||||
assert!(peer_names.contains(&"peer-bob"));
|
||||
assert!(peer_names.contains(&"peer-charlie"));
|
||||
|
||||
// Verify representative fields are present and valid
|
||||
for p in &all_peers {
|
||||
assert!(p["id"].is_string());
|
||||
assert!(p["public_key"].is_string());
|
||||
assert!(p["interface_id"].is_string());
|
||||
assert!(p["state"].is_string());
|
||||
assert!(p["allowed_ips"].is_string());
|
||||
}
|
||||
|
||||
// 7. Verify interface-scoped endpoint still works and returns only that interface's peers
|
||||
let list_iface0_req = Request::builder()
|
||||
.uri(format!("/api/v1/interfaces/{iface0_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let iface0_peers_resp = app.clone().oneshot(list_iface0_req).await.unwrap();
|
||||
assert_eq!(iface0_peers_resp.status(), StatusCode::OK);
|
||||
let iface0_peers: Vec<Value> = serde_json::from_slice(
|
||||
&to_bytes(iface0_peers_resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap(),
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(iface0_peers.len(), 2, "wg0 must return exactly 2 peers");
|
||||
|
||||
let list_iface1_req = Request::builder()
|
||||
.uri(format!("/api/v1/interfaces/{iface1_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let iface1_peers_resp = app.oneshot(list_iface1_req).await.unwrap();
|
||||
assert_eq!(iface1_peers_resp.status(), StatusCode::OK);
|
||||
let iface1_peers: Vec<Value> = serde_json::from_slice(
|
||||
&to_bytes(iface1_peers_resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap(),
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(iface1_peers.len(), 1, "wg1 must return exactly 1 peer");
|
||||
assert_eq!(iface1_peers[0]["name"], "peer-charlie");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_peer_creation_allocates_from_selected_network() {
|
||||
let (app, cookie) = setup_test_app().await;
|
||||
|
||||
// Interface Network (WireGuard transport address space)
|
||||
let create_iface_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/interfaces")
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "wg0",
|
||||
"listen_port": 51820,
|
||||
"address_v4": "10.100.0.1/24"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(create_iface_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let iface_val: Value =
|
||||
serde_json::from_slice(&to_bytes(resp.into_body(), usize::MAX).await.unwrap()).unwrap();
|
||||
let iface_id = iface_val["id"].as_str().unwrap().to_string();
|
||||
assert_eq!(iface_val["address_v4"], "10.100.0.1/24");
|
||||
|
||||
// Subnet Network (peer allocation domain)
|
||||
let create_net_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/networks")
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "mobile-clients",
|
||||
"cidr": "10.100.2.0/24"
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(create_net_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let net_val: Value =
|
||||
serde_json::from_slice(&to_bytes(resp.into_body(), usize::MAX).await.unwrap()).unwrap();
|
||||
let network_id = net_val["id"].as_str().unwrap();
|
||||
assert_eq!(net_val["cidr"], "10.100.2.0/24");
|
||||
|
||||
// Exact production enrollment payload: selected Subnet Network UUID as network_id.
|
||||
let selected_peer_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{iface_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "sunil-moto-mobile-network-01",
|
||||
"peer_type": "road_warrior",
|
||||
"profile": "full_tunnel",
|
||||
"mtu": 1280,
|
||||
"persistent_keepalive": 25,
|
||||
"dns": "1.1.1.1, 1.0.0.1",
|
||||
"allowed_ips": "0.0.0.0/0, ::/0",
|
||||
"network_id": network_id
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(selected_peer_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let selected_peer: Value =
|
||||
serde_json::from_slice(&to_bytes(resp.into_body(), usize::MAX).await.unwrap()).unwrap();
|
||||
let selected_addr = selected_peer["address_v4"].as_str().unwrap();
|
||||
assert_eq!(
|
||||
selected_addr, "10.100.2.1/32",
|
||||
"selected Network must allocate the first host of 10.100.2.0/24, got {selected_addr}"
|
||||
);
|
||||
assert!(
|
||||
selected_addr.starts_with("10.100.2."),
|
||||
"selected Network must allocate from 10.100.2.0/24, got {selected_addr}"
|
||||
);
|
||||
assert!(
|
||||
!selected_addr.starts_with("10.100.0."),
|
||||
"must not allocate from Interface Network 10.100.0.0/24 when a Subnet Network is selected, got {selected_addr}"
|
||||
);
|
||||
assert!(selected_addr.ends_with("/32"));
|
||||
|
||||
// network_id = null preserves existing fallback (Interface Network CIDR)
|
||||
let fallback_peer_req = Request::builder()
|
||||
.method("POST")
|
||||
.uri(format!("/api/v1/interfaces/{iface_id}/peers"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.header(header::CONTENT_TYPE, "application/json")
|
||||
.body(Body::from(
|
||||
json!({
|
||||
"name": "bob-fallback",
|
||||
"peer_type": "road_warrior",
|
||||
"profile": "full_tunnel",
|
||||
"network_id": null
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(fallback_peer_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let fallback_peer: Value =
|
||||
serde_json::from_slice(&to_bytes(resp.into_body(), usize::MAX).await.unwrap()).unwrap();
|
||||
let fallback_addr = fallback_peer["address_v4"].as_str().unwrap();
|
||||
assert!(
|
||||
fallback_addr.starts_with("10.100.0."),
|
||||
"network_id=null must preserve fallback allocation from Interface Network 10.100.0.0/24, got {fallback_addr}"
|
||||
);
|
||||
assert!(
|
||||
!fallback_addr.starts_with("10.100.2."),
|
||||
"network_id=null must not allocate from a Subnet Network, got {fallback_addr}"
|
||||
);
|
||||
assert!(fallback_addr.ends_with("/32"));
|
||||
|
||||
// WireGuard interface address space is unchanged
|
||||
let get_iface_req = Request::builder()
|
||||
.uri(format!("/api/v1/interfaces/{iface_id}"))
|
||||
.header(header::COOKIE, &cookie)
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let resp = app.oneshot(get_iface_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let iface_after: Value =
|
||||
serde_json::from_slice(&to_bytes(resp.into_body(), usize::MAX).await.unwrap()).unwrap();
|
||||
assert_eq!(iface_after["name"], "wg0");
|
||||
assert_eq!(iface_after["address_v4"], "10.100.0.1/24");
|
||||
}
|
||||
@@ -0,0 +1,845 @@
|
||||
//! Comprehensive tests for WireGuard road-warrior data-plane, cryptokey routing,
|
||||
//! endpoint resolution, telemetry ingestion, and reconciliation invariants.
|
||||
|
||||
use axum::body::Body;
|
||||
use axum::http::{Request, StatusCode};
|
||||
use chrono::Utc;
|
||||
use ipnet::IpNet;
|
||||
use nx9_wg_api::collect_managed_wg_subnets;
|
||||
use nx9_wg_api::reconciliation::ReconciliationEngine;
|
||||
use nx9_wg_api::routes::build_api_router;
|
||||
use nx9_wg_api::state::AppState;
|
||||
use nx9_wg_core::crypto::generate_keypair;
|
||||
use nx9_wg_core::types::network::Network;
|
||||
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerProfile, PeerState, PeerType};
|
||||
use nx9_wg_db::Store;
|
||||
use nx9_wg_network::{NetworkEngine, SimulatedNetworkEngine};
|
||||
use nx9_wireguard::{
|
||||
ClientConfigBuilder, LiveInterfaceStats, LivePeerStats, SimulatedWireGuardEngine,
|
||||
WireGuardEngine,
|
||||
};
|
||||
use std::str::FromStr;
|
||||
use std::sync::Arc;
|
||||
use tower::ServiceExt;
|
||||
use uuid::Uuid;
|
||||
|
||||
async fn setup_test_context() -> (AppState, Interface, Peer, String) {
|
||||
let store = Store::connect_in_memory().await.unwrap();
|
||||
store.migrate().await.unwrap();
|
||||
|
||||
let now = Utc::now().naive_utc();
|
||||
let hash = nx9_wg_core::crypto::hash_password("testadminpass123").unwrap();
|
||||
store.create_admin("admin", &hash).await.unwrap();
|
||||
|
||||
let session = nx9_wg_core::types::auth::Session {
|
||||
id: "test-dataplane-session-id".to_string(),
|
||||
admin_id: 1,
|
||||
created_at: now,
|
||||
expires_at: now + chrono::Duration::hours(24),
|
||||
last_seen_at: Some(now),
|
||||
ip_address: Some("127.0.0.1".to_string()),
|
||||
user_agent: Some("test-agent".to_string()),
|
||||
};
|
||||
store.create_session(&session).await.unwrap();
|
||||
|
||||
let (srv_priv, srv_pub) = generate_keypair();
|
||||
let (peer_priv, peer_pub) = generate_keypair();
|
||||
|
||||
let interface = Interface {
|
||||
id: Uuid::new_v4(),
|
||||
name: "wg0".to_string(),
|
||||
private_key: srv_priv,
|
||||
public_key: srv_pub,
|
||||
listen_port: 51820,
|
||||
address_v4: IpNet::from_str("10.100.0.1/24").unwrap(),
|
||||
address_v6: None,
|
||||
mtu: Some(1420),
|
||||
dns: Some("1.1.1.1, 1.0.0.1".to_string()),
|
||||
enabled: true,
|
||||
pre_up: None,
|
||||
post_up: None,
|
||||
pre_down: None,
|
||||
post_down: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
store.create_interface(&interface).await.unwrap();
|
||||
|
||||
let peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: interface.id,
|
||||
name: "Mobile".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: peer_pub,
|
||||
private_key: Some(peer_priv),
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(),
|
||||
server_allowed_ips: None,
|
||||
address_v4: Some(IpNet::from_str("10.100.0.9/32").unwrap()),
|
||||
address_v6: None,
|
||||
dns: Some("1.1.1.1, 1.0.0.1".to_string()),
|
||||
mtu: Some(1420),
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
store.create_peer(&peer).await.unwrap();
|
||||
|
||||
let state = AppState::new(store);
|
||||
(state, interface, peer, session.id)
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_road_warrior_server_allowed_ips_vs_client_full_tunnel() {
|
||||
let (_state, iface, peer, _session_id) = setup_test_context().await;
|
||||
|
||||
// 1. Server-side WireGuard peer AllowedIPs MUST be strictly the assigned client IP (10.100.0.9/32)
|
||||
assert_eq!(peer.server_wireguard_allowed_ips(), "10.100.0.9/32");
|
||||
|
||||
// 2. Client configuration MUST contain the FullTunnel routing policy (0.0.0.0/0 for IPv4-only server)
|
||||
let conf = ClientConfigBuilder::build(&peer, &iface, "192.168.1.8:51820").unwrap();
|
||||
assert!(conf.contains("Address = 10.100.0.9/32"));
|
||||
assert!(conf.contains("AllowedIPs = 0.0.0.0/0"));
|
||||
assert!(conf.contains("Endpoint = 192.168.1.8:51820"));
|
||||
assert!(conf.contains("PersistentKeepalive = 25"));
|
||||
|
||||
// Dual-stack interface exports dual-stack full tunnel
|
||||
let mut dual_iface = iface.clone();
|
||||
dual_iface.address_v6 = Some(IpNet::from_str("fd00::1/64").unwrap());
|
||||
let dual_conf = ClientConfigBuilder::build(&peer, &dual_iface, "192.168.1.8:51820").unwrap();
|
||||
assert!(dual_conf.contains("AllowedIPs = 0.0.0.0/0, ::/0"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_endpoint_resolution_failure_and_override() {
|
||||
let (state, _iface, peer, session_id) = setup_test_context().await;
|
||||
let app = build_api_router(state.clone());
|
||||
|
||||
// 1. Config export without persistent setting or query endpoint fails with 422
|
||||
let req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let err_json: serde_json::Value = serde_json::from_slice(&body).unwrap();
|
||||
assert!(
|
||||
err_json["error"]["message"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.contains("No reachable WireGuard server endpoint is configured")
|
||||
);
|
||||
|
||||
// 2. Setting persistent server_endpoint setting succeeds
|
||||
state
|
||||
.store
|
||||
.set_setting("server_endpoint", "192.168.1.8:51820", false)
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
let req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::OK);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(body.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = 192.168.1.8:51820"));
|
||||
|
||||
// 3. Explicit query parameter overrides persistent setting
|
||||
let req = Request::builder()
|
||||
.uri(format!(
|
||||
"/api/v1/peers/{}/config?server_endpoint=vpn.publicdomain.org:51820",
|
||||
peer.id
|
||||
))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let res = app.clone().oneshot(req).await.unwrap();
|
||||
assert_eq!(res.status(), StatusCode::OK);
|
||||
let body = axum::body::to_bytes(res.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(body.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = vpn.publicdomain.org:51820"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_learned_endpoint_and_handshake_telemetry_ingestion() {
|
||||
let (state, iface, peer, _session_id) = setup_test_context().await;
|
||||
|
||||
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
||||
|
||||
// Sync initial state to simulated engine
|
||||
wg_engine
|
||||
.sync_interface(&iface, std::slice::from_ref(&peer))
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
let reconciler =
|
||||
ReconciliationEngine::new(state.clone(), wg_engine.clone(), net_engine.clone());
|
||||
|
||||
// Initially peer has no learned endpoint or handshake in DB
|
||||
let p_db = state.store.get_peer(peer.id).await.unwrap().unwrap();
|
||||
assert!(p_db.endpoint.is_none());
|
||||
assert!(p_db.last_handshake_at.is_none());
|
||||
|
||||
// Simulate incoming authenticated handshake from client
|
||||
let hs_time = Utc::now().naive_utc();
|
||||
let learned_client_ep = "192.168.1.50:41234".to_string();
|
||||
|
||||
// Apply initial baseline state to ensure all subsystems start converged
|
||||
let initial_report = reconciler.apply().await.unwrap();
|
||||
assert!(initial_report.success);
|
||||
|
||||
// Directly simulate kernel stats containing learned endpoint and handshake
|
||||
let live_peers = vec![LivePeerStats {
|
||||
public_key: peer.public_key.as_str().to_string(),
|
||||
endpoint: Some(learned_client_ep.clone()),
|
||||
rx_bytes: 1024,
|
||||
tx_bytes: 2048,
|
||||
last_handshake_at: Some(hs_time),
|
||||
allowed_ips: vec!["10.100.0.9/32".to_string()],
|
||||
persistent_keepalive: Some(25),
|
||||
}];
|
||||
wg_engine
|
||||
.inject_interface_stats(LiveInterfaceStats {
|
||||
name: iface.name.clone(),
|
||||
public_key: iface.public_key.as_str().to_string(),
|
||||
listen_port: iface.listen_port,
|
||||
fwmark: 0,
|
||||
peers: live_peers,
|
||||
addresses: vec!["10.100.0.1/24".to_string()],
|
||||
mtu: Some(1420),
|
||||
is_up: true,
|
||||
})
|
||||
.await;
|
||||
|
||||
// Run reconciliation plan — should ingest telemetry without peer drift
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert_eq!(plan.peer_changes, 0);
|
||||
|
||||
// Verify learned telemetry was ingested into the SQLite store
|
||||
let updated_peer = state.store.get_peer(peer.id).await.unwrap().unwrap();
|
||||
assert_eq!(updated_peer.endpoint.as_deref(), Some("192.168.1.50:41234"));
|
||||
assert_eq!(
|
||||
updated_peer
|
||||
.last_handshake_at
|
||||
.unwrap()
|
||||
.and_utc()
|
||||
.timestamp(),
|
||||
hs_time.and_utc().timestamp()
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_peer_allowed_ips_and_keepalive_kernel_drift() {
|
||||
let (state, iface, peer, _session_id) = setup_test_context().await;
|
||||
|
||||
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
||||
|
||||
let reconciler =
|
||||
ReconciliationEngine::new(state.clone(), wg_engine.clone(), net_engine.clone());
|
||||
|
||||
// Inject drift: kernel peer erroneously has 0.0.0.0/0 as AllowedIPs and keepalive = 10s
|
||||
let drifted_peers = vec![LivePeerStats {
|
||||
public_key: peer.public_key.as_str().to_string(),
|
||||
endpoint: None,
|
||||
rx_bytes: 0,
|
||||
tx_bytes: 0,
|
||||
last_handshake_at: None,
|
||||
allowed_ips: vec!["0.0.0.0/0".to_string(), "::/0".to_string()],
|
||||
persistent_keepalive: Some(10),
|
||||
}];
|
||||
wg_engine
|
||||
.inject_interface_stats(LiveInterfaceStats {
|
||||
name: iface.name.clone(),
|
||||
public_key: iface.public_key.as_str().to_string(),
|
||||
listen_port: iface.listen_port,
|
||||
fwmark: 0,
|
||||
peers: drifted_peers,
|
||||
addresses: vec!["10.100.0.1/24".to_string()],
|
||||
mtu: Some(1420),
|
||||
is_up: true,
|
||||
})
|
||||
.await;
|
||||
|
||||
// Reconciliation plan MUST detect this semantic drift
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert!(plan.has_drift);
|
||||
assert_eq!(plan.peer_changes, 1);
|
||||
assert!(
|
||||
plan.actions
|
||||
.iter()
|
||||
.any(|a| a.action_type == "update_peer" && a.description.contains("AllowedIPs drift"))
|
||||
);
|
||||
|
||||
// Execute reconciliation apply
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
assert_eq!(
|
||||
report.status,
|
||||
nx9_wg_api::reconciliation::ReconciliationStatus::Converged
|
||||
);
|
||||
|
||||
// Verify post-apply convergence: zero drift
|
||||
let post_plan = reconciler.plan().await.unwrap();
|
||||
assert!(!post_plan.has_drift);
|
||||
assert_eq!(post_plan.peer_changes, 0);
|
||||
|
||||
// Verify live kernel stats now match desired server AllowedIPs (10.100.0.9/32)
|
||||
let live_stats = wg_engine.get_interface_stats("wg0").await.unwrap().unwrap();
|
||||
assert_eq!(live_stats.peers[0].allowed_ips, vec!["10.100.0.9/32"]);
|
||||
assert_eq!(live_stats.peers[0].persistent_keepalive, Some(25));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_forwarding_and_nat_reconciliation_invariants() {
|
||||
let (state, _iface, _peer, _session_id) = setup_test_context().await;
|
||||
|
||||
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
||||
|
||||
let reconciler =
|
||||
ReconciliationEngine::new(state.clone(), wg_engine.clone(), net_engine.clone());
|
||||
|
||||
// Enable NAT masquerade in settings
|
||||
state
|
||||
.store
|
||||
.set_setting("nat_enabled", "true", false)
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
// Reconcile apply
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
assert_eq!(
|
||||
report.status,
|
||||
nx9_wg_api::reconciliation::ReconciliationStatus::Converged
|
||||
);
|
||||
|
||||
// Verify NAT masquerade is active in network engine for 10.100.0.0/24 subnet
|
||||
let ruleset = net_engine.get_active_nftables_ruleset().await.unwrap();
|
||||
assert!(ruleset.contains("masquerade"));
|
||||
assert!(ruleset.contains("10.100.0.0/24"));
|
||||
|
||||
// Re-planning shows 0 drift
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert!(!plan.has_drift);
|
||||
assert_eq!(plan.firewall_changes, 0);
|
||||
assert_eq!(plan.route_changes, 0);
|
||||
assert_eq!(plan.interface_changes, 0);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_selected_network_dataplane_nat_and_routes() {
|
||||
let (state, iface, _peer, _session_id) = setup_test_context().await;
|
||||
let now = Utc::now().naive_utc();
|
||||
|
||||
let network = Network {
|
||||
id: Uuid::new_v4(),
|
||||
name: "mobile-clients".to_string(),
|
||||
cidr: IpNet::from_str("10.100.2.0/24").unwrap(),
|
||||
enabled: true,
|
||||
description: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
state.store.create_network(&network).await.unwrap();
|
||||
|
||||
let (peer_priv, peer_pub) = generate_keypair();
|
||||
let selected_peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: iface.id,
|
||||
name: "test-mobile".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: peer_pub,
|
||||
private_key: Some(peer_priv),
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(),
|
||||
server_allowed_ips: None,
|
||||
address_v4: Some(IpNet::from_str("10.100.2.1/32").unwrap()),
|
||||
address_v6: None,
|
||||
dns: Some("1.1.1.1, 1.0.0.1".to_string()),
|
||||
mtu: Some(1280),
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
state.store.create_peer(&selected_peer).await.unwrap();
|
||||
|
||||
assert_eq!(
|
||||
selected_peer.server_wireguard_allowed_ips(),
|
||||
"10.100.2.1/32",
|
||||
"server-side AllowedIPs must remain the assigned selected-Network address"
|
||||
);
|
||||
assert_eq!(selected_peer.allowed_ips, "0.0.0.0/0, ::/0");
|
||||
|
||||
let subnets = collect_managed_wg_subnets(&state.store).await.unwrap();
|
||||
assert!(
|
||||
subnets
|
||||
.iter()
|
||||
.any(|s| s.trunc().to_string() == "10.100.0.0/24"),
|
||||
"Interface CIDR must remain in managed NAT subnets"
|
||||
);
|
||||
assert!(
|
||||
subnets
|
||||
.iter()
|
||||
.any(|s| s.trunc().to_string() == "10.100.2.0/24"),
|
||||
"selected Network CIDR must participate in managed NAT subnets"
|
||||
);
|
||||
|
||||
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
||||
let reconciler =
|
||||
ReconciliationEngine::new(state.clone(), wg_engine.clone(), net_engine.clone());
|
||||
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
|
||||
let persisted_iface = state.store.get_interface(iface.id).await.unwrap().unwrap();
|
||||
assert_eq!(persisted_iface.address_v4.to_string(), "10.100.0.1/24");
|
||||
assert_eq!(persisted_iface.name, "wg0");
|
||||
let stored_routes = state.store.list_routes().await.unwrap();
|
||||
assert!(
|
||||
!stored_routes
|
||||
.iter()
|
||||
.any(|r| r.destination.trunc().to_string() == "10.100.2.0/24"),
|
||||
"peer-allocation Network CIDR must not be persisted as a static route"
|
||||
);
|
||||
|
||||
let ruleset = net_engine.get_active_nftables_ruleset().await.unwrap();
|
||||
assert!(
|
||||
ruleset.contains("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade"),
|
||||
"Interface-CIDR peers must keep existing NAT: {ruleset}"
|
||||
);
|
||||
assert!(
|
||||
ruleset.contains("ip saddr 10.100.2.0/24 oifname != \"wg*\" masquerade"),
|
||||
"selected Network CIDR must be masqueraded for full-tunnel Internet: {ruleset}"
|
||||
);
|
||||
|
||||
let live_stats = wg_engine.get_interface_stats("wg0").await.unwrap().unwrap();
|
||||
assert!(
|
||||
live_stats
|
||||
.peers
|
||||
.iter()
|
||||
.any(|p| p.allowed_ips.iter().any(|a| a == "10.100.2.1/32")),
|
||||
"kernel peer AllowedIPs must include the selected-Network assignment"
|
||||
);
|
||||
|
||||
let (fallback_priv, fallback_pub) = generate_keypair();
|
||||
let fallback_peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: iface.id,
|
||||
name: "fallback-null-network".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: fallback_pub,
|
||||
private_key: Some(fallback_priv),
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(),
|
||||
server_allowed_ips: None,
|
||||
address_v4: Some(IpNet::from_str("10.100.0.2/32").unwrap()),
|
||||
address_v6: None,
|
||||
dns: None,
|
||||
mtu: None,
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
state.store.create_peer(&fallback_peer).await.unwrap();
|
||||
assert_eq!(
|
||||
fallback_peer.server_wireguard_allowed_ips(),
|
||||
"10.100.0.2/32"
|
||||
);
|
||||
|
||||
let report = reconciler.apply().await.unwrap();
|
||||
assert!(report.success);
|
||||
let ruleset = net_engine.get_active_nftables_ruleset().await.unwrap();
|
||||
assert!(ruleset.contains("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade"));
|
||||
assert!(ruleset.contains("ip saddr 10.100.2.0/24 oifname != \"wg*\" masquerade"));
|
||||
|
||||
let plan = reconciler.plan().await.unwrap();
|
||||
assert!(!plan.has_drift);
|
||||
assert_eq!(plan.firewall_changes, 0);
|
||||
assert_eq!(plan.route_changes, 0);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_interface_editing_persistence_and_key_preservation() {
|
||||
let (state, iface, _peer, session_id) = setup_test_context().await;
|
||||
let app = build_api_router(state.clone());
|
||||
|
||||
let orig_priv_key = iface.private_key.clone();
|
||||
let orig_pub_key = iface.public_key.clone();
|
||||
let orig_id = iface.id;
|
||||
|
||||
// 1. Edit interface wg0 (change address_v4, listen_port, MTU, DNS, enabled)
|
||||
let update_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri(format!("/api/v1/interfaces/{}", iface.id))
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"name": "wg0",
|
||||
"address_v4": "10.200.0.1/24",
|
||||
"listen_port": 51822,
|
||||
"mtu": 1360,
|
||||
"dns": "9.9.9.9",
|
||||
"enabled": true
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(update_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
// 2. Query updated interface from database
|
||||
let updated_iface = state.store.get_interface(orig_id).await.unwrap().unwrap();
|
||||
assert_eq!(updated_iface.address_v4.to_string(), "10.200.0.1/24");
|
||||
assert_eq!(updated_iface.listen_port, 51822);
|
||||
assert_eq!(updated_iface.mtu, Some(1360));
|
||||
assert_eq!(updated_iface.dns, Some("9.9.9.9".to_string()));
|
||||
|
||||
// 3. Verify private key, public key, and ID were strictly preserved (NEVER regenerated)
|
||||
assert_eq!(updated_iface.id, orig_id);
|
||||
assert_eq!(updated_iface.private_key.as_str(), orig_priv_key.as_str());
|
||||
assert_eq!(updated_iface.public_key.as_str(), orig_pub_key.as_str());
|
||||
|
||||
// 4. Verify peers attached to wg0 were preserved
|
||||
let peers = state.store.list_peers_for_interface(orig_id).await.unwrap();
|
||||
assert_eq!(peers.len(), 1);
|
||||
assert_eq!(peers[0].name, "Mobile");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_server_endpoint_persistence_validation_and_export_precedence() {
|
||||
let (state, _iface, peer, session_id) = setup_test_context().await;
|
||||
let app = build_api_router(state.clone());
|
||||
|
||||
// 1. Invalid server_endpoint format (missing port) is rejected with 422
|
||||
let invalid_setting_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "server_endpoint",
|
||||
"value": "192.168.1.8", // missing port!
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(invalid_setting_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
|
||||
// 2. Valid server_endpoint saves successfully
|
||||
let valid_setting_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "server_endpoint",
|
||||
"value": "192.168.1.8:51820",
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(valid_setting_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
// 3. Export config without override consumes the persisted setting automatically
|
||||
let export_req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(export_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let conf_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(conf_bytes.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = 192.168.1.8:51820"));
|
||||
|
||||
// 4. Export QR code returns JSON with SVG and data_url containing the same endpoint
|
||||
let qr_req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/qr", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(qr_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let qr_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let qr_json: serde_json::Value = serde_json::from_slice(&qr_bytes).unwrap();
|
||||
assert!(qr_json["svg"].as_str().unwrap().contains("<svg"));
|
||||
assert!(
|
||||
qr_json["data_url"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.starts_with("data:image/png;base64,")
|
||||
);
|
||||
|
||||
// 5. Explicit override query parameter takes precedence over setting
|
||||
let override_req = Request::builder()
|
||||
.uri(format!(
|
||||
"/api/v1/peers/{}/config?endpoint=vpn.wan-domain.org:51820",
|
||||
peer.id
|
||||
))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(override_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let conf_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(conf_bytes.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = vpn.wan-domain.org:51820"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_structured_server_endpoint_settings_api_and_peer_export() {
|
||||
let (state, _iface, peer, session_id) = setup_test_context().await;
|
||||
let app = build_api_router(state.clone());
|
||||
|
||||
// 1. Invalid wireguard.server_host with embedded port is rejected with 422
|
||||
let invalid_host_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "wireguard.server_host",
|
||||
"value": "vpn.thakares.com:51820", // embedded port!
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(invalid_host_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
|
||||
// 2. Invalid wireguard.server_port (0) is rejected with 422
|
||||
let invalid_port_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "wireguard.server_port",
|
||||
"value": "0",
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(invalid_port_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
|
||||
|
||||
// 3. Valid wireguard.server_host and wireguard.server_port save successfully
|
||||
let set_host_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "wireguard.server_host",
|
||||
"value": "vpn.thakares.com",
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(set_host_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
let set_port_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "wireguard.server_port",
|
||||
"value": "51820",
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(set_port_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
// 4. Export config automatically resolves Endpoint = vpn.thakares.com:51820
|
||||
let export_req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(export_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let conf_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(conf_bytes.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = vpn.thakares.com:51820"));
|
||||
|
||||
// 5. Export QR returns valid SVG
|
||||
let qr_req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/qr", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(qr_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
// 6. Set IPv6 host -> exports [2001:db8::10]:51820
|
||||
let set_v6_req = Request::builder()
|
||||
.method("PUT")
|
||||
.uri("/api/v1/system/settings")
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::from(
|
||||
serde_json::json!({
|
||||
"key": "wireguard.server_host",
|
||||
"value": "2001:db8::10",
|
||||
"is_secret": false
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(set_v6_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
|
||||
let export_v6_req = Request::builder()
|
||||
.uri(format!("/api/v1/peers/{}/config", peer.id))
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
let resp = app.clone().oneshot(export_v6_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let conf_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let conf_str = String::from_utf8(conf_bytes.to_vec()).unwrap();
|
||||
assert!(conf_str.contains("Endpoint = [2001:db8::10]:51820"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_peer_telemetry_enrichment_and_status_transitions() {
|
||||
let (state_orig, iface, peer, session_id) = setup_test_context().await;
|
||||
|
||||
let simulated_wg = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let simulated_net = Arc::new(SimulatedNetworkEngine::new());
|
||||
let state = AppState::with_engines(
|
||||
state_orig.store.clone(),
|
||||
simulated_wg.clone(),
|
||||
simulated_net.clone(),
|
||||
);
|
||||
|
||||
// Inject live kernel statistics into simulated WireGuard engine
|
||||
let recent_hs = Utc::now().naive_utc() - chrono::Duration::seconds(15);
|
||||
let live_peer = LivePeerStats {
|
||||
public_key: peer.public_key.to_string(),
|
||||
endpoint: Some("192.168.1.50:41234".to_string()),
|
||||
rx_bytes: 409600,
|
||||
tx_bytes: 819200,
|
||||
last_handshake_at: Some(recent_hs),
|
||||
allowed_ips: vec!["10.100.0.9/32".to_string()],
|
||||
persistent_keepalive: Some(25),
|
||||
};
|
||||
|
||||
let live_iface = LiveInterfaceStats {
|
||||
name: iface.name.clone(),
|
||||
public_key: iface.public_key.to_string(),
|
||||
listen_port: iface.listen_port,
|
||||
fwmark: 0,
|
||||
peers: vec![live_peer],
|
||||
addresses: vec!["10.100.0.1/24".to_string()],
|
||||
mtu: Some(1420),
|
||||
is_up: true,
|
||||
};
|
||||
|
||||
// Inject live stats into simulated_wg
|
||||
simulated_wg.inject_interface_stats(live_iface).await;
|
||||
|
||||
let app = build_api_router(state.clone());
|
||||
|
||||
// Query GET /api/v1/peers
|
||||
let list_req = Request::builder()
|
||||
.uri("/api/v1/peers")
|
||||
.header("Cookie", format!("nx9_session={session_id}"))
|
||||
.body(Body::empty())
|
||||
.unwrap();
|
||||
|
||||
let resp = app.clone().oneshot(list_req).await.unwrap();
|
||||
assert_eq!(resp.status(), StatusCode::OK);
|
||||
let body_bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
|
||||
.await
|
||||
.unwrap();
|
||||
let peers_json: Vec<serde_json::Value> = serde_json::from_slice(&body_bytes).unwrap();
|
||||
assert_eq!(peers_json.len(), 1);
|
||||
|
||||
let p = &peers_json[0];
|
||||
assert_eq!(p["name"], "Mobile");
|
||||
assert_eq!(p["endpoint"], "192.168.1.50:41234");
|
||||
assert_eq!(p["rx_bytes"], 409600);
|
||||
assert_eq!(p["tx_bytes"], 819200);
|
||||
|
||||
// Handshake is serialized as explicit RFC3339 UTC string with offset/Z
|
||||
let hs_str = p["last_handshake_at"].as_str().unwrap();
|
||||
assert!(hs_str.contains('T'));
|
||||
assert!(hs_str.ends_with('Z') || hs_str.contains("+00:00"));
|
||||
|
||||
// Verify learned telemetry was cached in SQLite
|
||||
let db_peer = state.store.get_peer(peer.id).await.unwrap().unwrap();
|
||||
assert_eq!(db_peer.endpoint, Some("192.168.1.50:41234".to_string()));
|
||||
assert_eq!(
|
||||
db_peer.last_handshake_at.unwrap().and_utc().timestamp(),
|
||||
recent_hs.and_utc().timestamp()
|
||||
);
|
||||
}
|
||||
@@ -7,6 +7,24 @@ use nx9_wg_api::state::AppState;
|
||||
use nx9_wg_db::Store;
|
||||
use tower::ServiceExt;
|
||||
|
||||
async fn setup_test_app() -> (axum::Router, Store) {
|
||||
let store = Store::connect_in_memory().await.expect("connect store");
|
||||
store.migrate().await.expect("migrate store");
|
||||
|
||||
let config = nx9_wg_core::config::AppConfig::default();
|
||||
let opts = nx9_wg_api::auth::BootstrapOptions {
|
||||
cli_password: Some("TestAdminPassword123!".to_string()),
|
||||
..Default::default()
|
||||
};
|
||||
nx9_wg_api::auth::bootstrap_admin(&store, &config, &opts)
|
||||
.await
|
||||
.expect("bootstrap admin");
|
||||
|
||||
let state = AppState::new(store.clone());
|
||||
let app = build_api_router(state);
|
||||
(app, store)
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_ui_spa_index_and_stylesheet_endpoints() {
|
||||
let store = Store::connect_in_memory().await.expect("connect store");
|
||||
@@ -105,6 +123,16 @@ async fn test_ui_spa_index_and_stylesheet_endpoints() {
|
||||
assert!(html.contains("triggerCreateBackup"));
|
||||
assert!(html.contains("openClientExportModal"));
|
||||
assert!(html.contains("openAddPeerModal"));
|
||||
|
||||
// Peer enrollment must submit the selected Network UUID as network_id,
|
||||
// never the display name or CIDR.
|
||||
assert!(html.contains(r#"value="${n.id}""#));
|
||||
assert!(html.contains("${escapeHtml(n.name)} (${n.cidr})"));
|
||||
assert!(html.contains("network_id: networkId"));
|
||||
assert!(html.contains("isNetworkUuid"));
|
||||
assert!(html.contains("selectedNetwork.id"));
|
||||
assert!(!html.contains("network: network || null"));
|
||||
assert!(!html.contains(r#"value="${n.name}""#));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
@@ -121,6 +149,11 @@ async fn test_ui_api_complete_functional_loop() {
|
||||
.await
|
||||
.expect("bootstrap admin");
|
||||
|
||||
store
|
||||
.set_setting("server_endpoint", "vpn.example.com", false)
|
||||
.await
|
||||
.expect("set server_endpoint");
|
||||
|
||||
let state = AppState::new(store.clone());
|
||||
let app = build_api_router(state);
|
||||
|
||||
@@ -227,6 +260,26 @@ async fn test_ui_api_complete_functional_loop() {
|
||||
let peer_json: serde_json::Value = serde_json::from_slice(&peer_body).unwrap();
|
||||
let peer_id = peer_json["id"].as_str().unwrap();
|
||||
|
||||
// 4b. UI fetches collection of all peers (Peers page render: GET /api/v1/peers)
|
||||
let res_all_peers = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri("/api/v1/peers")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.expect("get all peers");
|
||||
assert_eq!(res_all_peers.status(), StatusCode::OK);
|
||||
let all_peers_bytes = to_bytes(res_all_peers.into_body(), 1024 * 1024)
|
||||
.await
|
||||
.unwrap();
|
||||
let all_peers_json: Vec<serde_json::Value> = serde_json::from_slice(&all_peers_bytes).unwrap();
|
||||
assert_eq!(all_peers_json.len(), 1);
|
||||
assert_eq!(all_peers_json[0]["name"], "alice-phone");
|
||||
|
||||
// 5. UI downloads Client Config & SVG QR Code
|
||||
let res_conf = app
|
||||
.clone()
|
||||
@@ -452,6 +505,7 @@ async fn test_ui_api_complete_functional_loop() {
|
||||
|
||||
// 13. UI Logout
|
||||
let res_logout = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.method("POST")
|
||||
@@ -463,4 +517,205 @@ async fn test_ui_api_complete_functional_loop() {
|
||||
.await
|
||||
.expect("logout request");
|
||||
assert_eq!(res_logout.status(), StatusCode::OK);
|
||||
|
||||
// 14. Post-Logout: Session must be completely rejected on protected endpoints
|
||||
let res_post_logout = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri("/api/v1/auth/session")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.expect("post-logout session request");
|
||||
assert_eq!(res_post_logout.status(), StatusCode::UNAUTHORIZED);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_logout_session_invalidation_and_idempotency() {
|
||||
let (app, _store) = setup_test_app().await;
|
||||
|
||||
// 1. Initial login
|
||||
let login_body = serde_json::to_vec(&serde_json::json!({
|
||||
"username": "admin",
|
||||
"password": "TestAdminPassword123!"
|
||||
}))
|
||||
.unwrap();
|
||||
|
||||
let res_login = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/auth/login")
|
||||
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||
.body(axum::body::Body::from(login_body))
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.expect("login request");
|
||||
assert_eq!(res_login.status(), StatusCode::OK);
|
||||
|
||||
let cookie_header = res_login
|
||||
.headers()
|
||||
.get(axum::http::header::SET_COOKIE)
|
||||
.expect("Set-Cookie header present")
|
||||
.to_str()
|
||||
.unwrap();
|
||||
let session_cookie = cookie_header
|
||||
.split(';')
|
||||
.next()
|
||||
.expect("nx9_session cookie")
|
||||
.to_string();
|
||||
|
||||
// 2. Verified access before logout
|
||||
let res_auth_session = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri("/api/v1/auth/session")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(res_auth_session.status(), StatusCode::OK);
|
||||
|
||||
let res_system = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri("/api/v1/system")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(res_system.status(), StatusCode::OK);
|
||||
|
||||
// 3. Perform Logout
|
||||
let res_logout = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/auth/logout")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(res_logout.status(), StatusCode::OK);
|
||||
|
||||
let logout_cookie = res_logout
|
||||
.headers()
|
||||
.get(axum::http::header::SET_COOKIE)
|
||||
.expect("Set-Cookie on logout")
|
||||
.to_str()
|
||||
.unwrap();
|
||||
assert!(
|
||||
logout_cookie.contains("Max-Age=0"),
|
||||
"Logout must clear session cookie with Max-Age=0"
|
||||
);
|
||||
|
||||
// 4. All protected endpoints must return 401 Unauthorized after logout
|
||||
let endpoints = [
|
||||
"/api/v1/auth/session",
|
||||
"/api/v1/system",
|
||||
"/api/v1/interfaces",
|
||||
"/api/v1/networks",
|
||||
"/api/v1/routes",
|
||||
"/api/v1/firewall/rules",
|
||||
"/api/v1/diagnostics/all",
|
||||
"/api/v1/client-profiles",
|
||||
"/api/v1/audit",
|
||||
"/api/v1/backups",
|
||||
"/api/v1/reconcile/plan",
|
||||
];
|
||||
|
||||
for ep in endpoints {
|
||||
let res_blocked = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri(ep)
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
res_blocked.status(),
|
||||
StatusCode::UNAUTHORIZED,
|
||||
"Endpoint {ep} must be blocked (401) after logout"
|
||||
);
|
||||
}
|
||||
|
||||
// 5. Repeated logout when already logged out is safe and idempotent
|
||||
let res_logout_again = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.method("POST")
|
||||
.uri("/api/v1/auth/logout")
|
||||
.header(axum::http::header::COOKIE, &session_cookie)
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(res_logout_again.status(), StatusCode::OK);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_ui_index_contains_login_view_and_hidden_app_layout() {
|
||||
let (app, _store) = setup_test_app().await;
|
||||
|
||||
let res = app
|
||||
.clone()
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri("/")
|
||||
.body(axum::body::Body::empty())
|
||||
.unwrap(),
|
||||
)
|
||||
.await
|
||||
.expect("index request");
|
||||
assert_eq!(res.status(), StatusCode::OK);
|
||||
|
||||
let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
|
||||
.await
|
||||
.unwrap();
|
||||
let html = String::from_utf8(bytes.to_vec()).unwrap();
|
||||
|
||||
assert!(
|
||||
html.contains("id=\"login-view\""),
|
||||
"HTML must contain dedicated login-view container"
|
||||
);
|
||||
assert!(
|
||||
html.contains("id=\"app-layout\" style=\"display: none;\""),
|
||||
"app-layout must be initially hidden until authenticated"
|
||||
);
|
||||
assert!(
|
||||
html.contains("id=\"login-username\""),
|
||||
"HTML must contain login username input"
|
||||
);
|
||||
assert!(
|
||||
html.contains("id=\"login-password\""),
|
||||
"HTML must contain login password input"
|
||||
);
|
||||
assert!(
|
||||
html.contains("id=\"login-submit-btn\""),
|
||||
"HTML must contain login submit button"
|
||||
);
|
||||
assert!(
|
||||
html.contains("handleLogout()"),
|
||||
"HTML must contain handleLogout handler"
|
||||
);
|
||||
}
|
||||
@@ -29,3 +29,27 @@ impl std::fmt::Debug for Setting {
|
||||
.finish()
|
||||
}
|
||||
}
|
||||
|
||||
/// Persistent WireGuard server endpoint configuration.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
pub struct ServerEndpointSettings {
|
||||
pub host: String,
|
||||
pub port: u16,
|
||||
pub enabled: bool,
|
||||
}
|
||||
|
||||
impl Default for ServerEndpointSettings {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
host: String::new(),
|
||||
port: 51820,
|
||||
enabled: true,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub const SETTING_SERVER_HOST: &str = "wireguard.server_host";
|
||||
pub const SETTING_SERVER_PORT: &str = "wireguard.server_port";
|
||||
pub const SETTING_SERVER_ENDPOINT_ENABLED: &str = "wireguard.server_endpoint_enabled";
|
||||
pub const LEGACY_SETTING_SERVER_ENDPOINT: &str = "server_endpoint";
|
||||
pub const LEGACY_SETTING_PUBLIC_ENDPOINT: &str = "public_endpoint";
|
||||
@@ -215,9 +215,82 @@ pub struct Peer {
|
||||
pub updated_at: NaiveDateTime,
|
||||
}
|
||||
|
||||
impl Peer {
|
||||
/// Returns the effective server-side WireGuard AllowedIPs string for this peer.
|
||||
///
|
||||
/// # Semantics:
|
||||
/// - If `server_allowed_ips` is explicitly configured and non-empty, it is used after
|
||||
/// validating CIDRs. For `RoadWarrior` peers, default full-tunnel routes (`0.0.0.0/0`, `::/0`)
|
||||
/// are strictly forbidden as server-side AllowedIPs.
|
||||
/// - For `RoadWarrior` peers: derives exclusively from the peer's assigned tunnel addresses
|
||||
/// (`address_v4/32` and `address_v6/128`).
|
||||
/// - For non-`RoadWarrior` peers (e.g. `SiteGateway`, `Server`, `Relay`): uses assigned tunnel
|
||||
/// addresses or explicit subnets from `allowed_ips` (excluding `0.0.0.0/0` and `::/0`).
|
||||
///
|
||||
/// # Invariants:
|
||||
/// - NEVER returns `0.0.0.0/0` or `::/0` as server-side AllowedIPs for a RoadWarrior peer.
|
||||
/// - NEVER falls back to client full-tunnel routing policy.
|
||||
pub fn server_wireguard_allowed_ips(&self) -> String {
|
||||
// 1. Explicit server_allowed_ips override
|
||||
if let Some(ref s_allowed) = self.server_allowed_ips {
|
||||
let trimmed = s_allowed.trim();
|
||||
if !trimmed.is_empty() {
|
||||
let mut valid_cidrs = Vec::new();
|
||||
for item in trimmed.split(',') {
|
||||
let item_trim = item.trim();
|
||||
if let Ok(net) = item_trim.parse::<IpNet>() {
|
||||
// For RoadWarrior, reject 0.0.0.0/0 or ::/0
|
||||
if self.peer_type == PeerType::RoadWarrior && net.prefix_len() == 0 {
|
||||
continue;
|
||||
}
|
||||
valid_cidrs.push(net.to_string());
|
||||
}
|
||||
}
|
||||
if !valid_cidrs.is_empty() {
|
||||
return valid_cidrs.join(", ");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Default for RoadWarrior (and default for any peer with assigned addresses):
|
||||
// Derive exclusively from assigned tunnel addresses (/32 and /128)
|
||||
let mut addrs = Vec::new();
|
||||
if let Some(ref v4) = self.address_v4 {
|
||||
addrs.push(format!("{}/32", v4.addr()));
|
||||
}
|
||||
if let Some(ref v6) = self.address_v6 {
|
||||
addrs.push(format!("{}/128", v6.addr()));
|
||||
}
|
||||
|
||||
if !addrs.is_empty() {
|
||||
return addrs.join(", ");
|
||||
}
|
||||
|
||||
// 3. For non-RoadWarrior peers without assigned tunnel addresses (e.g. site gateway routing subnets),
|
||||
// inspect allowed_ips, strictly excluding default 0.0.0.0/0 and ::/0
|
||||
if self.peer_type != PeerType::RoadWarrior {
|
||||
let mut valid_cidrs = Vec::new();
|
||||
for item in self.allowed_ips.split(',') {
|
||||
let item_trim = item.trim();
|
||||
if let Ok(net) = item_trim.parse::<IpNet>()
|
||||
&& net.prefix_len() > 0
|
||||
{
|
||||
valid_cidrs.push(net.to_string());
|
||||
}
|
||||
}
|
||||
if !valid_cidrs.is_empty() {
|
||||
return valid_cidrs.join(", ");
|
||||
}
|
||||
}
|
||||
|
||||
String::new()
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use chrono::Utc;
|
||||
|
||||
#[test]
|
||||
fn test_peer_type_roundtrip() {
|
||||
@@ -233,4 +306,102 @@ mod tests {
|
||||
let pk = WireGuardPrivateKey::new("secret".to_string());
|
||||
assert_eq!(format!("{:?}", pk), "[REDACTED]");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_road_warrior_server_allowed_ips_derives_from_assigned_address() {
|
||||
let now = Utc::now().naive_utc();
|
||||
let peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: Uuid::new_v4(),
|
||||
name: "Mobile".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: WireGuardPublicKey::new("pubkey123".to_string()),
|
||||
private_key: None,
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(), // Client full tunnel routing policy
|
||||
server_allowed_ips: None,
|
||||
address_v4: Some("10.100.0.9/24".parse().unwrap()),
|
||||
address_v6: Some("fd00::9/64".parse().unwrap()),
|
||||
dns: None,
|
||||
mtu: None,
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
|
||||
// Server-side AllowedIPs MUST be 10.100.0.9/32, fd00::9/128 (never 0.0.0.0/0)
|
||||
assert_eq!(
|
||||
peer.server_wireguard_allowed_ips(),
|
||||
"10.100.0.9/32, fd00::9/128"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_road_warrior_explicit_server_allowed_ips_override() {
|
||||
let now = Utc::now().naive_utc();
|
||||
let peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: Uuid::new_v4(),
|
||||
name: "Mobile".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: WireGuardPublicKey::new("pubkey123".to_string()),
|
||||
private_key: None,
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(),
|
||||
server_allowed_ips: Some("10.100.0.9/32, 192.168.50.0/24".to_string()),
|
||||
address_v4: Some("10.100.0.9/32".parse().unwrap()),
|
||||
address_v6: None,
|
||||
dns: None,
|
||||
mtu: None,
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
|
||||
assert_eq!(
|
||||
peer.server_wireguard_allowed_ips(),
|
||||
"10.100.0.9/32, 192.168.50.0/24"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_road_warrior_forbids_default_route_as_server_allowed_ips() {
|
||||
let now = Utc::now().naive_utc();
|
||||
let peer = Peer {
|
||||
id: Uuid::new_v4(),
|
||||
interface_id: Uuid::new_v4(),
|
||||
name: "Mobile".to_string(),
|
||||
peer_type: PeerType::RoadWarrior,
|
||||
state: PeerState::Active,
|
||||
public_key: WireGuardPublicKey::new("pubkey123".to_string()),
|
||||
private_key: None,
|
||||
preshared_key: None,
|
||||
endpoint: None,
|
||||
allowed_ips: "0.0.0.0/0, ::/0".to_string(),
|
||||
server_allowed_ips: Some("0.0.0.0/0".to_string()), // Attempt to set full tunnel as server allowed ips
|
||||
address_v4: Some("10.100.0.9/32".parse().unwrap()),
|
||||
address_v6: None,
|
||||
dns: None,
|
||||
mtu: None,
|
||||
persistent_keepalive: Some(25),
|
||||
profile: PeerProfile::FullTunnel,
|
||||
expires_at: None,
|
||||
last_handshake_at: None,
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
};
|
||||
|
||||
// Rejects 0.0.0.0/0 and falls back to assigned address 10.100.0.9/32
|
||||
assert_eq!(peer.server_wireguard_allowed_ips(), "10.100.0.9/32");
|
||||
}
|
||||
}
|
||||
@@ -146,6 +146,27 @@ pub fn validate_ip_in_network(ip: IpAddr, net: IpNet) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Validate a comma-separated list of CIDR subnets (e.g. "10.100.0.9/32, 192.168.1.0/24").
|
||||
pub fn validate_allowed_ips_cidr_list(list: &str) -> Result<Vec<IpNet>> {
|
||||
let mut nets = Vec::new();
|
||||
for item in list.split(',') {
|
||||
let trimmed = item.trim();
|
||||
if trimmed.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let net = validate_cidr(trimmed)?;
|
||||
if !nets.contains(&net) {
|
||||
nets.push(net);
|
||||
}
|
||||
}
|
||||
if nets.is_empty() {
|
||||
return Err(Nx9Error::Validation(
|
||||
"AllowedIPs list cannot be empty".into(),
|
||||
));
|
||||
}
|
||||
Ok(nets)
|
||||
}
|
||||
|
||||
/// Validate port.
|
||||
pub fn validate_port(port: u16) -> Result<u16> {
|
||||
if port == 0 {
|
||||
@@ -248,6 +269,120 @@ pub fn validate_client_mtu(mtu: u16) -> Result<u16> {
|
||||
Ok(mtu)
|
||||
}
|
||||
|
||||
/// Validate server host or IP for WireGuard server endpoint settings.
|
||||
///
|
||||
/// Rules:
|
||||
/// - Trim surrounding whitespace.
|
||||
/// - Reject empty host.
|
||||
/// - Accept valid DNS hostname.
|
||||
/// - Accept valid IPv4 address.
|
||||
/// - Accept valid IPv6 address (e.g. 2001:db8::10 or [2001:db8::10]).
|
||||
/// - Reject embedded port syntax (e.g. example.com:51820, 192.168.1.1:51820, [::1]:51820)
|
||||
/// with an explicit error indicating that port belongs in the separate port field.
|
||||
pub fn validate_server_host(host: &str) -> Result<String> {
|
||||
let trimmed = host.trim();
|
||||
if trimmed.is_empty() {
|
||||
return Err(Nx9Error::Validation(
|
||||
"server host / IP cannot be empty".into(),
|
||||
));
|
||||
}
|
||||
|
||||
// Check if bracketed IPv6 (e.g. [2001:db8::10] or [2001:db8::10]:51820)
|
||||
if trimmed.starts_with('[') {
|
||||
if let Some(closing) = trimmed.find(']') {
|
||||
let inside = &trimmed[1..closing];
|
||||
if closing + 1 < trimmed.len() {
|
||||
// Contains characters after bracket, likely a port
|
||||
return Err(Nx9Error::Validation(
|
||||
"server host must not include a port; specify the port in the Client Endpoint Port field".into(),
|
||||
));
|
||||
}
|
||||
if inside.parse::<std::net::Ipv6Addr>().is_ok() {
|
||||
return Ok(inside.to_string());
|
||||
}
|
||||
}
|
||||
return Err(Nx9Error::Validation(format!(
|
||||
"invalid IPv6 server host '{trimmed}'"
|
||||
)));
|
||||
}
|
||||
|
||||
// Check if direct unbracketed IPv6
|
||||
if let Ok(ipv6) = trimmed.parse::<std::net::Ipv6Addr>() {
|
||||
return Ok(ipv6.to_string());
|
||||
}
|
||||
|
||||
// If it contains a colon and was not parsed as IPv6 above, it has an embedded port or is invalid
|
||||
if trimmed.contains(':') {
|
||||
return Err(Nx9Error::Validation(
|
||||
"server host must not include a port; specify the port in the Client Endpoint Port field".into(),
|
||||
));
|
||||
}
|
||||
|
||||
// Check if IPv4
|
||||
if let Ok(ipv4) = trimmed.parse::<std::net::Ipv4Addr>() {
|
||||
return Ok(ipv4.to_string());
|
||||
}
|
||||
|
||||
// Validate DNS hostname (RFC 1123 / RFC 952)
|
||||
if trimmed.len() > 253 {
|
||||
return Err(Nx9Error::Validation(
|
||||
"server hostname exceeds maximum length of 253 characters".into(),
|
||||
));
|
||||
}
|
||||
|
||||
for label in trimmed.split('.') {
|
||||
if label.is_empty() {
|
||||
return Err(Nx9Error::Validation(format!(
|
||||
"invalid hostname '{trimmed}': empty label"
|
||||
)));
|
||||
}
|
||||
if label.len() > 63 {
|
||||
return Err(Nx9Error::Validation(format!(
|
||||
"invalid hostname '{trimmed}': label '{label}' exceeds 63 characters"
|
||||
)));
|
||||
}
|
||||
if !label.chars().all(|c| c.is_ascii_alphanumeric() || c == '-') {
|
||||
return Err(Nx9Error::Validation(format!(
|
||||
"invalid hostname '{trimmed}': contains invalid characters"
|
||||
)));
|
||||
}
|
||||
if label.starts_with('-') || label.ends_with('-') {
|
||||
return Err(Nx9Error::Validation(format!(
|
||||
"invalid hostname '{trimmed}': label '{label}' cannot start or end with hyphen"
|
||||
)));
|
||||
}
|
||||
}
|
||||
|
||||
Ok(trimmed.to_string())
|
||||
}
|
||||
|
||||
/// Validate WireGuard client endpoint port (range 1..=65535).
|
||||
pub fn validate_server_port(port: u16) -> Result<u16> {
|
||||
if port == 0 {
|
||||
return Err(Nx9Error::Validation(
|
||||
"server endpoint port must be between 1 and 65535".into(),
|
||||
));
|
||||
}
|
||||
Ok(port)
|
||||
}
|
||||
|
||||
/// Format host and port into a standard WireGuard Endpoint string.
|
||||
///
|
||||
/// Formats IPv6 as `[host]:port` and hostname/IPv4 as `host:port`.
|
||||
pub fn format_endpoint(host: &str, port: u16) -> String {
|
||||
let trimmed = host.trim();
|
||||
let unbracketed = trimmed
|
||||
.strip_prefix('[')
|
||||
.and_then(|s| s.strip_suffix(']'))
|
||||
.unwrap_or(trimmed);
|
||||
|
||||
if unbracketed.parse::<std::net::Ipv6Addr>().is_ok() || unbracketed.contains(':') {
|
||||
format!("[{}]:{}", unbracketed, port)
|
||||
} else {
|
||||
format!("{}:{}", unbracketed, port)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -334,4 +469,67 @@ mod tests {
|
||||
assert!(validate_client_mtu(9001).is_err());
|
||||
assert!(validate_client_mtu(65535).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_validate_server_host_valid() {
|
||||
assert_eq!(
|
||||
validate_server_host("vpn.thakares.com").unwrap(),
|
||||
"vpn.thakares.com"
|
||||
);
|
||||
assert_eq!(
|
||||
validate_server_host(" 203.0.113.10 ").unwrap(),
|
||||
"203.0.113.10"
|
||||
);
|
||||
assert_eq!(
|
||||
validate_server_host("2001:db8::10").unwrap(),
|
||||
"2001:db8::10"
|
||||
);
|
||||
assert_eq!(
|
||||
validate_server_host("[2001:db8::10]").unwrap(),
|
||||
"2001:db8::10"
|
||||
);
|
||||
assert_eq!(
|
||||
validate_server_host("vpn-node-01.internal").unwrap(),
|
||||
"vpn-node-01.internal"
|
||||
);
|
||||
assert_eq!(validate_server_host("localhost").unwrap(), "localhost");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_validate_server_host_invalid() {
|
||||
assert!(validate_server_host("").is_err());
|
||||
assert!(validate_server_host(" ").is_err());
|
||||
// Embedded ports rejected
|
||||
assert!(validate_server_host("vpn.thakares.com:51820").is_err());
|
||||
assert!(validate_server_host("203.0.113.10:51820").is_err());
|
||||
assert!(validate_server_host("[2001:db8::10]:51820").is_err());
|
||||
// Invalid hostname characters
|
||||
assert!(validate_server_host("vpn$host.com").is_err());
|
||||
assert!(validate_server_host("-invalid.com").is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_validate_server_port() {
|
||||
assert_eq!(validate_server_port(1).unwrap(), 1);
|
||||
assert_eq!(validate_server_port(51820).unwrap(), 51820);
|
||||
assert_eq!(validate_server_port(65535).unwrap(), 65535);
|
||||
assert!(validate_server_port(0).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_format_endpoint() {
|
||||
assert_eq!(
|
||||
format_endpoint("vpn.thakares.com", 51820),
|
||||
"vpn.thakares.com:51820"
|
||||
);
|
||||
assert_eq!(format_endpoint("203.0.113.10", 51820), "203.0.113.10:51820");
|
||||
assert_eq!(
|
||||
format_endpoint("2001:db8::10", 51820),
|
||||
"[2001:db8::10]:51820"
|
||||
);
|
||||
assert_eq!(
|
||||
format_endpoint("[2001:db8::10]", 51820),
|
||||
"[2001:db8::10]:51820"
|
||||
);
|
||||
}
|
||||
}
|
||||
+11
-10
@@ -1,12 +1,12 @@
|
||||
# nx9-db — SQLite Persistence Layer
|
||||
# nx9-wg-db — SQLite Persistence Layer
|
||||
|
||||
`nx9-db` provides the authoritative SQLite persistence layer for the `nx9-wg` native Rust WireGuard management system.
|
||||
`nx9-wg-db` provides the authoritative SQLite persistence layer for the `nx9-wg` native Rust WireGuard management system.
|
||||
|
||||
## Architectural Boundaries
|
||||
|
||||
- **Authoritative State**: SQLite is the authoritative persistent store for `nx9-wg` desired state. It stores what the system intends the network, interfaces, peers, routes, firewall rules, administrator credentials, sessions, tokens, and settings to be.
|
||||
- **Separation of Concerns**: SQLite records desired configuration only. Live kernel state (WireGuard interface status, handshake counters, packet counters, live nftables rules, live kernel routes) is queried directly from Linux kernel subsystems in later phases.
|
||||
- **SQL Encapsulation**: All SQL queries, SQLite connection lifecycle, migrations, and row conversions are strictly encapsulated inside `nx9-db`. Neither `nx9-core`, `nx9-api`, `nx9-ui`, `nx9-wireguard`, nor `nx9-network` issue SQL directly.
|
||||
- **Authoritative State**: SQLite is the authoritative persistent store for `nx9-wg` desired state. It stores what the system intends the network, interfaces, peers, routes, firewall rules, administrator credentials, sessions, tokens, client profiles, and settings to be.
|
||||
- **Separation of Concerns**: SQLite records desired configuration only. Live kernel state (WireGuard interface status, handshake counters, packet counters, live nftables rules, live kernel routes) is queried directly from Linux kernel subsystems.
|
||||
- **SQL Encapsulation**: All SQL queries, SQLite connection lifecycle, migrations, and row conversions are strictly encapsulated inside `nx9-wg-db`. Neither `nx9-wg-core`, `nx9-wg-api`, `nx9-wg-ui`, `nx9-wireguard`, nor `nx9-wg-network` issue SQL directly.
|
||||
|
||||
## SQLite Configuration
|
||||
|
||||
@@ -16,7 +16,7 @@ Every connection opened by `Store` enforces:
|
||||
- `PRAGMA busy_timeout = 5000` — 5-second busy timeout to avoid contention errors.
|
||||
- `PRAGMA synchronous = NORMAL` — Optimal reliability and performance in WAL mode.
|
||||
|
||||
## Database Schema (12 Tables)
|
||||
## Database Schema (13 Tables)
|
||||
|
||||
1. `admin` — Single administrator identity (`CHECK (id = 1)`), Argon2id password hash, TOTP secrets, and login timestamp.
|
||||
2. `sessions` — Admin web sessions (`ON DELETE CASCADE`).
|
||||
@@ -27,20 +27,21 @@ Every connection opened by `Store` enforces:
|
||||
7. `networks` — Named network CIDRs for routing and organization.
|
||||
8. `routes` — Desired kernel routing rules (`ON DELETE SET NULL`).
|
||||
9. `firewall_rules` — Desired firewall policy rules with priorities and directions (`in`, `out`, `forward`).
|
||||
10. `settings` — Key-value system settings with secret redaction support.
|
||||
10. `settings` — Key-value system settings with secret redaction support and structured WireGuard server endpoint keys.
|
||||
11. `audit_events` — Append-only operational audit log with event filtering and pagination.
|
||||
12. `backups` — Backup metadata and manifest checksum records.
|
||||
13. `client_profiles` — Device, connection, and MTU transport profile specifications with built-in protections.
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
- Migrations are defined in `crates/nx9-db/migrations/` and embedded at compile time via `sqlx::migrate!("./migrations")`.
|
||||
- Migrations are defined in `crates/nx9-wg-db/migrations/` and embedded at compile time via `sqlx::migrate!("./migrations")`.
|
||||
- Migrations are executed automatically via `store.migrate().await?`.
|
||||
- Migrations are tracked in the `_sqlx_migrations` table for idempotency.
|
||||
|
||||
## Usage in Code
|
||||
|
||||
```rust
|
||||
use nx9_db::Store;
|
||||
use nx9_wg_db::Store;
|
||||
use std::path::Path;
|
||||
|
||||
#[tokio::main]
|
||||
@@ -63,5 +64,5 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
Tests use isolated in-memory or temporary file SQLite instances:
|
||||
|
||||
```bash
|
||||
cargo test -p nx9-db
|
||||
cargo test -p nx9-wg-db
|
||||
```
|
||||
@@ -349,6 +349,49 @@ pub async fn update_peer_handshake(
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Update operational telemetry (learned remote endpoint and last handshake timestamp) from kernel.
|
||||
pub async fn update_peer_learned_telemetry(
|
||||
pool: &SqlitePool,
|
||||
id: Uuid,
|
||||
handshake_at: Option<NaiveDateTime>,
|
||||
endpoint: Option<&str>,
|
||||
) -> Result<()> {
|
||||
let id_str = id.to_string();
|
||||
let handshake_str = handshake_at.as_ref().map(format_datetime);
|
||||
|
||||
if handshake_str.is_none() && endpoint.is_none() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let mut query = String::from("UPDATE peers SET ");
|
||||
let mut set_clauses = Vec::new();
|
||||
|
||||
if handshake_str.is_some() {
|
||||
set_clauses.push("last_handshake_at = ?");
|
||||
}
|
||||
if endpoint.is_some() {
|
||||
set_clauses.push("endpoint = ?");
|
||||
}
|
||||
query.push_str(&set_clauses.join(", "));
|
||||
query.push_str(" WHERE id = ?");
|
||||
|
||||
let mut q = sqlx::query(&query);
|
||||
if let Some(ref hs) = handshake_str {
|
||||
q = q.bind(hs);
|
||||
}
|
||||
if let Some(ep) = endpoint {
|
||||
q = q.bind(ep);
|
||||
}
|
||||
q = q.bind(&id_str);
|
||||
|
||||
let result = q.execute(pool).await.map_err(DbError::Sqlx)?;
|
||||
if result.rows_affected() == 0 {
|
||||
return Err(DbError::NotFound(format!("Peer '{id_str}' not found")));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Delete a peer by UUID.
|
||||
pub async fn delete_peer(pool: &SqlitePool, id: Uuid) -> Result<()> {
|
||||
let id_str = id.to_string();
|
||||
|
||||
@@ -3,7 +3,11 @@
|
||||
use crate::error::{DbError, Result};
|
||||
use crate::models::{format_datetime, parse_datetime};
|
||||
use chrono::Utc;
|
||||
use nx9_wg_core::types::settings::Setting;
|
||||
use nx9_wg_core::types::settings::{
|
||||
LEGACY_SETTING_PUBLIC_ENDPOINT, LEGACY_SETTING_SERVER_ENDPOINT,
|
||||
SETTING_SERVER_ENDPOINT_ENABLED, SETTING_SERVER_HOST, SETTING_SERVER_PORT,
|
||||
ServerEndpointSettings, Setting,
|
||||
};
|
||||
use sqlx::{Row, SqlitePool};
|
||||
|
||||
/// Retrieve a setting by its key.
|
||||
@@ -99,3 +103,254 @@ pub async fn list_settings(pool: &SqlitePool) -> Result<Vec<Setting>> {
|
||||
|
||||
Ok(list)
|
||||
}
|
||||
|
||||
/// Retrieve structured server endpoint settings from the database with legacy fallback.
|
||||
pub async fn get_server_endpoint_settings(pool: &SqlitePool) -> Result<ServerEndpointSettings> {
|
||||
let host_opt = get_setting_value(pool, SETTING_SERVER_HOST).await?;
|
||||
let port_opt = get_setting_value(pool, SETTING_SERVER_PORT).await?;
|
||||
let enabled_opt = get_setting_value(pool, SETTING_SERVER_ENDPOINT_ENABLED).await?;
|
||||
|
||||
let enabled = enabled_opt
|
||||
.as_deref()
|
||||
.map(|v| {
|
||||
let t = v.trim();
|
||||
t.parse::<bool>().unwrap_or_else(|_| t == "1")
|
||||
})
|
||||
.unwrap_or(true);
|
||||
|
||||
let port = port_opt
|
||||
.as_deref()
|
||||
.and_then(|v| v.trim().parse::<u16>().ok())
|
||||
.filter(|&p| p > 0)
|
||||
.unwrap_or(51820);
|
||||
|
||||
if let Some(host) = host_opt.filter(|h| !h.trim().is_empty()) {
|
||||
return Ok(ServerEndpointSettings {
|
||||
host: host.trim().to_string(),
|
||||
port,
|
||||
enabled,
|
||||
});
|
||||
}
|
||||
|
||||
// Legacy fallback: inspect server_endpoint
|
||||
if let Some(legacy) = get_setting_value(pool, LEGACY_SETTING_SERVER_ENDPOINT).await? {
|
||||
let trimmed = legacy.trim();
|
||||
if !trimmed.is_empty() {
|
||||
let (legacy_host, legacy_port) = split_host_port(trimmed, port);
|
||||
return Ok(ServerEndpointSettings {
|
||||
host: legacy_host,
|
||||
port: legacy_port,
|
||||
enabled,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Legacy fallback: inspect public_endpoint
|
||||
if let Some(legacy) = get_setting_value(pool, LEGACY_SETTING_PUBLIC_ENDPOINT).await? {
|
||||
let trimmed = legacy.trim();
|
||||
if !trimmed.is_empty() {
|
||||
let (legacy_host, legacy_port) = split_host_port(trimmed, port);
|
||||
return Ok(ServerEndpointSettings {
|
||||
host: legacy_host,
|
||||
port: legacy_port,
|
||||
enabled,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Ok(ServerEndpointSettings {
|
||||
host: String::new(),
|
||||
port,
|
||||
enabled,
|
||||
})
|
||||
}
|
||||
|
||||
/// Persist structured server endpoint settings.
|
||||
pub async fn set_server_endpoint_settings(
|
||||
pool: &SqlitePool,
|
||||
settings: &ServerEndpointSettings,
|
||||
) -> Result<()> {
|
||||
let host_trimmed = settings.host.trim();
|
||||
if settings.enabled && !host_trimmed.is_empty() {
|
||||
nx9_wg_core::validation::validate_server_host(host_trimmed)?;
|
||||
nx9_wg_core::validation::validate_server_port(settings.port)?;
|
||||
}
|
||||
|
||||
set_setting(pool, SETTING_SERVER_HOST, host_trimmed, false).await?;
|
||||
set_setting(pool, SETTING_SERVER_PORT, &settings.port.to_string(), false).await?;
|
||||
set_setting(
|
||||
pool,
|
||||
SETTING_SERVER_ENDPOINT_ENABLED,
|
||||
&settings.enabled.to_string(),
|
||||
false,
|
||||
)
|
||||
.await?;
|
||||
|
||||
// Synchronize legacy server_endpoint setting for backwards compatibility
|
||||
if settings.enabled && !host_trimmed.is_empty() {
|
||||
let formatted = nx9_wg_core::validation::format_endpoint(host_trimmed, settings.port);
|
||||
set_setting(pool, LEGACY_SETTING_SERVER_ENDPOINT, &formatted, false).await?;
|
||||
} else {
|
||||
delete_setting(pool, LEGACY_SETTING_SERVER_ENDPOINT).await?;
|
||||
delete_setting(pool, LEGACY_SETTING_PUBLIC_ENDPOINT).await?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Authoritative server endpoint resolver.
|
||||
///
|
||||
/// Precedence:
|
||||
/// 1. Explicit endpoint override (if non-empty)
|
||||
/// 2. Persistent `wireguard.server_*` settings (when enabled and host non-empty)
|
||||
/// 3. Legacy `server_endpoint` setting (if non-empty)
|
||||
/// 4. Legacy `public_endpoint` setting (if non-empty)
|
||||
/// 5. Actionable error explaining how to configure server endpoint or provide `--endpoint`.
|
||||
pub async fn resolve_server_endpoint(
|
||||
pool: &SqlitePool,
|
||||
explicit_override: Option<&str>,
|
||||
) -> Result<String> {
|
||||
// 1. Explicit endpoint override
|
||||
if let Some(ep) = explicit_override {
|
||||
let trimmed = ep.trim();
|
||||
if !trimmed.is_empty() {
|
||||
return parse_and_normalize_endpoint(trimmed);
|
||||
}
|
||||
}
|
||||
|
||||
// Check enabled toggle
|
||||
let enabled_opt = get_setting_value(pool, SETTING_SERVER_ENDPOINT_ENABLED).await?;
|
||||
let enabled = enabled_opt
|
||||
.as_deref()
|
||||
.map(|v| {
|
||||
let t = v.trim();
|
||||
t.parse::<bool>().unwrap_or_else(|_| t == "1")
|
||||
})
|
||||
.unwrap_or(true);
|
||||
|
||||
if !enabled {
|
||||
return Err(DbError::Validation(
|
||||
"No reachable WireGuard server endpoint is configured. Configure WireGuard Server Endpoint in Settings or provide --endpoint.".to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
// 2. Persistent wireguard.server_* settings
|
||||
let host_opt = get_setting_value(pool, SETTING_SERVER_HOST).await?;
|
||||
let port_opt = get_setting_value(pool, SETTING_SERVER_PORT).await?;
|
||||
let port = port_opt
|
||||
.as_deref()
|
||||
.and_then(|v| v.trim().parse::<u16>().ok())
|
||||
.filter(|&p| p > 0)
|
||||
.unwrap_or(51820);
|
||||
|
||||
if let Some(host) = host_opt.filter(|h| !h.trim().is_empty()) {
|
||||
let validated_host = nx9_wg_core::validation::validate_server_host(&host)?;
|
||||
let validated_port = nx9_wg_core::validation::validate_server_port(port)?;
|
||||
return Ok(nx9_wg_core::validation::format_endpoint(
|
||||
&validated_host,
|
||||
validated_port,
|
||||
));
|
||||
}
|
||||
|
||||
// 3. Legacy server_endpoint fallback
|
||||
if let Some(legacy) = get_setting_value(pool, LEGACY_SETTING_SERVER_ENDPOINT).await? {
|
||||
let trimmed = legacy.trim();
|
||||
if !trimmed.is_empty() {
|
||||
return parse_and_normalize_endpoint(trimmed);
|
||||
}
|
||||
}
|
||||
|
||||
// 4. Legacy public_endpoint fallback
|
||||
if let Some(legacy) = get_setting_value(pool, LEGACY_SETTING_PUBLIC_ENDPOINT).await? {
|
||||
let trimmed = legacy.trim();
|
||||
if !trimmed.is_empty() {
|
||||
return parse_and_normalize_endpoint(trimmed);
|
||||
}
|
||||
}
|
||||
|
||||
// 5. Actionable error
|
||||
Err(DbError::Validation(
|
||||
"No reachable WireGuard server endpoint is configured. Configure WireGuard Server Endpoint in Settings or provide --endpoint.".to_string(),
|
||||
))
|
||||
}
|
||||
|
||||
fn split_host_port(s: &str, default_port: u16) -> (String, u16) {
|
||||
let trimmed = s.trim();
|
||||
if trimmed.starts_with('[')
|
||||
&& let Some(closing) = trimmed.find(']')
|
||||
{
|
||||
let host_part = &trimmed[1..closing];
|
||||
let rest = &trimmed[closing + 1..];
|
||||
if let Some(port_str) = rest.strip_prefix(':')
|
||||
&& let Ok(port) = port_str.parse::<u16>()
|
||||
&& port > 0
|
||||
{
|
||||
return (host_part.to_string(), port);
|
||||
}
|
||||
return (host_part.to_string(), default_port);
|
||||
}
|
||||
if let Ok(ipv6) = trimmed.parse::<std::net::Ipv6Addr>() {
|
||||
return (ipv6.to_string(), default_port);
|
||||
}
|
||||
if let Some(last_colon) = trimmed.rfind(':') {
|
||||
let host_part = &trimmed[..last_colon];
|
||||
let port_part = &trimmed[last_colon + 1..];
|
||||
if let Ok(port) = port_part.parse::<u16>()
|
||||
&& port > 0
|
||||
{
|
||||
return (host_part.to_string(), port);
|
||||
}
|
||||
}
|
||||
(trimmed.to_string(), default_port)
|
||||
}
|
||||
|
||||
fn parse_and_normalize_endpoint(ep: &str) -> Result<String> {
|
||||
let trimmed = ep.trim();
|
||||
if trimmed.is_empty() {
|
||||
return Err(DbError::Validation("endpoint cannot be empty".into()));
|
||||
}
|
||||
|
||||
if trimmed.starts_with('[')
|
||||
&& let Some(closing) = trimmed.find(']')
|
||||
{
|
||||
let host_part = &trimmed[1..closing];
|
||||
let ipv6 = host_part.parse::<std::net::Ipv6Addr>().map_err(|e| {
|
||||
DbError::Validation(format!("invalid IPv6 in endpoint '{trimmed}': {e}"))
|
||||
})?;
|
||||
let rest = &trimmed[closing + 1..];
|
||||
let port = if let Some(port_str) = rest.strip_prefix(':') {
|
||||
port_str
|
||||
.parse::<u16>()
|
||||
.map_err(|_| DbError::Validation(format!("invalid port in endpoint '{trimmed}'")))?
|
||||
} else if rest.is_empty() {
|
||||
51820
|
||||
} else {
|
||||
return Err(DbError::Validation(format!(
|
||||
"invalid endpoint format '{trimmed}'"
|
||||
)));
|
||||
};
|
||||
if port == 0 {
|
||||
return Err(DbError::Validation("port must be non-zero".into()));
|
||||
}
|
||||
return Ok(format!("[{}]:{}", ipv6, port));
|
||||
}
|
||||
|
||||
if let Ok(ipv6) = trimmed.parse::<std::net::Ipv6Addr>() {
|
||||
return Ok(format!("[{}]:51820", ipv6));
|
||||
}
|
||||
|
||||
if let Some(last_colon) = trimmed.rfind(':') {
|
||||
let host_part = &trimmed[..last_colon];
|
||||
let port_part = &trimmed[last_colon + 1..];
|
||||
if let Ok(port) = port_part.parse::<u16>() {
|
||||
if port == 0 {
|
||||
return Err(DbError::Validation("port must be non-zero".into()));
|
||||
}
|
||||
let host = nx9_wg_core::validation::validate_server_host(host_part)?;
|
||||
return Ok(nx9_wg_core::validation::format_endpoint(&host, port));
|
||||
}
|
||||
}
|
||||
|
||||
let host = nx9_wg_core::validation::validate_server_host(trimmed)?;
|
||||
Ok(nx9_wg_core::validation::format_endpoint(&host, 51820))
|
||||
}
|
||||
@@ -349,6 +349,15 @@ impl Store {
|
||||
crate::peers::update_peer_handshake(&self.pool, id, handshake_at).await
|
||||
}
|
||||
|
||||
pub async fn update_peer_learned_telemetry(
|
||||
&self,
|
||||
id: uuid::Uuid,
|
||||
handshake_at: Option<chrono::NaiveDateTime>,
|
||||
endpoint: Option<&str>,
|
||||
) -> Result<()> {
|
||||
crate::peers::update_peer_learned_telemetry(&self.pool, id, handshake_at, endpoint).await
|
||||
}
|
||||
|
||||
pub async fn delete_peer(&self, id: uuid::Uuid) -> Result<()> {
|
||||
crate::peers::delete_peer(&self.pool, id).await
|
||||
}
|
||||
@@ -515,6 +524,23 @@ impl Store {
|
||||
crate::settings::list_settings(&self.pool).await
|
||||
}
|
||||
|
||||
pub async fn get_server_endpoint_settings(
|
||||
&self,
|
||||
) -> Result<nx9_wg_core::types::settings::ServerEndpointSettings> {
|
||||
crate::settings::get_server_endpoint_settings(&self.pool).await
|
||||
}
|
||||
|
||||
pub async fn set_server_endpoint_settings(
|
||||
&self,
|
||||
settings: &nx9_wg_core::types::settings::ServerEndpointSettings,
|
||||
) -> Result<()> {
|
||||
crate::settings::set_server_endpoint_settings(&self.pool, settings).await
|
||||
}
|
||||
|
||||
pub async fn resolve_server_endpoint(&self, explicit_override: Option<&str>) -> Result<String> {
|
||||
crate::settings::resolve_server_endpoint(&self.pool, explicit_override).await
|
||||
}
|
||||
|
||||
// Audit
|
||||
pub async fn create_audit_event(
|
||||
&self,
|
||||
|
||||
@@ -225,3 +225,171 @@ async fn test_backup_metadata_crud() {
|
||||
.is_none()
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_server_endpoint_settings_crud_and_persistence() {
|
||||
let store = Store::connect_in_memory().await.expect("connect");
|
||||
store.migrate().await.expect("migrate");
|
||||
|
||||
// 1. Initial state defaults
|
||||
let initial = store
|
||||
.get_server_endpoint_settings()
|
||||
.await
|
||||
.expect("get initial");
|
||||
assert_eq!(initial.host, "");
|
||||
assert_eq!(initial.port, 51820);
|
||||
assert!(initial.enabled);
|
||||
|
||||
// Initial resolution with no settings returns actionable error
|
||||
let err = store.resolve_server_endpoint(None).await.unwrap_err();
|
||||
assert!(
|
||||
err.to_string()
|
||||
.contains("No reachable WireGuard server endpoint is configured")
|
||||
);
|
||||
|
||||
// 2. Set structured server endpoint settings
|
||||
let new_settings = nx9_wg_core::types::settings::ServerEndpointSettings {
|
||||
host: "vpn.thakares.com".to_string(),
|
||||
port: 51820,
|
||||
enabled: true,
|
||||
};
|
||||
store
|
||||
.set_server_endpoint_settings(&new_settings)
|
||||
.await
|
||||
.expect("set server endpoint settings");
|
||||
|
||||
let loaded = store
|
||||
.get_server_endpoint_settings()
|
||||
.await
|
||||
.expect("get loaded settings");
|
||||
assert_eq!(loaded.host, "vpn.thakares.com");
|
||||
assert_eq!(loaded.port, 51820);
|
||||
assert!(loaded.enabled);
|
||||
|
||||
// 3. Resolve persistent setting
|
||||
let resolved = store.resolve_server_endpoint(None).await.expect("resolve");
|
||||
assert_eq!(resolved, "vpn.thakares.com:51820");
|
||||
|
||||
// 4. IPv6 persistence and formatting
|
||||
let ipv6_settings = nx9_wg_core::types::settings::ServerEndpointSettings {
|
||||
host: "2001:db8::10".to_string(),
|
||||
port: 51821,
|
||||
enabled: true,
|
||||
};
|
||||
store
|
||||
.set_server_endpoint_settings(&ipv6_settings)
|
||||
.await
|
||||
.expect("set ipv6");
|
||||
let resolved_v6 = store
|
||||
.resolve_server_endpoint(None)
|
||||
.await
|
||||
.expect("resolve v6");
|
||||
assert_eq!(resolved_v6, "[2001:db8::10]:51821");
|
||||
|
||||
// 5. Disable setting
|
||||
let disabled = nx9_wg_core::types::settings::ServerEndpointSettings {
|
||||
host: "vpn.thakares.com".to_string(),
|
||||
port: 51820,
|
||||
enabled: false,
|
||||
};
|
||||
store
|
||||
.set_server_endpoint_settings(&disabled)
|
||||
.await
|
||||
.expect("set disabled");
|
||||
let err = store.resolve_server_endpoint(None).await.unwrap_err();
|
||||
assert!(
|
||||
err.to_string()
|
||||
.contains("No reachable WireGuard server endpoint is configured")
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_server_endpoint_resolution_precedence() {
|
||||
let store = Store::connect_in_memory().await.expect("connect");
|
||||
store.migrate().await.expect("migrate");
|
||||
|
||||
// 1. Explicit override with no settings configured
|
||||
let ep = store
|
||||
.resolve_server_endpoint(Some("custom.vpn.net:51820"))
|
||||
.await
|
||||
.expect("override");
|
||||
assert_eq!(ep, "custom.vpn.net:51820");
|
||||
|
||||
// 2. Configure persistent settings
|
||||
let settings = nx9_wg_core::types::settings::ServerEndpointSettings {
|
||||
host: "persistent.vpn.io".to_string(),
|
||||
port: 51820,
|
||||
enabled: true,
|
||||
};
|
||||
store
|
||||
.set_server_endpoint_settings(&settings)
|
||||
.await
|
||||
.expect("set");
|
||||
|
||||
// Precedence test: explicit override beats persistent setting
|
||||
let overridden = store
|
||||
.resolve_server_endpoint(Some("override.vpn.io:5555"))
|
||||
.await
|
||||
.expect("override beats persistent");
|
||||
assert_eq!(overridden, "override.vpn.io:5555");
|
||||
|
||||
// Precedence test: None uses persistent setting
|
||||
let default_resolved = store.resolve_server_endpoint(None).await.expect("default");
|
||||
assert_eq!(default_resolved, "persistent.vpn.io:51820");
|
||||
|
||||
// 3. Legacy fallback test when wireguard.server_host is missing
|
||||
store
|
||||
.delete_setting(nx9_wg_core::types::settings::SETTING_SERVER_HOST)
|
||||
.await
|
||||
.expect("delete new host");
|
||||
store
|
||||
.set_setting("server_endpoint", "legacy.vpn.org:51820", false)
|
||||
.await
|
||||
.expect("set legacy");
|
||||
|
||||
let legacy_resolved = store
|
||||
.resolve_server_endpoint(None)
|
||||
.await
|
||||
.expect("legacy resolved");
|
||||
assert_eq!(legacy_resolved, "legacy.vpn.org:51820");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_server_endpoint_survives_reopen() {
|
||||
let temp_dir = tempfile::tempdir().expect("temp dir");
|
||||
let db_path = temp_dir.path().join("persist_endpoint.db");
|
||||
let db_url = format!("sqlite://{}?mode=rwc", db_path.display());
|
||||
|
||||
{
|
||||
let store = Store::connect(&db_url).await.expect("connect 1");
|
||||
store.migrate().await.expect("migrate 1");
|
||||
|
||||
let settings = nx9_wg_core::types::settings::ServerEndpointSettings {
|
||||
host: "vpn.thakares.com".to_string(),
|
||||
port: 51820,
|
||||
enabled: true,
|
||||
};
|
||||
store
|
||||
.set_server_endpoint_settings(&settings)
|
||||
.await
|
||||
.expect("set");
|
||||
}
|
||||
|
||||
// Reconnect to existing store on disk
|
||||
{
|
||||
let store = Store::connect(&db_url).await.expect("connect 2");
|
||||
let loaded = store
|
||||
.get_server_endpoint_settings()
|
||||
.await
|
||||
.expect("get after reopen");
|
||||
assert_eq!(loaded.host, "vpn.thakares.com");
|
||||
assert_eq!(loaded.port, 51820);
|
||||
assert!(loaded.enabled);
|
||||
|
||||
let resolved = store
|
||||
.resolve_server_endpoint(None)
|
||||
.await
|
||||
.expect("resolve after reopen");
|
||||
assert_eq!(resolved, "vpn.thakares.com:51820");
|
||||
}
|
||||
}
|
||||
@@ -10,4 +10,6 @@ pub mod nftables;
|
||||
pub use engine::{NativeLinuxNetworkEngine, NetworkEngine, SimulatedNetworkEngine};
|
||||
pub use error::{NetworkError, Result};
|
||||
pub use forwarding::IpForwardingStatus;
|
||||
pub use nftables::NftablesRulesetBuilder;
|
||||
pub use nftables::{
|
||||
CanonicalNftablesRuleset, NftablesRulesetBuilder, has_nftables_drift, normalize_rule_statement,
|
||||
};
|
||||
@@ -138,7 +138,7 @@ impl NftablesRulesetBuilder {
|
||||
// Build Postrouting / NAT Masquerade rules
|
||||
let mut nat_rules = Vec::new();
|
||||
if enable_nat {
|
||||
let mut unique_subnets = wg_subnets.to_vec();
|
||||
let mut unique_subnets: Vec<IpNet> = wg_subnets.iter().map(|s| s.trunc()).collect();
|
||||
unique_subnets.sort();
|
||||
unique_subnets.dedup();
|
||||
|
||||
@@ -200,6 +200,224 @@ impl NftablesRulesetBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
/// Structured semantic representation of the managed `table inet nx9_wg` ruleset.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Default)]
|
||||
pub struct CanonicalNftablesRuleset {
|
||||
pub table_exists: bool,
|
||||
pub input_rules: Vec<String>,
|
||||
pub forward_rules: Vec<String>,
|
||||
pub postrouting_rules: Vec<String>,
|
||||
pub other_rules: Vec<String>,
|
||||
}
|
||||
|
||||
impl CanonicalNftablesRuleset {
|
||||
/// Parse an nftables ruleset string (from builder or kernel `list table`) into canonical semantic state.
|
||||
pub fn parse(ruleset: &str) -> Option<Self> {
|
||||
let trimmed_ruleset = ruleset.trim();
|
||||
if trimmed_ruleset.is_empty() {
|
||||
return None;
|
||||
}
|
||||
|
||||
let mut in_table = false;
|
||||
let mut current_chain: Option<&str> = None;
|
||||
let mut input_rules = Vec::new();
|
||||
let mut forward_rules = Vec::new();
|
||||
let mut postrouting_rules = Vec::new();
|
||||
let mut other_rules = Vec::new();
|
||||
|
||||
for raw_line in trimmed_ruleset.lines() {
|
||||
// Strip comments (e.g. "# handle 46", "# NX9 WireGuard...")
|
||||
let line_no_comment = if let Some(idx) = raw_line.find('#') {
|
||||
&raw_line[..idx]
|
||||
} else {
|
||||
raw_line
|
||||
};
|
||||
let trimmed = line_no_comment.trim();
|
||||
if trimmed.is_empty() {
|
||||
continue;
|
||||
}
|
||||
|
||||
if trimmed.starts_with("table inet nx9_wg") {
|
||||
in_table = true;
|
||||
continue;
|
||||
}
|
||||
|
||||
if !in_table {
|
||||
continue;
|
||||
}
|
||||
|
||||
if trimmed == "}" {
|
||||
if current_chain.is_some() {
|
||||
current_chain = None;
|
||||
} else {
|
||||
in_table = false;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
if trimmed.starts_with("chain input") {
|
||||
current_chain = Some("input");
|
||||
continue;
|
||||
} else if trimmed.starts_with("chain forward") {
|
||||
current_chain = Some("forward");
|
||||
continue;
|
||||
} else if trimmed.starts_with("chain postrouting") {
|
||||
current_chain = Some("postrouting");
|
||||
continue;
|
||||
} else if trimmed.starts_with("chain ") {
|
||||
current_chain = Some("other");
|
||||
continue;
|
||||
}
|
||||
|
||||
// Skip chain type/hook declarations (e.g. "type filter hook input priority ...; policy accept;")
|
||||
if trimmed.starts_with("type filter")
|
||||
|| trimmed.starts_with("type nat")
|
||||
|| trimmed.starts_with("type route")
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
let normalized = normalize_rule_statement(trimmed);
|
||||
if normalized.is_empty() {
|
||||
continue;
|
||||
}
|
||||
|
||||
match current_chain {
|
||||
Some("input") => input_rules.push(normalized),
|
||||
Some("forward") => forward_rules.push(normalized),
|
||||
Some("postrouting") => postrouting_rules.push(normalized),
|
||||
Some(_) => other_rules.push(normalized),
|
||||
None => {}
|
||||
}
|
||||
}
|
||||
|
||||
if in_table
|
||||
|| !input_rules.is_empty()
|
||||
|| !forward_rules.is_empty()
|
||||
|| !postrouting_rules.is_empty()
|
||||
|| trimmed_ruleset.contains("table inet nx9_wg")
|
||||
{
|
||||
Some(Self {
|
||||
table_exists: true,
|
||||
input_rules,
|
||||
forward_rules,
|
||||
postrouting_rules,
|
||||
other_rules,
|
||||
})
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Normalize an individual nftables rule statement for canonical comparison.
|
||||
pub fn normalize_rule_statement(rule: &str) -> String {
|
||||
// 1. Strip double quotes (e.g. `"lo"` -> `lo`, `"wg*"` -> `wg*`)
|
||||
let no_quotes = rule.replace('"', "");
|
||||
|
||||
// 2. Normalize whitespace around braces and commas: "{ a, b }" -> "{a,b}"
|
||||
let mut normalized = String::with_capacity(no_quotes.len());
|
||||
let mut chars = no_quotes.chars().peekable();
|
||||
|
||||
while let Some(c) = chars.next() {
|
||||
if c == ',' {
|
||||
normalized.push(',');
|
||||
while let Some(&next) = chars.peek() {
|
||||
if next == ' ' || next == '\t' {
|
||||
chars.next();
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
} else if c == '{' {
|
||||
normalized.push('{');
|
||||
while let Some(&next) = chars.peek() {
|
||||
if next == ' ' || next == '\t' {
|
||||
chars.next();
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
} else if c == ' ' || c == '\t' {
|
||||
let mut is_before_close_brace = false;
|
||||
let temp_peek = chars.clone();
|
||||
for peek_char in temp_peek {
|
||||
if peek_char == '}' {
|
||||
is_before_close_brace = true;
|
||||
break;
|
||||
} else if peek_char != ' ' && peek_char != '\t' {
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if is_before_close_brace {
|
||||
continue;
|
||||
}
|
||||
|
||||
if !normalized.ends_with(' ') && !normalized.is_empty() {
|
||||
normalized.push(' ');
|
||||
}
|
||||
} else {
|
||||
normalized.push(c);
|
||||
}
|
||||
}
|
||||
|
||||
let mut result = normalized.trim().to_string();
|
||||
|
||||
// Standardize "ct state {established,related}" to "ct state established,related"
|
||||
if result.contains("ct state {established,related}") {
|
||||
result = result.replace(
|
||||
"ct state {established,related}",
|
||||
"ct state established,related",
|
||||
);
|
||||
}
|
||||
|
||||
// Standardize redundant leading protocol prefixes before IP selectors
|
||||
if (result.starts_with("tcp ip ") || result.starts_with("tcp ip6 "))
|
||||
&& (result.contains("tcp dport")
|
||||
|| result.contains("tcp sport")
|
||||
|| result.contains("th dport"))
|
||||
{
|
||||
result = result[4..].trim().to_string();
|
||||
}
|
||||
if (result.starts_with("udp ip ") || result.starts_with("udp ip6 "))
|
||||
&& (result.contains("udp dport")
|
||||
|| result.contains("udp sport")
|
||||
|| result.contains("th dport"))
|
||||
{
|
||||
result = result[4..].trim().to_string();
|
||||
}
|
||||
result = result.replace("tcp tcp dport", "tcp dport");
|
||||
result = result.replace("udp udp dport", "udp dport");
|
||||
result = result.replace("tcp tcp sport", "tcp sport");
|
||||
result = result.replace("udp udp sport", "udp sport");
|
||||
|
||||
let mut words: Vec<String> = result.split_whitespace().map(|s| s.to_string()).collect();
|
||||
for word in &mut words {
|
||||
if word.contains('/')
|
||||
&& let Ok(net) = word.parse::<IpNet>()
|
||||
{
|
||||
*word = net.trunc().to_string();
|
||||
}
|
||||
}
|
||||
result = words.join(" ");
|
||||
|
||||
result
|
||||
}
|
||||
|
||||
/// Detect semantic drift between desired and live nftables rulesets.
|
||||
/// Ignores non-semantic variations such as rule handles (`# handle 46`), formatting, tabs, comments, and hook priority keywords.
|
||||
pub fn has_nftables_drift(expected_ruleset: &str, active_ruleset: &str) -> bool {
|
||||
let expected = CanonicalNftablesRuleset::parse(expected_ruleset);
|
||||
let active = CanonicalNftablesRuleset::parse(active_ruleset);
|
||||
|
||||
match (expected, active) {
|
||||
(Some(exp), Some(act)) => exp != act,
|
||||
(None, None) => false,
|
||||
_ => true,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -322,7 +540,6 @@ mod tests {
|
||||
assert!(ruleset.contains("ip6 saddr fd00:1::/64 oifname != \"wg*\" masquerade"));
|
||||
assert!(ruleset.contains("ip6 saddr fd00:2::/64 oifname != \"wg*\" masquerade"));
|
||||
|
||||
// Verify deduplication: 10.100.0.0/24 appears exactly once in masquerade statements
|
||||
let count = ruleset
|
||||
.matches("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade")
|
||||
.count();
|
||||
@@ -331,4 +548,189 @@ mod tests {
|
||||
"Duplicate subnet must be deduplicated to exactly one masquerade rule"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_nftables_drift_ignores_handles_and_formatting() {
|
||||
let desired = r#"#!/usr/sbin/nft -f
|
||||
|
||||
# NX9 WireGuard Dedicated Firewall Ruleset
|
||||
table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
ip saddr 10.100.0.0/24 oifname != "wg*" masquerade
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
let live_with_kernel_handles = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority filter; policy accept;
|
||||
ct state established,related accept # handle 46
|
||||
iifname "lo" accept # handle 1
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority filter; policy accept;
|
||||
ct state established,related accept # handle 4
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
ip saddr 10.100.0.0/24 oifname != "wg*" masquerade # handle 3
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
assert!(
|
||||
!has_nftables_drift(desired, live_with_kernel_handles),
|
||||
"Desired ruleset and live kernel output with handles and tabs must converge with zero drift"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_nftables_drift_detects_real_rule_changes() {
|
||||
let desired = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
tcp dport 80 accept
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
ip saddr 10.100.0.0/24 oifname != "wg*" masquerade
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
let live_missing_port_80 = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority filter; policy accept;
|
||||
ct state established,related accept # handle 2
|
||||
iifname "lo" accept # handle 3
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority filter; policy accept;
|
||||
ct state established,related accept # handle 4
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
ip saddr 10.100.0.0/24 oifname != "wg*" masquerade # handle 5
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
assert!(
|
||||
has_nftables_drift(desired, live_missing_port_80),
|
||||
"Missing port 80 rule must detect drift"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_nftables_drift_nat_toggle() {
|
||||
let desired_nat_disabled = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
let live_with_nat = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
}
|
||||
|
||||
chain forward {
|
||||
type filter hook forward priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
}
|
||||
|
||||
chain postrouting {
|
||||
type nat hook postrouting priority srcnat; policy accept;
|
||||
ip saddr 10.100.0.0/24 oifname != "wg*" masquerade # handle 5
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
assert!(
|
||||
has_nftables_drift(desired_nat_disabled, live_with_nat),
|
||||
"Disabling NAT in desired state while active in kernel must detect drift"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_nftables_drift_missing_table() {
|
||||
let desired = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
assert!(
|
||||
has_nftables_drift(desired, ""),
|
||||
"Empty active ruleset (missing table) must detect drift"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_nftables_drift_unexpected_rules() {
|
||||
let desired = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
let live_with_rogue_rule = r#"table inet nx9_wg {
|
||||
chain input {
|
||||
type filter hook input priority 0; policy accept;
|
||||
ct state established,related accept
|
||||
iifname "lo" accept
|
||||
tcp dport 22 drop # handle 99
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
assert!(
|
||||
has_nftables_drift(desired, live_with_rogue_rule),
|
||||
"Unexpected kernel rules must detect drift"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -13,6 +13,8 @@ pub struct ClientExportState {
|
||||
pub selected_connection: ConnectionType,
|
||||
pub selected_nat: NatType,
|
||||
pub manual_mtu_override: Option<u16>,
|
||||
pub server_endpoint: Option<String>,
|
||||
pub is_default_from_settings: bool,
|
||||
pub resolved_profile: Option<ResolvedClientProfile>,
|
||||
pub is_override_enabled: bool,
|
||||
pub qr_view_active: bool,
|
||||
@@ -26,6 +28,8 @@ impl Default for ClientExportState {
|
||||
selected_connection: ConnectionType::Web,
|
||||
selected_nat: NatType::Unknown,
|
||||
manual_mtu_override: None,
|
||||
server_endpoint: None,
|
||||
is_default_from_settings: false,
|
||||
resolved_profile: None,
|
||||
is_override_enabled: false,
|
||||
qr_view_active: false,
|
||||
@@ -59,6 +63,12 @@ impl ClientExportState {
|
||||
self.selected_provider = provider;
|
||||
}
|
||||
|
||||
/// Set server endpoint override and whether it was populated from default settings.
|
||||
pub fn set_server_endpoint(&mut self, endpoint: Option<String>, is_default: bool) {
|
||||
self.server_endpoint = endpoint;
|
||||
self.is_default_from_settings = is_default;
|
||||
}
|
||||
|
||||
/// Toggle or set manual MTU override.
|
||||
pub fn set_manual_mtu(&mut self, mtu: Option<u16>) {
|
||||
self.manual_mtu_override = mtu;
|
||||
@@ -95,6 +105,14 @@ impl ClientExportState {
|
||||
if let Some(m) = self.manual_mtu_override {
|
||||
params.push(format!("mtu={m}"));
|
||||
}
|
||||
if let Some(ep) = self
|
||||
.server_endpoint
|
||||
.as_deref()
|
||||
.filter(|s| !s.trim().is_empty())
|
||||
{
|
||||
params.push(format!("endpoint={}", urlencoding(ep.trim())));
|
||||
}
|
||||
|
||||
if let Some(id) = profile_id {
|
||||
params.push(format!("profile={}", urlencoding(id)));
|
||||
}
|
||||
|
||||
@@ -38,9 +38,10 @@ impl PeerRowView {
|
||||
let is_expired =
|
||||
peer.state == PeerState::Expired || peer.expires_at.is_some_and(|exp| exp <= now);
|
||||
|
||||
let maybe_hs = last_handshake.or(peer.last_handshake_at);
|
||||
let is_online = if is_expired || peer.state != PeerState::Active {
|
||||
false
|
||||
} else if let Some(hs) = last_handshake.or(peer.last_handshake_at) {
|
||||
} else if let Some(hs) = maybe_hs {
|
||||
let diff = now.signed_duration_since(hs);
|
||||
diff.num_seconds() >= 0 && diff.num_seconds() < 180
|
||||
} else {
|
||||
@@ -53,9 +54,14 @@ impl PeerRowView {
|
||||
match peer.state {
|
||||
PeerState::Active => {
|
||||
if is_online {
|
||||
("Online".to_string(), "status-pass".to_string())
|
||||
("Connected".to_string(), "status-pass".to_string())
|
||||
} else if maybe_hs.is_some() {
|
||||
("Disconnected".to_string(), "status-fail".to_string())
|
||||
} else {
|
||||
("Offline".to_string(), "status-neutral".to_string())
|
||||
(
|
||||
"Awaiting Handshake".to_string(),
|
||||
"status-warning".to_string(),
|
||||
)
|
||||
}
|
||||
}
|
||||
PeerState::Disabled => ("Disabled".to_string(), "status-warning".to_string()),
|
||||
@@ -216,10 +222,18 @@ mod tests {
|
||||
|
||||
let row = PeerRowView::from_peer_and_telemetry(&peer, 1024, 2048, None);
|
||||
assert_eq!(row.name, "alice-laptop");
|
||||
assert_eq!(row.status_label, "Offline");
|
||||
assert_eq!(row.status_label, "Awaiting Handshake");
|
||||
assert_eq!(row.rx_bytes_formatted, "1.0 KB");
|
||||
assert_eq!(row.tx_bytes_formatted, "2.0 KB");
|
||||
|
||||
let recent_hs = Utc::now().naive_utc() - chrono::Duration::seconds(30);
|
||||
let row_online = PeerRowView::from_peer_and_telemetry(&peer, 1024, 2048, Some(recent_hs));
|
||||
assert_eq!(row_online.status_label, "Connected");
|
||||
|
||||
let stale_hs = Utc::now().naive_utc() - chrono::Duration::seconds(300);
|
||||
let row_stale = PeerRowView::from_peer_and_telemetry(&peer, 1024, 2048, Some(stale_hs));
|
||||
assert_eq!(row_stale.status_label, "Disconnected");
|
||||
|
||||
let filter = PeerTableFilter {
|
||||
search_query: "alice".to_string(),
|
||||
status_filter: None,
|
||||
|
||||
@@ -15,6 +15,9 @@ pub struct SettingsState {
|
||||
pub default_interface: String,
|
||||
pub default_mtu: u16,
|
||||
pub default_listen_port: u16,
|
||||
pub wireguard_server_host: String,
|
||||
pub wireguard_server_port: u16,
|
||||
pub wireguard_server_endpoint_enabled: bool,
|
||||
|
||||
// Card 3: Networking
|
||||
pub nat_enabled: bool,
|
||||
@@ -46,6 +49,9 @@ impl Default for SettingsState {
|
||||
default_interface: "wg0".to_string(),
|
||||
default_mtu: 1420,
|
||||
default_listen_port: 51820,
|
||||
wireguard_server_host: String::new(),
|
||||
wireguard_server_port: 51820,
|
||||
wireguard_server_endpoint_enabled: true,
|
||||
nat_enabled: true,
|
||||
ipv4_forwarding: true,
|
||||
ipv6_forwarding: false,
|
||||
|
||||
@@ -33,6 +33,64 @@ a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/* ── Authentication & Login View ─────────────────────────────────────────────── */
|
||||
#login-view {
|
||||
min-height: 100vh;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
background-color: var(--bg-base);
|
||||
padding: 24px;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.login-card {
|
||||
width: 100%;
|
||||
max-width: 400px;
|
||||
background-color: var(--bg-surface);
|
||||
border: 1px solid var(--border-subtle);
|
||||
border-radius: var(--radius-lg);
|
||||
padding: 32px;
|
||||
box-shadow: var(--shadow-lg);
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.login-header {
|
||||
text-align: center;
|
||||
margin-bottom: 24px;
|
||||
}
|
||||
|
||||
.login-header .brand-mark {
|
||||
font-size: 14px;
|
||||
padding: 4px 10px;
|
||||
display: inline-block;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.login-header h2 {
|
||||
font-size: 20px;
|
||||
font-weight: 700;
|
||||
color: var(--text-primary);
|
||||
}
|
||||
|
||||
.login-header p {
|
||||
font-size: 13px;
|
||||
color: var(--text-secondary);
|
||||
margin-top: 4px;
|
||||
}
|
||||
|
||||
.login-error {
|
||||
background-color: var(--status-fail-bg);
|
||||
color: var(--status-fail-text);
|
||||
border: 1px solid var(--status-fail-border);
|
||||
padding: 10px 14px;
|
||||
border-radius: var(--radius-md);
|
||||
font-size: 13px;
|
||||
margin-bottom: 16px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
/* ── App Shell Layout ────────────────────────────────────────────────────────── */
|
||||
#app-layout {
|
||||
display: flex;
|
||||
@@ -634,10 +692,30 @@ table.data-table tr:hover td {
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 20px;
|
||||
padding: 24px;
|
||||
background-color: #ffffff;
|
||||
border-radius: var(--radius-lg);
|
||||
margin: 16px 0;
|
||||
border: 1px solid var(--border-subtle);
|
||||
box-sizing: border-box;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.qr-target-box {
|
||||
width: 240px;
|
||||
height: 240px;
|
||||
max-width: 100%;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.qr-target-box svg {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
max-width: 240px;
|
||||
max-height: 240px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.qr-image {
|
||||
|
||||
@@ -79,18 +79,31 @@ impl ClientConfigBuilder {
|
||||
lines.push(format!("PresharedKey = {}", psk.as_str()));
|
||||
}
|
||||
|
||||
let host_trimmed = server_host_or_ip.trim();
|
||||
if host_trimmed.is_empty() {
|
||||
return Err(WireGuardError::Config(
|
||||
"No reachable WireGuard server endpoint is configured. Configure 'server_endpoint' in settings or provide --endpoint.".to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
// Endpoint
|
||||
let endpoint = if server_host_or_ip.contains(':') && !server_host_or_ip.starts_with('[') {
|
||||
let endpoint = if host_trimmed.contains(':') && !host_trimmed.starts_with('[') {
|
||||
// Check if already contains port
|
||||
server_host_or_ip.to_string()
|
||||
host_trimmed.to_string()
|
||||
} else {
|
||||
format!("{}:{}", server_host_or_ip, interface.listen_port)
|
||||
format!("{}:{}", host_trimmed, interface.listen_port)
|
||||
};
|
||||
lines.push(format!("Endpoint = {endpoint}"));
|
||||
|
||||
// AllowedIPs based on Peer Profile
|
||||
let allowed_ips = match peer.profile {
|
||||
PeerProfile::FullTunnel => "0.0.0.0/0, ::/0".to_string(),
|
||||
PeerProfile::FullTunnel => {
|
||||
if interface.address_v6.is_some() || peer.address_v6.is_some() {
|
||||
"0.0.0.0/0, ::/0".to_string()
|
||||
} else {
|
||||
"0.0.0.0/0".to_string()
|
||||
}
|
||||
}
|
||||
PeerProfile::SplitTunnel => {
|
||||
let mut subnets = Vec::new();
|
||||
subnets.push(interface.address_v4.to_string());
|
||||
@@ -101,7 +114,11 @@ impl ClientConfigBuilder {
|
||||
}
|
||||
PeerProfile::Custom => {
|
||||
if peer.allowed_ips.trim().is_empty() {
|
||||
"0.0.0.0/0, ::/0".to_string()
|
||||
if interface.address_v6.is_some() || peer.address_v6.is_some() {
|
||||
"0.0.0.0/0, ::/0".to_string()
|
||||
} else {
|
||||
"0.0.0.0/0".to_string()
|
||||
}
|
||||
} else {
|
||||
peer.allowed_ips.clone()
|
||||
}
|
||||
@@ -181,7 +198,7 @@ mod tests {
|
||||
updated_at: now,
|
||||
};
|
||||
|
||||
// Full Tunnel
|
||||
// Full Tunnel (IPv4-only interface -> 0.0.0.0/0 to prevent silent IPv6 blackhole)
|
||||
let full_conf = ClientConfigBuilder::build(&peer, &iface, "vpn.example.com").unwrap();
|
||||
assert!(full_conf.contains(&format!("PrivateKey = {}", peer_priv.as_str())));
|
||||
assert!(full_conf.contains("Address = 10.0.0.2/32"));
|
||||
@@ -190,9 +207,15 @@ mod tests {
|
||||
assert!(full_conf.contains(&format!("PublicKey = {}", srv_pub.as_str())));
|
||||
assert!(full_conf.contains(&format!("PresharedKey = {}", psk.as_str())));
|
||||
assert!(full_conf.contains("Endpoint = vpn.example.com:51820"));
|
||||
assert!(full_conf.contains("AllowedIPs = 0.0.0.0/0, ::/0"));
|
||||
assert!(full_conf.contains("AllowedIPs = 0.0.0.0/0"));
|
||||
assert!(full_conf.contains("PersistentKeepalive = 25"));
|
||||
|
||||
// Full Tunnel (Dual-stack interface -> 0.0.0.0/0, ::/0)
|
||||
let mut dual_iface = iface.clone();
|
||||
dual_iface.address_v6 = Some(IpNet::from_str("fd00::1/64").unwrap());
|
||||
let dual_conf = ClientConfigBuilder::build(&peer, &dual_iface, "vpn.example.com").unwrap();
|
||||
assert!(dual_conf.contains("AllowedIPs = 0.0.0.0/0, ::/0"));
|
||||
|
||||
// Split Tunnel
|
||||
peer.profile = PeerProfile::SplitTunnel;
|
||||
let split_conf = ClientConfigBuilder::build(&peer, &iface, "vpn.example.com").unwrap();
|
||||
@@ -274,6 +297,6 @@ mod tests {
|
||||
assert!(conf.contains("PersistentKeepalive = 20"));
|
||||
assert!(conf.contains("DNS = 9.9.9.9"));
|
||||
assert!(conf.contains("Address = 10.0.0.5/32"));
|
||||
assert!(conf.contains("AllowedIPs = 0.0.0.0/0, ::/0"));
|
||||
assert!(conf.contains("AllowedIPs = 0.0.0.0/0"));
|
||||
}
|
||||
}
|
||||
@@ -2,9 +2,10 @@
|
||||
|
||||
use crate::error::{Result, WireGuardError};
|
||||
use chrono::{NaiveDateTime, Utc};
|
||||
use ipnet::IpNet;
|
||||
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerState};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::collections::HashMap;
|
||||
use std::collections::{BTreeSet, HashMap};
|
||||
use std::sync::Arc;
|
||||
use tokio::sync::RwLock;
|
||||
|
||||
@@ -28,6 +29,42 @@ pub struct LiveInterfaceStats {
|
||||
pub listen_port: u16,
|
||||
pub fwmark: u32,
|
||||
pub peers: Vec<LivePeerStats>,
|
||||
#[serde(default)]
|
||||
pub addresses: Vec<String>,
|
||||
#[serde(default)]
|
||||
pub mtu: Option<u32>,
|
||||
#[serde(default)]
|
||||
pub is_up: bool,
|
||||
}
|
||||
|
||||
/// Peer tunnel addresses that are not on the Interface connected prefix.
|
||||
///
|
||||
/// Interface-CIDR peers (e.g. 10.100.0.x with wg0 10.100.0.1/24) are already
|
||||
/// reachable via the kernel connected route created by the interface address.
|
||||
/// Selected-Network peers (e.g. 10.100.2.1/32) are not. Those prefixes must be
|
||||
/// installed as on-link device routes on the WireGuard interface so the FIB
|
||||
/// delivers packets into wg0, where cryptokey routing (AllowedIPs) applies.
|
||||
///
|
||||
/// This is not a Routes-table LAN-behind-peer destination and has no gateway.
|
||||
pub fn onlink_peer_address_prefixes(interface: &Interface, peers: &[Peer]) -> Vec<IpNet> {
|
||||
let mut prefixes = BTreeSet::new();
|
||||
for peer in peers.iter().filter(|p| p.state == PeerState::Active) {
|
||||
if let Some(v4) = peer.address_v4
|
||||
&& v4.prefix_len() > 0
|
||||
&& !interface.address_v4.contains(&v4.addr())
|
||||
{
|
||||
prefixes.insert(v4);
|
||||
}
|
||||
if let Some(v6) = peer.address_v6
|
||||
&& v6.prefix_len() > 0
|
||||
&& !interface
|
||||
.address_v6
|
||||
.is_some_and(|iface_v6| iface_v6.contains(&v6.addr()))
|
||||
{
|
||||
prefixes.insert(v6);
|
||||
}
|
||||
}
|
||||
prefixes.into_iter().collect()
|
||||
}
|
||||
|
||||
/// Abstract WireGuard Engine interface for kernel netlink and simulated environments.
|
||||
@@ -82,6 +119,12 @@ impl SimulatedWireGuardEngine {
|
||||
"Peer '{peer_public_key}' on interface '{interface_name}' not found"
|
||||
)))
|
||||
}
|
||||
|
||||
/// Directly inject live interface stats (for testing drift and telemetry scenarios).
|
||||
pub async fn inject_interface_stats(&self, stats: LiveInterfaceStats) {
|
||||
let mut map = self.state.write().await;
|
||||
map.insert(stats.name.clone(), stats);
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait::async_trait]
|
||||
@@ -94,7 +137,7 @@ impl WireGuardEngine for SimulatedWireGuardEngine {
|
||||
.filter(|p| p.state == PeerState::Active)
|
||||
.map(|p| {
|
||||
let allowed_ips: Vec<String> = p
|
||||
.allowed_ips
|
||||
.server_wireguard_allowed_ips()
|
||||
.split(',')
|
||||
.map(|s| s.trim().to_string())
|
||||
.filter(|s| !s.is_empty())
|
||||
@@ -112,12 +155,20 @@ impl WireGuardEngine for SimulatedWireGuardEngine {
|
||||
})
|
||||
.collect();
|
||||
|
||||
let mut addresses = vec![interface.address_v4.to_string()];
|
||||
if let Some(ref v6) = interface.address_v6 {
|
||||
addresses.push(v6.to_string());
|
||||
}
|
||||
|
||||
let stats = LiveInterfaceStats {
|
||||
name: interface.name.clone(),
|
||||
public_key: interface.public_key.as_str().to_string(),
|
||||
listen_port: interface.listen_port,
|
||||
fwmark: 0,
|
||||
peers: live_peers,
|
||||
addresses,
|
||||
mtu: interface.mtu.map(|m| m as u32),
|
||||
is_up: true,
|
||||
};
|
||||
|
||||
map.insert(interface.name.clone(), stats);
|
||||
|
||||
@@ -10,7 +10,7 @@ pub mod qr;
|
||||
pub use config_builder::ClientConfigBuilder;
|
||||
pub use engine::{
|
||||
LiveInterfaceStats, LivePeerStats, NativeLinuxWireGuardEngine, SimulatedWireGuardEngine,
|
||||
WireGuardEngine,
|
||||
WireGuardEngine, onlink_peer_address_prefixes,
|
||||
};
|
||||
pub use error::{Result, WireGuardError};
|
||||
pub use qr::{
|
||||
|
||||
@@ -8,7 +8,9 @@
|
||||
//!
|
||||
//! No external commands (wg, ip, wg-quick, nft, sysctl) are ever executed.
|
||||
|
||||
use crate::engine::{LiveInterfaceStats, LivePeerStats, WireGuardEngine};
|
||||
use crate::engine::{
|
||||
LiveInterfaceStats, LivePeerStats, WireGuardEngine, onlink_peer_address_prefixes,
|
||||
};
|
||||
use crate::error::{Result, WireGuardError};
|
||||
use base64::Engine as _;
|
||||
use chrono::NaiveDateTime;
|
||||
@@ -24,8 +26,13 @@ use netlink_packet_wireguard::{
|
||||
};
|
||||
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerState};
|
||||
use rtnetlink::LinkWireguard;
|
||||
use rtnetlink::packet_route::link::{InfoKind, LinkAttribute, LinkInfo};
|
||||
use std::net::{IpAddr, SocketAddr};
|
||||
use rtnetlink::RouteMessageBuilder;
|
||||
use rtnetlink::packet_route::AddressFamily;
|
||||
use rtnetlink::packet_route::address::{AddressAttribute, AddressMessage};
|
||||
use rtnetlink::packet_route::link::{InfoKind, LinkAttribute, LinkFlags, LinkInfo};
|
||||
use rtnetlink::packet_route::route::{RouteAddress, RouteAttribute, RouteMessage};
|
||||
use std::collections::HashSet;
|
||||
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
|
||||
|
||||
/// Linux Native WireGuard Engine using kernel RTNETLINK and Generic Netlink.
|
||||
#[derive(Debug, Clone, Default)]
|
||||
@@ -55,42 +62,53 @@ async fn rtnetlink_handle() -> Result<(rtnetlink::Handle, tokio::task::JoinHandl
|
||||
Ok((handle, join))
|
||||
}
|
||||
|
||||
/// Ensure a WireGuard interface exists with the given name.
|
||||
/// Ensure a WireGuard interface exists with the given name and addresses.
|
||||
///
|
||||
/// - If the interface already exists and is a WireGuard link, this is a no-op.
|
||||
/// - If the interface already exists but is NOT a WireGuard link, returns an error.
|
||||
/// - If the interface does not exist, it is created as a WireGuard link and brought up.
|
||||
async fn ensure_link(name: &str) -> Result<()> {
|
||||
/// - Sets MTU if configured.
|
||||
/// - Assigns IPv4 and IPv6 addresses via RTNETLINK if not already assigned.
|
||||
/// - Removes stale IP addresses on the managed interface that do not match desired state.
|
||||
async fn ensure_link_and_addresses(interface: &Interface) -> Result<()> {
|
||||
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||
|
||||
// Try to find existing interface by name
|
||||
let mut links = handle.link().get().match_name(name.to_string()).execute();
|
||||
let mut links = handle
|
||||
.link()
|
||||
.get()
|
||||
.match_name(interface.name.to_string())
|
||||
.execute();
|
||||
|
||||
match links.try_next().await {
|
||||
let link_index = match links.try_next().await {
|
||||
Ok(Some(link)) => {
|
||||
let mut is_wireguard = false;
|
||||
let mut is_other_type = false;
|
||||
for nla in &link.attributes {
|
||||
if let LinkAttribute::LinkInfo(infos) = nla {
|
||||
for info in infos {
|
||||
if let LinkInfo::Kind(InfoKind::Wireguard) = info {
|
||||
is_wireguard = true;
|
||||
match info {
|
||||
LinkInfo::Kind(InfoKind::Wireguard) => {}
|
||||
LinkInfo::Kind(InfoKind::Other(k))
|
||||
if k.eq_ignore_ascii_case("wireguard") => {}
|
||||
LinkInfo::Kind(_) => {
|
||||
is_other_type = true;
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if is_wireguard {
|
||||
tracing::debug!(interface = %name, "WireGuard interface already exists");
|
||||
Ok(())
|
||||
} else {
|
||||
Err(WireGuardError::WrongInterfaceType(format!(
|
||||
"interface '{name}' exists but is not a WireGuard interface"
|
||||
)))
|
||||
if is_other_type {
|
||||
return Err(WireGuardError::WrongInterfaceType(format!(
|
||||
"interface '{}' exists but is not a WireGuard interface",
|
||||
interface.name
|
||||
)));
|
||||
}
|
||||
tracing::debug!(interface = %interface.name, index = link.header.index, "WireGuard interface found");
|
||||
link.header.index
|
||||
}
|
||||
Ok(None) | Err(_) => {
|
||||
// Interface does not exist — create it and bring it up
|
||||
tracing::info!(interface = %name, "Creating WireGuard interface via RTNETLINK");
|
||||
let add_msg = LinkWireguard::new(name).up().build();
|
||||
tracing::info!(interface = %interface.name, "Creating WireGuard interface via RTNETLINK");
|
||||
let add_msg = LinkWireguard::new(&interface.name).up().build();
|
||||
|
||||
handle.link().add(add_msg).execute().await.map_err(|e| {
|
||||
let msg = format!("{e}");
|
||||
@@ -99,19 +117,208 @@ async fn ensure_link(name: &str) -> Result<()> {
|
||||
|| msg.contains("Operation not permitted")
|
||||
{
|
||||
WireGuardError::PermissionDenied(format!(
|
||||
"insufficient privileges to create WireGuard interface '{name}': {e}"
|
||||
"insufficient privileges to create WireGuard interface '{}': {e}",
|
||||
interface.name
|
||||
))
|
||||
} else {
|
||||
WireGuardError::Netlink(format!(
|
||||
"failed to create WireGuard interface '{name}': {e}"
|
||||
"failed to create WireGuard interface '{}': {e}",
|
||||
interface.name
|
||||
))
|
||||
}
|
||||
})?;
|
||||
|
||||
tracing::info!(interface = %name, "WireGuard interface created and brought up");
|
||||
Ok(())
|
||||
// Retrieve newly created link to get its index
|
||||
let mut new_links = handle
|
||||
.link()
|
||||
.get()
|
||||
.match_name(interface.name.to_string())
|
||||
.execute();
|
||||
match new_links.try_next().await {
|
||||
Ok(Some(nl)) => {
|
||||
tracing::info!(interface = %interface.name, "WireGuard interface created and brought up");
|
||||
nl.header.index
|
||||
}
|
||||
_ => {
|
||||
return Err(WireGuardError::Netlink(format!(
|
||||
"failed to retrieve newly created interface '{}'",
|
||||
interface.name
|
||||
)));
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Set MTU and ensure UP
|
||||
let mut link_builder = rtnetlink::LinkUnspec::new_with_index(link_index).up();
|
||||
if let Some(mtu) = interface.mtu {
|
||||
link_builder = link_builder.mtu(mtu as u32);
|
||||
}
|
||||
let msg = link_builder.build();
|
||||
if let Err(e) = handle.link().change(msg).execute().await {
|
||||
let msg_str = format!("{e}");
|
||||
if msg_str.contains("permission")
|
||||
|| msg_str.contains("EPERM")
|
||||
|| msg_str.contains("Operation not permitted")
|
||||
{
|
||||
return Err(WireGuardError::PermissionDenied(format!(
|
||||
"insufficient privileges to set link UP/MTU for '{}': {e}",
|
||||
interface.name
|
||||
)));
|
||||
}
|
||||
tracing::warn!(interface = %interface.name, "Failed to set link UP/MTU: {e}");
|
||||
}
|
||||
|
||||
// Read existing addresses on link
|
||||
let mut existing_addrs: Vec<(IpAddr, u8)> = Vec::new();
|
||||
let mut stale_addr_msgs: Vec<AddressMessage> = Vec::new();
|
||||
|
||||
let mut addr_stream = handle
|
||||
.address()
|
||||
.get()
|
||||
.set_link_index_filter(link_index)
|
||||
.execute();
|
||||
|
||||
let desired_v4_ip = interface.address_v4.addr();
|
||||
let desired_v4_prefix = interface.address_v4.prefix_len();
|
||||
let desired_v6 = interface.address_v6.as_ref();
|
||||
|
||||
while let Ok(Some(addr_msg)) = addr_stream.try_next().await {
|
||||
let prefix = addr_msg.header.prefix_len;
|
||||
let mut msg_ip: Option<IpAddr> = None;
|
||||
|
||||
for attr in &addr_msg.attributes {
|
||||
match attr {
|
||||
AddressAttribute::Address(ip) | AddressAttribute::Local(ip) => {
|
||||
if !existing_addrs.contains(&(*ip, prefix)) {
|
||||
existing_addrs.push((*ip, prefix));
|
||||
}
|
||||
msg_ip = Some(*ip);
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(ip) = msg_ip {
|
||||
let is_desired = match ip {
|
||||
IpAddr::V4(v4) => v4 == desired_v4_ip && prefix == desired_v4_prefix,
|
||||
IpAddr::V6(v6) => {
|
||||
if v6.is_unicast_link_local() {
|
||||
true // preserve IPv6 link-local fe80::/10
|
||||
} else if let Some(v6_desired) = desired_v6 {
|
||||
v6 == v6_desired.addr() && prefix == v6_desired.prefix_len()
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
if !is_desired {
|
||||
stale_addr_msgs.push(addr_msg);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Remove any stale addresses
|
||||
for stale_msg in stale_addr_msgs {
|
||||
if let Err(e) = handle.address().del(stale_msg).execute().await {
|
||||
tracing::warn!(interface = %interface.name, "Failed to delete stale address: {e}");
|
||||
}
|
||||
}
|
||||
|
||||
// Add desired IPv4 address if not already present
|
||||
if !existing_addrs
|
||||
.iter()
|
||||
.any(|(ip, p)| *ip == desired_v4_ip && *p == desired_v4_prefix)
|
||||
{
|
||||
handle
|
||||
.address()
|
||||
.add(link_index, desired_v4_ip, desired_v4_prefix)
|
||||
.execute()
|
||||
.await
|
||||
.map_err(|e| {
|
||||
let msg = format!("{e}");
|
||||
if msg.contains("permission")
|
||||
|| msg.contains("EPERM")
|
||||
|| msg.contains("Operation not permitted")
|
||||
{
|
||||
WireGuardError::PermissionDenied(format!(
|
||||
"insufficient privileges to assign IPv4 address '{}/{}' to interface '{}': {e}",
|
||||
desired_v4_ip, desired_v4_prefix, interface.name
|
||||
))
|
||||
} else if msg.contains("File exists") || msg.contains("EEXIST") {
|
||||
WireGuardError::Netlink(e.to_string())
|
||||
} else {
|
||||
WireGuardError::Netlink(format!(
|
||||
"failed to assign IPv4 address '{}/{}' to interface '{}': {e}",
|
||||
desired_v4_ip, desired_v4_prefix, interface.name
|
||||
))
|
||||
}
|
||||
})
|
||||
.or_else(|e| {
|
||||
if e.to_string().contains("File exists") || e.to_string().contains("EEXIST") {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(e)
|
||||
}
|
||||
})?;
|
||||
tracing::info!(
|
||||
interface = %interface.name,
|
||||
ip = %desired_v4_ip,
|
||||
prefix = desired_v4_prefix,
|
||||
"Assigned IPv4 address to WireGuard interface via RTNETLINK"
|
||||
);
|
||||
}
|
||||
|
||||
// Add desired IPv6 address if present and not already configured
|
||||
if let Some(v6) = desired_v6 {
|
||||
let v6_ip = v6.addr();
|
||||
let v6_prefix = v6.prefix_len();
|
||||
if !existing_addrs
|
||||
.iter()
|
||||
.any(|(ip, p)| *ip == v6_ip && *p == v6_prefix)
|
||||
{
|
||||
handle
|
||||
.address()
|
||||
.add(link_index, v6_ip, v6_prefix)
|
||||
.execute()
|
||||
.await
|
||||
.map_err(|e| {
|
||||
let msg = format!("{e}");
|
||||
if msg.contains("permission")
|
||||
|| msg.contains("EPERM")
|
||||
|| msg.contains("Operation not permitted")
|
||||
{
|
||||
WireGuardError::PermissionDenied(format!(
|
||||
"insufficient privileges to assign IPv6 address '{}/{}' to interface '{}': {e}",
|
||||
v6_ip, v6_prefix, interface.name
|
||||
))
|
||||
} else if msg.contains("File exists") || msg.contains("EEXIST") {
|
||||
WireGuardError::Netlink(e.to_string())
|
||||
} else {
|
||||
WireGuardError::Netlink(format!(
|
||||
"failed to assign IPv6 address '{}/{}' to interface '{}': {e}",
|
||||
v6_ip, v6_prefix, interface.name
|
||||
))
|
||||
}
|
||||
})
|
||||
.or_else(|e| {
|
||||
if e.to_string().contains("File exists") || e.to_string().contains("EEXIST") {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(e)
|
||||
}
|
||||
})?;
|
||||
tracing::info!(
|
||||
interface = %interface.name,
|
||||
ip = %v6_ip,
|
||||
prefix = v6_prefix,
|
||||
"Assigned IPv6 address to WireGuard interface via RTNETLINK"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Delete a WireGuard interface by name.
|
||||
@@ -140,17 +347,18 @@ async fn delete_link(name: &str) -> Result<()> {
|
||||
}
|
||||
}
|
||||
|
||||
/// List all WireGuard interface names using RTNETLINK link dump.
|
||||
/// List all WireGuard interface names using RTNETLINK link dump and Generic Netlink enumeration.
|
||||
async fn list_wireguard_links() -> Result<Vec<String>> {
|
||||
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||
|
||||
let mut links = handle.link().get().execute();
|
||||
let mut wg_names = Vec::new();
|
||||
|
||||
// 1. Primary discovery: RTNETLINK link dump
|
||||
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||
let mut links = handle.link().get().execute();
|
||||
|
||||
while let Some(link) = links
|
||||
.try_next()
|
||||
.await
|
||||
.map_err(|e| WireGuardError::Netlink(format!("failed to dump links: {e}")))?
|
||||
.map_err(|e| WireGuardError::Netlink(format!("failed to dump links via rtnetlink: {e}")))?
|
||||
{
|
||||
let mut name = None;
|
||||
let mut is_wireguard = false;
|
||||
@@ -160,8 +368,14 @@ async fn list_wireguard_links() -> Result<Vec<String>> {
|
||||
LinkAttribute::IfName(n) => name = Some(n.clone()),
|
||||
LinkAttribute::LinkInfo(infos) => {
|
||||
for info in infos {
|
||||
if let LinkInfo::Kind(InfoKind::Wireguard) = info {
|
||||
is_wireguard = true;
|
||||
match info {
|
||||
LinkInfo::Kind(InfoKind::Wireguard) => is_wireguard = true,
|
||||
LinkInfo::Kind(InfoKind::Other(k))
|
||||
if k.eq_ignore_ascii_case("wireguard") =>
|
||||
{
|
||||
is_wireguard = true;
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -169,11 +383,44 @@ async fn list_wireguard_links() -> Result<Vec<String>> {
|
||||
}
|
||||
}
|
||||
|
||||
if let (true, Some(n)) = (is_wireguard, name) {
|
||||
if let (true, Some(n)) = (is_wireguard, name)
|
||||
&& !wg_names.contains(&n)
|
||||
{
|
||||
wg_names.push(n);
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Secondary discovery: WireGuard Generic Netlink dump
|
||||
if let Ok((mut genl_handle, _)) = wireguard_genl_handle().await {
|
||||
let genlmsg = GenlMessage::from_payload(WireguardMessage {
|
||||
cmd: WireguardCmd::GetDevice,
|
||||
attributes: Vec::new(),
|
||||
});
|
||||
let mut nlmsg = NetlinkMessage::from(genlmsg);
|
||||
nlmsg.header.flags = NLM_F_REQUEST | NLM_F_DUMP;
|
||||
nlmsg.finalize();
|
||||
|
||||
if let Ok(mut response) = genl_handle.request(nlmsg).await {
|
||||
while let Some(Ok(msg)) = response.next().await {
|
||||
if let NetlinkPayload::InnerMessage(genl) = msg.payload {
|
||||
for attr in genl.payload.attributes {
|
||||
if let WireguardAttribute::IfName(ifname) = attr
|
||||
&& !wg_names.contains(&ifname)
|
||||
{
|
||||
wg_names.push(ifname);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
tracing::debug!(
|
||||
discovered_count = wg_names.len(),
|
||||
interfaces = ?wg_names,
|
||||
"Discovered WireGuard interfaces in kernel"
|
||||
);
|
||||
|
||||
Ok(wg_names)
|
||||
}
|
||||
|
||||
@@ -236,8 +483,9 @@ async fn configure_device(interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||
peer_attrs.push(WireguardPeerAttribute::PersistentKeepalive(keepalive));
|
||||
}
|
||||
|
||||
// Allowed IPs
|
||||
let allowed_ips = parse_allowed_ips(&peer.allowed_ips)?;
|
||||
// Server-side Allowed IPs (cryptokey routing in Linux kernel)
|
||||
let server_allowed_str = peer.server_wireguard_allowed_ips();
|
||||
let allowed_ips = parse_allowed_ips(&server_allowed_str)?;
|
||||
if !allowed_ips.is_empty() {
|
||||
peer_attrs.push(WireguardPeerAttribute::Flags(
|
||||
WireguardPeerFlags::ReplaceAllowedIps,
|
||||
@@ -299,6 +547,51 @@ async fn configure_device(interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||
|
||||
/// Query a WireGuard device via Generic Netlink GET_DEVICE and return live stats.
|
||||
async fn query_device(name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||
// 1. Query RTNETLINK for link existence, MTU, is_up, and assigned addresses
|
||||
let mut link_exists = false;
|
||||
let mut addresses = Vec::new();
|
||||
let mut mtu = None;
|
||||
let mut is_up = false;
|
||||
|
||||
if let Ok((rt_handle, _)) = rtnetlink_handle().await {
|
||||
let mut links = rt_handle
|
||||
.link()
|
||||
.get()
|
||||
.match_name(name.to_string())
|
||||
.execute();
|
||||
if let Ok(Some(link)) = links.try_next().await {
|
||||
link_exists = true;
|
||||
let index = link.header.index;
|
||||
is_up = link.header.flags.contains(LinkFlags::Up);
|
||||
for attr in link.attributes {
|
||||
if let LinkAttribute::Mtu(m) = attr {
|
||||
mtu = Some(m);
|
||||
}
|
||||
}
|
||||
|
||||
let mut addr_stream = rt_handle
|
||||
.address()
|
||||
.get()
|
||||
.set_link_index_filter(index)
|
||||
.execute();
|
||||
while let Ok(Some(addr_msg)) = addr_stream.try_next().await {
|
||||
let prefix = addr_msg.header.prefix_len;
|
||||
for attr in addr_msg.attributes {
|
||||
match attr {
|
||||
AddressAttribute::Address(ip) | AddressAttribute::Local(ip) => {
|
||||
let cidr = format!("{}/{}", ip, prefix);
|
||||
if !addresses.contains(&cidr) {
|
||||
addresses.push(cidr);
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Query Generic Netlink for WireGuard keys, port, fwmark, and peers
|
||||
let (mut handle, _conn_task) = wireguard_genl_handle().await?;
|
||||
|
||||
let genlmsg = GenlMessage::from_payload(WireguardMessage {
|
||||
@@ -310,18 +603,35 @@ async fn query_device(name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||
nlmsg.header.flags = NLM_F_REQUEST | NLM_F_DUMP;
|
||||
nlmsg.finalize();
|
||||
|
||||
let mut response = handle.request(nlmsg).await.map_err(|e| {
|
||||
let msg = format!("{e}");
|
||||
if msg.contains("No such device") || msg.contains("ENODEV") {
|
||||
WireGuardError::InterfaceNotFound(format!("interface '{name}' not found"))
|
||||
} else if msg.contains("not found") || msg.contains("No such") {
|
||||
WireGuardError::Unsupported(
|
||||
"WireGuard Generic Netlink family not available — is the wireguard kernel module loaded?".to_string(),
|
||||
)
|
||||
} else {
|
||||
WireGuardError::Netlink(format!("failed to query WireGuard device '{name}': {e}"))
|
||||
let mut response = match handle.request(nlmsg).await {
|
||||
Ok(resp) => resp,
|
||||
Err(e) => {
|
||||
let msg = format!("{e}");
|
||||
if msg.contains("No such device") || msg.contains("ENODEV") {
|
||||
if link_exists {
|
||||
return Ok(Some(LiveInterfaceStats {
|
||||
name: name.to_string(),
|
||||
public_key: String::new(),
|
||||
listen_port: 0,
|
||||
fwmark: 0,
|
||||
peers: Vec::new(),
|
||||
addresses,
|
||||
mtu,
|
||||
is_up,
|
||||
}));
|
||||
}
|
||||
return Ok(None);
|
||||
} else if msg.contains("not found") || msg.contains("No such") {
|
||||
return Err(WireGuardError::Unsupported(
|
||||
"WireGuard Generic Netlink family not available — is the wireguard kernel module loaded?".to_string(),
|
||||
));
|
||||
} else {
|
||||
return Err(WireGuardError::Netlink(format!(
|
||||
"failed to query WireGuard device '{name}': {e}"
|
||||
)));
|
||||
}
|
||||
}
|
||||
})?;
|
||||
};
|
||||
|
||||
let mut public_key = String::new();
|
||||
let mut listen_port: u16 = 0;
|
||||
@@ -335,11 +645,40 @@ async fn query_device(name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||
NetlinkPayload::Error(err) => {
|
||||
if let Some(code) = err.code {
|
||||
let code_val = code.get();
|
||||
// ENODEV = -19 means device not found
|
||||
if code_val == -19 {
|
||||
// ENODEV
|
||||
if link_exists {
|
||||
return Ok(Some(LiveInterfaceStats {
|
||||
name: name.to_string(),
|
||||
public_key: String::new(),
|
||||
listen_port: 0,
|
||||
fwmark: 0,
|
||||
peers: Vec::new(),
|
||||
addresses,
|
||||
mtu,
|
||||
is_up,
|
||||
}));
|
||||
}
|
||||
return Ok(None);
|
||||
}
|
||||
if code_val == -1 {
|
||||
// EPERM
|
||||
if link_exists {
|
||||
tracing::warn!(
|
||||
interface = %name,
|
||||
"Permission denied reading WireGuard keys via Generic Netlink; returning RTNETLINK link info"
|
||||
);
|
||||
return Ok(Some(LiveInterfaceStats {
|
||||
name: name.to_string(),
|
||||
public_key: String::new(),
|
||||
listen_port: 0,
|
||||
fwmark: 0,
|
||||
peers: Vec::new(),
|
||||
addresses,
|
||||
mtu,
|
||||
is_up,
|
||||
}));
|
||||
}
|
||||
return Err(WireGuardError::PermissionDenied(
|
||||
"insufficient privileges to query WireGuard device".to_string(),
|
||||
));
|
||||
@@ -438,16 +777,28 @@ async fn query_device(name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||
}
|
||||
}
|
||||
|
||||
if !found {
|
||||
if !found && !link_exists {
|
||||
return Ok(None);
|
||||
}
|
||||
|
||||
tracing::debug!(
|
||||
interface = %name,
|
||||
listen_port,
|
||||
peer_count = live_peers.len(),
|
||||
addresses_count = addresses.len(),
|
||||
is_up,
|
||||
"Retrieved live WireGuard interface telemetry"
|
||||
);
|
||||
|
||||
Ok(Some(LiveInterfaceStats {
|
||||
name: name.to_string(),
|
||||
public_key,
|
||||
listen_port,
|
||||
fwmark,
|
||||
peers: live_peers,
|
||||
addresses,
|
||||
mtu,
|
||||
is_up,
|
||||
}))
|
||||
}
|
||||
|
||||
@@ -507,17 +858,199 @@ fn parse_endpoint(s: &str) -> Result<SocketAddr> {
|
||||
)))
|
||||
}
|
||||
|
||||
/// Install on-link device routes for peer tunnel addresses outside the Interface prefix.
|
||||
///
|
||||
/// Interface-CIDR peers are already covered by the connected route from the
|
||||
/// interface address. Selected-Network peer addresses are not; without a FIB
|
||||
/// path into wg0, cryptokey routing never sees the packet. Routes have no
|
||||
/// gateway and are not Routes-table LAN destinations.
|
||||
async fn ensure_onlink_peer_routes(interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||
let (handle, _join) = rtnetlink_handle().await?;
|
||||
|
||||
let mut links = handle
|
||||
.link()
|
||||
.get()
|
||||
.match_name(interface.name.to_string())
|
||||
.execute();
|
||||
let Some(link) = links.try_next().await.map_err(|e| {
|
||||
WireGuardError::Netlink(format!(
|
||||
"failed to resolve interface '{}' for on-link routes: {e}",
|
||||
interface.name
|
||||
))
|
||||
})?
|
||||
else {
|
||||
return Ok(());
|
||||
};
|
||||
let link_index = link.header.index;
|
||||
|
||||
let desired: HashSet<IpNet> = onlink_peer_address_prefixes(interface, peers)
|
||||
.into_iter()
|
||||
.collect();
|
||||
|
||||
let live = list_onlink_routes_for_index(&handle, link_index).await?;
|
||||
|
||||
for prefix in &desired {
|
||||
if live.contains(prefix) {
|
||||
continue;
|
||||
}
|
||||
add_onlink_device_route(&handle, link_index, *prefix).await?;
|
||||
}
|
||||
|
||||
let iface_v4 = interface.address_v4.trunc();
|
||||
let iface_v6 = interface.address_v6.map(|n| n.trunc());
|
||||
for prefix in live {
|
||||
let is_host = matches!(prefix, IpNet::V4(n) if n.prefix_len() == 32)
|
||||
|| matches!(prefix, IpNet::V6(n) if n.prefix_len() == 128);
|
||||
if !is_host {
|
||||
continue;
|
||||
}
|
||||
if prefix.trunc() == iface_v4 || iface_v6 == Some(prefix.trunc()) {
|
||||
continue;
|
||||
}
|
||||
if desired.contains(&prefix) {
|
||||
continue;
|
||||
}
|
||||
let _ = delete_onlink_device_route(&handle, link_index, prefix).await;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn list_onlink_routes_for_index(
|
||||
handle: &rtnetlink::Handle,
|
||||
link_index: u32,
|
||||
) -> Result<HashSet<IpNet>> {
|
||||
let mut results = HashSet::new();
|
||||
for family in [AddressFamily::Inet, AddressFamily::Inet6] {
|
||||
let mut req = RouteMessage::default();
|
||||
req.header.address_family = family;
|
||||
let mut stream = handle.route().get(req).execute();
|
||||
while let Some(msg) = stream
|
||||
.try_next()
|
||||
.await
|
||||
.map_err(|e| WireGuardError::Netlink(format!("RTNETLINK route dump failed: {e}")))?
|
||||
{
|
||||
let mut dest_ip = match family {
|
||||
AddressFamily::Inet => IpAddr::V4(Ipv4Addr::UNSPECIFIED),
|
||||
AddressFamily::Inet6 => IpAddr::V6(Ipv6Addr::UNSPECIFIED),
|
||||
_ => continue,
|
||||
};
|
||||
let mut oif = None;
|
||||
let mut has_gateway = false;
|
||||
for attr in &msg.attributes {
|
||||
match attr {
|
||||
RouteAttribute::Destination(RouteAddress::Inet(v4)) => {
|
||||
dest_ip = IpAddr::V4(*v4);
|
||||
}
|
||||
RouteAttribute::Destination(RouteAddress::Inet6(v6)) => {
|
||||
dest_ip = IpAddr::V6(*v6);
|
||||
}
|
||||
RouteAttribute::Gateway(_) => has_gateway = true,
|
||||
RouteAttribute::Oif(idx) => oif = Some(*idx),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
if has_gateway || oif != Some(link_index) {
|
||||
continue;
|
||||
}
|
||||
if let Ok(net) = IpNet::new(dest_ip, msg.header.destination_prefix_length) {
|
||||
results.insert(net);
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(results)
|
||||
}
|
||||
|
||||
async fn add_onlink_device_route(
|
||||
handle: &rtnetlink::Handle,
|
||||
link_index: u32,
|
||||
prefix: IpNet,
|
||||
) -> Result<()> {
|
||||
let exec_result = match prefix {
|
||||
IpNet::V4(v4) => {
|
||||
let msg = RouteMessageBuilder::<Ipv4Addr>::new()
|
||||
.destination_prefix(v4.addr(), v4.prefix_len())
|
||||
.output_interface(link_index)
|
||||
.build();
|
||||
handle.route().add(msg).execute().await
|
||||
}
|
||||
IpNet::V6(v6) => {
|
||||
let msg = RouteMessageBuilder::<Ipv6Addr>::new()
|
||||
.destination_prefix(v6.addr(), v6.prefix_len())
|
||||
.output_interface(link_index)
|
||||
.build();
|
||||
handle.route().add(msg).execute().await
|
||||
}
|
||||
};
|
||||
if let Err(e) = exec_result {
|
||||
let err_str = e.to_string();
|
||||
if err_str.contains("File exists") || err_str.contains("17") {
|
||||
return Ok(());
|
||||
}
|
||||
if err_str.contains("permission")
|
||||
|| err_str.contains("EPERM")
|
||||
|| err_str.contains("Operation not permitted")
|
||||
{
|
||||
return Err(WireGuardError::PermissionDenied(format!(
|
||||
"insufficient privileges to add on-link route '{prefix}': {e}"
|
||||
)));
|
||||
}
|
||||
return Err(WireGuardError::Netlink(format!(
|
||||
"failed to add on-link route '{prefix}': {e}"
|
||||
)));
|
||||
}
|
||||
tracing::info!(prefix = %prefix, "On-link peer address route added via RTNETLINK");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn delete_onlink_device_route(
|
||||
handle: &rtnetlink::Handle,
|
||||
link_index: u32,
|
||||
prefix: IpNet,
|
||||
) -> Result<()> {
|
||||
let exec_result = match prefix {
|
||||
IpNet::V4(v4) => {
|
||||
let msg = RouteMessageBuilder::<Ipv4Addr>::new()
|
||||
.destination_prefix(v4.addr(), v4.prefix_len())
|
||||
.output_interface(link_index)
|
||||
.build();
|
||||
handle.route().del(msg).execute().await
|
||||
}
|
||||
IpNet::V6(v6) => {
|
||||
let msg = RouteMessageBuilder::<Ipv6Addr>::new()
|
||||
.destination_prefix(v6.addr(), v6.prefix_len())
|
||||
.output_interface(link_index)
|
||||
.build();
|
||||
handle.route().del(msg).execute().await
|
||||
}
|
||||
};
|
||||
if let Err(e) = exec_result {
|
||||
tracing::debug!(prefix = %prefix, error = %e, "On-link peer address route delete skipped");
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// ── WireGuardEngine Trait Implementation ─────────────────────────────────────
|
||||
|
||||
#[async_trait::async_trait]
|
||||
impl WireGuardEngine for NativeLinuxWireGuardEngine {
|
||||
async fn sync_interface(&self, interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||
// 1. Ensure the WireGuard link exists
|
||||
ensure_link(&interface.name).await?;
|
||||
// 1. Ensure the WireGuard link exists and addresses/MTU are configured
|
||||
ensure_link_and_addresses(interface).await?;
|
||||
|
||||
// 2. Configure the WireGuard device (private key, listen port, peers)
|
||||
configure_device(interface, peers).await?;
|
||||
|
||||
// 3. On-link device routes for peer tunnel addresses outside the
|
||||
// Interface connected prefix (cryptokey routing still uses AllowedIPs).
|
||||
if let Err(e) = ensure_onlink_peer_routes(interface, peers).await {
|
||||
tracing::warn!(
|
||||
interface = %interface.name,
|
||||
error = %e,
|
||||
"On-link peer address routes skipped"
|
||||
);
|
||||
}
|
||||
|
||||
tracing::info!(
|
||||
interface = %interface.name,
|
||||
active_peers = peers.iter().filter(|p| p.state == PeerState::Active).count(),
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
#[cfg(target_os = "linux")]
|
||||
#[tokio::test]
|
||||
async fn test_native_linux_live_discovery() {
|
||||
use nx9_wireguard::NativeLinuxWireGuardEngine;
|
||||
use nx9_wireguard::WireGuardEngine;
|
||||
|
||||
let engine = NativeLinuxWireGuardEngine::new();
|
||||
let ifaces = engine.list_interfaces().await.unwrap();
|
||||
println!("Discovered WireGuard interfaces: {:?}", ifaces);
|
||||
|
||||
// Ensure list_interfaces returns a valid list
|
||||
for iface in &ifaces {
|
||||
match engine.get_interface_stats(iface).await {
|
||||
Ok(Some(stats)) => {
|
||||
println!(
|
||||
"Interface {iface} live stats: public_key={:?}, port={}, peers={}, up={}",
|
||||
stats.public_key,
|
||||
stats.listen_port,
|
||||
stats.peers.len(),
|
||||
stats.is_up
|
||||
);
|
||||
}
|
||||
Ok(None) => println!("Interface {iface} returned None"),
|
||||
Err(e) => println!("Interface {iface} query returned error: {e}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -101,6 +101,9 @@ async fn test_wireguard_engine_lifecycle_and_telemetry() {
|
||||
.expect("interface exists");
|
||||
assert_eq!(stats.name, "wg0");
|
||||
assert_eq!(stats.public_key, srv_pub.as_str());
|
||||
assert_eq!(stats.addresses, vec!["10.0.0.1/24".to_string()]);
|
||||
assert_eq!(stats.mtu, Some(1420));
|
||||
assert!(stats.is_up);
|
||||
assert_eq!(
|
||||
stats.peers.len(),
|
||||
1,
|
||||
|
||||
+17
-13
@@ -6,10 +6,10 @@ The `nx9-wg` API daemon serves JSON REST endpoints and a real-time WebSocket eve
|
||||
|
||||
## 1. Authentication & Session Model
|
||||
|
||||
Authentication is supported via two mechanisms:
|
||||
Authentication is supported via two secure mechanisms:
|
||||
|
||||
### A. HTTP Session Cookie (`nx9_session`)
|
||||
Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header and automatically attached by web browsers.
|
||||
Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header with `HttpOnly; SameSite=Strict; Path=/` and automatically attached by web browsers for both REST API requests and WebSocket upgrade handshakes.
|
||||
|
||||
### B. Bearer API Token
|
||||
Passed in the `Authorization` header:
|
||||
@@ -36,8 +36,8 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `401 Unauthorized`: Missing, invalid, or expired session/token.
|
||||
- `404 Not Found`: Resource ID does not exist in SQLite.
|
||||
- `409 Conflict`: Unique constraint violation (e.g. duplicate interface name or IP).
|
||||
- `422 Unprocessable Entity`: Semantic constraint failure.
|
||||
- `429 Too Many Requests`: Brute-force rate limiting triggered.
|
||||
- `422 Unprocessable Entity`: Semantic constraint failure (e.g. invalid server host with embedded port, invalid port bounds).
|
||||
- `429 Too Many Requests`: Brute-force rate limiting triggered (5 failed logins in 15 minutes).
|
||||
- `500 Internal Server Error`: Native Linux execution plane or storage failure.
|
||||
|
||||
---
|
||||
@@ -58,20 +58,20 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `GET /api/v1/system/version`: Public version and build information.
|
||||
- `GET /api/v1/system`: System operational overview and interface/peer counts.
|
||||
- `GET /api/v1/system/settings`: List all key-value settings.
|
||||
- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "...", "value": "...", "description": "..." }`.
|
||||
- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "wireguard.server_host", "value": "vpn.thakares.com", "is_secret": false, "description": "..." }`. Supports `wireguard.server_host`, `wireguard.server_port`, and `wireguard.server_endpoint_enabled`.
|
||||
|
||||
### WireGuard Interfaces
|
||||
- `GET /api/v1/interfaces`: List all WireGuard interfaces.
|
||||
- `POST /api/v1/interfaces`: Create interface `{ "name": "wg0", "address_v4": "10.100.0.1/24", "listen_port": 51820, "mtu": 1420 }`.
|
||||
- `GET /api/v1/interfaces/{id}`: Get interface details.
|
||||
- `PUT /api/v1/interfaces/{id}`: Update interface configuration.
|
||||
- `PUT /api/v1/interfaces/{id}`: Update interface configuration (preserves private/public cryptographic identity).
|
||||
- `DELETE /api/v1/interfaces/{id}`: Delete interface (cascades to peers).
|
||||
- `POST /api/v1/interfaces/{id}/enable`: Set interface `IFF_UP`.
|
||||
- `POST /api/v1/interfaces/{id}/disable`: Set interface `IFF_DOWN`.
|
||||
- `GET /api/v1/interfaces/{id}/status`: Query live kernel netlink telemetry.
|
||||
|
||||
### Peers & Client Configs
|
||||
- `GET /api/v1/peers`: List all peers across all interfaces.
|
||||
- `GET /api/v1/peers`: List all peers across all interfaces (enriched with live kernel telemetry).
|
||||
- `GET /api/v1/interfaces/{id}/peers`: List peers for specific interface.
|
||||
- `POST /api/v1/interfaces/{id}/peers`: Enroll peer `{ "name": "alice", "profile": "full_tunnel", "mtu": 1280, ... }`.
|
||||
- `GET /api/v1/peers/{id}`: Get peer details.
|
||||
@@ -79,8 +79,12 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `DELETE /api/v1/peers/{id}`: Delete peer.
|
||||
- `POST /api/v1/peers/{id}/enable`: Enable peer.
|
||||
- `POST /api/v1/peers/{id}/disable`: Disable peer.
|
||||
- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...`).
|
||||
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg`).
|
||||
- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...&endpoint=...`). Uses persistent `wireguard.server_*` settings if `endpoint` query parameter is omitted.
|
||||
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg&endpoint=...`). Returns `{ "svg": "<svg...", "data_url": "data:image/png;base64,..." }`.
|
||||
|
||||
### Client Profiles & MTU Resolution
|
||||
- `GET /api/v1/client-profiles`: List client transport profiles.
|
||||
- `GET /api/v1/client-profiles/resolve`: Resolve optimal MTU and keepalive parameters for device and connection environment.
|
||||
|
||||
### Networks & Subnets
|
||||
- `GET /api/v1/networks`: List subnet networks.
|
||||
@@ -95,8 +99,8 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `DELETE /api/v1/routes/{id}`: Delete route.
|
||||
|
||||
### Firewall & NAT
|
||||
- `GET /api/v1/firewall/rules`: List nftables rules.
|
||||
- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": "22", "action": "accept" }`.
|
||||
- `GET /api/v1/firewall/rules`: List nftables rules in `table inet nx9_wg`.
|
||||
- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": 22, "action": "accept" }`.
|
||||
- `DELETE /api/v1/firewall/rules/{id}`: Delete rule.
|
||||
- `POST /api/v1/firewall/rules/{id}/enable`: Enable rule.
|
||||
- `POST /api/v1/firewall/rules/{id}/disable`: Disable rule.
|
||||
@@ -106,7 +110,7 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `POST /api/v1/reconcile/apply`: Execute native mutations and verify convergence.
|
||||
|
||||
### Diagnostics
|
||||
- `GET /api/v1/diagnostics/all`: Run automated checks across all 9 subsystems.
|
||||
- `GET /api/v1/diagnostics/all`: Run automated checks across all subsystems.
|
||||
- `GET /api/v1/diagnostics/{subsystem}`: Run checks for a single subsystem.
|
||||
|
||||
### Backups
|
||||
@@ -123,7 +127,7 @@ All non-2xx responses return a structured JSON error body:
|
||||
|
||||
## 4. Real-Time WebSocket Protocol (`/api/v1/ws`)
|
||||
|
||||
Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events:
|
||||
Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events. Authentication is handled automatically using the browser's `nx9_session` cookie or `Authorization: Bearer <token>` header:
|
||||
|
||||
```json
|
||||
{
|
||||
File renamed without changes.
File renamed without changes.
+177
@@ -0,0 +1,177 @@
|
||||
# Native CLI Command Reference (`nx9-wg`)
|
||||
|
||||
The `nx9-wg` binary provides native CLI coverage across all 18 application command groups without spawning external subprocesses.
|
||||
|
||||
---
|
||||
|
||||
## 1. Global Options
|
||||
|
||||
| Option | Environment Variable | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `-c, --config <PATH>` | `NX9_WG_CONFIG` | Path to configuration file (default: `/etc/nx9-wg/config.toml`) |
|
||||
| `-d, --data-dir <PATH>` | `NX9_WG_DATA_DIR` | Path to data directory (default: `/var/lib/nx9-wg`) |
|
||||
| `--database <PATH>` | `NX9_WG_DATABASE` | Specific SQLite database file path or URL |
|
||||
| `--format <FORMAT>` | N/A | Output format (`table`, `json`, `yaml`, `csv`, default: `table`) |
|
||||
| `--json` | N/A | Convenience flag for strict JSON output |
|
||||
| `-q, --quiet` | N/A | Suppress status and conversational messages |
|
||||
| `-v, --verbose` | N/A | Enable verbose trace logging |
|
||||
| `--log-level <LEVEL>` | `NX9_WG_LOG_LEVEL` | Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Command Groups Reference
|
||||
|
||||
### 1. `version`
|
||||
Displays version, build edition, architecture, OS platform, and security flags.
|
||||
```bash
|
||||
nx9-wg version
|
||||
nx9-wg version --format json
|
||||
```
|
||||
|
||||
### 2. `serve`
|
||||
Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler.
|
||||
```bash
|
||||
nx9-wg serve
|
||||
nx9-wg serve --bind 0.0.0.0:8080
|
||||
```
|
||||
|
||||
### 3. `init`
|
||||
Initializes the single administrator account across bootstrap sources.
|
||||
```bash
|
||||
# Generate secure random password written to a restricted file:
|
||||
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||
|
||||
# Password via stdin:
|
||||
echo "StrongPassword123!" | nx9-wg init --password-stdin
|
||||
|
||||
# Password from file:
|
||||
nx9-wg init --password-file /run/secrets/admin_pw
|
||||
```
|
||||
|
||||
### 4. `system`
|
||||
- `nx9-wg system status`: System database statistics and object counts.
|
||||
- `nx9-wg system health`: System and SQLite connectivity health check.
|
||||
- `nx9-wg system info`: System platform, architecture, and runtime paths.
|
||||
- `nx9-wg system settings list`: List all key-value settings.
|
||||
- `nx9-wg system settings get <KEY>`: Query setting value.
|
||||
- `nx9-wg system settings set <KEY> <VALUE> [--secret]`: Save setting (validates `wireguard.server_host`, `wireguard.server_port`, `wireguard.server_endpoint_enabled`).
|
||||
- `nx9-wg system settings delete <KEY>`: Delete setting.
|
||||
|
||||
```bash
|
||||
# Configure persistent WireGuard 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
|
||||
```
|
||||
|
||||
### 5. `admin`
|
||||
- `nx9-wg admin status`: Query administrator account metadata.
|
||||
- `nx9-wg admin create [--username U] [--password P | --password-stdin | --generate-password]`: Bootstrap admin if uninitialized.
|
||||
- `nx9-wg admin password [--new-password P | --stdin | --password-file F | --generate]`: Change administrator password.
|
||||
- `nx9-wg admin tokens create --name <NAME> [--days N] [--write-token-file PATH]`: Generate API token.
|
||||
- `nx9-wg admin tokens list`: List active API tokens.
|
||||
- `nx9-wg admin tokens revoke <TOKEN_ID>`: Revoke an API token.
|
||||
- `nx9-wg admin sessions list`: List active browser sessions.
|
||||
- `nx9-wg admin sessions revoke <SESSION_ID>`: Revoke an active session.
|
||||
- `nx9-wg admin sessions revoke-all`: Invalidate all active sessions.
|
||||
|
||||
### 6. `interface`
|
||||
- `nx9-wg interface list`: List all WireGuard interfaces.
|
||||
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--address-v6 <CIDR>] [--port PORT] [--mtu MTU] [--dns DNS]`: Create interface.
|
||||
- `nx9-wg interface show <NAME_OR_ID>`: Show interface details.
|
||||
- `nx9-wg interface update <NAME_OR_ID> [--port P] [--address-v4 A] [--address-v6 A] [--mtu M] [--dns D] [--enabled BOOL]`: Update interface.
|
||||
- `nx9-wg interface enable <NAME_OR_ID>`: Enable interface (`IFF_UP`).
|
||||
- `nx9-wg interface disable <NAME_OR_ID>`: Disable interface (`IFF_DOWN`).
|
||||
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface (cascades to peers).
|
||||
- `nx9-wg interface status <NAME_OR_ID>`: Show live interface status and peer metrics.
|
||||
- `nx9-wg interface reconcile <NAME_OR_ID>`: Reconcile specific interface with kernel.
|
||||
|
||||
### 7. `peer`
|
||||
- `nx9-wg peer list [--interface NAME_OR_ID]`: List enrolled peers.
|
||||
- `nx9-wg peer show <PEER_ID>`: Show peer configuration.
|
||||
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--peer-type TYPE] [--profile PROFILE] [--network NET] [--address-v4 CIDR] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu MTU] [--expires-at RFC3339]`: Enroll peer.
|
||||
- `nx9-wg peer update <PEER_ID> [--name N] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu M] [--enabled BOOL]`: Update peer.
|
||||
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>`: Toggle peer state.
|
||||
- `nx9-wg peer revoke <PEER_ID>`: Revoke peer.
|
||||
- `nx9-wg peer expire <PEER_ID>`: Mark peer as expired.
|
||||
- `nx9-wg peer lifecycle <PEER_ID>`: Show peer lifecycle metadata.
|
||||
- `nx9-wg peer status <PEER_ID>`: Show live peer status and telemetry.
|
||||
- `nx9-wg peer delete <PEER_ID>`: Delete peer.
|
||||
- `nx9-wg peer config <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--output PATH]`: Export `.conf` client file (uses persistent `wireguard.server_*` settings or `--endpoint` override).
|
||||
- `nx9-wg peer qr <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--qr-format terminal|svg|png]`: Render QR code in terminal, SVG, or PNG format.
|
||||
|
||||
### 8. `profile`
|
||||
- `nx9-wg profile list [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT]`: List client configuration profiles.
|
||||
- `nx9-wg profile show <PROFILE_ID>`: Show details of a client profile (e.g. `default-mobile`, `android-mobile`).
|
||||
- `nx9-wg profile validate <MTU>`: Validate MTU against safe operational limits.
|
||||
- `nx9-wg profile resolve [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF]`: Resolve optimal client profile and MTU.
|
||||
|
||||
### 9. `network`
|
||||
- `nx9-wg network list`: List subnet networks.
|
||||
- `nx9-wg network show <ID>`: Show network details.
|
||||
- `nx9-wg network create <NAME> --cidr <CIDR> [--description DESC]`: Create network.
|
||||
- `nx9-wg network available <ID> [--limit N] [--interface IFACE]`: Show available unallocated IP addresses.
|
||||
- `nx9-wg network allocations <ID>`: Show allocated IP addresses and peer mappings.
|
||||
- `nx9-wg network update <ID> [--name N] [--cidr C] [--description D] [--enabled BOOL]`: Update network.
|
||||
- `nx9-wg network delete <ID>`: Delete subnet network.
|
||||
|
||||
### 10. `route`
|
||||
- `nx9-wg route list`: List configured routing rules.
|
||||
- `nx9-wg route show <ID>`: Show route details.
|
||||
- `nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]`: Add kernel routing rule.
|
||||
- `nx9-wg route update <ID> [--destination C] [--gateway IP] [--interface-name IFACE] [--metric M] [--enabled BOOL]`: Update route.
|
||||
- `nx9-wg route delete <ID>`: Delete routing rule.
|
||||
- `nx9-wg route status`: Show current kernel routing status.
|
||||
- `nx9-wg route sync`: Synchronize routes with kernel routing table.
|
||||
|
||||
### 11. `firewall`
|
||||
- `nx9-wg firewall list [--peer PEER]`: List configured nftables rules.
|
||||
- `nx9-wg firewall show <ID>`: Show firewall rule details.
|
||||
- `nx9-wg firewall add --name <NAME> [--direction in|out|forward] [--source CIDR] [--destination CIDR] [--peer PEER] [--protocol tcp|udp|tcp_udp|icmp|any] [--port P] [--port-range R] [--action accept|drop|reject] [--priority P]`: Add rule.
|
||||
- `nx9-wg firewall update <ID> [--name N] [--action A] [--priority P] [--enabled BOOL]`: Update rule.
|
||||
- `nx9-wg firewall enable <ID>` / `disable <ID>`: Toggle rule.
|
||||
- `nx9-wg firewall delete <ID>`: Delete rule.
|
||||
- `nx9-wg firewall sync`: Synchronize nftables ruleset in `table inet nx9_wg`.
|
||||
- `nx9-wg firewall status`: Show active nftables status.
|
||||
|
||||
### 12. `nat`
|
||||
- `nx9-wg nat status`: Query NAT masquerade state.
|
||||
- `nx9-wg nat enable` / `disable`: Toggle outbound NAT masquerading.
|
||||
- `nx9-wg nat list`: List subnets configured for NAT masquerade.
|
||||
- `nx9-wg nat sync`: Synchronize NAT rules with kernel.
|
||||
|
||||
### 13. `forwarding`
|
||||
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
|
||||
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP packet forwarding.
|
||||
- `nx9-wg forwarding sync`: Synchronize IP forwarding setting with kernel.
|
||||
|
||||
### 14. `reconcile`
|
||||
- `nx9-wg reconcile status`: Inspect reconciliation status and statistics.
|
||||
- `nx9-wg reconcile plan [--interface IFACE]`: Calculate read-only drift plan between SQLite and Linux kernel.
|
||||
- `nx9-wg reconcile apply [--interface IFACE]`: Apply reconciliation mutations to live kernel state.
|
||||
- `nx9-wg reconcile verify`: Verify zero drift between SQLite and kernel.
|
||||
|
||||
### 15. `backup`
|
||||
- `nx9-wg backup list`: List backup snapshots.
|
||||
- `nx9-wg backup create [--description DESC]`: Generate atomic SQLite online backup (`VACUUM INTO`).
|
||||
- `nx9-wg backup show <ID>`: Show backup details and manifest.
|
||||
- `nx9-wg backup verify <PATH>`: Verify SQLite 3 header and SHA-256 checksum.
|
||||
- `nx9-wg backup restore <PATH> [-y, --yes]`: Restore database with automatic safety snapshot.
|
||||
- `nx9-wg backup delete <ID>`: Delete backup record and snapshot archive.
|
||||
|
||||
### 16. `audit`
|
||||
- `nx9-wg audit list [--event-type TYPE] [--actor ACTOR] [--resource-type TYPE] [--limit N] [--offset N]`: List append-only audit trail records.
|
||||
- `nx9-wg audit show <ID>`: Show full details for an audit event.
|
||||
|
||||
### 17. `live`
|
||||
- `nx9-wg live interface list`: List live WireGuard interface names in kernel.
|
||||
- `nx9-wg live interface show <NAME>`: Show live interface statistics.
|
||||
- `nx9-wg live peer <IFACE>`: Query live peers, transfer bytes, and handshakes.
|
||||
- `nx9-wg live routes`: Query live Linux kernel routing table.
|
||||
- `nx9-wg live firewall`: Query live active `table inet nx9_wg` nftables ruleset.
|
||||
- `nx9-wg live forwarding`: Query live IP packet forwarding status.
|
||||
- `nx9-wg live nat`: Query live NAT masquerade status.
|
||||
|
||||
### 18. `diagnostics`
|
||||
- `nx9-wg diagnostics all`: Inspect health across all subsystems.
|
||||
- `nx9-wg diagnostics <SUBSYSTEM> [--peer PEER_UUID]`: Inspect specific subsystem (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`).
|
||||
@@ -59,8 +59,50 @@ Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` n
|
||||
|
||||
---
|
||||
|
||||
## Persistent WireGuard Server Endpoint Configuration
|
||||
|
||||
When generating client `.conf` configurations and QR codes, `nx9-wg` embeds the public or reachable server endpoint address so client devices can reach the server. This is managed through persistent settings in SQLite.
|
||||
|
||||
### Settings Keys
|
||||
|
||||
| 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. | `51820` | `51820` |
|
||||
| `wireguard.server_endpoint_enabled` | Boolean | Whether the persistent server 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` |
|
||||
|
||||
### Important Architectural Invariants
|
||||
|
||||
- **Public Endpoint vs. Interface Listen Port**: The public server endpoint (`wireguard.server_host` and `wireguard.server_port`) is the external address that clients use to connect across the Internet or WAN. It is conceptually separate from the WireGuard interface's local kernel UDP `listen_port` (which may sit behind NAT, port-forwarding, or a reverse proxy).
|
||||
- **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**: If no endpoint is configured, generation fails with an actionable error directing the administrator to configure the server endpoint in Settings or provide an explicit override.
|
||||
|
||||
### Configuring via CLI
|
||||
|
||||
```bash
|
||||
# Configure the persistent 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
|
||||
|
||||
# Export a client configuration using the persistent default:
|
||||
nx9-wg peer config <PEER_UUID>
|
||||
# Generated output contains: Endpoint = vpn.thakares.com:51820
|
||||
|
||||
# Export with a temporary one-off override (does not modify persistent settings):
|
||||
nx9-wg peer config <PEER_UUID> --endpoint custom.backup-vpn.com:51820
|
||||
# Generated output contains: Endpoint = custom.backup-vpn.com:51820
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Secret Handling & Docker Secrets
|
||||
|
||||
- **Never Persisted in Cleartext**: `NX9_WG_ADMIN_PASSWORD` is hashed into SQLite using Argon2id during initialization and is never written to disk, config files, or logs.
|
||||
- **Docker Secrets**: In container environments, mount Docker secrets to `/run/secrets/nx9_wg_admin_password` and specify `NX9_WG_ADMIN_PASSWORD_FILE=/run/secrets/nx9_wg_admin_password`.
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -53,7 +53,7 @@ The `port_range` field supports three RFC-compliant formats:
|
||||
NAT masquerading is governed by key-value appliance settings in SQLite:
|
||||
|
||||
- **`enable_nat`**: Boolean string (`"true"` / `"false"`). When enabled, all active managed WireGuard subnets are masqueraded outbound to the host WAN interface.
|
||||
- **Dynamic Subnet Calculation**: The reconciliation engine queries all enabled interfaces (`Interface.address_v4`) and generates dedicated masquerade rules for each unique subnet.
|
||||
- **Dynamic Subnet Calculation**: The reconciliation engine queries enabled Interface address CIDRs and enabled Subnet Network CIDRs, then generates dedicated masquerade rules for each unique subnet. Interface addresses remain the WireGuard transport identity; Network CIDRs are the peer allocation domains.
|
||||
|
||||
---
|
||||
|
||||
@@ -23,8 +23,8 @@ Download and extract the official release archive:
|
||||
|
||||
```bash
|
||||
# 1. Download release archive (replace with current version/arch)
|
||||
tar -xzf nx9-wg-v0.8.0-linux-x86_64.tar.gz
|
||||
cd nx9-wg-v0.8.0-linux-x86_64
|
||||
tar -xzf nx9-wg-v1.0.0-linux-x86_64.tar.gz
|
||||
cd nx9-wg-v1.0.0-linux-x86_64
|
||||
|
||||
# 2. Run the automated installer as root
|
||||
sudo bash install.sh
|
||||
@@ -94,7 +94,7 @@ sudo systemctl status nx9-wg
|
||||
### Step 3.2 — Check Operational Health via CLI
|
||||
```bash
|
||||
sudo /usr/local/bin/nx9-wg system health
|
||||
sudo /usr/local/bin/nx9-wg diagnostics inspect all
|
||||
sudo /usr/local/bin/nx9-wg diagnostics all
|
||||
```
|
||||
|
||||
### Step 3.3 — Log in via Web User Interface
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -66,8 +66,9 @@ table inet nx9_wg {
|
||||
|
||||
Outbound NAT masquerading is dynamically scoped exclusively to managed WireGuard client subnets:
|
||||
1. **Subnet Deduplication**: Overlapping subnets are merged to prevent redundant rules.
|
||||
2. **Interface Exclusion**: Traffic routing back into the WireGuard interface (`oifname != "wg0"`) is not masqueraded to preserve true source IPs for site-to-site tunnels.
|
||||
2. **Interface Exclusion**: Traffic routing back into the WireGuard interface (`oifname != "wg*"`) is not masqueraded to preserve true source IPs for site-to-site tunnels.
|
||||
3. **No Catch-All Masquerade**: `nx9-wg` never creates a catch-all `masquerade` rule that affects non-WireGuard traffic on the host.
|
||||
4. **Interface and Subnet Network CIDRs**: Masquerade sources include each enabled Interface address CIDR and each enabled Subnet Network CIDR. A peer allocated from a selected Network (for example outside the WireGuard interface `/24`) is masqueraded from that Network CIDR; the Interface address itself is unchanged.
|
||||
|
||||
---
|
||||
|
||||
+19
-19
@@ -5,38 +5,38 @@ Welcome to the official documentation for the **NX9 WireGuard (`nx9-wg`)** appli
|
||||
---
|
||||
|
||||
## 1. Getting Started & Philosophy
|
||||
- [**NX9 Design Principles**](design-principles.md) — Architectural philosophy, self-hosted sovereignty, zero scripting runtime, and SQLite authority.
|
||||
- [**Installation & Deployment Guide**](installation.md) — Production installation, systemd service, admin bootstrap, first interface, and peer setup.
|
||||
- [**Linux Platform & Kernel Requirements**](linux_requirements.md) — Kernel 5.6+, in-tree WireGuard module, Netlink sockets, `libnftables.so.1`, and capabilities.
|
||||
- [**NX9 Design Principles**](DESIGN-PRINCIPLES.md) — Architectural philosophy, self-hosted sovereignty, zero scripting runtime, and SQLite authority.
|
||||
- [**Installation & Deployment Guide**](INSTALLATION.md) — Production installation, systemd service, admin bootstrap, first interface, and peer setup.
|
||||
- [**Linux Platform & Kernel Requirements**](LINUX_REQUIREMENTS.md) — Kernel 5.6+, in-tree WireGuard module, Netlink sockets, `libnftables.so.1`, and capabilities.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture & Native Linux Execution
|
||||
- [**System Architecture & Workspace Structure**](architecture.md) — Six-crate workspace breakdown, layer boundaries, and end-to-end data flows.
|
||||
- [**Native WireGuard Netlink Engine**](native-wireguard.md) — Direct RTNETLINK and Generic Netlink (`wireguard`) protocol implementation.
|
||||
- [**Native Network & Routing Engine**](native-network.md) — RTNETLINK link/address/route lifecycle and direct procfs IP packet forwarding.
|
||||
- [**Native nftables Engine**](nftables.md) — In-process `libnftables.so.1` FFI transactions and dedicated `table inet nx9_wg` scoping.
|
||||
- [**Firewall & NAT Domain Model**](firewall_nat.md) — Typed rules, protocol groups, port ranges, priorities, and outbound NAT masquerading.
|
||||
- [**System Architecture & Workspace Structure**](ARCHITECTURE.md) — Six-crate workspace breakdown, layer boundaries, and end-to-end data flows.
|
||||
- [**Native WireGuard Netlink Engine**](NATIVE-WIREGUARD.md) — Direct RTNETLINK and Generic Netlink (`wireguard`) protocol implementation.
|
||||
- [**Native Network & Routing Engine**](NATIVE-NETWORK.md) — RTNETLINK link/address/route lifecycle and direct procfs IP packet forwarding.
|
||||
- [**Native nftables Engine**](NFTABLES.md) — In-process `libnftables.so.1` FFI transactions and dedicated `table inet nx9_wg` scoping.
|
||||
- [**Firewall & NAT Domain Model**](FIREWALL_NAT.md) — Typed rules, protocol groups, port ranges, priorities, and outbound NAT masquerading.
|
||||
|
||||
---
|
||||
|
||||
## 3. Control Plane, UI & Telemetry
|
||||
- [**Reconciliation Engine & Convergence**](reconciliation.md) — Closed-loop drift detection, read-only planning, serialized apply, and convergence lifecycle states.
|
||||
- [**Web User Interface (SPA)**](ui.md) — Zero-dependency embedded HTML5/CSS/JS frontend, theme engine, and all 15 application routes.
|
||||
- [**Axum REST API & WebSocket Protocol**](api.md) — Complete endpoint reference, JSON schemas, error handling, and real-time event broadcaster.
|
||||
- [**Native CLI Command Reference**](cli.md) — Full reference for all 17 CLI subcommands, multi-format output (`table`/`json`/`yaml`/`csv`), and secret files.
|
||||
- [**Reconciliation Engine & Convergence**](RECONCILIATION.md) — Closed-loop drift detection, read-only planning, serialized apply, and convergence lifecycle states.
|
||||
- [**Web User Interface (SPA)**](UI.md) — Zero-dependency embedded HTML5/CSS/JS frontend, theme engine, and all 15 application routes.
|
||||
- [**Axum REST API & WebSocket Protocol**](API.md) — Complete endpoint reference, JSON schemas, error handling, and real-time event broadcaster.
|
||||
- [**Native CLI Command Reference**](CLI.md) — Full reference for all 18 CLI subcommands, multi-format output (`table`/`json`/`yaml`/`csv`), and secret files.
|
||||
|
||||
---
|
||||
|
||||
## 4. Security & Disaster Recovery
|
||||
- [**Security Model & Privilege Architecture**](security.md) — Single admin model (`CHECK (id=1)`), Argon2id hashing, SHA-256 tokens, permissions matrix, and brute-force protection.
|
||||
- [**Backup & Disaster Recovery Guide**](backup_restore.md) — Atomic online SQLite backups (`VACUUM INTO`), SHA-256 manifests, and pre-restore safety snapshots.
|
||||
- [**Security Model & Privilege Architecture**](SECURITY.md) — Single admin model (`CHECK (id=1)`), Argon2id hashing, SHA-256 tokens, permissions matrix, and brute-force protection.
|
||||
- [**Backup & Disaster Recovery Guide**](BACKUP_RESTORE.md) — Atomic online SQLite backups (`VACUUM INTO`), SHA-256 manifests, and pre-restore safety snapshots.
|
||||
|
||||
---
|
||||
|
||||
## 5. Operations, Development & Release
|
||||
- [**Release Engineering & Packaging**](release.md) — Standalone distribution packages (`.tar.gz`/`.tar.xz`), systemd sandboxing, installer, and rollback strategy.
|
||||
- [**Quality Assurance & Testing Strategy**](testing.md) — Multi-tiered test suites, SAFE mode (`LIVE=0`) vs real-kernel mode (`LIVE=1`), and automated security audits.
|
||||
- [**Developer & Contributing Guide**](development.md) — Building, testing, linting, and workspace contribution standards.
|
||||
- [**Configuration Reference**](configuration.md) — TOML configuration format and `NX9_WG_*` environment variable precedence.
|
||||
- [**Docker & Container Deployment**](docker.md) — Containerized deployment with Linux capability isolation and volume persistence.
|
||||
- [**Release Engineering & Packaging**](RELEASE.md) — Standalone distribution packages (`.tar.gz`/`.tar.xz`), systemd sandboxing, installer, and rollback strategy.
|
||||
- [**Comprehensive Testing Specification**](TESTING.md) — Multi-tiered test suites, SAFE mode (`LIVE=0`) vs real-kernel mode (`LIVE=1`), and automated security audits.
|
||||
- [**Developer & Contributing Guide**](DEVELOPMENT.md) — Building, testing, linting, and workspace contribution standards.
|
||||
- [**Configuration Reference**](CONFIGURATION.md) — TOML configuration format and `NX9_WG_*` environment variable precedence.
|
||||
- [**Docker & Container Deployment**](DOCKER.md) — Containerized deployment with Linux capability isolation and volume persistence.
|
||||
File renamed without changes.
@@ -6,31 +6,36 @@ This document describes the release packaging, artifact verification, filesystem
|
||||
|
||||
## 1. Release Packaging Pipeline
|
||||
|
||||
Release archives are generated using [`scripts/package-release.sh`](file:///home/sunil/Programs/nx9-wg/scripts/package-release.sh):
|
||||
Release archives are generated using [`scripts/package-release.sh`](../scripts/package-release.sh):
|
||||
|
||||
```bash
|
||||
bash scripts/package-release.sh
|
||||
```
|
||||
|
||||
### Packaging Outputs in `target/dist/`:
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.tar.gz` (Standard gzip archive)
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.tar.xz` (High-compression XZ archive)
|
||||
- `nx9-wg-v0.8.0-linux-x86_64.sha256` (Cryptographic SHA-256 checksums)
|
||||
- `nx9-wg-v1.0.0-linux-x86_64.tar.gz` (Standard gzip archive)
|
||||
- `nx9-wg-v1.0.0-linux-x86_64.tar.xz` (High-compression XZ archive)
|
||||
- `nx9-wg-v1.0.0-linux-x86_64.sha256` (Cryptographic SHA-256 checksums)
|
||||
|
||||
---
|
||||
|
||||
## 2. Release Archive Contents
|
||||
## 2. Release Documentation
|
||||
|
||||
The release documentation is versioned with the source tree. `CHANGELOG.md` records release-level changes, while `docs/TESTING.md` is the authoritative v1.0.0 testing and acceptance specification.
|
||||
|
||||
## 3. Release Archive Contents
|
||||
|
||||
Every release archive contains everything required for a standalone, offline production deployment:
|
||||
|
||||
```
|
||||
nx9-wg-v0.8.0-linux-x86_64/
|
||||
nx9-wg-v1.0.0-linux-x86_64/
|
||||
├── nx9-wg (Native executable binary, mode 0755)
|
||||
├── nx9-wg.service (Hardened systemd unit file, mode 0644)
|
||||
├── config.example.toml (Production configuration template, mode 0644)
|
||||
├── install.sh (Automated production installer, mode 0755)
|
||||
├── uninstall.sh (Safe uninstallation script, mode 0755)
|
||||
├── README.md (Primary project guide)
|
||||
├── CHANGELOG.md (Release history)
|
||||
├── LICENSE-MIT (MIT License text)
|
||||
├── LICENSE-APACHE (Apache 2.0 License text)
|
||||
└── docs/ (Complete offline documentation suite)
|
||||
@@ -38,7 +43,7 @@ nx9-wg-v0.8.0-linux-x86_64/
|
||||
|
||||
---
|
||||
|
||||
## 3. Standalone Verification Invariant
|
||||
## 4. Standalone Verification Invariant
|
||||
|
||||
Release packages must function completely independently of the source repository. When extracted into an isolated clean directory (`/tmp/nx9-release-verify...`):
|
||||
- `nx9-wg version` outputs valid version, architecture, and platform strings.
|
||||
@@ -48,7 +53,7 @@ Release packages must function completely independently of the source repository
|
||||
|
||||
---
|
||||
|
||||
## 4. Production Filesystem Layout
|
||||
## 5. Production Filesystem Layout
|
||||
|
||||
```
|
||||
/usr/local/bin/nx9-wg (0755 root:root - Binary)
|
||||
@@ -67,7 +72,7 @@ Release packages must function completely independently of the source repository
|
||||
|
||||
---
|
||||
|
||||
## 5. Systemd Security Sandboxing
|
||||
## 6. Systemd Security Sandboxing
|
||||
|
||||
The production service unit (`nx9-wg.service`) enforces modern Linux security directives:
|
||||
|
||||
@@ -79,7 +84,7 @@ The production service unit (`nx9-wg.service`) enforces modern Linux security di
|
||||
|
||||
---
|
||||
|
||||
## 6. Upgrade and Rollback Sequence
|
||||
## 7. Upgrade and Rollback Sequence
|
||||
|
||||
### Mandatory Upgrade Flow
|
||||
1. **Pre-Upgrade Backup**: `nx9-wg backup create --description "Pre-upgrade checkpoint"`
|
||||
File renamed without changes.
@@ -0,0 +1,595 @@
|
||||
# NX9-WG Stress Test --- Remote LAN Multi-Path Integration
|
||||
|
||||
**Project:** NX9-WG\
|
||||
**Test Type:** Integration / Stress Test\
|
||||
**Status:** PASS\
|
||||
**Date:** 2026-08-19\
|
||||
**Purpose:** Validate robust remote access to a protected LAN through
|
||||
NX9-WG across substantially different underlying network paths.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
This test validates that `nx9-wg` can provide authenticated, routed
|
||||
access to a remote `192.168.1.0/24` LAN while the WireGuard client uses
|
||||
different and independent Internet/access-network paths.
|
||||
|
||||
The test deliberately exercised NX9-WG through:
|
||||
|
||||
1. Cellular 5G → mobile WAN AP → laptop.
|
||||
2. Airtel Wi-Fi → Pixel Wi-Fi Station + Access Point concurrency →
|
||||
laptop.
|
||||
3. A separate Wi-Fi network → laptop.
|
||||
|
||||
In all tested paths, the same NX9-WG peer successfully established the
|
||||
VPN and reached hosts and services on the protected LAN.
|
||||
|
||||
The strongest validation was successful interactive SSH access to
|
||||
`192.168.1.200`, in addition to ICMP, HTTP, network filesystem access,
|
||||
and LAN host discovery.
|
||||
|
||||
**Overall result: PASS.**
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 2. Test Objective
|
||||
|
||||
Validate that NX9-WG:
|
||||
|
||||
- establishes a WireGuard tunnel independently of the client's
|
||||
underlying access network;
|
||||
- correctly routes traffic from a remote peer to the protected LAN;
|
||||
- handles different upstream NAT/network topologies;
|
||||
- provides access to multiple LAN hosts rather than only a single
|
||||
endpoint;
|
||||
- supports real application traffic over the tunnel;
|
||||
- preserves connectivity when the client changes access-network
|
||||
topology;
|
||||
- does not require changes to the protected LAN or ISP router
|
||||
configuration.
|
||||
|
||||
This test is intended as an **integration and robustness validation**,
|
||||
not as a throughput benchmark.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 3. Network Topology
|
||||
|
||||
### Protected LAN
|
||||
|
||||
``` text
|
||||
192.168.1.0/24
|
||||
```
|
||||
|
||||
Representative hosts:
|
||||
|
||||
``` text
|
||||
192.168.1.1 Airtel AirFiber / Nokia AAP321NK
|
||||
192.168.1.200 Debian server / Thakares IoT Hub
|
||||
```
|
||||
|
||||
### NX9-WG peer
|
||||
|
||||
``` text
|
||||
WireGuard interface: Office-Laptop
|
||||
WireGuard address: 10.100.0.6/32
|
||||
MTU: 1280
|
||||
```
|
||||
|
||||
The important architectural property is that the client-side underlay
|
||||
network can change while the WireGuard overlay identity and protected
|
||||
LAN remain unchanged.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 4. Test Scenario A --- Cellular 5G
|
||||
|
||||
## Path
|
||||
|
||||
``` text
|
||||
5G Internet
|
||||
│
|
||||
▼
|
||||
Mobile phone
|
||||
│
|
||||
│ WAN AP / hotspot
|
||||
▼
|
||||
Laptop
|
||||
│
|
||||
│ NX9-WG
|
||||
▼
|
||||
NX9-WG server
|
||||
│
|
||||
│ routed LAN access
|
||||
▼
|
||||
192.168.1.0/24
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Mobile phone connected to cellular 5G.
|
||||
2. Mobile phone provided WAN/AP connectivity.
|
||||
3. Laptop connected to the mobile AP.
|
||||
4. NX9-WG VPN was enabled.
|
||||
5. Laptop received an Internet address on the mobile network.
|
||||
6. Remote LAN routes became reachable through NX9-WG.
|
||||
|
||||
## Observed client addressing
|
||||
|
||||
``` text
|
||||
wlan0: 10.137.106.48/24
|
||||
WireGuard: 10.100.0.6/32
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
### Internet
|
||||
|
||||
``` text
|
||||
ping google.com
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
``` text
|
||||
0% packet loss
|
||||
```
|
||||
|
||||
### LAN host
|
||||
|
||||
``` text
|
||||
ping 192.168.1.200
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
``` text
|
||||
0% packet loss
|
||||
```
|
||||
|
||||
### LAN discovery
|
||||
|
||||
An initial ordinary `nmap -sP 192.168.1.0/24` did not discover hosts
|
||||
while the LAN was only reachable through the routed WireGuard path.
|
||||
Individual routed hosts were nevertheless reachable.
|
||||
|
||||
This was subsequently validated more comprehensively in Scenario C using
|
||||
`nmap` with the active routed path.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 5. Test Scenario B --- Wi-Fi STA + AP Concurrency
|
||||
|
||||
This was the more interesting underlay test.
|
||||
|
||||
The Pixel device supports simultaneous Wi-Fi client (STA) and Access
|
||||
Point operation.
|
||||
|
||||
## Path
|
||||
|
||||
``` text
|
||||
Airtel Wi-Fi
|
||||
│
|
||||
▼
|
||||
Pixel Wi-Fi STA
|
||||
│
|
||||
Pixel Wi-Fi AP
|
||||
│
|
||||
▼
|
||||
Laptop
|
||||
│
|
||||
NX9-WG
|
||||
│
|
||||
▼
|
||||
NX9-WG server
|
||||
│
|
||||
▼
|
||||
192.168.1.0/24
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Pixel connected to Airtel Wi-Fi.
|
||||
2. Pixel simultaneously enabled its Access Point.
|
||||
3. Laptop connected to the Pixel AP.
|
||||
4. Laptop enabled NX9-WG.
|
||||
5. No cellular Internet was used.
|
||||
6. Remote LAN access worked immediately.
|
||||
|
||||
## Result
|
||||
|
||||
**PASS**
|
||||
|
||||
This demonstrates that NX9-WG remains functional when the client reaches
|
||||
the Internet through a Wi-Fi STA/AP-concurrent intermediate device.
|
||||
|
||||
No cellular fallback was required.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 6. Test Scenario C --- Remote LAN Application and Host Validation
|
||||
|
||||
A further test was performed from an external Wi-Fi network.
|
||||
|
||||
## Client addressing
|
||||
|
||||
``` text
|
||||
wlan0:
|
||||
10.24.3.48/24
|
||||
|
||||
WireGuard:
|
||||
10.100.0.6/32
|
||||
```
|
||||
|
||||
The underlying Wi-Fi network therefore differed from the protected LAN.
|
||||
|
||||
## Internet validation
|
||||
|
||||
``` bash
|
||||
ping nx9.in
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
``` text
|
||||
5 packets transmitted
|
||||
5 received
|
||||
0% packet loss
|
||||
|
||||
min/avg/max/mdev:
|
||||
82.653 / 93.637 / 101.691 / 7.049 ms
|
||||
```
|
||||
|
||||
## Public Internet validation
|
||||
|
||||
``` bash
|
||||
ping google.com
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
``` text
|
||||
5 packets transmitted
|
||||
5 received
|
||||
0% packet loss
|
||||
|
||||
min/avg/max/mdev:
|
||||
87.633 / 118.502 / 165.108 / 30.034 ms
|
||||
```
|
||||
|
||||
## Airtel gateway validation
|
||||
|
||||
``` bash
|
||||
ping 192.168.1.1
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
``` text
|
||||
2 packets transmitted
|
||||
2 received
|
||||
0% packet loss
|
||||
|
||||
min/avg/max/mdev:
|
||||
98.975 / 99.509 / 100.043 / 0.534 ms
|
||||
```
|
||||
|
||||
## LAN server validation
|
||||
|
||||
``` bash
|
||||
ping 192.168.1.200
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
``` text
|
||||
3 packets transmitted
|
||||
3 received
|
||||
0% packet loss
|
||||
|
||||
min/avg/max/mdev:
|
||||
88.959 / 95.690 / 105.145 / 6.882 ms
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 7. LAN Host Discovery
|
||||
|
||||
The routed LAN was scanned using:
|
||||
|
||||
``` bash
|
||||
nmap -sP 192.168.1.0/24
|
||||
```
|
||||
|
||||
The following 17 hosts were discovered:
|
||||
|
||||
``` text
|
||||
192.168.1.1
|
||||
192.168.1.3
|
||||
192.168.1.4
|
||||
192.168.1.5
|
||||
192.168.1.6
|
||||
192.168.1.7
|
||||
192.168.1.8
|
||||
192.168.1.9
|
||||
192.168.1.10
|
||||
192.168.1.13
|
||||
192.168.1.18
|
||||
192.168.1.20
|
||||
192.168.1.60
|
||||
192.168.1.64
|
||||
192.168.1.100
|
||||
192.168.1.152
|
||||
192.168.1.200
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
``` text
|
||||
17 hosts up
|
||||
```
|
||||
|
||||
This is significant because it validates routed access to the LAN as a
|
||||
network segment rather than connectivity to only one predefined host.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 8. Application-Level Validation
|
||||
|
||||
## HTTP
|
||||
|
||||
The NX9-WG client successfully accessed:
|
||||
|
||||
``` text
|
||||
http://192.168.1.200:8008
|
||||
```
|
||||
|
||||
The Thakares IoT Hub web application loaded successfully.
|
||||
|
||||
## Network filesystem
|
||||
|
||||
The Linux desktop successfully accessed the remote Debian server:
|
||||
|
||||
``` text
|
||||
192.168.1.200
|
||||
/home/sunil
|
||||
```
|
||||
|
||||
## SSH
|
||||
|
||||
The strongest application-level validation was:
|
||||
|
||||
``` bash
|
||||
ssh 192.168.1.200
|
||||
```
|
||||
|
||||
which produced a normal interactive login:
|
||||
|
||||
``` text
|
||||
Linux thakares 6.12.101+deb13-rt-amd64
|
||||
Debian GNU/Linux
|
||||
x86_64
|
||||
```
|
||||
|
||||
The remote shell was successfully entered and exited normally.
|
||||
|
||||
This confirms:
|
||||
|
||||
- TCP connectivity;
|
||||
- routing;
|
||||
- return-path routing;
|
||||
- firewall/forwarding compatibility;
|
||||
- SSH service accessibility;
|
||||
- stable encrypted transport;
|
||||
- real bidirectional application traffic.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 9. Test Results
|
||||
|
||||
Validation Result
|
||||
------------------------------------ --------
|
||||
WireGuard tunnel establishment PASS
|
||||
External Internet through tunnel PASS
|
||||
Cellular 5G underlay PASS
|
||||
Wi-Fi underlay PASS
|
||||
Wi-Fi STA + AP concurrent underlay PASS
|
||||
Protected LAN reachability PASS
|
||||
Airtel gateway `192.168.1.1` PASS
|
||||
LAN server `192.168.1.200` PASS
|
||||
ICMP PASS
|
||||
LAN host discovery PASS
|
||||
HTTP application PASS
|
||||
Network filesystem access PASS
|
||||
SSH PASS
|
||||
Interactive remote shell PASS
|
||||
Multiple LAN hosts PASS
|
||||
No cellular dependency PASS
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 10. Key Finding
|
||||
|
||||
The same NX9-WG peer:
|
||||
|
||||
``` text
|
||||
10.100.0.6/32
|
||||
```
|
||||
|
||||
successfully accessed:
|
||||
|
||||
``` text
|
||||
192.168.1.0/24
|
||||
```
|
||||
|
||||
while its underlying client network changed.
|
||||
|
||||
Examples included:
|
||||
|
||||
``` text
|
||||
10.137.106.0/24
|
||||
10.24.3.0/24
|
||||
```
|
||||
|
||||
This demonstrates a clean separation between:
|
||||
|
||||
- **underlay:** whatever network currently provides Internet
|
||||
connectivity;
|
||||
- **overlay:** the authenticated NX9-WG tunnel;
|
||||
- **protected network:** the routed `192.168.1.0/24` LAN.
|
||||
|
||||
The protected LAN required no modification for these tests.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 11. Why This Is a Meaningful Stress Test
|
||||
|
||||
This test does not attempt to measure maximum WireGuard throughput.
|
||||
|
||||
Instead, it stresses the **network topology and routing assumptions** of
|
||||
NX9-WG.
|
||||
|
||||
The tested paths introduce:
|
||||
|
||||
- different client networks;
|
||||
- different NAT environments;
|
||||
- mobile AP routing;
|
||||
- Wi-Fi STA/AP concurrency;
|
||||
- additional network hops;
|
||||
- remote access to an entire private subnet;
|
||||
- multiple simultaneous LAN destinations;
|
||||
- multiple application protocols.
|
||||
|
||||
The successful results indicate that NX9-WG is not dependent on a
|
||||
particular client access network.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 12. Airtel LAN Collision Use Case
|
||||
|
||||
The test originated from a practical problem involving an Airtel
|
||||
AirFiber Nokia AAP321NK using:
|
||||
|
||||
``` text
|
||||
192.168.1.1
|
||||
```
|
||||
|
||||
which overlaps with the existing home LAN addressing.
|
||||
|
||||
Instead of modifying the ISP-controlled router configuration, NX9-WG
|
||||
provided an independent routed management path:
|
||||
|
||||
``` text
|
||||
External network
|
||||
│
|
||||
▼
|
||||
NX9-WG
|
||||
│
|
||||
▼
|
||||
192.168.1.0/24
|
||||
│
|
||||
├── 192.168.1.1
|
||||
├── 192.168.1.200
|
||||
└── other LAN hosts
|
||||
```
|
||||
|
||||
This demonstrates a practical operational benefit of the NX9-WG
|
||||
architecture: remote authenticated access to infrastructure can remain
|
||||
available without requiring ISP router reconfiguration.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 13. What This Test Does Not Establish
|
||||
|
||||
This test should **not** be interpreted as a performance benchmark.
|
||||
|
||||
The following remain outside the scope of this test:
|
||||
|
||||
- maximum throughput;
|
||||
- sustained high-volume transfer;
|
||||
- CPU utilisation;
|
||||
- simultaneous high-volume traffic from many peers;
|
||||
- large-scale concurrent peer testing;
|
||||
- packet-loss recovery under severe loss;
|
||||
- roaming during an active session;
|
||||
- MTU/fragmentation testing under load;
|
||||
- IPv6 routed-LAN testing;
|
||||
- server restart/recovery testing;
|
||||
- client sleep/resume testing;
|
||||
- long-duration soak testing.
|
||||
|
||||
These should be covered by separate tests if required.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 14. Recommended Future Stress Tests
|
||||
|
||||
Future NX9-WG validation can extend this matrix with:
|
||||
|
||||
### Performance
|
||||
|
||||
``` text
|
||||
iperf3
|
||||
```
|
||||
|
||||
- TCP throughput;
|
||||
- UDP throughput;
|
||||
- bidirectional traffic;
|
||||
- sustained transfers.
|
||||
|
||||
### Reliability
|
||||
|
||||
- 1-hour soak test;
|
||||
- 24-hour soak test;
|
||||
- repeated tunnel reconnects;
|
||||
- server restart;
|
||||
- client suspend/resume.
|
||||
|
||||
### Mobility
|
||||
|
||||
- Wi-Fi → 5G;
|
||||
- 5G → Wi-Fi;
|
||||
- AP changes while tunnel is active;
|
||||
- changing NAT environments.
|
||||
|
||||
### Scale
|
||||
|
||||
- multiple simultaneous peers;
|
||||
- multiple LAN destinations;
|
||||
- concurrent HTTP/SSH/file traffic.
|
||||
|
||||
### Network edge cases
|
||||
|
||||
- MTU stress;
|
||||
- fragmentation;
|
||||
- packet loss;
|
||||
- high latency;
|
||||
- jitter;
|
||||
- IPv6.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 15. Final Assessment
|
||||
|
||||
**NX9-WG Remote LAN Multi-Path Integration Test: PASS**
|
||||
|
||||
The implementation successfully provided authenticated routed access
|
||||
from externally connected clients to the protected `192.168.1.0/24` LAN
|
||||
across multiple substantially different network paths.
|
||||
|
||||
The successful SSH session to `192.168.1.200`, access to the IoT Hub,
|
||||
network filesystem access, and discovery of 17 LAN hosts provide strong
|
||||
practical evidence that the VPN is functioning as a complete remote-LAN
|
||||
connectivity solution rather than merely establishing a WireGuard
|
||||
handshake.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
**Test conclusion:**
|
||||
|
||||
> NX9-WG successfully maintained functional remote access to the
|
||||
> protected LAN independently of the underlying client access network,
|
||||
> including cellular, Wi-Fi, and Wi-Fi STA/AP concurrent paths.
|
||||
|
||||
**Status: PASS**
|
||||
+487
@@ -0,0 +1,487 @@
|
||||
# NX9-WG v1.0.0 — Comprehensive Testing Specification
|
||||
|
||||
This document is the authoritative testing and release-acceptance specification for NX9-WG.
|
||||
|
||||
NX9-WG is a native Linux WireGuard, networking, firewall/NAT, reconciliation, telemetry, and WebUI control plane. Testing therefore covers both the Rust control plane and the Linux kernel data plane.
|
||||
|
||||
> **Release principle:** Passing unit and integration tests does not substitute for physical WireGuard client validation. A production VPN release must distinguish simulated/control-plane evidence from real packet-path evidence.
|
||||
|
||||
---
|
||||
|
||||
## 1. Testing Philosophy
|
||||
|
||||
Testing is layered from deterministic Rust unit tests through native Linux kernel integration and real client acceptance. Each layer has a defined scope and must not be represented as evidence for a different layer.
|
||||
|
||||
Primary invariants:
|
||||
|
||||
- SQLite is authoritative desired state.
|
||||
- Linux kernel state is live state.
|
||||
- Reconciliation is deterministic and idempotent.
|
||||
- Server-side WireGuard peer `AllowedIPs` represent cryptokey routing, not client routing policy.
|
||||
- Client-side `AllowedIPs` represent the client's routing policy.
|
||||
- NAT and forwarding must operate on real packets, not merely generated nftables rules.
|
||||
- Live peer status must be derived from kernel telemetry.
|
||||
- Secrets must never leak through logs, CLI output, API responses, or test artifacts.
|
||||
|
||||
## 2. Release Quality Gates
|
||||
|
||||
| Gate | Command / Evidence | Requirement |
|
||||
|---|---|---|
|
||||
| Formatting | `cargo fmt --all -- --check` | PASS |
|
||||
| Compilation | `cargo check --workspace --all-targets` | PASS |
|
||||
| Lint | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | PASS |
|
||||
| Workspace tests | `cargo test --workspace` | All tests PASS |
|
||||
| Release build | `cargo build --release --workspace` | PASS |
|
||||
| CLI suite | `LIVE=0 bash scripts/test-cli-comprehensive.sh` | PASS |
|
||||
| Native integration | `LIVE=0 bash scripts/test-native-integration.sh` | PASS |
|
||||
| Kernel suite | `LIVE=0 bash scripts/test-live-kernel.sh` | PASS in SAFE baseline; LIVE acceptance requires dedicated host |
|
||||
| Diff hygiene | `git diff --check` | PASS |
|
||||
| Physical client | Android WireGuard acceptance | Required for production VPN certification |
|
||||
|
||||
## 3. Workspace Unit Tests
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
The v1.0.0 documentation baseline records **162 passing workspace tests**. The final release count must always be regenerated after code changes; documentation must never assume that the historical count remains unchanged.
|
||||
|
||||
Focused crates may be run independently:
|
||||
|
||||
```bash
|
||||
cargo test -p nx9-wg-core
|
||||
cargo test -p nx9-wireguard
|
||||
cargo test -p nx9-wg-api
|
||||
cargo test -p nx9-wg-db
|
||||
cargo test -p nx9-wg-network
|
||||
cargo test -p nx9-wg-ui
|
||||
```
|
||||
|
||||
## 4. Formatting, Compilation & Clippy
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace --all-targets
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
cargo build --release --workspace
|
||||
```
|
||||
|
||||
No release is accepted with formatting drift, compiler warnings promoted by `-D warnings`, or a non-reproducible release build.
|
||||
|
||||
## 5. Core Domain & Validation Tests
|
||||
|
||||
Validate:
|
||||
|
||||
- Interface identity and CIDR validation.
|
||||
- Peer tunnel address validation.
|
||||
- Full-tunnel, split-tunnel, and custom client profiles.
|
||||
- Server/client `AllowedIPs` semantic separation.
|
||||
- Non-overlapping server-side cryptokey routes.
|
||||
- MTU validation.
|
||||
- Endpoint validation.
|
||||
- Interface-name uniqueness.
|
||||
- Key preservation during interface edits.
|
||||
|
||||
## 6. WireGuard Engine Tests
|
||||
|
||||
The WireGuard engine must validate:
|
||||
|
||||
- Interface creation and deletion.
|
||||
- Private/public key configuration.
|
||||
- Listen port and MTU.
|
||||
- Peer creation/update/removal.
|
||||
- `ReplaceAllowedIps` behavior.
|
||||
- Server-side peer routes derived from assigned addresses.
|
||||
- Learned endpoint and handshake telemetry.
|
||||
- Idempotent synchronization.
|
||||
|
||||
For a road-warrior peer such as `10.100.0.9/32`, the Linux kernel peer must receive `10.100.0.9/32`, not the client's `0.0.0.0/0` full-tunnel route.
|
||||
|
||||
## 7. Client Configuration & QR Tests
|
||||
|
||||
Verify generated client configuration:
|
||||
|
||||
```ini
|
||||
[Interface]
|
||||
Address = 10.100.0.9/32
|
||||
|
||||
[Peer]
|
||||
AllowedIPs = 0.0.0.0/0
|
||||
Endpoint = <configured-server-endpoint>:51820
|
||||
```
|
||||
|
||||
For IPv4-only server interfaces, do not silently export `::/0` unless IPv6 service is actually configured and intended.
|
||||
|
||||
Verify:
|
||||
|
||||
- Explicit endpoint override wins.
|
||||
- Persistent `server_endpoint` setting is consumed automatically.
|
||||
- Endpoint includes a valid UDP port.
|
||||
- QR generation is equivalent to exported configuration.
|
||||
- Terminal QR rendering works.
|
||||
- WebUI QR rendering is present and scannable.
|
||||
|
||||
## 8. REST API Tests
|
||||
|
||||
Cover:
|
||||
|
||||
- Interface CRUD.
|
||||
- Interface editing.
|
||||
- Peer CRUD.
|
||||
- Peer telemetry enrichment.
|
||||
- Server endpoint settings.
|
||||
- QR/config export.
|
||||
- Reconciliation endpoints.
|
||||
- Diagnostics.
|
||||
- Authentication and authorization.
|
||||
- Invalid input and conflict responses.
|
||||
|
||||
Telemetry responses must expose current kernel-derived endpoint, handshake, RX, and TX values where available.
|
||||
|
||||
## 9. WebUI Tests
|
||||
|
||||
Verify:
|
||||
|
||||
- Interface list displays existing interfaces.
|
||||
- Interface Edit action exists.
|
||||
- Edit form preserves public identity and does not regenerate keys.
|
||||
- Peer list displays tunnel address and learned endpoint.
|
||||
- QR action is available.
|
||||
- Endpoint configuration is visible in Settings.
|
||||
- Refresh Telemetry obtains fresh kernel state.
|
||||
- Status states are truthful.
|
||||
|
||||
Status semantics:
|
||||
|
||||
| State | Condition |
|
||||
|---|---|
|
||||
| Connected | Active peer with handshake age < 180 seconds |
|
||||
| Awaiting Handshake | Active peer with no observed handshake |
|
||||
| Disconnected | Active peer with handshake age >= 180 seconds |
|
||||
| Disabled | Peer disabled |
|
||||
| Expired | Peer expired |
|
||||
| Revoked | Peer revoked |
|
||||
|
||||
## 10. Timestamp & Telemetry Tests
|
||||
|
||||
Backend timestamps must carry an explicit UTC offset. Browser parsing must not reinterpret UTC database timestamps as local wall-clock timestamps.
|
||||
|
||||
Test:
|
||||
|
||||
- Never-handshaken peer.
|
||||
- Fresh handshake.
|
||||
- Handshake exactly around the 180-second boundary.
|
||||
- Stale handshake.
|
||||
- RX/TX counters increasing.
|
||||
- Learned endpoint changing due to roaming.
|
||||
- SQLite telemetry cache update.
|
||||
|
||||
## 11. Reconciliation Tests
|
||||
|
||||
Required lifecycle:
|
||||
|
||||
```text
|
||||
Desired SQLite State
|
||||
↓
|
||||
Reconciliation Plan
|
||||
↓
|
||||
Native Linux Engines
|
||||
↓
|
||||
Kernel State
|
||||
↓
|
||||
Live Telemetry
|
||||
↓
|
||||
Zero Drift
|
||||
```
|
||||
|
||||
Test deliberate drift in:
|
||||
|
||||
- Interface address.
|
||||
- Interface MTU.
|
||||
- Interface listen port.
|
||||
- Peer server-side `AllowedIPs`.
|
||||
- Peer keepalive.
|
||||
- Routes.
|
||||
- Firewall/NAT state.
|
||||
|
||||
For every mutation:
|
||||
|
||||
```bash
|
||||
sudo nx9-wg reconcile plan
|
||||
sudo nx9-wg reconcile apply
|
||||
sudo nx9-wg reconcile plan
|
||||
```
|
||||
|
||||
The final plan must report zero drift.
|
||||
|
||||
## 12. Network & Routing Tests
|
||||
|
||||
Verify:
|
||||
|
||||
- `10.100.0.0/24 dev wg0` exists when `10.100.0.1/24` is assigned.
|
||||
- Peer `/32` routes resolve through `wg0`.
|
||||
- No unintended default-route replacement occurs.
|
||||
- Existing LAN routes remain intact.
|
||||
- Route deletion/recreation converges safely.
|
||||
- Split-tunnel routes remain distinct from full-tunnel client routing.
|
||||
|
||||
## 13. Forwarding Tests
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
sudo nx9-wg live forwarding --json
|
||||
```
|
||||
|
||||
Expected IPv4 forwarding is enabled for a full-tunnel road-warrior deployment.
|
||||
|
||||
Where IPv6 is not configured, IPv6 forwarding must not create an accidental blackhole or misleading client configuration.
|
||||
|
||||
## 14. Firewall & NAT Tests
|
||||
|
||||
The managed nftables table is:
|
||||
|
||||
```text
|
||||
table inet nx9_wg
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
- Atomic ruleset application.
|
||||
- Forward chain behavior.
|
||||
- Established/related traffic handling.
|
||||
- NAT masquerade scoped to `10.100.0.0/24`.
|
||||
- No unrelated nftables table is flushed.
|
||||
- Packet counters increase during real client traffic.
|
||||
|
||||
A successful ruleset-generation test is not equivalent to packet-level NAT validation.
|
||||
|
||||
## 15. SAFE Mode Testing (`LIVE=0`)
|
||||
|
||||
SAFE mode is the default for developer workstations:
|
||||
|
||||
```bash
|
||||
LIVE=0 bash scripts/test-cli-comprehensive.sh
|
||||
LIVE=0 bash scripts/test-native-integration.sh
|
||||
LIVE=0 bash scripts/test-live-kernel.sh
|
||||
```
|
||||
|
||||
SAFE mode validates control-plane logic, parsers, deterministic builders, simulations, and read-only kernel inspection without intentionally mutating production networking.
|
||||
|
||||
## 16. LIVE Kernel Testing (`LIVE=1`)
|
||||
|
||||
LIVE testing requires a dedicated disposable Linux host or VM with appropriate privileges.
|
||||
|
||||
```bash
|
||||
sudo -E LIVE=1 bash scripts/test-native-integration.sh
|
||||
sudo -E LIVE=1 bash scripts/test-live-kernel.sh
|
||||
```
|
||||
|
||||
The test harness must:
|
||||
|
||||
- Capture a baseline.
|
||||
- Use isolated test resources.
|
||||
- Avoid changing default routes.
|
||||
- Avoid modifying unrelated nftables tables.
|
||||
- Restore forwarding state.
|
||||
- Remove only resources created by the test.
|
||||
- Compare post-test state against baseline.
|
||||
|
||||
## 17. Comprehensive CLI Suite
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
LIVE=0 bash scripts/test-cli-comprehensive.sh
|
||||
```
|
||||
|
||||
The suite covers CLI commands, help, output formats, authentication, profiles, interfaces, peers, routes, firewall, NAT, forwarding, reconciliation, backup, audit, live inspection, diagnostics, environment handling, explicit database paths, and source-level safety checks.
|
||||
|
||||
The documented baseline is **203 passed / 7 skipped**; regenerate the count after any test changes.
|
||||
|
||||
## 18. Native Integration Suite
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
LIVE=0 bash scripts/test-native-integration.sh
|
||||
```
|
||||
|
||||
The documented baseline is **19 passed / 1 skipped**.
|
||||
|
||||
The suite validates the desired-state-to-native-engine-to-kernel architecture, drift injection, convergence, and diagnostic evidence.
|
||||
|
||||
## 19. Dedicated Live-Kernel Suite
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
LIVE=0 bash scripts/test-live-kernel.sh
|
||||
```
|
||||
|
||||
The documented SAFE baseline is **23 passed / 1 skipped**. A true production release should additionally capture a `LIVE=1` evidence run on the intended Linux platform.
|
||||
|
||||
## 20. Security, Secrets & Script Safety
|
||||
|
||||
Audit requirements:
|
||||
|
||||
- No plaintext private keys in normal human-readable diagnostics.
|
||||
- No passwords in logs.
|
||||
- No preshared keys in normal status output.
|
||||
- No token secrets in logs or test output.
|
||||
- No production subprocess execution from the Rust control plane.
|
||||
- Scripts use strict shell options and bounded cleanup.
|
||||
- Live tests use isolated temporary resources.
|
||||
- Installer/uninstaller operations are explicit and privilege-aware.
|
||||
|
||||
The repository scripts are:
|
||||
|
||||
- `scripts/install.sh`
|
||||
- `scripts/package-release.sh`
|
||||
- `scripts/test-cli-comprehensive.sh`
|
||||
- `scripts/test-cli-live.sh`
|
||||
- `scripts/test-live-kernel.sh`
|
||||
- `scripts/test-native-integration.sh`
|
||||
- `scripts/uninstall.sh`
|
||||
|
||||
## 21. Physical Android / Road-Warrior Acceptance
|
||||
|
||||
A real WireGuard client is mandatory evidence for production VPN certification.
|
||||
|
||||
Minimum test:
|
||||
|
||||
1. Generate QR/config for a test peer.
|
||||
2. Import into the official Android WireGuard client.
|
||||
3. Connect over LAN first.
|
||||
4. Verify `ping 10.100.0.1`.
|
||||
5. Verify Internet IP connectivity such as `ping 1.1.1.1`.
|
||||
6. Verify DNS resolution.
|
||||
7. Load an HTTPS page.
|
||||
8. Confirm server live telemetry reports endpoint, handshake, RX, and TX.
|
||||
9. Disconnect and verify stale-state transition.
|
||||
10. Reconnect and verify telemetry refresh.
|
||||
|
||||
For WAN road-warrior certification:
|
||||
|
||||
1. Disable Android Wi-Fi.
|
||||
2. Use 4G/5G cellular data.
|
||||
3. Configure the public server endpoint.
|
||||
4. Forward UDP 51820 to the NX9-WG host.
|
||||
5. Verify handshake, tunnel reachability, DNS, and full-tunnel Internet.
|
||||
|
||||
## 22. Release Acceptance Matrix
|
||||
|
||||
| Acceptance Gate | v1.0.0 Evidence Status |
|
||||
|---|---|
|
||||
| Real Android handshake | **PASS — operator verified** |
|
||||
| Tunnel control connectivity | **PASS — operator verified** |
|
||||
| Full-tunnel Internet | **PASS — operator verified** |
|
||||
| NAT/forwarding data plane | **PASS — operator verified through working Internet path; packet-counter evidence should be retained for formal audit** |
|
||||
| Disconnect/reconnect status | **PASS — implementation verified; retain physical transition evidence for audit** |
|
||||
| Interface editing | **PASS — operator verified** |
|
||||
| Persistent server endpoint / QR | **PASS — operator verified** |
|
||||
| WebUI live peer status | **PASS — operator verified with connected mobile client** |
|
||||
| Final reconciliation | **PASS — zero drift observed** |
|
||||
| IPv6 safety | **PASS — code/config validation; live IPv6 remains deployment-specific** |
|
||||
| External cellular/WAN road-warrior | **NOT VERIFIED unless separately executed and recorded** |
|
||||
| Post-reboot physical-client persistence | **NOT VERIFIED unless separately executed and recorded** |
|
||||
|
||||
**Release rule:** Do not convert an unexecuted physical gate into PASS merely because simulated or unit tests pass.
|
||||
|
||||
## 23. Server Reboot Acceptance
|
||||
|
||||
On the actual deployment host:
|
||||
|
||||
```bash
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
After boot:
|
||||
|
||||
```bash
|
||||
sudo systemctl status nx9-wg --no-pager
|
||||
sudo nx9-wg live interface show wg0 --json
|
||||
sudo nx9-wg live peer list wg0 --json
|
||||
sudo nx9-wg reconcile plan
|
||||
```
|
||||
|
||||
Verify that desired state reconstructs:
|
||||
|
||||
- `wg0`.
|
||||
- Interface address.
|
||||
- Listen port and MTU.
|
||||
- Server-side peer `/32` routes.
|
||||
- Forwarding.
|
||||
- nftables/NAT.
|
||||
- WebUI/API availability.
|
||||
|
||||
Then reconnect a physical client and repeat the data-plane acceptance.
|
||||
|
||||
## 24. Release Packaging Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo build --release --workspace
|
||||
bash scripts/package-release.sh
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
- Package name contains `v1.0.0`.
|
||||
- Binary reports `1.0.0`.
|
||||
- README and CHANGELOG are included.
|
||||
- `docs/TESTING.md` is included.
|
||||
- Installation scripts are executable.
|
||||
- Archive extracts into an isolated directory.
|
||||
- SHA-256 manifest matches the generated archives.
|
||||
|
||||
## 25. Version & Repository Consistency Audit
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo metadata --no-deps --format-version 1
|
||||
./target/release/nx9-wg --version
|
||||
grep -RIn --exclude-dir=.git 'v0.8.0\|0.8.0' .
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Historical backup/runtime artifacts are not release documentation and must not be packaged as source or distribution state.
|
||||
|
||||
All current release-facing references must identify v1.0.0.
|
||||
|
||||
## 26. Final Release Command Set
|
||||
|
||||
The minimum final gate is:
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace --all-targets
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
cargo test --workspace
|
||||
cargo build --release --workspace
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Then execute the appropriate SAFE and LIVE suites, followed by physical client acceptance and package verification.
|
||||
|
||||
## 27. Evidence Retention
|
||||
|
||||
For a formal release record, retain:
|
||||
|
||||
- Exact commit ID.
|
||||
- `cargo test --workspace` output.
|
||||
- CLI/integration/kernel test summaries.
|
||||
- `nx9-wg --version` output.
|
||||
- `systemctl status nx9-wg` output.
|
||||
- Live WireGuard interface/peer JSON.
|
||||
- Reconciliation plan output.
|
||||
- Android handshake and Internet verification evidence.
|
||||
- WAN/cellular evidence where performed.
|
||||
- Reboot evidence where performed.
|
||||
- Release archive SHA-256 checksums.
|
||||
|
||||
This evidence separates **software correctness**, **kernel integration correctness**, and **real-world VPN data-plane correctness**.
|
||||
+12
-7
@@ -10,7 +10,7 @@
|
||||
- **Embedded Static Assets**: HTML, CSS, and JavaScript are bundled into the binary at compile time via `include_str!()` and served from memory.
|
||||
- **Unified Design Tokens**: Custom CSS variable design system (`nx9-wg-ui/src/css.rs`) providing Dark and Light themes with persistent `localStorage` preference.
|
||||
- **Responsive Layout**: Mobile-first responsive layout with side-drawer navigation and `@media (max-width: 768px)` breakpoints.
|
||||
- **Live WebSocket Event Stream**: Connects to `ws://<host>/api/v1/ws` for reactive dashboard, peer handshake, and reconciliation updates without polling.
|
||||
- **Live WebSocket Event Stream**: Connects to `ws://<host>/api/v1/ws` authenticated via the browser's `nx9_session` HttpOnly cookie for reactive dashboard, peer handshake, and reconciliation updates without polling.
|
||||
- **Presentation-Only Separation**: The UI contains presentation and client routing logic only; all business validation, allocation, and state authority reside in the backend REST API and SQLite.
|
||||
|
||||
---
|
||||
@@ -20,7 +20,7 @@
|
||||
| Hash Route | Navigation Label | Purpose & Operational Features |
|
||||
| :--- | :--- | :--- |
|
||||
| `#dashboard` | **Dashboard** | System status, uptime, interface/peer counts, diagnostics health, and reconciliation status cards. |
|
||||
| `#interfaces` | **Interfaces** | List WireGuard interfaces, "+ Create Interface" modal, enable/disable toggle, and delete interface. |
|
||||
| `#interfaces` | **Interfaces** | List WireGuard interfaces, "+ Create Interface" modal, interface "Edit" action (with cryptographic key preservation), enable/disable toggle, and delete interface. |
|
||||
| `#peers` | **Peers** | Enrolled peer table with real-time handshakes, status filter, "+ Add Peer" modal with MTU profile resolution, client configuration export, and live SVG QR rendering. |
|
||||
| `#networks` | **Networks** | Subnet network ranges, CIDR masks, "+ Create Network" modal, and deletion. |
|
||||
| `#routes` | **Routes** | Routing table entries, gateway assignments, "+ Create Route" modal, and deletion. |
|
||||
@@ -28,9 +28,9 @@
|
||||
| `#nat` | **NAT & Masquerade** | Outbound NAT masquerade status card, active masqueraded subnet list, and instant toggle. |
|
||||
| `#forwarding` | **IP Forwarding** | Kernel sysctl `/proc/sys/net/ipv4/ip_forward` packet forwarding status and toggle. |
|
||||
| `#reconciliation` | **Reconciliation** | Real-time kernel drift overview, planned execution actions table, and interactive "Run Reconcile (Apply)" button. |
|
||||
| `#diagnostics` | **Diagnostics** | Automated health inspection across all 9 subsystems (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`) with remediation hints. |
|
||||
| `#diagnostics` | **Diagnostics** | Automated health inspection across all subsystems (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`) with remediation hints. |
|
||||
| `#live-state` | **Live State** | Live Linux Netlink kernel telemetry, active WireGuard interfaces, and live routing table entries. |
|
||||
| `#settings` | **Settings** | Appliance key-value parameters table and danger zone reset controls. |
|
||||
| `#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 database backup snapshots list, "+ Create Backup Snapshot" button, and direct `.db` download. |
|
||||
| `#audit` | **Audit Log** | Append-only security and administrative audit trail with actor, IP, timestamp, and metadata. |
|
||||
| `#administrator` | **Administrator** | Admin account verification, "Change Password" modal, and "+ Generate API Token" modal with one-time raw secret copy. |
|
||||
@@ -43,9 +43,14 @@
|
||||
When enrolling a new peer (`#peers`), the modal automatically queries `/api/v1/client-profiles/resolve` based on selected Device (Android, iOS, Linux, Windows, macOS) and Connection (Mobile Cellular 4G/5G, Wi-Fi, Wired Ethernet) to determine optimal MTU (1280 vs 1360 vs 1420) and persistent keepalive (25s).
|
||||
|
||||
### B. Client Export & QR Code Modal
|
||||
Displays both:
|
||||
1. **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
|
||||
2. **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
|
||||
When opening the export modal for a peer, the UI automatically:
|
||||
1. Pre-populates the **Server Endpoint** field using the persistent settings (`wireguard.server_host` and `wireguard.server_port`) configured under Settings.
|
||||
2. Displays a `"Default from Server Settings"` badge indicating persistent configuration source.
|
||||
3. Automatically triggers client `.conf` and QR code generation on modal open without requiring manual typing.
|
||||
4. Allows the administrator to enter a temporary one-off endpoint override directly in the modal for specialized network requirements without mutating global server settings.
|
||||
5. Displays both:
|
||||
- **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
|
||||
- **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
|
||||
|
||||
### C. One-Time API Token Delivery Modal
|
||||
Generates a new API token, calculates its SHA-256 digest for SQLite storage, and presents the raw token string once in an interactive modal with a copy button.
|
||||
-132
@@ -1,132 +0,0 @@
|
||||
# Native CLI Command Reference (`nx9-wg`)
|
||||
|
||||
The `nx9-wg` binary provides 100% native CLI coverage across all 17 application subcommands without spawning external subprocesses.
|
||||
|
||||
---
|
||||
|
||||
## 1. Global Options
|
||||
|
||||
| Option | Environment Variable | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `-c, --config <PATH>` | `NX9_WG_CONFIG` | Path to configuration file (default: `/etc/nx9-wg/config.toml`) |
|
||||
| `-d, --data-dir <PATH>` | `NX9_WG_DATA_DIR` | Path to data directory (default: `/var/lib/nx9-wg`) |
|
||||
| `--database <PATH>` | `NX9_WG_DATABASE` | Specific SQLite database file path or URL |
|
||||
| `--format <FORMAT>` | N/A | Output format (`table`, `json`, `yaml`, `csv`, default: `table`) |
|
||||
| `--json` | N/A | Convenience flag for strict JSON output |
|
||||
| `-q, --quiet` | N/A | Suppress status and conversational messages |
|
||||
| `-v, --verbose` | N/A | Enable verbose trace logging |
|
||||
| `--log-level <LEVEL>` | `NX9_WG_LOG_LEVEL` | Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Command Groups Reference
|
||||
|
||||
### 1. `version`
|
||||
Displays version, build edition, architecture, OS platform, and security flags.
|
||||
```bash
|
||||
nx9-wg version
|
||||
nx9-wg version --format json
|
||||
```
|
||||
|
||||
### 2. `serve`
|
||||
Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler.
|
||||
```bash
|
||||
nx9-wg serve
|
||||
nx9-wg serve --bind 0.0.0.0:8080
|
||||
```
|
||||
|
||||
### 3. `init`
|
||||
Initializes the single administrator account across 7 bootstrap sources.
|
||||
```bash
|
||||
# Generated secure password:
|
||||
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||
|
||||
# Password via stdin:
|
||||
echo "StrongPassword123!" | nx9-wg init --password-stdin
|
||||
|
||||
# Password from file:
|
||||
nx9-wg init --password-file /run/secrets/admin_pw
|
||||
```
|
||||
|
||||
### 4. `system`
|
||||
- `nx9-wg system status`: System database statistics and object counts.
|
||||
- `nx9-wg system health`: System and SQLite connectivity health check.
|
||||
- `nx9-wg system info`: System platform, architecture, and runtime paths.
|
||||
- `nx9-wg system settings list`: List all key-value settings.
|
||||
- `nx9-wg system settings get <KEY>`: Query setting value.
|
||||
- `nx9-wg system settings set <KEY> <VALUE> [--secret]`: Save setting.
|
||||
- `nx9-wg system settings delete <KEY>`: Delete setting.
|
||||
|
||||
### 5. `admin`
|
||||
- `nx9-wg admin info`: Query administrator account metadata.
|
||||
- `nx9-wg admin password`: Change administrator password.
|
||||
- `nx9-wg admin token create <NAME> [--expires-in-days N] [--write-token-file PATH]`: Generate API token.
|
||||
- `nx9-wg admin token list`: List active API tokens.
|
||||
- `nx9-wg admin token revoke <TOKEN_ID>`: Revoke an API token.
|
||||
- `nx9-wg admin session list`: List active browser sessions.
|
||||
- `nx9-wg admin session revoke-all`: Invalidate all active sessions.
|
||||
|
||||
### 6. `interface`
|
||||
- `nx9-wg interface list`: List all WireGuard interfaces.
|
||||
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--port PORT] [--mtu MTU]`: Create interface.
|
||||
- `nx9-wg interface show <NAME_OR_ID>`: Show interface configuration.
|
||||
- `nx9-wg interface enable <NAME_OR_ID>`: Enable interface (`IFF_UP`).
|
||||
- `nx9-wg interface disable <NAME_OR_ID>`: Disable interface (`IFF_DOWN`).
|
||||
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface.
|
||||
|
||||
### 7. `peer`
|
||||
- `nx9-wg peer list [--interface NAME]`: List enrolled peers.
|
||||
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--profile PROFILE] [--mtu MTU]`: Enroll peer.
|
||||
- `nx9-wg peer show <PEER_ID>`: Show peer configuration.
|
||||
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>`: Toggle peer state.
|
||||
- `nx9-wg peer delete <PEER_ID>`: Delete peer.
|
||||
- `nx9-wg peer config <PEER_ID> [--device DEV] [--connection CONN]`: Output `.conf` client file.
|
||||
- `nx9-wg peer qr <PEER_ID>`: Render ASCII QR code in terminal for mobile scanning.
|
||||
|
||||
### 8. `network`
|
||||
- `nx9-wg network list`: List subnet networks.
|
||||
- `nx9-wg network create <NAME> --cidr <CIDR>`: Create network.
|
||||
- `nx9-wg network delete <NAME_OR_ID>`: Delete network.
|
||||
|
||||
### 9. `route`
|
||||
- `nx9-wg route list`: List routing table entries.
|
||||
- `nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]`: Add route.
|
||||
- `nx9-wg route delete <ROUTE_ID>`: Delete route.
|
||||
|
||||
### 10. `firewall`
|
||||
- `nx9-wg firewall list`: List nftables firewall rules.
|
||||
- `nx9-wg firewall add --name <NAME> [--protocol PROTO] [--port PORT] [--action ACTION] [--priority P]`: Add rule.
|
||||
- `nx9-wg firewall enable <RULE_ID>` / `disable <RULE_ID>`: Toggle rule.
|
||||
- `nx9-wg firewall delete <RULE_ID>`: Delete rule.
|
||||
|
||||
### 11. `nat`
|
||||
- `nx9-wg nat status`: Query NAT masquerade state.
|
||||
- `nx9-wg nat enable` / `disable`: Toggle outbound NAT masquerading.
|
||||
|
||||
### 12. `forwarding`
|
||||
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
|
||||
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP forwarding.
|
||||
|
||||
### 13. `reconcile`
|
||||
- `nx9-wg reconcile plan`: Calculate read-only drift between SQLite and kernel.
|
||||
- `nx9-wg reconcile apply`: Apply mutations across all execution planes.
|
||||
- `nx9-wg reconcile verify`: Post-apply verification check.
|
||||
|
||||
### 14. `backup`
|
||||
- `nx9-wg backup list`: List backup snapshots.
|
||||
- `nx9-wg backup create [--description DESC]`: Generate atomic SQLite online backup (`VACUUM INTO`).
|
||||
- `nx9-wg backup verify <PATH>`: Verify SQLite 3 header and SHA-256 checksum.
|
||||
- `nx9-wg backup restore <PATH_OR_ID>`: Restore database with automatic safety snapshot.
|
||||
|
||||
### 15. `audit`
|
||||
- `nx9-wg audit list [--limit N] [--event-type TYPE]`: List append-only audit trail records.
|
||||
|
||||
### 16. `live`
|
||||
- `nx9-wg live interfaces`: Query active Linux kernel WireGuard interfaces.
|
||||
- `nx9-wg live peers <IFACE>`: Query live peers, transfer bytes, and handshakes.
|
||||
- `nx9-wg live routes`: Query live kernel routing table.
|
||||
- `nx9-wg live nftables`: Query active `table inet nx9_wg` ruleset.
|
||||
|
||||
### 17. `diagnostics`
|
||||
- `nx9-wg diagnostics inspect all`: Inspect health across all 9 subsystems.
|
||||
- `nx9-wg diagnostics inspect <SUBSYSTEM>`: Inspect specific subsystem (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`).
|
||||
@@ -1,46 +0,0 @@
|
||||
# Quality Assurance & Testing Strategy
|
||||
|
||||
`nx9-wg` enforces a comprehensive, multi-tiered verification strategy designed to guarantee code correctness, memory safety, failure semantics, and secret protection.
|
||||
|
||||
---
|
||||
|
||||
## 1. Test Suite Summary & Quality Gates
|
||||
|
||||
| Tier | Test Suite / Check | Scope & Execution Target | Current Status |
|
||||
| :--- | :--- | :--- | :---: |
|
||||
| **Tier 1** | Code Formatting | `cargo fmt --all -- --check` | **PASS** (Zero diffs) |
|
||||
| **Tier 2** | Type & Borrow Check | `cargo check --workspace` | **PASS** (Zero errors) |
|
||||
| **Tier 3** | Workspace Unit Tests | `cargo test --workspace` | **PASS** (**91 / 91 passed**) |
|
||||
| **Tier 4** | Clippy Linter Check | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (Zero warnings) |
|
||||
| **Tier 5** | Release Compilation | `cargo build --release` | **PASS** (Clean build) |
|
||||
| **Tier 6** | Comprehensive CLI Suite | `LIVE=0 bash scripts/test-cli-comprehensive.sh` | **PASS** (**203 passed** / 7 skipped) |
|
||||
| **Tier 7** | Native Integration Suite | `LIVE=0 bash scripts/test-native-integration.sh` | **PASS** (**19 passed** / 1 skipped) |
|
||||
| **Tier 8** | Dedicated Live Kernel Suite | `LIVE=0 bash scripts/test-live-kernel.sh` | **PASS** (**23 passed** / 1 skipped) |
|
||||
| **Tier 9** | Subprocess Safety Audit | Automated source scan for `Command::new` | **PASS** (Zero subprocesses) |
|
||||
| **Tier 10** | Secret Leakage Audit | Automated scan for plaintext credentials | **PASS** (Zero secrets leaked) |
|
||||
| **Tier 11** | Release Package Check | Standalone archive extraction & verification | **PASS** (Independent execution) |
|
||||
|
||||
---
|
||||
|
||||
## 2. SAFE Mode (`LIVE=0`) vs Real-Kernel Mode (`LIVE=1`)
|
||||
|
||||
To guarantee safety when developing on unprivileged developer workstations:
|
||||
|
||||
### SAFE Mode (`LIVE=0` — Default)
|
||||
- Uses real in-memory SQLite stores and dry-run Netlink message builders.
|
||||
- Validates CLI parsers, JSON/YAML/CSV output formatters, route equality rules, and read-only reconciliation planning.
|
||||
- Automatically skips live kernel mutation steps that require root or `CAP_NET_ADMIN`.
|
||||
|
||||
### Real-Kernel Mode (`LIVE=1` — Dedicated Host Only)
|
||||
- Requires `root` or `CAP_NET_ADMIN` in a dedicated, disposable Linux VM.
|
||||
- Creates real kernel WireGuard interfaces (e.g. `nx9t...`), attaches IPv4/IPv6 addresses, installs routes in the kernel routing table, configures `table inet nx9_wg` in Netfilter, and validates live handshake telemetry.
|
||||
|
||||
---
|
||||
|
||||
## 3. Automated Subprocess & Secret Audits
|
||||
|
||||
Every verification run executes strict source-level security audits:
|
||||
|
||||
1. **Subprocess Audit**: Confirms zero instances of `std::process::Command`, `tokio::process::Command`, `Command::new`, or shell scripts in production Rust crates.
|
||||
2. **Secret Redaction Audit**: Confirms that password hashes, private keys, preshared keys, and token hashes are never printed in human-readable status outputs or logs.
|
||||
3. **Environment Audit**: Confirms that all recognized environment variables strictly observe the `NX9_WG_*` namespace.
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[Unit]
|
||||
Description=NX9 WireGuard Appliance Management Engine
|
||||
Documentation=https://github.com/nx9/nx9-wg
|
||||
Documentation=https://github.com/thakares/nx9-wg
|
||||
After=network.target network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 11 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 372 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 452 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 521 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 495 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 331 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 333 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 396 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 332 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 275 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 321 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 498 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 299 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 403 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 491 KiB |
Executable
+85
@@ -0,0 +1,85 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Source Repository Backup Tool
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Creates a timestamped, compressed source code backup archive while strictly
|
||||
# excluding build artifacts (target/) and temporary databases, while retaining
|
||||
# the full .git version history for recovery and auditability.
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - tar
|
||||
# - xz or gzip
|
||||
# - sha256sum
|
||||
#
|
||||
# BEHAVIOR:
|
||||
# - Non-destructive to the source tree.
|
||||
# - Verifies the integrity of the generated archive.
|
||||
# - Generates a companion .sha256 checksum file.
|
||||
#
|
||||
# USAGE:
|
||||
# bash scripts/backup-source.sh [DESTINATION_DIR]
|
||||
# ./scripts/backup-source.sh /backup/sources
|
||||
# ==============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
DEST_DIR="${1:-${ROOT_DIR}/..}"
|
||||
mkdir -p "${DEST_DIR}"
|
||||
DEST_DIR="$(cd "${DEST_DIR}" && pwd)"
|
||||
|
||||
PROJECT_NAME="nx9-wg"
|
||||
TIMESTAMP="$(date +%Y-%m-%d-%H%M%S)"
|
||||
ARCHIVE_BASE="${PROJECT_NAME}-source-${TIMESTAMP}"
|
||||
ARCHIVE_PATH="${DEST_DIR}/${ARCHIVE_BASE}.tar.xz"
|
||||
|
||||
log() {
|
||||
echo -e "\033[1;34m[BACKUP-SRC]\033[0m \033[1;37m$*\033[0m"
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "\033[1;32m[SUCCESS]\033[0m $*"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
log "Creating source backup of ${ROOT_DIR}..."
|
||||
log "Destination archive: ${ARCHIVE_PATH}"
|
||||
|
||||
# Create archive excluding heavy/temporary build outputs
|
||||
tar --exclude='target' \
|
||||
--exclude='.cargo' \
|
||||
--exclude='*.log' \
|
||||
--exclude='*.tmp' \
|
||||
--exclude='*.db' \
|
||||
--exclude='*.db-wal' \
|
||||
--exclude='*.db-shm' \
|
||||
--exclude='*.tar.gz' \
|
||||
--exclude='*.tar.xz' \
|
||||
-cJf "${ARCHIVE_PATH}" \
|
||||
-C "$(dirname "${ROOT_DIR}")" "$(basename "${ROOT_DIR}")" || error "Failed to create source archive."
|
||||
|
||||
# Verify archive integrity
|
||||
log "Verifying archive integrity..."
|
||||
tar -tf "${ARCHIVE_PATH}" >/dev/null || error "Archive verification check failed."
|
||||
|
||||
# Generate checksum
|
||||
(cd "${DEST_DIR}" && sha256sum "$(basename "${ARCHIVE_PATH}")" > "${ARCHIVE_BASE}.sha256")
|
||||
|
||||
ARCHIVE_SIZE="$(du -h "${ARCHIVE_PATH}" | cut -f1)"
|
||||
ARCHIVE_SHA="$(cat "${DEST_DIR}/${ARCHIVE_BASE}.sha256" | awk '{print $1}')"
|
||||
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;32m SOURCE BACKUP COMPLETED SUCCESSFULLY!\033[0m"
|
||||
echo -e "================================================================="
|
||||
echo " Archive Path: ${ARCHIVE_PATH}"
|
||||
echo " Archive Size: ${ARCHIVE_SIZE}"
|
||||
echo " SHA-256: ${ARCHIVE_SHA}"
|
||||
echo " Checksum File:${DEST_DIR}/${ARCHIVE_BASE}.sha256"
|
||||
echo -e "=================================================================\n"
|
||||
Executable
+85
@@ -0,0 +1,85 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Production Release Builder
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Runs release quality gates and compiles an optimized release binary:
|
||||
# 1. Format verification
|
||||
# 2. Check & Clippy (-D warnings)
|
||||
# 3. Full workspace test suite
|
||||
# 4. Release build (cargo build --release --workspace)
|
||||
# 5. Artifact verification (binary size, permissions, SHA-256)
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - Rust toolchain (stable)
|
||||
# - Linux C build tools (libsqlite3 / pkg-config / ldd)
|
||||
#
|
||||
# BEHAVIOR:
|
||||
# - Non-destructive to existing deployments.
|
||||
# - Does NOT run 'cargo clean' to prevent accidental removal of release artifacts.
|
||||
# - Produces target/release/nx9-wg.
|
||||
#
|
||||
# USAGE:
|
||||
# bash scripts/build-release.sh
|
||||
# ./scripts/build-release.sh
|
||||
# ==============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
log() {
|
||||
echo -e "\n\033[1;34m[RELEASE-BUILD]\033[0m \033[1;37m$*\033[0m"
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "\033[1;32m[PASS]\033[0m $*"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
cd "${ROOT_DIR}"
|
||||
|
||||
log "1/4 Verifying code formatting..."
|
||||
cargo fmt --all -- --check || error "Formatting verification failed."
|
||||
success "Formatting verified."
|
||||
|
||||
log "2/4 Running compiler and Clippy checks..."
|
||||
cargo check --workspace --all-targets || error "Cargo check failed."
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings || error "Clippy check failed."
|
||||
success "Lint checks passed with 0 warnings."
|
||||
|
||||
log "3/4 Running full workspace test suite..."
|
||||
cargo test --workspace --all-targets || error "Workspace test suite failed."
|
||||
success "All unit and integration tests passed."
|
||||
|
||||
log "4/4 Compiling optimized release binary (cargo build --release --workspace)..."
|
||||
cargo build --release --workspace || error "Release build failed."
|
||||
|
||||
TARGET_BIN="${ROOT_DIR}/target/release/nx9-wg"
|
||||
|
||||
if [[ ! -f "${TARGET_BIN}" ]]; then
|
||||
error "Expected release binary not found at ${TARGET_BIN}"
|
||||
fi
|
||||
|
||||
if [[ ! -x "${TARGET_BIN}" ]]; then
|
||||
error "Release binary is not executable at ${TARGET_BIN}"
|
||||
fi
|
||||
|
||||
BIN_SIZE="$(du -h "${TARGET_BIN}" | cut -f1)"
|
||||
BIN_SHA="$(sha256sum "${TARGET_BIN}" | awk '{print $1}')"
|
||||
BIN_DATE="$(date -r "${TARGET_BIN}" '+%Y-%m-%d %H:%M:%S')"
|
||||
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;32m RELEASE BUILD SUCCESSFUL!\033[0m"
|
||||
echo -e "================================================================="
|
||||
echo " Binary Path: ${TARGET_BIN}"
|
||||
echo " Binary Size: ${BIN_SIZE}"
|
||||
echo " Timestamp: ${BIN_DATE}"
|
||||
echo " SHA-256: ${BIN_SHA}"
|
||||
echo " Version: $("${TARGET_BIN}" version | head -n 1)"
|
||||
echo -e "=================================================================\n"
|
||||
Executable
+216
@@ -0,0 +1,216 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Production Deployment Tool
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Deploys the compiled release binary target/release/nx9-wg to the production
|
||||
# system path (/usr/local/bin/nx9-wg) with validated controlled replacement,
|
||||
# automatic backup of the previous binary, and controlled systemd service management.
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - Root privileges (or sudo)
|
||||
# - Pre-compiled release binary at target/release/nx9-wg
|
||||
# - Linux with systemd
|
||||
#
|
||||
# SAFETY INVARIANTS:
|
||||
# - Never overwrites the existing production binary without creating a timestamped backup.
|
||||
# - Never modifies or overwrites database files (/var/lib/nx9-wg/nx9-wg.db).
|
||||
# - Never deletes WireGuard interfaces or kills processes automatically on port conflict.
|
||||
# - Uses the standard 'install' command for controlled binary replacement and strict permissions.
|
||||
# - Returns non-zero exit code on failure.
|
||||
#
|
||||
# USAGE:
|
||||
# sudo bash scripts/deploy.sh [OPTIONS]
|
||||
#
|
||||
# OPTIONS:
|
||||
# --no-restart Install binary without restarting nx9-wg.service
|
||||
# --dry-run Simulate deployment actions without applying changes
|
||||
# -h, --help Show this help message
|
||||
# ==============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
SOURCE_BIN="${ROOT_DIR}/target/release/nx9-wg"
|
||||
DEST_BIN="/usr/local/bin/nx9-wg"
|
||||
CONF_DIR="/etc/nx9-wg"
|
||||
DATA_DIR="/var/lib/nx9-wg"
|
||||
BACKUP_DIR="${DATA_DIR}/backups"
|
||||
LOG_DIR="/var/log/nx9-wg"
|
||||
SERVICE_DEST="/etc/systemd/system/nx9-wg.service"
|
||||
SERVICE_SRC="${ROOT_DIR}/nx9-wg.service"
|
||||
|
||||
DRY_RUN=0
|
||||
NO_RESTART=0
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
nx9-wg Production Deployment Tool
|
||||
|
||||
Usage:
|
||||
sudo bash scripts/deploy.sh [OPTIONS]
|
||||
|
||||
Options:
|
||||
--no-restart Install binary without restarting nx9-wg.service
|
||||
--dry-run Simulate deployment actions without applying changes
|
||||
-h, --help Show this help message
|
||||
EOF
|
||||
exit 0
|
||||
}
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--dry-run)
|
||||
DRY_RUN=1
|
||||
shift
|
||||
;;
|
||||
--no-restart)
|
||||
NO_RESTART=1
|
||||
shift
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
;;
|
||||
*)
|
||||
echo "Unknown option: $1" >&2
|
||||
usage
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
log() {
|
||||
echo -e "\033[1;34m[DEPLOY]\033[0m \033[1;37m$*\033[0m"
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "\033[1;32m[SUCCESS]\033[0m $*"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "\033[1;33m[WARN]\033[0m $*"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
# 1. Privilege Verification
|
||||
if [[ "${EUID}" -ne 0 && "${DRY_RUN}" -eq 0 ]]; then
|
||||
error "Deployment must be run as root (or via sudo)."
|
||||
fi
|
||||
|
||||
# 2. Source Binary Verification
|
||||
if [[ ! -f "${SOURCE_BIN}" ]]; then
|
||||
error "Source binary not found at ${SOURCE_BIN}. Run 'bash scripts/build-release.sh' first."
|
||||
fi
|
||||
|
||||
if [[ ! -x "${SOURCE_BIN}" ]]; then
|
||||
error "Source binary at ${SOURCE_BIN} is not executable."
|
||||
fi
|
||||
|
||||
SOURCE_SIZE="$(du -h "${SOURCE_BIN}" | cut -f1)"
|
||||
SOURCE_SHA="$(sha256sum "${SOURCE_BIN}" | awk '{print $1}')"
|
||||
SOURCE_DATE="$(date -r "${SOURCE_BIN}" '+%Y-%m-%d %H:%M:%S')"
|
||||
|
||||
log "Source binary verified:"
|
||||
echo " Path: ${SOURCE_BIN}"
|
||||
echo " Size: ${SOURCE_SIZE}"
|
||||
echo " Timestamp: ${SOURCE_DATE}"
|
||||
echo " SHA-256: ${SOURCE_SHA}"
|
||||
|
||||
# 3. Create Filesystem Layout with Strict Permissions
|
||||
log "Ensuring directory permissions..."
|
||||
if [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||
install -d -m 0750 "${CONF_DIR}"
|
||||
install -d -m 0700 "${DATA_DIR}"
|
||||
install -d -m 0700 "${BACKUP_DIR}"
|
||||
install -d -m 0750 "${LOG_DIR}"
|
||||
else
|
||||
echo " [DRY-RUN] install -d directories: ${CONF_DIR}, ${DATA_DIR}, ${BACKUP_DIR}, ${LOG_DIR}"
|
||||
fi
|
||||
|
||||
# 4. Backup Existing Production Binary
|
||||
if [[ -f "${DEST_BIN}" ]]; then
|
||||
TIMESTAMP="$(date +%Y%m%d_%H%M%S)"
|
||||
BACKUP_DEST="${DEST_BIN}.backup.${TIMESTAMP}"
|
||||
log "Backing up active binary to ${BACKUP_DEST}..."
|
||||
if [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||
cp -p "${DEST_BIN}" "${BACKUP_DEST}"
|
||||
chmod 0755 "${BACKUP_DEST}"
|
||||
success "Backup created: ${BACKUP_DEST}"
|
||||
else
|
||||
echo " [DRY-RUN] cp -p ${DEST_BIN} ${BACKUP_DEST}"
|
||||
fi
|
||||
fi
|
||||
|
||||
# 5. Controlled Installation of New Binary
|
||||
log "Installing new release binary to ${DEST_BIN}..."
|
||||
if [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||
install -m 0755 "${SOURCE_BIN}" "${DEST_BIN}"
|
||||
success "Binary installed to ${DEST_BIN}"
|
||||
else
|
||||
echo " [DRY-RUN] install -m 0755 ${SOURCE_BIN} ${DEST_BIN}"
|
||||
fi
|
||||
|
||||
# 6. Install or Update systemd Service Unit
|
||||
if [[ -f "${SERVICE_SRC}" && -d "/etc/systemd/system" ]]; then
|
||||
log "Installing/updating systemd service unit..."
|
||||
if [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||
install -m 0644 "${SERVICE_SRC}" "${SERVICE_DEST}"
|
||||
if command -v systemctl >/dev/null 2>&1; then
|
||||
systemctl daemon-reload
|
||||
fi
|
||||
success "systemd service unit updated at ${SERVICE_DEST}"
|
||||
else
|
||||
echo " [DRY-RUN] install -m 0644 ${SERVICE_SRC} ${SERVICE_DEST}"
|
||||
fi
|
||||
fi
|
||||
|
||||
# 7. Safe Socket Inspection
|
||||
if command -v ss >/dev/null 2>&1; then
|
||||
log "Inspecting active UDP listen sockets without modifying the host..."
|
||||
ACTIVE_UDP_SOCKETS="$(ss -lunp 2>/dev/null | grep -v '^State' || true)"
|
||||
if [[ -n "${ACTIVE_UDP_SOCKETS}" ]]; then
|
||||
echo "${ACTIVE_UDP_SOCKETS}"
|
||||
else
|
||||
echo " No UDP listeners reported by ss."
|
||||
fi
|
||||
fi
|
||||
|
||||
# 8. Service Restart & Verification
|
||||
if [[ "${NO_RESTART}" -eq 0 && "${DRY_RUN}" -eq 0 ]]; then
|
||||
if command -v systemctl >/dev/null 2>&1; then
|
||||
log "Restarting nx9-wg.service..."
|
||||
systemctl restart nx9-wg || error "Failed to restart nx9-wg service."
|
||||
sleep 1
|
||||
|
||||
if systemctl is-active --quiet nx9-wg; then
|
||||
success "nx9-wg.service is active and running."
|
||||
else
|
||||
warn "nx9-wg.service is not in active state. Inspecting journal..."
|
||||
journalctl -u nx9-wg -n 20 --no-pager || true
|
||||
error "Service failed to start."
|
||||
fi
|
||||
fi
|
||||
elif [[ "${NO_RESTART}" -eq 1 ]]; then
|
||||
log "Skipping service restart as requested (--no-restart)."
|
||||
fi
|
||||
|
||||
# 9. Final Deployment Verification
|
||||
log "Verifying deployed binary version..."
|
||||
if [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||
DEPLOYED_VER="$("${DEST_BIN}" version | head -n 1)"
|
||||
success "Deployed binary active: ${DEPLOYED_VER}"
|
||||
fi
|
||||
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;32m DEPLOYMENT COMPLETED SUCCESSFULLY!\033[0m"
|
||||
echo -e "================================================================="
|
||||
echo " Installed Binary: ${DEST_BIN}"
|
||||
echo " Configuration: ${CONF_DIR}/config.toml"
|
||||
echo " Database: ${DATA_DIR}/nx9-wg.db"
|
||||
echo " Service Status: systemctl status nx9-wg"
|
||||
echo -e "=================================================================\n"
|
||||
Executable
+155
@@ -0,0 +1,155 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Production Diagnostic Collector
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Collects a comprehensive, non-destructive diagnostic snapshot across both
|
||||
# desired SQLite state and live Linux kernel networking state:
|
||||
# - Systemd service & journal log health
|
||||
# - UDP socket bindings & conflict inspection
|
||||
# - Kernel IP link, address, and routing status
|
||||
# - Kernel WireGuard link/interface and peer telemetry (via secret-safe 'wg show')
|
||||
# - Netfilter / nftables ruleset in 'table inet nx9_wg'
|
||||
# - Linux sysctl IP packet forwarding
|
||||
# - Application-level diagnostic subsystem inspections
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - Root privileges (recommended for kernel/socket inspection, or run via sudo)
|
||||
#
|
||||
# SECURITY INVARIANTS:
|
||||
# - NEVER calls 'wg showconf' (which prints private keys in cleartext).
|
||||
# - Relies exclusively on 'wg show' which masks private keys.
|
||||
# - Strictly non-destructive: only performs read-only inspections.
|
||||
#
|
||||
# USAGE:
|
||||
# sudo bash scripts/diagnose.sh
|
||||
# ./scripts/diagnose.sh
|
||||
# ==============================================================================
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
BIN="/usr/local/bin/nx9-wg"
|
||||
if [[ ! -x "${BIN}" ]]; then
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
if [[ -x "${ROOT_DIR}/target/release/nx9-wg" ]]; then
|
||||
BIN="${ROOT_DIR}/target/release/nx9-wg"
|
||||
elif [[ -x "${ROOT_DIR}/target/debug/nx9-wg" ]]; then
|
||||
BIN="${ROOT_DIR}/target/debug/nx9-wg"
|
||||
fi
|
||||
fi
|
||||
|
||||
section() {
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;36m>> $*\033[0m"
|
||||
echo -e "================================================================="
|
||||
}
|
||||
|
||||
subsection() {
|
||||
echo -e "\n\033[1;33m--- $*\033[0m"
|
||||
}
|
||||
|
||||
section "1. System & Host Runtime Environment"
|
||||
echo "Timestamp: $(date --iso-8601=seconds)"
|
||||
echo "Hostname: $(hostname)"
|
||||
echo "Kernel: $(uname -r)"
|
||||
echo "Architecture: $(uname -m)"
|
||||
echo "Uptime: $(uptime -p 2>/dev/null || uptime)"
|
||||
if [[ -x "${BIN}" ]]; then
|
||||
echo "nx9-wg: $("${BIN}" version | head -n 1)"
|
||||
else
|
||||
echo "nx9-wg: Binary not found"
|
||||
fi
|
||||
|
||||
section "2. Systemd Service & Process State"
|
||||
if command -v systemctl >/dev/null 2>&1; then
|
||||
subsection "Service Status (nx9-wg.service)"
|
||||
systemctl status nx9-wg --no-pager -l || true
|
||||
|
||||
subsection "Recent Journalctl Logs (Last 30 entries)"
|
||||
journalctl -u nx9-wg -n 30 --no-pager || true
|
||||
else
|
||||
echo "systemctl not available on this host."
|
||||
fi
|
||||
|
||||
section "3. UDP Sockets & Listen Port Inspection"
|
||||
if command -v ss >/dev/null 2>&1; then
|
||||
subsection "Active UDP Listen Sockets (ss -lunp)"
|
||||
ss -lunp 2>/dev/null || true
|
||||
else
|
||||
echo "ss utility not found."
|
||||
fi
|
||||
|
||||
section "4. Linux Network Interfaces & Addresses"
|
||||
if command -v ip >/dev/null 2>&1; then
|
||||
subsection "Brief Interface State (ip -br link)"
|
||||
ip -br link show || true
|
||||
|
||||
subsection "Brief IPv4 / IPv6 Addresses (ip -br addr)"
|
||||
ip -br addr show || true
|
||||
|
||||
subsection "WireGuard Interface Addresses"
|
||||
if command -v wg >/dev/null 2>&1; then
|
||||
WG_INTERFACES="$(wg show interfaces 2>/dev/null || true)"
|
||||
if [[ -n "${WG_INTERFACES}" ]]; then
|
||||
for WG_IFACE in ${WG_INTERFACES}; do
|
||||
echo "Interface: ${WG_IFACE}"
|
||||
ip addr show dev "${WG_IFACE}" 2>/dev/null || true
|
||||
done
|
||||
else
|
||||
echo "No WireGuard interfaces reported by the kernel."
|
||||
fi
|
||||
else
|
||||
echo "wg utility not found; WireGuard interface-specific address inspection skipped."
|
||||
fi
|
||||
else
|
||||
echo "ip utility not found."
|
||||
fi
|
||||
|
||||
section "5. Kernel Routing Table"
|
||||
if command -v ip >/dev/null 2>&1; then
|
||||
subsection "IPv4 Routes (ip route show)"
|
||||
ip route show || true
|
||||
|
||||
subsection "IPv6 Routes (ip -6 route show)"
|
||||
ip -6 route show || true
|
||||
fi
|
||||
|
||||
section "6. Kernel WireGuard Telemetry (Secret-Safe 'wg show')"
|
||||
if command -v wg >/dev/null 2>&1; then
|
||||
wg show 2>&1 || echo "wg show returned non-zero (may require root privileges)."
|
||||
else
|
||||
echo "wg utility not found on host."
|
||||
fi
|
||||
|
||||
section "7. Netfilter / nftables Firewall State (table inet nx9_wg)"
|
||||
if command -v nft >/dev/null 2>&1; then
|
||||
nft list table inet nx9_wg 2>/dev/null || echo "nftables table 'inet nx9_wg' not present."
|
||||
else
|
||||
echo "nft utility not found on host."
|
||||
fi
|
||||
|
||||
section "8. IP Packet Forwarding (Kernel Sysctl)"
|
||||
echo -n "net.ipv4.ip_forward: "
|
||||
cat /proc/sys/net/ipv4/ip_forward 2>/dev/null || echo "Unable to read /proc/sys/net/ipv4/ip_forward"
|
||||
echo -n "net.ipv6.conf.all.forwarding: "
|
||||
cat /proc/sys/net/ipv6/conf/all/forwarding 2>/dev/null || echo "Unable to read /proc/sys/net/ipv6/conf/all/forwarding"
|
||||
|
||||
section "9. Application Desired State & Health Checks"
|
||||
if [[ -x "${BIN}" ]]; then
|
||||
subsection "Appliance Health Check"
|
||||
"${BIN}" system health 2>&1 || true
|
||||
|
||||
subsection "All Subsystems Diagnostics"
|
||||
"${BIN}" diagnostics all 2>&1 || true
|
||||
|
||||
subsection "Reconciliation Drift Status"
|
||||
"${BIN}" reconcile status 2>&1 || true
|
||||
|
||||
subsection "Live WireGuard Interface Status"
|
||||
"${BIN}" live interface list 2>&1 || true
|
||||
else
|
||||
echo "nx9-wg binary not executable; skipping application-level diagnostics."
|
||||
fi
|
||||
|
||||
section "Diagnostic Collection Complete"
|
||||
Regular → Executable
+1
-1
@@ -161,7 +161,7 @@ fi
|
||||
if [[ "${NO_INIT}" -eq 0 && "${DRY_RUN}" -eq 0 ]]; then
|
||||
PW_FILE="${DATA_DIR}/admin-initial-password"
|
||||
log "Checking administrator account initialization..."
|
||||
if "${BIN_DIR}/nx9-wg" --config "${CONF_DIR}/config.toml" --data-dir "${DATA_DIR}" admin info >/dev/null 2>&1; then
|
||||
if "${BIN_DIR}/nx9-wg" --config "${CONF_DIR}/config.toml" --data-dir "${DATA_DIR}" admin status >/dev/null 2>&1; then
|
||||
log "Administrator account already initialized in database."
|
||||
else
|
||||
log "Initializing administrator account with secure random credentials..."
|
||||
|
||||
Regular → Executable
+7
-1
@@ -12,7 +12,11 @@ set -euo pipefail
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
VERSION="$(grep -m 1 '^version = ' "${ROOT_DIR}/Cargo.toml" | cut -d '"' -f 2)"
|
||||
VERSION="$(sed -n '/^[[:space:]]*\[workspace\.package\]/,/^[[:space:]]*\[/ { /^[[:space:]]*version[[:space:]]*=/ { s/.*= *"\([^"]*\)".*/\1/p; q; } }' "${ROOT_DIR}/Cargo.toml")"
|
||||
if [[ -z "${VERSION}" ]]; then
|
||||
echo "ERROR: unable to determine workspace package version from Cargo.toml" >&2
|
||||
exit 1
|
||||
fi
|
||||
ARCH="$(uname -m)"
|
||||
OS="linux"
|
||||
|
||||
@@ -22,6 +26,7 @@ STAGE_DIR="${DIST_DIR}/${PACKAGE_NAME}"
|
||||
|
||||
echo "================================================================="
|
||||
echo " Packaging nx9-wg Release: ${PACKAGE_NAME}"
|
||||
echo " Workspace version: ${VERSION}"
|
||||
echo "================================================================="
|
||||
|
||||
# 1. Ensure release binary is compiled
|
||||
@@ -44,6 +49,7 @@ install -m 0755 "${ROOT_DIR}/scripts/uninstall.sh" "${STAGE_DIR}/uninstall.sh"
|
||||
install -m 0644 "${ROOT_DIR}/README.md" "${STAGE_DIR}/README.md"
|
||||
install -m 0644 "${ROOT_DIR}/LICENSE-MIT" "${STAGE_DIR}/LICENSE-MIT"
|
||||
install -m 0644 "${ROOT_DIR}/LICENSE-APACHE" "${STAGE_DIR}/LICENSE-APACHE"
|
||||
install -m 0644 "${ROOT_DIR}/CHANGELOG.md" "${STAGE_DIR}/CHANGELOG.md"
|
||||
|
||||
# Copy documentation
|
||||
cp -r "${ROOT_DIR}/docs/"* "${STAGE_DIR}/docs/"
|
||||
|
||||
Executable
+174
@@ -0,0 +1,174 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Production Rollback Tool
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Rolls back the active production binary (/usr/local/bin/nx9-wg) to the most
|
||||
# recent (or specified) backup binary created during previous deployments.
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - Root privileges (or sudo)
|
||||
# - At least one backup binary at /usr/local/bin/nx9-wg.backup.*
|
||||
#
|
||||
# SAFETY INVARIANTS:
|
||||
# - Never modifies or deletes the SQLite database.
|
||||
# - Restores executable permissions (0755) and root ownership.
|
||||
# - Confirms service restoration and binary version after rollback.
|
||||
#
|
||||
# USAGE:
|
||||
# sudo bash scripts/rollback.sh [OPTIONS] [SPECIFIC_BACKUP_PATH]
|
||||
#
|
||||
# OPTIONS:
|
||||
# -y, --yes Skip confirmation prompt
|
||||
# -l, --list List available backup binaries and exit
|
||||
# -h, --help Show this help message
|
||||
# ==============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
BIN_DIR="/usr/local/bin"
|
||||
ACTIVE_BIN="${BIN_DIR}/nx9-wg"
|
||||
ASSUME_YES=0
|
||||
LIST_ONLY=0
|
||||
SPECIFIED_BACKUP=""
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
nx9-wg Production Rollback Tool
|
||||
|
||||
Usage:
|
||||
sudo bash scripts/rollback.sh [OPTIONS] [BACKUP_FILE]
|
||||
|
||||
Options:
|
||||
-y, --yes Skip interactive confirmation prompt
|
||||
-l, --list List available backup binaries and exit
|
||||
-h, --help Show this help message
|
||||
EOF
|
||||
exit 0
|
||||
}
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-y|--yes)
|
||||
ASSUME_YES=1
|
||||
shift
|
||||
;;
|
||||
-l|--list)
|
||||
LIST_ONLY=1
|
||||
shift
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
;;
|
||||
-*)
|
||||
echo "Unknown option: $1" >&2
|
||||
usage
|
||||
;;
|
||||
*)
|
||||
SPECIFIED_BACKUP="$1"
|
||||
shift
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
log() {
|
||||
echo -e "\033[1;34m[ROLLBACK]\033[0m \033[1;37m$*\033[0m"
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "\033[1;32m[SUCCESS]\033[0m $*"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "\033[1;33m[WARN]\033[0m $*"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
# 1. Privilege Verification (unless list only)
|
||||
if [[ "${EUID}" -ne 0 && "${LIST_ONLY}" -eq 0 ]]; then
|
||||
error "Rollback must be run as root (or via sudo)."
|
||||
fi
|
||||
|
||||
# 2. Discover Available Backups
|
||||
BACKUPS=($(ls -1t "${ACTIVE_BIN}".backup.* 2>/dev/null || true))
|
||||
|
||||
if [[ "${#BACKUPS[@]}" -eq 0 ]]; then
|
||||
error "No backup binaries found in ${BIN_DIR} matching nx9-wg.backup.*"
|
||||
fi
|
||||
|
||||
if [[ "${LIST_ONLY}" -eq 1 ]]; then
|
||||
echo "Available production backup binaries in ${BIN_DIR}:"
|
||||
for b in "${BACKUPS[@]}"; do
|
||||
SIZE="$(du -h "$b" | cut -f1)"
|
||||
DATE="$(date -r "$b" '+%Y-%m-%d %H:%M:%S')"
|
||||
echo " $b (${SIZE}, ${DATE})"
|
||||
done
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# 3. Select Target Backup
|
||||
TARGET_BACKUP=""
|
||||
if [[ -n "${SPECIFIED_BACKUP}" ]]; then
|
||||
if [[ -f "${SPECIFIED_BACKUP}" ]]; then
|
||||
TARGET_BACKUP="${SPECIFIED_BACKUP}"
|
||||
elif [[ -f "${BIN_DIR}/${SPECIFIED_BACKUP}" ]]; then
|
||||
TARGET_BACKUP="${BIN_DIR}/${SPECIFIED_BACKUP}"
|
||||
else
|
||||
error "Specified backup file not found: ${SPECIFIED_BACKUP}"
|
||||
fi
|
||||
else
|
||||
TARGET_BACKUP="${BACKUPS[0]}"
|
||||
fi
|
||||
|
||||
log "Selected rollback target: ${TARGET_BACKUP}"
|
||||
BACKUP_SIZE="$(du -h "${TARGET_BACKUP}" | cut -f1)"
|
||||
BACKUP_DATE="$(date -r "${TARGET_BACKUP}" '+%Y-%m-%d %H:%M:%S')"
|
||||
echo " Size: ${BACKUP_SIZE}"
|
||||
echo " Timestamp: ${BACKUP_DATE}"
|
||||
|
||||
# 4. Confirmation Prompt
|
||||
if [[ "${ASSUME_YES}" -eq 0 ]]; then
|
||||
echo -e "\n\033[1;33mAre you sure you want to replace active binary ${ACTIVE_BIN} with ${TARGET_BACKUP}?\033[0m"
|
||||
read -r -p "Type 'yes' to proceed with rollback: " CONFIRM
|
||||
if [[ "${CONFIRM}" != "yes" ]]; then
|
||||
error "Rollback aborted by user."
|
||||
fi
|
||||
fi
|
||||
|
||||
# 5. Execute Rollback
|
||||
if command -v systemctl >/dev/null 2>&1; then
|
||||
if systemctl is-active --quiet nx9-wg 2>/dev/null; then
|
||||
log "Stopping nx9-wg service..."
|
||||
systemctl stop nx9-wg || true
|
||||
fi
|
||||
fi
|
||||
|
||||
log "Restoring binary from ${TARGET_BACKUP} to ${ACTIVE_BIN}..."
|
||||
install -m 0755 "${TARGET_BACKUP}" "${ACTIVE_BIN}"
|
||||
|
||||
# 6. Restart Service
|
||||
if command -v systemctl >/dev/null 2>&1; then
|
||||
log "Starting nx9-wg service..."
|
||||
systemctl start nx9-wg || error "Failed to restart nx9-wg service after rollback."
|
||||
sleep 1
|
||||
|
||||
if systemctl is-active --quiet nx9-wg; then
|
||||
success "nx9-wg.service is active and running."
|
||||
else
|
||||
warn "nx9-wg.service is not active. Checking logs:"
|
||||
journalctl -u nx9-wg -n 20 --no-pager || true
|
||||
error "Service failed to become active after rollback."
|
||||
fi
|
||||
fi
|
||||
|
||||
# 7. Verify Restored Version
|
||||
RESTORED_VER="$("${ACTIVE_BIN}" version | head -n 1)"
|
||||
success "Rollback successful. Active binary version: ${RESTORED_VER}"
|
||||
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;32m PRODUCTION ROLLBACK COMPLETED SUCCESSFULLY!\033[0m"
|
||||
echo -e "=================================================================\n"
|
||||
@@ -154,9 +154,14 @@ log_pass "Pre-flight baseline captured in ${BASELINE_DIR}"
|
||||
# ----------------------------------------------------------------------------
|
||||
section "02 — SQLite Store Initialization"
|
||||
|
||||
TEMP_ADMIN_PW="$(head -c 24 /dev/urandom | base64 | tr -dc 'A-Za-z0-9!@#%^&*_-' | head -c 20)"
|
||||
PW_FILE="${TEST_ROOT}/admin_pw.txt"
|
||||
echo -n "${TEMP_ADMIN_PW}" > "${PW_FILE}"
|
||||
chmod 0600 "${PW_FILE}"
|
||||
|
||||
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" init \
|
||||
--username "admin" \
|
||||
--password "AdminPassword123!" >/dev/null
|
||||
--password-file "${PW_FILE}" >/dev/null
|
||||
|
||||
if [[ -f "${DB_PATH}" ]]; then
|
||||
log_pass "SQLite authoritative store created and migrated"
|
||||
@@ -288,7 +293,7 @@ all_dumps="${TEST_ROOT}/all_dumps.txt"
|
||||
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan >> "${all_dumps}" 2>&1 || true
|
||||
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json diagnostics all >> "${all_dumps}" 2>&1 || true
|
||||
|
||||
if grep -q "AdminPassword123!" "${all_dumps}"; then
|
||||
if grep -F -q "${TEMP_ADMIN_PW}" "${all_dumps}"; then
|
||||
log_fail "Plaintext administrator password found in command output"
|
||||
else
|
||||
log_pass "Zero plaintext passwords leaked in CLI/diagnostics output"
|
||||
|
||||
Regular → Executable
-1
@@ -119,4 +119,3 @@ else
|
||||
fi
|
||||
|
||||
log "nx9-wg uninstalled successfully."
|
||||
EOF
|
||||
Executable
+83
@@ -0,0 +1,83 @@
|
||||
#!/usr/bin/env bash
|
||||
# ==============================================================================
|
||||
# nx9-wg Development Verification Gate
|
||||
# ==============================================================================
|
||||
# PURPOSE:
|
||||
# Executes the full development and release quality gate suite in sequence:
|
||||
# 1. Formatting verification (cargo fmt --all -- --check)
|
||||
# 2. Workspace compilation (cargo check --workspace --all-targets)
|
||||
# 3. Strict Clippy linting (cargo clippy --workspace --all-targets --all-features -- -D warnings)
|
||||
# 4. Complete workspace unit & integration tests (cargo test --workspace --all-targets)
|
||||
# 5. Comprehensive CLI verification (scripts/test-cli-comprehensive.sh)
|
||||
#
|
||||
# PREREQUISITES:
|
||||
# - Rust toolchain (cargo, rustc, rustfmt, clippy)
|
||||
#
|
||||
# BEHAVIOR:
|
||||
# - 100% Non-destructive.
|
||||
# - Returns exit code 0 if all checks pass.
|
||||
# - Returns non-zero exit code immediately on any failure.
|
||||
#
|
||||
# USAGE:
|
||||
# bash scripts/verify.sh
|
||||
# ./scripts/verify.sh
|
||||
# ==============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
log() {
|
||||
echo -e "\n\033[1;34m[VERIFY]\033[0m \033[1;37m$*\033[0m"
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "\033[1;32m[PASS]\033[0m $*"
|
||||
}
|
||||
|
||||
error() {
|
||||
echo -e "\033[1;31m[FAIL]\033[0m $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
cd "${ROOT_DIR}"
|
||||
|
||||
log "1/5 Checking code formatting..."
|
||||
if cargo fmt --all -- --check; then
|
||||
success "Code formatting is clean."
|
||||
else
|
||||
error "Formatting check failed. Run 'cargo fmt --all' to fix."
|
||||
fi
|
||||
|
||||
log "2/5 Compiling workspace targets..."
|
||||
if cargo check --workspace --all-targets; then
|
||||
success "Workspace compilation check passed."
|
||||
else
|
||||
error "Compilation check failed."
|
||||
fi
|
||||
|
||||
log "3/5 Running Clippy with -D warnings..."
|
||||
if cargo clippy --workspace --all-targets --all-features -- -D warnings; then
|
||||
success "Clippy linting passed with 0 warnings."
|
||||
else
|
||||
error "Clippy check failed."
|
||||
fi
|
||||
|
||||
log "4/5 Running complete workspace test suite..."
|
||||
if cargo test --workspace --all-targets; then
|
||||
success "All workspace unit and integration tests passed."
|
||||
else
|
||||
error "Workspace test suite failed."
|
||||
fi
|
||||
|
||||
log "5/5 Running comprehensive CLI verification..."
|
||||
if bash "${SCRIPT_DIR}/test-cli-comprehensive.sh"; then
|
||||
success "CLI comprehensive verification suite passed."
|
||||
else
|
||||
error "CLI verification failed."
|
||||
fi
|
||||
|
||||
echo -e "\n================================================================="
|
||||
echo -e "\033[1;32m ALL VERIFICATION QUALITY GATES PASSED SUCCESSFULLY!\033[0m"
|
||||
echo -e "=================================================================\n"
|
||||
+100
-23
@@ -23,9 +23,11 @@ use nx9_wg_core::validation::{
|
||||
validate_port_spec,
|
||||
};
|
||||
use nx9_wg_db::Store;
|
||||
#[allow(unused_imports)]
|
||||
use nx9_wg_network::{
|
||||
IpForwardingStatus, NativeLinuxNetworkEngine, NetworkEngine, SimulatedNetworkEngine,
|
||||
};
|
||||
#[allow(unused_imports)]
|
||||
use nx9_wireguard::{
|
||||
ClientConfigBuilder, NativeLinuxWireGuardEngine, SimulatedWireGuardEngine, WireGuardEngine,
|
||||
generate_qr_ascii, generate_qr_png_bytes, generate_qr_svg,
|
||||
@@ -509,6 +511,8 @@ enum PeerSubcommands {
|
||||
mtu: Option<u16>,
|
||||
#[arg(long, help = "Explicit client profile ID")]
|
||||
profile: Option<String>,
|
||||
#[arg(long, help = "WireGuard server endpoint host or IP")]
|
||||
endpoint: Option<String>,
|
||||
#[arg(short, long, help = "Write configuration to file")]
|
||||
output: Option<PathBuf>,
|
||||
},
|
||||
@@ -533,6 +537,8 @@ enum PeerSubcommands {
|
||||
mtu: Option<u16>,
|
||||
#[arg(long, help = "Explicit client profile ID")]
|
||||
profile: Option<String>,
|
||||
#[arg(long, help = "WireGuard server endpoint host or IP")]
|
||||
endpoint: Option<String>,
|
||||
#[arg(
|
||||
long = "qr-format",
|
||||
default_value = "terminal",
|
||||
@@ -932,6 +938,28 @@ enum LivePeerSubcommands {
|
||||
Show { id: String },
|
||||
}
|
||||
|
||||
fn create_wireguard_engine() -> Arc<dyn WireGuardEngine> {
|
||||
#[cfg(target_os = "linux")]
|
||||
{
|
||||
Arc::new(NativeLinuxWireGuardEngine::new())
|
||||
}
|
||||
#[cfg(not(target_os = "linux"))]
|
||||
{
|
||||
Arc::new(SimulatedWireGuardEngine::new())
|
||||
}
|
||||
}
|
||||
|
||||
fn create_network_engine() -> Arc<dyn NetworkEngine> {
|
||||
#[cfg(target_os = "linux")]
|
||||
{
|
||||
Arc::new(NativeLinuxNetworkEngine::new())
|
||||
}
|
||||
#[cfg(not(target_os = "linux"))]
|
||||
{
|
||||
Arc::new(SimulatedNetworkEngine::new())
|
||||
}
|
||||
}
|
||||
|
||||
// ── Output Formatter ────────────────────────────────────────────────────────
|
||||
|
||||
fn print_output<T: Serialize>(
|
||||
@@ -1323,7 +1351,48 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
}
|
||||
}
|
||||
SettingsSubcommands::Set { key, value, secret } => {
|
||||
store.set_setting(&key, &value, secret).await?;
|
||||
let key_trimmed = key.trim();
|
||||
let val_trimmed = value.trim();
|
||||
if key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_HOST {
|
||||
if !val_trimmed.is_empty() {
|
||||
nx9_wg_core::validation::validate_server_host(val_trimmed)?;
|
||||
}
|
||||
} else if key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_PORT {
|
||||
let port: u16 = val_trimmed.parse().map_err(
|
||||
|_| "Invalid server port: must be an integer between 1 and 65535",
|
||||
)?;
|
||||
nx9_wg_core::validation::validate_server_port(port)?;
|
||||
} else if key_trimmed
|
||||
== nx9_wg_core::types::settings::SETTING_SERVER_ENDPOINT_ENABLED
|
||||
&& val_trimmed != "true"
|
||||
&& val_trimmed != "false"
|
||||
&& val_trimmed != "1"
|
||||
&& val_trimmed != "0"
|
||||
{
|
||||
return Err("Setting wireguard.server_endpoint_enabled must be 'true' or 'false'".into());
|
||||
}
|
||||
store.set_setting(key_trimmed, val_trimmed, secret).await?;
|
||||
if (key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_HOST
|
||||
|| key_trimmed == nx9_wg_core::types::settings::SETTING_SERVER_PORT
|
||||
|| key_trimmed
|
||||
== nx9_wg_core::types::settings::SETTING_SERVER_ENDPOINT_ENABLED)
|
||||
&& let Ok(settings) = store.get_server_endpoint_settings().await
|
||||
&& settings.enabled
|
||||
&& !settings.host.trim().is_empty()
|
||||
{
|
||||
let formatted = nx9_wg_core::validation::format_endpoint(
|
||||
&settings.host,
|
||||
settings.port,
|
||||
);
|
||||
let _ = store
|
||||
.set_setting(
|
||||
nx9_wg_core::types::settings::LEGACY_SETTING_SERVER_ENDPOINT,
|
||||
&formatted,
|
||||
false,
|
||||
)
|
||||
.await;
|
||||
}
|
||||
|
||||
println!("Setting '{key}' saved.");
|
||||
}
|
||||
SettingsSubcommands::Delete { key } => {
|
||||
@@ -1712,7 +1781,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
println!("Interface '{interface}' disabled.");
|
||||
}
|
||||
InterfaceSubcommands::Status { interface } => {
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let stats = wg.get_interface_stats(&interface).await?;
|
||||
match stats {
|
||||
Some(s) => print_output(&s, format)?,
|
||||
@@ -1721,8 +1790,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
}
|
||||
InterfaceSubcommands::Reconcile { interface: _ } => {
|
||||
let state = AppState::new(store);
|
||||
let wg = Arc::new(SimulatedWireGuardEngine::new());
|
||||
let net = Arc::new(SimulatedNetworkEngine::new());
|
||||
let wg = create_wireguard_engine();
|
||||
let net = create_network_engine();
|
||||
let reconciler = ReconciliationEngine::new(state, wg, net);
|
||||
let report = reconciler.apply().await?;
|
||||
print_output(&report, format)?;
|
||||
@@ -1988,7 +2057,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
.get_interface(peer.interface_id)
|
||||
.await?
|
||||
.ok_or("Interface not found")?;
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let iface_stats = wg.get_interface_stats(&iface.name).await?;
|
||||
let peer_stat = iface_stats.and_then(|s| {
|
||||
s.peers
|
||||
@@ -2008,6 +2077,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
nat,
|
||||
mtu,
|
||||
profile,
|
||||
endpoint,
|
||||
output,
|
||||
} => {
|
||||
let peer_id = Uuid::parse_str(&id)?;
|
||||
@@ -2060,10 +2130,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
None
|
||||
};
|
||||
|
||||
let server_host = store.resolve_server_endpoint(endpoint.as_deref()).await?;
|
||||
|
||||
let conf = ClientConfigBuilder::build_with_profile(
|
||||
&peer,
|
||||
&iface,
|
||||
"127.0.0.1",
|
||||
&server_host,
|
||||
resolved_profile.as_ref(),
|
||||
)?;
|
||||
if let Some(out_path) = output {
|
||||
@@ -2081,6 +2153,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
nat,
|
||||
mtu,
|
||||
profile,
|
||||
endpoint,
|
||||
qr_format,
|
||||
} => {
|
||||
let peer_id = Uuid::parse_str(&id)?;
|
||||
@@ -2133,12 +2206,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
None
|
||||
};
|
||||
|
||||
let server_host = store.resolve_server_endpoint(endpoint.as_deref()).await?;
|
||||
|
||||
let conf = ClientConfigBuilder::build_with_profile(
|
||||
&peer,
|
||||
&iface,
|
||||
"127.0.0.1",
|
||||
&server_host,
|
||||
resolved_profile.as_ref(),
|
||||
)?;
|
||||
|
||||
match qr_format.to_lowercase().as_str() {
|
||||
"svg" => {
|
||||
let svg = generate_qr_svg(&conf)?;
|
||||
@@ -2538,8 +2614,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
}
|
||||
FirewallSubcommands::Sync => {
|
||||
let rules = store.list_firewall_rules().await?;
|
||||
let ifaces = store.list_interfaces().await?;
|
||||
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
||||
let subnets = nx9_wg_api::collect_managed_wg_subnets(&store).await?;
|
||||
let net = NativeLinuxNetworkEngine::new();
|
||||
net.sync_firewall(&rules, true, &subnets).await?;
|
||||
println!("Firewall ruleset synchronized successfully.");
|
||||
@@ -2563,10 +2638,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
|
||||
match args.subcommand {
|
||||
NatSubcommands::Status => {
|
||||
let ifaces = store.list_interfaces().await?;
|
||||
let subnets: Vec<String> = ifaces
|
||||
let subnets: Vec<String> = nx9_wg_api::collect_managed_wg_subnets(&store)
|
||||
.await?
|
||||
.into_iter()
|
||||
.map(|i| i.address_v4.to_string())
|
||||
.map(|s| s.to_string())
|
||||
.collect();
|
||||
let status = serde_json::json!({
|
||||
"nat_masquerade_enabled": true,
|
||||
@@ -2584,17 +2659,16 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
println!("NAT masquerade disabled in settings.");
|
||||
}
|
||||
NatSubcommands::List => {
|
||||
let ifaces = store.list_interfaces().await?;
|
||||
let subnets: Vec<String> = ifaces
|
||||
let subnets: Vec<String> = nx9_wg_api::collect_managed_wg_subnets(&store)
|
||||
.await?
|
||||
.into_iter()
|
||||
.map(|i| i.address_v4.to_string())
|
||||
.map(|s| s.to_string())
|
||||
.collect();
|
||||
print_output(&subnets, format)?;
|
||||
}
|
||||
NatSubcommands::Sync => {
|
||||
let rules = store.list_firewall_rules().await?;
|
||||
let ifaces = store.list_interfaces().await?;
|
||||
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
||||
let subnets = nx9_wg_api::collect_managed_wg_subnets(&store).await?;
|
||||
let net = NativeLinuxNetworkEngine::new();
|
||||
net.sync_firewall(&rules, true, &subnets).await?;
|
||||
println!("NAT masquerade rules synchronized with nftables.");
|
||||
@@ -2778,12 +2852,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
Commands::Live(args) => match args.subcommand {
|
||||
LiveSubcommands::Interface(i_args) => match i_args.subcommand {
|
||||
LiveInterfaceSubcommands::List => {
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let list = wg.list_interfaces().await?;
|
||||
print_output(&list, format)?;
|
||||
}
|
||||
LiveInterfaceSubcommands::Show { name } => {
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let stats = wg.get_interface_stats(&name).await?;
|
||||
match stats {
|
||||
Some(s) => print_output(&s, format)?,
|
||||
@@ -2796,13 +2870,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
},
|
||||
LiveSubcommands::Peer(p_args) => match p_args.subcommand {
|
||||
LivePeerSubcommands::List { interface } => {
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let stats = wg.get_interface_stats(&interface).await?;
|
||||
let peers = stats.map(|s| s.peers).unwrap_or_default();
|
||||
print_output(&peers, format)?;
|
||||
}
|
||||
LivePeerSubcommands::Show { id } => {
|
||||
let wg = SimulatedWireGuardEngine::new();
|
||||
let wg = create_wireguard_engine();
|
||||
let ifaces = wg.list_interfaces().await?;
|
||||
let mut found = None;
|
||||
for iface in ifaces {
|
||||
@@ -2835,7 +2909,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
print_output(&status, format)?;
|
||||
}
|
||||
LiveSubcommands::Firewall => {
|
||||
let net = NativeLinuxNetworkEngine::new();
|
||||
let net = create_network_engine();
|
||||
let ruleset = net.get_active_nftables_ruleset().await?;
|
||||
print_output(&ruleset, format)?;
|
||||
}
|
||||
@@ -2844,8 +2918,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
print_output(&status, format)?;
|
||||
}
|
||||
LiveSubcommands::Nat => {
|
||||
let net = create_network_engine();
|
||||
let ruleset = net.get_active_nftables_ruleset().await.unwrap_or_default();
|
||||
let nat_active = ruleset.contains("masquerade");
|
||||
let status = serde_json::json!({
|
||||
"nat_active": true,
|
||||
"nat_masquerade_active": nat_active,
|
||||
"table": "inet nx9_wg",
|
||||
"chain": "postrouting"
|
||||
});
|
||||
|
||||
@@ -240,10 +240,6 @@ fn test_cli_interface_and_peer_lifecycle() {
|
||||
let ifaces: serde_json::Value = serde_json::from_str(&out).expect("valid json");
|
||||
assert_eq!(ifaces.as_array().unwrap().len(), 1);
|
||||
|
||||
// Status
|
||||
let (ok, _, _) = runner.run(&["interface", "status", "wg0"]);
|
||||
assert!(ok);
|
||||
|
||||
// Create Peer
|
||||
let (ok, out, _) = runner.run(&[
|
||||
"peer",
|
||||
@@ -274,19 +270,41 @@ fn test_cli_interface_and_peer_lifecycle() {
|
||||
let peers: serde_json::Value = serde_json::from_str(&out).expect("valid json");
|
||||
assert_eq!(peers.as_array().unwrap().len(), 1);
|
||||
|
||||
// Peer Config
|
||||
let (ok, out, _) = runner.run(&["peer", "config", peer_id]);
|
||||
// Peer Config without endpoint or setting should fail with actionable error
|
||||
let (ok, _, err) = runner.run(&["peer", "config", peer_id]);
|
||||
assert!(!ok);
|
||||
assert!(err.contains("No reachable WireGuard server endpoint is configured"));
|
||||
|
||||
// Peer Config with explicit --endpoint
|
||||
let (ok, out, _) = runner.run(&["peer", "config", peer_id, "--endpoint", "vpn.example.com"]);
|
||||
assert!(ok);
|
||||
assert!(out.contains("[Interface]"));
|
||||
assert!(out.contains("[Peer]"));
|
||||
assert!(out.contains("Endpoint = vpn.example.com:51820"));
|
||||
|
||||
// Peer QR ASCII
|
||||
let (ok, out, _) = runner.run(&["peer", "qr", peer_id, "--qr-format", "terminal"]);
|
||||
let (ok, out, _) = runner.run(&[
|
||||
"peer",
|
||||
"qr",
|
||||
peer_id,
|
||||
"--endpoint",
|
||||
"vpn.example.com",
|
||||
"--qr-format",
|
||||
"terminal",
|
||||
]);
|
||||
assert!(ok);
|
||||
assert!(!out.is_empty());
|
||||
|
||||
// Peer QR SVG
|
||||
let (ok, out, _) = runner.run(&["peer", "qr", peer_id, "--qr-format", "svg"]);
|
||||
let (ok, out, _) = runner.run(&[
|
||||
"peer",
|
||||
"qr",
|
||||
peer_id,
|
||||
"--endpoint",
|
||||
"vpn.example.com",
|
||||
"--qr-format",
|
||||
"svg",
|
||||
]);
|
||||
assert!(ok);
|
||||
assert!(out.contains("<svg"));
|
||||
|
||||
@@ -755,7 +773,17 @@ fn test_cli_client_profile_and_mtu_system() {
|
||||
assert_eq!(res_json2["mtu"], 1360);
|
||||
assert_eq!(res_json2["applied_profile_id"], "starlink-cgnat");
|
||||
|
||||
// 6. Peer Config with Profile Options
|
||||
// 6. Set server_endpoint setting
|
||||
let (ok, _, _) = runner.run(&[
|
||||
"system",
|
||||
"settings",
|
||||
"set",
|
||||
"server_endpoint",
|
||||
"vpn.example.com",
|
||||
]);
|
||||
assert!(ok);
|
||||
|
||||
// 7. Peer Config with Profile Options
|
||||
let (ok, out, _) = runner.run(&[
|
||||
"peer",
|
||||
"config",
|
||||
@@ -797,6 +825,40 @@ fn test_cli_client_profile_and_mtu_system() {
|
||||
]);
|
||||
assert!(ok);
|
||||
assert!(out.contains("<svg"));
|
||||
|
||||
// 8. Set structured WireGuard server endpoint settings
|
||||
let (ok, _, _) = runner.run(&[
|
||||
"system",
|
||||
"settings",
|
||||
"set",
|
||||
"wireguard.server_host",
|
||||
"vpn.thakares.com",
|
||||
]);
|
||||
assert!(ok);
|
||||
let (ok, _, _) = runner.run(&[
|
||||
"system",
|
||||
"settings",
|
||||
"set",
|
||||
"wireguard.server_port",
|
||||
"51820",
|
||||
]);
|
||||
assert!(ok);
|
||||
|
||||
// 9. Peer Config consumes persistent structured setting
|
||||
let (ok, out, _) = runner.run(&["peer", "config", peer_id]);
|
||||
assert!(ok, "peer config failed: {out}");
|
||||
assert!(out.contains("Endpoint = vpn.thakares.com:51820"));
|
||||
|
||||
// 10. CLI explicit --endpoint overrides persistent setting
|
||||
let (ok, out, _) = runner.run(&[
|
||||
"peer",
|
||||
"config",
|
||||
peer_id,
|
||||
"--endpoint",
|
||||
"custom.override.io:51820",
|
||||
]);
|
||||
assert!(ok, "peer config with explicit override failed: {out}");
|
||||
assert!(out.contains("Endpoint = custom.override.io:51820"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
||||
Reference in new issue
Block a user