Electron FilesystemPermissionRequest 对象详解：fileSystem 权限请求的 details 结构、判定字段与源码级实现

FilesystemPermissionRequest 是 Electron 权限系统中专门用于描述 Web File System API（如 showDirectoryPicker、FileSystemFileHandle 相关能力）读写请求的详情对象。它在渲染进程发起 fileSystem 类型权限请求时，作为 session.setPermissionRequestHandler 的 details 参数传递给主进程，携带 filePath、isDirectory、fileAccessType 三个关键字段。读完本文，你将掌握该对象每个字段的准确含义与来源、如何基于它实现按路径和读写模式精细授权的权限处理器，以及 Electron 底层（shell/browser/file_system_access/）如何构造、传递和最终回收这些权限授予。

一、FilesystemPermissionRequest 对象定义

该对象的完整定义见 filesystem-permission-request.md：

属性	类型	是否可选	说明
filePath	string	optional	该 fileSystem 请求所针对的路径
isDirectory	boolean	optional	该 fileSystem 请求指向的是否为目录
fileAccessType	string	optional	该 fileSystem 请求的访问类型，取值为 writable 或 readable

它继承自 PermissionRequest 对象，因此同时携带两个基础字段：

继承属性	类型	说明
requestingUrl	string	发起请求的 frame 最近加载的 URL
isMainFrame	boolean	发起请求的 frame 是否为主 frame

三个字段都标注为 optional，这与它的使用位置有关：在 session.md 中，setPermissionRequestHandler 的 details 参数声明为 PermissionRequest | FilesystemPermissionRequest | MediaAccessPermissionRequest | OpenExternalPermissionRequest 的联合类型——只有当 permission 参数为 fileSystem 时，details 才会是 FilesystemPermissionRequest 并携带上述三个可选字段；其他权限类型（如 media、display-capture、openExternal）则携带对应的其他结构。

二、字段在 C++ 侧的构造位置

从源码看，这三个字段并非文档层面的约定，而是由 Electron 的 FileSystemAccessPermissionContext 直接构造的。在 file_system_access_permission_context.cc 中，PermissionGrantImpl::RequestPermission 在把请求转发给权限管理器前，构造了如下字典：

base::DictValue details;
details.Set("filePath", base::FilePathToValue(path_info_.path));
details.Set("isDirectory", handle_type_ == HandleType::kDirectory);
details.Set("fileAccessType",
            type_ == GrantType::kWrite ? "writable" : "readable");

const blink::PermissionType type = blink::PermissionType::FILE_SYSTEM;
permission_manager->RequestPermissionWithDetails(
    content::PermissionDescriptorUtil::
        CreatePermissionDescriptorForPermissionType(type),
    rfh, origin, rfh->HasTransientUserActivation(), std::move(details), ...);

这段代码直接印证了文档中的全部细节：

• 权限类型常量是 blink::PermissionType::FILE_SYSTEM，对应 JS 侧 permission 参数收到的字符串 fileSystem；
• isDirectory 由底层句柄类型 HandleType::kDirectory / kFile 决定；
• fileAccessType 由授予类型 GrantType::kWrite / kRead 二选一映射为 "writable" / "readable"，不存在第三种取值。

同样的三个键也在 PermissionGrantImpl::GetStatus（file_system_access_permission_context.cc）中再次构造，用于在已有授权状态下执行权限检查（check）而非权限请求（request）：

bool granted = permission_manager->CheckPermissionWithDetails(
    blink::PermissionType::FILE_SYSTEM, nullptr, origin_.GetURL(),
    std::move(details));
return granted ? PermissionStatus::GRANTED : PermissionStatus::DENIED;

这解释了 Electron 文档反复强调的“request 与 check 必须配对实现”：Web 端多数 API 会先做 permission check（走 setPermissionCheckHandler），检查被拒后再触发 permission request（走 setPermissionRequestHandler），两条路径共用同一份 details 结构。

三、何时会收到 FilesystemPermissionRequest

阅读 RequestPermission 的守卫逻辑（file_system_access_permission_context.cc）可以看到，并不是所有来自渲染进程的 fileSystem 请求都会到达你的 JS 处理器，以下情况会被提前拦截并以特定结果码返回，你的 handler 不会收到 details：

拦截条件（源码行为）	返回结果码	含义
请求来自已失效的 RenderFrameHost	kInvalidFrame	frame 已不存在
frame 处于“不允许激活”的非活跃状态	kInvalidFrame	页面无法区分用户拒绝与自动拒绝
frame 嵌套在 fenced frame（隐私沙箱帧）内	kInvalidFrame	禁止 fenced frame 请求文件系统访问
要求用户激活但缺少 transient user activation	kNoUserActivation	无用户手势，不发起权限询问
frame 的 origin 与授予记录的 origin 不一致（如第三方 iframe）	kThirdPartyContext	第三方上下文不允许追加权限
已有 GRANTED 状态的授予	kRequestAborted	已授权则直接复用，不再询问

因此在主进程处理逻辑里，若长时间收不到 fileSystem 请求，可以先排查页面是否处于用户手势之外、是否来自第三方 iframe 等场景。

四、在 setPermissionRequestHandler 中消费 FilesystemPermissionRequest

details 的完整联合类型声明见 session.md（ses.setPermissionRequestHandler 小节）。一个只针对 fileSystem 权限、基于三个字段做精细判定的处理器示例：

const { session } = require('electron')

