polaris-vpn 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-06-28
+
+### Fixed
+- Gracefully handled interactive `sudo` password prompts during WireGuard configuration when running in `--json` mode.
+- Improved robust error handling for `wg-quick` start/stop routines.
+
+## [0.3.0] - 2026-06-28
+
+### Added
+- Automated system-wide VPN deployment command (`polaris deploy --server user@host`) for Ubuntu 22.04.
+- Peer command namespace (`polaris peer add/list/remove/qr`) to manage multiple WireGuard client connections.
+- Terminal QR code generation (`polaris peer qr <name>`) using `qrcode-terminal` for mobile client pairing.
+- OS-level Network Kill Switch (`polaris config set kill-switch true`) for Linux (`iptables`) and macOS (`pfctl`) interfaces.
+- Pure JavaScript base64 Curve25519/X25519 key derivation helper using standard Node.js `crypto` (no local binary `wg` CLI command dependency).
+- Integrated smart auto-detection mode fallback sequence (`wireguard` -> `tls` -> `ssh`) for client tunnel startup.
+
 ## [0.2.0] - 2026-06-28
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polaris-vpn",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
   "type": "module",
   "bin": {
@@ -40,6 +40,9 @@
     "node-fetch": "^3.3.2",
     "node-notifier": "^10.0.1",
     "ora": "^9.4.1",
-    "socks-proxy-agent": "^10.1.0"
+    "qrcode-terminal": "^0.12.0",
+    "socks-proxy-agent": "^10.1.0",
+    "ssh2": "^1.17.0",
+    "wireguard-tools": "^0.1.0"
   }
 }

package/src/cli.js

@@ -22,10 +22,10 @@ const willPrintJson = () => process.argv.includes('--json');
 
 program
   .command('start')
-  .description('Start the encrypted SSH or TLS tunnel')
-  .option('-s, --server <user@host>', 'SSH/TLS server to connect to')
+  .description('Start the encrypted SSH, TLS or WireGuard tunnel')
+  .option('-s, --server <user@host>', 'SSH/TLS/WireGuard server to connect to')
   .option('-p, --port <number>', 'Local SOCKS5 port to bind', '1080')
-  .option('-m, --mode <type>', 'Tunnel mode: ssh, tls or auto', 'auto')
+  .option('-m, --mode <type>', 'Tunnel mode: ssh, tls, wireguard or auto', 'auto')
   .action(async (options, cmd) => {
     if (!cmd.optsWithGlobals().json) printBanner();
     try {
@@ -168,6 +168,107 @@ dnsCmd
     }
   });
 
