fix: improve Windows tunnel support

2026-06-05 15:01:22 +03:00
parent e823497cf1
commit 16fdff530b
24 changed files with 936 additions and 151 deletions
@@ -4,6 +4,10 @@ import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import yaml from 'yaml';
+import {
+  createExecutableSearchEnv,
+  resolveExecutableLaunchTarget,
+} from './tunnels/executable-search.js';

 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -17,52 +21,18 @@ const TUNNEL_MODE_QUICK = 'quick';
 const TUNNEL_MODE_MANAGED_REMOTE = 'managed-remote';
 const TUNNEL_MODE_MANAGED_LOCAL = 'managed-local';

-async function searchPathFor(command) {
-  const pathValue = process.env.PATH || '';
-  const segments = pathValue.split(path.delimiter).filter(Boolean);
-  const WINDOWS_EXTENSIONS = process.platform === 'win32'
-    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
-        .split(';')
-        .map((ext) => ext.trim().toLowerCase())
-        .filter(Boolean)
-        .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`))
-    : [''];
-
-  for (const dir of segments) {
-    for (const ext of WINDOWS_EXTENSIONS) {
-      const fileName = process.platform === 'win32' ? `${command}${ext}` : command;
-      const candidate = path.join(dir, fileName);
-      try {
-        const stats = fs.statSync(candidate);
-        if (stats.isFile()) {
-          if (process.platform !== 'win32') {
-            try {
-              fs.accessSync(candidate, fs.constants.X_OK);
-            } catch {
-              continue;
-            }
-          }
-          return candidate;
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-  return null;
-}
-
 export async function checkCloudflaredAvailable() {
-  const cfPath = await searchPathFor('cloudflared');
-  if (cfPath) {
+  const target = resolveExecutableLaunchTarget('cloudflared');
+  if (target) {
    try {
-      const result = spawnSync(cfPath, ['--version'], {
+      const result = spawnSync(target.command, ['--version'], {
        encoding: 'utf8',
        stdio: ['pipe', 'pipe', 'pipe'],
        windowsHide: true,
+        env: target.env,
      });
      if (result.status === 0) {
-        return { available: true, path: cfPath, version: result.stdout.trim() };
+        return { available: true, path: target.command, version: result.stdout.trim() };
      }
    } catch {
      // Ignore
@@ -102,7 +72,7 @@ const spawnCloudflared = (args, envOverrides = {}, resolvedBinaryPath = 'cloudfl
  stdio: ['ignore', 'pipe', 'pipe'],
  windowsHide: true,
  env: {
-    ...process.env,
+    ...createExecutableSearchEnv(),
    CF_TELEMETRY_DISABLE: '1',
    ...envOverrides,
  },
@@ -1,59 +1,29 @@
 import { spawn, spawnSync } from 'child_process';
-import fs from 'fs';
-import path from 'path';
+import {
+  createExecutableSearchEnv,
+  resolveExecutableLaunchTarget,
+} from './tunnels/executable-search.js';
+import { getTunnelDependencyInstallInfo } from './tunnels/install-help.js';
+import { TUNNEL_PROVIDER_NGROK } from './tunnels/types.js';

 const DEFAULT_STARTUP_TIMEOUT_MS = 30000;
 const NGROK_API_URL = 'http://127.0.0.1:4040/api/tunnels';
-const NGROK_INSTALL_HELP = 'brew install ngrok';
+const NGROK_PUBLIC_URL_REGEX = /https:\/\/[^\s"']+/i;
 const NGROK_AUTHTOKEN_HELP = 'Run: ngrok config add-authtoken <your-ngrok-token>';
-
-async function searchPathFor(command) {
-  const pathValue = process.env.PATH || '';
-  const segments = pathValue.split(path.delimiter).filter(Boolean);
-  const WINDOWS_EXTENSIONS = process.platform === 'win32'
-    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
-        .split(';')
-        .map((ext) => ext.trim().toLowerCase())
-        .filter(Boolean)
-        .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`))
-    : [''];
-
-  for (const dir of segments) {
-    for (const ext of WINDOWS_EXTENSIONS) {
-      const fileName = process.platform === 'win32' ? `${command}${ext}` : command;
-      const candidate = path.join(dir, fileName);
-      try {
-        const stats = fs.statSync(candidate);
-        if (!stats.isFile()) {
-          continue;
-        }
-        if (process.platform !== 'win32') {
-          try {
-            fs.accessSync(candidate, fs.constants.X_OK);
-          } catch {
-            continue;
-          }
-        }
-        return candidate;
-      } catch {
-        continue;
-      }
-    }
-  }
-  return null;
-}
+const getNgrokInstallInfo = () => getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_NGROK);

 export async function checkNgrokAvailable() {
-  const ngrokPath = await searchPathFor('ngrok');
-  if (ngrokPath) {
+  const target = resolveExecutableLaunchTarget('ngrok');
+  if (target) {
    try {
-      const result = spawnSync(ngrokPath, ['version'], {
+      const result = spawnSync(target.command, ['version'], {
        encoding: 'utf8',
        stdio: ['pipe', 'pipe', 'pipe'],
        windowsHide: true,
+        env: target.env,
      });
      if (result.status === 0) {
-        return { available: true, path: ngrokPath, version: result.stdout.trim() || result.stderr.trim() };
+        return { available: true, path: target.command, version: result.stdout.trim() || result.stderr.trim() };
      }
    } catch {
      // Ignore and report unavailable below.
@@ -67,16 +37,19 @@ export async function checkNgrokAuthtokenConfigured(ngrokPath = null) {
    return { configured: true, detail: 'NGROK_AUTHTOKEN is set.' };
  }

-  const resolvedPath = ngrokPath || await searchPathFor('ngrok');
-  if (!resolvedPath) {
-    return { configured: false, detail: `ngrok is not installed. Install it with: ${NGROK_INSTALL_HELP}` };
+  const target = ngrokPath
+    ? { command: ngrokPath, env: createExecutableSearchEnv() }
+    : resolveExecutableLaunchTarget('ngrok');
+  if (!target) {
+    return { configured: false, detail: getNgrokInstallInfo().message };
  }

  try {
-    const result = spawnSync(resolvedPath, ['config', 'check'], {
+    const result = spawnSync(target.command, ['config', 'check'], {
      encoding: 'utf8',
      stdio: ['pipe', 'pipe', 'pipe'],
      windowsHide: true,
+      env: target.env,
    });
    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
    if (result.status === 0) {
@@ -118,10 +91,138 @@ export async function checkNgrokApiReachability({ fetchImpl = globalThis.fetch,
 const spawnNgrok = (args, resolvedBinaryPath = 'ngrok') => spawn(resolvedBinaryPath, args, {
  stdio: ['ignore', 'pipe', 'pipe'],
  windowsHide: true,
-  env: process.env,
+  env: createExecutableSearchEnv(),
  killSignal: 'SIGINT',
 });

+const normalizeNgrokPublicUrl = (value) => {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return null;
+  }
+  const trimmed = value.trim();
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol === 'https:' && parsed.hostname.includes('ngrok')) {
+      return parsed.toString().replace(/\/$/, '');
+    }
+  } catch {
+    return null;
+  }
+  return null;
+};
+
+export function extractNgrokPublicUrlFromText(text) {
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return null;
+  }
+
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      const parsedUrl = normalizeNgrokPublicUrl(parsed?.url) || normalizeNgrokPublicUrl(parsed?.public_url);
+      if (parsedUrl) {
+        return parsedUrl;
+      }
+    } catch {
+      // ngrok may emit non-JSON diagnostics even when log-format=json.
+    }
+
+    const match = line.match(NGROK_PUBLIC_URL_REGEX);
+    const matchedUrl = normalizeNgrokPublicUrl(match?.[0]);
+    if (matchedUrl) {
+      return matchedUrl;
+    }
+  }
+
+  return null;
+}
+
+const normalizeNgrokDiagnosticText = (value) => {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value
+    .replace(/\r/g, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+export const summarizeNgrokOutput = (lines) => {
+  const nonEmptyLines = Array.isArray(lines)
+    ? lines.map((line) => String(line || '').trim()).filter(Boolean)
+    : [];
+  if (nonEmptyLines.length === 0) {
+    return '';
+  }
+
+  for (const line of [...nonEmptyLines].reverse()) {
+    try {
+      const parsed = JSON.parse(line);
+      const level = typeof parsed?.lvl === 'string' ? parsed.lvl.toLowerCase() : '';
+      if (level !== 'eror' && level !== 'error' && level !== 'crit') {
+        continue;
+      }
+      const err = normalizeNgrokDiagnosticText(parsed?.err);
+      if (err && err !== '<nil>') {
+        return err;
+      }
+    } catch {
+      // Not a JSON ngrok log line.
+    }
+  }
+
+  for (const line of [...nonEmptyLines].reverse()) {
+    try {
+      const parsed = JSON.parse(line);
+      const err = normalizeNgrokDiagnosticText(parsed?.err);
+      if (err && err !== '<nil>' && !/context canceled/i.test(err)) {
+        return err;
+      }
+      const msg = normalizeNgrokDiagnosticText(parsed?.msg);
+      if (msg && /failed|error|invalid|auth/i.test(msg)) {
+        return msg;
+      }
+    } catch {
+      // Not a JSON ngrok log line.
+    }
+  }
+
+  const errorLines = nonEmptyLines
+    .filter((line) => /^ERROR:/i.test(line))
+    .map((line) => normalizeNgrokDiagnosticText(line.replace(/^ERROR:\s*/i, '')))
+    .filter(Boolean);
+  if (errorLines.length > 0) {
+    return errorLines.slice(0, 4).join(' ');
+  }
+
+  const lastLine = [...nonEmptyLines].reverse().find((line) => line.trim().length > 0);
+  if (!lastLine) {
+    return '';
+  }
+  try {
+    const parsed = JSON.parse(lastLine);
+    if (typeof parsed?.err === 'string' && parsed.err.trim().length > 0) {
+      return normalizeNgrokDiagnosticText(parsed.err);
+    }
+    if (typeof parsed?.msg === 'string' && parsed.msg.trim().length > 0) {
+      return normalizeNgrokDiagnosticText(parsed.msg);
+    }
+  } catch {
+    // Fall through to plain text output.
+  }
+  return normalizeNgrokDiagnosticText(lastLine);
+};
+
+const appendNgrokOutputSummary = (message, lines) => {
+  const summary = summarizeNgrokOutput(lines);
+  return summary ? `${message}: ${summary}` : message;
+};
+
 async function fetchNgrokPublicUrl(fetchImpl = globalThis.fetch) {
  if (typeof fetchImpl !== 'function') {
    return null;
@@ -133,9 +234,9 @@ async function fetchNgrokPublicUrl(fetchImpl = globalThis.fetch) {
    }
    const payload = await response.json();
    const tunnels = Array.isArray(payload?.tunnels) ? payload.tunnels : [];
-    const httpsTunnel = tunnels.find((entry) => entry?.proto === 'https' && typeof entry?.public_url === 'string');
-    const fallbackTunnel = tunnels.find((entry) => typeof entry?.public_url === 'string');
-    return httpsTunnel?.public_url || fallbackTunnel?.public_url || null;
+    const httpsTunnel = tunnels.find((entry) => entry?.proto === 'https' && normalizeNgrokPublicUrl(entry?.public_url));
+    const fallbackTunnel = tunnels.find((entry) => normalizeNgrokPublicUrl(entry?.public_url));
+    return normalizeNgrokPublicUrl(httpsTunnel?.public_url) || normalizeNgrokPublicUrl(fallbackTunnel?.public_url);
  } catch {
    return null;
  }
@@ -144,54 +245,87 @@ async function fetchNgrokPublicUrl(fetchImpl = globalThis.fetch) {
 export async function startNgrokQuickTunnel({ port }) {
  const ngrokCheck = await checkNgrokAvailable();
  if (!ngrokCheck.available) {
-    throw new Error(`ngrok is not installed. Install it with: ${NGROK_INSTALL_HELP}`);
+    throw new Error(getNgrokInstallInfo().message);
  }

  const authtokenCheck = await checkNgrokAuthtokenConfigured(ngrokCheck.path);
  if (!authtokenCheck.configured) {
-    throw new Error(`ngrok authtoken is not configured. ${NGROK_AUTHTOKEN_HELP}`);
+    throw new Error(`ngrok authtoken is not configured. ${authtokenCheck.detail || NGROK_AUTHTOKEN_HELP}`);
  }

  if (!Number.isFinite(port)) {
    throw new Error('A local port is required to start an ngrok tunnel');
  }

-  const child = spawnNgrok(['http', String(port)], ngrokCheck.path);
+  const child = spawnNgrok(['http', '--log=stdout', '--log-format=json', `127.0.0.1:${port}`], ngrokCheck.path);
  let publicUrl = null;
+  const recentOutput = [];

-  child.stdout.on('data', () => {
-    // Keep stream drained; ngrok exposes the URL via its local API.
+  const captureOutput = (chunk) => {
+    const text = chunk.toString('utf8');
+    const parsedUrl = extractNgrokPublicUrlFromText(text);
+    if (parsedUrl) {
+      publicUrl = parsedUrl;
+    }
+
+    for (const line of text.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      recentOutput.push(trimmed);
+      if (recentOutput.length > 200) {
+        recentOutput.shift();
+      }
+    }
+    return text;
+  };
+
+  child.stdout.on('data', (chunk) => {
+    captureOutput(chunk);
  });

  child.stderr.on('data', (chunk) => {
-    process.stderr.write(chunk.toString('utf8'));
-  });
-
-  child.on('error', (error) => {
-    console.error(`Ngrok error: ${error.message}`);
+    const text = captureOutput(chunk);
+    process.stderr.write(text);
  });

  await new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
+    let settled = false;
+    const finish = (handler, value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
      clearInterval(checkReady);
+      child.off('error', onError);
+      child.off('exit', onExit);
+      handler(value);
+    };
+
+    const timeout = setTimeout(() => {
      try { child.kill('SIGINT'); } catch { /* ignore */ }
-      reject(new Error('Ngrok tunnel URL not received within 30 seconds'));
+      finish(reject, new Error(appendNgrokOutputSummary('Ngrok tunnel URL not received within 30 seconds', recentOutput)));
    }, DEFAULT_STARTUP_TIMEOUT_MS);

    const checkReady = setInterval(async () => {
-      publicUrl = await fetchNgrokPublicUrl();
+      publicUrl = publicUrl || await fetchNgrokPublicUrl();
      if (publicUrl) {
-        clearTimeout(timeout);
-        clearInterval(checkReady);
-        resolve(null);
+        finish(resolve, null);
      }
    }, 250);

-    child.once('exit', (code) => {
-      clearTimeout(timeout);
-      clearInterval(checkReady);
-      reject(new Error(`Ngrok exited while starting (code ${code ?? 'unknown'})`));
-    });
+    const onError = (error) => {
+      finish(reject, new Error(`Ngrok failed to start: ${error.message}`));
+    };
+
+    const onExit = (code) => {
+      finish(reject, new Error(appendNgrokOutputSummary(`Ngrok exited while starting (code ${code ?? 'unknown'})`, recentOutput)));
+    };
+
+    child.once('error', onError);
+    child.once('exit', onExit);
  });

  return {
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  extractNgrokPublicUrlFromText,
+  summarizeNgrokOutput,
+} from './ngrok-tunnel.js';
+
+describe('extractNgrokPublicUrlFromText', () => {
+  it('extracts public URL from ngrok JSON logs', () => {
+    const url = extractNgrokPublicUrlFromText('{"lvl":"info","msg":"started tunnel","url":"https://demo.ngrok-free.app"}\n');
+
+    expect(url).toBe('https://demo.ngrok-free.app');
+  });
+
+  it('extracts public URL from ngrok text output', () => {
+    const url = extractNgrokPublicUrlFromText('Forwarding https://demo.ngrok-free.app -> http://127.0.0.1:3000');
+
+    expect(url).toBe('https://demo.ngrok-free.app');
+  });
+
+  it('ignores non-ngrok URLs', () => {
+    const url = extractNgrokPublicUrlFromText('{"url":"https://example.com"}\n');
+
+    expect(url).toBeNull();
+  });
+});
+
+describe('summarizeNgrokOutput', () => {
+  it('prefers actionable JSON error details over trailing help text', () => {
+    const summary = summarizeNgrokOutput([
+      '{"err":"authentication failed: Your ngrok-agent version \\"3.3.1\\" is too old. The minimum supported agent version for your account is \\"3.20.0\\".\\r\\n\\r\\nERR_NGROK_121\\r\\n","lvl":"crit","msg":"command failed"}',
+      'NAME:',
+      '  http - start an HTTP tunnel',
+    ]);
+
+    expect(summary).toContain('Your ngrok-agent version "3.3.1" is too old');
+    expect(summary).toContain('ERR_NGROK_121');
+  });
+
+  it('skips bare ERROR lines and keeps the useful error text', () => {
+    const summary = summarizeNgrokOutput([
+      'ERROR:',
+      'ERROR:  authentication failed',
+      'ERROR:',
+      'ERROR:  ERR_NGROK_121',
+    ]);
+
+    expect(summary).toBe('authentication failed ERR_NGROK_121');
+  });
+});
@@ -5,8 +5,10 @@ This module contains tunnel provider orchestration for OpenChamber, including pr

 ## Entrypoints and structure
 - `packages/web/server/lib/tunnels/index.js`: tunnel service orchestration.
+- `packages/web/server/lib/tunnels/executable-search.js`: cross-platform executable discovery, including Windows Store app aliases.
 - `packages/web/server/lib/tunnels/registry.js`: provider registry.
 - `packages/web/server/lib/tunnels/managed-config.js`: managed remote tunnel token/preset persistence runtime.
+- `packages/web/server/lib/tunnels/install-help.js`: provider/platform install command metadata for missing tunnel dependencies.
 - `packages/web/server/lib/tunnels/routes.js`: tunnel API route registration and request orchestration runtime.
 - `packages/web/server/lib/tunnels/types.js`: tunnel constants, normalization, and shared type helpers.
 - `packages/web/server/lib/tunnels/providers/cloudflare.js`: Cloudflare tunnel provider implementation.
@@ -0,0 +1,140 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const getEnvValue = (env, keys) => {
+  for (const key of keys) {
+    const value = env?.[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return '';
+};
+
+const normalizeSearchDirectoryKey = (directory, platform) => {
+  const trimmed = typeof directory === 'string' ? directory.trim() : '';
+  return platform === 'win32' ? trimmed.toLowerCase() : trimmed;
+};
+
+const getWindowsAppsDirectory = (env) => {
+  const localAppData = getEnvValue(env, ['LOCALAPPDATA', 'LocalAppData', 'localappdata']);
+  if (localAppData) {
+    return path.win32.join(localAppData, 'Microsoft', 'WindowsApps');
+  }
+
+  const userProfile = getEnvValue(env, ['USERPROFILE', 'UserProfile', 'userprofile']);
+  if (userProfile) {
+    return path.win32.join(userProfile, 'AppData', 'Local', 'Microsoft', 'WindowsApps');
+  }
+
+  return path.win32.join(os.homedir(), 'AppData', 'Local', 'Microsoft', 'WindowsApps');
+};
+
+export function getExecutableSearchDirectories({ env = process.env, platform = process.platform } = {}) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathValue = getEnvValue(env, ['PATH', 'Path', 'path']);
+  const directories = pathValue.split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+
+  if (platform === 'win32') {
+    directories.push(getWindowsAppsDirectory(env));
+  }
+
+  const seen = new Set();
+  const unique = [];
+  for (const directory of directories) {
+    const key = normalizeSearchDirectoryKey(directory, platform);
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push(directory);
+  }
+
+  return unique;
+}
+
+export function createExecutableSearchEnv({ env = process.env, platform = process.platform } = {}) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathValue = getExecutableSearchDirectories({ env, platform }).join(delimiter);
+  const nextEnv = { ...env };
+
+  if (platform === 'win32') {
+    nextEnv.PATH = pathValue;
+    nextEnv.Path = pathValue;
+    nextEnv.path = pathValue;
+  } else {
+    nextEnv.PATH = pathValue;
+  }
+
+  return nextEnv;
+}
+
+const getExecutableExtensions = ({ env = process.env, platform = process.platform } = {}) => {
+  if (platform !== 'win32') {
+    return [''];
+  }
+
+  return (env.PATHEXT || env.PathExt || env.pathext || '.EXE;.CMD;.BAT;.COM')
+    .split(';')
+    .map((ext) => ext.trim().toLowerCase())
+    .filter(Boolean)
+    .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`));
+};
+
+export function findExecutableOnPath(command, {
+  env = process.env,
+  platform = process.platform,
+  fsLike = fs,
+} = {}) {
+  if (typeof command !== 'string' || command.trim().length === 0) {
+    return null;
+  }
+
+  const pathApi = platform === 'win32' ? path.win32 : path;
+  const directories = getExecutableSearchDirectories({ env, platform });
+  const extensions = getExecutableExtensions({ env, platform });
+  const commandName = command.trim();
+
+  for (const directory of directories) {
+    for (const extension of extensions) {
+      const fileName = platform === 'win32' ? `${commandName}${extension}` : commandName;
+      const candidate = pathApi.join(directory, fileName);
+      try {
+        const stats = fsLike.statSync(candidate);
+        if (!stats.isFile()) {
+          continue;
+        }
+        if (platform !== 'win32') {
+          try {
+            fsLike.accessSync(candidate, fs.constants.X_OK);
+          } catch {
+            continue;
+          }
+        }
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function resolveExecutableLaunchTarget(command, options = {}) {
+  const platform = options.platform || process.platform;
+  const resolvedPath = findExecutableOnPath(command, { ...options, platform });
+  const env = createExecutableSearchEnv({ env: options.env || process.env, platform });
+  if (resolvedPath) {
+    return { command: resolvedPath, env };
+  }
+
+  // Windows Store app execution aliases are launchable through CreateProcess
+  // but can reject fs.stat/fs.access with EACCES. Let the version probe decide.
+  if (platform === 'win32' && typeof command === 'string' && command.trim().length > 0) {
+    return { command: command.trim(), env };
+  }
+
+  return null;
+}
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  createExecutableSearchEnv,
+  findExecutableOnPath,
+  getExecutableSearchDirectories,
+  resolveExecutableLaunchTarget,
+} from './executable-search.js';
+
+describe('getExecutableSearchDirectories', () => {
+  it('adds the WindowsApps app-alias directory on Windows', () => {
+    const directories = getExecutableSearchDirectories({
+      platform: 'win32',
+      env: {
+        PATH: 'C:\\Tools',
+        LOCALAPPDATA: 'C:\\Users\\Ada\\AppData\\Local',
+      },
+    });
+
+    expect(directories).toContain('C:\\Users\\Ada\\AppData\\Local\\Microsoft\\WindowsApps');
+  });
+
+  it('reads Windows Path casing when PATH is not present', () => {
+    const directories = getExecutableSearchDirectories({
+      platform: 'win32',
+      env: {
+        Path: 'C:\\Tools;C:\\MoreTools',
+        LOCALAPPDATA: 'C:\\Users\\Ada\\AppData\\Local',
+      },
+    });
+
+    expect(directories[0]).toBe('C:\\Tools');
+    expect(directories[1]).toBe('C:\\MoreTools');
+  });
+});
+
+describe('findExecutableOnPath', () => {
+  it('finds Windows Store app execution aliases even when PATH omits WindowsApps', () => {
+    const aliasPath = 'C:\\Users\\Ada\\AppData\\Local\\Microsoft\\WindowsApps\\ngrok.exe';
+    const fsLike = {
+      statSync: (candidate) => {
+        if (candidate === aliasPath) {
+          return { isFile: () => true };
+        }
+        throw new Error('not found');
+      },
+      accessSync: () => {},
+    };
+
+    const resolved = findExecutableOnPath('ngrok', {
+      platform: 'win32',
+      env: {
+        PATH: 'C:\\Tools',
+        LOCALAPPDATA: 'C:\\Users\\Ada\\AppData\\Local',
+        PATHEXT: '.EXE;.CMD',
+      },
+      fsLike,
+    });
+
+    expect(resolved).toBe(aliasPath);
+  });
+});
+
+describe('resolveExecutableLaunchTarget', () => {
+  it('returns a Windows launch target with WindowsApps on PATH when stat lookup fails', () => {
+    const target = resolveExecutableLaunchTarget('ngrok', {
+      platform: 'win32',
+      env: {
+        PATH: 'C:\\Windows\\System32',
+        LOCALAPPDATA: 'C:\\Users\\Ada\\AppData\\Local',
+      },
+      fsLike: {
+        statSync: () => { throw new Error('EACCES'); },
+        accessSync: () => {},
+      },
+    });
+
+    expect(target?.command).toBe('ngrok');
+    expect(target?.env.Path).toContain('C:\\Users\\Ada\\AppData\\Local\\Microsoft\\WindowsApps');
+  });
+});
+
+describe('createExecutableSearchEnv', () => {
+  it('keeps Windows PATH variants in sync', () => {
+    const env = createExecutableSearchEnv({
+      platform: 'win32',
+      env: {
+        PATH: 'C:\\Windows\\System32',
+        LOCALAPPDATA: 'C:\\Users\\Ada\\AppData\\Local',
+      },
+    });
+
+    expect(env.PATH).toBe(env.Path);
+    expect(env.path).toBe(env.Path);
+  });
+});
@@ -5,6 +5,7 @@ import {
  normalizeTunnelStartRequest,
  validateTunnelStartRequest,
 } from './types.js';
+import { getTunnelDependencyInstallInfo } from './install-help.js';

 export function createTunnelService({
  registry,
@@ -82,8 +83,9 @@ export function createTunnelService({

      let publicUrl = provider.resolvePublicUrl(getController());
      const activeMode = resolveActiveMode();
+      const activeProvider = resolveActiveProvider();

-      if (publicUrl && activeMode !== request.mode) {
+      if (publicUrl && (activeMode !== request.mode || activeProvider !== request.provider)) {
        stop();
        publicUrl = null;
      }
@@ -94,7 +96,7 @@ export function createTunnelService({
          const missingDependencyMessage = typeof availability?.message === 'string' && availability.message.trim().length > 0
            ? availability.message
            : (request.provider === TUNNEL_PROVIDER_CLOUDFLARE
-              ? 'cloudflared is not installed. Install it with: brew install cloudflared'
+              ? getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE).message
              : `Required dependency for provider '${request.provider}' is missing`);
          throw new TunnelServiceError('missing_dependency', missingDependencyMessage);
        }
@@ -102,11 +104,22 @@ export function createTunnelService({
        const activePort = Number.isFinite(getActivePort?.()) ? getActivePort() : null;
        const originUrl = activePort !== null ? `http://127.0.0.1:${activePort}` : undefined;

-        const controller = await provider.start(request, {
-          activePort,
-          originUrl,
-          ...options,
-        });
+        let controller;
+        try {
+          controller = await provider.start(request, {
+            activePort,
+            originUrl,
+            ...options,
+          });
+        } catch (error) {
+          if (error instanceof TunnelServiceError) {
+            throw error;
+          }
+          const message = error instanceof Error && error.message.trim().length > 0
+            ? error.message
+            : 'Failed to start tunnel';
+          throw new TunnelServiceError('startup_failed', message);
+        }
        controller.provider = request.provider;
        setController(controller);

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTunnelService } from './index.js';
+import {
+  TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+  TUNNEL_MODE_QUICK,
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TUNNEL_PROVIDER_NGROK,
+} from './types.js';
+
+const createProvider = ({ provider, start, stop, resolvePublicUrl }) => ({
+  id: provider,
+  capabilities: {
+    provider,
+    modes: [{ key: TUNNEL_MODE_QUICK, intent: TUNNEL_INTENT_EPHEMERAL_PUBLIC }],
+  },
+  checkAvailability: async () => ({ available: true }),
+  start,
+  stop,
+  resolvePublicUrl: resolvePublicUrl || ((controller) => controller?.getPublicUrl?.() ?? null),
+});
+
+const createRegistry = (providers) => ({
+  get: (providerId) => providers[providerId] ?? null,
+});
+
+describe('createTunnelService', () => {
+  it('returns provider startup errors to route callers', async () => {
+    let controller = null;
+    const provider = createProvider({
+      provider: TUNNEL_PROVIDER_NGROK,
+      start: async () => {
+        throw new Error('ngrok authtoken is not configured');
+      },
+    });
+    const service = createTunnelService({
+      registry: createRegistry({ [TUNNEL_PROVIDER_NGROK]: provider }),
+      getController: () => controller,
+      setController: (next) => { controller = next; },
+      getActivePort: () => 3000,
+    });
+
+    try {
+      await service.start({ provider: TUNNEL_PROVIDER_NGROK, mode: TUNNEL_MODE_QUICK });
+      throw new Error('Expected service.start to fail');
+    } catch (error) {
+      expect(error.name).toBe('TunnelServiceError');
+      expect(error.code).toBe('startup_failed');
+      expect(error.message).toBe('ngrok authtoken is not configured');
+    }
+  });
+
+  it('replaces an active quick tunnel when the provider changes', async () => {
+    let stopped = false;
+    let ngrokStarted = false;
+    let controller = {
+      provider: TUNNEL_PROVIDER_CLOUDFLARE,
+      mode: TUNNEL_MODE_QUICK,
+      stop: () => { stopped = true; },
+      getPublicUrl: () => 'https://cloudflare.example',
+    };
+    const cloudflareProvider = createProvider({
+      provider: TUNNEL_PROVIDER_CLOUDFLARE,
+      start: async () => controller,
+    });
+    const ngrokProvider = createProvider({
+      provider: TUNNEL_PROVIDER_NGROK,
+      start: async () => {
+        ngrokStarted = true;
+        return {
+          mode: TUNNEL_MODE_QUICK,
+          getPublicUrl: () => 'https://demo.ngrok-free.app',
+        };
+      },
+    });
+    const service = createTunnelService({
+      registry: createRegistry({
+        [TUNNEL_PROVIDER_CLOUDFLARE]: cloudflareProvider,
+        [TUNNEL_PROVIDER_NGROK]: ngrokProvider,
+      }),
+      getController: () => controller,
+      setController: (next) => { controller = next; },
+      getActivePort: () => 3000,
+    });
+
+    const result = await service.start({ provider: TUNNEL_PROVIDER_NGROK, mode: TUNNEL_MODE_QUICK });
+
+    expect(stopped).toBe(true);
+    expect(ngrokStarted).toBe(true);
+    expect(result.provider).toBe(TUNNEL_PROVIDER_NGROK);
+    expect(result.publicUrl).toBe('https://demo.ngrok-free.app');
+  });
+});
@@ -0,0 +1,56 @@
+import {
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TUNNEL_PROVIDER_NGROK,
+} from './types.js';
+
+const PROVIDER_INSTALL_INFO = {
+  [TUNNEL_PROVIDER_CLOUDFLARE]: {
+    dependency: 'cloudflared',
+    installUrl: 'https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflared/downloads/',
+    commands: {
+      darwin: 'brew install cloudflared',
+      win32: 'winget install --id Cloudflare.cloudflared',
+      linux: 'Download cloudflared from https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflared/downloads/',
+    },
+  },
+  [TUNNEL_PROVIDER_NGROK]: {
+    dependency: 'ngrok',
+    installUrl: 'https://ngrok.com/download',
+    commands: {
+      darwin: 'brew install ngrok',
+      win32: 'winget install ngrok -s msstore',
+      linux: 'Download ngrok from https://ngrok.com/download',
+    },
+  },
+};
+
+const normalizeInstallPlatform = (platform) => {
+  if (platform === 'darwin' || platform === 'win32' || platform === 'linux') {
+    return platform;
+  }
+  return 'linux';
+};
+
+const createMissingDependencyMessage = ({ dependency, installCommand }) => {
+  if (installCommand.startsWith('Download ')) {
+    return `${dependency} is not installed. ${installCommand}`;
+  }
+  return `${dependency} is not installed. Install it with: ${installCommand}`;
+};
+
+export function getTunnelDependencyInstallInfo(provider, platform = process.platform) {
+  const providerInfo = PROVIDER_INSTALL_INFO[provider] || PROVIDER_INSTALL_INFO[TUNNEL_PROVIDER_CLOUDFLARE];
+  const normalizedPlatform = normalizeInstallPlatform(platform);
+  const installCommand = providerInfo.commands[normalizedPlatform] || providerInfo.commands.linux;
+
+  return {
+    dependency: providerInfo.dependency,
+    installCommand,
+    installUrl: providerInfo.installUrl,
+    platform: normalizedPlatform,
+    message: createMissingDependencyMessage({
+      dependency: providerInfo.dependency,
+      installCommand,
+    }),
+  };
+}
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+
+import { getTunnelDependencyInstallInfo } from './install-help.js';
+import {
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TUNNEL_PROVIDER_NGROK,
+} from './types.js';
+
+describe('getTunnelDependencyInstallInfo', () => {
+  it('returns Windows cloudflared winget guidance', () => {
+    const info = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE, 'win32');
+
+    expect(info.dependency).toBe('cloudflared');
+    expect(info.installCommand).toBe('winget install --id Cloudflare.cloudflared');
+    expect(info.message).toContain('Cloudflare.cloudflared');
+  });
+
+  it('returns Windows ngrok winget guidance', () => {
+    const info = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_NGROK, 'win32');
+
+    expect(info.dependency).toBe('ngrok');
+    expect(info.installCommand).toBe('winget install ngrok -s msstore');
+    expect(info.message).toContain('ngrok -s msstore');
+  });
+
+  it('keeps macOS Homebrew guidance', () => {
+    const info = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE, 'darwin');
+
+    expect(info.installCommand).toBe('brew install cloudflared');
+  });
+});
@@ -17,6 +17,7 @@ import {
  TUNNEL_PROVIDER_CLOUDFLARE,
  TunnelServiceError,
 } from '../types.js';
+import { getTunnelDependencyInstallInfo } from '../install-help.js';

 export const cloudflareTunnelProviderCapabilities = {
  provider: TUNNEL_PROVIDER_CLOUDFLARE,
@@ -97,16 +98,21 @@ export function createCloudflareTunnelProvider() {
    checkAvailability: async () => {
      const result = await checkCloudflaredAvailable();
      if (result.available) {
-        return result;
+        return {
+          ...result,
+          ...getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE),
+        };
      }
+      const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE);
      return {
        ...result,
-        message: 'cloudflared is not installed. Install it with: brew install cloudflared',
+        ...installInfo,
      };
    },
    diagnose: async (request = {}) => {
      const dependency = await checkCloudflaredAvailable();
      const network = await checkCloudflareApiReachability();
+      const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE);

      const providerChecks = [
        {
@@ -115,7 +121,7 @@ export function createCloudflareTunnelProvider() {
          status: dependency.available ? 'pass' : 'fail',
          detail: dependency.available
            ? (dependency.version || dependency.path || 'cloudflared available')
-            : 'cloudflared is not installed. Install it with: brew install cloudflared',
+            : installInfo.message,
        },
        {
          id: 'network',
@@ -11,6 +11,7 @@ import {
  TUNNEL_PROVIDER_NGROK,
  TunnelServiceError,
 } from '../types.js';
+import { getTunnelDependencyInstallInfo } from '../install-help.js';

 export const ngrokTunnelProviderCapabilities = {
  provider: TUNNEL_PROVIDER_NGROK,
@@ -37,17 +38,22 @@ export function createNgrokTunnelProvider() {
    checkAvailability: async () => {
      const result = await checkNgrokAvailable();
      if (result.available) {
-        return result;
+        return {
+          ...result,
+          ...getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_NGROK),
+        };
      }
+      const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_NGROK);
      return {
        ...result,
-        message: 'ngrok is not installed. Install it with: brew install ngrok',
+        ...installInfo,
      };
    },
    diagnose: async () => {
      const dependency = await checkNgrokAvailable();
      const authtoken = await checkNgrokAuthtokenConfigured(dependency.path);
      const network = await checkNgrokApiReachability();
+      const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_NGROK);
      const startupReady = dependency.available && authtoken.configured && network.reachable;
      const providerChecks = [
        {
@@ -56,7 +62,7 @@ export function createNgrokTunnelProvider() {
          status: dependency.available ? 'pass' : 'fail',
          detail: dependency.available
            ? (dependency.version || dependency.path || 'ngrok available')
-            : 'ngrok is not installed. Install it with: brew install ngrok',
+            : installInfo.message,
        },
        {
          id: 'authtoken',
@@ -220,10 +220,15 @@ export const createTunnelRoutesRuntime = (dependencies) => {
          available: result.available,
          provider: requestedProvider,
          version: result.version || null,
+          dependency: result.dependency || null,
+          installCommand: result.installCommand || null,
+          installUrl: result.installUrl || null,
+          platform: result.platform || process.platform,
+          message: result.message || null,
        });
      } catch (error) {
        console.warn('Tunnel dependency check failed:', error);
-        res.json({ available: false, provider: null, version: null });
+        res.json({ available: false, provider: null, version: null, dependency: null, installCommand: null, installUrl: null, platform: process.platform, message: null });
      }
    });

@@ -38,6 +38,45 @@ const SUPPORTED_TUNNEL_PROVIDERS = new Set([
  TUNNEL_PROVIDER_NGROK,
 ]);

+const getPathApiForPlatform = (platform) => (platform === 'win32' ? path.win32 : path);
+
+export function isPathWithinDirectory(candidatePath, directoryPath, platform = process.platform) {
+  if (typeof candidatePath !== 'string' || typeof directoryPath !== 'string') {
+    return false;
+  }
+
+  const pathApi = getPathApiForPlatform(platform);
+  const resolvedCandidate = pathApi.resolve(candidatePath);
+  const resolvedDirectory = pathApi.resolve(directoryPath);
+  const comparableCandidate = platform === 'win32' ? resolvedCandidate.toLowerCase() : resolvedCandidate;
+  const comparableDirectory = platform === 'win32' ? resolvedDirectory.toLowerCase() : resolvedDirectory;
+  const directoryPrefix = comparableDirectory.endsWith(pathApi.sep)
+    ? comparableDirectory
+    : `${comparableDirectory}${pathApi.sep}`;
+
+  return comparableCandidate === comparableDirectory || comparableCandidate.startsWith(directoryPrefix);
+}
+
+export function resolveTunnelConfigPath(value, home = os.homedir(), platform = process.platform) {
+  const pathApi = getPathApiForPlatform(platform);
+  let resolved;
+  if (value === '~') {
+    resolved = home;
+  } else if (value.startsWith('~/') || value.startsWith('~\\')) {
+    resolved = pathApi.join(home, value.slice(2));
+  } else {
+    resolved = pathApi.resolve(value);
+  }
+
+  if (!isPathWithinDirectory(resolved, home, platform)) {
+    throw new TunnelServiceError(
+      'validation_error',
+      `Config path must be within the home directory (${home}). Got: ${resolved}`
+    );
+  }
+  return resolved;
+}
+
 export function normalizeTunnelProvider(value) {
  if (typeof value !== 'string') {
    return TUNNEL_PROVIDER_CLOUDFLARE;
@@ -111,22 +150,7 @@ export function normalizeOptionalPath(value) {
  if (!trimmed) {
    return null;
  }
-  let resolved;
-  if (trimmed === '~') {
-    resolved = os.homedir();
-  } else if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
-    resolved = path.join(os.homedir(), trimmed.slice(2));
-  } else {
-    resolved = path.resolve(trimmed);
-  }
-  const home = os.homedir();
-  if (resolved !== home && !resolved.startsWith(home + path.sep)) {
-    throw new TunnelServiceError(
-      'validation_error',
-      `Config path must be within the home directory (${home}). Got: ${resolved}`
-    );
-  }
-  return resolved;
+  return resolveTunnelConfigPath(trimmed);
 }

 export function isSupportedTunnelMode(mode) {
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  isPathWithinDirectory,
+  resolveTunnelConfigPath,
+} from './types.js';
+
+describe('tunnel config path normalization', () => {
+  it('allows Windows home paths with different drive casing', () => {
+    expect(isPathWithinDirectory(
+      'c:\\Users\\Bohdan\\.cloudflared\\config.yml',
+      'C:\\Users\\Bohdan',
+      'win32'
+    )).toBe(true);
+  });
+
+  it('does not allow Windows sibling home directories', () => {
+    expect(isPathWithinDirectory(
+      'C:\\Users\\Bohdan2\\.cloudflared\\config.yml',
+      'C:\\Users\\Bohdan',
+      'win32'
+    )).toBe(false);
+  });
+
+  it('resolves Windows tilde paths inside the provided home directory', () => {
+    expect(resolveTunnelConfigPath('~\\.cloudflared\\config.yml', 'C:\\Users\\Bohdan', 'win32'))
+      .toBe('C:\\Users\\Bohdan\\.cloudflared\\config.yml');
+  });
+
+  it('rejects Windows paths outside the provided home directory', () => {
+    expect(() => resolveTunnelConfigPath('C:\\Temp\\config.yml', 'C:\\Users\\Bohdan', 'win32'))
+      .toThrow(/Config path must be within the home directory/);
+  });
+});