Electron 安全实践：OpenExternalPermissionRequest 对象与 openExternal 权限请求拦截机制

本文围绕 Electron 的 OpenExternalPermissionRequest 对象展开，说明它由哪些字段构成、在 session.setPermissionRequestHandler 的权限请求流程中于何时出现，并结合仓库源码剖析 externalURL 字段的底层填充位置与 blink::PermissionType::OPEN_EXTERNAL 的触发链路，帮助开发者在应用内实现"打开外部链接前先审查目标 URL"的安全拦截能力。

对象定义与字段说明

OpenExternalPermissionRequest 是 Electron 主进程 API 中的一个结构对象（Structure Object），它继承自 PermissionRequest 对象，并在其基础上增加了一个可选字段。完整定义见 docs/api/structures/open-external-permission-request.md：

字段	类型	是否必填	说明
externalURL	string	可选（optional）	本次 openExternal 请求的目标 URL

由于它继承自 PermissionRequest，因此对象中还包含两个来自父类的公共字段，定义于 docs/api/structures/permission-request.md：

字段	类型	说明
requestingUrl	string	发起请求的 frame 最近一次加载的 URL
isMainFrame	boolean	发起请求的 frame 是否为主 frame（main frame）

这两个继承字段在安全审查中非常有用：requestingUrl 告诉你"是哪个页面"想打开外部链接，isMainFrame 则帮你区分是主文档行为还是来自 iframe 子文档的行为——后者通常是更值得警惕的来源。

它出现在哪个 API 中：setPermissionRequestHandler

OpenExternalPermissionRequest 的正式使用入口是 session 模块的 setPermissionRequestHandler 方法，其完整文档见 docs/api/session.md。该 API 的 details 参数被声明为多种权限请求对象之一，其中就包括 OpenExternalPermissionRequest：

* details PermissionRequest | FilesystemPermissionRequest |
  MediaAccessPermissionRequest | OpenExternalPermissionRequest
  - Additional information about the permission being requested.

在 setPermissionRequestHandler 的权限类型（permission）列表中，openExternal 被明确列出：

openExternal - Request to open links in external applications.（请求在外部应用程序中打开链接）

也就是说，当渲染进程中的页面通过 shell.openExternal 请求在系统默认浏览器等外部应用中打开一个 URL 时，Chromium 会先向宿主（Electron 主进程）发起一次权限检查；你注册的权限请求处理器就能收到一条 permission === 'openExternal' 的事件，并且此时 details 中携带的正是 OpenExternalPermissionRequest 对象——通过其中的 externalURL 字段即可获知页面想打开的具体目标地址，再决定是否放行（callback(true)）或拒绝（callback(false)）。

官方文档同时提醒：要实现完整的权限处理，除了 setPermissionRequestHandler 之外通常还需配合实现 setPermissionCheckHandler，因为大多数 Web API 会先做 permission check，被拒绝后才发起 permission request。

源码实现：externalURL 在哪里被填充

仓库源码可以精确印证文档中"继承 PermissionRequest、新增 externalURL"这一结构描述。在 shell/browser/web_contents_permission_helper.cc 中，WebContentsPermissionHelper 实现了专用的权限请求入口：

void WebContentsPermissionHelper::RequestOpenExternalPermission(
    content::RenderFrameHost* requesting_frame,
    base::OnceCallback<void(bool)> callback,
    bool user_gesture,
    const GURL& url) {
  base::DictValue details;
  details.Set("externalURL", url.spec());
  RequestPermission(requesting_frame, blink::PermissionType::OPEN_EXTERNAL,
                    std::move(callback), user_gesture, std::move(details));
}

从这段实现可以看出三点关键事实：

1. externalURL 的取值：直接来自发起请求时传入的 url.spec()，即目标 URL 的完整字符串形式，与文档字段描述完全一致；
2. 权限类型标识：内部使用 Chromium 的 blink::PermissionType::OPEN_EXTERNAL，这正是它区别于 media、geolocation 等其他权限、最终在 JS 层映射为 'openExternal' 字符串的依据；
3. details 的组装方式：externalURL 被塞入 base::DictValue details，随 RequestPermission 一起上抛；requestingUrl 与 isMainFrame 等父类字段则由通用的 RequestPermission 流程基于 requesting_frame 统一填充，最终序列化为 JS 对象传给你的回调函数。

