nessi
830491cb0d
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
181 lines
5.1 KiB
Markdown
181 lines
5.1 KiB
Markdown
# 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.
|