thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v1.1.0
nx9-wg/docs/API.md
T
thakares edc710cbd2 Release v1.1.0
2026-09-02 15:19:19 +05:30

8.3 KiB
Raw Permalink Blame History

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 (includes role: "overlay" | "upstream" and listen_port: u16 | null).
  • POST /api/v1/interfaces: Create standard Overlay interface { "name": "wg0", "address_v4": "10.100.0.1/24", "listen_port": 51820, "mtu": 1420 }.
  • POST /api/v1/interfaces/upstreams/preview: Dry-run validate and preview third-party WireGuard .conf { "name": "proton0", "config": "[Interface]\n..." }. Returns parsed interface and provider peer metadata with secrets redacted. Does not mutate database.
  • POST /api/v1/interfaces/upstreams/import: Import third-party WireGuard .conf { "name": "proton0", "config": "[Interface]\n..." }. Atomically creates Upstream interface and provider peer in SQLite, syncs kernel device with dynamic local listen port, and triggers reconciliation.
  • 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 (tears down kernel device via Netlink and cascades to peers in database; protected against wg0).
  • POST /api/v1/interfaces/{id}/enable: Set interface IFF_UP.
  • POST /api/v1/interfaces/{id}/disable: Set interface IFF_DOWN (protected against wg0).
  • POST /api/v1/interfaces/{id}/restart: Restart interface (tears down kernel link and re-synchronizes desired configuration and peers).
  • 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.

SPA CLI Console

  • POST /api/v1/cli/execute: Execute a structured read-only CLI command { "command": "interface", "subcommand": "upstream", "sub_subcommand": "list", "target": null, "parameters": {} }. Enforces a strict read-only allowlist and sanitizes output against secret leakage. Mutating commands and arbitrary shell execution are strictly rejected.

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.
Reference in new issue View Git Blame Copy Permalink