oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/files/files-routes.js

@@ -0,0 +1,182 @@
+/**
+ * 文件浏览的 HTTP 路由（M4）——从 index.ts 抽出（400 行护栏）。
+ *
+ *   `GET /api/files/list?path=<相对路径>` → 列一层目录（懒惰展开）
+ *   `GET /api/files/read?path=<相对路径>` → 只读预览（≤512KB，二进制给标记）
+ *
+ * `workspaceOf()` 返回**当前会话**的工作区（多项目：文件树跟着当前会话走，ADR-0021 §3）。
+ */
+import { createReadStream, realpathSync, statSync } from "node:fs";
+import { listDirectory, parseRange, readPreview, readRaw, resolveMediaFile } from "./file-service.js";
+import { searchFiles } from "./file-search.js";
+import { checkoutBranch, readGitBranches } from "./git-info.js";
+export function registerFileRoutes(app, options) {
+    app.get("/api/files/list", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        // 隐藏文件由界面的「眼睛」按钮显式打开（?hidden=1）
+        const result = await listDirectory(root, relPath, { showHidden: request.query.hidden === "1" });
+        if (!result.ok) {
+            response.status(400).json({ error: { code: "files.list_failed", message: result.error } });
+            return;
+        }
+        response.json(result);
+    });
+    // markdown 图片用：直接回字节（只放行图片/PDF 白名单，仍受工作区约束）
+    app.get("/api/files/raw", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        const result = await readRaw(root, relPath);
+        if (!result.ok) {
+            response.status(result.tooLarge ? 413 : 400).json({ error: { code: "files.raw_failed", message: result.error } });
+            return;
+        }
+        response.setHeader("Content-Type", result.mime);
+        response.setHeader("Cache-Control", "private, max-age=60");
+        response.send(result.bytes);
+    });
+    /**
+     * 视频 / 音频：**流式 + Range**（拖动进度条、边下边播都靠它）。
+     * 只让白名单里的媒体类型通过；大小上限 4GB；路径同样受工作区约束。
+     */
+    app.get("/api/files/media", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        const file = await resolveMediaFile(root, relPath);
+        if (!file.ok) {
+            response.status(file.tooLarge ? 413 : 400).json({ error: { code: "files.media_failed", message: file.error } });
+            return;
+        }
+        const range = parseRange(request.headers.range, file.size);
+        response.setHeader("Content-Type", file.mime);
+        response.setHeader("Accept-Ranges", "bytes");
+        response.setHeader("Cache-Control", "private, max-age=600");
+        if (range) {
+            response.status(206);
+            response.setHeader("Content-Range", `bytes ${range.start}-${range.end}/${file.size}`);
+            response.setHeader("Content-Length", String(range.end - range.start + 1));
+        }
+        else {
+            response.setHeader("Content-Length", String(file.size));
+        }
+        if (request.method === "HEAD") {
+            response.end();
+            return;
+        }
+        createReadStream(file.path, range ? { start: range.start, end: range.end } : undefined)
+            .on("error", () => response.destroy())
+            .pipe(response);
+    });
+    /** 文件名搜索（放大镜）：只匹配名字，不做内容搜索 */
+    app.get("/api/files/search", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        const query = typeof request.query.q === "string" ? request.query.q : "";
+        const result = await searchFiles(root, query);
+        if (!result.ok) {
+            response.status(400).json({ error: { code: "files.search_failed", message: result.error } });
+            return;
+        }
+        response.json(result);
+    });
+    /** 当前项目的 git 信息（分支名 + 本地分支清单；不是仓库就 isRepo=false） */
+    app.get("/api/files/git", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response.json({ isRepo: false, branch: null, branches: [] });
+            return;
+        }
+        response.json(await readGitBranches(root));
+    });
+    /**
+     * 切分支：`{ root, branch, force? }` → `git checkout <branch>`。
+     * 只接受**本地已有分支**；工作区有未提交改动时先 409 回一份改动清单（`files.dirty_worktree`），
+     * 界面确认后带 `force: true` 再发一次。冲突时 git 会拒绝，报错原样回给界面。
+     */
+    app.post("/api/files/git/checkout", async (request, response) => {
+        const body = request.body;
+        const root = rootOf(body?.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        if (typeof body?.branch !== "string" || body.branch.trim() === "") {
+            response.status(400).json({ error: { code: "files.no_branch", message: "没有指定要切换的分支" } });
+            return;
+        }
+        const result = await checkoutBranch(root, body.branch, { force: body.force === true });
+        if (!result.ok) {
+            if (result.dirty) {
+                response.status(409).json({
+                    error: {
+                        code: "files.dirty_worktree",
+                        message: `工作区有 ${result.dirty.total} 个未提交改动`,
+                        files: result.dirty.files,
+                        total: result.dirty.total,
+                    },
+                });
+                return;
+            }
+            response.status(400).json({ error: { code: "files.checkout_failed", message: result.message } });
+            return;
+        }
+        response.json({ ...(await readGitBranches(root)), branch: result.branch });
+    });
+    app.get("/api/files/read", async (request, response) => {
+        const root = rootOf(request.query.root, options.workspaceOf());
+        if (!root) {
+            response
+                .status(409)
+                .json({ error: { code: "files.no_workspace", message: "还没有打开会话（不知道是哪个项目）" } });
+            return;
+        }
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        const result = await readPreview(root, relPath);
+        if (!result.ok) {
+            response.status(400).json({ error: { code: "files.read_failed", message: result.error } });
+            return;
+        }
+        response.json(result);
+    });
+}
+/**
+ * 文件根目录：默认是当前会话的工作区；「在文件中打开」某个项目时传 root 覆盖。
+ * 校验：必须是存在的目录（realpath）。不做工作区包含检查 —— 因为根目录本身就是工作区，
+ * 一旦允许换根，"包含于工作区"就退化成"包含于自己"，没有意义；真正的边界是**只读**。
+ */
+function rootOf(raw, fallback) {
+    if (typeof raw !== "string" || !raw.startsWith("/"))
+        return fallback;
+    try {
+        const real = realpathSync(raw);
+        return statSync(real).isDirectory() ? real : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/server/files/git-info.js

@@ -0,0 +1,186 @@
+/**
+ * 当前项目的 git 分支（文件管理下拉框右边那枚「⎇ main」小标签）。
+ *
+ * 两件事分开做：
+ *   - **读当前分支**：直接读 `.git/HEAD`，不 spawn 进程 —— 只读几十字节，
+ *     也不需要 git 装在某处、不会因为仓库损坏而卡住；
+ *   - **列分支 / 切分支**（下拉菜单）：必须 spawn `git`（refs 可能塞在 packed-refs、
+ *     切分支还要更新工作区），带超时、不带 shell、参数逐个传（注入不了）。
+ * 兼容 `.git` 是**文件**的情况（worktree / submodule 里 `.git` 指向别处）。
+ */
+import { spawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { join, isAbsolute, resolve } from "node:path";
+/** 纯函数：把 HEAD 内容解析成分支名（detached 时返回短 hash） */
+export function parseHead(content) {
+    const text = content.trim();
+    if (text === "")
+        return null;
+    const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(text);
+    if (ref?.[1])
+        return ref[1];
+    // detached HEAD：直接是 40 位 sha，取前 7 位够认
+    return /^[0-9a-f]{7,40}$/i.test(text) ? text.slice(0, 7) : null;
+}
+/** 工作区可能在仓库的子目录里：从 root 往上找 6 层 `.git`，返回**仓库（工作树）根** */
+export async function findRepoRoot(root) {
+    let dir = resolve(root);
+    for (let depth = 0; depth < 6; depth += 1) {
+        try {
+            await stat(join(dir, ".git"));
+            return dir;
+        }
+        catch {
+            const parent = resolve(dir, "..");
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+export async function readGitInfo(root) {
+    const repo = await findRepoRoot(root);
+    if (!repo)
+        return { branch: null, isRepo: false };
+    const gitPath = join(repo, ".git");
+    try {
+        const info = await stat(gitPath);
+        const headPath = info.isDirectory() ? join(gitPath, "HEAD") : await worktreeHead(gitPath);
+        if (!headPath)
+            return { branch: null, isRepo: false };
+        return { branch: parseHead(await readFile(headPath, "utf8")), isRepo: true };
+    }
+    catch {
+        return { branch: null, isRepo: false };
+    }
+}
+/** `.git` 是文件时内容形如 `gitdir: /path/to/repo/.git/worktrees/x` */
+async function worktreeHead(gitFile) {
+    try {
+        const content = (await readFile(gitFile, "utf8")).trim();
+        const match = /^gitdir:\s*(.+)$/.exec(content);
+        if (!match?.[1])
+            return null;
+        const target = isAbsolute(match[1]) ? match[1] : resolve(join(gitFile, ".."), match[1]);
+        return join(target, "HEAD");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 跑一条 git 命令：`git -C <repo> …`，5 秒超时，`LC_ALL=C`（错误信息稳定成英文）。
+ * 不经过 shell —— 分支名即使带 `;` `$()` 也只是普通参数。
+ */
+function runGit(repo, args, timeoutMs = 5000) {
+    return new Promise((done) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            done(result);
+        };
+        const child = spawn("git", ["-C", repo, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish({ ok: false, stdout, stderr: stderr || "git 命令超时（5s）" });
+        }, timeoutMs);
+        child.stdout.setEncoding("utf8").on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => finish({ ok: false, stdout, stderr: error.message }));
+        child.on("close", (code) => finish({ ok: code === 0, stdout, stderr }));
+    });
+}
+/** 当前分支 + 本地分支清单（下拉菜单用；每次打开菜单可以刷新一次） */
+export async function readGitBranches(root) {
+    const info = await readGitInfo(root);
+    if (!info.isRepo)
+        return { ...info, branches: [] };
+    const repo = await findRepoRoot(root);
+    if (!repo)
+        return { ...info, branches: [] };
+    const result = await runGit(repo, ["branch", "--no-color", "--format=%(refname:short)", "--sort=-committerdate"]);
+    if (!result.ok)
+        return { ...info, branches: [], error: firstLine(result.stderr) || "列不出分支" };
+    const branches = result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    return { ...info, branches };
+}
+export async function readWorktreeStatus(repo) {
+    const result = await runGit(repo, ["status", "--porcelain"], 8000);
+    if (!result.ok)
+        return { files: [], total: 0 };
+    const lines = result.stdout
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line !== "");
+    // 每行前 3 个字符是状态码（` M ` / `?? ` / `R  `），后面才是路径
+    const files = lines.slice(0, 20).map((line) => line.slice(3).trim() || line.trim());
+    return { files, total: lines.length };
+}
+/**
+ * 切分支（`git checkout <branch>`，不用 shell）。
+ *
+ * 只允许切到**本地已有分支**：名字先在清单里对一遍，既挡掉 `-b` 这类会被 git 当成
+ * 参数的名字，也避免"点了一下结果多建出一个分支"。工作区有冲突改动时 git 自己会拒绝，
+ * 它的报错原样回给界面（比我们自己猜准）。
+ *
+ * 工作区脏的时候默认**不切**，先把改动清单交给界面去问一句（`force: true` 才真切）——
+ * 切过去那些改动会跟着走，用户至少得知道一声。
+ */
+export async function checkoutBranch(root, branch, options = {}) {
+    const name = branch.trim();
+    if (!/^[^\s~^:?*[\\]+$/.test(name) || name.startsWith("-")) {
+        return { ok: false, message: "分支名不合法" };
+    }
+    const repo = await findRepoRoot(root);
+    if (!repo)
+        return { ok: false, message: "这里不是 git 仓库" };
+    const listed = await readGitBranches(repo);
+    if (!listed.isRepo)
+        return { ok: false, message: "这里不是 git 仓库" };
+    if (!listed.branches.includes(name))
+        return { ok: false, message: `没有本地分支 ${name}` };
+    if (listed.branch === name)
+        return { ok: true, branch: name };
+    if (options.force !== true) {
+        const dirty = await readWorktreeStatus(repo);
+        if (dirty.total > 0) {
+            return { ok: false, dirty, message: `工作区有 ${dirty.total} 个未提交改动，没切换` };
+        }
+    }
+    const result = await runGit(repo, ["checkout", "--quiet", name], 15000);
+    if (!result.ok) {
+        return { ok: false, message: firstLine(result.stderr) || `切换到 ${name} 失败` };
+    }
+    const after = await readGitInfo(repo);
+    return { ok: true, branch: after.branch };
+}
+/**
+ * git 的报错常常是多行（还会列一串文件）：挑最有用的一两行喂给界面。
+ * `error:` / `fatal:` 那行是结论，后面通常跟着「哪些文件挡路了」。
+ */
+function firstLine(text) {
+    const lines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    const pick = lines.find((line) => /^(error|fatal):/i.test(line)) ?? lines[0] ?? "";
+    const detail = lines.find((line) => line !== pick && !/^hint:/i.test(line)) ?? "";
+    const summary = detail ? `${pick} ${detail}` : pick;
+    return summary.length > 240 ? `${summary.slice(0, 240)}…` : summary;
+}

package/dist/server/http/auth-routes.js

@@ -0,0 +1,99 @@
+/**
+ * 登录 / 登出端点（ADR-0031 修订）：自建登录页把密码 POST 到这里。
+ *
+ * 为什么单独成文件、且**注册在鉴权中间件之前**：密码都还没校验，不能要求先有 cookie。
+ * 这两个端点自己只做三件事 —— 比对密码（常量时间）、节流失败次数、种/清 cookie。
+ *
+ * 登录成功后的 cookie 有效期 **7 天**（`AUTH_COOKIE_MAX_AGE`），且每次通过鉴权的访问都会
+ * 顺延一次；7 天不访问才需要重新输密码。
+ */
+import express, {} from "express";
+import { BRAND_NAME } from "../brand.js";
+import { CLEAR_AUTH_COOKIE, authCookieHeader, effectiveAddress, samePassword } from "./auth.js";
+import { renderLoginPage } from "./login-page.js";
+/** 失败节流窗口与上限：同一来源 10 分钟内失败 20 次就从这里起拒收（挡在线爆破） */
+const FAILURE_WINDOW_MS = 10 * 60_000;
+const MAX_FAILURES = 20;
+const MAX_TRACKED_SOURCES = 512;
+function addressOf(request) {
+    const forwarded = request.headers["x-forwarded-for"];
+    return (effectiveAddress(request.socket.remoteAddress, typeof forwarded === "string" ? forwarded : undefined) ?? "unknown");
+}
+function acceptsHtml(request) {
+    const accept = request.headers.accept;
+    return typeof accept === "string" && accept.includes("text/html");
+}
+export function registerAuthRoutes(app, options) {
+    const brandName = options.brandName ?? BRAND_NAME;
+    const attempts = new Map();
+    /** 失败计数（顺手清掉过期的，避免 Map 只增不减） */
+    function noteFailure(address, now) {
+        const current = attempts.get(address);
+        if (!current || now > current.resetAt) {
+            if (attempts.size >= MAX_TRACKED_SOURCES) {
+                for (const [key, value] of attempts)
+                    if (now > value.resetAt)
+                        attempts.delete(key);
+            }
+            attempts.set(address, { count: 1, resetAt: now + FAILURE_WINDOW_MS });
+            return;
+        }
+        current.count += 1;
+    }
+    function throttled(address, now) {
+        const current = attempts.get(address);
+        if (!current)
+            return false;
+        if (now > current.resetAt) {
+            attempts.delete(address);
+            return false;
+        }
+        return current.count >= MAX_FAILURES;
+    }
+    app.post("/api/auth/login", express.urlencoded({ extended: false, limit: "2kb" }), express.json({ limit: "2kb" }), (request, response) => {
+        const password = options.password;
+        const html = acceptsHtml(request);
+        // 没设密码 = 不开放远程（与本机直连无关：本机根本不需要登录）
+        if (!password) {
+            response.setHeader("Content-Type", "text/plain; charset=utf-8");
+            response.status(403).end("未设置 AGENT_WEB_PASSWORD：本服务不开放远程访问\n");
+            return;
+        }
+        const address = addressOf(request);
+        const now = Date.now();
+        if (throttled(address, now)) {
+            response.setHeader("Content-Type", "application/json; charset=utf-8");
+            response.status(429).end(JSON.stringify({ ok: false, error: "尝试次数过多，请稍后再试" }));
+            return;
+        }
+        const body = request.body;
+        const submitted = typeof body?.password === "string" ? body.password : "";
+        if (submitted === "" || !samePassword(submitted, password)) {
+            noteFailure(address, now);
+            const error = "密码不正确";
+            if (html) {
+                response.setHeader("Content-Type", "text/html; charset=utf-8");
+                response.setHeader("Cache-Control", "no-store");
+                response.status(401).end(renderLoginPage({ brandName, error }));
+                return;
+            }
+            response.setHeader("Content-Type", "application/json; charset=utf-8");
+            response.setHeader("Cache-Control", "no-store");
+            response.status(401).end(JSON.stringify({ ok: false, error }));
+            return;
+        }
+        attempts.delete(address);
+        response.setHeader("Set-Cookie", authCookieHeader(password));
+        // 无 JS 的表单提交：种完 cookie 直接跳回首页（不采信任何外部传入的 next，避免开放重定向）
+        if (html) {
+            response.redirect(303, "/");
+            return;
+        }
+        response.setHeader("Cache-Control", "no-store");
+        response.status(204).end();
+    });
+    app.post("/api/auth/logout", (_request, response) => {
+        response.setHeader("Set-Cookie", CLEAR_AUTH_COOKIE);
+        response.status(204).end();
+    });
+}

package/dist/server/http/auth.js

@@ -0,0 +1,191 @@
+/**
+ * 访问鉴权（ADR-0031，2026-10 修订）：本机直连放行，**其它来源必须输密码**。
+ *
+ * 登录界面是**自己渲染的页面**（`login-page.ts`），不再用浏览器原生 Basic 弹窗：
+ * `POST /api/auth/login` 校验密码后种一张 **7 天**的 cookie（`auth-routes.ts`），
+ * 页面 / 静态资源 / API / WS 握手全都认这张 cookie。
+ * Basic 头仍然接受（curl、脚本、老客户端都还在用），只是不再拿它去触发弹窗。
+ *
+ * 判定顺序（先便宜后贵）：
+ *   1. 来源是本机回环 → 放行（本地开发不该被打断输密码）
+ *   2. 没设 `AGENT_WEB_PASSWORD` → **远程一律 403**（不给登录页：没有密码就没法远程进）
+ *   3. 带有效 cookie 或 Basic 凭据且密码正确 → 放行
+ *   4. 其它 → 401
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { BRAND_NAME } from "../brand.js";
+import { renderLoginPage } from "./login-page.js";
+export const AUTH_REALM = BRAND_NAME;
+/** 登录状态的保存时长：**7 天**（每次访问顺延） */
+export const AUTH_COOKIE_MAX_AGE = 7 * 24 * 60 * 60;
+/**
+ * 登录成功后下发的 cookie 值：`sha256(密码)`，不含明文密码。
+ *
+ * 为什么需要它：**WebSocket 握手不一定带 Basic 凭据**（浏览器只在部分场景复用），
+ * 但 cookie 一定会带 —— 有了它，WS 才能稳定通过鉴权。
+ */
+export const AUTH_COOKIE = "agent-web-auth";
+export function cookieToken(password) {
+    return createHash("sha256").update(`agent-web:${password}`).digest("hex");
+}
+/** 登录成功后要写回的 `Set-Cookie`（7 天；HttpOnly：前端读不到也就偷不走） */
+export function authCookieHeader(password) {
+    return [
+        `${AUTH_COOKIE}=${cookieToken(password)}`,
+        "Path=/",
+        "HttpOnly",
+        "SameSite=Lax",
+        `Max-Age=${AUTH_COOKIE_MAX_AGE}`,
+    ].join("; ");
+}
+/** 清掉登录态（登出 / 密码错误兜底） */
+export const CLEAR_AUTH_COOKIE = `${AUTH_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`;
+/**
+ * 免鉴权的静态路径（图标 / 清单）。
+ *
+ * 为什么必须放行：手机「添加到主屏幕」时，iOS 抳 `apple-touch-icon`、Android 抳
+ * `manifest` 和清单里的图标，**这些子请求不保证带 Basic 凭据** —— 回 401 设备就
+ * 拿不到图，自己生成一个「主题色底 + 首字母」的方块顶上去（蓝底白 A 就是这么来的）。
+ * 这些响应里没有任何用户数据（纯图片 / 图标清单），放行不扩大攻击面；
+ * `/api/*`、页面本身、WebSocket 仍然一律要过密码。
+ */
+const PUBLIC_STATIC = /^\/(favicon[^/]*|icons\/.*|apple-touch-icon[^/]*|manifest\.webmanifest)$/;
+export function isPublicStaticPath(path) {
+    return PUBLIC_STATIC.test(path);
+}
+/** 从 Cookie 头里取登录令牌 */
+export function tokenFromCookie(header) {
+    if (!header)
+        return null;
+    for (const part of header.split(";")) {
+        const [name, ...rest] = part.trim().split("=");
+        if (name === AUTH_COOKIE)
+            return rest.join("=").trim();
+    }
+    return null;
+}
+/** 是否是本机回环地址（IPv4 / IPv6 / IPv4-mapped） */
+export function isLoopback(address) {
+    if (!address)
+        return false;
+    if (address === "::1")
+        return true;
+    if (address.startsWith("127."))
+        return true;
+    return address.startsWith("::ffff:127.");
+}
+/** 常量时间比较（长度不同直接 false，避免泄漏长度以外的信息） */
+export function samePassword(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * 这次请求该不该拿到**登录页**（而不是 401 JSON）？
+ *
+ * 只认 `text/html`：fetch / EventSource / XHR 的默认 `Accept: *\/*` 必须继续拿 JSON，
+ * 否则前端会把一张 HTML 当数据去解析。
+ */
+export function wantsLoginPage(method, accept) {
+    if (method !== "GET" && method !== "HEAD")
+        return false;
+    return typeof accept === "string" && accept.includes("text/html");
+}
+/**
+ * 真实来源：本机对端（比如 Vite 反代）带了 `X-Forwarded-For` 时取**最右边**那个。
+ *
+ * 为什么不是最左边：那个位置客户端可以自己伪造（`X-Forwarded-For: 127.0.0.1` 就冒充本机了）；
+ * 最右边是**我们的代理附加的**，才是可信值。同时只在对端本身是回环时才看这个头。
+ */
+export function effectiveAddress(peer, forwardedFor) {
+    if (!isLoopback(peer) || !forwardedFor)
+        return peer;
+    const parts = forwardedFor
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "");
+    const last = parts[parts.length - 1];
+    return last ?? peer;
+}
+/** 从 `Authorization: Basic base64(user:pass)` 里取密码（用户名忽略） */
+export function passwordFromHeader(header) {
+    if (!header || !header.toLowerCase().startsWith("basic "))
+        return null;
+    const decoded = Buffer.from(header.slice(6).trim(), "base64").toString("utf8");
+    const index = decoded.indexOf(":");
+    return index < 0 ? null : decoded.slice(index + 1);
+}
+export function decide(input) {
+    if (isLoopback(input.remoteAddress))
+        return "allow";
+    // 没设密码 = 根本不开放远程（不是"留个空密码"，那样等于谁都能进）
+    if (!input.password)
+        return "forbid";
+    // 先看 cookie（浏览器加载页面时已经登录过），再看 Basic
+    const token = tokenFromCookie(input.cookie);
+    if (token !== null && samePassword(token, cookieToken(input.password)))
+        return "allow";
+    const provided = passwordFromHeader(input.authorization);
+    return provided !== null && samePassword(provided, input.password) ? "allow" : "challenge";
+}
+/**
+ * Express 中间件：本机放行；远程未登录时——**页面请求给登录页**，其余给 401。
+ *
+ * 不再发 `WWW-Authenticate`：那会让浏览器弹原生框，与自建登录页打架。
+ */
+export function authMiddleware(options) {
+    const { password } = options;
+    return (request, response, next) => {
+        // 图标 / 清单：手机加桌面时不带凭据也能取（见 isPublicStaticPath）
+        if (isPublicStaticPath(request.path)) {
+            next();
+            return;
+        }
+        const authorization = request.headers.authorization;
+        const forwarded = request.headers["x-forwarded-for"];
+        const cookie = request.headers.cookie;
+        const decision = decide({
+            password,
+            remoteAddress: effectiveAddress(request.socket.remoteAddress, typeof forwarded === "string" ? forwarded : undefined),
+            authorization: typeof authorization === "string" ? authorization : undefined,
+            cookie: typeof cookie === "string" ? cookie : undefined,
+        });
+        if (decision === "allow") {
+            // 每次访问都把 7 天重新算起（顺延）；WS / SSE 握手一定带 cookie，Basic 不保证
+            if (password)
+                response.setHeader("Set-Cookie", authCookieHeader(password));
+            next();
+            return;
+        }
+        if (decision === "forbid") {
+            response.setHeader("Content-Type", "text/plain; charset=utf-8");
+            response.status(403).end("未设置 AGENT_WEB_PASSWORD：本服务不开放远程访问\n");
+            return;
+        }
+        const accept = request.headers.accept;
+        if (wantsLoginPage(request.method, typeof accept === "string" ? accept : undefined)) {
+            const page = renderLoginPage(options.brandName ? { brandName: options.brandName } : {});
+            response.setHeader("Content-Type", "text/html; charset=utf-8");
+            response.setHeader("Cache-Control", "no-store");
+            // connect-src 必须显式放开 'self'：default-src 'none' 会把 fetch 一起禁掉，
+            // 表现就是「点了登录没反应」（密码 POST 被浏览器拦下，根本没有请求出去）。
+            // form-action 'self' 兜住无 JS 的原生表单提交，两者缺一个登录都会坏。
+            response.setHeader("Content-Security-Policy", [
+                "default-src 'none'",
+                "img-src 'self'",
+                "style-src 'unsafe-inline'",
+                "script-src 'unsafe-inline'",
+                "connect-src 'self'",
+                "form-action 'self'",
+                "base-uri 'none'",
+            ].join("; "));
+            response.status(200).end(page);
+            return;
+        }
+        response.setHeader("Content-Type", "application/json; charset=utf-8");
+        response.setHeader("Cache-Control", "no-store");
+        response.status(401).end(JSON.stringify({ ok: false, error: "未登录或登录已过期" }));
+    };
+}