@oversk7/pi-web-dsh-style 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 采用 DeepSeek Harness（DSH）视觉风格、面向 Windows 的非官方 Pi Coding Agent 本地浏览器界面扩展。后端使用 Pi 的公开 RPC 模式，每个会话对应独立的 RPC 进程；历史会话可直接从 Pi 会话文件恢复和渲染。
 
-> 当前正式版本为 1.0.0，仅承诺 Windows 10/11。服务只监听 `127.0.0.1`，不应通过端口转发或反向代理暴露到局域网或公网。
+> 仅承诺 Windows 10/11。首次启动只监听 `127.0.0.1`；电脑网页的“设置 → 手机访问”可配置仅本机、局域网和服务器中转。之后 `pi --web` 使用已保存的模式。
 
 ## 安装
 
@@ -34,9 +34,41 @@ pi --web
 /web
 /web --no-open
 /web --port 18789
+/web --lan
+/web --relay
+/web --local
 /web --stop
 ```
 
+### 手机通过局域网访问
+
+电脑和手机连接同一 Wi-Fi，在电脑本机网页“设置 → 手机访问”中选择“局域网”并保存。也可以执行 `/web --lan`，或直接以 `pi --web-lan` 启动。首次使用时，在同一设置中设置固定密码；之后手机打开显示的地址，输入该密码即可登录。界面只显示一个手机访问地址，优先使用 Wi-Fi，并过滤 WSL、Hyper-V 等虚拟网卡。
+
+手机登录状态保留 30 天。密码在服务重启后继续有效，可在电脑本机网页中修改；修改密码后，已登录的手机需要重新登录。
+
+手机与电脑共用工作区和会话，可各自切换、发送消息、停止生成及回答扩展提问。手机上点击左上角按钮展开会话列表；输入框回车换行，点击发送按钮提交；图片按钮选择手机图片。手机切回前台或网络重连时会刷新会话内容。
+
+设置面板及 `/web --lan`、`/web --relay`、`/web --local` 会保存模式并切换正在运行的服务，保留后台会话进程。切换时浏览器实时连接会重新连接。执行 `/reload` 会保留端口和访问模式；重载或重启服务会保留密码和未过期的登录状态。
+
+首次开启时，如 Windows 弹出防火墙提示，请允许 Node.js 在当前可信网络上接收连接。若手机仍无法打开，检查防火墙是否允许该端口，以及 Wi-Fi 是否启用了客户端隔离。电脑需要保持运行且未休眠。
+
+局域网直连使用 HTTP，请只在可信局域网内使用。
+
+### 通过服务器中转
+
+电脑运行扩展和原生 `frpc`，服务器运行 `frps`、作为 STCP 访问端的 `frpc` 以及 Nginx。手机通过服务器的 HTTPS 域名访问，适用于校园网客户端隔离等无法直连的网络。电脑上的 `frpc` 由扩展启动和关闭，中转请求直接进入扩展的 Web 服务。
+
+1. 从 [frp 官方 Releases](https://github.com/fatedier/frp/releases) 下载电脑对应架构的 Windows 版本，将 `frpc.exe` 解压到固定位置。客户端和服务器建议使用相同版本（已验证 0.70.1）。
+2. 在电脑网页“设置 → 手机访问”选择“服务器中转”，填写服务器域名或 IPv4、frps 端口（默认 `7000`）、frps 认证密钥、手机 HTTPS 入口（如 `https://web.example.com`），以及 `frpc.exe` 路径。路径留空时从 PATH 查找 `frpc`；相对路径以状态目录为基准。认证密钥留空会保留已保存的值。
+3. 保存后，下载设置中生成的 `frps.toml`、`visitor.toml` 和 `nginx.conf`。隧道名称和私有密钥自动生成；隧道名称及服务器内部端口可在高级配置中调整。将域名 DNS 指向服务器，并为该域名准备有效的 HTTPS 证书。
+4. 服务器安装原生 frp 和 Nginx。新服务器使用 `frps -c frps.toml`，访问端使用 `frpc -c visitor.toml`，并用 systemd 等服务管理器保持运行。已有 frps 时复用现有端口和认证密钥，保留其配置。把生成的 Nginx 配置中的证书路径替换成实际证书路径，再安装到 Nginx 的站点配置目录，执行 `nginx -t` 验证并重载。
+
+手机打开显示的 HTTPS 地址，输入原有固定密码即可使用。设置会显示 frpc 的连接或错误状态；服务器暂时不可达时 frpc 自动重连，本机网页仍可使用。后续执行 `pi --web` 会自动恢复保存的中转模式；也可以用 `pi --web-relay` 或 `/web --relay` 明确启用已配置的中转。
+
+服务器需开放 HTTPS 端口和 frps 控制端口；生成的 STCP 访问端仅监听服务器 `127.0.0.1`，无须开放其内部端口。Nginx 配置保留域名 Host、附加代理密钥、限制登录请求速率，并关闭缓冲以支持实时消息。公网访问由扩展直接验证来源和固定密码，登录 Cookie 带有 `Secure` 标记。中转模式下，电脑 Web 服务仅监听本机回环地址。
+
+网络配置和服务器配置下载仅对电脑本机网页开放。更换服务器域名、隧道名称、认证密钥或服务器内部端口后，需要同步部署重新下载的服务器配置。电脑上的 Pi Web 需要保持运行且未休眠。
+
 ## 功能
 
 - 多工作区、多会话和后台会话并行运行。
