thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: complete nx9-wg v0.8.0 platform

Browse Source
This commit is contained in:
thakares committed 2026-08-17 14:25:45 +05:30
1 parent c75e5c4e71
commit c8a9b7cde6
52 files changed
+7751 -725
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/api.md
+130 -70
View File
@@ -1,85 +1,145 @@
# REST API and WebSocket Reference
# Axum REST API & WebSocket Protocol Reference
All REST endpoints are nested under the `/api/v1` prefix.
The `nx9-wg` API daemon serves JSON REST endpoints and a real-time WebSocket event bus under the base path `/api/v1`.
---
## Authentication
## 1. Authentication & Session Model
The API supports two authentication mechanisms:
1. **Session Cookie**: `nx9_session=<SESSION_UUID>` (HttpOnly, SameSite=Strict).
2. **Bearer Token**: `Authorization: Bearer nx9_<TOKEN_BASE64>` (Hashed with SHA-256 on the server).
Authentication is supported via two 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.
### B. Bearer API Token
Passed in the `Authorization` header:
```http
Authorization: Bearer nx9_<uuid>_<random>
```
---
## Endpoints
## 2. Standard Error Response Model
### 1. Public Endpoints
- `POST /api/v1/auth/login`: Authenticates administrator with username and password. Sets session cookie.
- `GET /api/v1/system/health`: Service and database health check.
- `GET /api/v1/system/version`: Version and build metadata.
- `GET /api/v1/ws`: WebSocket real-time event stream.
All non-2xx responses return a structured JSON error body:
### 2. Administrator & Session Management
- `POST /api/v1/auth/logout`: Invalidates the current session.
- `GET /api/v1/auth/session`: Returns information about the active session.
- `POST /api/v1/auth/password`: Changes password and terminates all other sessions.
- `GET /api/v1/auth/tokens`: Lists all provisioned API tokens.
- `POST /api/v1/auth/tokens`: Creates a new API token.
- `DELETE /api/v1/auth/tokens/{id}`: Revokes an API token.
```json
{
"error": "Descriptive error message",
"status": 404
}
```
### 3. WireGuard Interfaces
- `GET /api/v1/interfaces`: Lists all interfaces.
- `POST /api/v1/interfaces`: Creates an interface.
- `GET /api/v1/interfaces/{id}`: Interface details.
- `PUT /api/v1/interfaces/{id}`: Updates interface settings.
- `DELETE /api/v1/interfaces/{id}`: Deletes interface.
- `POST /api/v1/interfaces/{id}/enable`: Enables interface.
- `POST /api/v1/interfaces/{id}/disable`: Disables interface.
- `GET /api/v1/interfaces/{id}/status`: Live statistics, listen port, and connected peer metrics.
### 4. WireGuard Peers
- `GET /api/v1/interfaces/{id}/peers`: Lists peers for a specific interface.
- `POST /api/v1/interfaces/{id}/peers`: Enrolls a new peer.
- `GET /api/v1/peers/{id}`: Peer details.
- `PUT /api/v1/peers/{id}`: Updates peer configuration.
- `DELETE /api/v1/peers/{id}`: Deletes peer.
- `POST /api/v1/peers/{id}/enable`: Activates peer.
- `POST /api/v1/peers/{id}/disable`: Disables peer.
- `POST /api/v1/peers/{id}/revoke`: Revokes peer.
- `GET /api/v1/peers/{id}/config`: Downloads standard client `.conf` file.
- `GET /api/v1/peers/{id}/qr`: Returns SVG, PNG base64, and Data URL QR code representations.
### 5. Networks & Routing
- `GET /api/v1/networks`, `POST /api/v1/networks`, `DELETE /api/v1/networks/{id}`
- `GET /api/v1/routes`, `POST /api/v1/routes`, `DELETE /api/v1/routes/{id}`
### 6. Firewall & nftables
- `GET /api/v1/firewall/rules`, `POST /api/v1/firewall/rules`, `DELETE /api/v1/firewall/rules/{id}`
- `POST /api/v1/firewall/rules/{id}/enable`, `POST /api/v1/firewall/rules/{id}/disable`
### 7. Audit Log
- `GET /api/v1/audit`: Paginated and filtered query of security and system events.
### 8. Backups
- `GET /api/v1/backups`: Lists existing backup records.
- `POST /api/v1/backups/create`: Creates a new snapshot and manifest.
- `GET /api/v1/backups/{id}/download`: Downloads backup archive.
- `POST /api/v1/backups/{id}/restore`: Safely restores database.
- `DELETE /api/v1/backups/{id}`: Deletes backup archive and metadata.
### 9. Reconciliation
- `GET /api/v1/reconcile/plan`: Returns detected drift without making changes.
- `POST /api/v1/reconcile/apply`: Applies reconciliation plan to live kernel.
### 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.
- `429 Too Many Requests`: Brute-force rate limiting triggered.
- `500 Internal Server Error`: Native Linux execution plane or storage failure.
---
## WebSocket Telemetry (`/api/v1/ws`)
## 3. REST API Endpoint Inventory
Upon connection, clients receive a stream of JSON `SystemEvent` frames:
- `InterfaceChanged { id, action }`
- `PeerChanged { id, action }`
- `NetworkChanged { id, action }`
- `RouteChanged { id, action }`
- `FirewallChanged { id, action }`
- `AuditEvent { event_type, message, resource_type, resource_id }`
### 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": "...", "value": "...", "description": "..." }`.
### 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.
- `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/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=...`).
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg`).
### 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.
- `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 9 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:
```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.