blue-js-sdk 2.0.0

package/batch.js

@@ -0,0 +1,293 @@
+/**
+ * Sentinel dVPN SDK — Batch Session Operations
+ *
+ * ⚠️  TESTING / AUDITING TOOL ONLY — NOT FOR CONSUMER APPS  ⚠️
+ *
+ * Batch session creation: start multiple node sessions in a single transaction.
+ * This is designed for network audit tools that test hundreds of nodes sequentially.
+ *
+ * WHY THIS EXISTS:
+ *   The Node Tester audits 1,000+ nodes. Paying individually = 1,000 TXs = 200 P2P in gas.
+ *   Batching 5 per TX = 200 TXs = 40 P2P in gas. 5x cheaper.
+ *
+ * WHY CONSUMER APPS SHOULD NOT USE THIS:
+ *   - Consumer apps connect to ONE node at a time. Use `connect()` or `connectDirect()`.
+ *   - Batch payment creates sessions for 5 nodes simultaneously — wasteful for single-node use.
+ *   - If any node in the batch fails, the entire TX fails (atomic).
+ *   - Session management complexity (credential caching, poisoning, dedup) is audit-level concern.
+ *
+ * FOR CONSUMER APPS: use `connect(mnemonic, options)` from the SDK. One function, one node, done.
+ *
+ * Usage (audit tools only):
+ *   import { batchStartSessions } from './batch.js';
+ *   const results = await batchStartSessions(client, account, nodes, 1, 'udvpn');
+ *   // results = Map<nodeAddr, BigInt sessionId>
+ */
+
+import { ChainError, ErrorCodes } from './errors.js';
+import { sleep } from './defaults.js';
+import {
+  broadcast,
+  extractAllSessionIds,
+  findExistingSession,
+  lcdPaginatedSafe,
+  MSG_TYPES,
+} from './cosmjs-setup.js';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Default batch size limit (chain-tested safe maximum) */
+const DEFAULT_BATCH_SIZE = 5;
+
+/** Default gas per message */
+const GAS_PER_MSG = 800000;
+
+/** Default fee per message (udvpn) */
+const FEE_PER_MSG = 200000;
+
+/** Wait time before polling chain for session confirmation (ms) */
+const POST_TX_POLL_DELAY = 2000;
+
+/** Max time to wait for sessions to appear on-chain (ms) */
+const DEFAULT_POLL_TIMEOUT = 20000;
+
+// ─── Batch Start Sessions ────────────────────────────────────────────────────
+
+/**
+ * Start sessions for multiple nodes in a single transaction.
+ * Builds N MsgStartSessionRequest messages, broadcasts as one TX,
+ * and extracts session IDs from the TX events.
+ *
+ * Handles:
+ *   - Duplicate payment detection (via sessionManager if provided)
+ *   - Session ID extraction from base64-encoded TX events
+ *   - Fallback: on-chain lookup if extraction fails for some sessions
+ *   - Cost tracking via optional onCost callback
+ *
+ * @param {SigningStargateClient} client - CosmJS signing client
+ * @param {{ address: string }} account - Signer account with .address
+ * @param {Array<{ address: string, gigabyte_prices: Array<{ denom: string, base_value: string, quote_value: string }> }>} nodes - Nodes to start sessions on
+ * @param {number} gigabytes - GB to allocate per session (typically 1)
+ * @param {string} denom - Token denomination (typically 'udvpn')
+ * @param {object} [options]
+ * @param {import('./session-manager.js').SessionManager} [options.sessionManager] - SessionManager for dedup/caching
+ * @param {number} [options.batchSize=5] - Max messages per TX
+ * @param {Function} [options.logger] - Optional logger function (msg) => void
+ * @param {Function} [options.onCost] - Called with { udvpn: number } after each TX (for cost tracking)
+ * @param {string} [options.lcdUrl] - LCD URL for fallback session lookups
+ * @returns {Promise<Map<string, bigint>>} Map of nodeAddr -> sessionId for all started sessions
+ */
+export async function batchStartSessions(client, account, nodes, gigabytes, denom, options = {}) {
+  const {
+    sessionManager,
+    batchSize = DEFAULT_BATCH_SIZE,
+    logger,
+    onCost,
+    lcdUrl,
+  } = options;
+
+  const log = logger || (() => {});
+  const allResults = new Map();
+
+  // Split into batches
+  const batches = [];
+  for (let i = 0; i < nodes.length; i += batchSize) {
+    batches.push(nodes.slice(i, i + batchSize));
+  }
+
+  for (const batch of batches) {
+    const batchResult = await _processBatch(
+      client, account, batch, gigabytes, denom,
+      { sessionManager, log, onCost, lcdUrl },
+    );
+    for (const [addr, sid] of batchResult) {
+      allResults.set(addr, sid);
+    }
+  }
+
+  return allResults;
+}
+
+// ─── Internal: Process a Single Batch ────────────────────────────────────────
+
+/**
+ * Process a single batch of nodes: build messages, broadcast, extract IDs.
+ * @private
+ */
+async function _processBatch(client, account, batch, gigabytes, denom, ctx) {
+  const { sessionManager, log, onCost, lcdUrl } = ctx;
+  const result = new Map();
+
+  // Filter out already-paid nodes
+  const toPayBatch = [];
+  for (const node of batch) {
+    if (sessionManager?.isPaid(node.address)) {
+      log(`Skip ${node.address.slice(0, 20)}... - already paid this run`);
+      continue;
+    }
+
+    const priceEntry = (node.gigabyte_prices || []).find(p => p.denom === denom);
+    if (!priceEntry) {
+      log(`Skip ${node.address.slice(0, 20)}... - no ${denom} pricing`);
+      continue;
+    }
+
+    toPayBatch.push({ node, priceEntry });
+  }
+
+  if (toPayBatch.length === 0) return result;
+
+  // Build messages
+  const messages = toPayBatch.map(({ node, priceEntry }) => ({
+    typeUrl: MSG_TYPES.START_SESSION,
+    value: {
+      from: account.address,
+      node_address: node.address,
+      gigabytes,
+      hours: 0,
+      max_price: {
+        denom: priceEntry.denom,
+        base_value: priceEntry.base_value,
+        quote_value: priceEntry.quote_value,
+      },
+    },
+  }));
+
+  // Calculate fee
+  const n = toPayBatch.length;
+  const fee = {
+    amount: [{ denom, amount: String(FEE_PER_MSG * n) }],
+    gas: String(GAS_PER_MSG * n),
+  };
+
+  // Broadcast
+  let txResult;
+  try {
+    txResult = await broadcast(client, account.address, messages, fee);
+  } catch (err) {
+    throw new ChainError(
+      ErrorCodes.BROADCAST_FAILED,
+      `Batch session TX failed (${n} nodes): ${err.message}`,
+      { nodeCount: n, original: err.message },
+    );
+  }
+
+  // Extract session IDs from TX events
+  const ids = extractAllSessionIds(txResult);
+
+  const unmatchedNodes = [];
+  toPayBatch.forEach(({ node }, i) => {
+    // Mark as paid regardless
+    if (sessionManager) sessionManager.markPaid(node.address);
+
+    if (ids[i]) {
+      result.set(node.address, ids[i]);
+      if (sessionManager) sessionManager.addToSessionMap(node.address, ids[i]);
+    } else {
+      unmatchedNodes.push(node.address);
+    }
+  });
+
+  // Fallback: look up missing session IDs on-chain
+  if (unmatchedNodes.length > 0) {
+    log(`${unmatchedNodes.length} session IDs not extracted from TX, looking up on chain...`);
+    await sleep(POST_TX_POLL_DELAY);
+
+    if (sessionManager) sessionManager.invalidateSessionMap();
+
+    for (const addr of unmatchedNodes) {
+      try {
+        const sid = sessionManager
+          ? await sessionManager.findExistingSession(addr)
+          : await findExistingSession(lcdUrl, account.address, addr);
+        if (sid) {
+          result.set(addr, sid);
+        } else {
+          log(`Could not find session for ${addr.slice(0, 20)}... - may need individual payment`);
+        }
+      } catch (err) {
+        log(`Fallback lookup failed for ${addr.slice(0, 20)}...: ${err.message}`);
+      }
+    }
+  }
+
+  // Log TX hash
+  log(`Batch TX (${n} msgs): ${txResult.transactionHash.slice(0, 16)}...`);
+
+  // Report cost
+  if (onCost) {
+    let sessionCost = 0;
+    for (const { node } of toPayBatch) {
+      const priceEntry = (node.gigabyte_prices || []).find(p => p.denom === denom);
+      if (priceEntry) {
+        sessionCost += Math.round(parseFloat(priceEntry.quote_value) || 0) * gigabytes;
+      }
+    }
+    const gasCost = FEE_PER_MSG * n;
+    onCost({ udvpn: sessionCost + gasCost, sessionCost, gasCost, txHash: txResult.transactionHash });
+  }
+
+  return result;
+}
+
+// ─── Wait for Batch Sessions ─────────────────────────────────────────────────
+
+/**
+ * Poll until all node sessions appear on chain, or timeout.
+ * Useful after batch payment to ensure sessions are confirmed before handshake.
+ *
+ * @param {string[]} nodeAddrs - Node addresses to wait for
+ * @param {string} walletAddr - Wallet address
+ * @param {string} [lcdUrl] - LCD endpoint URL
+ * @param {object} [options]
+ * @param {number} [options.maxWaitMs=20000] - Maximum wait time in ms
+ * @param {number} [options.pollIntervalMs=2000] - Poll interval in ms
+ * @returns {Promise<{ confirmed: string[], pending: string[] }>}
+ */
+export async function waitForBatchSessions(nodeAddrs, walletAddr, lcdUrl, options = {}) {
+  const maxWaitMs = options.maxWaitMs ?? DEFAULT_POLL_TIMEOUT;
+  const pollIntervalMs = options.pollIntervalMs ?? 2000;
+  const baseLcd = lcdUrl || 'https://lcd.sentinel.co';
+
+  if (nodeAddrs.length === 0) return { confirmed: [], pending: [] };
+
+  const pending = new Set(nodeAddrs);
+  const deadline = Date.now() + maxWaitMs;
+
+  while (pending.size > 0 && Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+    try {
+      const result = await lcdPaginatedSafe(
+        baseLcd,
+        `/sentinel/session/v3/sessions?address=${walletAddr}&status=1`,
+        'sessions',
+      );
+      for (const s of (result.items || [])) {
+        const bs = s.base_session || s;
+        const n = bs.node_address || bs.node;
+        if (pending.has(n)) pending.delete(n);
+      }
+    } catch {
+      // Transient LCD error — will retry on next poll
+    }
+  }
+
+  const confirmed = nodeAddrs.filter(a => !pending.has(a));
+  return { confirmed, pending: [...pending] };
+}
+
+/**
+ * Wait for a single session to appear on chain.
+ * Convenience wrapper around waitForBatchSessions.
+ *
+ * @param {string} nodeAddr - Node address
+ * @param {string} walletAddr - Wallet address
+ * @param {string} [lcdUrl] - LCD endpoint URL
+ * @param {object} [options]
+ * @param {number} [options.maxWaitMs=20000] - Maximum wait time in ms
+ * @returns {Promise<boolean>} True if session confirmed, false if timed out
+ */
+export async function waitForSessionActive(nodeAddr, walletAddr, lcdUrl, options = {}) {
+  const { confirmed } = await waitForBatchSessions([nodeAddr], walletAddr, lcdUrl, options);
+  return confirmed.includes(nodeAddr);
+}

