iTerm2 WebExtensionsFramework 权限声明指南:Manifest V3 `permissions` 字段详解与源码验证

原创2026-09-20 15:19:271,999 阅读
文章标签:桌面应用AI 应用

iTerm2 WebExtensionsFramework 权限声明指南:Manifest V3 permissions 字段详解与源码验证

本篇技术指南围绕 iTerm2 仓库内 WebExtensionsFramework 的 Manifest V3 权限体系展开,系统讲解 permissions 字段的 JSON 结构、48 个 API 权限关键字、特殊权限(activeTab、unlimitedStorage)以及权限请求时的用户体验与最佳实践;同时结合框架源码(BrowserExtensionPermission.swift、ExtensionManifest.swift)与测试用例,说明权限在 iTerm2 扩展运行时是如何被解析、校验和强制执行的。读完本文,你将能正确编写扩展的 permissions 声明、理解权限与 API 的对应关系,并掌握最小权限原则与可选权限的落地方法。

什么是 permissions 字段

在扩展的 manifest.json 中,permissions 字段用于声明扩展运行所需访问的浏览器 API。扩展只有声明了对应的权限关键字,才能在代码中调用相应的 WebExtension API;未声明的 API 调用会被运行时拒绝。

Manifest 字段定义

{
  "permissions": ["permission1", "permission2", ...]
}

字段属性:

  • 类型:字符串数组(Array of strings)
  • 必填:否
  • Manifest 版本:3(Manifest V3,iTerm2 WebExtensionsFramework 仅接受 manifest_version: 3)

与 host_permissions 的职责分离

在 Manifest V3 中,API 权限与主机权限被明确拆分:

  • permissions:声明扩展要访问的浏览器 API(能力权限);
  • host_permissions:声明扩展要访问的具体网址(URL 匹配模式),两者不能混写。

