desktop-security-tauri
Tauri 2.x deny-by-default security model, capabilities, permissions, scopes, ACL
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-security-tauri/skills/desktop-security-tauri
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Tauri Capabilities & ACL
Quick Guide: Tauri 2 uses a deny-by-default security model. Nothing is accessible unless explicitly granted in a capability file (
src-tauri/capabilities/*.json). Capabilities bind permissions to specific windows. Permissions follow theplugin:commandidentifier pattern. Scopes restrict operations to specific paths or URLs with allow/deny lists (deny always wins). Every plugin and custom command needs a permission grant -- missing permissions cause runtime errors, not compile errors.Current version: Tauri 2.x (stable). Tauri 1.x used a boolean allowlist which is completely removed in v2.
<critical_requirements>
CRITICAL: Before Using This Skill
(You MUST create at least one capability file in src-tauri/capabilities/ -- without it, ALL plugin and core API calls fail at runtime)
(You MUST include core:default in every capability -- without it, basic app lifecycle commands fail)
(You MUST scope permissions to specific windows using the windows array -- a window not listed in any capability has zero IPC access)
(You MUST use deny scopes to restrict sensitive paths -- deny ALWAYS takes precedence over allow)
(You MUST use plugin:permission-name format for plugin permissions and plain permission-name for app commands)
</critical_requirements>
Auto-detection: Tauri capabilities, src-tauri/capabilities, capability file, permissions, ACL, allow-scope, deny-scope, core:default, fs:allow, shell:allow, http:allow, permission set, remote domain, CapabilityRemote, desktop-schema.json, mobile-schema.json, scope allow deny, Tauri security, tauri permission denied, capability identifier
When to use:
- Creating or modifying capability files for a Tauri 2 app
- Granting permissions to specific windows or webviews
- Restricting filesystem, HTTP, or shell access with scoped permissions
- Writing custom permissions for your own Tauri commands
- Grouping permissions into permission sets
- Enabling remote domain access to Tauri APIs
- Debugging "permission denied" or "not allowed" runtime errors
- Migrating from the Tauri v1 allowlist to v2 capabilities
When NOT to use:
- Writing Tauri commands or IPC bridge logic (use desktop-framework-tauri)
- Plugin installation and registration (use desktop-framework-tauri)
- Window management, system tray, or menus (use desktop-framework-tauri)
- General Rust programming unrelated to Tauri ACL
- Frontend framework patterns
Key patterns covered:
- Capability file structure and fields (examples/core.md)
- Window-specific and platform-specific capabilities (examples/core.md)
- Scoped permissions with allow/deny lists (examples/core.md)
- Custom permission definitions in TOML (examples/custom-permissions.md)
- Permission sets for grouping related permissions (examples/custom-permissions.md)
- Remote domain access (examples/core.md)
- Debugging permission errors (examples/core.md)
- Migration from v1 allowlist (reference.md)
Detailed resources:
- examples/core.md - Capability files, scoped permissions, window/platform targeting, remote access, debugging
- examples/custom-permissions.md - Custom permission definitions, permission sets, app-level permissions
- reference.md - Permission identifier patterns, path variables, core permissions, v1 migration checklist
<decision_framework>
Decision Framework
What Permissions Does My App Need?
What does the app do?
|-- Reads/writes files?
| +-- tauri-plugin-fs permissions with path scopes
|-- Makes HTTP requests from Rust backend?
| +-- tauri-plugin-http permissions with URL scopes
|-- Opens file/folder dialogs?
| +-- tauri-plugin-dialog permissions
|-- Runs external processes?
| +-- tauri-plugin-shell permissions (desktop only)
|-- Shows system notifications?
| +-- tauri-plugin-notification permissions
|-- Uses persistent key-value storage?
| +-- tauri-plugin-store permissions
+-- Basic app + window lifecycle only?
+-- core:default is sufficient
How Granular Should Capabilities Be?
How many windows does the app have?
|-- Single window?
| +-- One capability file with all permissions is fine
|-- Multiple windows with SAME needs?
| +-- One capability file listing all windows in the array
+-- Multiple windows with DIFFERENT needs?
+-- Separate capability files per window (principle of least privilege)
Does the app need platform-specific features?
|-- Same features on all platforms?
| +-- Omit the platforms field
+-- Different features per platform?
+-- Separate capability files with platforms field
Where to Put the Scope?
Is the scope for a built-in plugin?
|-- YES -> Inline in the capability file permissions array
| { "identifier": "fs:allow-read-text-file", "allow": [...] }
+-- NO -> Is it for your custom commands?
|-- YES -> Define in src-tauri/permissions/*.toml
+-- NO -> It might not need a scope -- simple allow/deny suffices
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Missing
core:defaultin a capability -- basic app lifecycle commands fail silently - No capability file at all in
src-tauri/capabilities/-- ALL IPC calls fail at runtime - Using v1
tauri.allowlistin config -- completely removed in v2, does nothing - Granting
fs:allow-read-text-filewithout path scope -- allows reading ANY file on the system - Missing
windowsarray in capability -- permissions apply to no windows (useless capability)
Medium Priority Issues:
- Using wildcard
"windows": ["*"]in production -- every window gets these permissions, including dynamic ones - Not splitting capabilities by platform -- desktop-only plugins (shell, autostart, global-shortcut) cause errors on mobile
- Overly broad HTTP scopes (
http:allow-fetchwithout URL scope) -- allows requests to any URL - Granting write permissions when only read is needed -- violates least privilege
Common Mistakes:
- Forgetting that deny always wins -- adding a deny scope and wondering why the allow scope "doesn't work"
- Using OS paths (
/home/user/) instead of Tauri path variables ($HOME/) in scopes - Expecting compile-time errors for missing permissions -- they are runtime errors only
- Using
app.security.capabilitiesintauri.conf.jsonto list some capabilities, then wondering why unlisted capability files are ignored (explicit list overrides auto-discovery) - Capability identifier containing digits after first character (identifiers are restricted to
[a-z]plus hyphens)
Gotchas & Edge Cases:
- Stale ACL in builds: If you add a new permission but the build does not regenerate, the old ACL is embedded. Clean build (
cargo clean) or ensurebuild.rshascargo:rerun-if-changedfor the capabilities directory - Schema path: The
$schemafield must point to the correct generated schema (../gen/schemas/desktop-schema.jsonormobile-schema.json). Runcargo tauri devonce to generate schemas - Merged capabilities: A window listed in multiple capabilities gets ALL permissions from ALL matching capabilities merged together -- there is no "override" mechanism
- Remote access on Linux/Android: Tauri cannot distinguish iframe requests from window requests on these platforms, making remote domain restrictions less effective
- Permission identifier format: Plugin permissions use
plugin:permission-name, app-defined permissions use justpermission-name(no prefix). Using the wrong format causes "permission not found" errors - TOML vs JSON for permissions: Capability files accept JSON or TOML. Custom permission definitions (in
src-tauri/permissions/) must be TOML only
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(You MUST create at least one capability file in src-tauri/capabilities/ -- without it, ALL plugin and core API calls fail at runtime)
(You MUST include core:default in every capability -- without it, basic app lifecycle commands fail)
(You MUST scope permissions to specific windows using the windows array -- a window not listed in any capability has zero IPC access)
(You MUST use deny scopes to restrict sensitive paths -- deny ALWAYS takes precedence over allow)
(You MUST use plugin:permission-name format for plugin permissions and plain permission-name for app commands)
Failure to follow these rules will cause silent runtime permission denials that do not surface at compile time.
</critical_reminders>
Files (skills)
-
examples
-
core.md 13.9 KB
Loading… -
custom-permissions.md 6.7 KB
Loading…
-
-
reference.md 11.2 KB
Loading… -
SKILL.md 14.8 KB
--- name: desktop-security-tauri description: Tauri 2.x deny-by-default security model, capabilities, permissions, scopes, ACL --- # Tauri Capabilities & ACL > **Quick Guide:** Tauri 2 uses a deny-by-default security model. Nothing is accessible unless explicitly granted in a capability file (`src-tauri/capabilities/*.json`). Capabilities bind permissions to specific windows. Permissions follow the `plugin:command` identifier pattern. Scopes restrict operations to specific paths or URLs with allow/deny lists (deny always wins). Every plugin and custom command needs a permission grant -- missing permissions cause runtime errors, not compile errors. > > **Current version:** Tauri 2.x (stable). Tauri 1.x used a boolean allowlist which is completely removed in v2. --- <critical_requirements> ## CRITICAL: Before Using This Skill **(You MUST create at least one capability file in `src-tauri/capabilities/` -- without it, ALL plugin and core API calls fail at runtime)** **(You MUST include `core:default` in every capability -- without it, basic app lifecycle commands fail)** **(You MUST scope permissions to specific windows using the `windows` array -- a window not listed in any capability has zero IPC access)** **(You MUST use deny scopes to restrict sensitive paths -- deny ALWAYS takes precedence over allow)** **(You MUST use `plugin:permission-name` format for plugin permissions and plain `permission-name` for app commands)** </critical_requirements> --- **Auto-detection:** Tauri capabilities, src-tauri/capabilities, capability file, permissions, ACL, allow-scope, deny-scope, core:default, fs:allow, shell:allow, http:allow, permission set, remote domain, CapabilityRemote, desktop-schema.json, mobile-schema.json, scope allow deny, Tauri security, tauri permission denied, capability identifier **When to use:** - Creating or modifying capability files for a Tauri 2 app - Granting permissions to specific windows or webviews - Restricting filesystem, HTTP, or shell access with scoped permissions - Writing custom permissions for your own Tauri commands - Grouping permissions into permission sets - Enabling remote domain access to Tauri APIs - Debugging "permission denied" or "not allowed" runtime errors - Migrating from the Tauri v1 allowlist to v2 capabilities **When NOT to use:** - Writing Tauri commands or IPC bridge logic (use desktop-framework-tauri) - Plugin installation and registration (use desktop-framework-tauri) - Window management, system tray, or menus (use desktop-framework-tauri) - General Rust programming unrelated to Tauri ACL - Frontend framework patterns **Key patterns covered:** - Capability file structure and fields ([examples/core.md](examples/core.md)) - Window-specific and platform-specific capabilities ([examples/core.md](examples/core.md)) - Scoped permissions with allow/deny lists ([examples/core.md](examples/core.md)) - Custom permission definitions in TOML ([examples/custom-permissions.md](examples/custom-permissions.md)) - Permission sets for grouping related permissions ([examples/custom-permissions.md](examples/custom-permissions.md)) - Remote domain access ([examples/core.md](examples/core.md)) - Debugging permission errors ([examples/core.md](examples/core.md)) - Migration from v1 allowlist ([reference.md](reference.md)) **Detailed resources:** - [examples/core.md](examples/core.md) - Capability files, scoped permissions, window/platform targeting, remote access, debugging - [examples/custom-permissions.md](examples/custom-permissions.md) - Custom permission definitions, permission sets, app-level permissions - [reference.md](reference.md) - Permission identifier patterns, path variables, core permissions, v1 migration checklist --- <philosophy> ## Philosophy Tauri 2 implements a **deny-by-default** access control model. Every potentially dangerous operation (filesystem, network, shell, clipboard) is blocked until explicitly granted in a capability file. This is a fundamental shift from v1's boolean allowlist -- instead of toggling features on/off globally, you define granular permissions scoped to specific windows, platforms, and paths. **The security hierarchy:** 1. **Capabilities** - Bind permissions to windows/webviews. A window not listed in any capability has zero IPC access. 2. **Permissions** - Define what operations are allowed or denied. Follow the `plugin:command` identifier pattern. 3. **Scopes** - Restrict WHERE operations can act (paths, URLs). Deny always supersedes allow. **Key design decisions:** - **Granular, not global** -- permissions are per-window, per-platform, per-path - **Deny wins** -- if a path is denied by any scope, it is blocked even if allowed by another - **Runtime, not compile-time** -- missing permissions cause runtime errors, not build errors. This makes debugging harder but allows dynamic permission resolution. - **Schema-driven** -- capability files reference auto-generated schemas (`desktop-schema.json`, `mobile-schema.json`) for IDE autocompletion **When to invest in fine-grained capabilities:** - Multi-window apps where windows need different permission levels - Apps handling sensitive data (credentials, financial records) - Apps distributed publicly where security posture matters - Apps with remote content that needs limited API access **When simple capabilities suffice:** - Single-window apps with straightforward needs - Internal tools where the security boundary is less critical - Prototypes and MVPs where iteration speed matters more </philosophy> --- <patterns> ## Core Patterns ### Pattern 1: Capability File Structure Every Tauri 2 app needs at least one capability file in `src-tauri/capabilities/`. The file grants permissions to specific windows. ```json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "main-capability", "description": "Permissions for the main application window", "windows": ["main"], "permissions": ["core:default", "event:default", "window:default"] } ``` **Key fields:** `identifier` (unique name), `windows` (which windows get these permissions), `permissions` (what operations are allowed). The `$schema` field enables IDE autocompletion for available permissions. **Key rule:** All capabilities in `src-tauri/capabilities/` are auto-enabled unless you explicitly list capabilities in `tauri.conf.json`'s `app.security.capabilities` array -- in which case only the listed ones are used. See [examples/core.md](examples/core.md) for all capability fields and patterns. --- ### Pattern 2: Scoped Permissions (Allow/Deny) Restrict plugin operations to specific paths using inline scope objects. Deny always takes precedence. ```json { "identifier": "fs:allow-read-text-file", "allow": [{ "path": "$APPDATA/**" }] } ``` ```json { "identifier": "fs:deny-read-text-file", "deny": [{ "path": "$APPDATA/secrets/**" }] } ``` **Key rule:** Deny always supersedes allow. If a path matches both an allow and a deny scope, it is blocked. Use `$APPDATA`, `$HOME`, `$RESOURCE` and other Tauri path variables -- not hardcoded OS paths. See [examples/core.md](examples/core.md) for filesystem, HTTP, and shell scope patterns. --- ### Pattern 3: Window-Specific Capabilities Different windows get different permission sets. An editor window gets write access; a viewer window gets read-only access. ```json { "identifier": "editor-capability", "windows": ["editor"], "permissions": ["core:default", "fs:allow-write-text-file"] } ``` ```json { "identifier": "viewer-capability", "windows": ["viewer"], "permissions": ["core:default", "fs:allow-read-text-file"] } ``` **Key rule:** A window not listed in any capability's `windows` array has zero IPC access. Windows listed in multiple capabilities get the merged permissions of all matching capabilities. See [examples/core.md](examples/core.md) for multi-window and wildcard patterns. --- ### Pattern 4: Platform-Specific Capabilities Use the `platforms` field to restrict capabilities to specific operating systems. ```json { "identifier": "desktop-features", "windows": ["main"], "platforms": ["linux", "macOS", "windows"], "permissions": ["core:default", "shell:allow-open", "global-shortcut:default"] } ``` **Key rule:** Platform values are `"linux"`, `"macOS"`, `"windows"`, `"iOS"`, `"android"`. Splitting by platform prevents permission errors for platform-specific plugins. See [examples/core.md](examples/core.md) for mobile-specific capability examples. --- ### Pattern 5: Custom Permission Definitions Define permissions for your own Tauri commands using TOML files in `src-tauri/permissions/`. ```toml # src-tauri/permissions/default.toml [default] description = "Default app permissions" permissions = ["allow-greet", "allow-get-settings"] ``` ```toml # src-tauri/permissions/admin.toml [[permission]] identifier = "allow-admin-ops" description = "Allow admin operations" commands.allow = ["reset_database", "export_all_data"] ``` **Key point:** Tauri auto-generates `allow-*` and `deny-*` permissions for every command registered in `generate_handler![]`. Custom permission files let you group them and add scopes. See [examples/custom-permissions.md](examples/custom-permissions.md) for permission sets and custom scope definitions. --- ### Pattern 6: Remote Domain Access Grant remote web content access to Tauri APIs using the `remote` field with URL patterns. ```json { "identifier": "remote-api-access", "windows": ["main"], "remote": { "urls": ["https://*.mydomain.dev"] }, "permissions": ["core:default", "notification:default"] } ``` **Key rule:** Remote URLs gain access to the specified Tauri APIs -- understand the security implications. On Linux and Android, Tauri cannot distinguish between iframe requests and window requests, so remote access should be used cautiously on those platforms. See [examples/core.md](examples/core.md) for remote access patterns and security considerations. </patterns> --- <decision_framework> ## Decision Framework ### What Permissions Does My App Need? ``` What does the app do? |-- Reads/writes files? | +-- tauri-plugin-fs permissions with path scopes |-- Makes HTTP requests from Rust backend? | +-- tauri-plugin-http permissions with URL scopes |-- Opens file/folder dialogs? | +-- tauri-plugin-dialog permissions |-- Runs external processes? | +-- tauri-plugin-shell permissions (desktop only) |-- Shows system notifications? | +-- tauri-plugin-notification permissions |-- Uses persistent key-value storage? | +-- tauri-plugin-store permissions +-- Basic app + window lifecycle only? +-- core:default is sufficient ``` ### How Granular Should Capabilities Be? ``` How many windows does the app have? |-- Single window? | +-- One capability file with all permissions is fine |-- Multiple windows with SAME needs? | +-- One capability file listing all windows in the array +-- Multiple windows with DIFFERENT needs? +-- Separate capability files per window (principle of least privilege) Does the app need platform-specific features? |-- Same features on all platforms? | +-- Omit the platforms field +-- Different features per platform? +-- Separate capability files with platforms field ``` ### Where to Put the Scope? ``` Is the scope for a built-in plugin? |-- YES -> Inline in the capability file permissions array | { "identifier": "fs:allow-read-text-file", "allow": [...] } +-- NO -> Is it for your custom commands? |-- YES -> Define in src-tauri/permissions/*.toml +-- NO -> It might not need a scope -- simple allow/deny suffices ``` </decision_framework> --- <red_flags> ## RED FLAGS **High Priority Issues:** - Missing `core:default` in a capability -- basic app lifecycle commands fail silently - No capability file at all in `src-tauri/capabilities/` -- ALL IPC calls fail at runtime - Using v1 `tauri.allowlist` in config -- completely removed in v2, does nothing - Granting `fs:allow-read-text-file` without path scope -- allows reading ANY file on the system - Missing `windows` array in capability -- permissions apply to no windows (useless capability) **Medium Priority Issues:** - Using wildcard `"windows": ["*"]` in production -- every window gets these permissions, including dynamic ones - Not splitting capabilities by platform -- desktop-only plugins (shell, autostart, global-shortcut) cause errors on mobile - Overly broad HTTP scopes (`http:allow-fetch` without URL scope) -- allows requests to any URL - Granting write permissions when only read is needed -- violates least privilege **Common Mistakes:** - Forgetting that deny always wins -- adding a deny scope and wondering why the allow scope "doesn't work" - Using OS paths (`/home/user/`) instead of Tauri path variables (`$HOME/`) in scopes - Expecting compile-time errors for missing permissions -- they are runtime errors only - Using `app.security.capabilities` in `tauri.conf.json` to list some capabilities, then wondering why unlisted capability files are ignored (explicit list overrides auto-discovery) - Capability identifier containing digits after first character (identifiers are restricted to `[a-z]` plus hyphens) **Gotchas & Edge Cases:** - **Stale ACL in builds**: If you add a new permission but the build does not regenerate, the old ACL is embedded. Clean build (`cargo clean`) or ensure `build.rs` has `cargo:rerun-if-changed` for the capabilities directory - **Schema path**: The `$schema` field must point to the correct generated schema (`../gen/schemas/desktop-schema.json` or `mobile-schema.json`). Run `cargo tauri dev` once to generate schemas - **Merged capabilities**: A window listed in multiple capabilities gets ALL permissions from ALL matching capabilities merged together -- there is no "override" mechanism - **Remote access on Linux/Android**: Tauri cannot distinguish iframe requests from window requests on these platforms, making remote domain restrictions less effective - **Permission identifier format**: Plugin permissions use `plugin:permission-name`, app-defined permissions use just `permission-name` (no prefix). Using the wrong format causes "permission not found" errors - **TOML vs JSON for permissions**: Capability files accept JSON or TOML. Custom permission definitions (in `src-tauri/permissions/`) must be TOML only </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(You MUST create at least one capability file in `src-tauri/capabilities/` -- without it, ALL plugin and core API calls fail at runtime)** **(You MUST include `core:default` in every capability -- without it, basic app lifecycle commands fail)** **(You MUST scope permissions to specific windows using the `windows` array -- a window not listed in any capability has zero IPC access)** **(You MUST use deny scopes to restrict sensitive paths -- deny ALWAYS takes precedence over allow)** **(You MUST use `plugin:permission-name` format for plugin permissions and plain `permission-name` for app commands)** **Failure to follow these rules will cause silent runtime permission denials that do not surface at compile time.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.