命令范围

范围是一种定义 Tauri 命令的（不）允许行为的细粒度方法。

¥A scope is a granular way to define (dis)allowed behavior of a Tauri command.

范围分为 allow 或 deny 范围，其中 deny 始终取代 allow 范围。

¥Scopes are categorized into allow or deny scopes, where deny always supersedes the allow scope.

范围类型需要是任何 serde 可序列化类型。这些类型通常是插件特定的。对于在 Tauri 应用中实现的作用域命令，需要在应用中定义作用域类型，然后在命令实现中强制执行。

¥The scope type needs be of any serde serializable type. These types are plugin-specific in general. For scoped commands implemented in a Tauri application the scope type needs to be defined in the application and then enforced in the command implementation.

例如，Fs 插件允许你使用范围来允许或拒绝某些目录和文件，而 http 插件使用范围来过滤允许访问的 URL。

¥For instance, the Fs plugin allows you to use scopes to allow or deny certain directories and files and the http plugin uses scopes to filter URLs that are allowed to be reached.

范围传递给命令，处理或正确执行由命令本身实现。

¥The scope is passed to the command and handling or properly enforcing is implemented by the command itself.

:::caution 提醒

命令开发者需要确保不可能绕过范围。应审核范围验证实现以确保正确性。

¥Command developers need to ensure that there are no scope bypasses possible. The scope validation implementation should be audited to ensure correctness.

:::

示例

¥Examples

这些示例取自 Fs 插件权限：

¥These examples are taken from the Fs plugin permissions:

此插件中所有命令的范围类型都是字符串，其中包含与 glob 兼容的路径。

¥The scope type in this plugin for all commands is a string, which contains a glob compatible path.

[[permission]]
identifier = "scope-applocaldata-recursive"
description = '''
This scope recursive access to the complete `$APPLOCALDATA` folder,
including sub directories and files.
'''

[[permission.scope.allow]]
path = "$APPLOCALDATA/**"

[[permission]]
identifier = "deny-webview-data-linux"
description = '''
This denies read access to the
`$APPLOCALDATA` folder on linux as the webview data and
configuration values are stored here.
Allowing access can lead to sensitive information disclosure and
should be well considered.
'''
platforms = ["linux"]

[[scope.deny]]
path = "$APPLOCALDATA/**"

[[permission]]
identifier = "deny-webview-data-windows"
description = '''
This denies read access to the
`$APPLOCALDATA/EBWebView` folder on windows as the webview data and
configuration values are stored here.
Allowing access can lead to sensitive information disclosure and
should be well considered.
'''
platforms = ["windows"]

[[scope.deny]]
path = "$APPLOCALDATA/EBWebView/**"

上面的范围可用于允许访问 APPLOCALDATA 文件夹，同时阻止访问 Windows 上的 EBWebView 子文件夹，其中包含敏感的 webview 数据。

¥The above scopes can be used to allow access to the APPLOCALDATA folder, while preventing access to the EBWebView subfolder on windows, which contains sensitive webview data.

这些可以合并为一个集合，从而减少重复配置，并使任何查看应用配置的人都更容易理解。

¥These can merged into a set, which reduces duplicate configuration and makes it more understandable for anyone looking into the application configuration.

首先将拒绝范围合并到 deny-default 中：

¥First the deny scopes are merged into deny-default:

[[set]]
identifier = "deny-default"
description = '''
This denies access to dangerous Tauri relevant files and
folders by default.
'''
permissions = ["deny-webview-data-linux", "deny-webview-data-windows"]

之后，拒绝和允许范围合并：

¥Afterwards deny and allow scopes are merged:

[[set]]
identifier = "scope-applocaldata-reasonable"
description = '''
This scope set allows access to the `APPLOCALDATA` folder and
subfolders except for linux,
while it denies access to dangerous Tauri relevant files and
folders by default on windows.
'''
permissions = ["scope-applocaldata-recursive", "deny-default"]

这些范围可以用于所有命令（通过扩展插件的全局范围），也可以仅用于选定的命令（当它们与权限内的启用命令结合使用时）。

¥These scopes can be either used for all commands, by extending the global scope of the plugin, or for only selected commands when they are used in combination with a enabled command inside a permission.

对 APPLOCALDATA 中文件的合理只读文件访问可能如下所示：

¥Reasonable read only file access to files in the APPLOCALDATA could look like this:

[[set]]
identifier = "read-files-applocaldata"
description = '''
This set allows file read access to the `APPLOCALDATA` folder and
subfolders except for linux,
while it denies access to dangerous Tauri relevant files and
folders by default on windows.'''
permissions = ["scope-applocaldata-reasonable", "allow-read-file"]

这些示例仅高亮范围功能本身。每个插件或应用开发者都需要根据其用例考虑合理的范围组合。

¥These examples only highlight the scope functionality itself. Each plugin or application developer needs to consider reasonable combinations of scope depending on their use cases.