Extended permissions and paths
Extended permissions and paths
Function
Extended permissions are used to separate "what the extension declaration wants to do" and "what the running process is allowed to do". manifest.permissions first declares the capabilities required for the extension; at runtime, it will be combined with the BT process permission configuration to determine whether loading is allowed.
The path role is used to allow the WASM extension to safely receive paths within the project. The host will first parse the path passed in by the script according to BT path rules, then confirm that the path does not escape the project root, and finally rewrite it as a relative path in the WASI pre-open directory.
Syntax
{ "permissions": ["fs_read", "fs_write"] }
Parameters
| Permissions | Description |
|---|---|
fs_read | Allow reading the file path role. |
fs_write | Allow writing to file path role. |
net | Reserved for TCP, UDP, WebSocket, DNS and other network capabilities. |
http | Reserved for HTTP client capabilities. |
process | Reserved for process capabilities. |
env | Reserved for environment variable capabilities. |
Path role
Path role is written on the parameters of bindings.json:
{ "name": "copy_to", "id": 2, "params": [ { "name": "target", "type": "string", "role": "path_write" } ], "returns": "bool" }
| role | Permission requirements | Path requirements |
|---|---|---|
path_read | fs_read declared in permissions | The target must exist and be a file. |
path_write | fs_write is declared in permissions | The target cannot be a directory when it exists; the parent directory must exist when the target does not exist. |
path_dir | permissions declared in fs_read or fs_write | The target must exist and be a directory. |
The parameter type of path role must be string.
Return Value
Permission declaration has no script return value. If the verification is successful, the extension will continue to load; if the permission declaration does not match the process permissions, the path role does not match the permissions, the path escapes the project root, or the path type does not meet the role requirements, the call will return a Chinese error.
The path conversion
script can pass in the BT path:
ok = file_demo('@/in.txt').copy_to('@/out.txt') // Output: true print ok
The host processing sequence is:
1. Use BT path rules to parse the @ project root and ordinary relative paths.
2. Perform real path normalization on existing paths to prevent symbolic links from escaping from the project root.
3. Verify file or directory requirements by role.
4. Rewrite the host path to a WASI relative path, such as in.txt, nested/out.txt or ..
5. Pass the rewritten string to the WASM module.
The WASM module receives guest relative paths and should not assume that host absolute paths are received.
Notes
- path_read and path_dir require the target to already exist.
-
path_writeWhen writing a new file, the parent directory must already exist. -
permissionsOnly declare the required capabilities; do not write unused capabilities into the array. - An error will be reported if the path is an empty string.
- Path parameters cannot escape the project root directory.
- The file system path capability is mainly for WASM extensions; pure BT extensions usually directly use the BT standard library to handle the logic within the project.