# 扩展权限与路径

## 功能

扩展权限用于把“扩展声明想做什么”和“运行进程允许做什么”分开。`manifest.permissions` 先声明扩展需要的能力；运行时再结合 BT 进程权限配置判断是否允许加载。

路径 role 用于让 WASM 扩展安全接收项目内路径。宿主会先按 BT 路径规则解析脚本传入的路径，再确认路径没有逃出项目根，最后把它改写为 WASI 预打开目录内的相对路径。

## 语法

```json
{
    "permissions": {
        "fs_read": true,
        "fs_write": true,
        "net": false,
        "http": false,
        "process": false,
        "env": false
    }
}
```

## 参数

| 字段 | 说明 |
| ------ | ------ |
| `fs_read` | 允许读取文件路径 role。 |
| `fs_write` | 允许写入文件路径 role。 |
| `net` | 预留给 TCP、UDP、WebSocket、DNS 等网络能力。 |
| `http` | 预留给 HTTP 客户端能力。 |
| `process` | 预留给进程能力。 |
| `env` | 预留给环境变量能力。 |

## 路径 role

路径 role 写在 `bindings.json` 的参数上：

```json
{
    "name": "copy_to",
    "id": 2,
    "params": [
        { "name": "target", "type": "string", "role": "path_write" }
    ],
    "returns": "bool"
}
```

| role | 权限要求 | 路径要求 |
| ------ | ------ | ------ |
| `path_read` | `fs_read: true` | 目标必须存在且是文件。 |
| `path_write` | `fs_write: true` | 目标存在时不能是目录；目标不存在时父目录必须存在。 |
| `path_dir` | `fs_read: true` 或 `fs_write: true` | 目标必须存在且是目录。 |

路径 role 的参数类型必须是 `string`。

## 返回值

权限声明没有脚本返回值。校验成功时扩展继续加载；权限声明和进程权限不匹配、路径 role 和权限不匹配、路径逃出项目根或路径类型不满足 role 要求时，调用会返回中文错误。

## 路径转换

脚本可以传入 BT 路径：

```bt
ok = file_demo('@/in.txt').copy_to('@/out.txt')

// 输出：true
print ok
```

宿主处理顺序是：

1. 用 BT 路径规则解析 `@` 项目根和普通相对路径。
2. 对已存在路径执行真实路径归一化，防止符号链接逃出项目根。
3. 按 role 校验文件或目录要求。
4. 把宿主路径改写为 WASI 相对路径，例如 `in.txt`、`nested/out.txt` 或 `.`。
5. 把改写后的字符串传给 WASM 模块。

WASM 模块收到的是 guest 相对路径，不应假设会收到宿主绝对路径。

## 注意事项

- `path_read` 和 `path_dir` 需要目标已经存在。
- `path_write` 写入新文件时，父目录必须已经存在。
- 路径为空字符串会报错。
- 路径参数不能逃出项目根目录。
- 文件系统路径能力主要面向 WASM 扩展；纯 BT 扩展通常直接使用 BT 标准库处理项目内逻辑。