NexaVPN/docs/architecture.md

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.