polaris-vpn 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+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.1.0] - 2026-06-27
+
+### Added
+
+- MVP release of Polaris CLI.
+- `polaris start`: Setup a SOCKS5 SSH proxy.
+- `polaris stop`: Stop the active tunnel.
+- `polaris status`: Check tunnel status.
+- `polaris check`: 3-point privacy leak check (IP, DNS, IPv6).
+- `polaris add/list/use`: Save and manage server profiles.

package/LICENSE

@@ -0,0 +1,177 @@
+# Apache License
+
+Version 2.0, January 2004
+<http://www.apache.org/licenses/>
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,99 @@
+# polaris — Leave no trace
+
+![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 wraps SSH dynamic port forwarding into a beautiful CLI experience.
+
+## Prerequisites
+
+- SSH access to any VPS (Virtual Private Server).
+- Node.js >= 18
+
+We highly recommend **Oracle Cloud Free Tier** for your VPS.
+
+## Install
+
+```bash
+npm install -g polaris-vpn
+```
+
+## Quickstart (30 seconds)
+
+Once you have your server's IP address and SSH credentials (e.g. `ubuntu@1.2.3.4`), just run:
+
+```bash
+polaris start --server ubuntu@1.2.3.4
+```
+
+This will instantly create an encrypted SOCKS5 proxy on `127.0.0.1:1080` and route your traffic through it.
+
+Verify it's working:
+
+```bash
+polaris check
+```
+
+When you're done:
+
+```bash
+polaris stop
+```
+
+## Command Reference
+
+| Command | Description |
+| --- | --- |
+| `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 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. |
+
+> All commands support the `--json` flag for machine-readable output.
+
+## Oracle Cloud Free Tier Setup
+
+The recommended free server is Oracle Cloud Always Free tier:
+
+- **ARM VM (A1.Flex)**: 2 OCPUs, 12 GB RAM — completely free forever.
+- 10 TB outbound bandwidth/month — more than enough for personal use.
+- Best regions from South/Southeast Asia: India (Hyderabad) ~30ms, Singapore ~50ms, Japan (Tokyo) ~80ms.
+- Sign up at [cloud.oracle.com](https://cloud.oracle.com) (requires a credit card for verification but charges nothing for Always Free resources).
+- After VM creation, just grab the IP and SSH key, and run `polaris start --server ubuntu@<your-oracle-ip>`.
+
+## Shared Server Model
+
+One Oracle VM can serve multiple people:
+
+- Light browsing (1–2 Mbps/user): 25–50 people comfortably.
+- YouTube/social (5 Mbps/user): 8–10 people simultaneously.
+- One person owns the VM, others get SSH keys.
+- Or each person creates their own free Oracle account for full isolation.
+
+## How It Works
+
+`polaris` uses standard SSH dynamic port forwarding (`-D` flag) behind the scenes. It sets up a secure, encrypted tunnel from your local machine to your server, and exposes a local SOCKS5 proxy. This gives you instant VPN-like privacy without installing *any* server-side software.
+
+## Trust Model
+
+- **You own the server**: No reliance on third-party VPN providers.
+- **Zero telemetry**: No tracking, no crash reporting, no analytics.
+- **No central infra**: We run nothing. You bring your own VPS.
+- **Open Source**: Apache 2.0 licensed, fully auditable.
+
+## Roadmap
+
+- **v0.1**: MVP — SSH SOCKS5 tunnel (Current)
+- **v0.2**: TLS tunnel + DNS-over-HTTPS + leak checker
+- **v0.5**: WireGuard full tunnel + server provisioning
+- **v1.0**: AmneziaWG stealth mode + multi-peer + QR codes + kill switch
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+## License
+
+Apache 2.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "polaris-vpn",
+  "version": "0.1.0",
+  "description": "Your True North in Digital Privacy. A self-hosted VPN CLI.",
+  "type": "module",
+  "bin": {
+    "polaris": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node ./src/cli.js"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "vpn",
+    "privacy",
+    "tunnel",
+    "socks5",
+    "proxy",
+    "cli",
+    "wireguard",
+    "self-hosted",
+    "oracle-cloud"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
+    "conf": "^15.1.0",
+    "node-fetch": "^3.3.2",
+    "ora": "^9.4.1",
+    "socks-proxy-agent": "^10.1.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { printBanner, printError } from './ui/display.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('polaris')
+  .description(pkg.description)
+  .version(pkg.version)
+  .option('--json', 'Output results in JSON format');
+
+// Helper to check if we should print the banner
+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')
+  .option('-p, --port <number>', 'Local SOCKS5 port to bind', '1080')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program
+  .command('stop')
+  .description('Stop the active tunnel')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program
+  .command('status')
+  .description('Show current tunnel status, IP, and uptime')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program
+  .command('check')
+  .description('Run a 3-point privacy check (IP, DNS leak, IPv6 leak)')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program
+  .command('add <alias>')
+  .description('Save a server profile for quick access')
+  .requiredOption('-s, --server <user@host>', 'SSH server for this profile')
+  .action(async (alias, options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program
+  .command('list')
+  .description('List all saved server profiles')
+  .action(async (options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      const { listServers } = await import('./commands/servers.js');
+      await listServers(cmd.optsWithGlobals());
+    } catch (err) {
+      if (!cmd.optsWithGlobals().json) printError('Command failed', err);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('use <alias>')
+  .description('Set a saved profile as the active default')
+  .action(async (alias, options, cmd) => {
+    if (!cmd.optsWithGlobals().json) printBanner();
+    try {
+      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);
+    }
+  });
+
+program.parseAsync(process.argv).catch(err => {
+  if (!willPrintJson()) printError('Fatal error', err);
+  process.exit(1);
+});

package/src/commands/check.js

@@ -0,0 +1,101 @@
+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';
+
+export default async (options) => {
+  const isJson = options.json;
+  const info = getTunnelInfo();
+  
+  if (!isJson) {
+    console.log(chalk.cyan.bold('\nRunning Privacy Check...\n'));
+  }
+
+  const spinner = isJson ? null : createSpinner('Running tests...').start();
+  const results = { ip: null, dns: null, ipv6: null };
+  const details = {};
+
+  try {
+    // 1. IP Check
+    if (spinner) spinner.text = 'Checking IP address...';
+    if (info) {
+      try {
+        const tunnelIp = await getProxiedIp(info.port);
+        results.ip = true;
+        details.ip = `Tunnel active: ${tunnelIp}`;
+      } catch (e) {
+        results.ip = false;
+        details.ip = `Tunnel process running but proxy failed: ${e.message}`;
+      }
+    } else {
+      const pubIp = await getPublicIp();
+      results.ip = false;
+      details.ip = `No tunnel active. Exposed IP: ${pubIp}`;
+    }
+
+    // 2. DNS Leak Check
+    if (spinner) spinner.text = 'Checking DNS...';
+    const dnsResult = await checkDns();
+    if (!dnsResult.success) {
+      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}`;
+    }
+
+    // 3. IPv6 Leak Check
+    if (spinner) spinner.text = 'Checking IPv6 leaks...';
+    const ipv6 = await checkIpv6Leak();
+    if (ipv6) {
+      results.ipv6 = false;
+      details.ipv6 = `IPv6 address detected: ${ipv6} (potential leak)`;
+    } else {
+      results.ipv6 = true;
+      details.ipv6 = 'No IPv6 address detected';
+    }
+
+    if (spinner) spinner.stop();
+
+    if (isJson) {
+      console.log(JSON.stringify({ results, details }));
+    } else {
+      const table = createTable(['Check', 'Status', 'Details']);
+      
+      const formatResult = (pass) => pass ? chalk.green('✓ PASS') : chalk.red('✗ FAIL');
+      
+      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]
+      );
+      
+      console.log(table.toString());
+      console.log();
+      
+      if (!info) {
+        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).'));
+      }
+      console.log();
+    }
+  } catch (err) {
+    if (spinner) spinner.stop();
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Failed to run privacy checks', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/commands/servers.js

@@ -0,0 +1,89 @@
+import Conf from 'conf';
+import { printSuccess, printError, printInfo, createTable } from '../ui/display.js';
+import chalk from 'chalk';
+
+const config = new Conf({ projectName: 'polaris' });
+
+export const addServer = async (alias, 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 provide a server with --server <user@host>');
+    }
+    process.exitCode = 1;
+    return;
+  }
+  
+  const profiles = config.get('servers', {});
+  profiles[alias] = server;
+  config.set('servers', profiles);
+  
+  // Auto-set as active if it's the first one
+  if (!config.get('activeServer')) {
+    config.set('activeServer', alias);
+  }
+  
+  if (isJson) {
+    console.log(JSON.stringify({ success: true, alias, server }));
+  } else {
+    printSuccess(`Saved profile '${alias}' -> ${server}`);
+  }
+};
+
+export const listServers = async (options) => {
+  const isJson = options.json;
+  const profiles = config.get('servers', {});
+  const activeAlias = config.get('activeServer');
+  
+  const aliases = Object.keys(profiles);
+  
+  if (isJson) {
+    console.log(JSON.stringify({ servers: profiles, active: activeAlias }));
+    return;
+  }
+  
+  if (aliases.length === 0) {
+    printInfo('No server profiles saved yet. Use "polaris add <alias> --server <user@host>".');
+    return;
+  }
+  
+  const table = createTable(['Alias', 'Server', 'Active']);
+  
+  for (const alias of aliases) {
+    const isActive = alias === activeAlias;
+    table.push([
+      isActive ? chalk.green.bold(alias) : alias,
+      profiles[alias],
+      isActive ? chalk.green('★') : ''
+    ]);
+  }
+  
+  console.log('\n' + table.toString() + '\n');
+};
+
+export const useServer = async (alias, options) => {
+  const isJson = options.json;
+  const profiles = config.get('servers', {});
+  
+  if (!profiles[alias]) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: `Profile '${alias}' not found` }));
+    } else {
+      printError(`Profile '${alias}' not found. Run "polaris list" to see saved profiles.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  
+  config.set('activeServer', alias);
+  
+  if (isJson) {
+    console.log(JSON.stringify({ success: true, active: alias, server: profiles[alias] }));
+  } else {
+    printSuccess(`Set '${alias}' as the active profile.`);
+  }
+};

package/src/commands/start.js

@@ -0,0 +1,91 @@
+import chalk from 'chalk';
+import Conf from 'conf';
+import { printError, printSuccess, printInfo, createSpinner, printWarning } from '../ui/display.js';
+import { getPublicIp, getProxiedIp } from '../net/ip.js';
+import { spawnSSH, waitForSocks, saveTunnelInfo, getTunnelInfo } from '../tunnel/ssh.js';
+
+const config = new Conf({ projectName: 'polaris' });
+
+export default async (options) => {
+  const isJson = options.json;
+  let server = options.server;
+  const port = parseInt(options.port || '1080', 10);
+
+  if (!server) {
+    // Try to load default from profile if not provided
+    const profiles = config.get('servers', {});
+    const activeAlias = config.get('activeServer');
+    if (activeAlias && profiles[activeAlias]) {
+      server = profiles[activeAlias];
+    } 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;
+      return;
+    }
+  }
+
+  // Check if already running
+  const info = getTunnelInfo();
+  if (info) {
+    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.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  let oldIp;
+  const spinner = isJson ? null : createSpinner('Fetching current IP...').start();
+  
+  try {
+    oldIp = await getPublicIp();
+    if (!isJson) {
+      spinner.succeed(`Current IP: ${chalk.cyan(oldIp)}`);
+      spinner.text = 'Starting SSH SOCKS5 tunnel...';
+      spinner.start();
+    }
+    
+    const pid = spawnSSH(server, port);
+    saveTunnelInfo(pid, server, port);
+    
+    if (!isJson) {
+      spinner.text = 'Waiting for proxy to become ready...';
+    }
+    
+    await waitForSocks(port);
+    
+    if (!isJson) {
+      spinner.text = 'Verifying IP through proxy...';
+    }
+    
+    const newIp = await getProxiedIp(port);
+    
+    if (!isJson) {
+      spinner.stop();
+      printSuccess(`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('Proxy :')} ${chalk.cyan(`socks5://127.0.0.1:${port}`)}`);
+      
+      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.'));
+    } else {
+      console.log(JSON.stringify({ success: true, oldIp, newIp, proxy: `socks5://127.0.0.1:${port}`, pid }));
+    }
+
+  } 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;
+  }
+};

