# 权限配置

## 功能

BT 默认保持兼容行为，允许脚本使用全部标准库能力。生产环境可以通过环境变量收紧权限，在标准库边界拒绝文件、进程、网络、HTTP、MySQL、设备、环境变量、桌面、屏幕捕获和 FFI 能力。

权限检查只发生在标准库构造或方法调用边界，不进入 VM 普通指令循环。

## 语法

```text
BT_PERMISSION_ALLOW=fs,net,http
BT_PERMISSION_DENY=process,device
```

运行时查看当前配置：

```bt
BT.stats().permission
```

## 参数

| 环境变量 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ |
| BT_PERMISSION_ALLOW | String | 否 | 未配置 | 允许能力列表。配置后只允许列表内能力；支持逗号、分号或空白分隔。 |
| BT_PERMISSION_DENY | String | 否 | 未配置 | 拒绝能力列表。拒绝列表优先级高于允许列表。 |

能力名称：

| 名称 | 能力 |
| ------ | ------ |
| fs | `fs()` 文件读写、目录操作。 |
| process | `process()` 子进程能力。 |
| net | `net()`、`net.listen()`、`net.connect()`、DNS 和接口信息。 |
| http | `reqwest()` HTTP 客户端能力，也支持别名 `reqwest`。 |
| mysql | `mysql()` 数据库能力。 |
| device | `device()`、串口扫描和串口读写。 |
| env | `BT.env()`、`BT.set_env()`、`BT.envs()` 和 PATH 覆盖层。 |
| desktop | `bt-app` 桌面桥接命令，包括窗口、系统对话框、托盘、剪贴板、通知、拖入文件事件和应用级桌面操作。 |
| screen | `window.bt.screen.pick_color()` 和 `capture_area()` 的屏幕读取；支持别名 `capture`、`screenshot`。 |
| ffi | 控制动态库加载和原生函数调用，也支持别名 `native`。 |

特殊值：

| 值 | 说明 |
| ------ | ------ |
| all | 表示全部能力。 |
| none | 表示空能力列表。 |

## 返回值

`BT.stats().permission` 返回对象：

| 字段 | 类型 | 说明 |
| ------ | ------ | ------ |
| denied | Int | 当前进程内权限拒绝次数。 |
| config | Object | 当前权限配置快照。 |

`config` 字段：

| 字段 | 类型 | 说明 |
| ------ | ------ | ------ |
| allow_configured | Bool | 是否显式配置了 `BT_PERMISSION_ALLOW`。 |
| allow | Array | 允许列表中的能力名称。未配置时返回全部能力。 |
| deny | Array | 拒绝列表中的能力名称。 |
| allowed | Array | 当前实际允许的能力名称。 |
| config_error | String / Empty | 权限配置错误；没有错误时为 `empty`。 |

## 代码示例

```bt
stats = BT.stats().permission
allowed = stats.config.allowed.join(',')

// 输出：fs,process,net,http,mysql,device,env,desktop,screen
print allowed
```

```bt
stats = BT.stats().permission
denied = stats.denied

// 输出：0
print denied
```

## 注意事项

- 默认不设置 `BT_PERMISSION_ALLOW` 和 `BT_PERMISSION_DENY` 时，BT 允许全部能力，兼容现有脚本。
- 如果同时配置允许和拒绝，拒绝列表优先生效。例如 `BT_PERMISSION_ALLOW=all` 且 `BT_PERMISSION_DENY=process` 时，`process()` 会被拒绝。
- 权限拒绝会抛出中文运行时错误，不会返回 `empty` 或静默失败。
- 权限配置在进程内首次读取后缓存；常驻进程修改环境变量后需要重启进程才会生效。
- `desktop` 控制 `window.bt.window`、`window.bt.dialog`、`window.bt.tray`、`window.bt.clipboard`、`window.bt.notify`、`window.bt.drag`、`window.bt.app` 和初始化项目命令；`window.bt.call()` 仍是长期 VM 业务通道，被调用 BT 函数内部使用的 `fs`、`process`、`net` 等能力继续按各自权限检查。
- `screen` 是额外的敏感权限；公开屏幕 API 必须同时通过 `desktop` 和 `screen`，这样生产环境可以保留普通窗口/托盘 API 而单独关闭屏幕读取。
- `ffi.close()` 不检查 ffi 权限，确保权限收紧后仍能释放已经创建的动态库资源；加载和每次原生调用都会检查 ffi 权限。
- 权限配置回归示例位于 `examples/permission-stats.bt`，会验证 allow/deny 组合和 `BT.stats().permission` 配置快照。