@@ -45,14 +77,14 @@ pi --web
 - 模型、思考等级、中断、压缩和扩展交互对话框。
 - 运行中逐条显示待处理消息，可单条撤回并重新编辑；`Alt+Q` 可将全部队列消息恢复到输入框。
 - 会话历史保留完整分支与检查点，支持回溯后返回切换前的位置，以及 `pi-rewind` 文件恢复。
-- Windows 系统剪贴板图片和文本粘贴。
+- Windows 系统剪贴板图片和文本粘贴；手机支持选择或粘贴本机图片。
 - 会话中的本地文件链接可在右侧分栏预览，支持语法高亮、行定位和拖拽调整宽度。
 - 设置面板内更新扩展并热重载 Pi 运行时，无需退出 Web UI。
 - 会话 HTML 导出。
 
 ## 进程生命周期
 
-`/web --stop`、宿主 Pi 退出或运行时重载会关闭 Web 会话进程及其后代，包括 detached 后台进程；即使宿主被强制结束，Windows 托管进程也会检测到宿主退出并清理整棵进程树。不会扫描或结束工作区外独立启动的进程，也不会结束其他 Pi 实例。
+`/web --stop`、宿主 Pi 退出或运行时重载会关闭扩展托管的 frpc 和 Web 会话进程及其后代，包括 detached 后台进程；即使宿主被强制结束，Windows 托管进程也会检测到宿主退出并清理整棵进程树。不会扫描或结束工作区外独立启动的进程，也不会结束其他 Pi 实例。
 
 单个 RPC 进程退出、异常终止或被空闲进程回收时，它启动的后台进程也会一起结束。需要独立于会话长期运行的服务，应从 Web 会话之外的终端启动。通过系统服务管理器、计划任务等外部机制启动的进程不属于此进程树。
 