session.defaultSession.setPermissionRequestHandler(
  (webContents, permission, callback, details) => {
    if (permission !== 'fileSystem') {
      // 其他权限按需处理，这里默认拒绝
      return callback(false)
    }

    // details 即 FilesystemPermissionRequest：
    // details.filePath       - string  | 请求的路径
    // details.isDirectory    - boolean | 是否目录
    // details.fileAccessType - string  | 'writable' | 'readable'
    // 继承字段：details.requestingUrl、details.isMainFrame

    const origin = new URL(details.requestingUrl).origin
    const isWritableRequest = details.fileAccessType === 'writable'

    // 示例策略：
    // 1. 只信任受控 origin；
    // 2. 写请求只允许目录形态的受控工作区路径。
    const allowedOrigins = ['https://trusted.example.com']
    if (!allowedOrigins.includes(origin)) return callback(false)
    if (isWritableRequest && !details.filePath.startsWith('/workspace')) {
      return callback(false)
    }

    callback(true)
  }
)

注意两点：

1. 必须同时实现 setPermissionCheckHandler。session.md 明确说明“you must also implement setPermissionCheckHandler to get complete permission handling”。check handler 的 details 对象同样以可选形式携带 filePath / isDirectory / fileAccessType 三个 fileSystem 专有字段（见 session.md），与 request handler 的 FilesystemPermissionRequest 字段保持一致：

session.defaultSession.setPermissionCheckHandler(
  (webContents, permission, requestingOrigin, details) => {
    if (permission === 'fileSystem') {
      // 检查阶段同样可读取 details.filePath / isDirectory / fileAccessType
      return details?.fileAccessType !== 'writable' ||
             (details?.filePath ?? '').startsWith('/workspace')
    }
    return false
  }
)

2. 子 frame 发起的请求应以 details.requestingUrl（继承自 PermissionRequest）判断真实来源，而不是直接取 webContents.getURL()——session.md 在 handler 参数说明中对此有专门提醒。

五、配套的 file-system-access-restricted 事件：路径黑名单拦截

除权限请求/检查两条通道外，Electron 还针对“受保护路径”提供了独立的拦截事件。FileSystemAccessPermissionContext 在构造时会异步生成系统级路径黑名单（GenerateBlockPaths），当某次用户操作（如拖拽文件、打开/保存对话框选择）命中的路径被列入黑名单时，DidCheckPathAgainstBlocklist 会向对应 session 发出 file-system-access-restricted 事件（file_system_access_permission_context.cc）：

if (should_block) {
  // ... 构造 details 后：
  session->Get()->Emit(
      "file-system-access-restricted", details,
      base::BindRepeating(
          &FileSystemAccessPermissionContext::OnRestrictedPathResult, ...));
}

注意该事件的 details 是 { origin, isDirectory, path }（路径字段名为 path 而非 filePath），回调接收 'allow' | 'deny' | 'tryAgain' 三种动作，与 FilesystemPermissionRequest 的字段不完全相同，请勿混用。官方示例（session.md）展示了弹出消息框让用户三选一、再回调不同动作的完整流程。

六、授权的生命周期：自动授予、继承与回收

理解 fileAccessType 字段的实际约束力，需要看 Electron 如何判定哪些访问需要询问、哪些直接放行。GetReadPermissionGrant / GetWritePermissionGrant（file_system_access_permission_context.cc）中的规则是：

• 读权限自动授予：父目录已有可读授权时，子路径直接继承为 GRANTED（AncestorHasActivePermission，file_system_access_permission_context.cc，沿 path.DirName() 逐级上溯）；拖拽（drag & drop）获得的所有句柄自动授予读权限；
• 写权限自动授予：仅“保存”（save dialog）场景会自动授予写权限，打开（open）、拖拽、从存储恢复（load from storage）均不授予写权限；目录形态的 open/save 不自动授予读权限；
• 句柄类型变化即撤销：同一路径从目录变为文件（或反之）时，旧授权被置为 DENIED 并重建，这也是 isDirectory 必须随请求传递的原因——授权是按“路径 + 句柄类型”精确登记的。

授权并非永久有效：NavigatedAwayFromOrigin 会为离开原 origin 的 origin 启动一个 5 秒的清理定时器（常量 kPermissionRevocationTimeout = base::Seconds(5)，file_system_access_permission_context.cc），到期后 CleanupPermissions 调用 RevokeActiveGrants 将该 origin 的读/写授予统一重置为 ASK（file_system_access_permission_context.cc）。这意味着即使你在 handler 中 callback(true)，授权也仅在该 origin 存活期间有效；origin 导航离开 5 秒后，后续访问会重新走 check → request 流程，你的 handler 会再次收到同一结构的 FilesystemPermissionRequest。

七、要点小结

1. FilesystemPermissionRequest 继承 PermissionRequest，新增 filePath、isDirectory、fileAccessType（仅 writable/readable 两值）三个可选字段，完整定义见 filesystem-permission-request.md；
2. 它仅在 permission === 'fileSystem' 时作为 details 出现在 setPermissionRequestHandler 中，字段由 file_system_access_permission_context.cc 中 RequestPermission / GetStatus 直接构造，键名与文档一一对应；
3. 子 frame、无用户手势、fenced frame、第三方 origin 等请求会在到达 JS 层之前被 C++ 守卫拦截，排查“收不到请求”时应先核对这些前置条件；
4. request handler 与 check handler 需成对实现，check 的 details 也携带同名三字段；
5. 系统敏感路径的拦截走独立的 file-system-access-restricted 事件（origin / isDirectory / path + 三值回调），不要与 FilesystemPermissionRequest 的字段混淆；
6. 授权按“origin × 路径 × 句柄类型 × 读写类型”精确登记，父目录授权可被子路径继承，且 origin 导航离开约 5 秒后授权自动回收。