# 扩展信任与路径

## 功能

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

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

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

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

## 语法

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

```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 扩展；类型不符、目标不存在、输出父目录无效、路径逃出项目根，或者进程级文件能力被禁用时，调用返回英文运行时错误。

## 路径转换示例

```bt
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 扩展。
- [原生后台进程](/zh-hans/docs/extensions/host-process)运行在 WASI 沙箱之外，并继承操作系统账号权限。