Electron PermissionRequest 对象详解：setPermissionRequestHandler 的 origin 判定字段与权限请求源码管线

PermissionRequest 是 Electron 权限体系中最基础的一个结构体对象，它作为 details 参数被传入 session.setPermissionRequestHandler() 的回调，用于向应用标识“是谁、在哪个上下文发起了这次权限请求”。其中 requestingUrl 与 isMainFrame 两个字段是区分主框架与子框架请求、防止子框架冒领权限的关键依据。本文以 permission-request.md 的结构定义为主体，结合 Electron 主进程的 C++ 实现与官方测试用例，完整拆解这两个字段的赋值来源、派生对象体系、默认放行逻辑与实战使用方式。

PermissionRequest 对象字段定义

根据官方结构体文档（docs/api/structures/permission-request.md），该对象仅包含两个字段，但二者共同构成了权限决策的最小上下文：

字段	类型	含义
requestingUrl	string	发起请求的 frame 最近一次加载的 URL（The last URL the requesting frame loaded）
isMainFrame	boolean	发起请求的 frame 是否为主框架（Whether the frame making the request is the main frame）

这个对象的定位可以从 session.md 中 setPermissionRequestHandler(handler) 的 details 参数签名看出：

details PermissionRequest | FilesystemPermissionRequest | MediaAccessPermissionRequest | OpenExternalPermissionRequest

也就是说，PermissionRequest 是所有权限请求细节的基类，不同权限类型会派生出携带更多字段的子对象。

官方文档对这两个字段的实战意义有一处重要提示（session.md）：当请求来自子框架时，回调第一个参数 webContents.getURL() 返回的是主框架所在页面的 URL，因此应当使用 requestingUrl 而不是 webContents.getURL() 来判断请求来源。这也是该对象存在的核心价值。

源码级赋值：两个字段的真实来源

requestingUrl 与 isMainFrame 的赋值发生在主进程的权限管理器 electron_permission_manager.cc 中。

请求路径（Request 路径）

在 ElectronPermissionManager::RequestPermissionsWithDetails() 中（electron_permission_manager.cc），当应用注册了 request handler 后，Electron 会为每个待决策的权限组装 details 字典：

details.Set("requestingUrl", render_frame_host->GetLastCommittedURL().spec());
details.Set("isMainFrame", render_frame_host->GetParent() == nullptr);

（参见 electron_permission_manager.cc）

可以逐字印证文档定义：

• requestingUrl 来自 Chromium RenderFrameHost::GetLastCommittedURL()，即该 frame 最近一次提交（committed）的文档 URL。注意“last committed”语义：它反映的是 frame 当前实际加载的页面，而非用户可见的地址栏 URL，页面内导航尚未完成提交时可能仍是旧值。
• isMainFrame 来自 render_frame_host->GetParent() == nullptr，即判断该 frame 在渲染进程 frame 树中是否存在父 frame。顶层页面为 true，任何 <iframe>/<webview> 内嵌文档均为 false。

随后 handler 通过 base::BindRepeating 逐个权限回调，JS 侧最终收到 (webContents, permission, callback, details) 四个参数（electron_permission_manager.h 定义了 RequestHandler 的底层签名）。

检查路径（Check 路径）

同样的两个字段也出现在 setPermissionCheckHandler 的 details 中，赋值逻辑在 CheckPermissionWithDetails()（electron_permission_manager.cc）：

if (render_frame_host) {
  details.Set("requestingUrl",
              render_frame_host->GetLastCommittedURL().spec());
}
details.Set("isMainFrame",
            render_frame_host && render_frame_host->GetParent() == nullptr);

两处差异值得注意：

1. check 路径下 requestingUrl 是可选字段——当 render_frame_host 为 nullptr 时不设置，这对应 session.md 中“cross-origin sub frames making permission checks 不会提供 requestingUrl”的说明；此时应改用 embeddingOrigin / requestingOrigin 判断来源。
2. 即使 frame 存在，isMainFrame 的判定公式也完全一致，保证了 request 与 check 两个阶段看到相同的框架上下文。

