linkshell-cli 0.5.1 → 0.5.4

package/dist/cli/src/runtime/bridge-session.js

@@ -4,8 +4,8 @@ import WebSocket from "ws";
 import { hostname, platform, homedir } from "node:os";
 import { writeFileSync, readFileSync, readdirSync, statSync, unlinkSync, mkdirSync, existsSync, openSync, readSync, closeSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, basename, resolve } from "node:path";
-import { createEnvelope, parseEnvelope, parseTypedPayload, serializeEnvelope, PROTOCOL_VERSION, } from "@linkshell/protocol";
+import { join, basename, resolve, relative, isAbsolute } from "node:path";
+import { agentV2MessageRoute, createEnvelope, parseEnvelope, parseTypedPayload, serializeEnvelope, PROTOCOL_VERSION, } from "@linkshell/protocol";
 import { ScrollbackBuffer } from "./scrollback.js";
 import { ScreenFallback } from "./screen-fallback.js";
 import { ScreenShare } from "./screen-share.js";
@@ -22,6 +22,16 @@ const RECONNECT_MAX_DELAY = 30_000;
 const RECONNECT_MAX_ATTEMPTS = 20;
 const DEFAULT_TERMINAL_ID = "default";
 const HOOK_BODY_LIMIT = 256 * 1024;
+const SCROLLBACK_LINES = 500;
+// Upper bound on concurrent live terminals — forceNew removed the cwd-dedup
+// ceiling, so bound growth to avoid PTY/fd exhaustion from a runaway client.
+const MAX_TERMINALS = 12;
+// How long to keep an exited terminal (with its scrollback) in memory so the
+// client can replay its final output before it is reaped.
+const EXITED_TERMINAL_GRACE_MS = 30_000;
+// Default ports the bridge will proxy tunnel requests to when no explicit
+// allowlist is configured. Covers the common dev servers the app tunnels to.
+const DEFAULT_TUNNEL_PORTS = [3000, 3001, 4321, 5173, 5174, 8080, 8000, 8081];
 const PERMISSION_REQUEST_TIMEOUT_MS = Number(process.env.LINKSHELL_PERMISSION_TIMEOUT_MS ?? 5 * 60_000);
 const LINKSHELL_PERMISSION_GUARD_MARKER = "LINKSHELL_PERMISSION_GUARD";
 function isLinkShellHookEntry(entry, marker) {
@@ -128,9 +138,21 @@ function hookPermissionOptions(suggestions) {
             : []),
     ];
 }
+function stripGatewayBase(url) {
+    url.hash = "";
+    url.search = "";
+    url.pathname = "";
+    return url.toString().replace(/\/+$/, "");
+}
+function isHttpGatewayUrl(url) {
+    return url.protocol === "http:" || url.protocol === "https:";
+}
 function getPairingGatewayParam(gatewayHttpUrl) {
     try {
         const url = new URL(gatewayHttpUrl);
+        if (!isHttpGatewayUrl(url)) {
+            return undefined;
+        }
         const hostname = url.hostname.trim().toLowerCase();
         if (hostname === "localhost" ||
             hostname === "127.0.0.1" ||
@@ -142,38 +164,50 @@ function getPairingGatewayParam(gatewayHttpUrl) {
                 return undefined; // No LAN interface found, can't help
             }
             url.hostname = lanIp;
-            return url.toString().replace(/\/+$/, "");
+            return stripGatewayBase(url);
         }
-        return url.toString().replace(/\/+$/, "");
+        return stripGatewayBase(url);
     }
     catch {
         return gatewayHttpUrl.replace(/\/+$/, "") || undefined;
     }
 }
