surf-cli 2.8.0 → 2.9.0

package/native/client-transport.cjs

@@ -0,0 +1,168 @@
+const { connectEndpoint } = require("./endpoint.cjs");
+const { createFrameParser, createSocketWriter } = require("./remote-transport.cjs");
+const { createClientTransferController } = require("./file-transfer.cjs");
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
+async function openClientTransport(endpoint, { requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+  let socket;
+  let ready;
+  let readyReject;
+  let readyErrorListener;
+  ready = new Promise((resolve, reject) => {
+    readyReject = reject;
+    readyErrorListener = (error) => reject(error);
+    socket = connectEndpoint(endpoint, () => {
+      socket.removeListener("error", readyErrorListener);
+      resolve();
+    });
+    socket.once("error", readyErrorListener);
+  });
+  await ready;
+  const pending = new Map();
+  const writer = createSocketWriter(socket, { onOverflow: ({ error }) => socket.destroy(error) });
+  const transfers = endpoint.kind === "remote"
+    ? createClientTransferController({ writer, onActivity: () => {} })
+    : null;
+  let transferChain = Promise.resolve();
+  let transferCleanupPromise = null;
+  const cleanupTransfers = (error) => {
+    if (!transfers) return Promise.resolve();
+    transferCleanupPromise ||= transfers.cleanup(error);
+    return transferCleanupPromise;
+  };
+  const rejectPending = (error) => {
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  };
+  const parser = createFrameParser({
+    onFrame(message) {
+      if (transfers && message.type && message.type.startsWith("transfer_")) {
+        transferChain = transferChain.then(() => transfers.handle(message)).catch((error) => {
+          rejectPending(error);
+          return writer.send({ type: "transfer_error", version: 1, transferId: message.transferId, error: error.message }).finally(() => socket.destroy(error)).then(() => { throw error; });
+        });
+        transferChain.catch(() => undefined);
+        return;
+      }
+      if (message.type === "extension_disconnected") {
+        transferChain = transferChain.then(() => {
+          const error = new Error(message.message || "Surf extension disconnected");
+          rejectPending(error);
+          socket.end();
+        });
+        transferChain.catch(() => undefined);
+        return;
+      }
+      if (message.id === undefined || !pending.has(message.id)) return;
+      transferChain = transferChain.then(() => {
+        const entry = pending.get(message.id);
+        if (!entry) return;
+        pending.delete(message.id);
+        clearTimeout(entry.timer);
+        entry.resolve(message);
+      }).catch((error) => {
+        rejectPending(error);
+        socket.destroy(error);
+      });
+      transferChain.catch(() => undefined);
+    },
+    onError(error) {
+      rejectPending(error);
+      readyReject?.(error);
+      socket.destroy();
+    },
+  });
+  socket.on("data", (chunk) => parser.push(chunk));
+  let closed = false;
+  socket.on("close", () => {
+    parser.close();
+    const error = new Error("connection closed");
+    rejectPending(error);
+    writer.close(error);
+    cleanupTransfers(error);
+    closed = true;
+  });
+  return {
+    socket,
+    transfers,
+    async request(message, timeoutMs = requestTimeoutMs, transferPlan = {}) {
+      if (closed) throw new Error("client transport is closed");
+      if (message.id === undefined || message.id === null) throw new Error("request id is required");
+      if (pending.has(message.id)) throw new Error("duplicate request id");
+      const downloadIds = (transferPlan.downloads || []).map((download) => download.transferId);
+      const timeoutError = new Error("request timed out");
+      let rejectTimeout;
+      const timeout = new Promise((_, reject) => { rejectTimeout = reject; });
+      timeout.catch(() => undefined);
+      const timer = setTimeout(() => {
+        closed = true;
+        rejectPending(timeoutError);
+        cleanupTransfers(timeoutError).catch(() => {});
+        writer.close(timeoutError);
+        socket.destroy();
+        rejectTimeout(timeoutError);
+      }, timeoutMs);
+      const execute = async () => {
+        try {
+          if (transfers) {
+            for (const download of transferPlan.downloads || []) await transfers.expectDownload(download);
+            const uploadDescriptors = [];
+            for (const upload of transferPlan.uploads || []) {
+              const result = await transfers.upload(upload.path, upload);
+              uploadDescriptors.push({ transferId: result.transferId, field: upload.field, original: upload.original, kind: "upload" });
+            }
+            message = { ...message, _surfTransfers: { uploads: uploadDescriptors, downloads: (transferPlan.downloads || []).map(({ transferId, field, original }) => ({ transferId, field, original, kind: "download" })) }, _surfPaths: transferPlan.pathRefs || [] };
+          }
+          const response = new Promise((resolve, reject) => {
+            pending.set(message.id, { resolve, reject, timer });
+          });
+          response.catch(() => undefined);
+          try {
+            await writer.send(message);
+          } catch (error) {
+            const entry = pending.get(message.id);
+            if (entry) { pending.delete(message.id); clearTimeout(entry.timer); entry.reject(error); }
+            await transfers?.cancelDownloads(downloadIds);
+            await response.catch(() => undefined);
+            throw error;
+          }
+          const result = await response;
+          if (result.error || (transfers && downloadIds.some((id) => transfers.hasDownload(id)))) {
+            await transfers?.cancelDownloads(downloadIds);
+            if (!result.error) throw new Error("request completed without completing output download");
+          }
+          return result;
+        } catch (error) {
+          await transfers?.cancelDownloads(downloadIds);
+          throw error;
+        }
+      };
+      try {
+        return await Promise.race([execute(), timeout]);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    async closeAsync() {
+      if (closed) return transferCleanupPromise;
+      closed = true;
+      const error = new Error("client transport is closed");
+      parser.close();
+      rejectPending(error);
+      writer.close(error);
+      const cleanup = cleanupTransfers(error);
+      socket.end();
+      await cleanup;
+      return cleanup;
+    },
+    close() {
+      return this.closeAsync();
+    },
+  };
+}
+
+module.exports = { DEFAULT_REQUEST_TIMEOUT_MS, openClientTransport };

package/native/do-executor.cjs

@@ -10,8 +10,10 @@
  * Follows the same socket communication pattern as --script mode in cli.cjs.
  */
 
-const net = require("net");
-const { SOCKET_PATH, formatSocketError } = require("./socket-path.cjs");
+const { selectEndpoint } = require("./endpoint.cjs");
+const { openClientTransport } = require("./client-transport.cjs");
+const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
+const { prepareRemoteTool, validateLocalToolPaths } = require("./file-transfer.cjs");
 
 // Maximum iterations for loops (safety cap)
 const MAX_LOOP_ITERATIONS = 100;
@@ -71,48 +73,27 @@ function getAutoWaitCommand(cmd) {
  * @returns {Promise<object>} - Response from host
  */
 function sendDoRequest(toolName, toolArgs, context = {}) {
-  return new Promise((resolve, reject) => {
-    const sock = net.createConnection(SOCKET_PATH, () => {
-      const req = {
-        type: "tool_request",
-        method: "execute_tool",
-        params: { tool: toolName, args: toolArgs },
-        id: "do-" + Date.now() + "-" + Math.random(),
-      };
-      if (context.tabId) req.tabId = context.tabId;
-      if (context.windowId) req.windowId = context.windowId;
-      sock.write(JSON.stringify(req) + "\n");
-    });
-    
-    let buf = "";
-    sock.on("data", (d) => {
-      buf += d.toString();
-      const lines = buf.split("\n");
-      buf = lines.pop();
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        try {
-          const resp = JSON.parse(line);
-          sock.end();
-          resolve(resp);
-        } catch {
-          sock.end();
-          reject(new Error("Invalid JSON response"));
-        }
-      }
-    });
-    
-    sock.on("error", (e) => {
-      reject(new Error(formatSocketError(e)));
-    });
-    
-    const timeoutId = setTimeout(() => { 
-      sock.destroy(); 
-      reject(new Error("Request timeout")); 
-    }, 30000);
-    
-    sock.on("close", () => clearTimeout(timeoutId));
-  });
+  const request = {
+    type: "tool_request",
+    method: "execute_tool",
+    params: { tool: toolName, args: toolArgs },
+    id: "do-" + Date.now() + "-" + Math.random(),
+  };
+  if (context.tabId) request.tabId = context.tabId;
+  if (context.windowId) request.windowId = context.windowId;
+  const requestTimeoutMs = context.timeoutMs || resolveRequestDeadlineMs(toolName, toolArgs);
+  const endpoint = context.endpoint || selectEndpoint([]).endpoint;
+  const prepared = endpoint.kind === "remote" ? prepareRemoteTool(toolName, toolArgs) : (() => { const args = validateLocalToolPaths(toolName, toolArgs); return { args, uploads: [], downloads: [] }; })();
+  request.params.args = prepared.args;
+  if (context.transport) return context.transport.request(request, requestTimeoutMs, prepared);
+  return (async () => {
+    const transport = await openClientTransport(endpoint);
+    try {
+      return await transport.request(request, requestTimeoutMs, prepared);
+    } finally {
+      await transport.close();
+    }
+  })();
 }
 
 /**

package/native/doctor.cjs

@@ -3,6 +3,7 @@ const net = require("net");
 const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
+const { connectEndpoint, selectEndpoint } = require("./endpoint.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -402,6 +403,16 @@ function buildRecommendations(report) {
   return Array.from(new Set(recommendations));
 }
 
+function remoteRecommendations(endpoint, code) {
+  const base = [`Confirm Surf is listening on ${endpoint.display}; the remote host listener must allow this Tailnet connection.`];
+  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."];
+  if (code === "ENETUNREACH" || code === "EHOSTUNREACH") return [...base, `Run \`tailscale status\` and \`tailscale ping ${endpoint.host}\`; check Tailnet routing plus restrictive ACLs/grants.`];
+  if (code === "EAUTH") return [...base, "Verify the client credential path, pinned host identity, and that the labeled client has not been revoked."].map((item) => item.replace("<host>", endpoint.host));
+  return base;
+}
+
 async function runDoctor(rawOptions = {}, deps = {}) {
   const env = deps.env || process.env;
   const platform = deps.platform || process.platform;
@@ -413,6 +424,41 @@ async function runDoctor(rawOptions = {}, deps = {}) {
     socket: rawOptions.socket || env.SURF_SOCKET || defaultSocketPath(platform),
     connectTimeoutMs: rawOptions.connectTimeoutMs ?? 750,
   };
+  const selectedEndpoint = rawOptions.endpoint || selectEndpoint([], env).endpoint;
+  if (selectedEndpoint.kind === "remote") {
+    const endpoint = selectedEndpoint;
+    const connection = await (deps.connectEndpoint || ((target, timeoutMs) => new Promise((resolve) => {
+      let settled = false;
+      let socket;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        socket?.destroy();
+        resolve(result);
+      };
+      const timeout = setTimeout(() => finish({
+        ok: false,
+        code: socket?.connected ? "EAUTH" : "ETIMEDOUT",
+        message: socket?.connected ? "remote authentication timed out" : `timed out after ${timeoutMs}ms`,
+      }), timeoutMs);
+      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 }, {
+      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}`,
+      code: connection.code,
+    }, {
+      id: "remote-auth", status: connection.ok ? "pass" : connection.code === "EAUTH" ? "fail" : "info",
+      message: connection.ok ? "Remote credential authenticated and server identity verified" : connection.code === "EAUTH" ? "Remote credential rejected, revoked, or server identity mismatch" : "Remote authentication was not reached",
+      code: connection.code,
+    }];
+    const summary = summarize(checks);
+    const report = { ok: connection.ok, summary, environment: { platform, remoteEndpoint: endpoint.display, endpointKind: "remote", browsers: [] }, manifests: [], checks };
+    report.recommendations = connection.ok ? [] : remoteRecommendations(endpoint, connection.code);
+    return report;
+  }
   const effectiveTarget = resolveEffectiveTarget(options, { platform, runningInWsl });
   const browsers = resolveBrowsers(options.browser);
   const context = {
@@ -502,9 +548,13 @@ function formatCheck(check) {
 function formatDoctorReport(report) {
   const lines = ["Surf doctor", ""];
   lines.push(`Platform: ${report.environment.platform}${report.environment.runningInWsl ? " (WSL2 detected)" : ""}`);
-  lines.push(`Target: ${report.environment.effectiveTarget === "wsl-windows" ? "Windows browser from WSL2" : report.environment.effectiveTarget}`);
-  lines.push(`Socket: ${report.environment.socketPath}`);
-  lines.push(`Browsers: ${report.environment.browsers.join(", ")}`);
+  if (report.environment.endpointKind === "remote") {
+    lines.push(`Remote endpoint: ${report.environment.remoteEndpoint}`);
+  } else {
+    lines.push(`Target: ${report.environment.effectiveTarget === "wsl-windows" ? "Windows browser from WSL2" : report.environment.effectiveTarget}`);
+  }
+  if (report.environment.socketPath) lines.push(`Socket: ${report.environment.socketPath}`);
+  if (report.environment.browsers.length) lines.push(`Browsers: ${report.environment.browsers.join(", ")}`);
   lines.push("");
 
   for (const check of report.checks.filter((item) => item.status !== "info")) {
@@ -542,7 +592,7 @@ Examples:
 `;
 }
 
-async function runDoctorCli(rawArgs) {
+async function runDoctorCli(rawArgs, endpoint) {
   let options;
   try {
     options = parseDoctorArgs(rawArgs);
@@ -558,7 +608,7 @@ async function runDoctorCli(rawArgs) {
   }
 
   try {
-    const report = await runDoctor(options);
+    const report = await runDoctor({ ...options, endpoint });
     if (options.json) {
       console.log(JSON.stringify(report, null, 2));
     } else {

package/native/endpoint.cjs

@@ -0,0 +1,174 @@
+const net = require("net");
+const { DEFAULT_SOCKET_PATH } = require("./socket-path.cjs");
+const { authenticateClient } = require("./remote-transport.cjs");
+
+function parseRemoteEndpoint(value) {
+  if (typeof value !== "string" || !value) throw new Error("--remote requires host:port");
+  let host;
+  let portText;
+  if (value.startsWith("[")) {
+    const match = value.match(/^\[([^\]]+)\]:(\d+)$/);
+    if (!match || net.isIP(match?.[1]) !== 6) throw new Error("remote endpoint must use a bracketed IPv6 address and port");
+    [, host, portText] = match;
+    host = new URL(`http://[${host}]`).hostname.slice(1, -1);
+  } else {
+    const match = value.match(/^([^:]+):(\d+)$/);
+    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))) {
+      throw new Error("remote endpoint host is invalid");
+    }
+    host = host.toLowerCase();
+  }
+  const port = Number(portText);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("remote endpoint port must be between 1 and 65535");
+  if ((net.isIP(host) === 4 && host === "0.0.0.0") || (net.isIP(host) === 6 && /^0*:?0*$/.test(host.replace(/:/g, "")))) {
+    throw new Error("remote endpoint host must not be unspecified");
+  }
+  const display = net.isIP(host) === 6 ? `[${host}]:${port}` : `${host}:${port}`;
+  return { kind: "remote", host, port, display, key: `tcp:${display}`, connectionOptions: { host, port } };
+}
+
+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);
+  }
+  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 = 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 (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 } };
+}
+
+function createRemoteSocket(endpoint) {
+  const rawSocket = net.createConnection(endpoint.connectionOptions, () => {});
+  let ready = false;
+  let connected = false;
+  let destroyed = false;
+  const pending = new Map();
+  const queue = (event, listener, once) => {
+    if (ready) {
+      once ? rawSocket.once(event, listener) : rawSocket.on(event, listener);
+      return;
+    }
+    const listeners = pending.get(event) || [];
+    listeners.push({ listener, once });
+    pending.set(event, listeners);
+  };
+  const flush = () => {
+    ready = true;
+    for (const [event, listeners] of pending) {
+      for (const { listener, once } of listeners) {
+        once ? rawSocket.once(event, listener) : rawSocket.on(event, listener);
+      }
+    }
+    pending.clear();
+  };
+  const proxy = {
+    on(event, listener) { queue(event, listener, false); return proxy; },
+    once(event, listener) { queue(event, listener, true); return proxy; },
+    removeListener(event, listener) {
+      if (ready) rawSocket.removeListener(event, listener);
+      else pending.set(event, (pending.get(event) || []).filter((entry) => entry.listener !== listener));
+      return proxy;
+    },
+    write(...args) { return rawSocket.write(...args); },
+    end(...args) { return rawSocket.end(...args); },
+    destroy(...args) { destroyed = true; return rawSocket.destroy(...args); },
+    setTimeout(...args) { rawSocket.setTimeout(...args); return proxy; },
+    get authenticated() { return ready; },
+    get connected() { return connected; },
+  };
+  rawSocket.once("connect", () => { connected = true; });
+  rawSocket.on("error", (error) => {
+    if (ready || destroyed) return;
+    ready = true;
+    const listeners = pending.get("error") || [];
+    pending.delete("error");
+    for (const { listener } of listeners) listener(error);
+    if (proxy.__pendingErrors) proxy.__pendingErrors.length = 0;
+    flush();
+  });
+  rawSocket.on("close", () => {
+    if (ready) return;
+    ready = true;
+    const error = new Error("remote authentication connection closed");
+    for (const { listener } of pending.get("error") || []) listener(error);
+    for (const { listener } of pending.get("close") || []) listener();
+    pending.clear();
+    if (proxy.__pendingErrors) proxy.__pendingErrors.length = 0;
+  });
+  return { rawSocket, proxy, flush };
+}
+
+function connectEndpoint(endpoint, onConnect) {
+  if (endpoint.kind === "local") {
+    return net.createConnection(endpoint.connectionOptions, onConnect || (() => {}));
+  }
+  const { rawSocket, proxy, flush } = createRemoteSocket(endpoint);
+  rawSocket.once("connect", () => {
+    authenticateClient(rawSocket, endpoint.credentialPath)
+      .then(() => {
+        flush();
+        if (onConnect) onConnect(proxy);
+      })
+      .catch((error) => {
+        error.code = error.code || "EAUTH";
+        const listeners = proxy.__pendingErrors || [];
+        for (const listener of listeners) {
+          proxy.removeListener("error", listener);
+          listener(error);
+        }
+        proxy.__pendingErrors.length = 0;
+        flush();
+        proxy.destroy();
+      });
+  });
+  proxy.__pendingErrors = [];
+  const originalOn = proxy.on;
+  const originalOnce = proxy.once;
+  proxy.on = (event, listener) => {
+    if (event === "error" && !proxy.authenticated) proxy.__pendingErrors.push(listener);
+    return originalOn(event, listener);
+  };
+  proxy.once = (event, listener) => {
+    if (event === "error" && !proxy.authenticated) proxy.__pendingErrors.push(listener);
+    return originalOnce(event, listener);
+  };
+  return proxy;
+}
+
+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}`;
+}
+
+module.exports = { parseRemoteEndpoint, selectEndpoint, connectEndpoint, formatEndpointError };