polaris-vpn 0.7.0 → 2.0.0-beta

package/CHANGELOG.md

@@ -5,6 +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).
 
+## [2.0.0-beta] - 2026-07-12
+
+### Added
+
+- **Zero-Log Self-Hosted DNS (Unbound)**: `polaris deploy` now automatically installs and configures Unbound directly on the VPS, binding it to the tunnel interface (`10.0.0.1:53`). Client configs use this by default, ensuring your DNS queries never hit public resolvers (like Cloudflare) and never leave the encrypted tunnel.
+- **Server Hardening (Fail2Ban)**: Deployment now automatically secures the VPS SSH port against automated botnet brute-force attacks by installing and enabling `fail2ban`.
+
+## [1.0.0] - 2026-07-12
+
+### Added
+
+- **Multi-Peer Management**: `polaris peer add <name>` allows you to provision additional client configurations dynamically on your existing WireGuard or AmneziaWG server. Use `polaris peer list` and `polaris peer remove <name>` to manage your peers.
+- **Terminal QR Codes**: Automatically generate terminal-rendered QR codes using `polaris peer qr <name>` for instantly setting up mobile devices (iOS/Android).
+- **System Kill Switch**: Run `polaris killswitch on` to drop all non-VPN outbound traffic (using `iptables` or `pf`) when the tunnel is active, ensuring zero IP leaks.
+
 ## [0.7.0] - 2026-07-12
 
 ### Added

package/README.md