package/bin/setup.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/**
+ * Sentinel dVPN SDK — Setup Script
+ *
+ * Downloads required binaries (V2Ray, WireGuard) for the current platform.
+ * Run: node setup.js
+ *
+ * What it does:
+ * 1. Checks if V2Ray v5.2.1 exists in bin/ — downloads if missing
+ * 2. Checks if WireGuard is installed — prints install instructions if missing
+ * 3. Verifies all SDK dependencies are installed (npm install)
+ */
+
+import { existsSync, mkdirSync, createWriteStream, unlinkSync, readFileSync } from 'fs';
+import { execSync, execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import https from 'https';
+import http from 'http';
+
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = __dirname;
+
+import { V2RAY_VERSION } from '../defaults.js';
+const V2RAY_URLS = {
+  'win32-x64':  `https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-windows-64.zip`,
+  'win32-ia32': `https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-windows-32.zip`,
+  'linux-x64':  `https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-linux-64.zip`,
+  'linux-arm64':`https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-linux-arm64-v8a.zip`,
+  'darwin-x64': `https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-macos-64.zip`,
+  'darwin-arm64':`https://github.com/v2fly/v2ray-core/releases/download/v${V2RAY_VERSION}/v2ray-macos-arm64-v8a.zip`,
+};
+
+const V2RAY_BINARY = process.platform === 'win32' ? 'v2ray.exe' : 'v2ray';
+const V2RAY_FILES = [V2RAY_BINARY, 'geoip.dat', 'geosite.dat'];
+
+// SHA256 checksums for V2Ray v5.2.1 release binaries (from official .dgst files)
+const V2RAY_SHA256 = {
+  'win32-x64':   'd9791f911b603437a34219488b0111ae9913f38abe22c0103abce330537dabd6',
+  'win32-ia32':  'dc9f37dbeb32221e62b9a52b79f1842a217f049675872b334e1e5fd96121d0d2',
+  'linux-x64':   '56eb8d4727b058d10f8ff830bb0121381386b0695171767f38ba410f2613fc9a',
+  'linux-arm64': '63958429e93f24f10f34a64701f70b4f42dfa0bc8120e1c0a426c6161bd2a3c9',
+  'darwin-x64':  'edbb0b94c05570d39a4549186927369853542649eb6b703dd432bda300c5d51a',
+  'darwin-arm64':'e18c17a79c4585d963395ae6ddafffb18c5d22777f7ac5938c1b40563db88d56',
+};
+
+// ─── WireGuard Download URLs (verified 2026-03-26) ─────────────────────────
+// Direct MSI downloads — no browser, no bootstrapper, silent-installable
+const WG_VERSION = '0.5.3';
+const WG_URLS = {
+  'win32-x64':   `https://download.wireguard.com/windows-client/wireguard-amd64-${WG_VERSION}.msi`,
+  'win32-arm64': `https://download.wireguard.com/windows-client/wireguard-arm64-${WG_VERSION}.msi`,
+  'win32-ia32':  `https://download.wireguard.com/windows-client/wireguard-x86-${WG_VERSION}.msi`,
+};
+const WG_INSTALL_URL = 'https://download.wireguard.com/windows-client/wireguard-installer.exe';
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function log(msg) { console.log(`[setup] ${msg}`); }
+function warn(msg) { console.log(`[setup] ⚠ ${msg}`); }
+function ok(msg) { console.log(`[setup] ✓ ${msg}`); }
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const follow = (url, redirects = 0) => {
+      if (redirects > 5) return reject(new Error('Too many redirects'));
+      const mod = url.startsWith('https') ? https : http;
+      mod.get(url, { headers: { 'User-Agent': 'sentinel-sdk-setup' } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return follow(res.headers.location, redirects + 1);
+        }
+        if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        const file = createWriteStream(dest);
+        res.pipe(file);
+        file.on('finish', () => file.close(resolve));
+        file.on('error', reject);
+      }).on('error', reject);
+    };
+    follow(url);
+  });
+}
+
+function unzip(zipPath, destDir) {
+  // Use PowerShell on Windows, unzip on others
+  if (process.platform === 'win32') {
+    execFileSync('powershell', ['-NoProfile', '-Command', `Expand-Archive -Force -Path '${zipPath}' -DestinationPath '${destDir}'`], { stdio: 'pipe' });
+  } else {
+    execFileSync('unzip', ['-o', zipPath, '-d', destDir], { stdio: 'pipe' });
+  }
+}
+
+// ─── V2Ray ──────────────────────────────────────────────────────────────────
+
+async function setupV2Ray() {
+  const v2rayPath = path.join(BIN_DIR, V2RAY_BINARY);
+
+  // Check if already exists
+  if (existsSync(v2rayPath)) {
+    ok(`V2Ray found at ${v2rayPath}`);
+    // Verify companion files
+    for (const f of V2RAY_FILES) {
+      if (!existsSync(path.join(BIN_DIR, f))) {
+        warn(`Missing ${f} in bin/ — re-downloading`);
+        break;
+      }
+    }
+    if (V2RAY_FILES.every(f => existsSync(path.join(BIN_DIR, f)))) return;
+  }
+
+  // Check system-wide
+  const systemPaths = [
+    'C:\\Program Files\\V2Ray\\v2ray.exe',
+    'C:\\Program Files (x86)\\V2Ray\\v2ray.exe',
+    '/usr/local/bin/v2ray',
+    '/usr/bin/v2ray',
+  ];
+  for (const p of systemPaths) {
+    if (existsSync(p)) {
+      ok(`V2Ray found at ${p} (system install)`);
+      log('Tip: copy v2ray.exe + geoip.dat + geosite.dat to bin/ for portability');
+      return;
+    }
+  }
+
+  // Download
+  const platform = `${process.platform}-${process.arch}`;
+  const url = V2RAY_URLS[platform];
+  if (!url) {
+    warn(`No V2Ray binary available for ${platform}`);
+    warn(`Download manually from: https://github.com/v2fly/v2ray-core/releases/tag/v${V2RAY_VERSION}`);
+    warn(`Place v2ray${process.platform === 'win32' ? '.exe' : ''}, geoip.dat, geosite.dat in bin/`);
+    return;
+  }
+
+  mkdirSync(BIN_DIR, { recursive: true });
+  const zipPath = path.join(BIN_DIR, 'v2ray.zip');
+
+  log(`Downloading V2Ray v${V2RAY_VERSION} for ${platform}...`);
+  log(`URL: ${url}`);
+  await download(url, zipPath);
+
+  // SHA256 verification
+  const expectedHash = V2RAY_SHA256[platform];
+  if (expectedHash) {
+    const fileData = readFileSync(zipPath);
+    const actualHash = createHash('sha256').update(fileData).digest('hex');
+    if (actualHash !== expectedHash) {
+      unlinkSync(zipPath);
+      throw new Error(
+        `V2Ray SHA256 mismatch! Expected ${expectedHash}, got ${actualHash}. ` +
+        `Download may be corrupt or tampered. Delete bin/ and retry.`
+      );
+    }
+    ok('SHA256 checksum verified');
+  } else {
+    warn(`No SHA256 checksum for ${platform} — skipping verification`);
+  }
+
+  log('Extracting...');
+  unzip(zipPath, BIN_DIR);
+  unlinkSync(zipPath);
+
+  // Verify extraction + version check
+  if (existsSync(v2rayPath)) {
+    if (process.platform !== 'win32') {
+      execFileSync('chmod', ['+x', v2rayPath], { stdio: 'pipe' });
+    }
+    // Verify the binary runs and reports correct version
+    try {
+      const versionOut = execFileSync(v2rayPath, ['version'], { encoding: 'utf8', timeout: 10000, stdio: 'pipe' });
+      if (versionOut.includes(V2RAY_VERSION)) {
+        ok(`V2Ray v${V2RAY_VERSION} installed and verified`);
+      } else {
+        warn(`V2Ray binary reports unexpected version: ${versionOut.trim().split('\n')[0]}`);
+      }
+    } catch {
+      warn('V2Ray installed but version check failed (binary may not be executable on this platform)');
+    }
+  } else {
+    warn('V2Ray extraction failed — check bin/ directory');
+  }
+}
+
+// ─── WireGuard ──────────────────────────────────────────────────────────────
+
+function findWireGuard() {
+  // Windows: check standard install paths
+  if (process.platform === 'win32') {
+    const paths = [
+      'C:\\Program Files\\WireGuard\\wireguard.exe',
+      'C:\\Program Files (x86)\\WireGuard\\wireguard.exe',
+    ];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  }
+
+  // macOS/Linux: check wg-quick
+  if (process.platform !== 'win32') {
+    const paths = ['/usr/bin/wg', '/usr/local/bin/wg', '/opt/homebrew/bin/wg'];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  }
+
+  // Check system PATH
+  try {
+    const cmd = process.platform === 'win32' ? 'where wireguard.exe' : 'which wg';
+    const result = execSync(cmd, { encoding: 'utf8', stdio: 'pipe' }).trim();
+    if (result) return result.split('\n')[0];
+  } catch { /* not in PATH */ }
+
+  return null;
+}
+
+function isAdmin() {
+  if (process.platform === 'win32') {
+    try {
+      execSync('net session', { stdio: 'pipe' });
+      return true;
+    } catch {
+      try {
+        execSync('fsutil dirty query C:', { stdio: 'pipe' });
+        return true;
+      } catch { return false; }
+    }
+  }
+  return process.getuid?.() === 0;
+}
+
+async function setupWireGuard() {
+  const existing = findWireGuard();
+  if (existing) {
+    ok(`WireGuard found at ${existing}`);
+    return;
+  }
+
+  // ─── Windows: auto-download MSI and silent install ───
+  if (process.platform === 'win32') {
+    const platform = `${process.platform}-${process.arch}`;
+    const msiUrl = WG_URLS[platform];
+
+    if (!msiUrl) {
+      warn(`No WireGuard MSI for ${platform}`);
+      log(`Download manually from: ${WG_INSTALL_URL}`);
+      return;
+    }
+
+    if (!isAdmin()) {
+      warn('WireGuard not installed — admin privileges required for automatic install');
+      log('Run setup as Administrator, or install manually:');
+      log(`  Download: ${msiUrl}`);
+      log(`  Install:  msiexec /i wireguard-amd64-${WG_VERSION}.msi /qn /norestart`);
+      log('');
+      log('WireGuard is optional — V2Ray nodes (~70% of network) work without it');
+      return;
+    }
+
+    const msiPath = path.join(BIN_DIR, `wireguard-${WG_VERSION}.msi`);
+    mkdirSync(BIN_DIR, { recursive: true });
+
+    log(`Downloading WireGuard v${WG_VERSION} for ${platform}...`);
+    log(`URL: ${msiUrl}`);
+    await download(msiUrl, msiPath);
+
+    log('Installing WireGuard (silent)...');
+    try {
+      execSync(`msiexec /i "${msiPath}" /qn /norestart`, {
+        stdio: 'pipe',
+        timeout: 60000,
+      });
+
+      // Verify installation
+      const installed = findWireGuard();
+      if (installed) {
+        ok(`WireGuard v${WG_VERSION} installed at ${installed}`);
+      } else {
+        warn('WireGuard MSI completed but binary not found — may need reboot');
+      }
+    } catch (err) {
+      warn(`WireGuard MSI install failed: ${err.message}`);
+      log('Try installing manually:');
+      log(`  msiexec /i "${msiPath}" /qn /norestart`);
+    }
+
+    // Clean up MSI
+    try { unlinkSync(msiPath); } catch { /* ignore */ }
+    return;
+  }
+
+  // ─── macOS: use Homebrew ───
+  if (process.platform === 'darwin') {
+    try {
+      execSync('which brew', { stdio: 'pipe' });
+      log('Installing WireGuard via Homebrew...');
+      execSync('brew install wireguard-tools', { stdio: 'inherit', timeout: 120000 });
+      ok('WireGuard installed via Homebrew');
+      return;
+    } catch {
+      warn('WireGuard not found and Homebrew not available');
+      log('Install Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"');
+      log('Then: brew install wireguard-tools');
+      return;
+    }
+  }
+
+  // ─── Linux: use package manager ───
+  if (process.platform === 'linux') {
+    const managers = [
+      { cmd: 'apt-get', install: 'sudo apt-get install -y wireguard-tools' },
+      { cmd: 'dnf', install: 'sudo dnf install -y wireguard-tools' },
+      { cmd: 'pacman', install: 'sudo pacman -S --noconfirm wireguard-tools' },
+      { cmd: 'apk', install: 'sudo apk add wireguard-tools' },
+    ];
+
+    for (const mgr of managers) {
+      try {
+        execSync(`which ${mgr.cmd}`, { stdio: 'pipe' });
+        if (isAdmin()) {
+          log(`Installing WireGuard via ${mgr.cmd}...`);
+          execSync(mgr.install, { stdio: 'inherit', timeout: 120000 });
+          ok('WireGuard installed');
+        } else {
+          warn('WireGuard not installed — root required');
+          log(`Install: ${mgr.install}`);
+        }
+        return;
+      } catch { /* try next manager */ }
+    }
+
+    warn('WireGuard not found and no supported package manager detected');
+    log('Install wireguard-tools for your distribution');
+  }
+}
+
+// ─── npm dependencies ───────────────────────────────────────────────────────
+
+function checkDeps() {
+  if (!existsSync(path.join(__dirname, 'node_modules'))) {
+    log('Installing npm dependencies...');
+    execSync('npm install', { cwd: __dirname, stdio: 'inherit' });
+    ok('Dependencies installed');
+  } else {
+    ok('npm dependencies present');
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('');
+  console.log('  Sentinel dVPN SDK — Setup');
+  console.log('  ─────────────────────────');
+  console.log('');
+
+  checkDeps();
+  await setupV2Ray();
+  await setupWireGuard();
+
+  console.log('');
+  console.log('  Setup complete! Quick start:');
+  console.log('');
+  console.log('    import { connect, listNodes, registerCleanupHandlers } from \'./index.js\';');
+  console.log('');
+  console.log('    registerCleanupHandlers();');
+  console.log('    const nodes = await listNodes();');
+  console.log('    const conn = await connect({ mnemonic: \'...\', nodeAddress: nodes[0].address });');
+  console.log('');
+}
+
+main().catch(err => {
+  console.error(`[setup] Fatal: ${err.message}`);
+  process.exit(1);
+});