os.Root 怎样为插件读取建立目录边界

插件读取文件时，最容易留下的缺口不是把 ../ 忘了过滤，而是先检查路径、再用普通 os.Open 打开，中间给了符号链接和目录重命名可乘之机。Go 1.24 的 os.Root 把“只能在某个目录树内操作”放进文件打开过程：先用 os.OpenRoot 固定插件目录，再用 root.Open、root.ReadFile 或 root.FS() 读取相对路径。

官方文档：https://pkg.go.dev/os#Root

先把插件目录变成 Root 边界

假设每个插件都有一个独立目录，插件上报的 manifest.json、模板或缓存文件都只能从该目录读取。不要把用户输入拼到宿主机绝对路径上，也不要把“清理字符串”和“真正打开文件”拆成两个安全步骤。

package pluginfs

import (
    "fmt"
    "io"
    "os"
)

func ReadPluginFile(rootDir, name string) ([]byte, error) {
    // 打开插件专属目录，后续 Root 方法都以它为边界。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return nil, fmt.Errorf("open plugin root: %w", err)
    }
    // Root 持有目录句柄；无论读取成功还是失败都要释放它。
    defer root.Close()

    // name 是插件提供的相对路径，由 Root 在打开时做越界判断。
    f, err := root.Open(name)
    if err != nil {
        return nil, fmt.Errorf("open plugin file %q: %w", name, err)
    }
    // 文件句柄与 Root 是两层资源，不能只关闭 Root。
    defer f.Close()

    data, err := io.ReadAll(f)
    if err != nil {
        return nil, fmt.Errorf("read plugin file %q: %w", name, err)
    }
    return data, nil
}

这里没有先调用 filepath.Clean 再自行判断。Root 允许根内的相对路径折返，例如 a/../b 仍在边界内；但指向根外的 .. 或符号链接会失败。这样“检查”和“打开”由同一个受边界约束的操作完成，能避开单纯路径清洗无法覆盖的 TOCTOU 场景。

读取接口要围绕 Root 组织

插件加载器如果只读一个文件，root.Open 足够；如果已有 io/fs 风格接口，则把 root.FS() 传进去。这样目录遍历、读取和后续的 fs.ReadFile 仍然使用同一个边界，不需要把根目录重新暴露为字符串。

package pluginfs

import (
    "fmt"
    "io/fs"
    "os"
)

func ReadManifest(rootDir string) ([]byte, error) {
    // Root.FS 返回只覆盖插件目录树的 fs.FS。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return nil, fmt.Errorf("open plugin root: %w", err)
    }
    defer root.Close()

    // 读取固定的插件文件，路径仍然相对于 Root，而不是进程工作目录。
    data, err := fs.ReadFile(root.FS(), "manifest.json")
    if err != nil {
        return nil, fmt.Errorf("read manifest: %w", err)
    }
    return data, nil
}

若需要创建子目录，可使用 root.OpenRoot("assets") 得到更窄的子 Root；若只是判断文件信息，用 root.Stat 或 root.Lstat。不要把 root.Name() 拼回普通路径后再交给 os.Open，那会重新丢掉边界保证。

几个容易误判的边界

另外，官方文档对平台有明确限制：Unix 上 Chmod、Chown、Chtimes 存在竞态风险；GOOS=js 的符号链接校验也不能完全避免 TOCTOU。文章标题讨论的是“插件读取”，因此优先使用 Open、ReadFile、Stat 和 FS，不要把它误当成所有文件管理操作的通用沙箱。

接入前的检查清单

1. 运行环境使用 Go 1.24 或更高版本，并确认目标 GOOS 的 Root 能力。
2. 每次插件任务只打开自己的根目录，成功后用 defer root.Close() 收口。
3. 所有插件文件名都交给 Root 方法解析，拒绝任何“失败后改用普通路径”的兜底。
4. 将 Root 或 Root.FS 传入读取层，不传递可重新拼接的宿主机绝对路径。
5. 若威胁模型包含挂载点、设备文件或容器逃逸，再叠加操作系统权限和容器隔离。

常见问题

os.Root 能替代所有路径校验吗？

它覆盖目录树内的打开与访问边界，但业务仍应校验文件类型、大小、格式和插件权限；它不是业务授权系统。

Root 可以安全地跟随根目录内的符号链接吗？

可以跟随不越界的链接，指向根外的链接会被拒绝；如果不需要链接语义，可在业务层额外禁止链接。

为什么不直接用 filepath.Join 加 filepath.IsLocal？

字符串校验适合较简单的输入约束，但无法独立解决检查与打开之间的竞态；Root 将目录句柄和受约束的打开操作放在一起。