polaris-vpn 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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
+- Companion `polaris-server` dynamic HTTP/TLS forwarding proxy on port 8443.
+- local DNS-over-HTTPS (DoH) resolver command namespace (`polaris dns start/stop/status`) on port 5354.
+- TLS tunnel client option (`polaris start --mode tls`).
+- Auto-reconnect with exponential backoff & keepalive monitoring.
+- Desktop alerts/notifications via `node-notifier`.
+- Refactored codebase to highly modular MVC structure with centralized configurations and daemon manager.
+- Static runner scripts to ensure full compatibility with global NPM installation permissions.
+
 ## [0.1.0] - 2026-06-27
 
 ### Added

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "polaris-vpn",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
   "type": "module",
   "bin": {
-    "polaris": "src/cli.js"
+    "polaris": "src/cli.js",
+    "polaris-server": "src/server/server.js"
   },
   "files": [
     "src",
@@ -35,8 +36,13 @@
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
     "conf": "^15.1.0",
+    "dns2": "^3.0.0",
     "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

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import path from 'path';
-import { printBanner, printError } from './ui/display.js';
+import { printBanner, printError } from './utils/display.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -22,9 +22,10 @@ const willPrintJson = () => process.argv.includes('--json');
 
 program
   .command('start')
-  .description('Start the encrypted SSH tunnel')
-  .option('-s, --server <user@host>', 'SSH 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, wireguard or auto', 'auto')
   .action(async (options, cmd) => {
     if (!cmd.optsWithGlobals().json) printBanner();
     try {
@@ -121,6 +122,153 @@ program
     }
   });
 
+const dnsCmd = program.command('dns').description('Manage local DNS-over-HTTPS resolver');
+
+dnsCmd
+  .command('start')
+  .description('Start the local DoH resolver')
+  .option('-p, --port <number>', 'Local port to bind', '5354')
+  .option('-u, --upstream <provider>', 'Upstream DoH provider (cloudflare, google, or custom URL)', 'cloudflare')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { dnsStart } = await import('./commands/dns.js');
+      await dnsStart(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+dnsCmd
+  .command('stop')
+  .description('Stop the local DoH resolver')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { dnsStop } = await import('./commands/dns.js');
+      await dnsStop(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+dnsCmd
+  .command('status')
+  .description('Show local DoH resolver status')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { dnsStatus } = await import('./commands/dns.js');
+      await dnsStatus(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+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/check.js

@@ -1,11 +1,13 @@
 import chalk from 'chalk';
-import { getTunnelInfo } from '../tunnel/ssh.js';
-import { getPublicIp, getProxiedIp, checkDns, checkIpv6Leak } from '../net/ip.js';
-import { createTable, createSpinner, printError } from '../ui/display.js';
+import { getActiveTunnel } from '../core/tunnel-service.js';
+import { getDnsStatus } from '../core/dns-service.js';
+import { getPublicIp, getProxiedIp, checkDns, checkIpv6Leak } from '../net/ip-check.js';
+import { createTable, createSpinner, printError } from '../utils/display.js';
 
 export default async (options) => {
   const isJson = options.json;
-  const info = getTunnelInfo();
+  const info = getActiveTunnel();
+  const dnsStatus = getDnsStatus();
   
   if (!isJson) {
     console.log(chalk.cyan.bold('\nRunning Privacy Check...\n'));
@@ -22,7 +24,7 @@ export default async (options) => {
       try {
         const tunnelIp = await getProxiedIp(info.port);
         results.ip = true;
-        details.ip = `Tunnel active: ${tunnelIp}`;
+        details.ip = `Tunnel active (${(info.mode || 'ssh').toUpperCase()}): ${tunnelIp}`;
       } catch (e) {
         results.ip = false;
         details.ip = `Tunnel process running but proxy failed: ${e.message}`;
@@ -40,15 +42,14 @@ export default async (options) => {
       results.dns = false;
       details.dns = 'DNS resolution failed';
     } else {
-      // In a real full VPN this would check if it's our VPN's DNS.
-      // Since this is just a SOCKS5 proxy, system DNS is usually used.
-      // We flag it as warning/fail if it's likely an ISP DNS, but for MVP
-      // we'll just check if we can resolve and list the servers used.
-      const servers = dnsResult.servers.join(', ');
-      // SOCKS5 doesn't automatically tunnel DNS for all OS commands, 
-      // but browsers can be configured to use SOCKS5 for DNS.
-      results.dns = true; 
-      details.dns = `Using system DNS: ${servers}`;
+      if (dnsStatus) {
+        results.dns = true;
+        details.dns = `DoH Resolver Active: 127.0.0.1:${dnsStatus.port} (Upstream: ${dnsStatus.upstream})`;
+      } else {
+        const servers = dnsResult.servers.join(', ');
+        results.dns = false; 
+        details.dns = `Using system/ISP DNS: ${servers} (Potential DNS Leak)`;
+      }
     }
 
     // 3. IPv6 Leak Check
@@ -65,7 +66,12 @@ export default async (options) => {
     if (spinner) spinner.stop();
 
     if (isJson) {
-      console.log(JSON.stringify({ results, details }));
+      console.log(JSON.stringify({
+        results,
+        details,
+        tunnelMode: info ? (info.mode || 'ssh') : 'none',
+        dnsResolver: dnsStatus ? 'doh' : 'system'
+      }));
     } else {
       const table = createTable(['Check', 'Status', 'Details']);
       
@@ -73,9 +79,9 @@ export default async (options) => {
       
       table.push(
         ['IP Address', formatResult(results.ip), details.ip],
-        // If dns is "pass" but we know it's a SOCKS proxy, it's actually a warning that DNS isn't tunneled OS-wide
-        ['DNS Leak', results.dns ? chalk.yellow('⚠ WARN') : formatResult(results.dns), details.dns],
-        ['IPv6 Leak', formatResult(results.ipv6), details.ipv6]
+        ['DNS Leak', dnsStatus ? chalk.green('✓ PASS') : chalk.yellow('⚠ WARN'), details.dns],
+        ['IPv6 Leak', formatResult(results.ipv6), details.ipv6],
+        ['WebRTC Leak', chalk.cyan('ⓘ INFO'), 'WebRTC can bypass proxies. Check browserleaks.com/webrtc']
       );
       
       console.log(table.toString());
@@ -85,7 +91,9 @@ export default async (options) => {
         console.log(chalk.yellow('Note: Your traffic is currently exposed. Run "polaris start" to connect.'));
       } else {
         console.log(chalk.cyan('Note: SOCKS5 proxies only tunnel apps configured to use them (like your browser).'));
-        console.log(chalk.cyan('      System-wide DNS leaks are expected until v0.5 (WireGuard).'));
+        if (!dnsStatus) {
+          console.log(chalk.yellow('      Run "polaris dns start" to prevent DNS queries from leaking to your ISP.'));
+        }
       }
       console.log();
     }

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/dns.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+import { printError, printSuccess, printInfo, printWarning } from '../utils/display.js';
+import { startDnsResolver, stopDnsResolver, getDnsStatus } from '../core/dns-service.js';
+
+export const dnsStart = async (options) => {
+  const port = parseInt(options.port || '5354', 10);
+  const upstreamMap = {
+    'cloudflare': 'https://cloudflare-dns.com/dns-query',
+    'google': 'https://dns.google/resolve'
+  };
+  
+  const provider = options.upstream || 'cloudflare';
+  const upstream = upstreamMap[provider.toLowerCase()] || provider;
+  const isJson = options.json;
+
+  try {
+    const res = startDnsResolver(port, upstream);
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, ...res }));
+    } else {
+      printSuccess(`DNS-over-HTTPS resolver started on 127.0.0.1:${port}`);
+      printInfo(`Forwarding to: ${upstream}`);
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to start DNS resolver', err);
+    }
+    process.exitCode = 1;
+  }
+};
+
+export const dnsStop = async (options) => {
+  const isJson = options.json;
+
+  try {
+    const res = stopDnsResolver();
+    if (!res) {
+      if (isJson) {
+        console.log(JSON.stringify({ error: 'DNS resolver is not running' }));
+      } else {
+        printWarning('DNS resolver is not running.');
+      }
+      return;
+    }
+    
+    if (isJson) {
+      console.log(JSON.stringify({ success: true }));
+    } else {
+      printSuccess('DNS-over-HTTPS resolver stopped.');
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to stop DNS resolver', err);
+    }
+    process.exitCode = 1;
+  }
+};
+
+export const dnsStatus = async (options) => {
+  const isJson = options.json;
+  const status = getDnsStatus();
+
+  if (!status) {
+    if (isJson) {
+      console.log(JSON.stringify({ running: false }));
+    } else {
+      console.log(`${chalk.red('✗')} DNS Resolver: ${chalk.red('Stopped')}`);
+    }
+    return;
+  }
+
+  if (isJson) {
+    console.log(JSON.stringify({ running: true, ...status }));
+  } else {
+    console.log(`${chalk.green('✓')} DNS Resolver: ${chalk.green('Running')}`);
+    console.log(`  ${chalk.dim('PID     :')} ${status.pid}`);
+    console.log(`  ${chalk.dim('Port    :')} ${status.port}`);
+    console.log(`  ${chalk.dim('Upstream:')} ${status.upstream}`);
+    console.log(`  ${chalk.dim('Uptime  :')} ${Math.floor((Date.now() - new Date(status.startTime)) / 1000)}s`);
+  }
+};

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;
+  }
+};