Add Waylume Manifesto and update API routes for peer management

2025-08-17 21:56:59 +01:00
parent 573744a22d
commit 8b63de7db2
6 changed files with 574 additions and 253 deletions
--- a/README.md
+++ b/README.md
@@ -2,115 +2,96 @@

 ## About

-Waylume Server is the backend component of the Waylume premium VPN service. It provides a REST API for WireGuard VPN management and integrates with Supabase for server registration and heartbeat monitoring. The server is designed to be easily deployed with Docker and can be spun up quickly to expand VPN infrastructure.
-
-The server is written in Dart and uses process execution to interact with WireGuard tools. It is designed to be lightweight and efficient, making it suitable for deployment on various platforms, including cloud services and local servers.
+Waylume Server is a self-managing WireGuard VPN node that operates as part of the Waylume VPN infrastructure. Each server instance automatically registers with Supabase, manages WireGuard peer configurations, and responds to connection requests through Supabase Edge Functions. The server is designed for autonomous operation with minimal maintenance requirements.

 ## Architecture

 ```
 ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Client Apps   │───▶│    Supabase     │◄───│ Waylume Server  │
+│  Flutter Client │───▶│ Supabase Edge   │───▶│ Waylume Server  │
+│      App        │    │   Functions     │    │     Node        │
 └─────────────────┘    └─────────────────┘    └─────────────────┘
-                                                        │
-                                                        ▼
-                                               ┌─────────────────┐
-                                               │   WireGuard     │
-                                               └─────────────────┘
+                                │                        │
+                                ▼                        ▼
+                       ┌─────────────────┐    ┌─────────────────┐
+                       │   PostgreSQL    │    │   WireGuard     │
+                       │    Database     │    │   Interface     │
+                       └─────────────────┘    └─────────────────┘
 ```

-Client applications communicate through Supabase to discover available Waylume servers. Each server manages WireGuard connections via REST API and registers itself with Supabase for automatic discovery and load distribution.
+**Client Flow:**
+1. Flutter app requests available servers via `vpn-nodes-list` edge function
+2. User selects server and requests connection via `connection-request` edge function
+3. Edge function calls Waylume Server API to create WireGuard peer
+4. Server responds with peer configuration through Supabase
+5. Client receives WireGuard config and establishes VPN connection
+
+## Role in Waylume Ecosystem
+
+### Server Registration & Discovery
+- **Automatic Registration**: Servers register themselves in the `waylume_servers` table on startup
+- **Heartbeat Monitoring**: Continuous health reporting to maintain server availability status
+- **Geolocation Integration**: Provides location data for client server selection interface
+- **Load Distribution**: Multiple servers can be deployed for geographic distribution and load balancing
+
+### Integration with Supabase Edge Functions
+The server's REST API is exclusively accessed through Supabase Edge Functions:
+
+- **`connection-request`**: Calls `POST /api/peers` to create new VPN peers
+- **Session Management**: Works with `vpn_sessions` table for connection tracking
+- **Configuration Delivery**: Peer configs are delivered through Supabase to clients
+
+### WireGuard Management
+- **Interface Initialization**: Automatically configures `wg0` interface on startup
+- **Dynamic Peer Creation**: Creates peers with unique keys and IP assignments
+- **Traffic Control**: Implements speed limiting and data caps per peer
+- **Peer Isolation**: Enforces security rules to prevent peer-to-peer communication
+- **Cleanup Operations**: Removes peers and associated configurations on disconnect

 ## Features

-### Core Functionality
- **WireGuard Interface Management**: Automatic initialization and configuration of WireGuard server interface
- **Peer Management**: Create, delete, and configure VPN peers dynamically
- **Traffic Control**: Speed limiting and data cap enforcement per peer
- **Server Registration**: Automatic registration with Supabase backend
- **Health Monitoring**: Continuous heartbeat system for server availability
+### Self-Managing Operations
+- **Zero-Touch Deployment**: Fully automated setup with Docker
+- **Health Monitoring**: Built-in health checks and status reporting
+- **Automatic Recovery**: Handles WireGuard interface failures and restarts
+- **Resource Management**: Efficient peer lifecycle management

-### API Endpoints
+### Security & Traffic Control
+- **Peer Isolation**: iptables rules prevent peer-to-peer communication
+- **Bandwidth Control**: HTB-based speed limiting per peer
+- **Data Quotas**: iptables quota enforcement for usage limits
+- **IP Management**: Automatic IP assignment from managed subnets
+
+### API Endpoints (Internal Use Only)
+
+> **⚠️ Important**: These endpoints are for internal server management through Supabase Edge Functions only. They are not designed for direct client access and lack authentication for security reasons.

 #### `POST /api/peers`
