156 lines
8.3 KiB
Markdown
156 lines
8.3 KiB
Markdown
# 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:
|
|
```http
|
|
Authorization: Bearer nx9_<uuid>_<random>
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Standard Error Response Model
|
|
|
|
All non-2xx responses return a structured JSON error body:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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.
|