diff --git a/NX9-WG-STACK.md b/NX9-WG-STACK.md deleted file mode 100644 index 9ab897d..0000000 --- a/NX9-WG-STACK.md +++ /dev/null @@ -1,519 +0,0 @@ -# NX9 WireGuard (`nx9-wg`) β€” Full Technical Architecture & Stack Report - -![Rust](https://img.shields.io/badge/Rust-Stable-orange) -![SQLite](https://img.shields.io/badge/SQLite-Embedded-blue) -![Platform](https://img.shields.io/badge/Platform-Linux-lightgrey) -![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-green) -![Version](https://img.shields.io/badge/Version-v1.0.0-purple) -![Ecosystem](https://img.shields.io/badge/NX9-Ecosystem-6d5df6) - -> **"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:///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=` returned via `POST /api/v1/auth/login`. -- **Bearer Token**: `Authorization: Bearer nx9__` 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 - -# 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 -nx9-wg peer config - -# 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 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 -``` - ---- - -## 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-v1.0.0-linux-x86_64.tar.gz` (7.8 MB) -- `nx9-wg-v1.0.0-linux-x86_64.tar.xz` (5.0 MB) -- `nx9-wg-v1.0.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** (**162 / 162 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. diff --git a/README.md b/README.md index 1f15c70..7c575aa 100644 --- a/README.md +++ b/README.md @@ -455,5 +455,5 @@ the captured evidence have been redacted where applicable. ![NX9-WG Backups](screenshots/backup.png) -> **Additional evidence:** `screenshots/admin-instance.pdf` contains the captured administrative +> **Additional evidence:** `screenshots/admin-instance.png` contains the captured administrative > instance documentation and is retained in the repository alongside the UI screenshots.