package/src/commands/status.js

@@ -0,0 +1,63 @@
+import { getTunnelInfo } from '../tunnel/ssh.js';
+import { getProxiedIp, getPublicIp } from '../net/ip.js';
+import { createTable, createSpinner, printError } from '../ui/display.js';
+import chalk from 'chalk';
+
+export default async (options) => {
+  const isJson = options.json;
+  const info = getTunnelInfo();
+  
+  if (!info) {
+    if (isJson) {
+      console.log(JSON.stringify({ status: 'down' }));
+    } else {
+      console.log(chalk.red.bold('\n● Tunnel is DOWN\n'));
+    }
+    return;
+  }
+  
+  let currentIp = 'Unknown';
+  const spinner = isJson ? null : createSpinner('Checking proxy status...').start();
+  
+  try {
+    currentIp = await getProxiedIp(info.port);
+    if (spinner) spinner.stop();
+    
+    if (isJson) {
+      const uptimeMs = Date.now() - new Date(info.startTime).getTime();
+      console.log(JSON.stringify({
+        status: 'up',
+        server: info.server,
+        port: info.port,
+        pid: info.pid,
+        ip: currentIp,
+        uptimeMs
+      }));
+    } else {
+      console.log(chalk.green.bold('\n● Tunnel is UP\n'));
+      
+      const uptimeMin = Math.floor((Date.now() - new Date(info.startTime).getTime()) / 60000);
+      const table = createTable(['Property', 'Value']);
+      
+      table.push(
+        ['Status', chalk.green('Connected')],
+        ['Server', info.server],
+        ['Proxy', `socks5://127.0.0.1:${info.port}`],
+        ['Current IP', chalk.cyan(currentIp)],
+        ['Uptime', `${uptimeMin} minutes`],
+        ['PID', info.pid.toString()]
+      );
+      
+      console.log(table.toString());
+      console.log('');
+    }
+  } catch (err) {
+    if (spinner) spinner.stop();
+    if (isJson) {
+      console.log(JSON.stringify({ status: 'error', error: err.message }));
+    } else {
+      printError('Tunnel process is running, but proxy is unresponsive', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/commands/stop.js

@@ -0,0 +1,32 @@
+import { stopTunnel, getTunnelInfo } from '../tunnel/ssh.js';
+import { printSuccess, printInfo, printError } from '../ui/display.js';
+
+export default async (options) => {
+  const isJson = options.json;
+  const info = getTunnelInfo();
+  
+  if (!info) {
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, message: 'No active tunnel found.' }));
+    } else {
+      printInfo('No active tunnel found.');
+    }
+    return;
+  }
+  
+  try {
+    stopTunnel();
+    if (isJson) {
+      console.log(JSON.stringify({ success: true, message: 'Tunnel stopped successfully.' }));
+    } else {
+      printSuccess('Tunnel stopped successfully.');
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message }));
+    } else {
+      printError('Error stopping tunnel', err);
+    }
+    process.exitCode = 1;
+  }
+};

