扩展信任与路径

扩展信任与路径

扩展信任与路径

功能

BT 把每个已安装的 .bts 都视为用户信任的本地程序依赖。扩展不声明包级权限,运行时也不区分官网下载安装、本地复制、私有构建、修改版或闭源分发的包。加载扩展时不会连接官网。

官网扩展库是独立的分发边界:只收录经过审查的开源版本,并且只对自己发布的精确包文件及其哈希负责。安装其他扩展是用户自己的信任决定,不受官网目录限制。

BT 可选的进程级策略仍统一作用于整个进程。BT_PERMISSION_ALLOWBT_PERMISSION_DENY 可以限制 BT 进程本身,但不会给不同扩展分配不同能力。

路径 role 用于让 WASM 扩展接收 WASI 预打开项目目录中的路径。宿主解析 BT 路径语法,检查 role 要求的对象,防止转换后的 role 路径逃出项目根,最后把 WASI 相对路径传给扩展。

语法

扩展不需要权限声明。路径 role 只写在 bindings.json 中:

信任边界

来源运行时待遇官网审核范围
官网扩展包与所有 .bts 使用相同宿主 ABI 和进程策略只适用于已发布版本、源码提交和 SHA-256
手工复制的扩展包与所有 .bts 使用相同宿主 ABI 和进程策略
私有或闭源扩展包与所有 .bts 使用相同宿主 ABI 和进程策略
本地修改或重新构建的扩展包与所有 .bts 使用相同宿主 ABI 和进程策略无,即使使用相同名称

官网目录不是运行白名单,BT 加载本地包时不会查询官网。官网停止分发某个版本也不会禁用或删除已经安装的副本。

路径 role 字段

字段类型必填默认值有效值含义
nameStringsnake_case 标识向 BT 脚本公开的参数名。
typeString路径 role 必须是 string运行时参数类型。
roleStringvaluevaluepath_readpath_writepath_dir选择普通值传递或宿主路径转换。

role路径要求
path_read目标必须存在且是文件。
path_write已存在的目标不能是目录;新目标必须有已存在的父目录。
path_dir目标必须存在且是目录。

返回值

路径 role 没有独立的脚本返回值。合法参数经过转换后传给 WASM 扩展;类型不符、目标不存在、输出父目录无效、路径逃出项目根,或者进程级文件能力被禁用时,调用返回英文运行时错误。

路径转换示例

宿主按以下顺序处理路径:

1. 使用项目根解析 @,使用适用的源码目录解析普通相对路径。

2. 规范化已存在路径和输出父目录。

3. 拒绝逃出项目根的 role 路径,包括通过符号链接逃逸。

4. 检查 role 要求的文件或目录形态。

5. 转换为 in.txtnested/out.txt. 等 WASI 相对路径。

WASM 模块收到 guest 相对路径,不应假设会收到宿主绝对路径。进程级文件能力启用时,WASI 运行时统一以读写方式预打开项目根;所有 WASM 扩展待遇相同,不由 manifest 元数据选择。

注意事项

  • permissions 字段已经删除。仍包含该字段的扩展包无法通过 manifest 校验,必须按新版 .bts 格式重新构建。
  • 安装扩展即表示信任其代码。扩展可以使用 ABI 已实现的全部宿主能力,只受 BT 进程级策略和操作系统账号约束。
  • 进程级资源上限、包校验、WASM 内存隔离、有界队列、调用超时和对象生命周期仍是运行稳定性规则,不是扩展授权机制。
  • path_readpath_dir 要求目标已存在。
  • path_write 创建新文件时要求父目录已存在。
  • 路径 role 拒绝空字符串和转换后超出项目根的路径。
  • 纯 BT 扩展通常直接使用 BT 标准库;WASI 路径转换规则主要适用于 WASM 扩展。
  • 原生后台进程运行在 WASI 沙箱之外,并继承操作系统账号权限。