oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/uploads/upload-store.js

@@ -0,0 +1,115 @@
+/**
+ * 附件上传的存储（ADR-0020 §P3）。
+ *
+ * 三条硬约束（都来自既有 ADR）：
+ *   1. **图片不塞 WS**（ADR-0004 单条 ≤64KB）：走 HTTP 上传，消息里只带引用 id；
+ *   2. **id 必须防目录穿越**（ADR-0006 的精神）：只接受 `[a-z0-9-]`，其余一律拒；
+ *   3. **有清理**：上传目录不能无限长大 → 按时间清理旧文件（每次上传时顺手跑）。
+ *
+ * 不做的事：非图片文件的内容注入（ADR-0002 的原则：只给路径引用）。
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+export const UPLOADS_DIR = "uploads";
+/** 单文件上限（与 ADR-0020 §P3 一致） */
+export const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+/** 单条消息附件上限 */
+export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+/** 上传文件保留期（默认 7 天） */
+export const DEFAULT_UPLOAD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const ID_RE = /^[a-z0-9-]{8,64}$/;
+export function uploadsDir(dataDir) {
+    return join(dataDir, UPLOADS_DIR);
+}
+/** 纯函数：id 是否安全（防 `../` 与绝对路径） */
+export function isSafeUploadId(id) {
+    return ID_RE.test(id);
+}
+/** 纯函数：按魔术字节嗅探类型（不信任客户端给的 content-type） */
+export function sniffMime(bytes) {
+    const head = bytes.subarray(0, 12);
+    const isPng = head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47;
+    if (isPng)
+        return "image/png";
+    const isJpeg = head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff;
+    if (isJpeg)
+        return "image/jpeg";
+    const isGif = head[0] === 0x47 && head[1] === 0x49 && head[2] === 0x46;
+    if (isGif)
+        return "image/gif";
+    const isWebp = head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46 && head[8] === 0x57;
+    if (isWebp)
+        return "image/webp";
+    return null;
+}
+export function isImageMime(mime) {
+    return mime.startsWith("image/");
+}
+export function createUploadStore(options) {
+    const now = options.now ?? (() => Date.now());
+    const ttlMs = options.ttlMs ?? DEFAULT_UPLOAD_TTL_MS;
+    return {
+        /** 保存一个上传；超限抛错（调用方转成 4xx） */
+        async save(input) {
+            if (input.bytes.byteLength === 0)
+                throw new Error("空文件");
+            if (input.bytes.byteLength > MAX_UPLOAD_BYTES) {
+                throw new Error(`文件超过上限（${Math.round(MAX_UPLOAD_BYTES / 1024 / 1024)}MB）`);
+            }
+            const id = randomUUID().replace(/-/g, "").slice(0, 16);
+            const mime = sniffMime(input.bytes) ?? (input.declaredMime || "application/octet-stream");
+            const dir = uploadsDir(options.dataDir);
+            await mkdir(dir, { recursive: true });
+            const path = join(dir, id);
+            await writeFile(path, input.bytes);
+            // 顺手清理旧文件（不做后台任务，省一个定时器）
+            await this.cleanup();
+            return {
+                id,
+                path,
+                bytes: input.bytes.byteLength,
+                mime,
+                name: (input.name ?? "附件").slice(0, 200),
+            };
+        },
+        /** 读回一个上传（校验 id 安全 + 文件存在） */
+        async read(id) {
+            if (!isSafeUploadId(id))
+                return null;
+            try {
+                const bytes = await readFile(join(uploadsDir(options.dataDir), id));
+                return { bytes, mime: sniffMime(bytes) ?? "application/octet-stream" };
+            }
+            catch {
+                return null;
+            }
+        },
+        /** 清理超过保留期的上传（返回删掉的数量） */
+        async cleanup() {
+            const dir = uploadsDir(options.dataDir);
+            let names;
+            try {
+                names = await readdir(dir);
+            }
+            catch {
+                return 0;
+            }
+            const deadline = now() - ttlMs;
+            let removed = 0;
+            for (const name of names) {
+                try {
+                    const info = await stat(join(dir, name));
+                    if (info.mtimeMs < deadline) {
+                        await rm(join(dir, name), { force: true });
+                        removed += 1;
+                    }
+                }
+                catch {
+                    // 单个文件的问题不影响其他清理
+                }
+            }
+            return removed;
+        },
+    };
+}