-Create a new VPN peer with automatically generated WireGuard keys and IP assignment.
-
-**Request:** No body required
-**Response:**
-```json
-{
-  "success": true,
-  "peer": {
-    "privateKey": "base64_private_key",
-    "publicKey": "base64_public_key", 
-    "ip": "10.0.0.x"
-  },
-  "config": "complete_wireguard_client_config"
-}
-```
+Creates a new WireGuard peer with generated keys and IP assignment.
+- **Called by**: `connection-request` edge function
+- **Purpose**: Establish new VPN connection for authenticated user

 #### `POST /api/peers/delete`
-Remove a VPN peer and clean up associated WireGuard configuration.
-
-**Request Body:**
-```json
-{
-  "publicKey": "peer_public_key_here"
-}
-```
+Removes a WireGuard peer and cleans up configuration.
+- **Called by**: Session cleanup processes
+- **Purpose**: Terminate VPN connections and free resources

 #### `POST /api/peers/speed-limit`
-Set bidirectional bandwidth limits for a peer (controls both upload and download speeds).
-
-**Request Body:**
-```json
-{
-  "publicKey": "peer_public_key_here",
-  "bytesPerSecond": 125000
-}
-```
-*Note: 125000 bytes/s = 1000 kbps = 1 Mbps*
-*Use -1 for unlimited speed*
-
-**Common Speed Conversions:**
- 125 KB/s = 1 Mbps
- 1,250 KB/s = 10 Mbps  
- 12,500 KB/s = 100 Mbps
- -1 = Unlimited
+Applies bandwidth limitations to specific peers.
+- **Called by**: Subscription management functions
+- **Purpose**: Enforce plan-based speed limits

 #### `POST /api/peers/data-cap`
-Set total data usage limits for a peer using iptables quota rules.
-
-**Request Body:**
-```json
-{
-  "publicKey": "peer_public_key_here", 
-  "quotaBytes": 1073741824
-}
-```
-*Note: 1073741824 bytes = 1 GB*
-*Use -1 for unlimited data*
-
-**Common Data Conversions:**
- 1 GB = 1,073,741,824 bytes
- 10 GB = 10,737,418,240 bytes
- 100 GB = 107,374,182,400 bytes
- -1 = Unlimited
-
-#### `POST /api/peers/config`
-Retrieve peer configuration (currently not implemented - returns 404).
-
-### Security Features
- Peer isolation using iptables rules (prevents peer-to-peer communication)
- Traffic shaping and quota enforcement
- Automatic IP address assignment within 10.0.0.0/8 range
- Secure key generation for each peer
+Sets data usage quotas for peers.
+- **Called by**: Usage monitoring systems
+- **Purpose**: Enforce plan-based data allowances

 ## Prerequisites

 - Docker and Docker Compose
 - WireGuard kernel module support
- Supabase project with `waylume_servers` table
+- Supabase project with proper database schema
+- Network capabilities for WireGuard interface management

 ## Environment Variables

@@ -118,122 +99,131 @@ Create a `.env` file with the following variables:

 ```env
 # Supabase Configuration
-SUPABASE_URL=your_supabase_url
+SUPABASE_URL=your_supabase_project_url
 SUPABASE_KEY=your_supabase_anon_key

-# Server Configuration
+# Server Configuration  
 SERVER_ID=unique_server_identifier
 EXTERNAL_PORT=3000
+
+# Optional: Geographic Information
+SERVER_COUNTRY=United Kingdom
+SERVER_CITY=London
+SERVER_COORDS_LAT=51.5074
+SERVER_COORDS_LON=-0.1278
 ```

-## Quick Start
+## Quick Deployment

 ### Using Docker Compose (Recommended)

 1. Clone the repository
-2. Create your `.env` file with required variables
-3. Run the server:
+2. Create your `.env` file with required Supabase credentials
+3. Deploy the server:

 ```bash
 docker-compose up -d
 ```

-The server will be available on port 3000 (or your configured `EXTERNAL_PORT`).
+The server will:
+- Initialize WireGuard interface (`wg0`)
+- Register with your Supabase backend
+- Begin heartbeat monitoring
+- Start accepting API requests on port 3000

-### Building from Source
+### Verification

