polaris-vpn 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -5,23 +5,21 @@ 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
+## [0.5.0] - 2026-07-12
+
+### Added
 
-### 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.
+- **Server Health Dashboard**: `polaris status --full` now queries GeoIP data, tests ping latency directly to the server, and retrieves live WireGuard rx/tx data limits.
+- **Auto-Updater**: Introduced `polaris update` and background update notifications via `update-notifier`.
 
-## [0.3.0] - 2026-06-28
+## [0.4.0] - 2026-07-12
 
 ### 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
+
+- **Live Bandwidth Monitor**: Use `polaris monitor` to see real-time up/down speeds, data usage, and peer activity for WireGuard tunnels.
+- **Local REST API**: Use `polaris server start` to run a local API on `127.0.0.1:7070` for external integrations and status queries.
+
+## [0.3.1] - 2026-06-28
 
 ### Added
 - Companion `polaris-server` dynamic HTTP/TLS forwarding proxy on port 8443.

package/README.md

@@ -45,11 +45,14 @@ polaris stop
 | --- | --- |
 | `polaris start --server user@host [--port 1080]` | Start the encrypted SSH tunnel. |
 | `polaris stop` | Stop the active tunnel. |
-| `polaris status` | Show current tunnel status, IP, and uptime. |
+| `polaris status [--full]` | Show current tunnel status. `--full` shows GeoIP, ping latency, and WG stats. |
+| `polaris monitor` | Live bandwidth monitor for WireGuard tunnels. |
 | `polaris check` | Run a 3-point privacy check (IP, DNS leak, IPv6 leak). |
 | `polaris add <alias> --server user@host` | Save a server profile for quick access. |
 | `polaris list` | List all saved server profiles. |
 | `polaris use <alias>` | Set a saved profile as the active default. |
+| `polaris server start` | Start a local REST API on `127.0.0.1:7070`. |
+| `polaris update` | Update `polaris-vpn` to the latest version via npm. |
 
 > All commands support the `--json` flag for machine-readable output.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polaris-vpn",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
   "type": "module",
   "bin": {
@@ -37,12 +37,14 @@
     "commander": "^15.0.0",
     "conf": "^15.1.0",
     "dns2": "^3.0.0",
+    "express": "^5.2.1",
     "node-fetch": "^3.3.2",
     "node-notifier": "^10.0.1",
     "ora": "^9.4.1",
     "qrcode-terminal": "^0.12.0",
     "socks-proxy-agent": "^10.1.0",
     "ssh2": "^1.17.0",
+    "update-notifier": "^7.3.1",
     "wireguard-tools": "^0.1.0"
   }
 }

package/src/cli.js

@@ -3,12 +3,17 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import path from 'path';
-import { printBanner, printError } from './utils/display.js';
+import updateNotifier from 'update-notifier';
+import { spawnSync } from 'child_process';
+import { printBanner, printError, printSuccess } from './utils/display.js';
+import chalk from 'chalk';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
+updateNotifier({ pkg }).notify();
+
 const program = new Command();
 
 program
@@ -20,6 +25,20 @@ program
 // Helper to check if we should print the banner
 const willPrintJson = () => process.argv.includes('--json');
 