package/dist/server/util/data-dir.js

@@ -0,0 +1,36 @@
+/**
+ * 数据目录的**一次性搬家**：`~/.agent-web` → `~/.oh-my-agent-web`。
+ *
+ * 为什么要在启动时做、而不是让用户手动 mv：
+ *   那个目录里放的全是「丢了就麻烦」的东西 —— 远程访问密码、允许的域名、审批规则、
+ *   推送订阅、客户端设置、会话索引与日志。改个名字就让远程访问变 403 / 推送失效，
+ *   属于「程序自己惹的祸」。
+ *
+ * 三条边界：
+ *   1. 只在**用的是默认目录**时搬（用户显式 `--data-dir` 就绝不动别人的文件）；
+ *   2. 只在**新目录还不存在**时搬（已经搬过 / 新目录已有数据就什么都不做）；
+ *   3. 整个目录 rename（同一分区，原子），失败就打印一句该怎么办，不阻断启动。
+ */
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { DEFAULT_DATA_DIR_NAME, LEGACY_DATA_DIR_NAME } from "./env.js";
+export function migrateLegacyDataDir(options) {
+    const home = options.home ?? homedir();
+    const target = resolve(options.dataDir);
+    if (target !== resolve(join(home, DEFAULT_DATA_DIR_NAME)))
+        return false; // 自定义目录：不碰
+    const legacy = join(home, LEGACY_DATA_DIR_NAME);
+    if (!existsSync(legacy) || existsSync(target))
+        return false;
+    try {
+        renameSync(legacy, target);
+        options.log(`已把数据目录从 ${legacy} 迁移到 ${target}（密码 / 推送订阅 / 设置 / 会话索引都在里面）`);
+        return true;
+    }
+    catch (error) {
+        options.log(`旧数据目录 ${legacy} 迁移失败：${error instanceof Error ? error.message : String(error)}` +
+            `\n  → 手动搬一次即可：mv ${legacy} ${target}`);
+        return false;
+    }
+}

package/dist/server/util/env.js

