polaris-vpn 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,10 @@
 
 ![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
 
+<div align="center">
+  <img src="./docs/demo.gif" alt="Polaris VPN Terminal Demo" width="800">
+</div>
+
 Your True North in Digital Privacy. `polaris` is a production-quality, open-source, self-hosted VPN CLI tool. It supports SSH dynamic port forwarding, WireGuard, and AmneziaWG (Stealth) tunnels.
 
 ### Prerequisites

package/docs/marketing-drafts.md

@@ -0,0 +1,68 @@
+# Marketing Drafts for Polaris VPN
+
+Use these templates to post to various communities to drive your npm downloads.
+
+---
+
+## 1. Hacker News (Show HN)
+**Title:** Show HN: I built a free, self-hosted stealth VPN CLI for Oracle Cloud
+**Link / Text:**
+
+I got tired of paying for commercial VPNs that harvest data, so I built Polaris. It’s an open-source CLI tool that automatically provisions a WireGuard or AmneziaWG (Stealth Mode) VPN on any Linux VPS in about 30 seconds.
+
+I optimized it specifically for Oracle Cloud's "Always Free" ARM tier (2 OCPUs, 12GB RAM, 10TB bandwidth), so you can effectively get a high-performance personal VPN completely for free, forever. 
+
+Features:
+- Native WireGuard & Stealth Mode (AmneziaWG for DPI bypass)
+- Zero-Log Self-Hosted DNS (Unbound is automatically configured on the server)
+- SOCKS5 / SSH tunnel fallback modes
+- Built-in live bandwidth monitoring & terminal TUI dashboard
+- System-wide Kill Switch 
+- Terminal QR codes for mobile setup
+
+Would love for you to try it out and tear the code apart. 
+
+Repo: https://github.com/Divyo/polaris-vpn
+`npm install -g polaris-vpn`
+
+---
+
+## 2. Reddit (r/selfhosted, r/privacy, r/homelab)
+**Title:** I built a CLI tool to automate deploying a free, zero-log stealth VPN on Oracle Cloud in 30 seconds
+
+**Body:**
+Hey r/selfhosted!
+
+I’ve been working on a project called **Polaris VPN**. The goal was to make spinning up a secure, self-hosted VPN as easy as typing a single command, without having to manually mess with `iptables` routing, DNS leaks, or WireGuard configs.
+
+It works perfectly with the Oracle Cloud Free Tier. If you have an empty Ubuntu VM sitting there, you can run:
+
+`polaris deploy --server ubuntu@<your-ip>`
+
+And it will automatically:
+1. Install WireGuard (or AmneziaWG for stealth/DPI bypass)
+2. Setup UFW and Fail2Ban for security
+3. Install and configure **Unbound** so your DNS queries never hit Cloudflare or Google (Zero-Log DNS)
+4. Configure your local machine to route all traffic through it.
+
+It also has a cool terminal dashboard (`polaris dashboard`) to monitor your bandwidth and peers, and can generate QR codes in the terminal (`polaris peer qr mobile`) to instantly connect your phone.
+
+It's completely open-source (Apache 2.0). 
+Repo: https://github.com/Divyo/polaris-vpn
+
+If anyone has an Oracle Cloud account or a spare VPS, I'd love to hear your feedback!
+
+---
+
+## 3. Dev.to / Medium Tutorial
+**Title:** How to host your own Stealth VPN for free (and never pay for a VPN again)
+
+**(Outline for your blog post):**
+1. **The Problem:** Commercial VPNs are honeypots. They log your data, get blocked by Netflix/DPI, and cost $5-10/month.
+2. **The Solution:** Oracle Cloud Always Free tier + Polaris VPN.
+3. **Step 1:** Sign up for Oracle Cloud and launch an Ubuntu ARM VM.
+4. **Step 2:** Run `npm install -g polaris-vpn`
+5. **Step 3:** Run `polaris deploy --server ubuntu@your-ip`
+6. **Step 4:** Run `polaris start --server ubuntu@your-ip`
+7. **Explain the Tech:** Talk about AmneziaWG obfuscation, Unbound local DNS for privacy, and how it bypasses DPI (Deep Packet Inspection) which blocks normal WireGuard.
+8. **Call to Action:** Ask them to star the repo and try it out!

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "polaris-vpn",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
   "type": "module",
   "bin": {
     "polaris": "src/cli.js",
-    "polaris-server": "src/server/server.js"
+    "polaris-server": "src/commands/server.js"
   },
   "files": [
     "src",
@@ -16,13 +16,23 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Divyo/polaris-vpn.git"
+    "url": "git+https://github.com/Divyo/polaris-vpn.git"
+  },
+  "homepage": "https://github.com/Divyo/polaris-vpn#readme",
+  "bugs": {
+    "url": "https://github.com/Divyo/polaris-vpn/issues"
+  },
+  "author": "Divyo",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Divyo"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "start": "node ./src/cli.js"
+    "start": "node ./src/cli.js",
+    "test": "node --test"
   },
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +44,16 @@
     "cli",
     "wireguard",
     "self-hosted",
