blue-js-sdk 2.0.0

package/connection/security.js

@@ -0,0 +1,232 @@
+/**
+ * Security — kill switch, DNS leak prevention.
+ *
+ * Controls firewall rules and DNS settings to prevent traffic leaks
+ * when the VPN tunnel is active.
+ */
+
+import { execFileSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+
+import { _defaultState } from './state.js';
+import { saveState } from '../state.js';
+import { TunnelError } from '../errors.js';
+
+// ─── Kill Switch (Firewall / Packet Filter) ────────────────────────────────
+
+let _killSwitchEnabled = false;
+
+/**
+ * Enable kill switch — blocks all non-tunnel traffic.
+ * Windows: netsh advfirewall, macOS: pfctl, Linux: iptables.
+ * Call after WireGuard tunnel is installed.
+ * @param {string} serverEndpoint - WireGuard server "IP:PORT"
+ * @param {string} [tunnelName='wgsent0'] - WireGuard interface name
+ */
+export function enableKillSwitch(serverEndpoint, tunnelName = 'wgsent0') {
+  const [serverIp, serverPort] = serverEndpoint.split(':');
+
+  if (process.platform === 'win32') {
+    // Windows: netsh advfirewall
+    // Block all outbound by default
+    execFileSync('netsh', ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,blockoutbound'], { stdio: 'pipe' });
+
+    // Wrap allow rules in try-catch — if any fail after block-all, restore default policy
+    // to prevent permanent internet loss from partial firewall state.
+    try {
+      // Allow tunnel interface
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Allow-Tunnel', 'dir=out', `interface=${tunnelName}`, 'action=allow'], { stdio: 'pipe' });
+
+      // Allow WireGuard endpoint (UDP to server)
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Allow-WG-Endpoint', 'dir=out', 'action=allow', 'protocol=udp', `remoteip=${serverIp}`, `remoteport=${serverPort}`], { stdio: 'pipe' });
+
+      // Allow loopback
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Allow-Loopback', 'dir=out', 'action=allow', 'remoteip=127.0.0.1'], { stdio: 'pipe' });
+
+      // Allow DHCP
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Allow-DHCP', 'dir=out', 'action=allow', 'protocol=udp', 'localport=68', 'remoteport=67'], { stdio: 'pipe' });
+
+      // Allow DNS only through tunnel
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Allow-DNS-Tunnel', 'dir=out', 'action=allow', 'protocol=udp', 'remoteip=10.8.0.1', 'remoteport=53'], { stdio: 'pipe' });
+
+      // Block IPv6 (prevent leaks)
+      execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule', 'name=SentinelVPN-Block-IPv6', 'dir=out', 'action=block', 'protocol=any', 'remoteip=::/0'], { stdio: 'pipe' });
+    } catch (err) {
+      // Emergency restore — unblock outbound so user isn't locked out
+      try { execFileSync('netsh', ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,allowoutbound'], { stdio: 'pipe' }); } catch { /* last resort */ }
+      _killSwitchEnabled = false;
+      throw new TunnelError('KILL_SWITCH_FAILED', `Kill switch failed: ${err.message}`);
+    }
+
+  } else if (process.platform === 'darwin') {
+    // macOS: pfctl (packet filter)
+    const pfRules = [
+      '# Sentinel VPN Kill Switch',
+      'block out all',
+      `pass out on ${tunnelName} all`,
+      `pass out proto udp from any to ${serverIp} port ${serverPort}`,
+      'pass out on lo0 all',
+      'pass out proto udp from any port 68 to any port 67',
+      'pass out proto udp from any to 10.8.0.1 port 53',
+      'block out inet6 all',
+    ].join('\n') + '\n';
+
+    const pfPath = '/tmp/sentinel-killswitch.conf';
+    writeFileSync(pfPath, pfRules, { mode: 0o600 });
+
+    // Save current pf state for restore
+    try { execFileSync('pfctl', ['-sr'], { encoding: 'utf8', stdio: 'pipe' }); } catch { /* may not have existing rules */ }
+
+    // Load rules and enable pf
+    execFileSync('pfctl', ['-f', pfPath], { stdio: 'pipe' });
+    execFileSync('pfctl', ['-e'], { stdio: 'pipe' });
+
+  } else {
+    // Linux: iptables
+    // Flush existing sentinel rules first
+    try { execFileSync('iptables', ['-D', 'OUTPUT', '-m', 'comment', '--comment', 'sentinel-vpn', '-j', 'DROP'], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+
+    // Allow loopback
+    execFileSync('iptables', ['-A', 'OUTPUT', '-o', 'lo', '-j', 'ACCEPT', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Allow tunnel interface
+    execFileSync('iptables', ['-A', 'OUTPUT', '-o', tunnelName, '-j', 'ACCEPT', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Allow WireGuard server endpoint
+    execFileSync('iptables', ['-A', 'OUTPUT', '-d', serverIp, '-p', 'udp', '--dport', serverPort, '-j', 'ACCEPT', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Allow DHCP
+    execFileSync('iptables', ['-A', 'OUTPUT', '-p', 'udp', '--sport', '68', '--dport', '67', '-j', 'ACCEPT', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Allow DNS only through tunnel
+    execFileSync('iptables', ['-A', 'OUTPUT', '-d', '10.8.0.1', '-p', 'udp', '--dport', '53', '-j', 'ACCEPT', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Block everything else
+    execFileSync('iptables', ['-A', 'OUTPUT', '-j', 'DROP', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' });
+
+    // Block IPv6
+    try { execFileSync('ip6tables', ['-A', 'OUTPUT', '-j', 'DROP', '-m', 'comment', '--comment', 'sentinel-vpn'], { stdio: 'pipe' }); } catch { /* ip6tables may not be available */ }
+  }
+
+  _killSwitchEnabled = true;
+  // Persist kill switch state — survives crash so recoverOrphans() can restore internet
+  try {
+    const conn = _defaultState.connection || {};
+    saveState({ sessionId: conn.sessionId, serviceType: conn.serviceType, nodeAddress: conn.nodeAddress, killSwitchEnabled: true });
+  } catch {} // best-effort
+}
+
+/**
+ * Disable kill switch — restore normal routing.
+ * Windows: removes netsh rules, macOS: disables pfctl, Linux: removes iptables rules.
+ */
+export function disableKillSwitch() {
+  if (!_killSwitchEnabled) return;
+
+  if (process.platform === 'win32') {
+    // Windows: remove firewall rules
+    const rules = [
+      'SentinelVPN-Allow-Tunnel',
+      'SentinelVPN-Allow-WG-Endpoint',
+      'SentinelVPN-Allow-Loopback',
+      'SentinelVPN-Allow-DHCP',
+      'SentinelVPN-Allow-DNS-Tunnel',
+      'SentinelVPN-Block-IPv6',
+    ];
+    for (const rule of rules) {
+      try { execFileSync('netsh', ['advfirewall', 'firewall', 'delete', 'rule', `name=${rule}`], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+    }
+
+    // Restore default outbound policy
+    try { execFileSync('netsh', ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,allowoutbound'], { stdio: 'pipe' }); } catch { /* best effort */ }
+
+  } else if (process.platform === 'darwin') {
+    // macOS: disable pf and remove temp rules
+    try { execFileSync('pfctl', ['-d'], { stdio: 'pipe' }); } catch { /* pf may already be disabled */ }
+    try { unlinkSync('/tmp/sentinel-killswitch.conf'); } catch { /* file may not exist */ }
+
+  } else {
+    // Linux: remove all sentinel-vpn rules
+    let hasRules = true;
+    while (hasRules) {
+      try {
+        execFileSync('iptables', ['-D', 'OUTPUT', '-m', 'comment', '--comment', 'sentinel-vpn', '-j', 'ACCEPT'], { stdio: 'pipe' });
+      } catch {
+        hasRules = false;
+      }
+    }
+    try { execFileSync('iptables', ['-D', 'OUTPUT', '-m', 'comment', '--comment', 'sentinel-vpn', '-j', 'DROP'], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+    try { execFileSync('ip6tables', ['-D', 'OUTPUT', '-m', 'comment', '--comment', 'sentinel-vpn', '-j', 'DROP'], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+  }
+
+  _killSwitchEnabled = false;
+  // Persist cleared kill switch state
+  try {
+    const conn = _defaultState.connection || {};
+    saveState({ sessionId: conn.sessionId, serviceType: conn.serviceType, nodeAddress: conn.nodeAddress, killSwitchEnabled: false });
+  } catch {} // best-effort
+}
+
+/** Check if kill switch is enabled */
+export function isKillSwitchEnabled() { return _killSwitchEnabled; }
+
+// ─── DNS Leak Prevention ────────────────────────────────────────────────────
+
+/**
+ * Enable DNS leak prevention by forcing all DNS through the VPN tunnel.
+ * Windows: netsh interface ipv4 set dnsservers + firewall rules
+ * macOS: networksetup -setdnsservers
+ * Linux: write /etc/resolv.conf
+ * @param {string} [dnsServer='10.8.0.1'] - DNS server inside the tunnel
+ * @param {string} [tunnelInterface='wgsent0'] - WireGuard tunnel interface name
+ */
+export function enableDnsLeakPrevention(dnsServer = '10.8.0.1', tunnelInterface = 'wgsent0') {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    // Set DNS on all interfaces to tunnel DNS
+    execFileSync('netsh', ['interface', 'ipv4', 'set', 'dnsservers', tunnelInterface, 'static', dnsServer, 'primary'], { stdio: 'pipe' });
+    // Block DNS on non-tunnel interfaces
+    execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule',
+      'name=SentinelDNSBlock', 'dir=out', 'protocol=udp', 'remoteport=53',
+      'action=block'], { stdio: 'pipe' });
+    execFileSync('netsh', ['advfirewall', 'firewall', 'add', 'rule',
+      'name=SentinelDNSAllow', 'dir=out', 'protocol=udp', 'remoteport=53',
+      'interface=' + tunnelInterface, 'action=allow'], { stdio: 'pipe' });
+  } else if (platform === 'darwin') {
+    // macOS: set DNS via networksetup for all services
+    const services = execFileSync('networksetup', ['-listallnetworkservices'], { encoding: 'utf8' })
+      .split('\n').filter(s => s && !s.startsWith('*'));
+    for (const svc of services) {
+      try { execFileSync('networksetup', ['-setdnsservers', svc.trim(), dnsServer], { stdio: 'pipe' }); } catch { /* best effort */ }
+    }
+  } else {
+    // Linux: backup and overwrite resolv.conf
+    try { execFileSync('cp', ['/etc/resolv.conf', '/etc/resolv.conf.sentinel.bak'], { stdio: 'pipe' }); } catch { /* backup may fail if file missing */ }
+    writeFileSync('/etc/resolv.conf', `nameserver ${dnsServer}\n`);
+  }
+}
+
+/**
+ * Disable DNS leak prevention and restore normal DNS resolution.
+ * Windows: removes firewall rules, resets DNS to DHCP
+ * macOS: clears DNS overrides
+ * Linux: restores /etc/resolv.conf from backup
+ */
+export function disableDnsLeakPrevention() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    try { execFileSync('netsh', ['advfirewall', 'firewall', 'delete', 'rule', 'name=SentinelDNSBlock'], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+    try { execFileSync('netsh', ['advfirewall', 'firewall', 'delete', 'rule', 'name=SentinelDNSAllow'], { stdio: 'pipe' }); } catch { /* rule may not exist */ }
+    // Reset DNS to DHCP
+    try { execFileSync('netsh', ['interface', 'ipv4', 'set', 'dnsservers', 'Wi-Fi', 'dhcp'], { stdio: 'pipe' }); } catch { /* interface may not exist */ }
+    try { execFileSync('netsh', ['interface', 'ipv4', 'set', 'dnsservers', 'Ethernet', 'dhcp'], { stdio: 'pipe' }); } catch { /* interface may not exist */ }
+  } else if (platform === 'darwin') {
+    const services = execFileSync('networksetup', ['-listallnetworkservices'], { encoding: 'utf8' })
+      .split('\n').filter(s => s && !s.startsWith('*'));
+    for (const svc of services) {
+      try { execFileSync('networksetup', ['-setdnsservers', svc.trim(), 'empty'], { stdio: 'pipe' }); } catch { /* best effort */ }
+    }
+  } else {
+    try { execFileSync('cp', ['/etc/resolv.conf.sentinel.bak', '/etc/resolv.conf'], { stdio: 'pipe' }); } catch { /* backup may not exist */ }
+  }
+}

package/connection/state.js

@@ -0,0 +1,369 @@
+/**
+ * Connection State — shared state, event emitter, metrics, wallet cache, and helpers.
+ *
+ * This module owns all mutable state that other connection modules depend on.
+ * Import ConnectionState, _defaultState, events, etc. from here.
+ */
+
+import { EventEmitter } from 'events';
+import { execFileSync } from 'child_process';
+import axios from 'axios';
+import { sha256 as _sha256 } from '@cosmjs/crypto';
+
+import {
+  createWallet, createClient, broadcast, buildEndSessionMsg,
+} from '../cosmjs-setup.js';
+import {
+  SentinelError, NodeError, ErrorCodes,
+} from '../errors.js';
+import {
+  saveState, clearState,
+} from '../state.js';
+import {
+  sleep, RPC_ENDPOINTS, tryWithFallback,
+} from '../defaults.js';
+
+// ─── Event Emitter ───────────────────────────────────────────────────────────
+// Subscribe to SDK lifecycle events without polling:
+//   import { events } from './connection/state.js';
+//   events.on('connected', ({ sessionId, serviceType }) => updateUI());
+//   events.on('disconnected', ({ reason }) => showNotification());
+//   events.on('progress', ({ step, detail }) => updateProgressBar());
+
+export const events = new EventEmitter();
+
+// ─── Cleanup Safety ──────────────────────────────────────────────────────────
+// Track whether registerCleanupHandlers() has been called. If a developer calls
+// connect() without registering, they risk orphaning WireGuard adapters or V2Ray
+// processes on crash/SIGINT — the "Dead Internet" bug.
+let _cleanupRegistered = false;
+
+export function isCleanupRegistered() { return _cleanupRegistered; }
+export function markCleanupRegistered() { _cleanupRegistered = true; }
+
+export function warnIfNoCleanup(fnName) {
+  if (!_cleanupRegistered) {
+    throw new SentinelError(ErrorCodes.INVALID_OPTIONS,
+      `${fnName}() called without registerCleanupHandlers(). ` +
+      `If your app crashes, WireGuard/V2Ray tunnels will orphan and kill the user's internet. ` +
+      `Call registerCleanupHandlers() once at app startup, or use quickConnect() which does it automatically.`
+    );
+  }
+}
+
+// ─── Connection Mutex ─────────────────────────────────────────────────────────
+// v27: Prevent concurrent connection attempts (backported from C# SemaphoreSlim).
+// Only one connect call may be in-flight at a time. quickConnect inherits via connectAuto.
+let _connectLock = false;
+
+// v30: Abort flag — disconnect() sets this to stop a running connectAuto() retry loop.
+// Without this, disconnect() clears tunnel state but connectAuto() keeps retrying,
+// paying for new sessions. The user cannot reconnect because _connectLock stays held.
+let _abortConnect = false;
+
+/** Check if a connection attempt is currently in progress. */
+export function isConnecting() { return _connectLock; }
+export function getConnectLock() { return _connectLock; }
+export function setConnectLock(v) { _connectLock = v; }
+export function getAbortConnect() { return _abortConnect; }
+export function setAbortConnect(v) { _abortConnect = v; }
+
+// ─── Connection State ─────────────────────────────────────────────────────────
+// v22: Encapsulated state enables per-instance connections via SentinelClient.
+// Module-level functions use _defaultState for backward compatibility.
+
+// Global registry of active states — used by exit handlers to clean up all instances
+export const _activeStates = new Set();
+
+export class ConnectionState {
+  constructor() {
+    this.v2rayProc = null;
+    this.wgTunnel = null;
+    this.systemProxy = false;
+    this.connection = null;  // { nodeAddress, serviceType, sessionId, connectedAt, socksPort? }
+    this.savedProxyState = null;
+    this._mnemonic = null;   // Stored for session-end TX on disconnect (zeroed after use)
+    _activeStates.add(this);
+  }
+  get isConnected() { return !!(this.v2rayProc || this.wgTunnel); }
+  destroy() { _activeStates.delete(this); }
+}
+
+export const _defaultState = new ConnectionState();
+
+// Default logger — can be overridden per-call via opts.log
+export let defaultLog = console.log;
+
+// ─── Wallet Cache ────────────────────────────────────────────────────────────
+// v21: Cache wallet derivation (BIP39 → SLIP-10 is CPU-bound, ~300ms).
+// Same mnemonic always produces the same wallet — safe to cache.
+// Keyed by full SHA256 of mnemonic to avoid storing the raw mnemonic.
+
+const _walletCache = new Map();
+
+export async function cachedCreateWallet(mnemonic) {
+  const key = Buffer.from(_sha256(Buffer.from(mnemonic))).toString('hex'); // full SHA256 — no truncation
+  if (_walletCache.has(key)) return _walletCache.get(key);
+  const result = await createWallet(mnemonic);
+  _walletCache.set(key, result);
+  return result;
+}
+
+/** Clear the wallet derivation cache. Call after disconnect to release key material from memory. */
+export function clearWalletCache() {
+  _walletCache.clear();
+}
+
+// ─── Connection Metrics (v25) ────────────────────────────────────────────────
+// Track per-node connection stats for reliability tracking over time.
+
+const _connectionMetrics = new Map(); // nodeAddress -> { attempts, successes, failures, avgTimeMs, lastAttempt }
+
+export function _recordMetric(nodeAddress, success, durationMs) {
+  const entry = _connectionMetrics.get(nodeAddress) || { attempts: 0, successes: 0, failures: 0, totalTimeMs: 0, lastAttempt: 0 };
+  entry.attempts++;
+  if (success) entry.successes++; else entry.failures++;
+  entry.totalTimeMs += durationMs || 0;
+  entry.lastAttempt = Date.now();
+  _connectionMetrics.set(nodeAddress, entry);
+}
+
+/**
+ * Get connection metrics for observability.
+ * @param {string} [nodeAddress] - Specific node, or omit for all.
+ * @returns {object} Per-node stats: { attempts, successes, failures, successRate, avgTimeMs, lastAttempt }
+ */
+export function getConnectionMetrics(nodeAddress) {
+  const format = (entry) => ({
+    ...entry,
+    successRate: entry.attempts > 0 ? entry.successes / entry.attempts : 0,
+    avgTimeMs: entry.attempts > 0 ? Math.round(entry.totalTimeMs / entry.attempts) : 0,
+  });
+  if (nodeAddress) {
+    const entry = _connectionMetrics.get(nodeAddress);
+    return entry ? format(entry) : null;
+  }
+  const result = {};
+  for (const [addr, entry] of _connectionMetrics) result[addr] = format(entry);
+  return result;
+}
+
+// ─── Abort helper ────────────────────────────────────────────────────────────
+
+export function checkAborted(signal) {
+  if (signal?.aborted) {
+    throw new SentinelError(ErrorCodes.ABORTED, 'Connection aborted', { reason: signal.reason });
+  }
+}
+
+// ─── Progress helper ─────────────────────────────────────────────────────────
+
+export function progress(cb, logFn, step, detail, meta = {}) {
+  const entry = { event: `sdk.${step}`, detail, ts: Date.now(), ...meta };
+  events.emit('progress', entry);
+  if (logFn) try { logFn(`[${step}] ${detail}`); } catch {} // user callback may throw — don't crash SDK
+  if (cb) try { cb(step, detail, entry); } catch {} // user callback may throw — don't crash SDK
+}
+
+// ─── Node Inactive Retry Helper ──────────────────────────────────────────────
+// LCD may show node as active, but chain rejects TX with code 105 ("invalid
+// status inactive") if the node went offline between query and payment.
+// Retry once after 15s in case LCD data was stale.
+
+export function _isNodeInactiveError(err) {
+  const msg = String(err?.message || '');
+  const code = err?.details?.code;
+  return msg.includes('invalid status inactive') || code === 105;
+}
+
+export async function broadcastWithInactiveRetry(client, address, msgs, logFn, onProgress) {
+  try {
+    return await broadcast(client, address, msgs);
+  } catch (err) {
+    if (_isNodeInactiveError(err)) {
+      progress(onProgress, logFn, 'session', 'Node reported inactive (code 105) — LCD stale data. Retrying in 15s...');
+      await sleep(15000);
+      try {
+        return await broadcast(client, address, msgs);
+      } catch (retryErr) {
+        if (_isNodeInactiveError(retryErr)) {
+          throw new NodeError(ErrorCodes.NODE_INACTIVE, 'Node went inactive between query and payment (code 105). LCD stale data confirmed after retry.', {
+            original: retryErr.message,
+            code: 105,
+          });
+        }
+        throw retryErr;
+      }
+    }
+    throw err;
+  }
+}
+
+// ─── Uptime Formatter ────────────────────────────────────────────────────────
+
+export function formatUptime(ms) {
+  const s = Math.floor(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m ${s % 60}s`;
+  return `${s}s`;
+}
+
+// ─── Session End (on-chain cleanup) ──────────────────────────────────────────
+
+/**
+ * End a session on-chain. Best-effort, fire-and-forget.
+ * Prevents stale session accumulation on nodes.
+ * @param {string|bigint} sessionId - Session ID to end
+ * @param {string} mnemonic - BIP39 mnemonic for signing the TX
+ * @private
+ */
+export async function _endSessionOnChain(sessionId, mnemonic) {
+  const { wallet, account } = await cachedCreateWallet(mnemonic);
+  const client = await tryWithFallback(
+    RPC_ENDPOINTS,
+    async (url) => createClient(url, wallet),
+    'RPC connect (session end)',
+  ).then(r => r.result);
+  const msg = buildEndSessionMsg(account.address, sessionId);
+  const fee = { amount: [{ denom: 'udvpn', amount: '20000' }], gas: '200000' };
+  const result = await client.signAndBroadcast(account.address, [msg], fee);
+  if (result.code !== 0) {
+    console.warn(`[sentinel-sdk] End session TX failed (code ${result.code}): ${result.rawLog}`);
+  } else {
+    console.log(`[sentinel-sdk] Session ${sessionId} ended on chain (TX ${result.transactionHash})`);
+  }
+}
+
+// ─── Connection Status (VPN UX: user must always know if they're connected) ─
+
+/**
+ * Check if a VPN tunnel is currently active.
+ * Use this to show connected/disconnected state in UI — like the VPN icon.
+ */
+export function isConnected() {
+  return _defaultState.isConnected;
+}
+
+/**
+ * Get current connection status. Returns null if disconnected.
+ * Apps should poll this (e.g. every 5s) to update UI — like NordVPN's status bar.
+ * v25: Includes healthChecks for tunnel/proxy liveness.
+ */
+export function getStatus() {
+  if (!_defaultState.connection) return null;
+
+  // v29: Cross-check tunnel liveness FIRST — if connection object exists but neither
+  // tunnel handle is truthy, the state is phantom (tunnel torn down, connection stale).
+  // This prevents IP leak where user thinks they're connected but traffic goes direct.
+  if (!_defaultState.wgTunnel && !_defaultState.v2rayProc) {
+    const stale = _defaultState.connection;
+    _defaultState.connection = null;
+    // End session on chain (fire-and-forget) to prevent stale session leaks
+    if (stale?.sessionId && _defaultState._mnemonic) {
+      _endSessionOnChain(stale.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    }
+    clearState();
+    events.emit('disconnected', { nodeAddress: stale.nodeAddress, serviceType: stale.serviceType, reason: 'phantom_state' });
+    return null;
+  }
+
+  const conn = _defaultState.connection;
+  const uptimeMs = Date.now() - conn.connectedAt;
+
+  // v25: Health checks — distinguish tunnel states
+  const healthChecks = {
+    tunnelActive: false,
+    proxyListening: false,
+    systemProxyValid: _defaultState.systemProxy,
+  };
+
+  if (_defaultState.wgTunnel) {
+    // WireGuard: check if adapter exists
+    if (process.platform === 'win32') {
+      try {
+        const out = execFileSync('netsh', ['interface', 'show', 'interface', 'name=wgsent0'], { encoding: 'utf8', stdio: 'pipe', timeout: 3000 });
+        healthChecks.tunnelActive = out.includes('Connected');
+      } catch {
+        // Adapter gone — tunnel is dead
+        healthChecks.tunnelActive = false;
+      }
+    } else {
+      // Non-Windows: trust state (no easy check)
+      healthChecks.tunnelActive = true;
+    }
+  }
+
+  if (_defaultState.v2rayProc) {
+    // V2Ray: check if process is alive
+    healthChecks.tunnelActive = !_defaultState.v2rayProc.killed && _defaultState.v2rayProc.exitCode === null;
+    // Proxy listening = process alive (async port check removed — was broken, fired after return)
+    healthChecks.proxyListening = healthChecks.tunnelActive;
+    if (conn.socksPort) {
+    }
+  }
+
+  // v28: Auto-clear phantom state — if connection exists but tunnel is dead,
+  // clean up stale state. Prevents ghost "connected" status after tunnel dies.
+  if (!healthChecks.tunnelActive && !_defaultState.v2rayProc && !_defaultState.wgTunnel) {
+    // Both tunnel handles are null — connection state is stale
+    if (conn?.sessionId && _defaultState._mnemonic) {
+      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    }
+    _defaultState.connection = null;
+    clearState();
+    return null;
+  }
+  if (_defaultState.wgTunnel && !healthChecks.tunnelActive) {
+    // WireGuard state says connected but tunnel is dead — auto-cleanup
+    if (conn?.sessionId && _defaultState._mnemonic) {
+      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    }
+    _defaultState.wgTunnel = null;
+    _defaultState.connection = null;
+    clearState();
+    events.emit('disconnected', { nodeAddress: conn.nodeAddress, serviceType: conn.serviceType, reason: 'tunnel_died' });
+    return null;
+  }
+  if (_defaultState.v2rayProc && !healthChecks.tunnelActive) {
+    // V2Ray process died — auto-cleanup
+    if (conn?.sessionId && _defaultState._mnemonic) {
+      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    }
+    _defaultState.v2rayProc = null;
+    _defaultState.connection = null;
+    clearState();
+    events.emit('disconnected', { nodeAddress: conn.nodeAddress, serviceType: conn.serviceType, reason: 'tunnel_died' });
+    return null;
+  }
+
+  return {
+    connected: _defaultState.isConnected,
+    ...conn,
+    uptimeMs,
+    uptimeFormatted: formatUptime(uptimeMs),
+    healthChecks,
+  };
+}
+
+// ─── Verify Connection (v26c) ────────────────────────────────────────────────
+
+/**
+ * Verify VPN is working by checking if IP has changed.
+ * Fetches public IP via ipify.org and compares to a direct (non-VPN) fetch.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=8000]
+ * @returns {Promise<{ working: boolean, vpnIp: string|null, error?: string }>}
+ */
+export async function verifyConnection(opts = {}) {
+  const timeout = opts.timeoutMs || 8000;
+  try {
+    const res = await axios.get('https://api.ipify.org?format=json', { timeout });
+    const vpnIp = res.data?.ip || null;
+    return { working: !!vpnIp, vpnIp };
+  } catch (err) {
+    return { working: false, vpnIp: null, error: err.message };
+  }
+}