派生对象：不同权限类型的扩展 details

PermissionRequest 之外的三个同族结构体均“extends PermissionRequest”，在基类两字段之上补充特定信息：

MediaAccessPermissionRequest

文档定义（media-access-permission-request.md）：

• securityOrigin string（可选）- 请求的安全来源。
• mediaTypes string[]（可选）- 请求的媒体访问类型，元素为 video 或 audio。对 media 权限分别指摄像头与麦克风；对 display-capture 权限则指屏幕/窗口/标签页画面及其音频。

其赋值在 web_contents_permission_helper.cc 的 RequestMediaAccessPermission() 中：

base::DictValue details;
base::ListValue media_types;
if (blink::IsAudioInputMediaType(request.audio_type))
  media_types.Append("audio");
if (blink::IsVideoInputMediaType(request.video_type))
  media_types.Append("video");
details.Set("mediaTypes", std::move(media_types));
details.Set("securityOrigin", request.security_origin.spec());

这里还体现了近期的一项重要行为变更：屏幕/窗口/标签页捕获（getDisplayMedia 或带 chromeMediaSource 约束的 getUserMedia）现在以 display-capture 权限类型上报，而摄像头/麦克风上报为 media（变更说明见 breaking-changes.md）。应用若希望“允许摄像头麦克风、但单独控制屏幕共享”，必须在 handler 中区分这两类权限，官方文档给出了对应示例（session.md）：

const { session } = require('electron')

session.defaultSession.setPermissionRequestHandler((webContents, permission, callback, details) => {
  if (permission === 'media') {
    // 摄像头 / 麦克风。details.mediaTypes 列出具体请求了哪些
    return callback(true)
  }
  if (permission === 'display-capture') {
    // 屏幕、窗口或标签页捕获
    return callback(new URL(details.requestingUrl).origin === 'https://meet.example.com')
  }
  callback(false)
})

注意示例中正是用 details.requestingUrl 解析 origin 做白名单——这正是基类字段的典型用法。

OpenExternalPermissionRequest

文档定义（open-external-permission-request.md）：

• externalURL string（可选）- openExternal 请求的 URL。

赋值见 web_contents_permission_helper.cc 的 RequestOpenExternalPermission()：details.Set("externalURL", url.spec())，并以 OPEN_EXTERNAL 权限类型发起。当页面试图在外部应用中打开链接时，handler 即可拿到目标 URL 做协议/域名校验。

FilesystemPermissionRequest

文档定义（filesystem-permission-request.md）：

• filePath string（可选）- fileSystem 请求的路径。
• isDirectory boolean（可选）- 请求对象是否为目录。
• fileAccessType string（可选）- 访问类型，取值 writable 或 readable。

对应 Web File System API 的读/写/目录操作，handler 可以按路径与访问类型做细粒度放行。

快速对照表

权限类型	details 对象	基类字段之外新增
media / display-capture	MediaAccessPermissionRequest	securityOrigin、mediaTypes（video/audio）
openExternal	OpenExternalPermissionRequest	externalURL
fileSystem	FilesystemPermissionRequest	filePath、isDirectory、fileAccessType
其他权限	PermissionRequest	仅 requestingUrl、isMainFrame

请求管线与默认行为：handler 未注册时会发生什么

理解 PermissionRequest 必须理解它所处的完整管线。以 web_contents_permission_helper.cc 为例，渲染侧的权限请求先经 WebContentsPermissionHelper::RequestPermission()，取出发起 frame 的最后提交 origin，再委托给 ElectronPermissionManager::RequestPermissionWithDetails()；后者（electron_permission_manager.cc）会先拦截 fenced frame 嵌套场景直接拒绝，然后进入上述 RequestPermissionsWithDetails() 组装 details 并回调 JS handler。

有几条默认行为对理解这两个字段的“可信度”很关键，均可在源码中确认：