@@ -0,0 +1,140 @@
+/**
+ * 配置与环境变量（ADR-0007 §环境变量、ADR-0011 命名）。
+ *
+ * 四个环境变量，仅此四个：
+ *   AGENT_WEB_PORT       默认 25257
+ *   AGENT_WEB_CWD        默认 process.cwd()
+ *   AGENT_WEB_DATA_DIR   默认 ~/.oh-my-agent-web
+ *   AGENT_WEB_HOST       默认 127.0.0.1（对外监听需要它）
+ *   AGENT_WEB_PASSWORD   远程访问密码（不设 = 只允许本机）
+ *   AGENT_WEB_ALLOWED_HOSTS  额外允许的域名（逗号分隔，默认只认 loopback）
+ *   AGENT_WEB_TOKEN      占位：v1 不实现鉴权（ADR-0006），只留开关位
+ * 外加一个日志级别：AGENT_WEB_LOG（debug|info|warn|error，默认 info）
+ *
+ * 监听地址默认 127.0.0.1；改成别的地址也**不会**让远程随便进 ——
+ * 没有 AGENT_WEB_PASSWORD 时，非本机请求一律 403（ADR-0031）。
+ *
+ * 本模块全是纯函数：不读 process.env、不碰文件系统 —— 便于单测与守卫复用。
+ */
+import { join, resolve, sep } from "node:path";
+export const DEFAULT_PORT = 25257;
+/** 默认只听本机；要对外提供访问得显式改它 + 设密码（ADR-0031） */
+export const DEFAULT_HOST = "127.0.0.1";
+export const HOST_ENV = "AGENT_WEB_HOST";
+export const PASSWORD_ENV = "AGENT_WEB_PASSWORD";
+/** 额外允许的主机名（逗号分隔）：用自己的域名 / 局域网 IP 访问时配它 */
+export const ALLOWED_HOSTS_ENV = "AGENT_WEB_ALLOWED_HOSTS";
+/** 回合看门狗默认超时：20 分钟（与参考实现同口径） */
+export const DEFAULT_TURN_TIMEOUT_MS = 20 * 60 * 1000;
+export const DEFAULT_DATA_DIR_NAME = ".oh-my-agent-web";
+/**
+ * 旧的数据目录名（改名前的）。
+ *
+ * 里面装的是**这台机器的私有配置**：远程访问密码、允许的域名、审批规则、推送订阅、
+ * 客户端设置、日志和锁。改名不能让这些凭空消失，所以启动时会**自动搬家**
+ * （见 `server/util/data-dir.ts`），搬完旧目录就不存在了。
+ */
+export const LEGACY_DATA_DIR_NAME = ".agent-web";
+export const DATA_DIR_ENV = "AGENT_WEB_DATA_DIR";
+/** ADR-0011：绝不与参考实现（~/.pi-web）共用数据目录 —— 否则两边会互相覆盖会话与配置 */
+export const FOREIGN_DATA_DIR_NAMES = [".pi-web", ".pi"];
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+export function readConfig(env, options) {
+    const problems = [];
+    let port = DEFAULT_PORT;
+    const rawPort = env.AGENT_WEB_PORT;
+    if (rawPort !== undefined && rawPort !== "") {
+        const parsed = Number.parseInt(rawPort, 10);
+        if (Number.isInteger(parsed) && parsed > 0 && parsed < 65536)
+            port = parsed;
+        else
+            problems.push(`AGENT_WEB_PORT 不是合法端口：${rawPort}（回落到 ${DEFAULT_PORT}）`);
+    }
+    let logLevel = "info";
+    const rawLevel = env.AGENT_WEB_LOG;
+    if (rawLevel !== undefined && rawLevel !== "") {
+        if (LOG_LEVELS.includes(rawLevel))
+            logLevel = rawLevel;
+        else
+            problems.push(`AGENT_WEB_LOG 不是合法级别：${rawLevel}（回落到 info）`);
+    }
+    let turnTimeoutMs = DEFAULT_TURN_TIMEOUT_MS;
+    const rawTimeout = env.AGENT_WEB_TURN_TIMEOUT_MS;
+    if (rawTimeout !== undefined && rawTimeout !== "") {
+        const parsedTimeout = Number.parseInt(rawTimeout, 10);
+        if (Number.isInteger(parsedTimeout) && parsedTimeout >= 0)
+            turnTimeoutMs = parsedTimeout;
+        else
+            problems.push(`AGENT_WEB_TURN_TIMEOUT_MS 不是合法毫秒数：${rawTimeout}（回落到默认）`);
+    }
+    let engine = "pi";
+    const rawEngine = env.AGENT_WEB_ENGINE;
+    if (rawEngine !== undefined && rawEngine !== "") {
+        // 只做形状归一化；**是不是注册过的引擎**由注册表判断（ADR-0024）：
+        // 未注册的名字在那里回落 pi 并告警 —— 这样加引擎不用改这里
+        engine = rawEngine.trim().toLowerCase();
+    }
+    let host = DEFAULT_HOST;
+    const rawHost = env[`${HOST_ENV}`];
+    if (rawHost !== undefined && rawHost !== "")
+        host = rawHost.trim();
+    const password = env[`${PASSWORD_ENV}`] && env[`${PASSWORD_ENV}`] !== "" ? String(env[`${PASSWORD_ENV}`]) : null;
+    const allowedHosts = (env[ALLOWED_HOSTS_ENV] ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item !== "");
+    return {
+        config: {
+            port,
+            host,
+            workspace: env.AGENT_WEB_CWD && env.AGENT_WEB_CWD !== "" ? resolve(env.AGENT_WEB_CWD) : resolve(options.cwd),
+            dataDir: env[DATA_DIR_ENV] && env[DATA_DIR_ENV] !== ""
+                ? resolve(env[DATA_DIR_ENV])
+                : join(options.home, DEFAULT_DATA_DIR_NAME),
+            logLevel,
+            engine,
+            turnTimeoutMs,
+            token: env.AGENT_WEB_TOKEN && env.AGENT_WEB_TOKEN !== "" ? env.AGENT_WEB_TOKEN : null,
+            codexBin: env.AGENT_WEB_CODEX_BIN?.trim() || "codex",
+            codexHome: env.AGENT_WEB_CODEX_HOME?.trim() || null,
+            dshBin: env.AGENT_WEB_DSH_BIN?.trim() || "dsh",
+            dshHome: env.AGENT_WEB_DSH_HOME?.trim() || null,
+            dshModel: env.AGENT_WEB_DSH_MODEL?.trim() || null,
+            dshPatches: (env.AGENT_WEB_DSH_PATCH ?? "")
+                .split(":")
+                .map((item) => item.trim())
+                .filter((item) => item !== ""),
+            password,
+            allowedHosts,
+        },
+        problems,
+    };
+}
+/** 去掉尾部分隔符（保留根目录 `/`），便于比较 */
+export function normalizeDir(path) {
+    const resolved = resolve(path);
+    if (resolved === sep)
+        return sep;
+    return resolved.endsWith(sep) ? resolved.slice(0, -1) : resolved;
+}
+/** ADR-0006：工作区根不得是家目录，也不得是文件系统根 */
+export function isForbiddenWorkspaceRoot(workspace, home) {
+    const normalized = normalizeDir(workspace);
+    return normalized === normalizeDir(home) || normalized === normalizeDir(sep);
+}
+/** ADR-0011：数据目录不得是参考实现的目录 */
+export function isForeignDataDir(dataDir) {
+    const base = normalizeDir(dataDir).split(sep).pop() ?? "";
+    return FOREIGN_DATA_DIR_NAMES.includes(base);
+}
+/** 结构性校验：与 env 值是否合法无关，属「这个配置能不能安全地跑起来」 */
+export function validateConfig(config, options) {
+    const problems = [];
+    if (isForbiddenWorkspaceRoot(config.workspace, options.home)) {
+        problems.push(`工作区根不能是家目录或文件系统根：${config.workspace}（ADR-0006）`);
+    }
+    if (isForeignDataDir(config.dataDir)) {
+        problems.push(`数据目录不能与参考实现共用：${config.dataDir}（ADR-0011，会互相覆盖会话）`);
+    }
+    return problems;
+}

