Claude Skill

desktop-security-tauri

Tauri 2.x deny-by-default security model, capabilities, permissions, scopes, ACL

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_desktop-security-tauri_skills_desktop-security-tauri-707467a.zip · 14 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-security-tauri/skills/desktop-security-tauri
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git 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 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:

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: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>

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.

No comments yet.

Reviews (0)

No reviews yet.