# NX9 WireGuard (`nx9-wg`)

> **A native Rust, self-hosted WireGuard appliance and network management engine for the NX9 ecosystem.**

`nx9-wg` is designed from first principles as a clean, high-performance replacement for Node.js-based WireGuard managers (such as `wg-easy`). Built entirely in native Rust with zero external scripting runtime dependencies, `nx9-wg` provides authoritative SQLite persistence, robust administrative authentication, native Linux kernel networking, automated reconciliation, and pure Rust QR code and client configuration generation.

---

## Key Features

- **Native Rust Systems Architecture**: Zero Node.js, npm, Python, Electron, or external daemon runners.
- **Authoritative SQLite State**: Fully migration-driven schema with WAL mode, foreign key integrity, and isolated repository operations.
- **Single Administrator Security Model**: Strictly 1 administrator identity (`CHECK (id = 1)`), Argon2id password hashing, SHA-256 API token authentication, and sliding-window brute force lockout.
- **Native Linux WireGuard Engine**: Direct interaction with Linux networking and kernel interfaces without shelling out to `wg` or `wg-quick`.
- **nftables Isolation**: Dedicated `table inet nx9_wg` with input, forward, and NAT postrouting masquerade chains.
- **Continuous Reconciliation**: Automated drift detection and idempotent convergence between desired database state and live Linux kernel state.
- **Pure Rust Client Enrollment**: Full-tunnel and split-tunnel `.conf` builder, high-resolution SVG/PNG QR generator, and ASCII terminal QR output.
- **Consistent Backups**: Atomic SQLite snapshots (`VACUUM INTO`), manifest hashing with SHA-256, verification, and safety snapshots before restore.
- **Complete CLI & Axum REST API**: Multi-format CLI (`table`, `json`, `yaml`, `csv`) and RESTful API with real-time WebSocket telemetry.

---

## Quick Start

### 1. Build and Run Tests
```bash
# Build the workspace
cargo build --release

# Run all 41 unit and integration tests
cargo test --workspace
```

### 2. Initialize the Administrator
```bash
# Initialize with a generated password:
cargo run -- init --generate-password

# Or initialize with a specific password:
cargo run -- init --username admin --password "YourStrongPassword123!"
```

### 3. Start the Daemon
```bash
cargo run -- serve --bind 0.0.0.0:8080
```

### 4. Create an Interface and Enroll a Peer via CLI
```bash
# Create WireGuard interface wg0
cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24

# Create peer Alice
cargo run -- peer create --interface-id <INTERFACE_UUID> --name alice --address-v4 10.0.0.2/32

# Display terminal QR code for instant mobile scan:
cargo run -- peer qr <PEER_UUID>

# Print client .conf file:
cargo run -- peer config <PEER_UUID>
```

---

## Architecture Overview

```
 ┌────────────────────────────────────────────────────────┐
 │                      nx9-wg CLI                        │
 └───────────────────────────┬────────────────────────────┘
                             │
 ┌───────────────────────────▼────────────────────────────┐
 │               Axum REST API & WebSockets               │
 └───────┬───────────────────┬───────────────────┬────────┘
         │                   │                   │
 ┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
 │    nx9-db     │   │ nx9-wireguard │   │  nx9-network  │
 │ (SQLite+WAL)  │   │  (Kernel WG)  │   │(Routes+nftables)│
 └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
             ┌───────────────▼───────────────┐
             │     Reconciliation Engine     │
             │   (Desired vs Live Kernel)    │
             └───────────────────────────────┘
```

For complete architectural details, see [Architecture Documentation](docs/architecture.md).

---

## Documentation Index

- [Architecture & Crate Design](docs/architecture.md)
- [Installation & Systemd Setup](docs/installation.md)
- [Configuration Reference](docs/configuration.md)
- [CLI Command Guide](docs/cli.md)
- [REST API & WebSocket Reference](docs/api.md)
- [Security Model & Auditing](docs/security.md)
- [Docker & Container Deployment](docs/docker.md)
- [Backup & Restore Procedures](docs/backup_restore.md)
- [Development & Testing Guide](docs/development.md)
- [Linux Kernel Requirements](docs/linux_requirements.md)

---

## License

Copyright (c) NX9 Systems. All rights reserved.