From 5a231465661e2a775ff8ada0ccae255cb9244869 Mon Sep 17 00:00:00 2001 From: WofWca Date: Mon, 17 Mar 2025 15:29:58 +0400 Subject: [PATCH] docs: clarify Capability::windows/webviews OR nature (#13000) * docs: clarify Capability::windows/webviews OR nature It is intuitive to expect that for the capability to be enabled, _both_ the window label and the webview label have to match. However, this is not the case: the capability is enabled if _either_ the window label matches a pattern in `Capability::windows` _or_ the webview label matches a pattern in `Capability::webviews`. This commit should somewhat clarify this oddity and protect developers from adding excessive permissions. For reference, `Capability::webviews` was added in 0cb0a15ce22af3d649cf219ac04188c14c5f4905 (https://github.com/tauri-apps/tauri/pull/8789). * Apply suggestions from code review Co-authored-by: Amr Bashir * update schemas --------- Co-authored-by: Amr Bashir Co-authored-by: Lucas Nogueira --- crates/tauri-cli/config.schema.json | 4 ++-- .../schemas/capability.schema.json | 4 ++-- .../schemas/config.schema.json | 4 ++-- crates/tauri-utils/src/acl/capability.rs | 12 +++++++++--- 4 files changed, 15 insertions(+), 9 deletions(-) diff --git a/crates/tauri-cli/config.schema.json b/crates/tauri-cli/config.schema.json index c187fa568..ff059be6f 100644 --- a/crates/tauri-cli/config.schema.json +++ b/crates/tauri-cli/config.schema.json @@ -1318,14 +1318,14 @@ "type": "boolean" }, "windows": { - "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n On multiwebview windows, prefer [`Self::webviews`] for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", + "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n If a window label matches any of the patterns in this list,\n the capability will be enabled on all the webviews of that window,\n regardless of the value of [`Self::webviews`].\n\n On multiwebview windows, prefer specifying [`Self::webviews`] and omitting [`Self::windows`]\n for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", "type": "array", "items": { "type": "string" } }, "webviews": { - "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n This is only required when using on multiwebview contexts, by default\n all child webviews of a window that matches [`Self::windows`] are linked.\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", + "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n The capability will be enabled on all the webviews\n whose label matches any of the patterns in this list,\n regardless of whether the webview's window label matches a pattern in [`Self::windows`].\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", "type": "array", "items": { "type": "string" diff --git a/crates/tauri-schema-generator/schemas/capability.schema.json b/crates/tauri-schema-generator/schemas/capability.schema.json index 0c9462c50..89a0076d8 100644 --- a/crates/tauri-schema-generator/schemas/capability.schema.json +++ b/crates/tauri-schema-generator/schemas/capability.schema.json @@ -34,14 +34,14 @@ "type": "boolean" }, "windows": { - "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n On multiwebview windows, prefer [`Self::webviews`] for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", + "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n If a window label matches any of the patterns in this list,\n the capability will be enabled on all the webviews of that window,\n regardless of the value of [`Self::webviews`].\n\n On multiwebview windows, prefer specifying [`Self::webviews`] and omitting [`Self::windows`]\n for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", "type": "array", "items": { "type": "string" } }, "webviews": { - "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n This is only required when using on multiwebview contexts, by default\n all child webviews of a window that matches [`Self::windows`] are linked.\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", + "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n The capability will be enabled on all the webviews\n whose label matches any of the patterns in this list,\n regardless of whether the webview's window label matches a pattern in [`Self::windows`].\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", "type": "array", "items": { "type": "string" diff --git a/crates/tauri-schema-generator/schemas/config.schema.json b/crates/tauri-schema-generator/schemas/config.schema.json index c187fa568..ff059be6f 100644 --- a/crates/tauri-schema-generator/schemas/config.schema.json +++ b/crates/tauri-schema-generator/schemas/config.schema.json @@ -1318,14 +1318,14 @@ "type": "boolean" }, "windows": { - "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n On multiwebview windows, prefer [`Self::webviews`] for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", + "description": "List of windows that are affected by this capability. Can be a glob pattern.\n\n If a window label matches any of the patterns in this list,\n the capability will be enabled on all the webviews of that window,\n regardless of the value of [`Self::webviews`].\n\n On multiwebview windows, prefer specifying [`Self::webviews`] and omitting [`Self::windows`]\n for a fine grained access control.\n\n ## Example\n\n `[\"main\"]`", "type": "array", "items": { "type": "string" } }, "webviews": { - "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n This is only required when using on multiwebview contexts, by default\n all child webviews of a window that matches [`Self::windows`] are linked.\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", + "description": "List of webviews that are affected by this capability. Can be a glob pattern.\n\n The capability will be enabled on all the webviews\n whose label matches any of the patterns in this list,\n regardless of whether the webview's window label matches a pattern in [`Self::windows`].\n\n ## Example\n\n `[\"sub-webview-one\", \"sub-webview-two\"]`", "type": "array", "items": { "type": "string" diff --git a/crates/tauri-utils/src/acl/capability.rs b/crates/tauri-utils/src/acl/capability.rs index d5aeb3a79..4c8db374e 100644 --- a/crates/tauri-utils/src/acl/capability.rs +++ b/crates/tauri-utils/src/acl/capability.rs @@ -148,7 +148,12 @@ pub struct Capability { pub local: bool, /// List of windows that are affected by this capability. Can be a glob pattern. /// - /// On multiwebview windows, prefer [`Self::webviews`] for a fine grained access control. + /// If a window label matches any of the patterns in this list, + /// the capability will be enabled on all the webviews of that window, + /// regardless of the value of [`Self::webviews`]. + /// + /// On multiwebview windows, prefer specifying [`Self::webviews`] and omitting [`Self::windows`] + /// for a fine grained access control. /// /// ## Example /// @@ -157,8 +162,9 @@ pub struct Capability { pub windows: Vec, /// List of webviews that are affected by this capability. Can be a glob pattern. /// - /// This is only required when using on multiwebview contexts, by default - /// all child webviews of a window that matches [`Self::windows`] are linked. + /// The capability will be enabled on all the webviews + /// whose label matches any of the patterns in this list, + /// regardless of whether the webview's window label matches a pattern in [`Self::windows`]. /// /// ## Example ///