1. 未注册 handler 时默认全部放行。 RequestPermissionsWithDetails() 中若 request_handler_.is_null()，除 macOS 上被 --disable-geolocation 禁用的 geolocation 外，所有权限直接以 GRANTED 回应（electron_permission_manager.cc）。换言之，requestingUrl/isMainFrame 只在应用显式接管权限决策后才被填充并送达 JS。
2. 清空 handler 会立即以拒绝回应所有挂起请求。 每个 PendingRequest 的初始状态是 DENIED（electron_permission_manager.cc）；SetPermissionRequestHandler(null) 时，所有尚未收到 JS 回应的 pending 请求会被直接 RunCallback() 收尾（electron_permission_manager.cc），因此文档提示“清除 handler 后请同时实现 setPermissionCheckHandler 以获得完整的权限处理”（session.md）。
3. macOS 定位权限存在命令行级强制拒绝。 注册 handler 时 Electron 会包装一层 callback：若 --disable-geolocation 开关生效，无论 JS 侧回 callback(true) 还是 callback(false)，最终一律改写为 DENIED（electron_api_session.cc；开关说明见 command-line-switches.md）。这是少数绕过 JS 决策的内置策略。
4. Session::SetPermissionRequestHandler 的入参校验。 传入值必须是 null 或函数，否则抛出 TypeError: Must pass null or function（electron_api_session.cc）。

实战用法与测试佐证

完整示例：按请求 URL 与权限类型决策

结合 session.md 的官方示例，并扩展对两个基类字段的利用：

const { session } = require('electron')

session.fromPartition('some-partition').setPermissionRequestHandler(
  (webContents, permission, callback, details) => {
    // 子框架请求时 webContents.getURL() 是主框架 URL，
    // 必须用 details.requestingUrl 判断真实来源
    const requestingOrigin = new URL(details.requestingUrl).origin

    // 子框架一律不授予敏感权限
    if (!details.isMainFrame && (permission === 'geolocation' || permission === 'notifications')) {
      return callback(false)
    }

    if (requestingOrigin === 'https://some-host' && permission === 'notifications') {
      return callback(false) // denied
    }

    callback(true)
  }
)

测试用例验证字段语义

Electron 官方测试套件对这两个字段的断言可以直接作为行为依据：

• spec/api-session-spec.ts：expect(handlerDetails!.requestingUrl).to.equal(loadUrl) —— 验证 requestingUrl 与页面实际加载的 URL 一致；spec/api-session-spec.ts 进一步断言子框架场景下 isMainFrame 为 false。
• spec/chromium-spec.ts 等用例断言主框架场景下 isMainFrame: true 且 requestingUrl 等于当前 href。

安全最佳实践

官方安全指南（tutorial/security.md）将“在所有加载远程内容的 session 上实现 ses.setPermissionRequestHandler()”列为必做项，并在 tutorial/security.md 给出最小化示例：默认拒绝，仅对特定 origin + 权限组合放行。对 PermissionRequest 两字段的工程要点可归纳为：

• 永远以 requestingUrl 作为来源判定基准，webContents 参数仅用于标识承载窗口；
• isMainFrame === false 时谨慎授予 geolocation、notifications、media、display-capture 等敏感权限；
• 对 media/display-capture 需进一步读取派生字段 securityOrigin/mediaTypes 区分设备采集与屏幕共享；
• request handler 与 check handler 需成对实现：多数 Web API 先做 permission check，检查被拒后再发起 permission request（session.md 明确指出只实现其一时权限处理不完整）。

小结

PermissionRequest 虽然只有 requestingUrl 与 isMainFrame 两个字段，却是 Electron 权限决策中判定“谁在请求”的锚点：前者由 RenderFrameHost::GetLastCommittedURL() 提供，忠实反映发起 frame 的当前文档；后者由 frame 树父节点是否为空判定。二者在主进程 ElectronPermissionManager 中统一注入 details，经 MediaAccessPermissionRequest、OpenExternalPermissionRequest、FilesystemPermissionRequest 三个派生对象扩展到媒体、外链、文件系统三类高频场景。正确消费这两个字段并配合派生细节，是构建按 origin 白名单、按框架层级、按权限类型差异化放行的权限体系的基础。