@oversk7/pi-web-dsh-style 0.1.0-alpha.1 → 1.0.1

package/README.md

@@ -2,14 +2,14 @@
 
 采用 DeepSeek Harness（DSH）视觉风格、面向 Windows 的非官方 Pi Coding Agent 本地浏览器界面扩展。后端使用 Pi 的公开 RPC 模式，每个会话对应独立的 RPC 进程；历史会话可直接从 Pi 会话文件恢复和渲染。
 
-> 当前版本为 alpha，仅承诺 Windows 10/11。服务只监听 `127.0.0.1`，不应通过端口转发或反向代理暴露到局域网或公网。
+> 仅承诺 Windows 10/11。首次启动只监听 `127.0.0.1`；电脑网页的“设置 → 手机访问”可配置仅本机、局域网和服务器中转。之后 `pi --web` 使用已保存的模式。
 
 ## 安装
 
-需要 Node.js 22.19 或更高版本，以及 Pi Coding Agent 0.84.4 或更高版本。
+需要 Node.js 22.19 或更高版本，以及 Pi Coding Agent 0.85.0 或更高版本。
 
 ```powershell
-pi install npm:@oversk7/pi-web-dsh-style@alpha
+pi install npm:@oversk7/pi-web-dsh-style
 ```
 
 也可以从源码目录安装：
@@ -34,21 +34,62 @@ 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 需要保持运行且未休眠。
+
 ## 功能
 
 - 多工作区、多会话和后台会话并行运行。
 - 按需启动 Pi RPC 进程，最多保留一个空闲进程。
+- Windows 会话使用 Job Object 托管进程树：停止 Web 或宿主退出时，清理 RPC 及其启动的后台服务、子进程和孙进程。
 - 模型、思考等级、中断、压缩和扩展交互对话框。
 - 运行中逐条显示待处理消息，可单条撤回并重新编辑；`Alt+Q` 可将全部队列消息恢复到输入框。
-- 会话历史、分支树、对话回溯及 `pi-rewind` 文件恢复。
-- Windows 系统剪贴板图片和文本粘贴。
+- 会话历史保留完整分支与检查点，支持回溯后返回切换前的位置，以及 `pi-rewind` 文件恢复。
+- Windows 系统剪贴板图片和文本粘贴；手机支持选择或粘贴本机图片。
 - 会话中的本地文件链接可在右侧分栏预览，支持语法高亮、行定位和拖拽调整宽度。
 - 设置面板内更新扩展并热重载 Pi 运行时，无需退出 Web UI。
 - 会话 HTML 导出。
 
+## 进程生命周期
+
+`/web --stop`、宿主 Pi 退出或运行时重载会关闭扩展托管的 frpc 和 Web 会话进程及其后代，包括 detached 后台进程；即使宿主被强制结束，Windows 托管进程也会检测到宿主退出并清理整棵进程树。不会扫描或结束工作区外独立启动的进程，也不会结束其他 Pi 实例。
+
+单个 RPC 进程退出、异常终止或被空闲进程回收时，它启动的后台进程也会一起结束。需要独立于会话长期运行的服务，应从 Web 会话之外的终端启动。通过系统服务管理器、计划任务等外部机制启动的进程不属于此进程树。
+
+只关闭浏览器标签页不会停止 Web 服务或后台会话；要结束它们，请执行 `/web --stop` 或退出宿主 Pi。进程托管依赖 Windows 10/11 自带的 Windows PowerShell 和 Win32 Job Object；如果无法建立托管，RPC 启动会失败，不会回退为无托管进程。
+
 ## 数据与升级
 
 运行状态保存在：
@@ -57,6 +98,10 @@ pi --web
 ~/.pi/agent/pi-web/state.json
 ```
 
+访问密码的加盐哈希和登录签名密钥保存在同一目录的 `auth.json` 中，不保存明文密码。
+
+访问模式及中转配置保存在同一目录的 `network.json` 中。中转所需的 frps 认证密钥、STCP 私有密钥和代理密钥保存在此文件；普通设置响应不返回这些密钥，服务器配置下载会包含部署所需的密钥。配置文件不属于发布包。运行时的 frpc 配置写入状态目录下的 `runtime/`，正常停止时清理。
+
 从旧版目录安装首次升级时，如果新位置尚无状态文件，扩展会从扩展目录中的旧 `state.json` 原样复制并继续使用。旧文件不会被删除或改写，可作为迁移备份。
 
 可用环境变量：
@@ -78,11 +123,11 @@ npm run verify
 npm pack --dry-run
 ```
 
-发布 alpha：
+发布正式版：
 
 ```powershell
 npm login --registry=https://registry.npmjs.org
-npm publish --access public --tag alpha
+npm publish --access public --tag latest
 ```
 
 ## 许可证

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");
@@ -128,9 +139,10 @@ export default function (pi: ExtensionAPI) {
       const targetId = args.trim();
       if (!targetId || !ctx.sessionManager.getEntry(targetId)) throw new Error("会话树节点不存在");
       await ctx.waitForIdle();
+      const fromId = ctx.sessionManager.getLeafId();
       const result = await ctx.navigateTree(targetId, { summarize: false });
       if (result.cancelled) throw new Error("会话回溯已取消");
-      pi.appendEntry("pi-web-tree-navigation", { targetId });
+      pi.appendEntry("pi-web-tree-navigation", { targetId, fromId });
     },
   });
 
@@ -140,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}/`] : [];
+  }
+}