跳到正文

让浏览器插件调用本地能力:Native Host 的边界和协议(3):能力注册表与权限边界

让浏览器插件调用本地能力:Native Host 的边界和协议

  1. Native Messaging 通道与宿主选型
  2. 从 ping 到本机安装与诊断
  3. 能力注册表与权限边界(当前)

Native Messaging 让浏览器扩展与本机程序交换带长度前缀的 JSON 消息。多个扩展复用同一个 Host 时,还需要约定每条消息能调用什么能力、参数是否合法、失败怎样返回。这里讨论 method 分发、参数校验、错误、缓存和授权;通道与宿主选型见第一篇,ping demo 与本机安装见第二篇。能力注册表属于项目封装,不是浏览器规范自动提供的功能。

业务能力需要自己的校验与授权

通用 Native Host 的能力分发

多个扩展需要调用不同本地能力时,可以复用一个 Host。我们的方案把 host 做成能力分发层:扩展仍然只连接一个 native messaging host,host 内部再按 method 找到具体能力,并统一处理参数、错误、诊断和权限边界。

多个扩展复用同一个 Host

最小 demo 只需要扩展发一条 JSON,host 做一件事,再返回结果。这个 host 可以是 Python 脚本、Node 程序、Swift 程序,也可以是 Rust 二进制。

项目从右键复制 GIF 起步,后面还可能接本地 CLI、网络诊断、缓存清理、安装 doctor、二进制版本检查。把每个功能都写成一个独立 host,会带来重复的安装、协议维护和分散的权限边界:

  • 安装重复:每个 host 都要处理 manifest、浏览器差异、扩展 ID 和更新。
  • 协议重复:每个功能都要重新定义请求、返回值、错误和日志。
  • 风险分散:剪贴板、文件系统、命令行工具的权限边界散在不同程序里,很难统一审计。

本文采用的是「扩展 + JSON 请求 + Native Host + 能力注册表」这条实现路线,能力注册表和 native.doctor / clipboard.copyFile 等能力都属于项目增加的工程层。当前仓库可以同时保留解释型和编译型两个 host 落点,用同一套协议验证安装、剪贴板和 doctor 能力。Native Messaging 规范本身只要求浏览器能按 manifest 启动本机程序,并用 stdio 交换带长度前缀的 JSON 消息。

在这条方案里,扩展侧负责浏览器里的上下文:用户点了哪个右键菜单、当前页面 URL 是什么、要处理哪个资源、用户是否主动触发了动作。Host 负责浏览器碰不到的那层系统能力:本地文件、剪贴板、命令行工具、系统目录、注册表、诊断信息。

中间的业务协议仍然很薄。扩展发出去的是 JSON 请求,shell 字符串不应该透传给 host。host 回来的内容也要按 Native Messaging 的帧格式写入,普通日志不能混进 stdout。

Host 不能做成 raw shell

Native Messaging 最大的诱惑,是把本机端做成一个命令转发器:

{
  "method": "shell.run",
  "params": {
    "command": "some-cli --flag value"
  }
}

扩展 ID 白名单只限制入口来源,不能校验消息内容。内容脚本会接触网页,扩展构建链路可能受供应链影响,配置或消息转发也可能把不该传的字段带到 host。host 如果看见 command 字符串就执行,网页输入或扩展缺陷就可能变成本机命令执行。

allowed_origins 只能说明「哪个扩展可以连接这个 host」,不能证明每一条请求都安全。它是入口白名单,不是命令授权系统。

更稳的做法是让 host 暴露一组明确能力。扩展发的是 method + params,host 根据 method 找到具体 handler。每个 handler 自己校验参数、判断权限、记录审计信息,再决定能不能执行。

{
  "id": "copy-1",
  "method": "clipboard.copyFile",
  "params": {
    "path": "<CACHE_FILE_PATH>",
    "mime": "image/gif",
    "sourceUrl": "https://example.com/a.gif"
  }
}

按 method 分发后,每个能力都可以单独设置安全边界。

clipboard.copyFile 只应该写受控缓存目录里的文件,不应该允许任意本机路径。network.getInterfaces 可以读取网卡信息,但应该返回脱敏后的摘要。command.request 如果真的存在,也应该先经过策略引擎,而不是直接拼 shell。

能力注册表让 Host 可以持续扩展

host 一旦要同时服务剪贴板、CLI、诊断和缓存,就需要把三层代码分开:

  • 协议层:负责读写 Native Messaging 帧,处理 id、method、params、result、error。
  • 能力注册表:负责把 method 映射到 handler,并统一做 schema 校验、错误包装、日志和版本兼容。
  • 能力实现:真正调用剪贴板、文件系统、命令行工具、系统 API 或网络接口。

Host 做成能力内核

native.doctor 这类只读诊断请求可以这样写:

{
  "id": "doctor-1",
  "method": "native.doctor",
  "params": {
    "browser": "edge",
    "extensionId": "<EXTENSION_ID>"
  }
}

返回值也保持统一:

{
  "id": "doctor-1",
  "ok": true,
  "result": {
    "hostVersion": "0.2.0",
    "manifestFound": true,
    "originAllowed": true
  }
}