-    "oracle-cloud"
+    "oracle-cloud",
+    "free-vpn",
+    "ssh-tunnel",
+    "amneziawg",
+    "stealth-vpn",
+    "dpi-bypass",
+    "zero-trust",
+    "kill-switch",
+    "peer-to-peer",
+    "terminal"
   ],
   "dependencies": {
     "blessed": "^0.1.81",
@@ -51,7 +70,6 @@
     "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"
+    "update-notifier": "^7.3.1"
   }
 }

package/src/cli.js

@@ -6,6 +6,7 @@ import path from 'path';
 import updateNotifier from 'update-notifier';
 import { spawnSync } from 'child_process';
 import { printBanner, printError, printSuccess } from './utils/display.js';
+import { handleError } from './utils/error-handler.js';
 import chalk from 'chalk';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -51,8 +52,7 @@ program
       const run = (await import('./commands/start.js')).default;
       await run(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -65,8 +65,7 @@ program
       const run = (await import('./commands/stop.js')).default;
       await run(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -80,8 +79,7 @@ program
       const run = (await import('./commands/status.js')).default;
       await run(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -107,8 +105,7 @@ program
       const run = (await import('./commands/check.js')).default;
       await run(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -122,8 +119,7 @@ program
       const { addServer } = await import('./commands/servers.js');
       await addServer(alias, cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -136,8 +132,7 @@ program
       const { listServers } = await import('./commands/servers.js');
       await listServers(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -150,8 +145,7 @@ program
       const { useServer } = await import('./commands/servers.js');
       await useServer(alias, cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -168,8 +162,7 @@ dnsCmd
       const { dnsStart } = await import('./commands/dns.js');
       await dnsStart(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -182,8 +175,7 @@ dnsCmd
       const { dnsStop } = await import('./commands/dns.js');
       await dnsStop(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -196,8 +188,7 @@ dnsCmd
       const { dnsStatus } = await import('./commands/dns.js');
       await dnsStatus(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -214,8 +205,7 @@ program
       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);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -231,8 +221,7 @@ ksCmd
       setKillSwitchConfig(true);
       printSuccess('Kill switch enabled. All non-VPN traffic will be blocked when the tunnel is active.');
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -246,8 +235,7 @@ ksCmd
       setKillSwitchConfig(false);
       printSuccess('Kill switch disabled.');
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -262,8 +250,7 @@ peerCmd
       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);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -276,8 +263,7 @@ peerCmd
       const { peerList } = await import('./commands/peer.js');
       await peerList(cmd.optsWithGlobals());
     } catch (err) {
-      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
-      process.exit(1);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -290,8 +276,7 @@ peerCmd
       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);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 
@@ -303,8 +288,7 @@ peerCmd
       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);
+      handleError('Command failed', err, cmd.optsWithGlobals().json);
     }
   });
 

package/src/commands/server.js

@@ -1,4 +1,5 @@
-import { printSuccess, printError, printInfo } from '../utils/display.js';
+import { printSuccess, printInfo } from '../utils/display.js';
+import { handleError } from '../utils/error-handler.js';
 import { startApiServer } from '../server/api.js';
 
 export const serverStart = async (options) => {
@@ -25,11 +26,6 @@ Endpoints:
 `);
     }
   } catch (err) {
-    if (isJson) {
-      console.log(JSON.stringify({ error: err.message }));
-    } else {
-      printError('Failed to start local API', err);
-    }
-    process.exitCode = 1;
+    handleError('Failed to start local API', err, isJson);
   }
 };

package/src/commands/start.js

@@ -3,7 +3,8 @@ import tls from 'tls';
 import fs from 'fs';
 import path from 'path';
 import { spawnSync } from 'child_process';
-import { printError, printSuccess, createSpinner, printInfo } from '../utils/display.js';
+import { printSuccess, createSpinner, printInfo } from '../utils/display.js';
+import { handleError } from '../utils/error-handler.js';
 import { getPublicIp, getProxiedIp } from '../net/ip-check.js';
 import { getProfiles } from '../core/profile-service.js';
 import { getActiveTunnel, startTunnel } from '../core/tunnel-service.js';
@@ -54,12 +55,7 @@ export default async (options) => {
     if (active && profiles[active]) {
       server = profiles[active];
     } else {
-      if (isJson) {
-        console.log(JSON.stringify({ error: 'No server specified' }));
-      } else {
-        printError('No server specified. Use --server <user@host> or set an active profile with "polaris use".');
-      }
-      process.exitCode = 1;
+      handleError('No server specified. Use --server <user@host> or set an active profile with "polaris use".', null, isJson);
       return;
     }
   }
@@ -67,12 +63,7 @@ export default async (options) => {
   // Check if already running
   const info = getActiveTunnel();
   if (info) {
-    if (isJson) {
-      console.log(JSON.stringify({ error: 'Tunnel already running', pid: info.pid }));
-    } else {
-      printError(`Tunnel is already running connected to ${info.server}. Run "polaris stop" first.`);
-    }
-    process.exitCode = 1;
+    handleError(`Tunnel is already running connected to ${info.server}. Run "polaris stop" first.`, null, isJson);
     return;
   }
 
@@ -167,11 +158,6 @@ export default async (options) => {
 
   } catch (err) {
     if (!isJson && spinner) spinner.stop();
-    if (isJson) {
-      console.log(JSON.stringify({ error: err.message }));
-    } else {
-      printError('Failed to start tunnel', err);
-    }
-    process.exitCode = 1;
+    handleError('Failed to start tunnel', err, isJson);
   }
 };

package/src/core/deploy-service.js

@@ -39,9 +39,15 @@ export const deployServer = async (serverStr, options = {}) => {
   const host = parts.length > 1 ? parts[1] : parts[0];
   const isAwg = options.mode === 'amneziawg';
   
-  const privateKey = options.privateKey 
-    ? fs.readFileSync(options.privateKey) 
-    : getDefaultPrivateKey();
+  let privateKey = null;
+  if (options.privateKey) {
+    if (!fs.existsSync(options.privateKey)) {
+      throw new Error(`SSH private key file not found: ${options.privateKey}`);
+    }
+    privateKey = fs.readFileSync(options.privateKey);
+  } else {
+    privateKey = getDefaultPrivateKey();
+  }
 
   if (!privateKey && !options.password) {
     throw new Error('No SSH authentication method found. Please configure default SSH keys or specify key path/password.');
@@ -189,7 +195,8 @@ PersistentKeepalive = 25
       port: options.port || 22,
       username,
       privateKey,
-      password: options.password
+      password: options.password,
+      readyTimeout: 10000 // 10 second timeout for SSH connection
     });
   });
 };

package/src/utils/error-handler.js

@@ -0,0 +1,19 @@
+import { printError } from './display.js';
+
+export const handleError = (msg, err, isJson = false) => {
+  const isDebug = process.argv.includes('--debug');
+  
+  if (isJson) {
+    const errorOutput = { error: msg, details: err ? err.message : undefined };
+    if (isDebug && err && err.stack) {
+      errorOutput.stack = err.stack;
+    }
+    console.log(JSON.stringify(errorOutput));
+  } else {
+    printError(msg, err);
+    if (isDebug && err && err.stack) {
+      console.error('\n' + err.stack);
+    }
+  }
+  process.exitCode = 1;
+};