+program
+  .command('deploy')
+  .description('Provision a fresh Ubuntu server as a WireGuard server')
+  .requiredOption('-s, --server <user@host>', 'SSH server to configure')
+  .option('-i, --identity <path>', 'SSH private key file path')
+  .option('-p, --password <password>', 'SSH password (alternative to identity)')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const run = (await import('./commands/deploy.js')).default;
+      await run(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+const peerCmd = program.command('peer').description('Manage WireGuard client peers');
+
+peerCmd
+  .command('add <name>')
+  .description('Generate and add a new peer config')
+  .action(async (name, options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { peerAdd } = await import('./commands/peer.js');
+      await peerAdd(name, cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+peerCmd
+  .command('list')
+  .description('List all active peer configurations')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { peerList } = await import('./commands/peer.js');
+      await peerList(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+peerCmd
+  .command('remove <name>')
+  .description('Revoke a peer from the server')
+  .action(async (name, options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { peerRemove } = await import('./commands/peer.js');
+      await peerRemove(name, cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+peerCmd
+  .command('qr <name>')
+  .description('Show peer configuration QR code')
+  .action(async (name, options, cmd) => {
+    try {
+      const { peerQr } = await import('./commands/peer.js');
+      await peerQr(name, cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+const configCmd = program.command('config').description('Configure polaris settings');
+configCmd
+  .command('set <key> <value>')
+  .description('Set a configuration setting (e.g. kill-switch true)')
+  .action(async (key, value, options, cmd) => {
+    const isJson = cmd.optsWithGlobals().json;
+    if (!isJson) printBanner();
+    try {
+      if (key === 'kill-switch') {
+        const val = value === 'true';
+        const { setKillSwitchConfig } = await import('./utils/kill-switch.js');
+        setKillSwitchConfig(val);
+        const { printSuccess } = await import('./utils/display.js');
+        if (!isJson) {
+          printSuccess(`Set config 'kill-switch' to ${val}`);
+        } else {
+          console.log(JSON.stringify({ success: true, key, value: val }));
+        }
+      } else {
+        throw new Error(`Unknown config key '${key}'`);
+      }
+    } catch (err) {
+      if (!isJson) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
 program.parseAsync(process.argv).catch(err => {
   if (!willPrintJson()) printError('Fatal error', err);
   process.exit(1);

package/src/commands/deploy.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { printSuccess, printError, createSpinner, printInfo } from '../utils/display.js';
+import { deployServer } from '../core/deploy-service.js';
+import startCommand from './start.js';
+
+export default async (options) => {
+  const isJson = options.json;
+  const server = options.server;
+  
+  if (!server) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: 'Missing --server argument' }));
+    } else {
+      printError('You must specify a server with --server <user@host>');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const spinner = isJson ? null : createSpinner('Initiating server deployment...').start();
+
+  try {
+    const res = await deployServer(server, {
+      privateKey: options.identity,
+      password: options.password,
+      onProgress: (msg) => {
+        if (spinner) spinner.text = msg;
+      }
+    });
+
+    if (spinner) {
+      spinner.succeed('Server provisioning completed successfully!');
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, ...res }));
+    } else {
+      printSuccess(`WireGuard configured on remote VPS ${server}`);
+      printInfo(`Local Client Config: ${res.clientConfPath}`);
+      printInfo(`Client Public Key  : ${res.clientPublicKey}`);
+      printInfo(`Server Public Key  : ${res.serverPublicKey}`);
+      console.log(chalk.cyan('\nStarting WireGuard tunnel connection locally...\n'));
+    }
+
+    // Automatically trigger local connection
+    await startCommand({ mode: 'wireguard', json: isJson });
+
+  } catch (err) {
+    if (spinner) spinner.fail('Deployment failed');
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Deployment failed', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/commands/peer.js

@@ -0,0 +1,121 @@
+import fs from 'fs';
+import chalk from 'chalk';
+import qrcode from 'qrcode-terminal';
+import { printSuccess, printError, createSpinner, printInfo, createTable } from '../utils/display.js';
+import { addPeer, listPeers, removePeer, getLocalPeerConfPath } from '../core/peer-service.js';
+
+export const peerAdd = async (name, options) => {
+  const isJson = options.json;
+  const spinner = isJson ? null : createSpinner(`Creating peer '${name}' on server...`).start();
+
+  try {
+    const res = await addPeer(name);
+    if (spinner) spinner.succeed(`Peer '${name}' created successfully!`);
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, ...res }));
+    } else {
+      printSuccess(`Saved local peer profile: ${res.confPath}`);
+      printInfo(`IP Assigned: ${res.ip}`);
+      printInfo(`Public Key : ${res.publicKey}`);
+      console.log(chalk.cyan('\nScan this QR code with the WireGuard app on your mobile device:\n'));
+      
+      const confString = fs.readFileSync(res.confPath, 'utf-8');
+      qrcode.generate(confString, { small: true });
+    }
+  } catch (err) {
+    if (spinner) spinner.fail('Failed to add peer');
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to add peer', err);
+    }
+    process.exitCode = 1;
+  }
+};
+
+export const peerList = async (options) => {
+  const isJson = options.json;
+  const spinner = isJson ? null : createSpinner('Fetching peer list...').start();
+
+  try {
+    const peers = await listPeers();
+    if (spinner) spinner.stop();
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, peers }));
+      return;
+    }
+
+    if (peers.length === 0) {
+      printInfo('No peers configured on server.');
+      return;
+    }
+
+    const table = createTable(['Name', 'Assigned IP', 'Latest Handshake', 'Transfer Received/Sent']);
+    
+    for (const p of peers) {
+      table.push([
+        chalk.green.bold(p.name),
+        p.ip,
+        p.handshake,
+        `${p.transferRx} / ${p.transferTx}`
+      ]);
+    }
+
+    console.log('\n' + table.toString() + '\n');
+  } catch (err) {
+    if (spinner) spinner.stop();
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to list peers', err);
+    }
+    process.exitCode = 1;
+  }
+};
+
+export const peerRemove = async (name, options) => {
+  const isJson = options.json;
+  const spinner = isJson ? null : createSpinner(`Revoking peer '${name}'...`).start();
+
+  try {
+    await removePeer(name);
+    if (spinner) spinner.succeed(`Peer '${name}' revoked from server.`);
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true }));
+    }
+  } catch (err) {
+    if (spinner) spinner.fail('Failed to remove peer');
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to remove peer', err);
+    }
+    process.exitCode = 1;
+  }
+};
+
+export const peerQr = async (name, options) => {
+  const isJson = options.json;
+
+  try {
+    const confPath = getLocalPeerConfPath(name);
+    const confString = fs.readFileSync(confPath, 'utf-8');
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, config: confString }));
+    } else {
+      console.log(chalk.cyan(`\nQR code for peer configuration '${name}':\n`));
+      qrcode.generate(confString, { small: true });
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to retrieve QR code', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/commands/start.js

@@ -1,9 +1,15 @@
 import chalk from 'chalk';
 import tls from 'tls';
-import { printError, printSuccess, createSpinner } from '../utils/display.js';
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { printError, printSuccess, createSpinner, printInfo } from '../utils/display.js';
 import { getPublicIp, getProxiedIp } from '../net/ip-check.js';
 import { getProfiles } from '../core/profile-service.js';
 import { getActiveTunnel, startTunnel } from '../core/tunnel-service.js';
+import { CONFIG_DIR } from '../utils/config.js';
+
+const WG_CONF = path.join(CONFIG_DIR, 'wg', 'wg0.conf');
 
 const detectTlsServer = (host, port = 8443) => {
   return new Promise((resolve) => {
@@ -28,6 +34,15 @@ const detectTlsServer = (host, port = 8443) => {
   });
 };
 
+const hasWgQuick = () => {
+  try {
+    const res = spawnSync('which', ['wg-quick'], { encoding: 'utf-8' });
+    return res.status === 0;
+  } catch (e) {
+    return false;
+  }
+};
+
 export default async (options) => {
   const isJson = options.json;
   let server = options.server;
@@ -55,7 +70,7 @@ export default async (options) => {
     if (isJson) {
       console.log(JSON.stringify({ error: 'Tunnel already running', pid: info.pid }));
     } else {
-      printError(`Tunnel is already running (PID: ${info.pid}) connected to ${info.server}. Run "polaris stop" first.`);
+      printError(`Tunnel is already running connected to ${info.server}. Run "polaris stop" first.`);
     }
     process.exitCode = 1;
     return;
@@ -74,17 +89,21 @@ export default async (options) => {
     let actualMode = requestedMode;
 
     if (requestedMode === 'auto') {
-      if (!isJson) {
-        spinner.text = 'Checking server for TLS support...';
-        spinner.start();
-      }
-      const hasTls = await detectTlsServer(hostPart, 8443);
-      if (hasTls) {
-        actualMode = 'tls';
+      if (fs.existsSync(WG_CONF) && hasWgQuick()) {
+        actualMode = 'wireguard';
       } else {
-        actualMode = 'ssh';
         if (!isJson) {
-          spinner.info('TLS server not detected. Falling back to SSH mode...');
+          spinner.text = 'Checking server for TLS support...';
+          spinner.start();
+        }
+        const hasTls = await detectTlsServer(hostPart, 8443);
+        if (hasTls) {
+          actualMode = 'tls';
+        } else {
+          actualMode = 'ssh';
+          if (!isJson) {
+            spinner.info('TLS server not detected. Falling back to SSH mode...');
+          }
         }
       }
     }
@@ -94,25 +113,43 @@ export default async (options) => {
       spinner.start();
     }
 
-    const res = await startTunnel(server, port, actualMode);
-    
-    if (!isJson) {
-      spinner.text = 'Verifying IP through proxy...';
-    }
+    const res = await startTunnel(server, port, actualMode, isJson);
     
-    const newIp = await getProxiedIp(port);
-    
-    if (!isJson) {
-      spinner.stop();
-      printSuccess(`Tunnel established successfully to ${server} (${actualMode.toUpperCase()} mode)`);
-      console.log(`\n  ${chalk.dim('Old IP:')} ${chalk.red(oldIp)}`);
-      console.log(`  ${chalk.dim('New IP:')} ${chalk.green(newIp)}`);
-      console.log(`  ${chalk.dim('Proxy :')} ${chalk.cyan(`socks5://127.0.0.1:${port}`)}`);
+    if (actualMode === 'wireguard') {
+      if (!isJson) {
+        spinner.text = 'Waiting for interface to configure...';
+      }
+      await new Promise(r => setTimeout(r, 2000));
+      
+      if (!isJson) {
+        spinner.text = 'Verifying system-wide IP...';
+      }
+      const newIp = await getPublicIp();
       
-      console.log(chalk.dim('\nTunnel is running in the background. Leave this terminal or close it, it will stay alive.'));
-      console.log(chalk.dim('Run "polaris status" to check, or "polaris stop" to end.'));
+      if (!isJson) {
+        spinner.stop();
+        printSuccess(`WireGuard full tunnel established successfully to ${server}`);
+        console.log(`\n  ${chalk.dim('Old IP:')} ${chalk.red(oldIp)}`);
+        console.log(`  ${chalk.dim('New IP:')} ${chalk.green(newIp)}`);
+        console.log(`  ${chalk.dim('Routing:')} System-wide (All OS traffic)`);
+      } else {
+        console.log(JSON.stringify({ success: true, oldIp, newIp, mode: 'wireguard', pid: res.pid }));
+      }
     } else {
-      console.log(JSON.stringify({ success: true, oldIp, newIp, proxy: `socks5://127.0.0.1:${port}`, pid: res.pid, mode: actualMode }));
+      if (!isJson) {
+        spinner.text = 'Verifying IP through proxy...';
+      }
+      const newIp = await getProxiedIp(port);
+      
+      if (!isJson) {
+        spinner.stop();
+        printSuccess(`Tunnel established successfully to ${server} (${actualMode.toUpperCase()} mode)`);
+        console.log(`\n  ${chalk.dim('Old IP:')} ${chalk.red(oldIp)}`);
+        console.log(`  ${chalk.dim('New IP:')} ${chalk.green(newIp)}`);
+        console.log(`  ${chalk.dim('Proxy :')} ${chalk.cyan(`socks5://127.0.0.1:${port}`)}`);
+      } else {
+        console.log(JSON.stringify({ success: true, oldIp, newIp, proxy: `socks5://127.0.0.1:${port}`, pid: res.pid, mode: actualMode }));
+      }
     }
 
   } catch (err) {

package/src/commands/stop.js

@@ -5,7 +5,7 @@ export default async (options) => {
   const isJson = options.json;
   
   try {
-    const info = stopActiveTunnel();
+    const info = stopActiveTunnel(isJson);
     if (!info) {
       if (isJson) {
         console.log(JSON.stringify({ success: true, message: 'No active tunnel found.' }));

package/src/core/deploy-service.js

@@ -0,0 +1,150 @@
+import { Client } from 'ssh2';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { generateKeyPair } from '../tunnel/wg.js';
+import { ensureDir, CONFIG_DIR } from '../utils/config.js';
+
+const getDefaultPrivateKey = () => {
+  const keys = ['id_rsa', 'id_ed25519', 'id_ecdsa', 'id_dsa'];
+  for (const k of keys) {
+    const p = path.join(os.homedir(), '.ssh', k);
+    if (fs.existsSync(p)) {
+      return fs.readFileSync(p);
+    }
+  }
+  return null;
+};
+
+const sshExec = (client, command) => {
+  return new Promise((resolve, reject) => {
+    client.exec(command, (err, stream) => {
+      if (err) return reject(err);
+      let stdout = '';
+      let stderr = '';
+      stream.on('close', (code) => {
+        resolve({ code, stdout, stderr });
+      }).on('data', (data) => {
+        stdout += data.toString('utf8');
+      }).stderr.on('data', (data) => {
+        stderr += data.toString('utf8');
+      });
+    });
+  });
+};
+
+export const deployServer = async (serverStr, options = {}) => {
+  const parts = serverStr.split('@');
+  const username = parts.length > 1 ? parts[0] : 'ubuntu';
+  const host = parts.length > 1 ? parts[1] : parts[0];
+  
+  const privateKey = options.privateKey 
+    ? fs.readFileSync(options.privateKey) 
+    : getDefaultPrivateKey();
+
+  if (!privateKey && !options.password) {
+    throw new Error('No SSH authentication method found. Please configure default SSH keys or specify key path/password.');
+  }
+
+  // 1. Generate local keys
+  const serverKeys = generateKeyPair();
+  const clientKeys = generateKeyPair();
+
+  const conn = new Client();
+
+  return new Promise((resolve, reject) => {
+    conn.on('ready', async () => {
+      try {
+        const onProgress = options.onProgress || (() => {});
+
+        // Step 1: Install packages
+        onProgress('Installing WireGuard and UFW on remote VPS...');
+        let res = await sshExec(conn, 'sudo apt-get update -y && sudo apt-get install -y wireguard ufw');
+        if (res.code !== 0) throw new Error(`Installation failed: ${res.stderr}`);
+
+        // Step 2: Enable packet forwarding
+        onProgress('Enabling IPv4 forwarding...');
+        res = await sshExec(conn, 'sudo sysctl -w net.ipv4.ip_forward=1 && echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf');
+        if (res.code !== 0) throw new Error(`IPv4 forwarding setup failed: ${res.stderr}`);
+
+        // Step 3: Detect default interface
+        onProgress('Detecting default interface...');
+        res = await sshExec(conn, "ip route show default | awk '/default/ {print $5}'");
+        const ethInterface = res.stdout.trim() || 'eth0';
+
+        // Step 4: Write server config
+        onProgress('Configuring WireGuard server wg0...');
+        const serverConf = `[Interface]
+PrivateKey = ${serverKeys.privateKey}
+Address = 10.0.0.1/24
+ListenPort = 51820
+PostUp = ufw route allow in on wg0; iptables -t nat -A POSTROUTING -o ${ethInterface} -j MASQUERADE
+PostDown = ufw route delete allow in on wg0; iptables -t nat -D POSTROUTING -o ${ethInterface} -j MASQUERADE
+
+[Peer]
+PublicKey = ${clientKeys.publicKey}
+AllowedIPs = 10.0.0.2/32
+`;
+
+        res = await sshExec(conn, `cat << 'EOF' > /tmp/wg0.conf\n${serverConf}\nEOF\nsudo mv /tmp/wg0.conf /etc/wireguard/wg0.conf && sudo chmod 600 /etc/wireguard/wg0.conf`);
+        if (res.code !== 0) throw new Error(`Server config write failed: ${res.stderr}`);
+
+        // Step 5: Start service
+        onProgress('Starting WireGuard interface...');
+        res = await sshExec(conn, 'sudo systemctl stop wg-quick@wg0 || true && sudo systemctl start wg-quick@wg0 && sudo systemctl enable wg-quick@wg0');
+        if (res.code !== 0) throw new Error(`Starting WireGuard failed: ${res.stderr}`);
+
+        // Step 6: Configure UFW firewall
+        onProgress('Configuring UFW firewall...');
+        res = await sshExec(conn, 'sudo ufw allow 51820/udp && sudo ufw allow 22/tcp && echo "y" | sudo ufw enable');
+        if (res.code !== 0) throw new Error(`Firewall setup failed: ${res.stderr}`);
+
+        // Step 7: Write client config locally
+        onProgress('Saving local client configuration...');
+        const clientConf = `[Interface]
+PrivateKey = ${clientKeys.privateKey}
+Address = 10.0.0.2/24
+DNS = 1.1.1.1
+
+[Peer]
+PublicKey = ${serverKeys.publicKey}
+Endpoint = ${host}:51820
+AllowedIPs = 0.0.0.0/0
+PersistentKeepalive = 25
+`;
+
+        const wgDir = path.join(CONFIG_DIR, 'wg');
+        ensureDir(wgDir);
+        
+        // Save client config
+        const clientConfPath = path.join(wgDir, 'wg0.conf');
+        fs.writeFileSync(clientConfPath, clientConf, 'utf-8');
+
+        // Also save provisioning info to config
+        fs.writeFileSync(path.join(wgDir, 'deploy.json'), JSON.stringify({
+          server: serverStr,
+          serverPublicKey: serverKeys.publicKey,
+          clientPublicKey: clientKeys.publicKey,
+          interface: ethInterface,
+          timestamp: new Date().toISOString()
+        }, null, 2), 'utf-8');
+
+        conn.end();
+        resolve({ clientConfPath, clientPublicKey: clientKeys.publicKey, serverPublicKey: serverKeys.publicKey });
+      } catch (err) {
+        conn.end();
+        reject(err);
+      }
+    }).on('error', (err) => {
+      reject(err);
+    });
+
+    conn.connect({
+      host,
+      port: options.port || 22,
+      username,
+      privateKey,
+      password: options.password
+    });
+  });
+};

package/src/core/peer-service.js

@@ -0,0 +1,238 @@
+import { Client } from 'ssh2';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { generateKeyPair } from '../tunnel/wg.js';
+import { CONFIG_DIR, ensureDir } from '../utils/config.js';
+
+const DEPLOY_JSON = path.join(CONFIG_DIR, 'wg', 'deploy.json');
+
+const getDeployInfo = () => {
+  if (!fs.existsSync(DEPLOY_JSON)) {
+    throw new Error('No deployment found. Please deploy a server first using "polaris deploy".');
+  }
+  return JSON.parse(fs.readFileSync(DEPLOY_JSON, 'utf-8'));
+};
+
+const getDefaultPrivateKey = () => {
+  const keys = ['id_rsa', 'id_ed25519', 'id_ecdsa', 'id_dsa'];
+  for (const k of keys) {
+    const p = path.join(os.homedir(), '.ssh', k);
+    if (fs.existsSync(p)) {
+      return fs.readFileSync(p);
+    }
+  }
+  return null;
+};
+
+const sshConnect = (info) => {
+  const parts = info.server.split('@');
+  const username = parts.length > 1 ? parts[0] : 'ubuntu';
+  const host = parts.length > 1 ? parts[1] : parts[0];
+  
+  const privateKey = getDefaultPrivateKey();
+
+  const conn = new Client();
+  return new Promise((resolve, reject) => {
+    conn.on('ready', () => resolve(conn))
+        .on('error', (err) => reject(err));
+    conn.connect({
+      host,
+      port: 22,
+      username,
+      privateKey
+    });
+  });
+};
+
+const sshExec = (client, command) => {
+  return new Promise((resolve, reject) => {
+    client.exec(command, (err, stream) => {
+      if (err) return reject(err);
+      let stdout = '';
+      let stderr = '';
+      stream.on('close', (code) => {
+        resolve({ code, stdout, stderr });
+      }).on('data', (data) => {
+        stdout += data.toString('utf8');
+      }).stderr.on('data', (data) => {
+        stderr += data.toString('utf8');
+      });
+    });
+  });
+};
+
+export const addPeer = async (name) => {
+  const info = getDeployInfo();
+  const conn = await sshConnect(info);
+
+  try {
+    // 1. Read remote wg0.conf
+    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    if (catRes.code !== 0) throw new Error(`Failed to read server config: ${catRes.stderr}`);
+    const configContent = catRes.stdout;
+
+    // Check if name already exists
+    if (configContent.includes(`# Name: ${name}\n`) || configContent.includes(`# Name: ${name}\r\n`)) {
+      throw new Error(`Peer with name '${name}' already exists.`);
+    }
+
+    // Parse IPs to find next free IP
+    const ipMatches = [...configContent.matchAll(/AllowedIPs\s*=\s*10\.0\.0\.(\d+)\/32/g)];
+    let nextIpIndex = 2;
+    if (ipMatches.length > 0) {
+      const indices = ipMatches.map(m => parseInt(m[1], 10));
+      nextIpIndex = Math.max(...indices) + 1;
+    }
+    
+    if (nextIpIndex >= 254) {
+      throw new Error('IP range exhausted for subnet 10.0.0.0/24');
+    }
+
+    const peerIp = `10.0.0.${nextIpIndex}`;
+    const peerKeys = generateKeyPair();
+
+    // 2. Append peer to remote wg0.conf
+    const peerConfigBlock = `\n[Peer]
+# Name: ${name}
+PublicKey = ${peerKeys.publicKey}
+AllowedIPs = ${peerIp}/32
+`;
+
+    const writeCmd = `echo "${peerConfigBlock.replace(/"/g, '\\"')}" | sudo tee -a /etc/wireguard/wg0.conf`;
+    let res = await sshExec(conn, writeCmd);
+    if (res.code !== 0) throw new Error(`Failed to append remote peer: ${res.stderr}`);
+
+    // Sync remote wireguard
+    await sshExec(conn, 'sudo systemctl restart wg-quick@wg0');
+
+    // 3. Save peer config locally
+    const clientConf = `[Interface]
+PrivateKey = ${peerKeys.privateKey}
+Address = ${peerIp}/24
+DNS = 1.1.1.1
+
+[Peer]
+PublicKey = ${info.serverPublicKey}
+Endpoint = ${info.server.split('@')[1]}:51820
+AllowedIPs = 0.0.0.0/0
+PersistentKeepalive = 25
+`;
+
+    const peersDir = path.join(CONFIG_DIR, 'wg', 'peers');
+    ensureDir(peersDir);
+    const peerConfPath = path.join(peersDir, `${name}.conf`);
+    fs.writeFileSync(peerConfPath, clientConf, 'utf-8');
+
+    conn.end();
+    return { name, ip: peerIp, publicKey: peerKeys.publicKey, confPath: peerConfPath };
+  } catch (err) {
+    conn.end();
+    throw err;
+  }
+};
+
+export const listPeers = async () => {
+  const info = getDeployInfo();
+  const conn = await sshConnect(info);
+
+  try {
+    // 1. Read remote configuration to parse names
+    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    if (catRes.code !== 0) throw new Error('Failed to read remote config');
+    const content = catRes.stdout;
+
+    // Parse blocks
+    const lines = content.split('\n');
+    const peersMap = {}; // publicKey -> name
+    let currentName = 'Default Client';
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.startsWith('# Name:')) {
+        currentName = line.substring(7).trim();
+      }
+      if (line.startsWith('PublicKey')) {
+        const pk = line.split('=')[1].trim();
+        peersMap[pk] = currentName;
+      }
+    }
+
+    // 2. Fetch wg status
+    const showRes = await sshExec(conn, 'sudo wg show wg0 dump');
+    if (showRes.code !== 0) throw new Error('Failed to run wg show');
+    
+    const dumpLines = showRes.stdout.trim().split('\n');
+    const list = [];
+
+    // First line is server key info, subsequent lines are peers
+    for (let i = 1; i < dumpLines.length; i++) {
+      const parts = dumpLines[i].split('\t');
+      if (parts.length < 8) continue;
+      const [publicKey, , endpoint, allowedIps, latestHandshake, transferRx, transferTx] = parts;
+      
+      list.push({
+        name: peersMap[publicKey] || 'Unknown',
+        publicKey,
+        endpoint: endpoint === '(none)' ? 'Disconnected' : endpoint,
+        ip: allowedIps,
+        handshake: parseInt(latestHandshake, 10) === 0 ? 'Never' : `${Math.floor(Date.now() / 1000 - parseInt(latestHandshake, 10))}s ago`,
+        transferRx: `${Math.round(parseInt(transferRx, 10) / 1024 / 1024 * 100) / 100} MB`,
+        transferTx: `${Math.round(parseInt(transferTx, 10) / 1024 / 1024 * 100) / 100} MB`
+      });
+    }
+
+    conn.end();
+    return list;
+  } catch (err) {
+    conn.end();
+    throw err;
+  }
+};
+
+export const removePeer = async (name) => {
+  const info = getDeployInfo();
+  const conn = await sshConnect(info);
+
+  try {
+    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    if (catRes.code !== 0) throw new Error('Failed to read remote config');
+    const content = catRes.stdout;
+
+    if (!content.includes(`# Name: ${name}`)) {
+      throw new Error(`Peer '${name}' not found on server.`);
+    }
+
+    // Strip peer block from remote config
+    const blocks = content.split('[Peer]');
+    const filteredBlocks = blocks.filter(b => !b.includes(`# Name: ${name}`));
+    const newContent = filteredBlocks.join('[Peer]');
+
+    // Save remote config back
+    const writeRes = await sshExec(conn, `cat << 'EOF' > /tmp/wg0.conf\n${newContent}\nEOF\nsudo mv /tmp/wg0.conf /etc/wireguard/wg0.conf && sudo chmod 600 /etc/wireguard/wg0.conf`);
+    if (writeRes.code !== 0) throw new Error('Failed to update remote config');
+
+    // Sync remote wireguard
+    await sshExec(conn, 'sudo systemctl restart wg-quick@wg0');
+
+    // Remove local peer config if it exists
+    const peerConfPath = path.join(CONFIG_DIR, 'wg', 'peers', `${name}.conf`);
+    if (fs.existsSync(peerConfPath)) {
+      fs.unlinkSync(peerConfPath);
+    }
+
+    conn.end();
+    return true;
+  } catch (err) {
+    conn.end();
+    throw err;
+  }
+};
+
+export const getLocalPeerConfPath = (name) => {
+  const peerConfPath = path.join(CONFIG_DIR, 'wg', 'peers', `${name}.conf`);
+  if (!fs.existsSync(peerConfPath)) {
+    throw new Error(`Local config for peer '${name}' not found.`);
+  }
+  return peerConfPath;
+};

package/src/core/tunnel-service.js

@@ -1,26 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
 import { spawnSSH, waitForSocks } from '../tunnel/ssh.js';
 import { startTlsBackground } from '../tunnel/tls.js';
+import { startWgTunnel, stopWgTunnel } from '../tunnel/wg.js';
+import { enableKillSwitch, disableKillSwitch } from '../utils/kill-switch.js';
 import { loadDaemonState, clearDaemonState, killPid, saveDaemonState } from '../utils/daemon.js';
-import { TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE, ensureDir } from '../utils/config.js';
+import { TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE, CONFIG_DIR, ensureDir } from '../utils/config.js';
+
+const WG_CONF = path.join(CONFIG_DIR, 'wg', 'wg0.conf');
 
 export const getActiveTunnel = () => {
-  return loadDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE);
+  const info = loadDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE);
+  if (!info) return null;
+
+  // For WireGuard, PID file tracks start process, but we verify interface status
+  if (info.mode === 'wireguard') {
+    try {
+      const showRes = spawnSync('sudo', ['wg', 'show'], { encoding: 'utf-8' });
+      if (showRes.status !== 0 || !showRes.stdout.includes('interface:')) {
+        clearDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE);
+        return null;
+      }
+    } catch (e) {
+      clearDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE);
+      return null;
+    }
+  }
+  return info;
 };
 
-export const stopActiveTunnel = () => {
+export const stopActiveTunnel = (isJson = false) => {
   const info = getActiveTunnel();
   if (info) {
-    killPid(info.pid);
+    if (info.mode === 'wireguard') {
+      stopWgTunnel(WG_CONF, isJson);
+      disableKillSwitch(info.server);
+    } else {
+      killPid(info.pid);
+    }
   }
   clearDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE);
   return info;
 };
 
-export const startTunnel = async (server, port, mode = 'ssh') => {
+export const startTunnel = async (server, port, mode = 'ssh', isJson = false) => {
   const hostPart = server.includes('@') ? server.split('@')[1] : server;
   ensureDir();
 
   let pid;
+  if (mode === 'wireguard') {
+    if (!fs.existsSync(WG_CONF)) {
+      throw new Error(`WireGuard client configuration not found at ${WG_CONF}. Please provision the server first with "polaris deploy".`);
+    }
+
+    pid = startWgTunnel(WG_CONF, isJson);
+    
+    // Save state before enableKillSwitch in case sudo prompt needs to block
+    saveDaemonState(TUNNEL_PID_FILE, TUNNEL_CONFIG_FILE, {
+      pid,
+      server,
+      port: 0,
+      mode: 'wireguard',
+      startTime: new Date().toISOString()
+    });
+
+    enableKillSwitch(server);
+    return { pid, server, port: 0, mode: 'wireguard' };
+  } 
+  
   if (mode === 'tls') {
     pid = startTlsBackground(port, hostPart, 8443);
   } else {

package/src/tunnel/wg.js

@@ -0,0 +1,59 @@
+import { spawnSync, spawn } from 'child_process';
+import crypto from 'crypto';
+
+// Pure JS Curve25519/X25519 key generator matching WireGuard format
+export const generateKeyPair = () => {
+  const rawPriv = crypto.randomBytes(32);
+  // Apply Curve25519 private key clamping:
+  // - clear the lowest three bits of the first byte
+  // - clear the highest bit of the last byte
+  // - set the second highest bit of the last byte
+  rawPriv[0] &= 248;
+  rawPriv[31] &= 127;
+  rawPriv[31] |= 64;
+
+  const keyDer = Buffer.concat([
+    Buffer.from('302e020100300506032b656e04220420', 'hex'),
+    rawPriv
+  ]);
+  
+  const priv = crypto.createPrivateKey({ key: keyDer, format: 'der', type: 'pkcs8' });
+  const pub = crypto.createPublicKey(priv);
+  const pubRaw = pub.export({ format: 'der', type: 'spki' }).slice(-32);
+
+  return {
+    privateKey: rawPriv.toString('base64'),
+    publicKey: pubRaw.toString('base64')
+  };
+};
+
+export const startWgTunnel = (confPath, isJson = false) => {
+  const sudoCheck = spawnSync('sudo', ['-n', 'true']);
+  if (sudoCheck.status !== 0 && isJson) {
+    throw new Error('Sudo privileges required. Please run with "sudo polaris start ..." for JSON mode.');
+  }
+
+  const res = spawnSync('sudo', ['wg-quick', 'up', confPath], {
+    stdio: isJson ? 'ignore' : 'inherit'
+  });
+  
+  if (res.status !== 0) {
+    throw new Error(`wg-quick up failed with code ${res.status}`);
+  }
+  return process.pid;
+};
+
+export const stopWgTunnel = (confPath, isJson = false) => {
+  const sudoCheck = spawnSync('sudo', ['-n', 'true']);
+  if (sudoCheck.status !== 0 && isJson) {
+    throw new Error('Sudo privileges required. Please run with "sudo polaris stop" for JSON mode.');
+  }
+
+  const res = spawnSync('sudo', ['wg-quick', 'down', confPath], {
+    stdio: isJson ? 'ignore' : 'inherit'
+  });
+  
+  if (res.status !== 0) {
+    throw new Error(`wg-quick down failed with code ${res.status}`);
+  }
+};

package/src/utils/kill-switch.js

@@ -0,0 +1,69 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import { store } from './config.js';
+
+export const isKillSwitchConfigured = () => {
+  return store.get('kill-switch', false);
+};
+
+export const setKillSwitchConfig = (enabled) => {
+  store.set('kill-switch', enabled);
+};
+
+export const enableKillSwitch = (serverIp) => {
+  if (!isKillSwitchConfigured()) return;
+  
+  const platform = os.platform();
+  const hostIp = serverIp.includes('@') ? serverIp.split('@')[1] : serverIp;
+
+  try {
+    if (platform === 'linux') {
+      // 1. Loopback
+      execSync('sudo iptables -C OUTPUT -o lo -j ACCEPT || sudo iptables -A OUTPUT -o lo -j ACCEPT', { stdio: 'ignore' });
+      // 2. WireGuard interface (default wg0)
+      execSync('sudo iptables -C OUTPUT -o wg0 -j ACCEPT || sudo iptables -A OUTPUT -o wg0 -j ACCEPT', { stdio: 'ignore' });
+      // 3. Connect to the VPS server
+      execSync(`sudo iptables -C OUTPUT -d ${hostIp} -j ACCEPT || sudo iptables -A OUTPUT -d ${hostIp} -j ACCEPT`, { stdio: 'ignore' });
+      // 4. Drop other outbound connections
+      execSync('sudo iptables -C OUTPUT -j REJECT || sudo iptables -A OUTPUT -j REJECT', { stdio: 'ignore' });
+    } else if (platform === 'darwin') {
+      // macOS Packet Filter (PF) setup
+      const pfRules = `
+block out all
+pass out on lo0 all
+pass out on utun all
+pass out proto {tcp, udp} to ${hostIp}
+`;
+      fs.writeFileSync('/tmp/polaris_pf.conf', pfRules, 'utf-8');
+      execSync('sudo pfctl -ef /tmp/polaris_pf.conf', { stdio: 'ignore' });
+    }
+  } catch (err) {
+    console.error('Failed to enable kill switch rules:', err.message);
+  }
+};
+
+export const disableKillSwitch = (serverIp) => {
+  const platform = os.platform();
+  const hostIp = serverIp.includes('@') ? serverIp.split('@')[1] : serverIp;
+
+  try {
+    if (platform === 'linux') {
+      execSync('sudo iptables -D OUTPUT -j REJECT', { stdio: 'ignore' });
+      execSync(`sudo iptables -D OUTPUT -d ${hostIp} -j ACCEPT`, { stdio: 'ignore' });
+      execSync('sudo iptables -D OUTPUT -o wg0 -j ACCEPT', { stdio: 'ignore' });
+      execSync('sudo iptables -D OUTPUT -o lo -j ACCEPT', { stdio: 'ignore' });
+    } else if (platform === 'darwin') {
+      execSync('sudo pfctl -d', { stdio: 'ignore' });
+      // Reload default system rules
+      if (fs.existsSync('/etc/pf.conf')) {
+        execSync('sudo pfctl -f /etc/pf.conf', { stdio: 'ignore' });
+      }
+      if (fs.existsSync('/tmp/polaris_pf.conf')) {
+        fs.unlinkSync('/tmp/polaris_pf.conf');
+      }
+    }
+  } catch (err) {
+    // Ignore cleanup errors
+  }
+};