From 68de4adcd593171c690ef386560855af1d7b49a1 Mon Sep 17 00:00:00 2001 From: peng <1012890246@qq.com> Date: Wed, 26 Mar 2025 15:01:07 +0800 Subject: [PATCH 1/5] i18n(zh-cn): Add permission configuration related documents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增权限配置文档，详细介绍了权限的定义、配置和使用方法 - 文档中包含了多个权限配置示例，帮助开发者更好地理解和应用权限设置- 对权限标识符的命名规则和配置文件结构进行了详细说明 --- .../docs/zh-cn/security/permissions.mdx | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 src/content/docs/zh-cn/security/permissions.mdx diff --git a/src/content/docs/zh-cn/security/permissions.mdx b/src/content/docs/zh-cn/security/permissions.mdx new file mode 100644 index 0000000000..dde5256db2 --- /dev/null +++ b/src/content/docs/zh-cn/security/permissions.mdx @@ -0,0 +1,158 @@ +--- +title: 权限 +sidebar: + order: 2 +i18nReady: true +--- + +权限（Permissions）是对命令所具备的明确特权（explicit privileges）的具体描述。 + +```toml +[[permission]] +identifier = "my-identifier" +description = "This describes the impact and more." +commands.allow = [ + "read_file" +] + +[[scope.allow]] +my-scope = "$HOME/*" + +[[scope.deny]] +my-scope = "$HOME/secret" +``` + +该功能允许在 Tauri 应用程序的前端访问特定命令，通过将作用域（Scopes）映射到命令并定义可启用的命令列表。 +权限机制既可启用/禁用命令，也可定义作用域，或同时执行两种操作。 + +权限可以按新的标识符（Identifier）进行分组，形成`权限集（Permission set）`。这种机制允许将以下两类权限进行组合： +1. 范围相关权限（如数据访问范围） +2. 命令相关权限（如执行特定操作的权限） +同时，还能将操作系统层面的特定权限归类为更易于使用的集合。 + +作为插件开发者，您可以为所有对外暴露的命令提供多个预定义且命名清晰的权限。 + +作为应用开发者，您可以扩展现有插件权限或为自定义命令定义新权限。 +这些权限可被分组或组合成权限集（Permission Set），以便复用或简化后续的主配置文件配置。 + +## 权限标识符 + +权限标识符（Permissions identifier）用于确保权限可被复用，并具有唯一的名称。 + +:::tip + +此处**name**指插件的crate名称（不含`tauri-plugin-`前缀）， +用于命名空间隔离以降低命名冲突风险；当涉及应用程序自身权限引用时无需使用该前缀。 + +::: + +- `:default` 表明该权限是插件或应用程序的默认设置 +- `:` 表示该权限仅适用于单个命令（或独立命令）。 + +插件标识符在编译时将自动添加 `tauri-plugin-` 前缀，无需手动指定。 + +标识符仅限于ASCII小写字母字符 `[a-z]`，且当前最大长度限制为 `116` 字符（由以下常量决定）： + +```rust +const IDENTIFIER_SEPARATOR: u8 = b':'; +const PLUGIN_PREFIX: &str = "tauri-plugin-"; + +// https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field +const MAX_LEN_PREFIX: usize = 64 - PLUGIN_PREFIX.len(); +const MAX_LEN_BASE: usize = 64; +const MAX_LEN_IDENTIFIER: usize = MAX_LEN_PREFIX + 1 + MAX_LEN_BASE; +``` + +## 配置文件 + +Tauri **插件**目录结构的简化示例： + +```sh +tauri-plugin +├── README.md +├── src +│ └── lib.rs +├── build.rs +├── Cargo.toml +├── permissions +│ └── .json/toml +│ └── default.json/toml +``` + +默认权限以特殊方式处理，只要使用 Tauri CLI 向 Tauri 应用添加插件，该权限便会自动加入应用配置中。 + +对于**应用程序**开发者而言，其结构类似： + +```sh +tauri-app +├── index.html +├── package.json +├── src +├── src-tauri +│ ├── Cargo.toml +│ ├── permissions +│ └── .toml +| ├── capabilities +│ └── .json/.toml +│ ├── src +│ ├── tauri.conf.json +``` + +:::note + +作为应用开发者，功能配置文件（Capability files）可使用 `json`/`json5` 或 `toml` 格式编写，但权限配置仅支持 `toml` 格式。 + +::: + +## 示例 + +来自 File System 插件的权限示例 + +```toml title="plugins/fs/permissions/autogenerated/base-directories/home.toml" +[[permission]] +identifier = "scope-home" +description = """This scope permits access to all files and +list content of top level directories in the `$HOME`folder.""" + +[[scope.allow]] +path = "$HOME/*" +``` + +```toml title="plugins/fs/permissions/read-files.toml" +[[permission]] +identifier = "read-files" +description = """This enables all file read related +commands without any pre-configured accessible paths.""" +commands.allow = [ + "read_file", + "read", + "open", + "read_text_file", + "read_text_file_lines", + "read_text_file_lines_next" +] +``` + +```toml title="plugins/fs/permissions/autogenerated/commands/mkdir.toml" +[[permission]] +identifier = "allow-mkdir" +description = "This enables the mkdir command." +commands.allow = [ + "mkdir" +] +``` + +以下示例演示如何在您的应用中扩展上述插件权限的实现： + +```toml title="my-app/src-tauri/permissions/home-read-extends.toml" +[[set]] +identifier = "allow-home-read-extended" +description = """ This allows non-recursive read access to files and to create directories +in the `$HOME` folder. +""" +permissions = [ + "fs:read-files", + "fs:scope-home", + "fs:allow-mkdir" +] +``` From 9c5bc71d2ac3a9eb1deea409c4cfa47cfa8c7bd2 Mon Sep 17 00:00:00 2001 From: PengLiu <38398282+amourtoyou@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:50:34 +0800 Subject: [PATCH 2/5] Apply suggestions from code review supplement Co-authored-by: xubeiyan --- src/content/docs/zh-cn/security/permissions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/zh-cn/security/permissions.mdx b/src/content/docs/zh-cn/security/permissions.mdx index dde5256db2..da6c6a301f 100644 --- a/src/content/docs/zh-cn/security/permissions.mdx +++ b/src/content/docs/zh-cn/security/permissions.mdx @@ -10,7 +10,7 @@ i18nReady: true ```toml [[permission]] identifier = "my-identifier" -description = "This describes the impact and more." +description = "此处填写带来的影响等等" commands.allow = [ "read_file" ] From 09867a742ad3960e291d1bc2baf94c558ce5ec7f Mon Sep 17 00:00:00 2001 From: PengLiu <38398282+amourtoyou@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:50:49 +0800 Subject: [PATCH 3/5] Apply suggestions from code review supplement Co-authored-by: xubeiyan --- src/content/docs/zh-cn/security/permissions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/zh-cn/security/permissions.mdx b/src/content/docs/zh-cn/security/permissions.mdx index da6c6a301f..cce2a44185 100644 --- a/src/content/docs/zh-cn/security/permissions.mdx +++ b/src/content/docs/zh-cn/security/permissions.mdx @@ -41,7 +41,7 @@ my-scope = "$HOME/secret" :::tip -此处**name**指插件的crate名称（不含`tauri-plugin-`前缀）， +此处 **name** 指插件的 crate 名称（不含 `tauri-plugin-` 前缀）， 用于命名空间隔离以降低命名冲突风险；当涉及应用程序自身权限引用时无需使用该前缀。 ::: From 2358e39b42b195cfe98c2df2d147f18162f25386 Mon Sep 17 00:00:00 2001 From: PengLiu <38398282+amourtoyou@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:51:07 +0800 Subject: [PATCH 4/5] Apply suggestions from code review supplement Co-authored-by: xubeiyan --- src/content/docs/zh-cn/security/permissions.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/zh-cn/security/permissions.mdx b/src/content/docs/zh-cn/security/permissions.mdx index cce2a44185..909303f56f 100644 --- a/src/content/docs/zh-cn/security/permissions.mdx +++ b/src/content/docs/zh-cn/security/permissions.mdx @@ -121,8 +121,7 @@ path = "$HOME/*" ```toml title="plugins/fs/permissions/read-files.toml" [[permission]] identifier = "read-files" -description = """This enables all file read related -commands without any pre-configured accessible paths.""" +description = """将允许所有读取文件的命令，无需预先指定可访问路径。""" commands.allow = [ "read_file", "read", From 32e3141b355cc776794fc3dfddc9b3a2f27a631e Mon Sep 17 00:00:00 2001 From: PengLiu <38398282+amourtoyou@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:51:16 +0800 Subject: [PATCH 5/5] Apply suggestions from code review supplement Co-authored-by: xubeiyan --- src/content/docs/zh-cn/security/permissions.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/zh-cn/security/permissions.mdx b/src/content/docs/zh-cn/security/permissions.mdx index 909303f56f..3df4c56857 100644 --- a/src/content/docs/zh-cn/security/permissions.mdx +++ b/src/content/docs/zh-cn/security/permissions.mdx @@ -146,8 +146,7 @@ commands.allow = [ ```toml title="my-app/src-tauri/permissions/home-read-extends.toml" [[set]] identifier = "allow-home-read-extended" -description = """ This allows non-recursive read access to files and to create directories -in the `$HOME` folder. +description = """ 将允许在 `$HOME` 目录下使用非递归方式读取文件和创建文件夹 """ permissions = [ "fs:read-files",