-1. Install Dart SDK (3.9.0-100.2.beta or later)
-2. Install dependencies:
-```bash
-dart pub get
-```
-3. Compile and run:
-```bash
-dart compile exe lib/main.dart -o waylume_server
-./waylume_server
+Check that the server registered successfully:
+
+```sql
+-- In your Supabase SQL editor
+SELECT * FROM waylume_servers WHERE id = 'your_server_id';
 ```

-## Docker Configuration
-
-The Docker setup includes:
- WireGuard tools and kernel module support
- iptables for traffic control and peer isolation
- Network capabilities (`NET_ADMIN`) for interface management
- UDP port 51820 for WireGuard traffic
- TCP port 3000 for REST API
-
-## API Usage Examples
-
-### Create a new peer
-```bash
-curl -X POST http://localhost:3000/api/peers
-```
-
-Response:
-```json
-{
-  "success": true,
-  "peer": {
-    "privateKey": "...",
-    "publicKey": "...",
-    "ip": "10.0.0.2"
-  },
-  "config": "[Interface]\nPrivateKey = ...\n..."
-}
-```
-
-### Delete a peer
-```bash
-curl -X POST http://localhost:3000/api/peers/delete \
-  -H "Content-Type: application/json" \
-  -d '{"publicKey": "PEER_PUBLIC_KEY_HERE"}'
-```
-
-### Set speed limit for peer
-```bash
-curl -X POST http://localhost:3000/api/peers/speed-limit \
-  -H "Content-Type: application/json" \
-  -d '{"publicKey": "PEER_PUBLIC_KEY_HERE", "bytesPerSecond": 125000}' # 125000 bytes/s = 1000 kbps
-```
-
-### Set data cap for peer
-```bash
-curl -X POST http://localhost:3000/api/peers/data-cap \
-  -H "Content-Type: application/json" \
-  -d '{"publicKey": "PEER_PUBLIC_KEY_HERE", "quotaBytes": 1073741824}' # 1073741824 bytes = 1024 MB
-```
-
-### Get peer config
-```bash
-curl -X POST http://localhost:3000/api/peers/config \
-  -H "Content-Type: application/json" \
-  -d '{"publicKey": "PEER_PUBLIC_KEY_HERE"}'
-```
-
-## Network Architecture
+## Network Configuration

 - **WireGuard Interface**: `wg0` on `10.0.0.1/24`
 - **Peer IP Range**: `10.0.0.2` - `10.255.255.254`
 - **WireGuard Port**: `51820/udp`
- **API Port**: `3000/tcp`
+- **API Port**: `3000/tcp` (internal access only)

-## Logging
+## Production Deployment

-The server provides detailed request logging including:
- Client IP addresses (with proxy header support)
- User agents
- Request methods and paths
- Timestamps
+### Security Considerations
+- Deploy behind a firewall with port 3000 restricted to Supabase Edge Functions
+- Use private networks when possible for API communication
+- Implement network segmentation for additional security
+- Monitor logs for unusual API access patterns
+
+### Scaling Strategy
+- Deploy multiple servers across different geographic regions
+- Use unique `SERVER_ID` values for each instance
+- Monitor server load through Supabase analytics
+- Implement auto-scaling based on connection demand
+
+### Monitoring & Maintenance
+- Server health is automatically reported to Supabase
+- Monitor `waylume_servers` table for server availability
+- Check Docker logs for operational issues
+- WireGuard interface status is self-managed

 ## Development

-The project structure:
+### Project Structure
 ```
 lib/
-├── config/          # Supabase configuration
-├── core/            # Utility functions
+├── config/          # Supabase configuration and credentials
+├── core/            # Utility functions and helpers
 ├── services/        # Core services (server, heartbeat, wireguard)
-├── web/             # HTTP routes and handlers
+├── web/             # HTTP routes and API handlers
 ├── wireguard/       # WireGuard-specific functionality
-└── main.dart        # Application entry point
+└── main.dart        # Application entry point and server initialization
+```
+
+### Testing Server Integration
+
+You can test the integration by triggering a connection request through your Supabase Edge Functions:
+
+```bash
+# Test server listing
+curl -X GET https://your-project.supabase.co/functions/v1/vpn-nodes-list
+
+# Test connection request (requires authentication)
+curl -X POST https://your-project.supabase.co/functions/v1/connection-request \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"server_id": "your_server_id"}'
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Server not appearing in node list:**
+- Check Supabase credentials in `.env`
+- Verify server registered in `waylume_servers` table
+- Ensure heartbeat process is running
+
+**WireGuard interface issues:**
+- Verify WireGuard kernel module is loaded: `lsmod | grep wireguard`
+- Check Docker has `NET_ADMIN` capability
+- Ensure `/dev/net/tun` is accessible
+
+**API connectivity problems:**
+- Verify port 3000 is accessible from Supabase Edge Functions
+- Check firewall rules and network configuration
+- Review Docker logs for startup errors
+
+### Logging
+
+The server provides comprehensive logging including:
+- Supabase registration and heartbeat status
+- WireGuard interface management
+- API request processing
+- Peer lifecycle events
+- Error conditions and recovery attempts
+
+Monitor logs with:
+```bash
+docker-compose logs -f waylume-server
 ```