chore: initial project scaffold with admin web, backend, desktop client, and deployment setup

Add monorepo structure for NexaVPN WireGuard control plane including: - .gitignore for node_modules, build artifacts, and environment files - README with project overview, monorepo layout, and quick start guide - Admin web UI with React, Vite, TypeScript, and nginx reverse proxy - API client with type definitions for users, devices, policies, gateways, and audit logs - Admin pages for dashboard, users, devices, policies, g
2026-03-15 16:32:34 +01:00
commit 830491cb0d
91 changed files with 5279 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,180 @@
+# NexaVPN Architecture
+
+## System Overview
+
+NexaVPN is a self-hosted remote access platform that uses WireGuard for transport and a centralized control plane for identity, device enrollment, provisioning, and policy enforcement.
+
+The platform is split into four major planes:
+
+1. Control plane
+   - Go REST API
+   - PostgreSQL
+   - JWT auth and refresh sessions
+   - policy engine
+   - audit logging
+   - WireGuard profile builder
+   - gateway state publisher
+2. Management plane
+   - React admin console
+   - user, device, policy, gateway, and audit workflows
+3. Endpoint plane
+   - Tauri desktop client for Windows and macOS
+   - local secure token/config storage
+   - on-device WireGuard keypair generation
+   - embedded tunnel lifecycle management
+4. Data plane
+   - Linux WireGuard gateway
+   - nftables policy enforcement
+   - routed access to protected resources
+
+## Logical Components
+
+### Backend
+
+- `auth`
+  - username/password login
+  - access and refresh token issuance
+  - session tracking
+- `user`
+  - user CRUD
+  - role assignment
+  - account enable/disable
+- `device`
+  - device registration
+  - enrollment lifecycle
+  - device revocation
+  - device profile rotation
+- `policy`
+  - user and device policy resolution
+  - group-aware target model
+  - allow-list centric MVP with deny precedence reserved in schema
+- `gateway`
+  - gateway inventory
+  - endpoint metadata
+  - peer sync bundle generation
+  - firewall rule translation output
+- `profile`
+  - WireGuard config assembly
+  - connect metadata response
+- `audit`
+  - immutable security and admin events
+- `ipam`
+  - VPN address pool allocation
+  - uniqueness and lifecycle tracking
+
+### Admin UI
+
+- Dashboard
+  - counts, enrollment trend, latest audit events
+- Users
+  - create, edit, disable, password reset
+- Devices
+  - list, revoke, rotate, inspect assigned profile metadata
+- Policies
+  - create CIDR-based allow rules and attach them to users, devices, or groups
+- Gateways
+  - endpoint configuration, sync status, address pool view
+- Audit
+  - searchable event history
+- Settings
+  - DNS defaults, token lifetimes, bootstrap settings
+
+### Desktop Client
+
+- onboarding
+  - server URL
+  - username
+  - password
+- enrollment
+  - machine fingerprint generation
+  - WireGuard keypair generation on-device
+  - device registration
+  - profile provisioning
+- runtime
+  - secure local storage
+  - connect/disconnect
+  - status display
+  - last sync time
+  - allowed resources display
+- diagnostics
+  - logs
+  - TLS trust warning surface
+  - profile refresh retry
+
+### Gateway
+
+- WireGuard interface
+- issued peers synced from control plane
+- nftables chain generated from effective device policies
+- route advertisement limited to assigned resources or full tunnel mode
+
+## Key Design Decisions
+
+### Authentication
+
+- Access tokens are short-lived JWTs.
+- Refresh tokens are opaque, hashed in the database, and bound to a session.
+- Admin and standard-user authorization is role-based.
+
+### Device Trust
+
+- A device is represented as a durable record linked to a user.
+- Clients generate their own WireGuard keypairs.
+- Only the public key is stored server-side.
+- Device rotation invalidates the old peer and issues a fresh profile revision.
+
+### Policy Model
+
+- Effective access is the union of active allow policies targeted at:
+  - the user
+  - the device
+  - any future groups
+- Device-specific policies can narrow or extend user-level access.
+- Gateway enforcement is authoritative; the client display is informational.
+
+### WireGuard Provisioning
+
+- The backend returns structured peer metadata and a rendered profile payload.
+- The desktop client stores the private key and profile locally.
+- The MVP uses an embedded tunnel-management abstraction rather than depending on the standalone WireGuard desktop app.
+
+### Expandability
+
+The schema and package layout reserve room for:
+
+- MFA
+- OIDC and SSO
+- approval-based enrollment
+- group and role expansion
+- multiple gateways
+- route and posture-aware policies
+- richer sync agents at the gateway edge
+
+## Request Flow Summary
+
+### Login and Enrollment
+
+1. User enters server URL, username, and password in the desktop app.
+2. Client authenticates against `/api/v1/auth/login`.
+3. Client generates a WireGuard keypair and device fingerprint locally.
+4. Client registers with `/api/v1/devices/enroll`.
+5. Backend resolves policy, allocates IP, selects a gateway, stores the peer, and returns profile metadata.
+6. Client stores tokens and WireGuard config securely.
+7. Client uses the embedded tunnel manager to create the local profile and expose one-click connect/disconnect.
+
+### Policy Update
+
+1. Admin changes a policy in the web UI.
+2. Backend stores the update and writes an audit event.
+3. Gateway sync state is recalculated.
+4. Gateway rule bundle is regenerated for affected peers.
+5. The client sees refreshed allowed resources on next sync.
+
+## Security Posture
+
+- Passwords use Argon2id.
+- Refresh tokens are stored hashed.
+- Device private keys stay local.
+- Audit logs capture auth, enrollment, policy, and admin actions.
+- TLS is assumed in production behind a reverse proxy.
+- Gateway firewalling enforces allowed destinations independently from the client.