surf-cli 2.18.0 → 2.20.0

package/native/do-executor.cjs

@@ -35,6 +35,14 @@ function sendDoRequest(toolName, toolArgs, context = {}) {
   })();
 }
 
+function semanticRequestContext(context, timeoutMs, identity) {
+  return {
+    ...context,
+    timeoutMs,
+    ...(identity ? { tabId: identity.tabId, windowId: undefined, session: undefined } : {}),
+  };
+}
+
 function summarizeArgs(step) {
   return Object.entries(step.args || {})
     .map(([key, value]) => typeof value === "string" && value.length > 40 ? `${key}="${value.slice(0, 37)}..."` : `${key}=${JSON.stringify(value)}`)
@@ -63,14 +71,32 @@ function printProgress(event) {
 
 async function executeDoSteps(steps, options = {}) {
   const context = options.context || {};
-  return runtime.executeWorkflow(steps, {
-    ...options,
-    executeTool: options.executeTool || ((tool, args) => sendDoRequest(tool, args, context)),
-    onProgress: options.quiet ? options.onProgress : (event) => {
-      printProgress(event);
-      options.onProgress?.(event);
-    },
-  });
+  let semanticExecutor;
+  const executeSemanticStep = steps.some((step) => step.cmd === "semantic.step")
+    ? async (step, semanticContext, executionOptions) => {
+      if (!semanticExecutor) {
+        semanticExecutor = options.executeSemanticStep;
+        if (!semanticExecutor && typeof options.createSemanticExecutor === "function") {
+          semanticExecutor = await options.createSemanticExecutor({ context });
+        }
+        if (typeof semanticExecutor !== "function") throw new Error("semantic.step requires an injected semantic executor");
+      }
+      return semanticExecutor(step, semanticContext, executionOptions);
+    }
+    : undefined;
+  try {
+    return await runtime.executeWorkflow(steps, {
+      ...options,
+      executeTool: options.executeTool || ((tool, args) => sendDoRequest(tool, args, context)),
+      ...(executeSemanticStep ? { executeSemanticStep } : {}),
+      onProgress: options.quiet ? options.onProgress : (event) => {
+        printProgress(event);
+        options.onProgress?.(event);
+      },
+    });
+  } finally {
+    await semanticExecutor?.close?.();
+  }
 }
 
 module.exports = {
@@ -83,6 +109,7 @@ module.exports = {
   extractStepOutput: runtime.extractStepOutput,
   getAutoWaitCommand: runtime.getAutoWaitCommand,
   resolveVar: runtime.resolveVar,
+  semanticRequestContext,
   sendDoRequest,
   shouldAutoWait: runtime.shouldAutoWait,
   substituteVars: runtime.substituteVars,

package/native/doctor.cjs

@@ -4,6 +4,17 @@ const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const { connectEndpoint, selectEndpoint } = require("./endpoint.cjs");
+const {
+  convertWindowsPath,
+  getWindowsEnv,
+  nativeMessagingRegistryPath,
+  runWindowsExecutable,
+} = require("../scripts/windows-interop.cjs");
+const {
+  renderWslWrapper,
+  probeWindowsWrapper,
+} = require("./native-host-launch-probe.cjs");
+const { findNode, getHostPath } = require("../scripts/install-native-host.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -115,32 +126,12 @@ function resolveBrowsers(browserArg) {
   return browsers;
 }
 
-function getWindowsEnv(name, { env = process.env, execFileSync: execFile = execFileSync } = {}) {
-  if (env[name]) return env[name];
-  try {
-    return execFile("cmd.exe", ["/c", "echo", `%${name}%`], { encoding: "utf8" })
-      .trim()
-      .replace(/\r/g, "");
-  } catch {
-    return null;
-  }
-}
-
-function windowsPathToWslPath(winPath) {
-  const normalized = winPath.replace(/\\/g, "/");
-  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
-  if (!match) return normalized;
-  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
-}
-
 function manifestPathForBrowser(browserKey, context) {
   const browser = BROWSERS[browserKey];
   if (!browser) return null;
 
   if (context.effectiveTarget === "wsl-windows") {
-    const localAppData = getWindowsEnv("LOCALAPPDATA", context);
-    if (!localAppData || !browser.wsl) return null;
-    return path.join(windowsPathToWslPath(localAppData), browser.wsl, `${HOST_NAME}.json`);
+    return null;
   }
 
   if (context.platform === "win32") {
@@ -156,7 +147,7 @@ function manifestPathForBrowser(browserKey, context) {
 
 function fsPathFromManifestPath(manifestPath, context) {
   if (context.platform === "linux" && /^[A-Za-z]:[\\/]/.test(manifestPath)) {
-    return windowsPathToWslPath(manifestPath);
+    return convertWindowsPath(manifestPath, context);
   }
   return manifestPath;
 }
@@ -164,17 +155,21 @@ function fsPathFromManifestPath(manifestPath, context) {
 function windowsRegistryPathForBrowser(browserKey) {
   const browser = BROWSERS[browserKey];
   if (!browser?.win32) return null;
-  return `HKCU\\Software\\${browser.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
+  return nativeMessagingRegistryPath(browser.win32, HOST_NAME);
 }
 
 function readWindowsRegistryManifestPath(registryPath, context) {
   try {
-    const output = context.execFileSync("reg", ["query", registryPath, "/ve"], { encoding: "utf8" });
+    const output = runWindowsExecutable("reg.exe", ["query", registryPath, "/ve"], {
+      execFileSync: context.execFileSync,
+      allowWslFallback: context.effectiveTarget === "wsl-windows",
+      execOptions: { encoding: "utf8" },
+    });
     const line = output.split(/\r?\n/).find((item) => item.includes("REG_SZ"));
-    if (!line) return null;
-    return line.replace(/^.*REG_SZ\s+/, "").trim() || null;
-  } catch {
-    return null;
+    if (!line) return { manifestPath: null, error: "registry output contained no REG_SZ default value" };
+    return { manifestPath: line.replace(/^.*REG_SZ\s+/, "").trim() || null, error: null };
+  } catch (error) {
+    return { manifestPath: null, error: error.message };
   }
 }
 
@@ -192,15 +187,16 @@ function checkWindowsRegistry(browserKey, context) {
     };
   }
 
-  const manifestPath = readWindowsRegistryManifestPath(registryPath, context);
+  const registry = readWindowsRegistryManifestPath(registryPath, context);
+  const manifestPath = registry.manifestPath;
   return {
     check: {
       id: "windows-registry",
       status: manifestPath ? "pass" : "fail",
       browser: browserKey,
-      message: manifestPath
-        ? `Windows native messaging registry points to ${manifestPath}`
-        : `Windows native messaging registry entry not found: ${registryPath}`,
+      message: !manifestPath
+        ? `Windows native messaging registry entry not found: ${registryPath}${registry.error ? ` (${registry.error})` : ""}`
+        : `Windows native messaging registry points to ${manifestPath}`,
       registryPath,
       path: manifestPath,
     },
@@ -210,19 +206,32 @@ function checkWindowsRegistry(browserKey, context) {
 
 function checkManifest(manifestPath, context) {
   const checks = [];
-  const exists = manifestPath ? context.fs.existsSync(manifestPath) : false;
+  let manifestFsPath = manifestPath;
+  try {
+    manifestFsPath = manifestPath ? fsPathFromManifestPath(manifestPath, context) : manifestPath;
+  } catch (error) {
+    checks.push({
+      id: "manifest-file",
+      status: "fail",
+      message: `Could not resolve manifest path ${manifestPath}: ${error.message}`,
+      path: manifestPath,
+    });
+    return { checks, manifest: null };
+  }
+  const exists = manifestFsPath ? context.fs.existsSync(manifestFsPath) : false;
   checks.push({
     id: "manifest-file",
     status: exists ? "pass" : "fail",
-    message: exists ? `Manifest found: ${manifestPath}` : "Native messaging manifest not found",
+    message: exists ? `Manifest found: ${manifestPath}` : `Native messaging manifest not found: ${manifestPath}`,
     path: manifestPath,
+    fsPath: manifestFsPath,
   });
 
   if (!exists) return { checks, manifest: null };
 
   let manifest;
   try {
-    manifest = JSON.parse(context.fs.readFileSync(manifestPath, "utf8"));
+    manifest = JSON.parse(context.fs.readFileSync(manifestFsPath, "utf8"));
     checks.push({ id: "manifest-json", status: "pass", message: "Manifest JSON is valid" });
   } catch (error) {
     checks.push({ id: "manifest-json", status: "fail", message: `Manifest JSON is invalid: ${error.message}` });
@@ -288,6 +297,126 @@ function checkManifest(manifestPath, context) {
   return { checks, manifest };
 }
 
+function normalizeWindowsPath(filePath) {
+  return path.win32.normalize(filePath).replace(/[\\/]+$/, "").toLowerCase();
+}
+
+function checkWslWrapperLaunch(manifest, context) {
+  if (!manifest || typeof manifest.path !== "string" || manifest.path.length === 0) {
+    return null;
+  }
+
+  let canonicalWindowsPath;
+  try {
+    const localAppData = getWindowsEnv("LOCALAPPDATA", { execFileSync: context.execFileSync });
+    canonicalWindowsPath = path.win32.join(
+      localAppData,
+      "surf-cli",
+      "host-wrapper-wsl.cmd",
+    );
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not resolve Surf's managed Windows wrapper path: ${error.message}`,
+    };
+  }
+
+  if (normalizeWindowsPath(manifest.path) !== normalizeWindowsPath(canonicalWindowsPath)) {
+    return {
+      id: "wrapper-launch",
+      status: "warn",
+      message:
+        "Skipped launch probe because the manifest does not point to Surf's managed WSL wrapper. Run `surf install <extension-id>` to restore the managed wrapper.",
+      path: manifest.path,
+    };
+  }
+
+  let wrapperFsPath;
+  try {
+    wrapperFsPath = fsPathFromManifestPath(canonicalWindowsPath, context);
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not resolve Surf's managed WSL wrapper: ${error.message}`,
+      path: canonicalWindowsPath,
+    };
+  }
+
+  if (!context.fs.existsSync(wrapperFsPath)) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Surf's managed WSL wrapper does not exist: ${canonicalWindowsPath}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  let wrapperContent;
+  try {
+    wrapperContent = context.fs.readFileSync(wrapperFsPath, "utf8");
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not read Surf's managed WSL wrapper: ${error.message}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  const nodePath = context.nodePath || findNode();
+  const hostPath = context.hostPath || getHostPath();
+  const distro = context.env.WSL_DISTRO_NAME;
+  let explicitWrapper = null;
+  let defaultWrapper = null;
+  if (nodePath && hostPath && distro) {
+    try {
+      explicitWrapper = renderWslWrapper(nodePath, hostPath, distro);
+      defaultWrapper = renderWslWrapper(nodePath, hostPath, null);
+    } catch {
+      // Do not execute a wrapper whose installed paths cannot be rendered safely.
+    }
+  }
+  if (wrapperContent !== explicitWrapper && wrapperContent !== defaultWrapper) {
+    return {
+      id: "wrapper-launch",
+      status: "warn",
+      message:
+        "Surf's managed WSL wrapper does not match this installation, so it was not executed. Run `surf install <extension-id>` to replace it.",
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  try {
+    const observedDistro = context.probeWindowsWrapper(canonicalWindowsPath, {
+      execFileSync: context.execFileSync,
+      verifyDistro: wrapperContent === defaultWrapper,
+    });
+    if (wrapperContent === defaultWrapper && observedDistro !== distro) {
+      throw new Error("Windows default WSL distro does not match this installation");
+    }
+    return {
+      id: "wrapper-launch",
+      status: "pass",
+      message: "Surf's managed WSL wrapper completed its launch probe",
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Surf's managed WSL wrapper failed validation: ${error.message}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+}
+
 async function checkSocket(socketPath, context) {
   const checks = [];
   if (context.platform !== "win32") {
@@ -371,6 +500,20 @@ function summarize(checks) {
 function buildRecommendations(report) {
   const recommendations = [];
   const failedIds = new Set(report.checks.filter((check) => check.status === "fail").map((check) => check.id));
+  const debugRelevantIds = new Set([
+    "windows-registry",
+    "manifest-file",
+    "manifest-json",
+    "manifest-shape",
+    "manifest-name",
+    "manifest-type",
+    "manifest-origins",
+    "manifest-path",
+    "manifest-path-executable",
+    "wrapper-launch",
+    "socket-file",
+    "socket-connect",
+  ]);
 
   if (failedIds.has("windows-registry")) {
     recommendations.push("Run `surf install <extension-id> --browser <browser>` so Windows registers the native messaging host, then restart the browser.");
@@ -384,12 +527,18 @@ function buildRecommendations(report) {
   if (failedIds.has("manifest-path") || failedIds.has("manifest-path-executable")) {
     recommendations.push("Reinstall the native host so the manifest path points at the current Surf wrapper.");
   }
+  if (failedIds.has("wrapper-launch")) {
+    recommendations.push("Rerun `surf install <extension-id>` from the same WSL distro so Surf can replace and validate the Windows wrapper.");
+  }
   if (failedIds.has("manifest-supported")) {
     recommendations.push("Choose a browser supported for this target, or rerun with `--browser all` to inspect every supported setup.");
   }
   if (failedIds.has("socket-file") || failedIds.has("socket-connect")) {
     recommendations.push("Make sure the browser is running with the Surf extension enabled, then restart the browser after install changes.");
   }
+  if ([...failedIds].some((id) => debugRelevantIds.has(id))) {
+    recommendations.push("Open chrome://extensions and inspect Surf's service worker console. In Surf's Details > Extension options, enable Debug Mode, reproduce the failure, then disable Debug Mode when finished.");
+  }
   if (report.environment.surfSocketSet) {
     recommendations.push("SURF_SOCKET is set; make sure Chrome launches the native host with the same socket value.");
   }
@@ -405,6 +554,14 @@ function buildRecommendations(report) {
 
 function remoteRecommendations(endpoint, code) {
   const base = [`Confirm Surf is listening on ${endpoint.display}; the remote host listener must allow this Tailnet connection.`];
+  const tlsCodes = new Set([
+    "ERR_TLS_CERT_ALTNAME_INVALID", "UNABLE_TO_VERIFY_LEAF_SIGNATURE", "SELF_SIGNED_CERT_IN_CHAIN",
+    "DEPTH_ZERO_SELF_SIGNED_CERT", "UNABLE_TO_GET_ISSUER_CERT", "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "CERT_HAS_EXPIRED",
+  ]);
+  if (endpoint.tls?.enabled && (code === "ETIMEDOUT" || tlsCodes.has(code))) {
+    return [...base, "Check the reverse-proxy certificate chain and expected server name (or --remote-tls-server-name); a custom CA replaces system roots."];
+  }
   if (code === "ENOTFOUND") return [...base, "Check the Tailnet DNS name, then run `tailscale status` and `tailscale ping <host>`."].map((item) => item.replace("<host>", endpoint.host));
   if (code === "ETIMEDOUT") return [...base, `Run \`tailscale ping ${endpoint.host}\`; check restrictive Tailnet ACLs/grants and host firewall rules.`];
   if (code === "ECONNREFUSED") return [...base, "Verify the host process is running and bound to the requested TCP port; check restrictive Tailnet ACLs/grants."];
@@ -445,9 +602,10 @@ async function runDoctor(rawOptions = {}, deps = {}) {
       socket = connectEndpoint(target, () => finish({ ok: true, message: "authenticated" }));
       socket.once("error", (error) => finish({ ok: false, code: error.code, message: error.message || String(error) }));
     })))(endpoint, options.connectTimeoutMs);
-    const checks = [{ id: "remote-endpoint", status: "info", message: `Remote endpoint: ${endpoint.display}`, endpoint: endpoint.display }, {
+    const tlsMarker = endpoint.tls?.enabled ? " (TLS)" : "";
+    const checks = [{ id: "remote-endpoint", status: "info", message: `Remote endpoint: ${endpoint.display}${tlsMarker}`, endpoint: endpoint.display }, {
       id: "remote-connect", status: connection.ok ? "pass" : "fail",
-      message: connection.ok ? `Connected to remote endpoint ${endpoint.display}` : `Could not connect to remote endpoint ${endpoint.display}: ${connection.message}`,
+      message: connection.ok ? `Connected to remote endpoint ${endpoint.display}${tlsMarker}` : `Could not connect to remote endpoint ${endpoint.display}${tlsMarker}: ${connection.message}`,
       code: connection.code,
     }, {
       id: "remote-auth", status: connection.ok ? "pass" : connection.code === "EAUTH" ? "fail" : "info",
@@ -469,6 +627,9 @@ async function runDoctor(rawOptions = {}, deps = {}) {
     effectiveTarget,
     fs: deps.fs || fs,
     execFileSync: deps.execFileSync || execFileSync,
+    probeWindowsWrapper: deps.probeWindowsWrapper || probeWindowsWrapper,
+    nodePath: deps.nodePath,
+    hostPath: deps.hostPath,
     connectSocket: deps.connectSocket || connectSocket,
     connectTimeoutMs: options.connectTimeoutMs,
   };
@@ -484,15 +645,20 @@ async function runDoctor(rawOptions = {}, deps = {}) {
   for (const browserKey of browsers) {
     const browser = BROWSERS[browserKey];
     const browserChecks = [];
-    let manifestPath = manifestPathForBrowser(browserKey, context);
+    const usesWindowsRegistry =
+      (context.platform === "win32" || context.effectiveTarget === "wsl-windows") &&
+      Boolean(browser.win32);
+    let manifestPath = null;
 
-    if (context.platform === "win32" && browser.win32) {
+    if (usesWindowsRegistry) {
       const registry = checkWindowsRegistry(browserKey, context);
       browserChecks.push(registry.check);
-      if (registry.manifestPath) manifestPath = registry.manifestPath;
+      manifestPath = registry.manifestPath;
+    } else {
+      manifestPath = manifestPathForBrowser(browserKey, context);
     }
 
-    if (!manifestPath) {
+    if (!manifestPath && !usesWindowsRegistry) {
       const check = {
         id: "manifest-supported",
         status: options.browser === "all" ? "warn" : "fail",
@@ -507,6 +673,10 @@ async function runDoctor(rawOptions = {}, deps = {}) {
 
     const result = checkManifest(manifestPath, context);
     browserChecks.push(...result.checks.map((check) => ({ ...check, browser: browserKey })));
+    if (context.effectiveTarget === "wsl-windows" && result.manifest) {
+      const wrapperLaunch = checkWslWrapperLaunch(result.manifest, context);
+      if (wrapperLaunch) browserChecks.push({ ...wrapperLaunch, browser: browserKey });
+    }
     checks.push(...browserChecks);
     manifests.push({
       browser: browserKey,
@@ -629,5 +799,4 @@ module.exports = {
   parseDoctorArgs,
   runDoctor,
   runDoctorCli,
-  windowsPathToWslPath,
 };

package/native/endpoint.cjs

@@ -1,7 +1,12 @@
 const net = require("net");
+const fs = require("fs");
+const tls = require("tls");
 const { DEFAULT_SOCKET_PATH } = require("./socket-path.cjs");
 const { authenticateClient } = require("./remote-transport.cjs");
 
+const TLS_HANDSHAKE_TIMEOUT_MS = 5000;
+const HOSTNAME_PATTERN = /^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+
 function parseRemoteEndpoint(value) {
   if (typeof value !== "string" || !value) throw new Error("--remote requires host:port");
   let host;
@@ -16,7 +21,7 @@ function parseRemoteEndpoint(value) {
     if (!match) throw new Error("remote endpoint must be host:port (IPv6 must be bracketed)");
     [, host, portText] = match;
     if (host.includes("/") || host.includes("@") || host.includes(":") || host === "*" || host.includes("*")) throw new Error("remote endpoint host is invalid");
-    if ((/^\d+(?:\.\d+){3}$/.test(host) && net.isIP(host) !== 4) || (net.isIP(host) !== 4 && !/^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/.test(host))) {
+    if ((/^\d+(?:\.\d+){3}$/.test(host) && net.isIP(host) !== 4) || (net.isIP(host) !== 4 && !HOSTNAME_PATTERN.test(host))) {
       throw new Error("remote endpoint host is invalid");
     }
     host = host.toLowerCase();
@@ -30,45 +35,107 @@ function parseRemoteEndpoint(value) {
   return { kind: "remote", host, port, display, key: `tcp:${display}`, connectionOptions: { host, port } };
 }
 
+function extractRemoteOptions(args) {
+  const definitions = {
+    "--remote": { name: "remote", missing: "--remote requires host:port" },
+    "--remote-credential": { name: "credential", missing: "--remote-credential requires a file path" },
+    "--remote-tls": { name: "tls", boolean: true },
+    "--remote-tls-ca": { name: "tlsCa", missing: "--remote-tls-ca requires a file path" },
+    "--remote-tls-server-name": { name: "tlsServerName", missing: "--remote-tls-server-name requires a DNS hostname" },
+  };
+  const values = {};
+  const strippedArgs = [];
+  for (let index = 0; index < args.length; index++) {
+    const option = definitions[args[index]];
+    if (!option) {
+      strippedArgs.push(args[index]);
+      continue;
+    }
+    if (Object.hasOwn(values, option.name)) throw new Error(`${args[index]} may only be specified once`);
+    if (option.boolean) {
+      values[option.name] = true;
+      continue;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(option.missing);
+    values[option.name] = value;
+    index++;
+  }
+  return { values, strippedArgs };
+}
+
+function validateServerName(value, source) {
+  if (!value || net.isIP(value) !== 0 || !HOSTNAME_PATTERN.test(value)) {
+    throw new Error(`${source} must be a valid DNS hostname`);
+  }
+  return value.toLowerCase();
+}
+
+function loadTlsCa(caPath, source) {
+  let ca;
+  try {
+    ca = fs.readFileSync(caPath);
+  } catch (error) {
+    throw new Error(`${source} could not read CA file ${caPath}: ${error.message}`);
+  }
+  if (ca.length === 0 || !ca.includes(Buffer.from("-----BEGIN CERTIFICATE-----"))) {
+    throw new Error(`${source} CA file ${caPath} must contain a PEM certificate`);
+  }
+  return ca;
+}
+
 function selectEndpoint(args, env) {
   const selectedEnv = env === undefined ? process.env : env;
-  const remoteIndexes = [];
-  const credentialIndexes = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--remote") remoteIndexes.push(i);
-    if (args[i] === "--remote-credential") credentialIndexes.push(i);
-  }
-  if (remoteIndexes.length > 1) throw new Error("--remote may only be specified once");
-  if (credentialIndexes.length > 1) throw new Error("--remote-credential may only be specified once");
-  let cliRemote;
-  let cliCredential;
-  const strippedArgs = [...args];
-  if (remoteIndexes.length) {
-    const index = remoteIndexes[0];
-    cliRemote = args[index + 1];
-    if (!cliRemote || cliRemote.startsWith("--")) throw new Error("--remote requires host:port");
-    strippedArgs.splice(index, 2);
+  const { values, strippedArgs } = extractRemoteOptions(args);
+  const envTls = selectedEnv.SURF_REMOTE_TLS;
+  if (envTls && envTls !== "1") {
+    throw new Error('SURF_REMOTE_TLS must be "1" to enable TLS; unset it to disable');
   }
-  if (credentialIndexes.length) {
-    const index = credentialIndexes[0];
-    cliCredential = args[index + 1];
-    if (!cliCredential || cliCredential.startsWith("--")) throw new Error("--remote-credential requires a file path");
-    const adjustedIndex = index - (remoteIndexes.length && index > remoteIndexes[0] ? 2 : 0);
-    strippedArgs.splice(adjustedIndex, 2);
+  const remoteValue = values.remote || selectedEnv.SURF_REMOTE;
+  const credentialPath = values.credential || selectedEnv.SURF_REMOTE_CREDENTIAL;
+  const tlsEnabled = values.tls === true || envTls === "1";
+  const caPath = values.tlsCa || selectedEnv.SURF_REMOTE_TLS_CA;
+  const serverNameValue = values.tlsServerName || selectedEnv.SURF_REMOTE_TLS_SERVER_NAME;
+  if (!remoteValue) {
+    if (values.credential) throw new Error("--remote-credential requires a remote endpoint");
+    if (values.tls) throw new Error("--remote-tls requires a remote endpoint");
+    if (selectedEnv.SURF_REMOTE_TLS === "1") throw new Error("SURF_REMOTE_TLS requires a remote endpoint");
+    if (values.tlsCa) throw new Error("--remote-tls-ca requires a remote endpoint");
+    if (selectedEnv.SURF_REMOTE_TLS_CA) throw new Error("SURF_REMOTE_TLS_CA requires a remote endpoint");
+    if (values.tlsServerName) throw new Error("--remote-tls-server-name requires a remote endpoint");
+    if (selectedEnv.SURF_REMOTE_TLS_SERVER_NAME) throw new Error("SURF_REMOTE_TLS_SERVER_NAME requires a remote endpoint");
+    const socketPath = selectedEnv.SURF_SOCKET || DEFAULT_SOCKET_PATH;
+    return { args: strippedArgs, endpoint: { kind: "local", path: socketPath, display: socketPath, key: `unix:${socketPath}`, connectionOptions: socketPath } };
   }
-  const remoteValue = cliRemote || selectedEnv.SURF_REMOTE;
-  if (remoteValue) {
-    const credentialPath = cliCredential || selectedEnv.SURF_REMOTE_CREDENTIAL;
-    if (!credentialPath) throw new Error("remote endpoint requires --remote-credential <path> or SURF_REMOTE_CREDENTIAL");
-    return { args: strippedArgs, endpoint: { ...parseRemoteEndpoint(remoteValue), credentialPath } };
+  if (!credentialPath) throw new Error("remote endpoint requires --remote-credential <path> or SURF_REMOTE_CREDENTIAL");
+  if (caPath && !tlsEnabled) throw new Error(`${values.tlsCa ? "--remote-tls-ca" : "SURF_REMOTE_TLS_CA"} requires TLS to be enabled`);
+  if (serverNameValue && !tlsEnabled) throw new Error(`${values.tlsServerName ? "--remote-tls-server-name" : "SURF_REMOTE_TLS_SERVER_NAME"} requires TLS to be enabled`);
+  const endpoint = { ...parseRemoteEndpoint(remoteValue), credentialPath };
+  if (tlsEnabled) {
+    const tlsOptions = { enabled: true };
+    if (caPath) {
+      tlsOptions.ca = loadTlsCa(caPath, values.tlsCa ? "--remote-tls-ca" : "SURF_REMOTE_TLS_CA");
+      tlsOptions.caPath = caPath;
+    }
+    const serverName = serverNameValue
+      ? validateServerName(serverNameValue, values.tlsServerName ? "--remote-tls-server-name" : "SURF_REMOTE_TLS_SERVER_NAME")
+      : net.isIP(endpoint.host) === 0 ? endpoint.host : undefined;
+    if (serverName) tlsOptions.serverName = serverName;
+    endpoint.tls = tlsOptions;
   }
-  if (cliCredential) throw new Error("--remote-credential requires a remote endpoint");
-  const socketPath = selectedEnv.SURF_SOCKET || DEFAULT_SOCKET_PATH;
-  return { args: strippedArgs, endpoint: { kind: "local", path: socketPath, display: socketPath, key: `unix:${socketPath}`, connectionOptions: socketPath } };
+  return { args: strippedArgs, endpoint };
 }
 
 function createRemoteSocket(endpoint) {
-  const rawSocket = net.createConnection(endpoint.connectionOptions, () => {});
+  const usingTls = endpoint.tls?.enabled === true;
+  const rawSocket = usingTls
+    ? tls.connect({
+      ...endpoint.connectionOptions,
+      rejectUnauthorized: true,
+      ...(endpoint.tls.ca ? { ca: endpoint.tls.ca } : {}),
+      ...(endpoint.tls.serverName ? { servername: endpoint.tls.serverName } : {}),
+    })
+    : net.createConnection(endpoint.connectionOptions, () => {});
   let ready = false;
   let connected = false;
   let destroyed = false;
@@ -106,7 +173,25 @@ function createRemoteSocket(endpoint) {
     get authenticated() { return ready; },
     get connected() { return connected; },
   };
-  rawSocket.once("connect", () => { connected = true; });
+  const transportReadyEvent = usingTls ? "secureConnect" : "connect";
+  rawSocket.once(transportReadyEvent, () => { connected = true; });
+  let handshakeTimer;
+  if (usingTls) {
+    const timeoutMs = endpoint.tls.handshakeTimeoutMs ?? TLS_HANDSHAKE_TIMEOUT_MS;
+    const clearHandshakeTimer = () => {
+      if (handshakeTimer) clearTimeout(handshakeTimer);
+      handshakeTimer = undefined;
+    };
+    handshakeTimer = setTimeout(() => {
+      if (connected || rawSocket.destroyed) return;
+      const error = new Error(`TLS handshake timed out after ${timeoutMs}ms`);
+      error.code = "ETIMEDOUT";
+      rawSocket.destroy(error);
+    }, timeoutMs);
+    rawSocket.once("secureConnect", clearHandshakeTimer);
+    rawSocket.once("error", clearHandshakeTimer);
+    rawSocket.once("close", clearHandshakeTimer);
+  }
   rawSocket.on("error", (error) => {
     if (ready || destroyed) return;
     ready = true;
@@ -133,7 +218,7 @@ function connectEndpoint(endpoint, onConnect) {
     return net.createConnection(endpoint.connectionOptions, onConnect || (() => {}));
   }
   const { rawSocket, proxy, flush } = createRemoteSocket(endpoint);
-  rawSocket.once("connect", () => {
+  rawSocket.once(endpoint.tls?.enabled ? "secureConnect" : "connect", () => {
     authenticateClient(rawSocket, endpoint.credentialPath)
       .then(() => {
         flush();
@@ -168,7 +253,7 @@ function connectEndpoint(endpoint, onConnect) {
 function formatEndpointError(error, endpoint, formatSocketError) {
   if (endpoint.kind === "local") return formatSocketError(error);
   const message = error?.message || String(error);
-  return `Remote endpoint connection failed (${endpoint.display}): ${message}`;
+  return `Remote endpoint connection failed (${endpoint.display}${endpoint.tls?.enabled ? ", TLS" : ""}): ${message}`;
 }
 
-module.exports = { parseRemoteEndpoint, selectEndpoint, connectEndpoint, formatEndpointError };
+module.exports = { TLS_HANDSHAKE_TIMEOUT_MS, parseRemoteEndpoint, selectEndpoint, connectEndpoint, formatEndpointError };