package/dist/server/util/ids.js

@@ -0,0 +1,28 @@
+/**
+ * id 生成（ADR-0019）。
+ *
+ * 为什么不用进程内自增计数器（曾经的做法，踩过）：**会话是跨进程持久的，而计数器不是**。
+ * 重启后计数器从 1 重新开始 → 生成出磁盘上已存在的 `conv-1` → 两条会话被写进同一个
+ * JSONL（连 meta 行都追加了两次）、消息 id 也重复 → 前端的「按 id 找到那条消息」全部错位。
+ *
+ * 规则：id 必须**全局唯一**，且不依赖进程状态。
+ */
+import { randomUUID } from "node:crypto";
+/** 短 id：10 个十六进制字符（≈40 bit），单机自用场景足够 */
+export function shortId() {
+    return randomUUID().replace(/-/g, "").slice(0, 10);
+}
+/** 带前缀的 id 工厂：`msg-…`、`appr-…`、`notice-…`（会话不用它，见下面的 conversationId） */
+export function makeIdFactory() {
+    return (prefix) => `${prefix}-${shortId()}`;
+}
+/**
+ * 会话 id：直接给 UUID，和 pi CLI 自己建会话时一模一样（`01a13d8d-a916-70b8-…`）。
+ *
+ * 为什么单独一个函数而不是 `makeIdFactory()("conv")`：会话 id 会**进入 pi 的会话文件名**
+ * 和地址栏的 `?session=`，跟 pi 生成的会话用同一种格式，才不用去猜「这个 id 是谁建的」；
+ * 另外 122 bit 随机比短 id 的 40 bit 更抗撞（会话是要长期保存的）。
+ */
+export function conversationId() {
+    return randomUUID();
+}

