@yunzai-ng/core 0.1.0

package/src/server/auth.ts

@@ -0,0 +1,201 @@
+/**
+ * 模块职责：面板与插件路由的访问控制 —— 令牌生成、校验、跨站伪造防线
+ * 依赖方向：只依赖 node:crypto 与类型包
+ * 生命周期：纯函数，无状态；令牌本身存在配置里
+ * 注意事项：四条安全约定 ——
+ *
+ *          **令牌只从请求头读，绝不从查询串或 Cookie 读。** 查询串会进 access log、浏览器历史与
+ *          Referer；Cookie 会被浏览器自动附带，那正是 CSRF 的成因。头部令牌没有「自动附带」这回事，
+ *          故本服务器天然免疫 CSRF，也因此不需要 CSRF token。代价是 `EventSource` 用不了（它设不了
+ *          请求头），故日志实时推送走 WebSocket。
+ *
+ *          **浏览器 WebSocket 同样设不了请求头**，故允许把令牌放进 `Sec-WebSocket-Protocol`。
+ *          它是请求头的一部分，同样不会被自动附带。
+ *
+ *          **比较走 SHA-256 摘要 + `timingSafeEqual`。** 直接对原文用后者会在长度不等时抛错，
+ *          等于把「长度对不对」变成一个旁路信号；先摘要则两边恒为 32 字节。
+ *
+ *          **没设令牌时只放行本机**，判据是 TCP 对端地址，且服务器强制 `trustProxy: false` ——
+ *          否则任何人都能靠一个 `X-Forwarded-For: 127.0.0.1` 把自己伪装成本机。
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto"
+
+/** 自动生成令牌的字节数：24 字节 → base64url 32 字符，既可抵御爆破又便于人工转录 */
+const TOKEN_BYTES = 24
+
+/** 令牌请求头（`Authorization: Bearer` 之外的简易写法） */
+const TOKEN_HEADER = "x-yunzai-token"
+
+/** WebSocket 子协议里约定的第一个标识，第二个才是令牌 */
+export const WS_PROTOCOL = "yunzai"
+
+/**
+ * 会被跨站表单 / 简单请求造出来的请求体类型
+ *
+ * 这三种 `Content-Type` 不触发预检，因此一个恶意页面可以在用户不知情的情况下
+ * 向 `127.0.0.1` 发出携带它们的 POST。面板的写接口一律只收 JSON，于是把这三种
+ * 直接挡在门外 —— 挡的不是"错误的格式"，是"唯一一条能绕开同源策略的路"。
+ */
+const FORGEABLE_TYPES = ["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"]
+
+/** 会改变状态、因此需要防伪造的方法 */
+const UNSAFE_METHODS = ["POST", "PUT", "PATCH", "DELETE"]
+
+/**
+ * 生成一个新的访问令牌
+ *
+ * 用 `randomBytes` 而**不是** `util/id.ts` 的 `randomId()`：后者对随机字节取模
+ * 引入了可忽略但真实存在的分布偏差，其文档里也写明"不用于密码学场景"。
+ * 令牌正是密码学场景。
+ * @returns base64url 编码的 32 字符令牌
+ */
+export function generateToken(): string {
+  return randomBytes(TOKEN_BYTES).toString("base64url")
+}
+
+/**
+ * 定时安全地比较两个令牌
+ * @param expected 配置里的令牌
+ * @param given 请求带来的令牌
+ * @returns 是否一致
+ */
+export function tokenEquals(expected: string, given: string): boolean {
+  const a = createHash("sha256").update(expected, "utf8").digest()
+  const b = createHash("sha256").update(given, "utf8").digest()
+  return timingSafeEqual(a, b)
+}
+
+/**
+ * 判断一个对端地址是否是本机
+ *
+ * IPv4 的整个 `127.0.0.0/8` 都是回环，不只是 `127.0.0.1`；Node 在双栈监听下
+ * 会把 IPv4 对端写成 `::ffff:127.0.0.1` 这种映射形式。两者都要认。
+ * @param address 对端地址；unix socket 等场景可能是空串
+ * @returns 是否本机
+ */
+export function isLoopbackAddress(address: string): boolean {
+  if (address === "") return false
+  const ip = address.startsWith("::ffff:") ? address.slice(7) : address
+  if (ip === "::1" || ip === "localhost") return true
+  if (!ip.includes(".")) return false
+  return ip.startsWith("127.")
+}
+
+/**
+ * 判断配置中填写的监听地址是否仅对本机可见
+ *
+ * `ensureToken()` 据此决定是否强制生成令牌：仅监听本机时不生成，
+ * 以免单机部署的使用者被一串随机字符阻挡在面板之外。
+ * @param host 监听地址
+ * @returns 是否只对本机可见
+ */
+export function isLocalHost(host: string): boolean {
+  return host === "localhost" || isLoopbackAddress(host)
+}
+
+/**
+ * 从请求头里取出令牌
+ *
+ * 三个来源按优先级：`Authorization: Bearer x` → `x-yunzai-token: x` →
+ * `Sec-WebSocket-Protocol: yunzai, x`。刻意**不看**查询串与 Cookie，见文件头第 1 条。
+ * @param headers 已小写化键名的请求头
+ * @returns 令牌；没带时 undefined
+ */
+export function readToken(headers: Readonly<Record<string, string | string[] | undefined>>): string | undefined {
+  const auth = firstValue(headers.authorization)
+  if (auth !== undefined) {
+    const match = /^Bearer\s+(.+)$/i.exec(auth.trim())
+    if (match?.[1] !== undefined) return match[1].trim()
+  }
+
+  const plain = firstValue(headers[TOKEN_HEADER])
+  if (plain !== undefined && plain !== "") return plain.trim()
+
+  const protocols = firstValue(headers["sec-websocket-protocol"])
+  if (protocols !== undefined) {
+    const parts = protocols.split(",").map(part => part.trim())
+    if (parts[0] === WS_PROTOCOL && parts[1] !== undefined && parts[1] !== "") return parts[1]
+  }
+
+  return undefined
+}
+
+/**
+ * 取请求头的第一个值
+ *
+ * Node 对重复出现的请求头会给出数组。取第一个而非拼接：令牌被写入两次时，
+ * 拼接得到的字符串必定校验失败，而报错信息会指向"令牌错误"而非"令牌重复出现"。
+ * @param value 头值
+ * @returns 首个值；不存在时 undefined
+ */
+function firstValue(value: string | string[] | undefined): string | undefined {
+  if (value === undefined) return undefined
+  return Array.isArray(value) ? value[0] : value
+}
+
+/** 鉴权失败的描述 */
+export interface AuthFailure {
+  /** 建议的 HTTP 状态码 */
+  readonly status: number
+  /** 给人看的原因，会直接写进响应体 */
+  readonly message: string
+}
+
+/** 一次鉴权要用到的请求信息 */
+export interface AuthRequest {
+  /** 对端地址（必须是 TCP 对端，不能是 `X-Forwarded-For`） */
+  readonly ip: string
+  /** 请求方法 */
+  readonly method: string
+  /** 已小写化键名的请求头 */
+  readonly headers: Readonly<Record<string, string | string[] | undefined>>
+}
+
+/**
+ * 校验一次访问
+ *
+ * 规则：
+ * - 已配置令牌 → 一律要求携带正确令牌，**本机亦不例外**。本机进程与使用者浏览器中
+ *   的任意页面均可访问 `127.0.0.1`，"本机"并不等同于"可信"。
+ * - 未配置令牌 → 仅放行本机对端；外部访问直接拒绝，并说明需要配置的内容。
+ * @param token 配置中的令牌；未设置时 undefined
+ * @param req 请求信息
+ * @returns 校验失败时的描述；通过时 undefined
+ */
+export function checkAuth(token: string | undefined, req: AuthRequest): AuthFailure | undefined {
+  if (token === undefined || token === "") {
+    if (isLoopbackAddress(req.ip)) return undefined
+    return {
+      status: 401,
+      message: "本服务器尚未设置访问令牌，因此只接受本机访问。请在 config/yunzai.yaml 的 server.token 里设置令牌后重启"
+    }
+  }
+
+  const given = readToken(req.headers)
+  if (given === undefined) {
+    return {
+      status: 401,
+      message: "缺少访问令牌。请在请求头带上 Authorization: Bearer <令牌>，或 x-yunzai-token: <令牌>"
+    }
+  }
+  if (!tokenEquals(token, given)) return { status: 403, message: "访问令牌不正确" }
+  return undefined
+}
+
+/**
+ * 校验请求体类型，挡掉可跨站伪造的写请求
+ *
+ * 只对需要鉴权的路由生效：适配器 webhook 常用表单编码，它们走 `auth: false`
+ * 并自行验签，不该被这条规则牵连。
+ * @param req 请求信息
+ * @returns 校验失败时的描述；通过时 undefined
+ */
+export function checkForgeableBody(req: AuthRequest): AuthFailure | undefined {
+  if (!UNSAFE_METHODS.includes(req.method)) return undefined
+  const type = (firstValue(req.headers["content-type"]) ?? "").split(";")[0]?.trim().toLowerCase() ?? ""
+  if (type === "" || !FORGEABLE_TYPES.includes(type)) return undefined
+  return {
+    status: 415,
+    message: `${type} 不被接受：需要鉴权的写接口只收 application/json（这条限制是为了挡住跨站伪造请求）`
+  }
+}