完整字段定义可参见 ExtensionManifest.swift,其中 permissions、hostPermissions、optionalPermissions、optionalHostPermissions 均以可选的字符串数组形式存在,并通过 CodingKeys 映射到 manifest.json 中的 permissions、host_permissions、optional_permissions、optional_host_permissions 键。主机权限的匹配模式(如 https://example.com/*、<all_urls>)详见 host_permissions.md。

API 权限关键字完整清单

以下字符串可被加入 permissions 数组,以授予对应 WebExtension API 的访问权(清单与 permissions.md 一致):

权限关键字 授予的能力
activeTab 用户调用扩展时,对当前活动标签页的临时访问权
alarms 访问 chrome.alarms API
bookmarks 访问 chrome.bookmarks API
browsingData 访问 chrome.browsingData API
clipboardRead 剪贴板读取权限
clipboardWrite 剪贴板写入权限
contextMenus 访问 chrome.contextMenus API
cookies 访问 chrome.cookies API
debugger 访问 chrome.debugger API
declarativeContent 访问 chrome.declarativeContent API
declarativeNetRequest 访问 chrome.declarativeNetRequest API
declarativeNetRequestFeedback 访问 chrome.declarativeNetRequestFeedback API
desktopCapture 访问 chrome.desktopCapture API
downloads 访问 chrome.downloads API
fontSettings 访问 chrome.fontSettings API
gcm 访问 chrome.gcm API
geolocation 访问地理位置 API
history 访问 chrome.history API
identity 访问 chrome.identity API
idle 访问 chrome.idle API
management 访问 chrome.management API
nativeMessaging 访问原生消息(native messaging)
notifications 访问 chrome.notifications API
pageCapture 访问 chrome.pageCapture API
power 访问 chrome.power API
printerProvider 访问 chrome.printerProvider API
privacy 访问 chrome.privacy API
proxy 访问 chrome.proxy API
scripting 访问 chrome.scripting API
search 访问 chrome.search API
sessions 访问 chrome.sessions API
storage 访问 chrome.storage API
system.cpu 访问 chrome.system.cpu API
system.display 访问 chrome.system.display API
system.memory 访问 chrome.system.memory API
system.storage 访问 chrome.system.storage API
tabCapture 访问 chrome.tabCapture API
tabGroups 访问 chrome.tabGroups API
tabs 访问 chrome.tabs API
topSites 访问 chrome.topSites API
tts 访问 chrome.tts API
ttsEngine 访问 chrome.ttsEngine API
unlimitedStorage 移除 chrome.storage.local 的配额限制
vpnProvider 访问 chrome.vpnProvider API
wallpaper 访问 chrome.wallpaper API
webNavigation 访问 chrome.webNavigation API
webRequest 访问 chrome.webRequest API
webRequestBlocking 允许在 webRequest 中进行阻塞式操作

特殊权限

在 WebExtension 生态中有两个行为特殊的权限,值得单独说明:

  • activeTab:一种特殊权限,无需声明宽泛的主机权限,即可在用户主动触发扩展时(如点击工具栏按钮、执行快捷键命令)获得对当前标签页的临时、有限访问权。它是"最小权限 + 按需授权"组合中最常被推荐的权限之一。
  • unlimitedStorage:允许扩展突破 chrome.storage.local 的正常存储配额上限。注意其生效方式与 storage 不同——它本身不授予存储 API 的访问权,而是放大 storage 权限下的容量边界。

源码视角:unlimitedStorage 的实际生效路径

在 iTerm2 WebExtensionsFramework 的存储处理器 StorageHandlers.swift 中,storage.local 与 storage.sync 的读写、删除、清空处理器均通过 context.hasPermission(.unlimitedStorage) 判断是否启用无配额模式;而 storage.managed 区域(企业托管存储)则不需要显式权限(requiredPermissions: [],见同文件 StorageManaged*Handler 实现)。

用户安装时的权限体验

当扩展声明了权限,用户在安装/更新时会看到如下流程:

  1. 浏览器在安装(或更新)时展示权限警告;
  2. 警告内容会解释扩展将获得哪些访问能力(例如"读取你的浏览历史""访问所有网站的数据");
  3. 用户必须接受这些权限才能完成安装;拒绝则无法安装。

权限警告的意义在于建立用户信任:权限越少、越贴近功能实际所需,用户越容易接受安装。因此原文档也强调,开发者应当把权限数量控制到"每个权限都由具体功能支撑"的程度。

最佳实践

  1. 只请求必要权限:仅申请扩展实际用到的 API,多余的权限声明会直接暴露在安装警告中;
  2. 尽可能使用 activeTab:它提供临时访问能力,避免为了单次操作申请宽泛的主机权限;
  3. 考虑可选权限(optional_permissions):把非核心功能所需的权限放入 optional_permissions,在运行时按需请求,降低首次安装门槛;
  4. 给出清晰解释:在扩展描述、界面文案中说明"为什么需要某项权限",帮助用户理解并减少疑虑。

完整示例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": [
    "storage",
    "tabs",
    "notifications"
  ]
}

这个示例请求了三项 API 权限:storage(本地/同步/会话存储)、tabs(读取标签页属性)、notifications(发送桌面通知)。若扩展还需要访问具体网站,应按 Manifest V3 规则把 URL 放入独立的 host_permissions 字段(示例见 host_permissions.md 的 Example 小节)。

安全考量

  • 每一项权限都会扩大扩展的攻击面:权限越多,扩展一旦被恶意利用可造成的破坏范围越大;
  • 每个权限都应由具体功能来支撑和论证,避免"以防万一"式的提前声明;
  • 权限警告直接影响用户信任度——权限更少的扩展更容易获得安装与留存。

结合框架源码:权限在 iTerm2 运行时如何被处理

1. 权限字符串的解析

