iTerm2 WebExtensionsFramework 权限声明指南:Manifest V3 `permissions` 字段详解与源码验证
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 实现)。
用户安装时的权限体验
当扩展声明了权限,用户在安装/更新时会看到如下流程:
- 浏览器在安装(或更新)时展示权限警告;
- 警告内容会解释扩展将获得哪些访问能力(例如"读取你的浏览历史""访问所有网站的数据");
- 用户必须接受这些权限才能完成安装;拒绝则无法安装。
权限警告的意义在于建立用户信任:权限越少、越贴近功能实际所需,用户越容易接受安装。因此原文档也强调,开发者应当把权限数量控制到"每个权限都由具体功能支撑"的程度。
最佳实践
- 只请求必要权限:仅申请扩展实际用到的 API,多余的权限声明会直接暴露在安装警告中;
- 尽可能使用
activeTab:它提供临时访问能力,避免为了单次操作申请宽泛的主机权限; - 考虑可选权限(
optional_permissions):把非核心功能所需的权限放入optional_permissions,在运行时按需请求,降低首次安装门槛; - 给出清晰解释:在扩展描述、界面文案中说明"为什么需要某项权限",帮助用户理解并减少疑虑。
完整示例
{
"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>。如此既满足功能需求,又能把安装警告、运行时攻击面与用户信任成本降到最低。
参考资料
- Manifest V3 整体规范:manifest-v3-spec.md
- 其他 manifest 字段:
manifest_version、name、version、description、background、content_scripts,见 manifest-fields 目录 - API 权限解析与校验源码:BrowserExtensionPermission.swift、BrowserExtensionContext.swift
- 权限行为测试:BrowserExtensionPermissionTests.swift、BrowserExtensionPermissionSystemTests.swift