扩展信任与路径
扩展信任与路径
功能
BT 把每个已安装的 .bts 都视为用户信任的本地程序依赖。扩展不声明包级权限,运行时也不区分官网下载安装、本地复制、私有构建、修改版或闭源分发的包。加载扩展时不会连接官网。
官网扩展库是独立的分发边界:只收录经过审查的开源版本,并且只对自己发布的精确包文件及其哈希负责。安装其他扩展是用户自己的信任决定,不受官网目录限制。
BT 可选的进程级策略仍统一作用于整个进程。BT_PERMISSION_ALLOW 和 BT_PERMISSION_DENY 可以限制 BT 进程本身,但不会给不同扩展分配不同能力。
路径 role 用于让 WASM 扩展接收 WASI 预打开项目目录中的路径。宿主解析 BT 路径语法,检查 role 要求的对象,防止转换后的 role 路径逃出项目根,最后把 WASI 相对路径传给扩展。
语法
扩展不需要权限声明。路径 role 只写在 bindings.json 中:
{ "name": "copy_to", "id": 2, "params": [ { "name": "target", "type": "string", "role": "path_write" } ], "returns": "bool" }
信任边界
| 来源 | 运行时待遇 | 官网审核范围 |
|---|---|---|
| 官网扩展包 | 与所有 .bts 使用相同宿主 ABI 和进程策略 | 只适用于已发布版本、源码提交和 SHA-256 |
| 手工复制的扩展包 | 与所有 .bts 使用相同宿主 ABI 和进程策略 | 无 |
| 私有或闭源扩展包 | 与所有 .bts 使用相同宿主 ABI 和进程策略 | 无 |
| 本地修改或重新构建的扩展包 | 与所有 .bts 使用相同宿主 ABI 和进程策略 | 无,即使使用相同名称 |
官网目录不是运行白名单,BT 加载本地包时不会查询官网。官网停止分发某个版本也不会禁用或删除已经安装的副本。
路径 role 字段
| 字段 | 类型 | 必填 | 默认值 | 有效值 | 含义 |
|---|---|---|---|---|---|
name | String | 是 | 无 | snake_case 标识 | 向 BT 脚本公开的参数名。 |
type | String | 是 | 无 | 路径 role 必须是 string | 运行时参数类型。 |
role | String | 否 | value | value、path_read、path_write、path_dir | 选择普通值传递或宿主路径转换。 |
| role | 路径要求 |
|---|---|
path_read | 目标必须存在且是文件。 |
path_write | 已存在的目标不能是目录;新目标必须有已存在的父目录。 |
path_dir | 目标必须存在且是目录。 |
返回值
路径 role 没有独立的脚本返回值。合法参数经过转换后传给 WASM 扩展;类型不符、目标不存在、输出父目录无效、路径逃出项目根,或者进程级文件能力被禁用时,调用返回英文运行时错误。
路径转换示例
ok = file_demo('@/in.txt').copy_to('@/out.txt') // 输出:true print ok
宿主按以下顺序处理路径:
1. 使用项目根解析 @,使用适用的源码目录解析普通相对路径。
2. 规范化已存在路径和输出父目录。
3. 拒绝逃出项目根的 role 路径,包括通过符号链接逃逸。
4. 检查 role 要求的文件或目录形态。
5. 转换为 in.txt、nested/out.txt 或 . 等 WASI 相对路径。
WASM 模块收到 guest 相对路径,不应假设会收到宿主绝对路径。进程级文件能力启用时,WASI 运行时统一以读写方式预打开项目根;所有 WASM 扩展待遇相同,不由 manifest 元数据选择。
注意事项
-
permissions字段已经删除。仍包含该字段的扩展包无法通过 manifest 校验,必须按新版.bts格式重新构建。 - 安装扩展即表示信任其代码。扩展可以使用 ABI 已实现的全部宿主能力,只受 BT 进程级策略和操作系统账号约束。
- 进程级资源上限、包校验、WASM 内存隔离、有界队列、调用超时和对象生命周期仍是运行稳定性规则,不是扩展授权机制。
-
path_read和path_dir要求目标已存在。 -
path_write创建新文件时要求父目录已存在。 - 路径 role 拒绝空字符串和转换后超出项目根的路径。
- 纯 BT 扩展通常直接使用 BT 标准库;WASI 路径转换规则主要适用于 WASM 扩展。
- 原生后台进程运行在 WASI 沙箱之外,并继承操作系统账号权限。