@@ -66,6 +98,10 @@ pi --web
 ~/.pi/agent/pi-web/state.json
 ```
 
+访问密码的加盐哈希和登录签名密钥保存在同一目录的 `auth.json` 中，不保存明文密码。
+
+访问模式及中转配置保存在同一目录的 `network.json` 中。中转所需的 frps 认证密钥、STCP 私有密钥和代理密钥保存在此文件；普通设置响应不返回这些密钥，服务器配置下载会包含部署所需的密钥。配置文件不属于发布包。运行时的 frpc 配置写入状态目录下的 `runtime/`，正常停止时清理。
+
 从旧版目录安装首次升级时，如果新位置尚无状态文件，扩展会从扩展目录中的旧 `state.json` 原样复制并继续使用。旧文件不会被删除或改写，可作为迁移备份。
 
 可用环境变量：

package/frp-process.ts

@@ -0,0 +1,135 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type FrpStatus = { state: "stopped" | "connecting" | "connected" | "error"; message: string };
+type StartOptions = { executable: string; args: string[]; cwd: string };
+type Run = { child: ChildProcess; stopped: boolean; closed: Promise<void> };
+
+export class FrpProcess {
+  status: FrpStatus = { state: "stopped", message: "隧道已停止" };
+  private current?: Run;
+  private pending: Promise<void> = Promise.resolve();
+
+  private onStatus?: (status: FrpStatus) => void;
+
+  constructor(onStatus?: (status: FrpStatus) => void) {
+    this.onStatus = onStatus;
+  }
+
+  private update(state: FrpStatus["state"], message: string): void {
+    if (this.status.state === state && this.status.message === message) return;
+    this.status = { state, message };
+    this.onStatus?.({ ...this.status });
+  }
+
+  private enqueue(action: () => Promise<void>): Promise<void> {
+    const result = this.pending.then(action);
+    this.pending = result.catch(() => {});
+    return result;
+  }
+
+  start(options: StartOptions): Promise<void> {
+    const launch = { ...options, args: [...options.args] };
+    return this.enqueue(async () => {
+      await this.stopCurrent();
+      this.update("connecting", "正在连接隧道服务器");
+      const windows = process.platform === "win32";
+      let child: ChildProcess;
+      try {
+        child = spawn(windows
+          ? join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+          : launch.executable, windows
+          ? ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", fileURLToPath(new URL("./windows-rpc-job.ps1", import.meta.url))]
+          : launch.args, {
+          cwd: launch.cwd,
+          env: { ...process.env, NO_COLOR: "1", ...(windows ? {
+            PI_WEB_RPC_JOB: JSON.stringify({ ownerPid: process.pid, ...launch }),
+          } : {}) },
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true,
+          shell: false,
+          detached: !windows,
+        });
+      } catch {
+        this.update("error", "隧道进程启动失败");
+        throw new Error("隧道进程启动失败");
+      }
+      let resolveClosed!: () => void;
+      const run: Run = { child, stopped: false, closed: new Promise<void>((resolve) => { resolveClosed = resolve; }) };
+      this.current = run;
+      const line = (text: string) => {
+        if (this.current !== run || run.stopped) return;
+        const clean = text.replace(/\x1b\[[0-9;]*m/g, "");
+        if (/start proxy success/i.test(clean)) {
+          this.update("connected", "隧道已连接");
+        } else if (/login.*failed|connection.*(?:closed|lost)|connect.*(?:fail|refused|timeout)|reconnect|retry|re-?login|连接.*(?:丢失|断开|失败)|重试/i.test(clean)) {
+          this.update("connecting", "连接中断，正在重连");
+        } else if (/\b(?:error|fatal|failed)\b|\[E\]|错误/i.test(clean)) {
+          this.update("error", "隧道发生错误，请检查连接设置");
+        }
+      };
+      for (const stream of [child.stdout, child.stderr]) {
+        let buffer = "";
+        stream?.setEncoding("utf8");
+        stream?.on("data", (chunk: string) => {
+          buffer += chunk;
+          let end: number;
+          while ((end = buffer.indexOf("\n")) >= 0) {
+            line(buffer.slice(0, end));
+            buffer = buffer.slice(end + 1);
+          }
+          // Bound unfinished log lines from a long-lived process.
+          if (buffer.length > 16_384) buffer = buffer.slice(-16_384);
+        });
+        stream?.on("end", () => { if (buffer) line(buffer); });
+      }
+      child.on("error", () => {
+        if (this.current === run && !run.stopped) this.update("error", "隧道进程启动失败");
+      });
+      child.once("exit", () => { if (!windows) this.terminate(run); });
+      child.once("close", () => {
+        if (this.current === run) {
+          this.current = undefined;
+          if (run.stopped) this.update("stopped", "隧道已停止");
+          else this.update("error", "隧道进程意外退出");
+        }
+        resolveClosed();
+      });
+      // On Windows, spawn confirms the launcher; target creation failures arrive as an exit.
+      await new Promise<void>((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", () => reject(new Error("隧道进程启动失败")));
+      });
+    });
+  }
+
+  private terminate(run: Run): void {
+    if (process.platform !== "win32" && run.child.pid) {
+      try { process.kill(-run.child.pid, "SIGKILL"); } catch { /* The process group has already exited. */ }
+    }
+    run.child.kill("SIGKILL");
+  }
+
+  private async stopCurrent(): Promise<void> {
+    const run = this.current;
+    if (run) {
+      run.stopped = true;
+      this.terminate(run);
+      await run.closed;
+    }
+    this.update("stopped", "隧道已停止");
+  }
+
+  stop(): Promise<void> {
+    return this.enqueue(() => this.stopCurrent());
+  }
+
+  kill(): void {
+    const run = this.current;
+    if (run) {
+      run.stopped = true;
+      this.terminate(run);
+    }
+  }
+}

package/index.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { getPackageDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai/compat";
+import type { NetworkMode } from "./network-settings.ts";
 
 interface MaintenanceCommandResult {
   stdout: string;
@@ -15,6 +16,8 @@ interface WebServerModule {
     defaultCwd?: string;
     port?: number;
     open?: boolean;
+    lan?: boolean;
+    mode?: NetworkMode;
     initialModelInfo?: {
       models: unknown[];
       thinkingLevels: string[];
@@ -27,10 +30,13 @@ interface WebServerModule {
   }): Promise<string>;
   stopWebServer(): Promise<void>;
   getWebUrl(): string | undefined;
+  getWebLanUrls(): string[];
+  getWebConnectionOptions(): { port: number; lan: boolean; mode: NetworkMode } | undefined;
 }
 
 interface ReloadState {
   resumeWebAfterReload: boolean;
+  connection?: { port: number; lan: boolean; mode: NetworkMode };
 }
 
 const RELOAD_STATE_KEY = Symbol.for("@oversk7/pi-web-dsh-style/reload-state");
@@ -57,6 +63,9 @@ function parseArgs(args?: string): Record<string, string | boolean> {
     const token = tokens[i];
     if (token === "--stop") out.stop = true;
     else if (token === "--no-open") out.open = "false";
+    else if (token === "--lan") out.mode = "lan";
+    else if (token === "--local") out.mode = "local";
+    else if (token === "--relay") out.mode = "relay";
     else if (token === "--port" && tokens[i + 1]) {
       out.port = tokens[++i];
     }
@@ -78,6 +87,7 @@ async function startServer(
       defaultCwd: ctx.cwd,
       port: typeof options.port === "string" ? Number(options.port) : undefined,
       open: options.open !== "false",
+      mode: options.mode as NetworkMode | undefined,
       initialModelInfo: {
         models: initialModels,
         thinkingLevels: ctx.model ? getSupportedThinkingLevels(ctx.model) : [],
@@ -103,6 +113,7 @@ async function startServer(
       },
     });
     ctx.ui.notify(`pi-web: ${url}`, "info");
+    for (const lanUrl of mod.getWebLanUrls()) ctx.ui.notify(`手机访问: ${lanUrl}`, "info");
   } catch (error) {
     serverPromise = undefined;
     ctx.ui.notify(`pi-web failed: ${String(error)}`, "error");
@@ -141,17 +152,38 @@ export default function (pi: ExtensionAPI) {
     default: false,
   });
 
+  pi.registerFlag("web-lan", {
+    description: "Start the web UI with authenticated LAN access for phones",
+    type: "boolean",
+    default: false,
+  });
+
+  pi.registerFlag("web-relay", {
+    description: "Start the web UI with the configured native frp relay",
+    type: "boolean",
+    default: false,
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const resumeAfterReload = reloadState.resumeWebAfterReload;
+    const connection = reloadState.connection;
     reloadState.resumeWebAfterReload = false;
-    if (pi.getFlag("web") === true || resumeAfterReload) {
-      await startServer(pi, ctx, resumeAfterReload ? { open: "false" } : {});
+    reloadState.connection = undefined;
+    if (pi.getFlag("web") === true || pi.getFlag("web-lan") === true || pi.getFlag("web-relay") === true || resumeAfterReload) {
+      await startServer(pi, ctx, resumeAfterReload && connection
+        ? { open: "false", port: String(connection.port), mode: connection.mode }
+        : pi.getFlag("web-relay") === true ? { mode: "relay" }
+        : pi.getFlag("web-lan") === true ? { mode: "lan" } : {});
     }
   });
 
-  pi.on("session_shutdown", async () => {
+  pi.on("session_shutdown", async (event) => {
     if (!serverPromise) return;
     const mod = await serverPromise;
+    if (event.reason === "reload" && mod.getWebUrl()) {
+      reloadState.resumeWebAfterReload = true;
+      reloadState.connection = mod.getWebConnectionOptions();
+    }
     await mod.stopWebServer();
     serverPromise = undefined;
   });

package/local-session.ts

@@ -18,6 +18,7 @@ interface SessionEntry {
   parentId?: string | null;
   timestamp?: string;
   message?: Json;
+  usage?: Json;
   provider?: string;
   modelId?: string;
   thinkingLevel?: string;
@@ -143,6 +144,14 @@ export function loadLocalSession(sessionFile: string, fallbackCwd?: string): Loc
   let input = 0;
   let output = 0;
   let cost = 0;
+  for (const entry of entries) {
+    const message = entry.type === "message" ? entry.message : undefined;
+    const usage = message?.usage ?? ((entry.type === "compaction" || entry.type === "branch_summary") ? entry.usage : undefined);
+    const usageCost = usage && typeof usage === "object" ? (usage as Json).cost : undefined;
+    const total = usageCost && typeof usageCost === "object" ? (usageCost as Json).total : usageCost;
+    if (typeof total === "number" && Number.isFinite(total)) cost += total;
+    else if (typeof message?.cost === "number" && Number.isFinite(message.cost)) cost += message.cost;
+  }
   for (const raw of rawMessages) {
     const message = raw as Json;
     const role = message.role;
@@ -158,7 +167,6 @@ export function loadLocalSession(sessionFile: string, fallbackCwd?: string): Loc
       input += Number(usage.input ?? 0);
       output += Number(usage.output ?? 0);
     }
-    if (typeof message.cost === "number") cost += message.cost;
   }
 
   const state: Json = {
@@ -182,7 +190,7 @@ export function loadLocalSession(sessionFile: string, fallbackCwd?: string): Loc
       toolCalls,
       tokens: { input, output },
       contextUsage: { tokens: contextTokens },
-      cost: Number(cost.toFixed(6)),
+      cost,
     },
     title: sessionName || undefined,
     sessionFile: manager.getSessionFile(),

package/network-access.ts

@@ -0,0 +1,171 @@
+import { createHmac, randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import { networkInterfaces } from "node:os";
+import { promisify } from "node:util";
+import { loadJsonWithLegacyMigration, writeJsonAtomically } from "./state-store.ts";
+
+const derivePassword = promisify(scrypt);
+const LOGIN_SECONDS = 30 * 24 * 60 * 60;
+
+export interface WebProxyConfig {
+  origin: string;
+  secret: string;
+}
+
+function equalSecret(value: unknown, expected: string): boolean {
+  if (typeof value !== "string") return false;
+  const candidate = Buffer.from(value);
+  const secret = Buffer.from(expected);
+  return candidate.length === secret.length && timingSafeEqual(candidate, secret);
+}
+
+interface WebCredentials {
+  salt: string;
+  passwordHash: string;
+  sessionKey: string;
+}
+
+function validCredentials(value: unknown): value is WebCredentials {
+  const data = value as WebCredentials | null;
+  return Boolean(data && typeof data.salt === "string" && /^[a-f0-9]{32}$/.test(data.salt)
+    && typeof data.passwordHash === "string" && /^[a-f0-9]{128}$/.test(data.passwordHash)
+    && typeof data.sessionKey === "string" && /^[a-f0-9]{64}$/.test(data.sessionKey));
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+export function lanAddresses(): string[] {
+  return [...new Set(Object.values(networkInterfaces()).flatMap((entries) => (
+    (entries ?? []).filter((entry) => entry.family === "IPv4" && !entry.internal).map((entry) => entry.address)
+  )))];
+}
+
+export function phoneLanAddress(interfaces = networkInterfaces()): string | undefined {
+  const candidates = Object.entries(interfaces)
+    .filter(([name]) => !/vEthernet|WSL|Hyper-V|VirtualBox|VMware|Loopback/i.test(name))
+    .flatMap(([name, entries]) => (entries ?? [])
+      .filter((entry) => entry.family === "IPv4" && !entry.internal && !entry.address.startsWith("169.254."))
+      .map((entry) => ({ name, address: entry.address })));
+  return (candidates.find(({ name }) => /wi-?fi|wlan|无线/i.test(name)) ?? candidates[0])?.address;
+}
+
+export function requestHostname(req: IncomingMessage): string {
+  try {
+    const authority = req.headers.host ?? "";
+    const url = new URL(`http://${authority}`);
+    if (url.host.toLowerCase() !== authority.toLowerCase() && `${url.hostname}:80` !== authority.toLowerCase()) return "";
+    return url.hostname;
+  } catch {
+    return "";
+  }
+}
+
+export function isLocalRequest(req: IncomingMessage): boolean {
+  const address = req.socket.remoteAddress;
+  return (address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1")
+    && LOOPBACK_HOSTS.has(requestHostname(req))
+    && !req.headers["x-pi-web-proxy-secret"];
+}
+
+export class WebAccess {
+  lan: boolean;
+  private credentials?: WebCredentials;
+  private readonly proxy?: WebProxyConfig;
+
+  constructor(lan: boolean, credentials?: WebCredentials, proxy?: WebProxyConfig) {
+    this.lan = lan;
+    this.credentials = credentials;
+    this.proxy = proxy;
+  }
+
+  static async load(lan: boolean, path: string, proxy?: WebProxyConfig): Promise<WebAccess> {
+    const credentials = await loadJsonWithLegacyMigration({ stateFile: path, validate: validCredentials });
+    return new WebAccess(lan, credentials, proxy);
+  }
+
+  get remoteEnabled(): boolean {
+    return this.lan || Boolean(this.proxy);
+  }
+
+  private isProxyRequest(req: IncomingMessage): boolean {
+    return Boolean(this.proxy
+      && req.headers.host?.toLowerCase() === new URL(this.proxy.origin).host
+      && equalSecret(req.headers["x-pi-web-proxy-secret"], this.proxy.secret));
+  }
+
+  get passwordConfigured(): boolean {
+    return Boolean(this.credentials);
+  }
+
+  async setPassword(password: unknown, path: string): Promise<void> {
+    if (typeof password !== "string" || !password.trim() || password.length > 256) {
+      throw new Error("请输入 1–256 个字符的密码");
+    }
+    const salt = randomBytes(16).toString("hex");
+    const passwordHash = (await derivePassword(password, salt, 64) as Buffer).toString("hex");
+    const credentials = { salt, passwordHash, sessionKey: randomBytes(32).toString("hex") };
+    await writeJsonAtomically(path, credentials);
+    this.credentials = credentials;
+  }
+
+  trusted(req: IncomingMessage): boolean {
+    const hostname = requestHostname(req);
+    const proxied = this.isProxyRequest(req);
+    if (req.headers["x-pi-web-proxy-secret"] && !proxied) return false;
+    if (!proxied && !LOOPBACK_HOSTS.has(hostname) && !(this.lan && lanAddresses().includes(hostname))) return false;
+    if (req.headers["sec-fetch-site"] === "cross-site") return false;
+    if (req.headers.origin) {
+      try {
+        const expected = proxied ? this.proxy!.origin : new URL(`http://${req.headers.host}`).origin;
+        if (new URL(req.headers.origin).origin !== expected) return false;
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  async acceptsPassword(value: unknown): Promise<boolean> {
+    const credentials = this.credentials;
+    if (!credentials || typeof value !== "string" || value.length > 256) return false;
+    const candidate = await derivePassword(value, credentials.salt, 64) as Buffer;
+    return credentials === this.credentials && timingSafeEqual(candidate, Buffer.from(credentials.passwordHash, "hex"));
+  }
+
+  private signature(expires: string): string {
+    return createHmac("sha256", Buffer.from(this.credentials!.sessionKey, "hex")).update(expires).digest("hex");
+  }
+
+  private acceptsCookie(value: string): boolean {
+    if (!this.credentials) return false;
+    const match = /^(\d+)\.([a-f0-9]{64})$/.exec(value);
+    if (!match || Number(match[1]) <= Math.floor(Date.now() / 1000)) return false;
+    return timingSafeEqual(Buffer.from(match[2], "hex"), Buffer.from(this.signature(match[1]), "hex"));
+  }
+
+  cookieName(req: IncomingMessage): string {
+    return `pi_web_access_${req.socket.localPort}`;
+  }
+
+  authorized(req: IncomingMessage): boolean {
+    if (isLocalRequest(req)) return true;
+    if (!this.remoteEnabled) return false;
+    const prefix = `${this.cookieName(req)}=`;
+    return (req.headers.cookie ?? "").split(";").some((part) => {
+      const cookie = part.trim();
+      return cookie.startsWith(prefix) && this.acceptsCookie(cookie.slice(prefix.length));
+    });
+  }
+
+  cookie(req: IncomingMessage): string {
+    const expires = String(Math.floor(Date.now() / 1000) + LOGIN_SECONDS);
+    const secure = this.isProxyRequest(req) ? "; Secure" : "";
+    return `${this.cookieName(req)}=${expires}.${this.signature(expires)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${LOGIN_SECONDS}${secure}`;
+  }
+
+  urls(port: number): string[] {
+    if (this.proxy) return [`${this.proxy.origin}/`];
+    const address = this.lan ? phoneLanAddress() : undefined;
+    return address ? [`http://${address}:${port}/`] : [];
+  }
+}

package/network-settings.ts

@@ -0,0 +1,146 @@
+import { randomBytes } from "node:crypto";
+import { access, chmod, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { loadJsonWithLegacyMigration, writeJsonAtomically } from "./state-store.ts";
+import type { WebProxyConfig } from "./network-access.ts";
+
+export type NetworkMode = "local" | "lan" | "relay";
+
+export interface RelaySettings {
+  serverAddr: string;
+  serverPort: number;
+  token: string;
+  proxyName: string;
+  secretKey: string;
+  origin: string;
+  proxySecret: string;
+  frpcPath: string;
+  visitorPort: number;
+}
+
+export interface NetworkSettings {
+  mode: NetworkMode;
+  relay?: RelaySettings;
+}
+
+function text(value: unknown, label: string, max = 1024): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error(`${label}不能为空，且不能包含换行或控制字符`);
+  }
+  return value;
+}
+
+function port(value: unknown, label: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 65535) throw new Error(`${label}必须是 1–65535 之间的整数`);
+  return value;
+}
+
+function validateRelay(value: RelaySettings): RelaySettings {
+  text(value.serverAddr, "服务器地址", 253);
+  if (!/^[a-zA-Z0-9.-]+$/.test(value.serverAddr)) throw new Error("服务器地址应填写域名或 IPv4，不包含协议和端口");
+  port(value.serverPort, "frps 端口");
+  port(value.visitorPort, "服务器内部端口");
+  text(value.token, "frps 认证密钥");
+  text(value.frpcPath, "frpc 路径");
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(value.proxyName)) throw new Error("隧道名称只能包含英文字母、数字、下划线和短横线");
+  for (const key of [value.secretKey, value.proxySecret]) {
+    if (typeof key !== "string" || !/^[a-zA-Z0-9_-]{32,256}$/.test(key)) throw new Error("中转密钥必须包含 32–256 个字母、数字、下划线或短横线");
+  }
+  let url: URL;
+  try { url = new URL(value.origin); } catch { throw new Error("手机访问地址应填写 HTTPS 域名，例如 https://web.example.com"); }
+  if (url.protocol !== "https:" || url.origin !== value.origin || !/^[a-zA-Z0-9.-]+$/.test(url.hostname)) {
+    throw new Error("手机访问地址必须是 HTTPS 根地址，不包含路径、查询参数或用户名");
+  }
+  return value;
+}
+
+export function updateNetworkSettings(input: unknown, current: NetworkSettings = { mode: "local" }): NetworkSettings {
+  if (!input || typeof input !== "object") throw new Error("网络配置格式不正确");
+  const data = input as Record<string, unknown>;
+  if (!["local", "lan", "relay"].includes(data.mode as string)) throw new Error("请选择仅本机、局域网或服务器中转");
+  const mode = data.mode as NetworkMode;
+  if (data.relay === undefined) {
+    if (mode === "relay" && !current.relay) throw new Error("请先在设置中填写服务器中转配置");
+    return { mode, ...(current.relay ? { relay: current.relay } : {}) };
+  }
+  if (!data.relay || typeof data.relay !== "object") throw new Error("服务器中转配置格式不正确");
+  const incoming = data.relay as Record<string, unknown>;
+  const previous = current.relay;
+  const relay = validateRelay({
+    serverAddr: incoming.serverAddr as string,
+    serverPort: incoming.serverPort as number,
+    token: (incoming.token || previous?.token) as string,
+    proxyName: (incoming.proxyName ?? previous?.proxyName ?? `pi-web-${randomBytes(4).toString("hex")}`) as string,
+    secretKey: (incoming.secretKey ?? previous?.secretKey ?? randomBytes(32).toString("hex")) as string,
+    origin: incoming.origin as string,
+    proxySecret: (incoming.proxySecret ?? previous?.proxySecret ?? randomBytes(32).toString("hex")) as string,
+    frpcPath: (incoming.frpcPath || "frpc") as string,
+    visitorPort: (incoming.visitorPort ?? 13000) as number,
+  });
+  return { mode, relay };
+}
+
+export async function loadNetworkSettings(path: string): Promise<NetworkSettings> {
+  return await loadJsonWithLegacyMigration({ stateFile: path, validate: (value): value is NetworkSettings => {
+    try {
+      const data = value as NetworkSettings;
+      if (!data || !["local", "lan", "relay"].includes(data.mode)) return false;
+      if (data.relay) validateRelay(data.relay);
+      return data.mode !== "relay" || Boolean(data.relay);
+    } catch { return false; }
+  } }) ?? { mode: "local" };
+}
+
+export async function saveNetworkSettings(path: string, settings: NetworkSettings): Promise<void> {
+  await writeJsonAtomically(path, settings);
+  await chmod(path, 0o600);
+}
+
+export function publicNetworkSettings(settings: NetworkSettings) {
+  const relay = settings.relay;
+  return {
+    mode: settings.mode,
+    ...(relay ? { relay: {
+      serverAddr: relay.serverAddr, serverPort: relay.serverPort, proxyName: relay.proxyName,
+      origin: relay.origin, frpcPath: relay.frpcPath, visitorPort: relay.visitorPort, tokenConfigured: Boolean(relay.token),
+    } } : {}),
+  };
+}
+
+export function proxyForNetwork(settings: NetworkSettings): WebProxyConfig | undefined {
+  return settings.mode === "relay" && settings.relay ? { origin: settings.relay.origin, secret: settings.relay.proxySecret } : undefined;
+}
+
+export async function resolveFrpc(executable: string, configDir: string): Promise<string> {
+  const candidates = isAbsolute(executable) || /[\\/]/.test(executable)
+    ? [resolve(configDir, executable)]
+    : (process.env.PATH ?? "").split(delimiter).filter(Boolean).map((directory) => join(directory.replace(/^"|"$/g, ""), process.platform === "win32" && !executable.toLowerCase().endsWith(".exe") ? `${executable}.exe` : executable));
+  for (const candidate of candidates) {
+    try {
+      if (!(await stat(candidate)).isFile()) continue;
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch { /* Try the next PATH directory. */ }
+  }
+  throw new Error("未找到 frpc。请下载原生 frpc，并在服务器中转设置中填写 frpc.exe 路径，或将其加入 PATH。");
+}
+
+function frpCommon(relay: RelaySettings, serverAddr: string): string {
+  return `serverAddr = ${JSON.stringify(serverAddr)}\nserverPort = ${relay.serverPort}\nauth.method = "token"\nauth.token = ${JSON.stringify(relay.token)}\ntransport.tls.enable = true\nloginFailExit = false\nlog.to = "console"\nlog.disablePrintColor = true\n`;
+}
+
+export function frpcConfig(relay: RelaySettings, localPort: number): string {
+  return `${frpCommon(relay, relay.serverAddr)}\n[[proxies]]\nname = ${JSON.stringify(relay.proxyName)}\ntype = "stcp"\nsecretKey = ${JSON.stringify(relay.secretKey)}\nlocalIP = "127.0.0.1"\nlocalPort = ${port(localPort, "本机端口")}\n`;
+}
+
+export function relayServerFiles(relay: RelaySettings): Record<string, string> {
+  const url = new URL(relay.origin);
+  const zone = `pi_web_${relay.proxyName.replaceAll("-", "_")}`;
+  const proxyHeaders = `    proxy_http_version 1.1;\n    proxy_set_header Host ${url.host};\n    proxy_set_header X-Pi-Web-Proxy-Secret "${relay.proxySecret}";\n    proxy_set_header X-Forwarded-Proto https;\n    proxy_set_header Connection "";\n    proxy_buffering off;\n    proxy_request_buffering off;\n    proxy_read_timeout 3600s;\n    proxy_send_timeout 3600s;`;
+  return {
+    "frps.toml": `bindPort = ${relay.serverPort}\nauth.method = "token"\nauth.token = ${JSON.stringify(relay.token)}\ntransport.tls.force = true\n`,
+    "visitor.toml": `${frpCommon(relay, "127.0.0.1")}\n[[visitors]]\nname = ${JSON.stringify(`${relay.proxyName}-visitor`)}\ntype = "stcp"\nserverName = ${JSON.stringify(relay.proxyName)}\nsecretKey = ${JSON.stringify(relay.secretKey)}\nbindAddr = "127.0.0.1"\nbindPort = ${relay.visitorPort}\n`,
+    "nginx.conf": `limit_req_zone $binary_remote_addr zone=${zone}:10m rate=10r/m;\n\nserver {\n    listen 80;\n    server_name ${url.hostname};\n    return 301 ${relay.origin}$request_uri;\n}\n\nserver {\n    listen ${url.port || 443} ssl;\n    server_name ${url.hostname};\n    ssl_certificate /etc/nginx/ssl/pi-web.pem;\n    ssl_certificate_key /etc/nginx/ssl/pi-web.key;\n    client_max_body_size 21m;\n${proxyHeaders}\n\n    location = /api/auth {\n        limit_req zone=${zone} burst=10 nodelay;\n        limit_req_status 429;\n        proxy_pass http://127.0.0.1:${relay.visitorPort};\n    }\n    location / {\n        proxy_pass http://127.0.0.1:${relay.visitorPort};\n    }\n}\n`,
+  };
+}