-function resolvePairingGateway(gatewayHttpUrl, pairingGateway) {
+export function resolvePairingGateway(gatewayHttpUrl, pairingGateway) {
     const override = pairingGateway?.trim();
     if (!override) {
         return getPairingGatewayParam(gatewayHttpUrl);
     }
     try {
         const absoluteUrl = new URL(override);
-        return absoluteUrl.toString().replace(/\/+$/, "");
+        if (isHttpGatewayUrl(absoluteUrl)) {
+            return stripGatewayBase(absoluteUrl);
+        }
+    }
+    catch {
+        // Fall through and treat the override as a host[:port] value.
+    }
+    try {
+        const baseUrl = new URL(gatewayHttpUrl);
+        if (!isHttpGatewayUrl(baseUrl)) {
+            return override.replace(/\/+$/, "") || undefined;
+        }
+        const normalizedHost = override
+            .replace(/^https?:\/\//i, "")
+            .replace(/\/.*$/, "")
+            .trim();
+        if (!normalizedHost) {
+            return getPairingGatewayParam(gatewayHttpUrl);
+        }
+        baseUrl.host = normalizedHost;
+        return stripGatewayBase(baseUrl);
     }
     catch {
         try {
-            const baseUrl = new URL(gatewayHttpUrl);
-            const normalizedHost = override
-                .replace(/^https?:\/\//i, "")
-                .replace(/\/.*$/, "")
-                .trim();
-            if (!normalizedHost) {
-                return getPairingGatewayParam(gatewayHttpUrl);
-            }
-            baseUrl.hostname = normalizedHost;
-            return baseUrl.toString().replace(/\/+$/, "");
+            const prefixed = new URL(`http://${override.replace(/^\/+/, "")}`);
+            return stripGatewayBase(prefixed);
         }
         catch {
-            return override.replace(/\/+$/, "") || undefined;
+            return undefined;
         }
     }
 }
@@ -183,6 +217,25 @@ function normalizeAgentProvider(provider) {
     }
     return "codex";
 }
+export function resolveAgentWorkspaceProviders(options) {
+    if (options.agentCommand?.trim()) {
+        return [normalizeAgentProvider(options.agentProvider ?? "custom")];
+    }
+    const defaultProviders = ["codex", "claude"];
+    const detected = detectAvailableProviders();
+    const requested = options.agentProvider ? normalizeAgentProvider(options.agentProvider) : undefined;
+    const ordered = [
+        ...(requested ? [requested] : []),
+        ...detected,
+        ...defaultProviders,
+    ];
+    const unique = [];
+    for (const provider of ordered) {
+        if (!unique.includes(provider))
+            unique.push(provider);
+    }
+    return unique;
+}
 export class BridgeSession {
     options;
     socket;
@@ -192,6 +245,7 @@ export class BridgeSession {
     reconnectAttempts = 0;
     reconnecting = false;
     sessionId = "";
+    hostToken;
     exited = false;
     stopped = false;
     permissionStacks = new Map();
@@ -205,9 +259,48 @@ export class BridgeSession {
     agentSession;
     agentWorkspace;
     machineIdentity;
+    // Confinement root for client-driven filesystem ops; resolved once at construction.
+    fileRoot;
+    // Ports the tunnel proxy may connect to on 127.0.0.1.
+    allowedTunnelPorts;
+    // Pending deletions of exited terminals (terminalId → timer) so we can clear on stop().
+    exitedTerminalTimers = new Map();
+    // Invoked when all terminals have exited naturally — closes embedded gateway,
+    // removes daemon PID file, etc. Set by the CLI entry point.
+    onAllTerminalsExited;
     constructor(options) {
         this.options = options;
         this.sessionId = options.sessionId ?? "";
+        // Confine client-driven file ops to the user's home by default (single-user
+        // self-hosted model: the owner browses their own projects under ~). This
+        // still blocks /etc, /usr, other users' dirs. Override via --file-root.
+        this.fileRoot = resolve(options.fileRoot ?? homedir());
+        this.allowedTunnelPorts = new Set(options.allowedTunnelPorts && options.allowedTunnelPorts.length > 0
+            ? options.allowedTunnelPorts
+            : DEFAULT_TUNNEL_PORTS);
+    }
+    /** Register a callback invoked once all terminals exit naturally (process self-cleanup). */
+    setOnAllTerminalsExited(handler) {
+        this.onAllTerminalsExited = handler;
+    }
+    /**
+     * Resolve a client-supplied path inside the confinement root.
+     * Returns the absolute resolved path, or null if it escapes the root.
+     */
+    resolveConfinedPath(clientPath) {
+        const expanded = clientPath.startsWith("~")
+            ? clientPath.replace(/^~/, homedir())
+            : clientPath;
+        // Resolve relative paths against the confinement root, not process.cwd().
+        const target = isAbsolute(expanded)
+            ? resolve(expanded)
+            : resolve(this.fileRoot, expanded);
+        const rel = relative(this.fileRoot, target);
+        if (rel === "")
+            return target; // the root itself
+        if (rel.startsWith("..") || isAbsolute(rel))
+            return null;
+        return target;
     }
     log(msg) {
         if (this.options.verbose) {
@@ -221,6 +314,9 @@ export class BridgeSession {
     async start() {
         this.log(`starting session (gateway=${this.options.gatewayUrl}, provider=${this.options.providerConfig.provider})`);
         this.machineIdentity = loadOrCreateMachineIdentity();
+        // Sweep stale LinkShell hook entries (dead curl ports) left by a prior crash
+        // before we write fresh ones for this session.
+        this.sweepStaleHookConfigs();
         if (!this.sessionId) {
             await this.createPairing();
         }
@@ -232,9 +328,7 @@ export class BridgeSession {
         }
         if (this.options.agentUi) {
             process.env.LINKSHELL_ID = this.terminalHookMarker(DEFAULT_TERMINAL_ID);
-            const availableProviders = this.options.agentProvider
-                ? [normalizeAgentProvider(this.options.agentProvider)]
-                : detectAvailableProviders();
+            const availableProviders = resolveAgentWorkspaceProviders(this.options);
             const agentOptions = {
                 sessionId: this.sessionId,
                 cwd: process.cwd(),
@@ -270,6 +364,10 @@ export class BridgeSession {
         }
         const body = (await res.json());
         this.sessionId = body.sessionId;
+        // Secret token proving we are the legitimate host for this session; sent on
+        // every host WS connect so a third party who learns the sessionId can't
+        // hijack the host role.
+        this.hostToken = body.hostToken;
         const pairingGateway = resolvePairingGateway(this.options.gatewayHttpUrl, this.options.pairingGateway);
         const deepLink = pairingGateway
             ? `linkshell://pair?code=${body.pairingCode}&gateway=${encodeURIComponent(pairingGateway)}`
@@ -328,10 +426,23 @@ export class BridgeSession {
         url.searchParams.set("sessionId", this.sessionId);
         url.searchParams.set("role", "host");
         const authToken = await this.resolveAuthToken();
+        const wsOptions = {};
+        const headers = {};
         if (authToken) {
+            // Prefer the Authorization header so the token doesn't leak into URLs/logs.
+            headers["Authorization"] = `Bearer ${authToken}`;
+            // TODO: remove the query param once all gateways read the Authorization
+            // header. Kept for backward compatibility with older gateways that only
+            // read the `auth_token` query parameter.
             url.searchParams.set("auth_token", authToken);
         }
-        this.socket = new WebSocket(url);
+        if (this.hostToken) {
+            headers["x-linkshell-host-token"] = this.hostToken;
+        }
+        if (Object.keys(headers).length > 0) {
+            wsOptions.headers = headers;
+        }
+        this.socket = new WebSocket(url, wsOptions);
         this.socket.on("open", () => {
             process.stderr.write(this.reconnectAttempts > 0
                 ? "[bridge] gateway reconnected\n"
@@ -384,6 +495,49 @@ export class BridgeSession {
     }
     async handleMessage(envelope) {
         const tid = envelope.terminalId ?? DEFAULT_TERMINAL_ID;
+        const agentV2Route = agentV2MessageRoute(envelope.type);
+        if (agentV2Route === "client_write" || agentV2Route === "client_read") {
+            if (!this.agentWorkspace) {
+                this.send(createEnvelope({
+                    type: "agent.v2.capabilities",
+                    sessionId: this.sessionId,
+                    payload: {
+                        enabled: false,
+                        provider: normalizeAgentProvider(this.options.agentProvider ?? "codex"),
+                        machineId: this.machineIdentity?.machineId,
+                        workspaceProtocolVersion: 2,
+                        error: "Agent Workspace is not enabled. Start CLI with --agent-ui.",
+                        supportsSessionList: false,
+                        supportsSessionLoad: false,
+                        supportsImages: false,
+                        supportsAudio: false,
+                        supportsPermission: false,
+                        supportsPlan: false,
+                        supportsCancel: false,
+                    },
+                }));
+                return;
+            }
+            if (envelope.type === "agent.v2.prompt" || envelope.type === "agent.v2.command.execute") {
+                this.refreshAgentPermissionHooks();
+            }
+            try {
+                await this.agentWorkspace.handleEnvelope(envelope);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.log(`agent.v2 invalid message: ${message}`);
+                this.send(createEnvelope({
+                    type: "session.error",
+                    sessionId: this.sessionId,
+                    payload: {
+                        code: "invalid_message",
+                        message: `Invalid Agent Workspace message: ${message}`,
+                    },
+                }));
+            }
+            return;
+        }
         switch (envelope.type) {
             case "terminal.input": {
                 const p = parseTypedPayload("terminal.input", envelope.payload);
@@ -402,8 +556,22 @@ export class BridgeSession {
             case "terminal.spawn": {
                 const p = parseTypedPayload("terminal.spawn", envelope.payload);
                 const normalizedCwd = resolve(p.cwd);
-                // Dedup: if a running terminal already exists for this cwd, return it
-                const existing = [...this.terminals.values()].find((t) => t.status === "running" && resolve(t.cwd) === normalizedCwd);
+                // Cap concurrent terminals — forceNew removed the cwd-dedup ceiling, so
+                // bound growth explicitly to avoid PTY/fd exhaustion from a runaway client.
+                const liveCount = [...this.terminals.values()].filter((t) => t.status === "running").length;
+                if (liveCount >= MAX_TERMINALS) {
+                    this.send(createEnvelope({
+                        type: "session.error",
+                        sessionId: this.sessionId,
+                        payload: { code: "too_many_terminals", message: `最多同时打开 ${MAX_TERMINALS} 个终端` },
+                    }));
+                    break;
+                }
+                // Dedup by cwd UNLESS the client explicitly asks for a fresh terminal
+                // (forceNew lets web open multiple tabs in the same directory).
+                const existing = p.forceNew
+                    ? undefined
+                    : [...this.terminals.values()].find((t) => t.status === "running" && resolve(t.cwd) === normalizedCwd);
                 if (existing) {
                     this.send(createEnvelope({
                         type: "terminal.spawned",
@@ -446,9 +614,15 @@ export class BridgeSession {
             }
             case "terminal.browse": {
                 const p = parseTypedPayload("terminal.browse", envelope.payload);
-                // Expand ~ to home directory
-                const rawPath = p.path.startsWith("~") ? p.path.replace(/^~/, homedir()) : p.path;
-                const browsePath = resolve(rawPath);
+                const browsePath = this.resolveConfinedPath(p.path);
+                if (browsePath === null) {
+                    this.send(createEnvelope({
+                        type: "terminal.browse.result",
+                        sessionId: this.sessionId,
+                        payload: { path: p.path, entries: [], error: "Path is outside the allowed root", requestId: p.requestId },
+                    }));
+                    break;
+                }
                 try {
                     const entries = readdirSync(browsePath, { withFileTypes: true })
                         .filter((d) => !d.name.startsWith(".") && (d.isDirectory() || (p.includeFiles && d.isFile())))
@@ -485,8 +659,22 @@ export class BridgeSession {
             }
             case "terminal.file.read": {
                 const p = parseTypedPayload("terminal.file.read", envelope.payload);
-                const rawPath = p.path.startsWith("~") ? p.path.replace(/^~/, homedir()) : p.path;
-                const filePath = resolve(rawPath);
+                const filePath = this.resolveConfinedPath(p.path);
+                if (filePath === null) {
+                    this.send(createEnvelope({
+                        type: "terminal.file.read.result",
+                        sessionId: this.sessionId,
+                        payload: {
+                            path: p.path,
+                            content: "",
+                            encoding: "utf8",
+                            truncated: false,
+                            error: "Path is outside the allowed root",
+                            requestId: p.requestId,
+                        },
+                    }));
+                    break;
+                }
                 try {
                     const stats = statSync(filePath);
                     if (!stats.isFile()) {
@@ -536,8 +724,15 @@ export class BridgeSession {
             }
             case "terminal.mkdir": {
                 const p = parseTypedPayload("terminal.mkdir", envelope.payload);
-                const rawPath = p.path.startsWith("~") ? p.path.replace(/^~/, homedir()) : p.path;
-                const dirPath = resolve(rawPath);
+                const dirPath = this.resolveConfinedPath(p.path);
+                if (dirPath === null) {
+                    this.send(createEnvelope({
+                        type: "terminal.browse.result",
+                        sessionId: this.sessionId,
+                        payload: { path: p.path, entries: [], error: "Path is outside the allowed root" },
+                    }));
+                    break;
+                }
                 try {
                     mkdirSync(dirPath, { recursive: true });
                     // Browse the parent to refresh the listing
@@ -707,41 +902,6 @@ export class BridgeSession {
                 await this.agentSession.handleEnvelope(envelope);
                 break;
             }
-            case "agent.v2.capabilities.request":
-            case "agent.v2.conversation.open":
-            case "agent.v2.conversation.list":
-            case "agent.v2.prompt":
-            case "agent.v2.command.execute":
-            case "agent.v2.cancel":
-            case "agent.v2.permission.respond":
-            case "agent.v2.structured_input.respond":
-            case "agent.v2.snapshot.request": {
-                if (!this.agentWorkspace) {
-                    this.send(createEnvelope({
-                        type: "agent.v2.capabilities",
-                        sessionId: this.sessionId,
-                        payload: {
-                            enabled: false,
-                            provider: normalizeAgentProvider(this.options.agentProvider ?? "codex"),
-                            machineId: this.machineIdentity?.machineId,
-                            workspaceProtocolVersion: 2,
-                            error: "Agent Workspace is not enabled. Start CLI with --agent-ui.",
-                            supportsSessionList: false,
-                            supportsSessionLoad: false,
-                            supportsImages: false,
-                            supportsAudio: false,
-                            supportsPermission: false,
-                            supportsPlan: false,
-                            supportsCancel: false,
-                        },
-                    }));
-                    break;
-                }
-                if (envelope.type === "agent.v2.prompt" || envelope.type === "agent.v2.command.execute")
-                    this.refreshAgentPermissionHooks();
-                await this.agentWorkspace.handleEnvelope(envelope);
-                break;
-            }
             case "file.upload": {
                 const p = parseTypedPayload("file.upload", envelope.payload);
                 const ext = p.filename.split(".").pop() || "png";
@@ -807,6 +967,21 @@ export class BridgeSession {
     // ── Tunnel handlers ────────────────────────────────────────────────
     handleTunnelRequest(payload) {
         const { requestId, method, url: reqUrl, headers, body, port } = payload;
+        // SSRF guard: only proxy to ports in the allowlist (pinned to 127.0.0.1).
+        if (!this.allowedTunnelPorts.has(port)) {
+            this.log(`rejecting tunnel request to disallowed port ${port}`);
+            if (headers.upgrade === "websocket") {
+                this.send(createEnvelope({
+                    type: "tunnel.ws.close",
+                    sessionId: this.sessionId,
+                    payload: { requestId, code: 1008, reason: `Port ${port} is not allowed` },
+                }));
+            }
+            else {
+                this.sendTunnelError(requestId, 403, `Port ${port} is not allowed`);
+            }
+            return;
+        }
         // WebSocket upgrade request
         if (headers.upgrade === "websocket") {
             this.handleTunnelWsUpgrade(requestId, port, reqUrl);
@@ -1018,7 +1193,7 @@ export class BridgeSession {
             cwd,
             projectName: basename(cwd),
             provider,
-            scrollback: new ScrollbackBuffer(1000),
+            scrollback: new ScrollbackBuffer(SCROLLBACK_LINES),
             outputSeq: 0,
             statusSeq: 0,
             status: "running",
@@ -1055,6 +1230,20 @@ export class BridgeSession {
                 payload: { exitCode, signal },
             }));
             this.sendTerminalList();
+            // Reap the exited terminal (and its scrollback) after a grace period so
+            // clients can replay final output, then free the memory. Tracked so the
+            // timer can be cleared on stop().
+            const reapTimer = setTimeout(() => {
+                this.exitedTerminalTimers.delete(terminalId);
+                const t = this.terminals.get(terminalId);
+                if (t && t.status === "exited") {
+                    this.terminals.delete(terminalId);
+                    this.log(`reaped exited terminal ${terminalId}`);
+                }
+            }, EXITED_TERMINAL_GRACE_MS);
+            if (typeof reapTimer.unref === "function")
+                reapTimer.unref();
+            this.exitedTerminalTimers.set(terminalId, reapTimer);
             // If all terminals exited, close the session
             const allExited = [...this.terminals.values()].every((t) => t.status === "exited");
             if (allExited) {
@@ -1062,6 +1251,9 @@ export class BridgeSession {
                 setTimeout(() => {
                     this.stopHeartbeat();
                     this.socket?.close();
+                    // Self-clean process-level resources (embedded gateway + PID file)
+                    // since the PTYs exited naturally rather than via a signal handler.
+                    void this.onAllTerminalsExited?.();
                 }, 500);
                 process.exitCode = exitCode ?? 0;
             }
@@ -1186,9 +1378,7 @@ export class BridgeSession {
             return;
         const marker = term.hookMarker;
         const curlCmd = `curl -s --connect-timeout 1 --max-time ${Math.ceil((PERMISSION_REQUEST_TIMEOUT_MS + 30_000) / 1000)} -X POST "http://127.0.0.1:${term.hookPort}/hook?m=${marker}&lid=$LINKSHELL_ID" -H 'Content-Type: application/json' --data-binary @- || true`;
-        const providers = this.options.agentProvider
-            ? [normalizeAgentProvider(this.options.agentProvider)]
-            : detectAvailableProviders();
+        const providers = resolveAgentWorkspaceProviders(this.options);
         try {
             for (const provider of providers) {
                 if (provider === "codex") {
@@ -1751,6 +1941,60 @@ export class BridgeSession {
         }
         catch { /* ignore parse errors */ }
     }
+    /**
+     * Remove ALL LinkShell hook entries (any marker) from a JSON config file.
+     * Used on startup to sweep stale entries left behind by a crashed instance,
+     * whose curl ports are now dead. Matches via isLinkShellHookEntry rather than
+     * a single marker so entries from previous runs are also cleaned.
+     */
+    sweepLinkShellHookEntries(configPath) {
+        if (!existsSync(configPath))
+            return;
+        try {
+            // Re-read immediately before write to minimize the window for a
+            // concurrent writer to clobber our changes.
+            const raw = JSON.parse(readFileSync(configPath, "utf8"));
+            const hooks = raw.hooks;
+            if (!hooks)
+                return;
+            let changed = false;
+            for (const [eventName, entries] of Object.entries(hooks)) {
+                if (!Array.isArray(entries))
+                    continue;
+                const filtered = entries.filter((entry) => !isLinkShellHookEntry(entry));
+                if (filtered.length !== entries.length) {
+                    changed = true;
+                    if (filtered.length === 0) {
+                        delete hooks[eventName];
+                    }
+                    else {
+                        hooks[eventName] = filtered;
+                    }
+                }
+            }
+            if (changed) {
+                if (Object.keys(hooks).length === 0) {
+                    delete raw.hooks;
+                }
+                writeFileSync(configPath, JSON.stringify(raw, null, 2));
+                this.log(`swept stale LinkShell hook entries from ${configPath}`);
+            }
+        }
+        catch { /* ignore parse errors */ }
+    }
+    /** Sweep stale LinkShell hook entries from known shared config files on startup. */
+    sweepStaleHookConfigs() {
+        const home = homedir();
+        const candidates = [
+            join(home, ".claude", "settings.json"),
+            join(home, ".codex", "hooks.json"),
+            join(home, ".gemini", "settings.json"),
+            join(process.cwd(), "hooks.json"), // copilot (per-cwd)
+        ];
+        for (const path of candidates) {
+            this.sweepLinkShellHookEntries(path);
+        }
+    }
     send(message) {
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
             return;
@@ -1890,6 +2134,11 @@ export class BridgeSession {
             ws.close(1001, "Session stopped");
         }
         this.tunnelSockets.clear();
+        // Clear pending exited-terminal reap timers.
+        for (const timer of this.exitedTerminalTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.exitedTerminalTimers.clear();
         for (const term of this.terminals.values()) {
             this.cleanupHookServer(term);
             if (term.status === "running")