另外，从源码结构看，浏览器侧的权限拦截入口位于 shell/browser/electron_browser_client.cc（该文件包含对 OpenExternal 权限流程的引用），它作为 Chromium 的 BrowserClient 实现承接渲染进程的权限请求并转交给 WebContentsPermissionHelper；而 JS 侧 shell.openExternal 方法本身的注册则在 shell/common/api/electron_api_shell.cc 中完成：

dict.SetMethod("openExternal", &OpenExternal);

各平台实际"打开外部应用"的动作（浏览器、终端命令、macOS 的 open 等）由 shell/common/platform_util_linux.cc、shell/common/platform_util_mac.mm、shell/common/platform_util_win.cc 等平台工具实现，但这些发生在权限被批准之后。

实战示例：拦截并审查 openExternal 请求

基于上述机制，一个典型的安全用法是：只允许白名单域名或 http/https 协议的链接在外部打开，其余一律拒绝。以下示例基于 setPermissionRequestHandler 的官方文档签名（webContents, permission, callback, details）编写：

const { session, shell } = require('electron')

// 主进程：注册权限请求处理器
session.defaultSession.setPermissionRequestHandler(
  (webContents, permission, callback, details) => {
    if (permission === 'openExternal') {
      // details 此时为 OpenExternalPermissionRequest
      // 字段：externalURL（可选）、requestingUrl、isMainFrame
      const externalURL = details.externalURL

      // 只放行 http/https 协议，拒绝 file://、javascript: 等
      if (
        externalURL &&
        (externalURL.startsWith('http://') || externalURL.startsWith('https://'))
      ) {
        return callback(true)
      }
      console.warn('拒绝打开外部链接：', externalURL, '来源：', details.requestingUrl)
      return callback(false)
    }

    // 其他权限按默认策略处理（可按需收紧）
    callback(true)
  }
)

实际开发中还可以结合继承字段做更细粒度的策略，例如：

• 当 details.isMainFrame === false 时，说明打开外部链接的请求来自 iframe，可以更严格地拒绝；
• 结合 details.requestingUrl 判断是哪些业务页面触发了外链，便于审计日志；
• 放行后如需自行打开链接（而非交由默认流程），主进程仍可直接调用 shell.openExternal(url)，其行为定义见 docs/api/shell.md，对应测试覆盖在 spec/api-shell-spec.ts。

需要说明的是，externalURL 在 API 签名中标记为可选字段：从源码实现看该字段在 RequestOpenExternalPermission 中总会写入 url.spec()，但防御性编程时仍建议对 externalURL 取空做兜底处理。

为什么这个对象对桌面应用安全很重要

shell.openExternal 是 Electron 桌面应用与操作系统交互的通道之一——页面一旦能任意打开外部 URL，攻击面就从"渲染内容"扩展到了"系统级行为"（打开本地文件、唤起协议处理器、诱导用户跳转钓鱼站点等）。OpenExternalPermissionRequest 把"打开谁、从哪个页面发起、是否主文档"这三类关键信息一次性交给主进程决策，使得：

1. 白名单/黑名单策略可行：依据 externalURL 精确控制可打开的目标；
2. 来源追溯可行：依据 requestingUrl 与 isMainFrame 定位发起方；
3. 统一收口可行：所有经 openExternal 通道的外链行为都汇入同一权限流程（blink::PermissionType::OPEN_EXTERNAL），不需要在多处重复检查。

更完整的渲染进程安全模型（包括 context isolation、禁用 Node 集成等）可参考官方安全文档 docs/tutorial/security.md。

小结

• OpenExternalPermissionRequest 继承 PermissionRequest，唯一新增字段为可选的 externalURL，标识 openExternal 请求的目标 URL；
• 它经由 session.setPermissionRequestHandler 的 details 参数送达主进程，对应 permission === 'openExternal' 的事件；
• 源码层面，该对象在 shell/browser/web_contents_permission_helper.cc 的 RequestOpenExternalPermission 中被组装（details.Set("externalURL", url.spec()) 并使用 blink::PermissionType::OPEN_EXTERNAL），JS 入口 shell.openExternal 注册于 shell/common/api/electron_api_shell.cc；
• 结合继承的 requestingUrl、isMainFrame 字段，可实现按来源、按协议、按 frame 级别的多维度外链打开策略。