package/dist/server/util/log-file.js

@@ -0,0 +1,67 @@
+/**
+ * 日志落文件 + 按大小轮转（ADR-0013 §B）。
+ *
+ * 为什么需要文件：前台运行时 stdout 会随终端关闭而消失，而排障需要的是**崩溃前**那几行。
+ * 为什么不引日志库：这层总共 60 行，而且行为要精确可控（ADR-0008 的依赖预算也不允许）。
+ *
+ * 轮转：`agent-web.log` 超过上限 → 依次改名 `agent-web.log.1` / `.2` / …，最多保留 keep 个，
+ * 最老的被丢弃。同步写（日志量小，换来的是「崩溃时最后一行也落地」）。
+ */
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+export const DEFAULT_KEEP = 3;
+/** 纯函数：决定要保留哪些归档（把最老的挤掉） */
+export function archivePlan(keep) {
+    return Array.from({ length: Math.max(0, keep) }, (_, index) => index + 1);
+}
+export function createRotatingFileSink(options) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const keep = options.keep ?? DEFAULT_KEEP;
+    let size = 0;
+    try {
+        mkdirSync(dirname(options.file), { recursive: true });
+        if (existsSync(options.file))
+            size = statSync(options.file).size;
+    }
+    catch (error) {
+        options.onError?.(`准备日志文件失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    function rotate() {
+        try {
+            // 最老的先删：log.<keep> 没了，然后从 keep-1 往上挪
+            const archives = archivePlan(keep);
+            rmSync(`${options.file}.${archives[archives.length - 1]}`, { force: true });
+            for (let index = archives.length - 1; index > 0; index -= 1) {
+                const from = `${options.file}.${index}`;
+                if (!existsSync(from))
+                    continue;
+                renameSync(from, `${options.file}.${index + 1}`);
+            }
+            if (existsSync(options.file))
+                renameSync(options.file, `${options.file}.1`);
+            size = 0;
+        }
+        catch (error) {
+            options.onError?.(`日志轮转失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        write(line) {
+            try {
+                const payload = `${line}\n`;
+                if (size + Buffer.byteLength(payload, "utf8") > maxBytes)
+                    rotate();
+                appendFileSync(options.file, payload, "utf8");
+                size += Buffer.byteLength(payload, "utf8");
+            }
+            catch (error) {
+                options.onError?.(`写日志失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        size: () => size,
+    };
+}
+export function logFileName(dataDir) {
+    return join(dataDir, "logs", "agent-web.log");
+}

package/dist/server/util/log.js

@@ -0,0 +1,52 @@
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+/** 这些 key 的值一律不写日志（ADR-0013 §脱敏） */
+const SECRET_KEY_RE = /(key|token|secret|password|passwd|credential|authorization|cookie)/i;
+const MAX_VALUE_CHARS = 200;
+function redactValue(key, value) {
+    if (SECRET_KEY_RE.test(key))
+        return "[redacted]";
+    if (typeof value === "string" && value.length > MAX_VALUE_CHARS) {
+        return `${value.slice(0, MAX_VALUE_CHARS)}…[${value.length} 字]`;
+    }
+    if (Array.isArray(value))
+        return value.slice(0, 20).map((item, index) => redactValue(`${key}.${index}`, item));
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            out[childKey] = redactValue(childKey, childValue);
+        }
+        return out;
+    }
+    return value;
+}
+/** 纯函数：把上下文里的敏感值抹掉、把长值截断（可单测） */
+export function redactLogContext(ctx) {
+    const out = {};
+    for (const [key, value] of Object.entries(ctx))
+        out[key] = redactValue(key, value);
+    return out;
+}
+/** 纯函数：把一条日志格式化成单行 JSON（便于单测脱敏与字段形状） */
+export function formatLogLine(entry) {
+    return JSON.stringify(entry.ctx ? entry : { ...entry, ctx: undefined });
+}
+export function createLogger(options) {
+    const now = options.now ?? (() => Date.now());
+    const sink = options.sink ?? ((line) => process.stdout.write(`${line}\n`));
+    const scope = options.scope ?? "app";
+    const threshold = LEVEL_ORDER[options.level];
+    const write = (level, message, ctx) => {
+        if (LEVEL_ORDER[level] < threshold)
+            return;
+        const safeCtx = ctx ? redactLogContext(ctx) : undefined;
+        sink(formatLogLine({ ts: now(), level, scope, msg: message, ...(safeCtx ? { ctx: safeCtx } : {}) }));
+    };
+    return {
+        debug: (message, ctx) => write("debug", message, ctx),
+        info: (message, ctx) => write("info", message, ctx),
+        warn: (message, ctx) => write("warn", message, ctx),
+        error: (message, ctx) => write("error", message, ctx),
+        child: (childScope) => createLogger({ ...options, scope: `${scope}.${childScope}` }),
+    };
+}

package/dist/server/util/origin.js

@@ -0,0 +1,75 @@
+/**
+ * 握手校验（ADR-0006 §握手）—— 本 ADR 的核心条目。
+ *
+ * 为什么必须有：WebSocket **不受同源策略保护**。你浏览器里打开的任意网页都能向
+ * `ws://127.0.0.1:<port>` 发起升级请求；若服务端不校验 Origin，那个网页就能驱动
+ * 你这台机器上的 shell。所以「只绑 loopback」并不够，握手是第一道也是唯一一道门。
+ *
+ * 规则：
+ *   - 无 Origin（非浏览器客户端：测试脚本 / CLI / 健康检查）→ 放行；
+ *   - 有 Origin → 主机名在允许列表（loopback 或 `AGENT_WEB_ALLOWED_HOSTS` 里配的域名）+ 端口匹配；
+ *   - Host 头：如果带了，必须是 loopback 且端口在白名单里（防 DNS rebinding 一类）。
+ *
+ * 全是纯函数，单测直接覆盖。
+ */
+export const LOOPBACK_HOSTNAMES = ["127.0.0.1", "localhost", "::1", "[::1]"];
+export function allowedPorts(policy) {
+    return [policy.port, ...(policy.devPorts ?? [])];
+}
+export function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return LOOPBACK_HOSTNAMES.includes(normalized) || normalized === "::1";
+}
+/** 主机名在白名单里（loopback 或用户显式配置的域名/局域网 IP） */
+export function isAllowedHostname(hostname, policy) {
+    if (isLoopbackHostname(hostname))
+        return true;
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return (policy.extraHosts ?? []).some((item) => item.toLowerCase() === normalized);
+}
+function portMatches(port, policy) {
+    // 缺端口时按默认端口推断：http→80 / https→443，都不可能命中，视为不匹配
+    if (!port)
+        return false;
+    return allowedPorts(policy).includes(Number.parseInt(port, 10));
+}
+/** 校验 `Origin` 请求头 */
+export function isAllowedOrigin(origin, policy) {
+    if (!origin)
+        return true; // 非浏览器客户端
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    if (!isAllowedHostname(url.hostname, policy))
+        return false;
+    // 配置了域名（反向代理场景）时端口可能是 80/443，那两种按名字放行
+    if (isLoopbackHostname(url.hostname) === false && (url.port === "" || url.port === "80" || url.port === "443")) {
+        return true;
+    }
+    return portMatches(url.port, policy);
+}
+/** 校验 `Host` 请求头（缺失时放行；带了就必须是 loopback + 白名单端口） */
+export function isAllowedHost(host, policy) {
+    if (!host)
+        return true;
+    const trimmed = host.trim();
+    const [hostname, port] = trimmed.startsWith("[")
+        ? [trimmed.slice(0, trimmed.indexOf("]") + 1), trimmed.slice(trimmed.indexOf("]") + 2)]
+        : trimmed.split(":");
+    if (!isAllowedHostname(hostname ?? "", policy))
+        return false;
+    if (port === undefined || port === "" || port === "80" || port === "443")
+        return isAllowedHostname(hostname ?? "", policy);
+    return portMatches(port, policy);
+}
+/** 给人类看的错误信息（连不上时能立刻明白原因，而不是干瞪眼） */
+export function describePolicy(policy) {
+    const hosts = [...LOOPBACK_HOSTNAMES, ...(policy.extraHosts ?? [])];
+    return `允许的来源：${hosts.join(" / ")}；端口 ${allowedPorts(policy).join(" / ")}`;
+}

package/dist/server/util/paths.js

@@ -0,0 +1,60 @@
+/**
+ * 路径解析与约束（纯函数）。
+ *
+ * 两个场景用它：
+ *   1. `web/dist` 在哪 —— 源码运行与编译运行的层数不同（M1 踩过）；
+ *   2. 路径是否落在工作区内 —— ADR-0006：`realpath` 之后必须在根内（防 `..` 与 symlink 逃逸）。
+ *
+ * 刻意把 `realpath` 作为参数注入：单测不需要造文件系统，调用方传 `fs.realpathSync`。
+ */
+import { join, relative, resolve, sep } from "node:path";
+export function pickExisting(candidates, exists) {
+    for (const candidate of candidates)
+        if (exists(candidate))
+            return candidate;
+    return null;
+}
+/** web/dist 的候选路径：先是「源码运行」，再是「编译后运行」 */
+export function webDistCandidates(serverDir) {
+    return [join(serverDir, "..", "web", "dist"), join(serverDir, "..", "..", "web", "dist")];
+}
+/**
+ * `candidate` 是否在 `root` 之内。
+ *
+ * 用「相对路径不以 `..` 开头」判断，而不是字符串 `startsWith`：
+ * `/root2` 不是 `/root` 的子路径，但 `startsWith("/root")` 会误判为真。
+ * 传入的路径应当是**已经 realpath 过**的（调用方负责），否则 symlink 能逃出去。
+ */
+export function isPathInside(root, candidate) {
+    const relativePath = relative(resolve(root), resolve(candidate));
+    if (relativePath === "")
+        return true; // 就是根本身
+    return !relativePath.startsWith("..") && !relativePath.startsWith(`..${sep}`) && !isAbsoluteLike(relativePath);
+}
+function isAbsoluteLike(path) {
+    return path.startsWith(sep) || /^[A-Za-z]:[\\/]/.test(path);
+}
+/**
+ * 解析到真实路径并确认在工作区内（ADR-0006）。
+ * `realpath` 失败（路径不存在）时按「不在根内」处理 —— 宁可拒绝，不要放行。
+ */
+export function resolveInsideRoot(root, candidate, realpath) {
+    let realRoot;
+    try {
+        realRoot = realpath(root);
+    }
+    catch {
+        return { ok: false, reason: `工作区根无法解析：${root}` };
+    }
+    let realCandidate;
+    try {
+        realCandidate = realpath(candidate);
+    }
+    catch {
+        return { ok: false, reason: `路径不存在或无法解析：${candidate}` };
+    }
+    if (!isPathInside(realRoot, realCandidate)) {
+        return { ok: false, reason: `路径越界（不在工作区内）：${candidate}` };
+    }
+    return { ok: true, path: realCandidate };
+}