package/src/server/browse.test.ts

@@ -0,0 +1,193 @@
+/**
+ * 模块职责：`browse.ts` 的用例 —— 目录列举、上一级、错误映射与截断
+ * 依赖方向：测试文件，依赖被测模块与 node:fs
+ * 生命周期：每个用例一个临时目录
+ * 注意事项：**用例跑在真实文件系统上，不打桩。** 要验的恰是「Node 的 readdir 在这台
+ *          机器上给出什么」——把 fs 打成桩就只是在验证桩自己，而符号链接、悬空链接、
+ *          权限错误这几处的行为差异全在真实文件系统一侧。
+ *
+ *          符号链接一节在 Windows 上需要管理员权限或开发者模式，因此建链接失败时
+ *          跳过该用例而不是让它红 —— 那种失败与被测代码无关。
+ */
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, sep } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { browseDirectory, parentOf } from "./browse.js"
+
+describe("目录浏览", () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "yzng-browse-"))
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  /**
+   * 取成功结果的列举内容
+   * @param path 要列举的路径
+   * @returns 列举内容
+   */
+  async function listing(path: string | undefined): Promise<{
+    /** 路径 */
+    path: string
+    /** 上一级 */
+    parent?: string
+    /** 条目 */
+    entries: readonly { name: string; dir: boolean; link?: boolean }[]
+    /** 是否截断 */
+    truncated: boolean
+    /** 分隔符 */
+    sep: string
+  }> {
+    const result = await browseDirectory(path)
+    if (!result.ok) throw new Error(`预期成功，实得 ${result.status}：${result.message}`)
+    return result.listing
+  }
+
+  it("目录在前、文件在后，各按名称排序", async () => {
+    await mkdir(join(dir, "z-dir"))
+    await mkdir(join(dir, "a-dir"))
+    await writeFile(join(dir, "z.txt"), "1")
+    await writeFile(join(dir, "a.txt"), "1")
+
+    const out = await listing(dir)
+    expect(out.entries.map(e => e.name)).toEqual(["a-dir", "z-dir", "a.txt", "z.txt"])
+    expect(out.entries.map(e => e.dir)).toEqual([true, true, false, false])
+  })
+
+  it("数字按数值大小排，f2 在 f10 之前", async () => {
+    for (const name of ["f10.txt", "f2.txt", "f1.txt"]) await writeFile(join(dir, name), "1")
+    const out = await listing(dir)
+    expect(out.entries.map(e => e.name)).toEqual(["f1.txt", "f2.txt", "f10.txt"])
+  })
+
+  it("**中文名整块排在英文名之前** —— CLDR 中文排序把汉字提到拉丁字母之前，非缺陷", async () => {
+    for (const name of ["伽马", "阿尔法", "alpha"]) await mkdir(join(dir, name))
+    const out = await listing(dir)
+    // 汉字之间按拼音：阿尔法（a）在伽马（g）之前
+    expect(out.entries.map(e => e.name)).toEqual(["阿尔法", "伽马", "alpha"])
+  })
+
+  it("回的是名字与是否目录，**不含大小、时间与内容**", async () => {
+    await writeFile(join(dir, "secret.txt"), "不该出现在响应里")
+    const out = await listing(dir)
+    const entry = out.entries[0]
+    expect(entry).toEqual({ name: "secret.txt", dir: false })
+    expect(JSON.stringify(out)).not.toContain("不该出现")
+  })
+
+  it("给出上一级与本机分隔符", async () => {
+    const child = join(dir, "sub")
+    await mkdir(child)
+    const out = await listing(child)
+    expect(out.path).toBe(child)
+    expect(out.parent).toBe(dir)
+    expect(out.sep).toBe(sep)
+  })
+
+  it("隐藏项照常列出 —— Linux 上 .config 一类目录正是要找的", async () => {
+    await mkdir(join(dir, ".config"))
+    const out = await listing(dir)
+    expect(out.entries.map(e => e.name)).toContain(".config")
+  })
+
+  it("路径被规范化，末尾多余的分隔符与 `.` 不影响结果", async () => {
+    const out = await listing(`${dir}${sep}.${sep}`)
+    expect(out.path).toBe(dir)
+  })
+
+  it("**相对路径一律拒绝**，并说明基准不可见", async () => {
+    const result = await browseDirectory("plugins")
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.status).toBe(400)
+    expect(result.message).toContain("绝对路径")
+  })
+
+  it("不存在回 404、指向文件回 400", async () => {
+    const missing = await browseDirectory(join(dir, "无此目录"))
+    expect(missing.ok).toBe(false)
+    if (!missing.ok) expect(missing.status).toBe(404)
+
+    const file = join(dir, "f.txt")
+    await writeFile(file, "1")
+    const notDir = await browseDirectory(file)
+    expect(notDir.ok).toBe(false)
+    if (!notDir.ok) {
+      expect(notDir.status).toBe(400)
+      expect(notDir.message).toContain("不是一个目录")
+    }
+  })
+
+  it("超过 1000 项时截断并标明", async () => {
+    await Promise.all(
+      Array.from({ length: 1005 }, (_, i) => writeFile(join(dir, `f${String(i).padStart(4, "0")}.txt`), "1"))
+    )
+    const out = await listing(dir)
+    expect(out.entries.length).toBe(1000)
+    expect(out.truncated).toBe(true)
+    // 先排序再截断，故截到的必是排序后的前 1000 项
+    expect(out.entries[0]?.name).toBe("f0000.txt")
+  })
+
+  it("未超上限时 truncated 为假", async () => {
+    await writeFile(join(dir, "one.txt"), "1")
+    expect((await listing(dir)).truncated).toBe(false)
+  })
+
+  it("指向目录的符号链接算目录，悬空链接不算且不报错", async () => {
+    const target = join(dir, "real")
+    await mkdir(target)
+    try {
+      await symlink(target, join(dir, "link-dir"), "dir")
+      await symlink(join(dir, "无此物"), join(dir, "link-broken"), "dir")
+    } catch {
+      // Windows 上建符号链接需要额外权限，与被测代码无关
+      return
+    }
+    const out = await listing(dir)
+    const byName = new Map(out.entries.map(e => [e.name, e]))
+    expect(byName.get("link-dir")).toEqual({ name: "link-dir", dir: true, link: true })
+    expect(byName.get("link-broken")).toEqual({ name: "link-broken", dir: false, link: true })
+  })
+})
+
+describe("上一级", () => {
+  it("Windows 上盘根的上一级是盘符列表（空串），而不是它自己", () => {
+    expect(parentOf("C:\\Users\\x", true)).toBe("C:\\Users")
+    expect(parentOf("C:\\", true)).toBe("")
+  })
+
+  it("类 Unix 上根目录没有上一级", () => {
+    // 在 Windows 上 dirname("/") 同样是 "/"，故用 windows=false 走另一条分支
+    expect(parentOf("/", false)).toBeUndefined()
+  })
+})
+
+describe("缺省起点", () => {
+  it("不带路径时按平台给出最外层：Windows 列盘符、其余列根目录", async () => {
+    const result = await browseDirectory(undefined)
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    if (process.platform === "win32") {
+      expect(result.listing.path).toBe("")
+      expect(result.listing.parent).toBeUndefined()
+      // 至少有一个盘，且每个都形如 X:\
+      expect(result.listing.entries.length).toBeGreaterThan(0)
+      expect(result.listing.entries.every(e => /^[C-Z]:\\$/.test(e.name) && e.dir)).toBe(true)
+    } else {
+      expect(result.listing.path).toBe("/")
+    }
+  })
+
+  it("空串与只有空白的路径等同于缺省", async () => {
+    const blank = await browseDirectory("   ")
+    const none = await browseDirectory(undefined)
+    expect(blank.ok).toBe(true)
+    if (blank.ok && none.ok) expect(blank.listing.path).toBe(none.listing.path)
+  })
+})