+program
+  .command('update')
+  .description('Update polaris-vpn to the latest version')
+  .action(() => {
+    console.log(chalk.cyan('Updating polaris-vpn...'));
+    const res = spawnSync('npm', ['install', '-g', 'polaris-vpn@latest'], { stdio: 'inherit' });
+    if (res.status === 0) {
+      printSuccess('Successfully updated to the latest version!');
+    } else {
+      printError('Failed to update polaris-vpn.');
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('start')
   .description('Start the encrypted SSH, TLS or WireGuard tunnel')
@@ -54,6 +73,7 @@ program
 program
   .command('status')
   .description('Show current tunnel status, IP, and uptime')
+  .option('--full', 'Show GeoIP, latency, and full data usage stats')
   .action(async (options, cmd) => {
     if (!cmd.optsWithGlobals().json) printBanner();
     try {
@@ -269,6 +289,25 @@ configCmd
     }
   });
 
+program
+  .command('server')
+  .description('Manage the local REST API server')
+  .command('start')
+  .description('Start the local REST API server')
+  .option('-p, --port <port>', 'Port to listen on', '7070')
+  .action(async (options) => {
+    const { serverStart } = await import('./commands/server.js');
+    await serverStart({ ...options, json: willPrintJson() });
+  });
+
+program
+  .command('monitor')
+  .description('Live bandwidth monitor for WireGuard/AmneziaWG tunnels')
+  .action(async (options, cmd) => {
+    const run = (await import('./commands/monitor.js')).default;
+    await run(cmd.optsWithGlobals());
+  });
+
 program.parseAsync(process.argv).catch(err => {
   if (!willPrintJson()) printError('Fatal error', err);
   process.exit(1);

package/src/commands/monitor.js

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+import { getActiveTunnel } from '../core/tunnel-service.js';
+import { createTable, printError } from '../utils/display.js';
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { CONFIG_DIR } from '../utils/config.js';
+
+const getWgStats = () => {
+  const confPathAwg = path.join(CONFIG_DIR, 'wg', 'awg0.conf');
+  const showCmd = fs.existsSync(confPathAwg) ? 'awg' : 'wg';
+  
+  const dumpRes = spawnSync('sudo', [showCmd, 'show', 'all', 'dump'], { encoding: 'utf-8' });
+  if (dumpRes.status !== 0) return null;
+
+  const lines = dumpRes.stdout.trim().split('\n');
+  if (lines.length <= 1) return null;
+
+  const peers = [];
+  let totalRx = 0;
+  let totalTx = 0;
+
+  for (let i = 1; i < lines.length; i++) {
+    const peerInfo = lines[i].split('\t');
+    const rx = parseInt(peerInfo[6], 10) || 0;
+    const tx = parseInt(peerInfo[7], 10) || 0;
+    totalRx += rx;
+    totalTx += tx;
+    peers.push({
+      pubKey: peerInfo[1].substring(0, 8) + '...',
+      endpoint: peerInfo[4],
+      rx,
+      tx
+    });
+  }
+
+  return { peers, totalRx, totalTx };
+};
+
+const formatBytes = (bytes) => {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+};
+
+export default async (options) => {
+  const isJson = options.json;
+  const info = getActiveTunnel();
+
+  if (!info || info.mode !== 'wireguard') {
+    if (isJson) {
+      console.log(JSON.stringify({ error: 'WireGuard tunnel is not active' }));
+    } else {
+      printError('Monitor requires an active WireGuard or AmneziaWG tunnel.');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (isJson) {
+    console.log(JSON.stringify(getWgStats()));
+    return;
+  }
+
+  let prevRx = 0;
+  let prevTx = 0;
+  let hasInit = false;
+
+  console.clear();
+  console.log(chalk.cyan.bold('\n● Polaris Live Bandwidth Monitor\n'));
+  console.log(chalk.dim('Press Ctrl+C to exit.\n'));
+
+  setInterval(() => {
+    const stats = getWgStats();
+    if (!stats) return;
+
+    if (!hasInit) {
+      prevRx = stats.totalRx;
+      prevTx = stats.totalTx;
+      hasInit = true;
+      return;
+    }
+
+    const rxSpeed = stats.totalRx - prevRx;
+    const txSpeed = stats.totalTx - prevTx;
+
+    prevRx = stats.totalRx;
+    prevTx = stats.totalTx;
+
+    console.clear();
+    console.log(chalk.cyan.bold('\n● Polaris Live Bandwidth Monitor\n'));
+    console.log(chalk.dim('Press Ctrl+C to exit.\n'));
+
+    const table = createTable(['Metric', 'Value']);
+    table.push(
+      ['Download Speed', chalk.green(`${formatBytes(rxSpeed)}/s`)],
+      ['Upload Speed', chalk.green(`${formatBytes(txSpeed)}/s`)],
+      ['Total Data Received', formatBytes(stats.totalRx)],
+      ['Total Data Sent', formatBytes(stats.totalTx)]
+    );
+    console.log(table.toString());
+
+    if (stats.peers.length > 0) {
+      console.log(chalk.bold('\nActive Peers:'));
+      const peerTable = createTable(['Peer', 'Endpoint', 'Received', 'Sent']);
+      for (const peer of stats.peers) {
+        peerTable.push([
+          peer.pubKey, 
+          peer.endpoint, 
+          formatBytes(peer.rx), 
+          formatBytes(peer.tx)
+        ]);
+      }
+      console.log(peerTable.toString());
+    }
+
+  }, 1000);
+};

package/src/commands/server.js

@@ -0,0 +1,35 @@
+import { printSuccess, printError, printInfo } from '../utils/display.js';
+import { startApiServer } from '../server/api.js';
+
+export const serverStart = async (options) => {
+  const isJson = options.json;
+  
+  try {
+    if (!isJson) {
+      printInfo('Starting local REST API server...');
+    }
+
+    const port = parseInt(options.port || '7070', 10);
+    await startApiServer(port);
+
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, url: `http://127.0.0.1:${port}` }));
+    } else {
+      printSuccess(`Local API running at http://127.0.0.1:${port}`);
+      console.log(`
+Endpoints:
+  GET  /status     — Get tunnel state
+  POST /connect    — Start tunnel { "server": "user@host", "mode": "auto" }
+  POST /disconnect — Stop active tunnel
+  GET  /peers      — List WireGuard peers (requires active deploy)
+`);
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to start local API', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/commands/status.js

@@ -2,9 +2,64 @@ import { getActiveTunnel } from '../core/tunnel-service.js';
 import { getProxiedIp } from '../net/ip-check.js';
 import { createTable, createSpinner, printError } from '../utils/display.js';
 import chalk from 'chalk';
+import fetch from 'node-fetch';
+import { spawnSync } from 'child_process';
+import os from 'os';
+
+const pingServer = (ip) => {
+  const isWin = os.platform() === 'win32';
+  const args = isWin ? ['-n', '1', '-w', '2000', ip] : ['-c', '1', '-W', '2', ip];
+  const res = spawnSync('ping', args, { encoding: 'utf-8' });
+  if (res.status === 0) {
+    if (isWin) {
+      const match = res.stdout.match(/Average = (\d+)ms/);
+      if (match) return `${match[1]} ms`;
+    } else {
+      const match = res.stdout.match(/time=([\d.]+)\s*ms/);
+      if (match) return `${match[1]} ms`;
+    }
+  }
+  return 'Timeout';
+};
+
+const getGeoIp = async (ip) => {
+  try {
+    const res = await fetch(`http://ip-api.com/json/${ip}`);
+    const data = await res.json();
+    if (data.status === 'success') {
+      return `${data.city}, ${data.country} (${data.isp})`;
+    }
+  } catch (err) {}
+  return 'Unknown';
+};
+
+const formatBytes = (bytes) => {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+};
+
+const getWgStats = () => {
+  const dumpRes = spawnSync('sudo', ['wg', 'show', 'all', 'dump'], { encoding: 'utf-8' });
+  if (dumpRes.status !== 0) return null;
+  const lines = dumpRes.stdout.trim().split('\n');
+  if (lines.length <= 1) return null;
+  
+  let totalRx = 0;
+  let totalTx = 0;
+  for (let i = 1; i < lines.length; i++) {
+    const peerInfo = lines[i].split('\t');
+    totalRx += parseInt(peerInfo[6], 10) || 0;
+    totalTx += parseInt(peerInfo[7], 10) || 0;
+  }
+  return { totalRx, totalTx };
+};
 
 export default async (options) => {
   const isJson = options.json;
+  const isFull = options.full;
   const info = getActiveTunnel();
   
   if (!info) {
@@ -23,9 +78,33 @@ export default async (options) => {
     currentIp = await getProxiedIp(info.port);
     if (spinner) spinner.stop();
     
+    let geo = 'N/A';
+    let latency = 'N/A';
+    let dataUsage = 'N/A';
+
+    if (isFull) {
+      if (spinner) {
+        spinner.text = 'Fetching full health data...';
+        spinner.start();
+      }
+      
+      const serverIp = info.server.split('@').pop();
+      latency = pingServer(serverIp);
+      geo = await getGeoIp(currentIp);
+
+      if (info.mode === 'wireguard') {
+        const stats = getWgStats();
+        if (stats) {
+          dataUsage = `${formatBytes(stats.totalRx)} / ${formatBytes(stats.totalTx)}`;
+        }
+      }
+      
+      if (spinner) spinner.stop();
+    }
+    
     if (isJson) {
       const uptimeMs = Date.now() - new Date(info.startTime).getTime();
-      console.log(JSON.stringify({
+      const payload = {
         status: 'up',
         server: info.server,
         port: info.port,
@@ -33,7 +112,13 @@ export default async (options) => {
         mode: info.mode || 'ssh',
         ip: currentIp,
         uptimeMs
-      }));
+      };
+      if (isFull) {
+        payload.geo = geo;
+        payload.latency = latency;
+        payload.dataUsage = dataUsage;
+      }
+      console.log(JSON.stringify(payload));
     } else {
       console.log(chalk.green.bold('\n● Tunnel is UP\n'));
       
@@ -49,6 +134,14 @@ export default async (options) => {
         ['Uptime', `${uptimeMin} minutes`],
         ['PID', info.pid.toString()]
       );
+
+      if (isFull) {
+        table.push(
+          ['Geo Location', geo],
+          ['Latency (Ping)', latency],
+          ['Data (Rx/Tx)', dataUsage]
+        );
+      }
       
       console.log(table.toString());
       console.log('');

package/src/server/api.js

@@ -0,0 +1,77 @@
+import express from 'express';
+import { getActiveTunnel, startTunnel, stopActiveTunnel } from '../core/tunnel-service.js';
+import { listPeers } from '../core/peer-service.js';
+import { getProfiles } from '../core/profile-service.js';
+
+export const startApiServer = (port = 7070) => {
+  const app = express();
+  app.use(express.json());
+
+  app.get('/status', (req, res) => {
+    try {
+      const info = getActiveTunnel();
+      if (!info) {
+        return res.json({ status: 'disconnected' });
+      }
+      res.json({ status: 'connected', ...info });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/connect', async (req, res) => {
+    try {
+      const { server, mode, proxyPort } = req.body;
+      let targetServer = server;
+
+      if (!targetServer) {
+        const { profiles, active } = getProfiles();
+        if (active && profiles[active]) {
+          targetServer = profiles[active];
+        } else {
+          return res.status(400).json({ error: 'No server specified and no active profile found.' });
+        }
+      }
+
+      const info = getActiveTunnel();
+      if (info) {
+        return res.status(400).json({ error: 'Tunnel is already active.', current: info });
+      }
+
+      const pPort = proxyPort || 1080;
+      const tMode = mode || 'auto';
+
+      const result = await startTunnel(targetServer, pPort, tMode, true);
+      res.json({ status: 'connected', ...result });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/disconnect', (req, res) => {
+    try {
+      const info = stopActiveTunnel(true);
+      if (!info) {
+        return res.json({ status: 'disconnected', message: 'No active tunnel.' });
+      }
+      res.json({ status: 'disconnected', message: 'Tunnel stopped successfully.' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.get('/peers', async (req, res) => {
+    try {
+      const peers = await listPeers();
+      res.json({ success: true, peers });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    const server = app.listen(port, '127.0.0.1', () => {
+      resolve(server);
+    }).on('error', reject);
+  });
+};