@henlii/pidance 0.2.6 → 0.2.8

package/bin/pidance.js

@@ -10,10 +10,15 @@ const fs = require("fs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { parseLaunchOptions } = require("./pidance-options");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const { loadServerConfig } = require("./pidance-server-config");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const { shouldRequireAuth, resolvePassword, describeHost } = require("./pidance-auth-gate");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { startPidanceHttpServer } = require("./pidance-http-server");
 
 const pkgDir = path.join(__dirname, "..");
-const nextDir = path.join(pkgDir, ".next");
+const distDirName = process.env.PIDANCE_DIST_DIR || ".next";
+const nextDir = path.join(pkgDir, distDirName);
 
 // Node engine 门禁（与 package.json engines.node 对齐）：低于最低版本直接失败，
 // 避免进入半运行状态。npm engines 默认只警告，这里 fail-closed。
@@ -32,27 +37,23 @@ if (!nodeMeetsMin(process.versions.node)) {
   process.exit(1);
 }
 
-// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
-// may not exist when installed via npx).
-let nextBin;
-try {
-  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
-} catch {
-  // Fallback: locate next package root and derive the bin path manually.
-  try {
-    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
-    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
-  } catch {
-    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
-  }
+const { port: explicitPort, hostname: explicitHostname, openBrowser } = parseLaunchOptions();
+const serverConfig = loadServerConfig();
+// 默认绑定：设置 → 通用 开启远程服务 → 0.0.0.0；否则仅本机 127.0.0.1（免密码）。
+// 显式 --hostname / -H / HOSTNAME env 优先；显式 0.0.0.0 仍走密码门禁。
+const hostname = explicitHostname ?? (serverConfig.remoteEnabled ? "0.0.0.0" : "127.0.0.1");
+// 端口优先级：显式 -p / PORT env → 配置文件 port → 产品默认 31415。
+const port = explicitPort ?? (serverConfig.port ? String(serverConfig.port) : "31415");
+const listenPort = Number.parseInt(String(port), 10);
+if (!Number.isInteger(listenPort) || listenPort <= 0) {
+  console.error(`[pidance] 拒绝启动：无效端口 ${port}`);
+  process.exit(1);
 }
 
-const { port, hostname, openBrowser } = parseLaunchOptions();
-
 // 启动认证门禁（fail-closed，P0）：非回环监听地址（0.0.0.0 / :: / 局域网 IP / 非回环主机名）
 // 且未设置认证密码时拒绝启动，防止局域网/公网匿名调用 Agent API（创建会话/发 prompt/调工具）。
-// 仅本机使用：--hostname 127.0.0.1（或 localhost）可省略密码。
-if (shouldRequireAuth(hostname, resolvePassword(process.env))) {
+// 默认仅绑定 127.0.0.1（本机），无需密码；远程服务在设置 → 通用 中开启（须先设置密码）。
+if (shouldRequireAuth(hostname, resolvePassword(process.env), serverConfig)) {
   console.error(
     "[pidance] 拒绝启动：监听地址 " +
       describeHost(hostname) +
@@ -63,7 +64,10 @@ if (shouldRequireAuth(hostname, resolvePassword(process.env))) {
       "（兼容旧变量 PI_WEB_PASSWORD）。",
   );
   console.error(
-    "仅本机访问可省略密码并使用回环地址：pidance --hostname 127.0.0.1（或 localhost）。",
+    "也可以在设置 → 通用 中设置密码并开启远程服务（重启后监听 0.0.0.0）。",
+  );
+  console.error(
+    "仅本机访问默认绑定 127.0.0.1，直接运行 pidance 即可（或 --hostname 127.0.0.1 / localhost）。",
   );
   process.exit(1);
 }
@@ -73,66 +77,47 @@ if (!fs.existsSync(nextDir)) {
   process.exit(1);
 }
 
-const nextArgs = ["start", "-p", port];
-if (hostname) nextArgs.push("-H", hostname);
-
-// Always run next's JS entry with node directly — avoids .bin symlink issues
-// and path-with-spaces problems on Windows when shell: true is used.
-const child = spawn(process.execPath, [nextBin, ...nextArgs], {
-  cwd: pkgDir,
-  stdio: ["inherit", "pipe", "inherit"],
-  env: { ...process.env },
-});
-
-let browserOpened = false;
-const url = `http://${hostname ?? "localhost"}:${port}`;
+const url = `http://${hostname}:${listenPort}`;
+// 浏览器打开用回环地址（0.0.0.0 在多数浏览器不可直达）
+const browserHost = hostname === "0.0.0.0" || hostname === "::" ? "localhost" : hostname;
+const browserUrl = `http://${browserHost}:${listenPort}`;
 
-child.stdout.on("data", (chunk) => {
-  const text = chunk.toString();
-  process.stdout.write(text);
-  if (openBrowser && !browserOpened && text.includes("Ready")) {
-    browserOpened = true;
-    const isWindows = process.platform === "win32";
-    const isMac = process.platform === "darwin";
-    const openCmd = isWindows ? "start" : isMac ? "open" : "xdg-open";
-    const opener = spawn(openCmd, [url], {
-      shell: isWindows,
-      stdio: "ignore",
-      detached: true,
-    });
+function openBrowserOnce() {
+  const isWindows = process.platform === "win32";
+  const isMac = process.platform === "darwin";
+  const openCmd = isWindows ? "start" : isMac ? "open" : "xdg-open";
+  const opener = spawn(openCmd, [browserUrl], {
+    shell: isWindows,
+    stdio: "ignore",
+    detached: true,
+  });
+  opener.on("error", (error) => {
+    console.warn(`Could not open browser automatically: ${error.message}`);
+  });
+  opener.unref();
+}
 
-    opener.on("error", (error) => {
-      console.warn(`Could not open browser automatically: ${error.message}`);
-    });
+void startPidanceHttpServer({
+  dir: pkgDir,
+  hostname,
+  port: listenPort,
+}).then(({ server }) => {
+  console.log(`Ready on ${url}`);
+  if (openBrowser) openBrowserOnce();
 
-    opener.unref();
+  // 同一进程持有 HTTP：SIGTERM 关 listener，不再 spawn next-server。
+  const STOP_GRACE_MS = 8_000;
+  let stopping = false;
+  function requestStop() {
+    if (stopping) return;
+    stopping = true;
+    server.close(() => process.exit(0));
+    const force = setTimeout(() => process.exit(1), STOP_GRACE_MS);
+    if (typeof force.unref === "function") force.unref();
   }
+  process.on("SIGTERM", requestStop);
+  process.on("SIGINT", requestStop);
+}).catch((error) => {
+  console.error(`[pidance] 启动失败：${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
 });
-
-// systemd KillMode=control-group 会给包装进程和 next-server 同时发 SIGTERM。
-// next-server 有活跃 SSE/会话时经常不退出，拖到 TimeoutStopSec=120s 才被 SIGKILL，
-// 一键升级的 systemctl restart 会先超时误报失败。包装进程留下做限期回收。
-const CHILD_STOP_GRACE_MS = 8_000;
-let stopping = false;
-function requestChildStop() {
-  if (stopping) return;
-  stopping = true;
-  try {
-    if (child.exitCode == null && !child.killed) child.kill("SIGTERM");
-  } catch {
-    /* already gone */
-  }
-  const force = setTimeout(() => {
-    try {
-      if (child.exitCode == null) child.kill("SIGKILL");
-    } catch {
-      /* ignore */
-    }
-  }, CHILD_STOP_GRACE_MS);
-  if (typeof force.unref === "function") force.unref();
-  child.once("exit", () => clearTimeout(force));
-}
-process.on("SIGTERM", requestChildStop);
-process.on("SIGINT", requestChildStop);
-
-child.on("exit", (code) => process.exit(code ?? 0));

package/bin/pty-manager.cjs

@@ -0,0 +1,149 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const { existsSync, realpathSync } = require("fs");
+const { WebSocketServer } = require("ws");
+const ptyWss = new WebSocketServer({ noServer: true });
+
+function sanitizeEnv(env) {
+  const next = { ...env };
+  delete next.PI_WEB_PASSWORD;
+  delete next.PIDANCE_PASSWORD;
+  return next;
+}
+
+function tryLoadNodePty() {
+  try {
+    const loaded = require("node-pty");
+    if (typeof loaded.spawn !== "function") return null;
+    return loaded;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePtyCwd(cwd) {
+  if (!existsSync(cwd)) throw new Error("PTY cwd 不存在");
+  return realpathSync(cwd);
+}
+
+function startPtySession(options) {
+  const spawner = options.pty === undefined ? tryLoadNodePty() : options.pty;
+  if (!spawner) throw new Error("node-pty 不可用");
+  const cwd = resolvePtyCwd(options.cwd);
+  const cols = options.cols && options.cols > 0 ? options.cols : 80;
+  const rows = options.rows && options.rows > 0 ? options.rows : 24;
+  const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+  const proc = spawner.spawn(shell, [], {
+    name: "xterm-256color",
+    cols,
+    rows,
+    cwd,
+    env: sanitizeEnv(options.env ?? process.env),
+  });
+  let disposed = false;
+  const onChunk = (data) => {
+    if (!disposed) {
+      const text = typeof data === "string" ? data : data.toString();
+      options.onData(text);
+    }
+  };
+  if (typeof proc.on === "function") proc.on("data", onChunk);
+  else if (typeof proc.onData === "function") proc.onData(onChunk);
+  const onGone = (e) => {
+    if (!disposed) options.onExit(typeof e === "object" && e ? e.exitCode : 0);
+  };
+  if (typeof proc.on === "function") proc.on("exit", onGone);
+  else if (typeof proc.onExit === "function") proc.onExit(onGone);
+  return {
+    pid: proc.pid,
+    write: (data) => {
+      if (!disposed) proc.write(data);
+    },
+    resize: (nextCols, nextRows) => {
+      if (!disposed && nextCols > 0 && nextRows > 0) proc.resize(nextCols, nextRows);
+    },
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      try {
+        if (proc.pid > 0) process.kill(-proc.pid, "SIGTERM");
+      } catch {
+        /* 进程组可能已不在 */
+      }
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        /* 已退出 */
+      }
+    },
+  };
+}
+
+function attachPtyToWebSocket(ws, cwd) {
+  const { spawn } = require("child_process");
+  const path = require("path");
+  const workerPath = path.join(__dirname, "pty-worker.js");
+  const child = spawn(process.execPath, [workerPath, cwd, "80", "24"], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: process.env,
+  });
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (data) => console.warn("[pidance] pty-worker stderr", data));
+  child.on("error", (error) => console.warn("[pidance] pty-worker spawn", error.message));
+  const session = {
+    pid: child.pid,
+    write: (data) => child.stdin.write(`${JSON.stringify({ type: "in", d: data })}\n`),
+    resize: (cols, rows) => child.stdin.write(`${JSON.stringify({ type: "rs", cols, rows })}\n`),
+    dispose: () => {
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+    },
+  };
+  child.stdout.setEncoding("utf8");
+  // pty-worker 输出按 JSON Lines 帧化：{type:"out",d:...}，避免与终端原始输出混淆。
+  let stdoutBuf = "";
+  child.stdout.on("data", (data) => {
+    stdoutBuf += typeof data === "string" ? data : Buffer.from(data).toString("utf8");
+    let idx;
+    while ((idx = stdoutBuf.indexOf("\n")) >= 0) {
+      const line = stdoutBuf.slice(0, idx);
+      stdoutBuf = stdoutBuf.slice(idx + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg && msg.type === "out" && typeof msg.d === "string") {
+          // 统一用 JSON 帧发给浏览器，避免普通输出与控制消息混淆。
+          ws.send(JSON.stringify({ type: "out", d: msg.d }));
+        }
+      } catch { /* 非 JSON 的旧协议输出，尽量原样转发 */ try { ws.send(line); } catch { /* ignore */ } }
+    }
+  });
+  child.on("exit", (code) => {
+    try {
+      if (ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: "exit", code: code ?? 0 }));
+        ws.close();
+      }
+    } catch { /* ignore */ }
+  });
+  ws.on("message", (raw) => {
+    const text = typeof raw === "string" ? raw : raw.toString();
+    let parsed;
+    try { parsed = JSON.parse(text); } catch { return; }
+    if (parsed && parsed.type === "in" && typeof parsed.d === "string") session.write(parsed.d);
+    if (parsed && parsed.type === "rs" && parsed.cols > 0 && parsed.rows > 0) session.resize(parsed.cols, parsed.rows);
+  });
+  ws.on("close", () => session.dispose());
+  ws.on("error", () => session.dispose());
+  try { ws.send(JSON.stringify({ type: "out", d: "\r\n[pidance] terminal ready\r\n" })); } catch { /* ignore */ }
+  return session;
+}
+
+function completePtyUpgrade(req, socket, head, cwd) {
+  ptyWss.handleUpgrade(req, socket, head, (ws) => {
+    ptyWss.emit("connection", ws, req);
+    attachPtyToWebSocket(ws, cwd);
+  });
+}
+
+module.exports = { startPtySession, tryLoadNodePty, resolvePtyCwd, attachPtyToWebSocket, completePtyUpgrade };

package/bin/pty-worker.js

@@ -0,0 +1,48 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const pty = require("node-pty");
+
+const cwd = process.argv[2] || process.cwd();
+const cols = Number(process.argv[3]) || 80;
+const rows = Number(process.argv[4]) || 24;
+const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+const env = { ...process.env };
+delete env.PI_WEB_PASSWORD;
+delete env.PIDANCE_PASSWORD;
+
+const proc = pty.spawn(shell, [], {
+  name: "xterm-256color",
+  cols,
+  rows,
+  cwd,
+  env,
+});
+
+proc.onData((data) => {
+  process.stdout.write(JSON.stringify({ type: "out", d: data }) + "\n");
+});
+proc.onExit((e) => {
+  process.exit(e.exitCode ?? 0);
+});
+
+process.stdin.setEncoding("utf8");
+let buf = "";
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let idx;
+  while ((idx = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, idx);
+    buf = buf.slice(idx + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    if (msg.type === "in" && typeof msg.d === "string") proc.write(msg.d);
+    if (msg.type === "rs" && msg.cols > 0 && msg.rows > 0) proc.resize(msg.cols, msg.rows);
+  }
+});
+
+process.on("SIGTERM", () => {
+  try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+  process.exit(0);
+});

package/bin/pty-ws.js

@@ -0,0 +1,271 @@
+"use strict";
+
+// Pidance PTY WebSocket upgrade 处理器（发布包自包含：不依赖 lib/ 源码树）。
+// 守卫逻辑与 lib/request-guard.ts / lib/ui-session.ts 保持一致的精简内联版：
+// - Host 白名单（DNS rebinding 防护）
+// - 可选认证：PIDANCE_PASSWORD / PI_WEB_PASSWORD 启用时接受 UI 会话 Cookie（JWT）或 Basic
+// - 兜底：未设置密码时仅放行回环请求（fail-closed）
+// WebSocket 升级不做 CSRF 校验：部分手机浏览器 Origin / sec-fetch 不完整。
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { existsSync } = require("fs");
+const { homedir } = require("os");
+const { createHash, createHmac, randomBytes, timingSafeEqual } = require("crypto");
+const { isIP } = require("net");
+const fs = require("fs");
+const path = require("path");
+const { tryLoadNodePty, completePtyUpgrade } = require("./pty-manager.cjs");
+
+// ── Host 白名单（对齐 lib/request-guard.ts）──────────────────────────────
+
+function normalizeHostname(hostname) {
+  return (hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname)
+    .toLowerCase()
+    .replace(/\.$/, "");
+}
+
+function hostnameFromHostHeader(host) {
+  if (!host || /[\s/@\\]/.test(host)) return null;
+  try {
+    const url = new URL(`http://${host}`);
+    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) return null;
+    return normalizeHostname(url.hostname);
+  } catch {
+    return null;
+  }
+}
+
+function allowedHosts(env) {
+  return [
+    env.PI_WEB_HOSTNAME,
+    ...(env.PI_WEB_ALLOWED_HOSTS ? String(env.PI_WEB_ALLOWED_HOSTS).split(",") : []),
+  ]
+    .filter((h) => typeof h === "string" && h.trim().length > 0)
+    .map((h) => h.trim());
+}
+
+function isTrustedHost(hostHeader, env) {
+  const hostname = hostHeader ? hostnameFromHostHeader(hostHeader) : null;
+  if (!hostname) return false;
+  if (hostname === "localhost" || hostname.endsWith(".localhost") || isIP(hostname) !== 0) return true;
+  const names = allowedHosts(env)
+    .map((h) => hostnameFromHostHeader(h))
+    .filter((n) => n !== null);
+  return names.includes(hostname);
+}
+
+function isLoopbackHost(hostHeader) {
+  const hostname = hostHeader ? hostnameFromHostHeader(hostHeader) : null;
+  if (!hostname) return false;
+  if (hostname === "localhost" || hostname.endsWith(".localhost")) return true;
+  const ip = isIP(hostname);
+  if (ip === 4) return hostname.startsWith("127.");
+  if (ip === 6) return hostname === "::1" || hostname === "0:0:0:0:0:0:0:1";
+  return false;
+}
+
+// ── 认证（对齐 lib/request-guard.ts + lib/ui-session.ts 精简版）────────────
+
+const UI_SESSION_COOKIE_NAME = "pidance_ui_session";
+
+function resolvePassword(env) {
+  const p =
+    env && env.PIDANCE_PASSWORD && env.PIDANCE_PASSWORD.length > 0
+      ? env.PIDANCE_PASSWORD
+      : env && env.PI_WEB_PASSWORD;
+  return typeof p === "string" && p.length > 0 ? p : null;
+}
+
+function passwordEnabled(env) {
+  return resolvePassword(env) !== null;
+}
+
+function sha256(input) {
+  return createHash("sha256").update(input, "utf8").digest();
+}
+
+function safeEqual(a, b) {
+  return timingSafeEqual(sha256(a), sha256(b));
+}
+
+function checkBasicAuth(headers, env) {
+  const password = resolvePassword(env);
+  if (!passwordEnabled(env) || !password) return false;
+  const auth = headers.authorization;
+  if (!auth) return false;
+  const match = /^Basic\s+(\S+)$/i.exec(auth);
+  if (!match) return false;
+  let decoded;
+  try {
+    const buf = Buffer.from(match[1], "base64");
+    if (buf.toString("base64") !== match[1]) return false;
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch {
+    return false;
+  }
+  const idx = decoded.indexOf(":");
+  if (idx === -1) return false;
+  return safeEqual(decoded.slice(0, idx), "pi") && safeEqual(decoded.slice(idx + 1), password);
+}
+
+function parseCookieValue(cookieHeader, name) {
+  if (!cookieHeader) return null;
+  for (const part of String(cookieHeader).split(";")) {
+    const idx = part.indexOf("=");
+    if (idx <= 0) continue;
+    const key = part.slice(0, idx).trim();
+    if (key !== name) continue;
+    const raw = part.slice(idx + 1).trim();
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      return raw;
+    }
+  }
+  return null;
+}
+
+function defaultSecretFilePath() {
+  const root = process.env.PI_CODING_AGENT_DIR || path.join(homedir(), ".pi", "agent");
+  return path.join(root, "pidance-ui-jwt-secret");
+}
+
+function getOrCreateJwtSecret(env) {
+  const fromEnv = env.PIDANCE_UI_JWT_SECRET || env.OPENCODE_JWT_SECRET;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv.trim();
+  const filePath = defaultSecretFilePath();
+  try {
+    if (fs.existsSync(filePath)) {
+      const existing = fs.readFileSync(filePath, "utf8").trim();
+      if (existing) return existing;
+    }
+  } catch {
+    // 读失败则重建
+  }
+  const secret = randomBytes(32).toString("hex");
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, secret, { mode: 0o600 });
+  } catch {
+    // 无法落盘时仍返回内存密钥（进程内有效）
+  }
+  return secret;
+}
+
+function verifyUiSessionJwt(token, secret, nowMs) {
+  if (!token || !secret) return false;
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  const [header, payload, sig] = parts;
+  const data = `${header}.${payload}`;
+  const expected = createHmac("sha256", secret).update(data).digest();
+  let actual;
+  try {
+    actual = Buffer.from(sig, "base64url");
+  } catch {
+    return false;
+  }
+  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return false;
+  try {
+    const body = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (body.type !== "ui-session") return false;
+    if (typeof body.exp !== "number" || body.exp * 1000 <= nowMs) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function checkUiSessionCookie(headers, env) {
+  if (!passwordEnabled(env)) return false;
+  const token = parseCookieValue(headers.cookie, UI_SESSION_COOKIE_NAME);
+  if (!token) return false;
+  return verifyUiSessionJwt(token, getOrCreateJwtSecret(env), Date.now());
+}
+
+function checkAuthenticated(headers, env) {
+  return checkUiSessionCookie(headers, env) || checkBasicAuth(headers, env);
+}
+
+// ── upgrade 处理（原 lib/pty-ws.ts）─────────────────────────────────────
+
+function header(req, name) {
+  const value = req.headers[name];
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return null;
+}
+
+function ptyGuardHeaders(req) {
+  const host = header(req, "host");
+  const rawUrl = req.url || "/api/pty";
+  const url = `http://${host || "127.0.0.1"}${rawUrl}`;
+  let pathname = "/api/pty";
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    // 用默认
+  }
+  return {
+    host,
+    origin: header(req, "origin"),
+    secFetchSite: header(req, "sec-fetch-site"),
+    secFetchMode: header(req, "sec-fetch-mode"),
+    secFetchDest: header(req, "sec-fetch-dest"),
+    secFetchUser: header(req, "sec-fetch-user"),
+    authorization: header(req, "authorization"),
+    cookie: header(req, "cookie"),
+    method: "GET",
+    url,
+    pathname,
+  };
+}
+
+function reject(socket, status, message) {
+  try {
+    socket.write(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  } catch {
+    // ignore
+  }
+  try {
+    socket.destroy();
+  } catch {
+    // ignore
+  }
+}
+
+async function handlePtyUpgrade(req, socket, head) {
+  if (!tryLoadNodePty()) {
+    reject(socket, 503, "PTY Unavailable");
+    return;
+  }
+  const guardHeaders = ptyGuardHeaders(req);
+  if (!guardHeaders.pathname.startsWith("/api/pty")) {
+    reject(socket, 404, "Not Found");
+    return;
+  }
+  // WebSocket 升级：部分手机浏览器 Origin / sec-fetch 不完整，CSRF 会误杀。
+  // 仍校验 Host 白名单和登录（Cookie / Basic）。
+  if (!isTrustedHost(guardHeaders.host, process.env)) {
+    reject(socket, 403, "untrusted-host");
+    return;
+  }
+  if (passwordEnabled(process.env)) {
+    if (!checkAuthenticated(guardHeaders, process.env)) {
+      reject(socket, 401, "auth-required");
+      return;
+    }
+  } else if (!isLoopbackHost(guardHeaders.host)) {
+    // fail-closed 兜底：未设密码时仅放行回环请求（与 middleware 一致）。
+    reject(socket, 401, "auth-required");
+    return;
+  }
+  const cwd = homedir();
+  if (!existsSync(cwd)) {
+    reject(socket, 500, "home not found");
+    return;
+  }
+  completePtyUpgrade(req, socket, head, cwd);
+}
+
+module.exports = { handlePtyUpgrade, ptyGuardHeaders };