package/src/server/browse.ts

@@ -0,0 +1,240 @@
+/**
+ * 模块职责：只读的目录浏览 —— 面板填写「服务器上的路径」时的候选来源
+ * 依赖方向：依赖 node:fs / node:path 与 util/fs；不认识 HTTP，也不认识面板
+ * 生命周期：纯函数，无状态
+ * 注意事项：**这是内核唯一一处允许外部枚举本机文件系统的地方，故边界写在这里而非调用处。**
+ *          它的存在理由只有一个：配置里的 `file` / `dir` 字段要的是服务器上的路径，而浏览器的
+ *          `<input type="file">` 给不到路径。没有它，那两种 widget 只能让人手敲绝对路径。
+ *
+ *          四条刻意的限制，都是为了让扩权尽量小：**只回名字与「是不是目录」**，不回大小、时间、
+ *          权限、内容（附带好处是不必逐项 `stat`，万条文件的目录会因此慢上百倍）；**条目数设上限**
+ *          并如实标明截断；**符号链接只跟一层**，且跟不到就当普通文件（`withFileTypes` 是 lstat
+ *          语义，指向目录的链接会被判成不是目录、于是点不进去）；**不做写操作，也不收相对路径**
+ *          —— 相对路径的基准是内核的工作目录，而那不是面板看得见的东西。
+ *
+ *          「只读模式下要禁用这个只读接口」那条在 api.ts —— 那是面板策略，不是文件系统的性质。
+ */
+import { constants as fsConstants, type Dirent } from "node:fs"
+import { access, readdir, stat } from "node:fs/promises"
+import { posix, win32 } from "node:path"
+import { errorCode } from "../util/fs.js"
+
+/** 单次最多返回的条目数，见文件头第 2 条 */
+const MAX_ENTRIES = 1000
+
+/**
+ * 探测盘符的范围
+ *
+ * 自 C 起而不自 A 起：A、B 是软驱字母，在部分机器上探测它们会让驱动器空转数秒，
+ * 而这两个字母上今日不会有内核要访问的目录。
+ */
+const DRIVE_LETTERS = "CDEFGHIJKLMNOPQRSTUVWXYZ"
+
+/**
+ * 取对应平台的路径实现
+ *
+ * 本模块的每个导出都带 `windows` 参数，于是路径计算也必须跟着这个参数走，不能用
+ * `node:path` 的平台默认导出：那些导出绑的是**当前进程**的平台，于是
+ * `dirname("C:\\Users\\x")` 在 Linux 上是 `"."`，参数就成了摆设 —— 用例在 Windows 上
+ * 全绿、在 Linux 的 CI 上挂。
+ * @param windows 是否按 Windows 处理
+ * @returns `node:path` 的 win32 或 posix 实现
+ */
+function pathOf(windows: boolean): typeof win32 | typeof posix {
+  return windows ? win32 : posix
+}
+
+/** 目录里的一项 */
+export interface BrowseEntry {
+  /** 名字，不含所在目录 */
+  readonly name: string
+  /** 是不是目录（符号链接按其指向判定） */
+  readonly dir: boolean
+  /** 是不是符号链接；不是则不出现 */
+  readonly link?: boolean
+}
+
+/** 一次目录列举的结果 */
+export interface BrowseListing {
+  /** 规范化后的绝对路径；Windows 上列举盘符时为空串 */
+  readonly path: string
+  /** 上一级路径；已在最外层时不出现 */
+  readonly parent?: string
+  /** 条目，目录在前、各按名称排序 */
+  readonly entries: readonly BrowseEntry[]
+  /** 条目是否因超过上限而被截断 */
+  readonly truncated: boolean
+  /**
+   * 本机的路径分隔符
+   *
+   * 一并回给面板，免得前端靠 `navigator.platform` 猜 —— 浏览器所在的机器与内核
+   * 所在的机器完全可以是两台，用浏览器的分隔符去拼服务器的路径必然出错。
+   */
+  readonly sep: string
+}
+
+/** 列举结果：成功或一条可直接回给面板的失败说明 */
+export type BrowseResult =
+  | {
+      /** 成功 */
+      readonly ok: true
+      /** 列举内容 */
+      readonly listing: BrowseListing
+    }
+  | {
+      /** 失败 */
+      readonly ok: false
+      /** 建议的 HTTP 状态码 */
+      readonly status: number
+      /** 中文说明，可原样回给面板 */
+      readonly message: string
+    }
+
+/** 错误码 → 状态码与说明 */
+const CODE_TABLE: Record<string, { status: number; text: string }> = {
+  ENOENT: { status: 404, text: "不存在" },
+  ENOTDIR: { status: 400, text: "不是一个目录" },
+  EACCES: { status: 403, text: "没有读取权限" },
+  EPERM: { status: 403, text: "没有读取权限" },
+  ELOOP: { status: 400, text: "符号链接成环" },
+  ENAMETOOLONG: { status: 400, text: "路径过长" }
+}
+
+/**
+ * 上一级路径
+ *
+ * Windows 上盘根（`C:\`）的上一级是**盘符列表**（以空串表示），而不是它自己 ——
+ * 否则面板上的「上一级」在盘根处点不动，也就无从切换到另一个盘。
+ * @param target 绝对路径
+ * @param windows 是否 Windows
+ * @returns 上一级；已在最外层时 undefined
+ */
+export function parentOf(target: string, windows: boolean): string | undefined {
+  const up = pathOf(windows).dirname(target)
+  if (up !== target) return up
+  return windows ? "" : undefined
+}
+
+/**
+ * 列举现有的盘符
+ *
+ * Node 没有列举盘符的 API，只能逐个字母试。`access` 而非 `stat`：后者在未插盘的
+ * 读卡器上会等到超时，前者只问「能不能访问」。
+ * @returns 形如 `C:\` 的盘根数组
+ */
+async function listDrives(): Promise<BrowseEntry[]> {
+  const probes = [...DRIVE_LETTERS].map(async letter => {
+    const root = `${letter}:\\`
+    try {
+      await access(root, fsConstants.R_OK)
+      return root
+    } catch {
+      return undefined
+    }
+  })
+  const found = await Promise.all(probes)
+  return found.filter((root): root is string => root !== undefined).map(name => ({ name, dir: true }))
+}
+
+/**
+ * 判定一个条目是不是目录
+ *
+ * 只对符号链接补 `stat`，见文件头第 3 条。
+ * @param dir 所在目录
+ * @param entry readdir 给出的条目
+ * @param windows 是否按 Windows 处理
+ * @returns 是否为目录
+ */
+async function isDirEntry(dir: string, entry: Dirent, windows: boolean): Promise<boolean> {
+  if (!entry.isSymbolicLink()) return entry.isDirectory()
+  try {
+    return (await stat(pathOf(windows).join(dir, entry.name))).isDirectory()
+  } catch {
+    // 悬空链接：当作普通条目，不报错也不当目录 —— 点不进去是对的
+    return false
+  }
+}
+
+/**
+ * 排序：目录在前，同类按名称（`localeCompare` + `numeric`，故 `f2` 在 `f10` 之前）
+ *
+ * **中文名排在英文名之前不是缺陷** —— CLDR 的中文规则把汉字整块提到拉丁字母之前。
+ * 要改成「英文在前」得在此处显式加一层「是否以 ASCII 起头」的比较键，而不是换 locale。
+ * @param a 左项
+ * @param b 右项
+ * @returns 比较结果
+ */
+function compareEntries(a: BrowseEntry, b: BrowseEntry): number {
+  if (a.dir !== b.dir) return a.dir ? -1 : 1
+  return a.name.localeCompare(b.name, "zh-Hans-CN", { numeric: true })
+}
+
+/**
+ * 列举一个目录
+ *
+ * @param input 要列举的绝对路径；空或缺省时，Windows 上列举盘符、其余系统列举根目录
+ * @param windows 是否按 Windows 处理，缺省取当前平台。仅为让用例能同时覆盖两种行为
+ * @returns 列举结果
+ */
+export async function browseDirectory(input: string | undefined, windows = process.platform === "win32"): Promise<BrowseResult> {
+  const path = pathOf(windows)
+  const raw = (input ?? "").trim()
+
+  if (raw === "") {
+    if (windows) {
+      return { ok: true, listing: { path: "", entries: await listDrives(), truncated: false, sep: path.sep } }
+    }
+    return read("/", windows)
+  }
+
+  if (!path.isAbsolute(raw)) {
+    return {
+      ok: false,
+      status: 400,
+      message: `只接受绝对路径：${raw} 是相对路径，而它的基准（内核进程的工作目录）在面板上看不到`
+    }
+  }
+
+  return read(path.resolve(raw), windows)
+}
+
+/**
+ * 真正读一次目录
+ * @param target 已规范化的绝对路径
+ * @param windows 是否按 Windows 处理
+ * @returns 列举结果
+ */
+async function read(target: string, windows: boolean): Promise<BrowseResult> {
+  let raw: Dirent[]
+  try {
+    raw = await readdir(target, { withFileTypes: true })
+  } catch (err) {
+    const code = errorCode(err) ?? ""
+    const known = CODE_TABLE[code]
+    if (known !== undefined) return { ok: false, status: known.status, message: `${target} ${known.text}` }
+    return { ok: false, status: 500, message: `读取 ${target} 失败：${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  const entries: BrowseEntry[] = []
+  for (const item of raw) {
+    const link = item.isSymbolicLink()
+    const dir = await isDirEntry(target, item, windows)
+    entries.push(link ? { name: item.name, dir, link: true } : { name: item.name, dir })
+  }
+  entries.sort(compareEntries)
+
+  // 先排序再截断：反过来的话「截掉的是哪些」取决于文件系统给出的顺序，
+  // 同一个目录两次请求可能截到不同的一批
+  const truncated = entries.length > MAX_ENTRIES
+  const parent = parentOf(target, windows)
+  return {
+    ok: true,
+    listing: {
+      path: target,
+      ...(parent === undefined ? {} : { parent }),
+      entries: truncated ? entries.slice(0, MAX_ENTRIES) : entries,
+      truncated,
+      sep: pathOf(windows).sep
+    }
+  }
+}