@@ -3,6 +3,7 @@
 ![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
 
 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
 
 - Node.js (v18+)
@@ -50,6 +51,11 @@ polaris stop
 | `polaris dashboard` | Opens a rich Terminal User Interface (TUI) with real-time stats. |
 | `polaris status [--full]` | Show current tunnel status. `--full` shows GeoIP, ping latency, and WG stats. |
 | `polaris monitor` | Live bandwidth monitor for WireGuard tunnels. |
+| `polaris killswitch on/off` | Enable or disable the system-wide VPN kill switch. |
+| `polaris peer add <name>` | Generate and add a new peer config for WireGuard/AmneziaWG. |
+| `polaris peer list` | List all peers configured on the server. |
+| `polaris peer remove <name>` | Revoke a peer from the server. |
+| `polaris peer qr <name>` | Display the peer config as a QR code for mobile devices. |
 | `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. |
@@ -58,15 +64,19 @@ polaris stop
 | `polaris update` | Update `polaris-vpn` to the latest version via npm. |
 
 #### `polaris dashboard`
+
 Opens a rich Terminal User Interface (TUI) with real-time graphs, server location maps, and live statistics (Rx/Tx, Ping).
 
 #### `polaris status [--full]`
+
 Displays the connection state, mode, current proxy IP, and active server. Use `--full` to query GeoIP and ping latency.
 
 #### `polaris monitor`
+
 Live bandwidth monitor that actively graphs the download and upload speeds of your tunnel.
 
 #### `polaris check`
+
 Checks if your IP matches the proxy, tests for DNS leaks via `ipleak.net`, and verifies IPv6 routing.
 
 > All commands support the `--json` flag for machine-readable output.
@@ -106,8 +116,8 @@ One Oracle VM can serve multiple people:
 - **v0.1**: MVP — SSH SOCKS5 tunnel
 - **v0.5**: WireGuard full tunnel + server provisioning
 - **v0.6**: Windows NT Service bindings + Blessed TUI Dashboard
-- **v0.7**: AmneziaWG stealth mode (DPI bypass) (Current)
-- **v1.0**: Multi-peer management + QR codes + Kill switch
+- **v0.7**: AmneziaWG stealth mode (DPI bypass)
+- **v1.0**: Multi-peer management + QR codes + Kill switch (Current)
 
 ## Contributing
 

package/docs/ORACLE_CLOUD.md

@@ -0,0 +1,56 @@
+# Oracle Cloud "Always Free" VPS Guide
+
+Oracle Cloud offers the most generous free tier in the cloud computing market, making it the perfect companion for a self-hosted Polaris VPN.
+
+This guide will walk you through exactly how to set up an Oracle ARM instance, configure the firewall, and prepare it for Polaris.
+
+## 1. Sign Up for Oracle Cloud
+
+1. Go to [Oracle Cloud Free Tier](https://www.oracle.com/cloud/free/) and sign up.
+2. You will need to provide a credit/debit card for verification. **You will not be charged.** Oracle requires this to prevent spam.
+3. Select your **Home Region** carefully. You cannot change this later without deleting your account. Pick the region geographically closest to you for the lowest latency.
+   - *Example: If you are in South Asia, pick Mumbai or Hyderabad. If you are in Southeast Asia, pick Singapore.*
+
+## 2. Create the Compute Instance
+
+1. From the Oracle Cloud Dashboard, click **Create a VM instance**.
+2. **Name**: `polaris-vpn` (or whatever you prefer).
+3. **Placement**: Leave as default (AD-1).
+4. **Image and Shape**:
+   - Click **Edit**.
+   - **Image**: Select **Ubuntu** (Recommend version 22.04 or newer).
+   - **Shape**: Select **Ampere (ARM)** (`VM.Standard.A1.Flex`).
+   - Configure the shape to use **2 OCPUs** and **12 GB RAM**. (You are allowed up to 4 OCPUs and 24 GB RAM for free, but 2 OCPUs is more than enough for a VPN).
+5. **Networking**:
+   - Leave the default VCN settings.
+   - Ensure **Assign a public IPv4 address** is checked.
+6. **Add SSH keys**:
+   - Select **Generate a key pair for me**.
+   - Click **Save private key**. Keep this `.key` file safe! You will need it to connect.
+7. Click **Create** at the bottom of the page. Your instance will take about 2-3 minutes to provision.
+
+## 3. Configure the Virtual Cloud Network (VCN) Firewall
+
+By default, Oracle Cloud blocks all incoming traffic except SSH (Port 22). WireGuard (and AmneziaWG) requires UDP port 51820 to be open.
+
+1. On your instance details page, look for the **Primary VNIC** section and click on the **Subnet** link (e.g., `subnet-xxxx`).
+2. Under **Security Lists**, click the Default Security List.
+3. Click **Add Ingress Rules**.
+4. Configure the rule as follows:
+   - **Source Type**: CIDR
+   - **Source CIDR**: `0.0.0.0/0`
+   - **IP Protocol**: UDP
+   - **Destination Port Range**: `51820`
+   - **Description**: Allow WireGuard/AmneziaWG
+5. Click **Add Ingress Rules**.
+
+*(Note: If you plan to use the SSH SOCKS5 proxy instead of WireGuard, you don't need to open port 51820, as SSH uses port 22 which is already open).*
+
+## 4. Get Ready for Polaris
+
+1. Go back to your **Instance Details** page.
+2. Note down the **Public IP Address** (e.g., `123.45.67.89`).
+3. Note the default username for Ubuntu images is always `ubuntu`.
+4. Locate the private key you downloaded in Step 2.6 (e.g., `ssh-key-2026-07-12.key`).
+
+You are now ready to deploy Polaris! Head back to the [Full Setup Guide](./SETUP.md) and run the `polaris deploy` command with your new Oracle IP and SSH key.

package/docs/SETUP.md

@@ -0,0 +1,93 @@
+# Full Step-by-Step Setup Guide
+
+Welcome to Polaris VPN! This guide will take you from scratch to having a fully functional, DPI-resistant self-hosted VPN.
+
+## 1. Prepare a Virtual Private Server (VPS)
+
+Polaris needs a Linux server (Ubuntu/Debian recommended) to host the VPN.
+If you don't already have one, you can easily get a powerful one for **free forever**.
+
+👉 **[Click here for the Oracle Cloud Free Tier Guide](./ORACLE_CLOUD.md)**
+
+*Once you have your server's Public IP address and SSH Private Key, continue to Step 2.*
+
+## 2. Install Polaris VPN
+
+On your local machine (where you want to connect *from*), you need Node.js installed.
+
+Install the Polaris CLI globally:
+
+```bash
+npm install -g polaris-vpn
+```
+
+## 3. Provision the Server
+
+You will now use Polaris to automatically install and configure the VPN on your new VPS.
+
+Run the `deploy` command. We highly recommend using the `amneziawg` mode to ensure your VPN traffic cannot be blocked by Deep Packet Inspection (DPI):
+
+```bash
+polaris deploy --server ubuntu@<YOUR_SERVER_IP> --mode amneziawg
+```
+
+*Note: If you receive an SSH authentication error, you need to provide your SSH private key. By default, Polaris looks for `~/.ssh/id_rsa`. If your key is saved elsewhere (like the one downloaded from Oracle), you can use it like this:*
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add /path/to/your/oracle-ssh-key.key
+polaris deploy --server ubuntu@<YOUR_SERVER_IP> --mode amneziawg
+```
+
+This process takes about 2-3 minutes. Polaris will install AmneziaWG, configure the stealth parameters, set up the kernel modules, and generate your local client configuration.
+
+## 4. Start the Tunnel
+
+Once deployment is successful, you can connect to your new VPN!
+
+Run:
+
+```bash
+polaris start
+```
+
+You should see a success message. All your internet traffic is now encrypted and routed through your VPS!
+
+To verify everything is working and your IP has changed, run:
+
+```bash
+polaris check
+```
+
+## 5. Enable the Kill Switch (Optional)
+
+To ensure your real IP is never leaked if the VPN connection drops, enable the system kill switch:
+
+```bash
+polaris killswitch on
+```
+
+## 6. Connect Mobile Devices
+
+Want to use the VPN on your phone? Polaris can generate terminal QR codes!
+First, generate a new peer configuration on the server:
+
+```bash
+polaris peer add my-iphone
+```
+
+Then, display the QR code on your terminal:
+
+```bash
+polaris peer qr my-iphone
+```
+
+Download the **AmneziaWG** app on iOS or Android, tap the `+` button, select **Create from QR code**, and scan your screen!
+
+## 7. Stop the Tunnel
+
+When you are done, simply run:
+
+```bash
+polaris stop
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polaris-vpn",
-  "version": "0.7.0",
+  "version": "2.0.0-beta",
   "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
   "type": "module",
   "bin": {
@@ -9,10 +9,15 @@
   },
   "files": [
     "src",
+    "docs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Divyo/polaris-vpn.git"
+  },
   "engines": {
     "node": ">=18"
   },

package/src/cli.js

@@ -219,7 +219,39 @@ program
     }
   });
 
-const peerCmd = program.command('peer').description('Manage WireGuard client peers');
+const ksCmd = program.command('killswitch').description('Manage the system VPN kill switch');
+
+ksCmd
+  .command('on')
+  .description('Enable the kill switch')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { setKillSwitchConfig } = await import('./utils/kill-switch.js');
+      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);
+    }
+  });
+
+ksCmd
+  .command('off')
+  .description('Disable the kill switch')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { setKillSwitchConfig } = await import('./utils/kill-switch.js');
+      setKillSwitchConfig(false);
+      printSuccess('Kill switch disabled.');
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+const peerCmd = program.command('peer').description('Manage WireGuard/AmneziaWG client peers');
 
 peerCmd
   .command('add <name>')

package/src/core/deploy-service.js

@@ -63,10 +63,10 @@ export const deployServer = async (serverStr, options = {}) => {
         const quickCmd = isAwg ? 'awg-quick' : 'wg-quick';
 
         // Step 1: Install packages
-        onProgress(`Installing ${isAwg ? 'AmneziaWG' : 'WireGuard'} and UFW on remote VPS...`);
-        let installCmd = 'sudo apt-get update -y && sudo apt-get install -y wireguard ufw';
+        onProgress(`Installing ${isAwg ? 'AmneziaWG' : 'WireGuard'}, UFW, Unbound, and Fail2Ban...`);
+        let installCmd = 'sudo apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y wireguard ufw unbound fail2ban';
         if (isAwg) {
-          installCmd = 'sudo apt-get update -y && sudo apt-get install -y software-properties-common && sudo add-apt-repository -y ppa:amnezia/ppa && sudo apt-get update -y && sudo apt-get install -y amneziawg-dkms amneziawg-tools ufw';
+          installCmd = 'sudo apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common && sudo add-apt-repository -y ppa:amnezia/ppa && sudo apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y amneziawg-dkms amneziawg-tools ufw unbound fail2ban';
         }
         let res = await sshExec(conn, installCmd);
         if (res.code !== 0) throw new Error(`Installation failed: ${res.stderr}`);
@@ -118,6 +118,24 @@ AllowedIPs = 10.0.0.2/32
         res = await sshExec(conn, `sudo systemctl stop ${quickCmd}@${ifaceName} || true && sudo systemctl start ${quickCmd}@${ifaceName} && sudo systemctl enable ${quickCmd}@${ifaceName}`);
         if (res.code !== 0) throw new Error(`Starting tunnel failed: ${res.stderr}`);
 
+        // Step 5b: Configure Unbound DNS
+        onProgress('Configuring Unbound Zero-Log DNS...');
+        const unboundConf = `server:
+    interface: 10.0.0.1
+    access-control: 10.0.0.0/24 allow
+    hide-identity: yes
+    hide-version: yes
+    use-caps-for-id: yes
+    prefetch: yes
+`;
+        res = await sshExec(conn, `cat << 'EOF' > /tmp/polaris-dns.conf\n${unboundConf}\nEOF\nsudo mv /tmp/polaris-dns.conf /etc/unbound/unbound.conf.d/polaris-dns.conf && sudo systemctl restart unbound && sudo systemctl enable unbound`);
+        if (res.code !== 0) throw new Error(`Unbound setup failed: ${res.stderr}`);
+
+        // Step 5c: Start Fail2Ban
+        onProgress('Starting Fail2Ban SSH protection...');
+        res = await sshExec(conn, 'sudo systemctl enable fail2ban && sudo systemctl restart fail2ban');
+        if (res.code !== 0) throw new Error(`Fail2ban setup 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');
@@ -128,7 +146,7 @@ AllowedIPs = 10.0.0.2/32
         const clientConf = `[Interface]
 PrivateKey = ${clientKeys.privateKey}
 Address = 10.0.0.2/24
-DNS = 1.1.1.1
+DNS = 10.0.0.1
 ${obfuscationBlock}
 
 [Peer]
@@ -152,6 +170,7 @@ PersistentKeepalive = 25
           serverPublicKey: serverKeys.publicKey,
           clientPublicKey: clientKeys.publicKey,
           interface: ethInterface,
+          awgParams: isAwg ? awgParams : null,
           timestamp: new Date().toISOString()
         }, null, 2), 'utf-8');
 

package/src/core/peer-service.js

@@ -65,10 +65,13 @@ const sshExec = (client, command) => {
 export const addPeer = async (name) => {
   const info = getDeployInfo();
   const conn = await sshConnect(info);
+  const isAwg = info.mode === 'amneziawg';
+  const confFile = isAwg ? '/etc/amnezia/amneziawg/awg0.conf' : '/etc/wireguard/wg0.conf';
+  const quickCmd = isAwg ? 'awg-quick@awg0' : 'wg-quick@wg0';
 
   try {
-    // 1. Read remote wg0.conf
-    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    // 1. Read remote config
+    const catRes = await sshExec(conn, `sudo cat ${confFile}`);
     if (catRes.code !== 0) throw new Error(`Failed to read server config: ${catRes.stderr}`);
     const configContent = catRes.stdout;
 
@@ -99,18 +102,32 @@ PublicKey = ${peerKeys.publicKey}
 AllowedIPs = ${peerIp}/32
 `;
 
-    const writeCmd = `echo "${peerConfigBlock.replace(/"/g, '\\"')}" | sudo tee -a /etc/wireguard/wg0.conf`;
+    const writeCmd = `echo "${peerConfigBlock.replace(/"/g, '\\"')}" | sudo tee -a ${confFile}`;
     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');
+    // Sync remote tunnel
+    await sshExec(conn, `sudo systemctl restart ${quickCmd}`);
+
+    let obfuscationBlock = '';
+    if (isAwg && info.awgParams) {
+      obfuscationBlock = `Jc = ${info.awgParams.Jc}
+Jmin = ${info.awgParams.Jmin}
+Jmax = ${info.awgParams.Jmax}
+S1 = ${info.awgParams.S1}
+S2 = ${info.awgParams.S2}
+H1 = ${info.awgParams.H1}
+H2 = ${info.awgParams.H2}
+H3 = ${info.awgParams.H3}
+H4 = ${info.awgParams.H4}`;
+    }
 
     // 3. Save peer config locally
     const clientConf = `[Interface]
 PrivateKey = ${peerKeys.privateKey}
 Address = ${peerIp}/24
-DNS = 1.1.1.1
+DNS = 10.0.0.1
+${obfuscationBlock}
 
 [Peer]
 PublicKey = ${info.serverPublicKey}
@@ -135,10 +152,13 @@ PersistentKeepalive = 25
 export const listPeers = async () => {
   const info = getDeployInfo();
   const conn = await sshConnect(info);
+  const isAwg = info.mode === 'amneziawg';
+  const confFile = isAwg ? '/etc/amnezia/amneziawg/awg0.conf' : '/etc/wireguard/wg0.conf';
+  const showCmd = isAwg ? 'awg show awg0 dump' : 'wg show wg0 dump';
 
   try {
     // 1. Read remote configuration to parse names
-    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    const catRes = await sshExec(conn, `sudo cat ${confFile}`);
     if (catRes.code !== 0) throw new Error('Failed to read remote config');
     const content = catRes.stdout;
 
@@ -158,9 +178,9 @@ export const listPeers = async () => {
       }
     }
 
-    // 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');
+    // 2. Fetch tunnel status
+    const showRes = await sshExec(conn, `sudo ${showCmd}`);
+    if (showRes.code !== 0) throw new Error('Failed to run show command');
     
     const dumpLines = showRes.stdout.trim().split('\n');
     const list = [];
@@ -193,9 +213,12 @@ export const listPeers = async () => {
 export const removePeer = async (name) => {
   const info = getDeployInfo();
   const conn = await sshConnect(info);
+  const isAwg = info.mode === 'amneziawg';
+  const confFile = isAwg ? '/etc/amnezia/amneziawg/awg0.conf' : '/etc/wireguard/wg0.conf';
+  const quickCmd = isAwg ? 'awg-quick@awg0' : 'wg-quick@wg0';
 
   try {
-    const catRes = await sshExec(conn, 'sudo cat /etc/wireguard/wg0.conf');
+    const catRes = await sshExec(conn, `sudo cat ${confFile}`);
     if (catRes.code !== 0) throw new Error('Failed to read remote config');
     const content = catRes.stdout;
 
@@ -209,11 +232,11 @@ export const removePeer = async (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`);
+    const writeRes = await sshExec(conn, `cat << 'EOF' > /tmp/temp.conf\n${newContent}\nEOF\nsudo mv /tmp/temp.conf ${confFile} && sudo chmod 600 ${confFile}`);
     if (writeRes.code !== 0) throw new Error('Failed to update remote config');
 
-    // Sync remote wireguard
-    await sshExec(conn, 'sudo systemctl restart wg-quick@wg0');
+    // Sync remote tunnel
+    await sshExec(conn, `sudo systemctl restart ${quickCmd}`);
 
     // Remove local peer config if it exists
     const peerConfPath = path.join(CONFIG_DIR, 'wg', 'peers', `${name}.conf`);