package/src/net/ip.js

@@ -0,0 +1,50 @@
+import fetch from 'node-fetch';
+import { SocksProxyAgent } from 'socks-proxy-agent';
+import dns from 'dns';
+import { promisify } from 'util';
+
+const resolve4 = promisify(dns.resolve4);
+
+export const getPublicIp = async () => {
+  const res = await fetch('https://api64.ipify.org?format=json');
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ipify.org`);
+  const data = await res.json();
+  return data.ip;
+};
+
+export const getProxiedIp = async (port) => {
+  const agent = new SocksProxyAgent(`socks5h://127.0.0.1:${port}`);
+  const res = await fetch('https://api64.ipify.org?format=json', { agent });
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ipify.org via proxy`);
+  const data = await res.json();
+  return data.ip;
+};
+
+// Simple DNS leak check by resolving via system dns
+export const checkDns = async () => {
+  try {
+    const servers = dns.getServers();
+    const resolved = await resolve4('example.com');
+    return { success: resolved.length > 0, servers };
+  } catch (err) {
+    return { success: false, servers: dns.getServers(), error: err.message };
+  }
+};
+
+// Returns IPv6 address if leaked, null otherwise
+export const checkIpv6Leak = async () => {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch('https://ipv6.icanhazip.com', { signal: controller.signal });
+    clearTimeout(timeout);
+    
+    if (res.ok) {
+      const text = await res.text();
+      return text.trim() || null;
+    }
+    return null;
+  } catch (err) {
+    return null; // Timeout or network error typically means IPv6 is disabled/unreachable
+  }
+};

package/src/tunnel/ssh.js

@@ -0,0 +1,134 @@
+import { spawn } from 'child_process';
+import net from 'net';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'polaris');
+const PID_FILE = path.join(CONFIG_DIR, 'tunnel.pid');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const ensureDir = () => {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+};
+
+export const spawnSSH = (server, port) => {
+  // We want to run SSH as a detached child process so it survives terminal close.
+  // -D port: Dynamic SOCKS5 forwarding
+  // -N: Do not execute a remote command
+  // -o StrictHostKeyChecking=no: Don't prompt for host key verification
+  // -o ServerAliveInterval=30: Keep connection alive
+  // -o ExitOnForwardFailure=yes: Exit if port forwarding fails
+  
+  const args = [
+    '-D', String(port),
+    '-N',
+    '-o', 'StrictHostKeyChecking=no',
+    '-o', 'ServerAliveInterval=30',
+    '-o', 'ExitOnForwardFailure=yes',
+    server
+  ];
+
+  const child = spawn('ssh', args, {
+    detached: true,
+    stdio: 'ignore' // We don't want to capture stdio, keep it completely detached
+  });
+
+  child.unref(); // Allow the parent process to exit independently
+
+  return child.pid;
+};
+
+// Poll the local port until it accepts connections
+export const waitForSocks = async (port, timeoutMs = 30000) => {
+  const start = Date.now();
+  
+  while (Date.now() - start < timeoutMs) {
+    try {
+      await new Promise((resolve, reject) => {
+        const socket = new net.Socket();
+        
+        socket.setTimeout(1000);
+        
+        socket.on('connect', () => {
+          socket.destroy();
+          resolve(true);
+        });
+        
+        socket.on('timeout', () => {
+          socket.destroy();
+          reject(new Error('timeout'));
+        });
+        
+        socket.on('error', (err) => {
+          socket.destroy();
+          reject(err);
+        });
+        
+        socket.connect(port, '127.0.0.1');
+      });
+      return true; // Connection successful
+    } catch (err) {
+      // Wait 500ms before retrying
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+  
+  throw new Error(`Timed out waiting for SOCKS5 proxy on port ${port} to become ready`);
+};
+
+export const saveTunnelInfo = (pid, server, port) => {
+  ensureDir();
+  fs.writeFileSync(PID_FILE, String(pid), 'utf-8');
+  
+  const config = {
+    server,
+    port,
+    startTime: new Date().toISOString()
+  };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+};
+
+export const getTunnelInfo = () => {
+  if (!fs.existsSync(PID_FILE) || !fs.existsSync(CONFIG_FILE)) {
+    return null;
+  }
+  
+  try {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim(), 10);
+    const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    
+    // Check if process actually exists
+    try {
+      process.kill(pid, 0); // test signal 0 to check if alive
+    } catch (e) {
+      if (e.code === 'ESRCH') {
+        // Process doesn't exist, tunnel is dead, cleanup
+        clearTunnelInfo();
+        return null;
+      }
+    }
+    
+    return { pid, ...config };
+  } catch (err) {
+    return null;
+  }
+};
+
+export const stopTunnel = () => {
+  const info = getTunnelInfo();
+  if (info) {
+    try {
+      process.kill(info.pid, 'SIGTERM');
+    } catch (e) {
+      // Ignore errors if process already dead
+    }
+  }
+  clearTunnelInfo();
+};
+
+export const clearTunnelInfo = () => {
+  if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
+};

package/src/ui/display.js

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import Table from 'cli-table3';
+
+export const printBanner = () => {
+  console.log(chalk.cyan.bold('\npolaris — Leave no trace.'));
+  console.log(chalk.dim('Your True North in Digital Privacy.\n'));
+};
+
+export const createSpinner = (text) => {
+  return ora({ text, color: 'cyan' });
+};
+
+export const printError = (msg, err = null) => {
+  console.error(chalk.red.bold(`\n✗ Error: ${msg}`));
+  if (err && err.message) {
+    console.error(chalk.dim(err.message));
+  } else if (err) {
+    console.error(chalk.dim(String(err)));
+  }
+};
+
+export const printSuccess = (msg) => {
+  console.log(chalk.green(`✓ ${msg}`));
+};
+
+export const printInfo = (msg) => {
+  console.log(chalk.cyan(`ℹ ${msg}`));
+};
+
+export const printWarning = (msg) => {
+  console.log(chalk.yellow(`⚠ ${msg}`));
+};
+
+export const createTable = (head = []) => {
+  return new Table({
+    head: head.map(h => chalk.cyan(h)),
+    style: { head: [], border: [] }
+  });
+};