# Changelog All notable changes to **NX9-WG (`nx9-wg`)** are documented here. ## [1.1.0] — 2026-09-02 ### Added - **Interface Roles**: Explicit `InterfaceRole` discriminator (`Overlay` vs `Upstream`). Primary interface `wg0` is protected from deletion and disabling. - **Optional Third-Party Upstream Interfaces**: In-process parser and validator for standard third-party WireGuard `.conf` files (validated against ProtonVPN), creating managed `Upstream` interfaces (e.g. `proton0`) with exactly one provider peer. - **REST API Endpoints**: Added `POST /api/v1/interfaces/upstreams/preview` (dry-run configuration validation with secret redaction), `POST /api/v1/interfaces/upstreams/import` (atomic SQLite persistence and reconciliation), and `POST /api/v1/interfaces/{id}/restart` (link teardown and re-synchronization). - **Native CLI Commands**: Added `nx9-wg interface upstream` command suite (`list`, `show`, `import`, `status`, `enable`, `disable`, `restart`, `delete`) and `nx9-wg interface restart`. - **Read-Only SPA CLI Console**: Embedded web-based CLI runner enforcing a strict read-only command allowlist and output secret scrubbing. - **Reconciliation Hardening**: Added orphan kernel interface detection and removal during `apply()`, backed by empty-desired-state safety guards preventing destructive cleanup on database read failures. - **Provider AllowedIPs Preservation**: Upstream provider peers retain full-tunnel AllowedIPs (`0.0.0.0/0, ::/0`) in WireGuard Cryptokey Routing without modifying or hijacking host Linux FIB default routes. ### Changed - **Optional Local Listen Ports**: Changed `Interface.listen_port` to `Option` across domain models, Netlink device configuration, REST API, and SQLite database (`0005_optional_listen_port.sql`). - **Dynamic Port Web UI**: Unspecified listen ports are rendered as `Auto (Dynamic)` rather than a fabricated `51820`. ### Fixed - **Local Listen Port Collision (errno=-98 / EADDRINUSE)**: Fixed upstream interfaces defaulting omitted `ListenPort` to `51820`, which collided with `wg0`. Omitted listen ports now remain `None`, allowing Linux WireGuard to bind an ephemeral dynamic UDP port. - **Reconciliation Dynamic Port Drift**: Suppressed false listen-port drift when desired `listen_port` is `None` and the kernel reports a dynamic port. - **Provider Endpoint Port Independence**: Ensured remote destination `[Peer] Endpoint` port (e.g. `37.19.199.155:51820`) is strictly preserved and never assigned as the local interface listen port. ### Interoperability Status - **ProtonVPN**: ProtonVPN WireGuard `.conf` files import and synchronize cleanly into Linux kernel devices (`proton0`) with dynamic local listen ports. Upstream connectivity status is classified as `interop_pending_external_validation` (pending external provider session/endpoint resolution, not an NX9-WG implementation defect). ## [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.