From 32a325234ae234cc28063d01fa94b171995be321 Mon Sep 17 00:00:00 2001 From: Sunil Thakare Date: Sun, 30 Aug 2026 20:02:38 +0530 Subject: [PATCH] Clean up documentation structure and links --- README.md | 38 +++++++-------- config.example.toml | 2 +- docs/{api.md => API.md} | 0 docs/{architecture.md => ARCHITECTURE.md} | 0 docs/{backup_restore.md => BACKUP_RESTORE.md} | 0 docs/{cli.md => CLI.md} | 0 docs/{configuration.md => CONFIGURATION.md} | 0 ...ign-principles.md => DESIGN-PRINCIPLES.md} | 0 docs/{development.md => DEVELOPMENT.md} | 0 docs/{docker.md => DOCKER.md} | 0 docs/{firewall_nat.md => FIREWALL_NAT.md} | 0 docs/{installation.md => INSTALLATION.md} | 0 ..._requirements.md => LINUX_REQUIREMENTS.md} | 0 docs/{native-network.md => NATIVE-NETWORK.md} | 0 ...ative-wireguard.md => NATIVE-WIREGUARD.md} | 0 docs/{nftables.md => NFTABLES.md} | 0 docs/README.md | 36 +++++++-------- docs/{reconciliation.md => RECONCILIATION.md} | 0 docs/{release.md => RELEASE.md} | 2 +- docs/{security.md => SECURITY.md} | 0 docs/{ui.md => UI.md} | 0 docs/testing.md | 46 ------------------- 22 files changed, 40 insertions(+), 84 deletions(-) rename docs/{api.md => API.md} (100%) rename docs/{architecture.md => ARCHITECTURE.md} (100%) rename docs/{backup_restore.md => BACKUP_RESTORE.md} (100%) rename docs/{cli.md => CLI.md} (100%) rename docs/{configuration.md => CONFIGURATION.md} (100%) rename docs/{design-principles.md => DESIGN-PRINCIPLES.md} (100%) rename docs/{development.md => DEVELOPMENT.md} (100%) rename docs/{docker.md => DOCKER.md} (100%) rename docs/{firewall_nat.md => FIREWALL_NAT.md} (100%) rename docs/{installation.md => INSTALLATION.md} (100%) rename docs/{linux_requirements.md => LINUX_REQUIREMENTS.md} (100%) rename docs/{native-network.md => NATIVE-NETWORK.md} (100%) rename docs/{native-wireguard.md => NATIVE-WIREGUARD.md} (100%) rename docs/{nftables.md => NFTABLES.md} (100%) rename docs/{reconciliation.md => RECONCILIATION.md} (100%) rename docs/{release.md => RELEASE.md} (98%) rename docs/{security.md => SECURITY.md} (100%) rename docs/{ui.md => UI.md} (100%) delete mode 100644 docs/testing.md diff --git a/README.md b/README.md index 7c575aa..7981964 100644 --- a/README.md +++ b/README.md @@ -326,7 +326,7 @@ All release quality gates have been executed and verified on Debian Linux: | **Formatting** | `cargo fmt --all -- --check` | **PASS** (0 errors) | | **Compilation** | `cargo check --workspace --all-targets` | **PASS** (0 errors) | | **Clippy Linting** | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (0 warnings) | -| **Workspace Test Suite** | `cargo test --workspace --all-targets` | **PASS** (All 88 tests passing) | +| **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) | @@ -374,24 +374,24 @@ 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) +- [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) +- [Development Guide](docs/DEVELOPMENT.md) +- [Docker Deployment](docs/DOCKER.md) ## 17. Web UI Screenshots @@ -457,3 +457,5 @@ the captured evidence have been redacted where applicable. > **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) diff --git a/config.example.toml b/config.example.toml index 60086a7..65f90a1 100644 --- a/config.example.toml +++ b/config.example.toml @@ -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 * * *" diff --git a/docs/api.md b/docs/API.md similarity index 100% rename from docs/api.md rename to docs/API.md diff --git a/docs/architecture.md b/docs/ARCHITECTURE.md similarity index 100% rename from docs/architecture.md rename to docs/ARCHITECTURE.md diff --git a/docs/backup_restore.md b/docs/BACKUP_RESTORE.md similarity index 100% rename from docs/backup_restore.md rename to docs/BACKUP_RESTORE.md diff --git a/docs/cli.md b/docs/CLI.md similarity index 100% rename from docs/cli.md rename to docs/CLI.md diff --git a/docs/configuration.md b/docs/CONFIGURATION.md similarity index 100% rename from docs/configuration.md rename to docs/CONFIGURATION.md diff --git a/docs/design-principles.md b/docs/DESIGN-PRINCIPLES.md similarity index 100% rename from docs/design-principles.md rename to docs/DESIGN-PRINCIPLES.md diff --git a/docs/development.md b/docs/DEVELOPMENT.md similarity index 100% rename from docs/development.md rename to docs/DEVELOPMENT.md diff --git a/docs/docker.md b/docs/DOCKER.md similarity index 100% rename from docs/docker.md rename to docs/DOCKER.md diff --git a/docs/firewall_nat.md b/docs/FIREWALL_NAT.md similarity index 100% rename from docs/firewall_nat.md rename to docs/FIREWALL_NAT.md diff --git a/docs/installation.md b/docs/INSTALLATION.md similarity index 100% rename from docs/installation.md rename to docs/INSTALLATION.md diff --git a/docs/linux_requirements.md b/docs/LINUX_REQUIREMENTS.md similarity index 100% rename from docs/linux_requirements.md rename to docs/LINUX_REQUIREMENTS.md diff --git a/docs/native-network.md b/docs/NATIVE-NETWORK.md similarity index 100% rename from docs/native-network.md rename to docs/NATIVE-NETWORK.md diff --git a/docs/native-wireguard.md b/docs/NATIVE-WIREGUARD.md similarity index 100% rename from docs/native-wireguard.md rename to docs/NATIVE-WIREGUARD.md diff --git a/docs/nftables.md b/docs/NFTABLES.md similarity index 100% rename from docs/nftables.md rename to docs/NFTABLES.md diff --git a/docs/README.md b/docs/README.md index 2a7b947..fd8a20a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. +- [**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. +- [**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. diff --git a/docs/reconciliation.md b/docs/RECONCILIATION.md similarity index 100% rename from docs/reconciliation.md rename to docs/RECONCILIATION.md diff --git a/docs/release.md b/docs/RELEASE.md similarity index 98% rename from docs/release.md rename to docs/RELEASE.md index 4fbb7b6..eb97786 100644 --- a/docs/release.md +++ b/docs/RELEASE.md @@ -6,7 +6,7 @@ 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 diff --git a/docs/security.md b/docs/SECURITY.md similarity index 100% rename from docs/security.md rename to docs/SECURITY.md diff --git a/docs/ui.md b/docs/UI.md similarity index 100% rename from docs/ui.md rename to docs/UI.md diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index e33a521..0000000 --- a/docs/testing.md +++ /dev/null @@ -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.