权限声明的底层解析实现在 BrowserExtensionPermission.swift。BrowserExtensionPermissionParser 提供:

  • parse(_:):将权限字符串解析为 BrowserExtensionPermission,命中已知列表则为 .api(...),否则保留为 .unknown(...)(用于前向兼容,例如未来新增的权限关键字不会导致 manifest 解析失败);
  • isKnownPermission(_:):判断某字符串是否为框架已知的 API 权限;
  • allKnownPermissions:返回框架当前支持的全部权限关键字。

已知权限的完整集合由枚举 BrowserExtensionAPIPermission(BrowserExtensionPermission.swift)定义,覆盖原文档列表中的全部关键字,并额外包含带子域的变体,如 downloads.beta、identity.email、enterprise.deviceAttributes、webRequestFilterResponse.extraHeaders 等——这类带点号的权限字符串同样可以被精确解析与匹配。

2. manifest 层面的查询接口

ExtensionManifest 扩展(BrowserExtensionPermission.swift)暴露了三个便捷接口:

  • parsedPermissions:返回解析后的权限列表;
  • hasPermission(_:):判断 manifest 是否声明了指定权限(未声明 permissions 时返回 false);
  • unknownPermissions:列出所有无法识别的权限字符串,便于调试排查。

3. API 处理器的权限强制检查

在 iTerm2 扩展运行时,每个 API 请求处理器都声明自己的 requiredPermissions(见 BrowserExtensionAPIProtocols.swift 中各类 HandlerProtocol)。当扩展发起 API 调用时,BrowserExtensionContext.swift 的 requirePermissions(_:) 会逐一核对:

  • 若扩展缺少某项必需权限,抛出 BrowserExtensionError.insufficientPermissions(...) 并记录错误日志;
  • hasPermission(_:) 则用于需要根据权限调整行为的场景(如 unlimitedStorage 分支)。

例如 RuntimeSendMessageHandler 与 RuntimeGetPlatformInfoHandler 的 requiredPermissions 为空数组(SendMessageHandler.swift、GetPlatformInfoHandler.swift),即 runtime.sendMessage 与 runtime.getPlatformInfo 无需额外权限即可调用;而全部 storage 读写处理器(StorageLocalGetHandler、StorageSyncSetHandler、StorageSessionClearHandler 等)均要求 [.storage] 权限。

4. 测试验证

框架的权限行为有完整测试覆盖:

  • BrowserExtensionPermissionTests.swift 验证了已知/未知权限解析、带点号权限(system.cpu、downloads.beta)的枚举映射、hasPermission 判定以及 unknownPermissions 的提取逻辑;
  • BrowserExtensionPermissionSystemTests.swift 验证了 requirePermissions 的强制机制:声明了 storage、tabs 的扩展调用这些 API 成功,而调用未声明的 cookies 会抛出 insufficientPermissions("cookies")。

这些测试同时印证了原文档的安全原则:权限声明与 API 调用之间存在一一对应的强校验关系,多声明不会带来额外能力,少声明则直接导致功能不可用。

权限的进阶组织:可选权限与主机权限

为了让 permissions 保持最小化,Manifest V3 提供了两条配套路径:

  • optional_permissions:允许扩展在安装后、通过 chrome.permissions.request() 在运行时按需请求额外 API 权限(如 bookmarks、history、tabs),用户可随时授予或撤销;适合渐进增强、模块化功能等场景,完整说明见 optional_permissions.md。
  • host_permissions:所有涉及网页内容访问(跨域请求、标签页敏感信息、webRequest 拦截、cookie 读取等)的 URL 级授权,必须在此字段中声明,其匹配模式语法与用户控制方式见 host_permissions.md。

在编写 iTerm2 扩展时,推荐的组织策略是:核心功能用 permissions 声明必要 API;非必需能力放进 optional_permissions 按需申请;具体站点访问收敛到精确的 host_permissions 匹配模式,并尽量避开 <all_urls>。如此既满足功能需求,又能把安装警告、运行时攻击面与用户信任成本降到最低。

参考资料

登录后查看全文
iTerm2