Clean up documentation structure and links
This commit is contained in:
thakares committed
1 parent
d25846c58c
commit
32a325234a
22 files changed
+40
-84
No files matched your search
@@ -0,0 +1,106 @@
|
||||
# NX9 WireGuard — System Architecture & Workspace Structure
|
||||
|
||||
`nx9-wg` is structured as a modular six-crate Rust workspace designed for separation of concerns, strict failure domains, and testability.
|
||||
|
||||
```
|
||||
nx9-wg (Workspace Root & Binary Executable)
|
||||
├── crates/nx9-wg-core (Domain models, validation, cryptography, config)
|
||||
├── crates/nx9-wg-db (SQLite store, migrations, repositories, WAL)
|
||||
├── crates/nx9-wireguard (WireGuard Netlink execution, config builder, QR engine)
|
||||
├── crates/nx9-wg-network (RTNETLINK networking, route management, nftables, procfs)
|
||||
├── crates/nx9-wg-api (Axum REST API, WebSockets, auth, reconciliation, allocator)
|
||||
└── crates/nx9-wg-ui (Design tokens, CSS engine, view models, SPA integration)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Crate Inventory & Layer Responsibilities
|
||||
|
||||
### `nx9-wg-core`
|
||||
- **Domain Entities**: Typed domain structures (`Interface`, `Peer`, `Network`, `Route`, `FirewallRule`, `Setting`, `Admin`, `Session`, `ApiToken`, `BackupMeta`, `AuditEvent`).
|
||||
- **Validation**: Strict RFC-compliant validators for CIDRs, IP addresses, MTU ranges, listen ports, interface names, peer names, and password strength.
|
||||
- **Cryptography**: Argon2id password hashing, SHA-256 token digest generation, X25519 keypair generation, and secure random string generation.
|
||||
- **Configuration**: Hierarchical TOML and `NX9_WG_*` environment variable configuration loader.
|
||||
|
||||
### `nx9-wg-db`
|
||||
- **Authoritative Persistence**: Migration-driven SQLite storage using `sqlx` in Write-Ahead Logging (WAL) mode.
|
||||
- **Single Admin Invariant**: SQL constraint `CHECK (id = 1)` enforcing single-administrator identity.
|
||||
- **Repositories**: Isolated data access layers for admin, auth, audit, backups, client profiles, interfaces, login attempts, networks, peers, routes, sessions, settings, and tokens.
|
||||
- **Transactional Consistency**: Foreign key cascades (`ON DELETE CASCADE`) between interfaces and peers.
|
||||
|
||||
### `nx9-wireguard`
|
||||
- **Native Netlink Engine**: `NativeLinuxWireGuardEngine` interacting with Linux RTNETLINK for link lifecycle and Generic Netlink family `wireguard` (`SET_DEVICE`, `GET_DEVICE`, `ReplacePeers`).
|
||||
- **Client Config Generation**: Pure Rust `.conf` generation supporting full-tunnel and split-tunnel topologies.
|
||||
- **QR Code Engine**: High-resolution SVG, PNG byte streams, and UTF-8 ASCII terminal QR code rendering.
|
||||
- **Simulation Engine**: `SimulatedWireGuardEngine` for non-Linux platform development and testing.
|
||||
|
||||
### `nx9-wg-network`
|
||||
- **Native Network Engine**: `NativeLinuxNetworkEngine` managing RTNETLINK interfaces, IPv4/IPv6 addresses, and route tables.
|
||||
- **nftables Netfilter Engine**: `NativeLinuxNftablesEngine` utilizing `libnftables.so.1` for transactional rule generation in `table inet nx9_wg`.
|
||||
- **Kernel IP Forwarding**: Direct `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding` mutation.
|
||||
- **Simulation Engine**: `SimulatedNetworkEngine` for local platform testing.
|
||||
|
||||
### `nx9-wg-api`
|
||||
- **REST Router**: Axum HTTP handlers for auth, interfaces, peers, networks, routes, firewall, NAT, forwarding, settings, backups, diagnostics, and audit logs.
|
||||
- **WebSocket Event Bus**: Tokio broadcast channel broadcasting real-time system events (`AuditEvent`, `InterfaceChanged`, `PeerChanged`, `PeerHandshake`, `SettingsChanged`).
|
||||
- **Reconciliation Engine**: Mutex-serialized continuous drift detection and convergence controller.
|
||||
- **Deterministic IP Allocator**: Collision-resistant next-IP allocation engine for managed subnets.
|
||||
- **Backup & Restore Service**: Online SQLite atomic snapshot (`VACUUM INTO`) and verification engine.
|
||||
|
||||
### `nx9-wg-ui`
|
||||
- **Design Tokens**: Structured CSS variable tokens for Dark and Light themes.
|
||||
- **Stylesheet Generator**: In-process CSS compiler producing responsive layouts (`@media (max-width: 768px)`).
|
||||
- **View Models**: Strongly-typed Rust UI state representations for dashboards, diagnostics, client export modals, and peer management tables.
|
||||
|
||||
---
|
||||
|
||||
## 2. End-to-End Control and Execution Plane
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph ControlPlane["Control Plane (User & Administration)"]
|
||||
User["Administrator (Browser / CLI)"]
|
||||
SPA["Embedded SPA Web UI"]
|
||||
CLI["Native CLI (nx9-wg)"]
|
||||
API["Axum REST API / WebSockets"]
|
||||
DB[("Authoritative SQLite Database")]
|
||||
end
|
||||
|
||||
subgraph ReconciliationLayer["Reconciliation & Engine Layer"]
|
||||
Reconciler["Reconciliation Engine (Serialized Mutex)"]
|
||||
WGEngine["WireGuard Engine (Genl / RTNETLINK)"]
|
||||
NetEngine["Network Engine (RTNETLINK & procfs)"]
|
||||
NftEngine["Nftables Engine (libnftables Netfilter)"]
|
||||
end
|
||||
|
||||
subgraph LinuxKernel["Linux Kernel Execution Plane"]
|
||||
WGSocket["WireGuard Kernel Module (wireguard.ko)"]
|
||||
RTNL["Kernel RTNETLINK (Links, Addrs, Routes)"]
|
||||
Procfs["/proc/sys/net (IP Forwarding)"]
|
||||
Netfilter["Netfilter Subsystem (table inet nx9_wg)"]
|
||||
end
|
||||
|
||||
User -->|HTTPS / WSS| SPA
|
||||
User -->|CLI Invocations| CLI
|
||||
SPA -->|REST API Calls| API
|
||||
CLI -->|In-Process Service Calls| API
|
||||
API -->|Authoritative Mutations| DB
|
||||
DB -->|Desired State Snapshot| Reconciler
|
||||
Reconciler -->|Read Live Telemetry| WGEngine
|
||||
Reconciler -->|Read Live Routes/Forwarding| NetEngine
|
||||
Reconciler -->|Read Live Ruleset| NftEngine
|
||||
WGEngine -->|Generic Netlink Messages| WGSocket
|
||||
NetEngine -->|RTM_NEWLINK / NEWROUTE| RTNL
|
||||
NetEngine -->|Write 1/0| Procfs
|
||||
NftEngine -->|Atomic Netfilter Transactions| Netfilter
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Subsystem Invariants & Security Boundaries
|
||||
|
||||
1. **Subprocess Isolation**: Zero invocations of `std::process::Command` or shell scripts across the entire production codebase.
|
||||
2. **Persistence Authority**: SQLite remains the single authoritative source of truth. Kernel state is continuously reconciled to match database state.
|
||||
3. **Firewall Isolation**: All nftables operations are confined to `table inet nx9_wg`. Unmanaged host tables are untouched.
|
||||
4. **Route Safety**: Default gateway routes and host networking routes are protected against accidental deletion or flushing.
|
||||
5. **Secret Redaction**: Private keys, preshared keys, password hashes, and token hashes are masked in `Debug` formatters, CLI outputs, and API responses.
|
||||
Reference in new issue
Block a user