# Permission configuration

## Function

BT maintains compatibility behavior by default, allowing scripts to use all standard library capabilities. Production environments can tighten permissions via environment variables to deny file, process, network, HTTP, MySQL, device, environment variables, desktop, screen capture, and FFI capabilities at standard library boundaries.

Permission checking only occurs at standard library construction or method call boundaries and does not enter the VM ordinary instruction loop.

## Syntax

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

 View the current configuration when running:

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

## Parameters

| Environment variable | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| BT_PERMISSION_ALLOW | String | No | Not configured | List of allowed capabilities. After configuration, only the capabilities in the list are allowed; comma, semicolon or blank separation is supported. |
| BT_PERMISSION_DENY | String | No | Not configured | Deny capability list. Deny lists have higher priority than allow lists. |

Capability name:

| Name | Capability |
| ------ | ------ |
| fs | `fs()` File reading and writing, directory operations. |
| process | `process()` child process capability. |
| net | `net()`, `net.listen()`, `net.connect()`, DNS and interface information. |
| http | `reqwest()` HTTP client capability, also supports the alias `reqwest`. |
| mysql | `mysql()` database capabilities. |
| device | `device()`, serial port scanning and serial port reading and writing. |
| env | `BT.env()`, `BT.set_env()`, `BT.envs()` and PATH overlays. |
| desktop | `bt_app` Desktop bridging commands, including windows, system dialog boxes, trays, clipboards, notifications, drag-in file events and application-level desktop operations. |
| screen | Screen reading for `window.bt.screen.pick_color()` and `capture_area()`; supports aliases `capture`, `screenshot`. |
| ffi | Controls dynamic library loading and native function calling, and also supports the alias `native`. |

Special value:

| Value | Description |
| ------ | ------ |
| all | Indicates all abilities. |
| none | Indicates an empty capability list. |

## Return Value

`BT.stats().permission` Return object:

| Field | Type | Description |
| ------ | ------ | ------ |
| denied | Int | The number of permission denials in the current process. |
| config | Object | Snapshot of current permission configuration. |

`config` Field:

| Field | Type | Description |
| ------ | ------ | ------ |
| allow_configured | Bool | Whether `BT_PERMISSION_ALLOW` is explicitly configured. |
| allow | Array | Names of capabilities in the allow list. Returns all capabilities when not configured. |
| deny | Array | Names of capabilities in the deny list. |
| allowed | Array | The name of the currently allowed capability. |
| config_error | String / Empty | Permission configuration error; if there is no error, it is `empty`. |

## Code Examples

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

// Output: fs,process,net,http,mysql,device,env,desktop,screen
print allowed
```

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

// Output: 0
print denied
```

## Notes

- When `BT_PERMISSION_ALLOW` and `BT_PERMISSION_DENY` are not set by default, BT allows full capabilities and is compatible with existing scripts.
- If both allow and deny are configured, the deny list takes effect first. For example, when `BT_PERMISSION_ALLOW=all` and `BT_PERMISSION_DENY=process`, `process()` will be rejected.
 - Permission denied throws a Chinese runtime error, does not return `empty` or fails silently.
- The permission configuration is cached after being read for the first time in the process; after the resident process modifies the environment variables, the process needs to be restarted to take effect.
- `desktop` controls `window.bt.window`, `window.bt.dialog`, `window.bt.tray`, `window.bt.clipboard`, `window.bt.notify`, `window.bt.drag`, `window.bt.app` and initialization project commands; `window.bt.call()` is still a long-term VM business channel and is used internally by the called BT function `fs`, `process`, `net` and other capabilities continue to be checked according to their respective permissions.
 - `screen` is an additional sensitive permission; the public screen API must pass both `desktop` and `screen` so that production environments can retain the normal window/tray API and turn off screen reading alone.
- `ffi.close()` does not check ffi permissions to ensure that created dynamic library resources can still be released after tightening permissions; ffi permissions are checked during loading and every native call.
 - Permissions configuration regression example at `examples/permission-stats.bt` that verifies the allow/deny combination and the `BT.stats().permission` configuration snapshot.