失败时不要只回一段字符串。错误也应该结构化,至少包含稳定错误码、面向用户的短提示、面向调试的细节。

{
  "id": "copy-1",
  "ok": false,
  "error": {
    "code": "clipboard.file_not_found",
    "message": "要写入剪贴板的文件不存在",
    "details": {
      "path": "<CACHE_FILE_PATH>"
    }
  }
}

这样扩展 UI 才能把错误分成「需要安装 host」「host 版本太低」「扩展 ID 不匹配」「文件已被清理」「系统剪贴板写入失败」这些不同状态,而不是给用户一个模糊的失败弹窗。

动态能力要停在参数层

如果以后可能调用很多本地工具,host 能不能完全不改,只让扩展动态传?

可以做一部分,但动态边界要停在参数、策略和组合方式上,不能变成任意代码执行。

安全一点的动态请求仍然是结构化的:

{
  "id": "run-1",
  "method": "command.request",
  "params": {
    "tool": "local-worker",
    "args": ["--print"],
    "cwd": "<PROJECT_PATH>",
    "stdin": "请分析这次构建失败原因",
    "intent": "读取项目并给出分析",
    "riskHints": ["readOnly", "networkMayBeUsed"]
  }
}

这个请求里没有 raw shell 字符串。tool 必须命中 host 已知的工具表,args 必须按数组传递,cwd 必须落在允许目录里,riskHints 只能作为提示,真正的风险判断仍由 host 的 policy 决定。

host 可以内置几类稳定 primitive:

  • 启动已登记的本地 CLI。
  • 给 CLI 传参数数组和 stdin。
  • 限制工作目录。
  • 设置超时、输出大小和环境变量白名单。
  • 要求用户确认高风险动作。
  • 记录调用日志和退出码。

扩展可以动态组合这些 primitive,但不能传一段新的 JS、PowerShell、bash 或任意 shell 字符串让 host 执行。这样 host 确实需要不断增加基础能力,但不需要为了每个 UI 按钮都写一份新通信逻辑。

这也是「host 解耦」比较现实的含义:host 的协议层和分发层尽量稳定,能力层按风险逐步增加。host 仍然会演进,但每次业务功能不必都改动通信骨架。

剪贴板能力只是一个例子

GIF 复制问题正好卡在这条边界上。

纯扩展可以拿到图片 URL,也可以写 text/html、text/plain 或部分浏览器支持的自定义 Web 剪贴板格式。但它不能像桌面程序那样稳定写 Windows CF_HDROP 文件列表,也不能直接操作 macOS Pasteboard 里的 file URL 或 GIF 类型。

从这个角度看,clipboard.copyFile 比 copyGif 更值得沉淀。GIF 只是第一种文件,后面也可能是 WebP、视频片段、下载后的附件、截图文件或其他目标应用更愿意按文件处理的资源。

clipboard.copyFile 所在的文件复制链路,需要扩展与 host 分别承担以下职责:

  • 扩展确认这是用户主动触发的复制动作。
  • host 下载或接收文件,并校验大小、MIME、magic bytes 和扩展名。
  • 文件进入受控缓存目录,而不是一次调用结束就删除。
  • Windows 写文件列表,macOS 写 file URL 或合适的 pasteboard 类型。
  • host 返回写入结果、缓存路径、过期时间和可诊断状态。
  • 清理任务只删除自己管理的缓存文件。

这样设计以后,GIF 复制只是能力内核上的一个 handler。后面要加「复制图片文件」「复制本地日志」「把 CLI 输出保存成文件再复制」这类功能,也能沿用同一套协议和缓存策略。

第一版先收紧能力边界

Native Messaging 让扩展可以调用本机能力,也把权限判断留给了 host。新能力进 host 前,我会先问这几个问题:

  • 纯扩展或 Web API 是否已经能安全完成?能完成就别进 host。
  • 这个能力是否必须访问操作系统、本地文件、系统剪贴板或本机 CLI?
  • 请求能不能写成结构化 method,而不是 raw shell?
  • 参数 schema 能不能清楚描述,错误能不能稳定返回?
  • 是否需要用户确认、目录限制、大小限制、超时、脱敏或审计?
  • Windows 和 macOS 是否都能给出明确安装和诊断路径?
  • 失败时扩展 UI 能不能告诉用户下一步做什么?

这些要求需要落实到 host 的参数校验、权限策略、安装与诊断逻辑中。

第一版不急着开放本地 CLI,也不急着做动态命令平台。先把 clipboard.copyFile、native.doctor、安装诊断和缓存生命周期跑稳。等这条链路能稳定工作,再让本地 CLI 调用进入策略层。后续接入剪贴板、网络诊断或文件缓存时,可以复用通信和诊断层,分别补上各自的参数校验与权限限制。

总结

本文在通道上增加了语言无关的业务协议、能力注册表和具体 handler,让多个扩展复用安装、错误与诊断。入口白名单仍不能替代每次调用的授权,能力要按结构化参数、受控目录、超时和风险策略执行;文件剪贴板还必须管理缓存生命周期,不能把 Host 变成 raw shell 转发器。