nx9-wg/docs/API.md

Axum REST API & WebSocket Protocol Reference

The nx9-wg API daemon serves JSON REST endpoints and a real-time WebSocket event bus under the base path /api/v1.

---

1. Authentication & Session Model

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 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:

Authorization: Bearer nx9_<uuid>_<random>

---

2. Standard Error Response Model

All non-2xx responses return a structured JSON error body:

{
  "error": "Descriptive error message",
  "status": 404
}

Common HTTP Status Codes:

• 200 OK: Request succeeded.
• 400 Bad Request: Validation failure on input parameters.
• 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 (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.

---

3. REST API Endpoint Inventory

Authentication & Tokens

• POST /api/v1/auth/login: Authenticate with { "username": "admin", "password": "..." }. Returns session cookie and user metadata.
• POST /api/v1/auth/logout: Invalidate current active session.
• GET /api/v1/auth/session: Query authenticated session info.
• POST /api/v1/auth/password: Update administrator password { "current_password": "...", "new_password": "..." }. Invalidates all active sessions.
• GET /api/v1/auth/tokens: List all API token metadata.
• POST /api/v1/auth/tokens: Generate API token { "name": "ci-token", "expires_in_days": 30 }. Returns { "raw_token": "...", "meta": {...} }.
• DELETE /api/v1/auth/tokens/{id}: Revoke an API token.

System & Health

• GET /api/v1/system/health: Public system health check { "status": "healthy", "database": "connected" }.
• 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": "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 (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 (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.
• PUT /api/v1/peers/{id}: Update peer parameters.
• 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=...&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.
• POST /api/v1/networks: Create subnet { "name": "clients", "cidr": "10.100.1.0/24" }.
• GET /api/v1/networks/{id}: Get network details.
• DELETE /api/v1/networks/{id}: Delete network.
• GET /api/v1/networks/{id}/available: List unallocated IP addresses.

Routing

• GET /api/v1/routes: List routing table entries.
• POST /api/v1/routes: Add route { "destination": "192.168.50.0/24", "gateway": "10.100.0.2", "metric": 100 }.
• DELETE /api/v1/routes/{id}: Delete route.

Firewall & NAT

• 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.

Reconciliation

• GET /api/v1/reconcile/plan: Query read-only drift plan between SQLite and Linux kernel.
• POST /api/v1/reconcile/apply: Execute native mutations and verify convergence.

Diagnostics

• GET /api/v1/diagnostics/all: Run automated checks across all subsystems.
• GET /api/v1/diagnostics/{subsystem}: Run checks for a single subsystem.

Backups

• GET /api/v1/backups: List backup snapshots.
• POST /api/v1/backups/create: Trigger atomic online backup snapshot (VACUUM INTO).
• GET /api/v1/backups/{id}/download: Download raw SQLite database backup file.
• POST /api/v1/backups/{id}/restore: Restore database from snapshot.
• DELETE /api/v1/backups/{id}: Delete backup record and snapshot file.

Audit Trail

• GET /api/v1/audit: List append-only security and operational audit records.

---

4. Real-Time WebSocket Protocol (/api/v1/ws)

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:

{
  "type": "AuditEvent",
  "payload": {
    "event_type": "peer_created",
    "message": "Peer 'alice-phone' enrolled on interface wg0",
    "resource_type": "peer",
    "resource_id": "974755a9-74d9-4488-85c9-f057230ab8e2"
  }
}

Event Types:

• AuditEvent: Security and state mutation events.
• InterfaceChanged: Interface status toggle or link state change.
• PeerChanged: Peer parameter update or state transition.
• PeerHandshake: Real-time cryptographic handshake update.
• SettingsChanged: Key-value configuration change.