Finalize nx9-wg production release

docs/api.md

@@ -6,10 +6,10 @@ The `nx9-wg` API daemon serves JSON REST endpoints and a real-time WebSocket eve
 
 ## 1. Authentication & Session Model
 
-Authentication is supported via two mechanisms:
+Authentication is supported via two secure mechanisms:
 
 ### A. HTTP Session Cookie (`nx9_session`)
-Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header and automatically attached by web browsers.
+Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header with `HttpOnly; SameSite=Strict; Path=/` and automatically attached by web browsers for both REST API requests and WebSocket upgrade handshakes.
 
 ### B. Bearer API Token
 Passed in the `Authorization` header:
@@ -36,8 +36,8 @@ All non-2xx responses return a structured JSON error body:
 - `401 Unauthorized`: Missing, invalid, or expired session/token.
 - `404 Not Found`: Resource ID does not exist in SQLite.
 - `409 Conflict`: Unique constraint violation (e.g. duplicate interface name or IP).
-- `422 Unprocessable Entity`: Semantic constraint failure.
-- `429 Too Many Requests`: Brute-force rate limiting triggered.
+- `422 Unprocessable Entity`: Semantic constraint failure (e.g. invalid server host with embedded port, invalid port bounds).
+- `429 Too Many Requests`: Brute-force rate limiting triggered (5 failed logins in 15 minutes).
 - `500 Internal Server Error`: Native Linux execution plane or storage failure.
 
 ---
@@ -58,20 +58,20 @@ All non-2xx responses return a structured JSON error body:
 - `GET /api/v1/system/version`: Public version and build information.
 - `GET /api/v1/system`: System operational overview and interface/peer counts.
 - `GET /api/v1/system/settings`: List all key-value settings.
-- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "...", "value": "...", "description": "..." }`.
+- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "wireguard.server_host", "value": "vpn.thakares.com", "is_secret": false, "description": "..." }`. Supports `wireguard.server_host`, `wireguard.server_port`, and `wireguard.server_endpoint_enabled`.
 
 ### WireGuard Interfaces
 - `GET /api/v1/interfaces`: List all WireGuard interfaces.
 - `POST /api/v1/interfaces`: Create interface `{ "name": "wg0", "address_v4": "10.100.0.1/24", "listen_port": 51820, "mtu": 1420 }`.
 - `GET /api/v1/interfaces/{id}`: Get interface details.
-- `PUT /api/v1/interfaces/{id}`: Update interface configuration.
+- `PUT /api/v1/interfaces/{id}`: Update interface configuration (preserves private/public cryptographic identity).
 - `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.
 
 ### Peers & Client Configs
-- `GET /api/v1/peers`: List all peers across all interfaces.
+- `GET /api/v1/peers`: List all peers across all interfaces (enriched with live kernel telemetry).
 - `GET /api/v1/interfaces/{id}/peers`: List peers for specific interface.
 - `POST /api/v1/interfaces/{id}/peers`: Enroll peer `{ "name": "alice", "profile": "full_tunnel", "mtu": 1280, ... }`.
 - `GET /api/v1/peers/{id}`: Get peer details.
@@ -79,8 +79,12 @@ All non-2xx responses return a structured JSON error body:
 - `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 WireGuard `.conf` file (supports `?device=...&connection=...`).
-- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg`).
+- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...&endpoint=...`). Uses persistent `wireguard.server_*` settings if `endpoint` query parameter is omitted.
+- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg&endpoint=...`). Returns `{ "svg": "<svg...", "data_url": "data:image/png;base64,..." }`.
+
+### Client Profiles & MTU Resolution
+- `GET /api/v1/client-profiles`: List client transport profiles.
+- `GET /api/v1/client-profiles/resolve`: Resolve optimal MTU and keepalive parameters for device and connection environment.
 
 ### Networks & Subnets
 - `GET /api/v1/networks`: List subnet networks.
@@ -95,8 +99,8 @@ All non-2xx responses return a structured JSON error body:
 - `DELETE /api/v1/routes/{id}`: Delete route.
 
 ### Firewall & NAT
-- `GET /api/v1/firewall/rules`: List nftables rules.
-- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": "22", "action": "accept" }`.
+- `GET /api/v1/firewall/rules`: List nftables rules in `table inet nx9_wg`.
+- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": 22, "action": "accept" }`.
 - `DELETE /api/v1/firewall/rules/{id}`: Delete rule.
 - `POST /api/v1/firewall/rules/{id}/enable`: Enable rule.
 - `POST /api/v1/firewall/rules/{id}/disable`: Disable rule.
@@ -106,7 +110,7 @@ All non-2xx responses return a structured JSON error body:
 - `POST /api/v1/reconcile/apply`: Execute native mutations and verify convergence.
 
 ### Diagnostics
-- `GET /api/v1/diagnostics/all`: Run automated checks across all 9 subsystems.
+- `GET /api/v1/diagnostics/all`: Run automated checks across all subsystems.
 - `GET /api/v1/diagnostics/{subsystem}`: Run checks for a single subsystem.
 
 ### Backups
@@ -123,7 +127,7 @@ All non-2xx responses return a structured JSON error body:
 
 ## 4. Real-Time WebSocket Protocol (`/api/v1/ws`)
 
-Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events:
+Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events. Authentication is handled automatically using the browser's `nx9_session` cookie or `Authorization: Bearer <token>` header:
 
 ```json
 {