rdjakovic/configuring-tauri-capabilities

Tauri Capabilities Configuration

Capabilities are Tauri's permission management system that granularly controls which APIs and commands the frontend can access. They define security boundaries by specifying which permissions apply to which windows or webviews.

What Are Capabilities?

Capabilities serve as the bridge between permissions and windows/webviews. They:

• Define which permissions are granted or denied for specific windows
• Enable developers to minimize the impact of frontend compromises
• Create security boundaries based on window labels (not titles)
• Support platform-specific targeting (desktop vs mobile)

Capability File Location

Capability files reside in src-tauri/capabilities/ and use JSON or TOML format.

Capability File Structure

A capability file contains:

| Field | Required | Description | |-------|----------|-------------| | identifier | Yes | Unique capability name | | description | No | Purpose explanation | | windows | Yes | Target window labels (supports wildcards) | | permissions | Yes | Array of allowed/denied operations | | platforms | No | Target platforms (linux, macOS, windows, iOS, android) | | remote | No | Remote URL access configuration | | $schema | No | Reference to generated schema for IDE support |

Basic Capability Example

Create src-tauri/capabilities/main.json:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default"
  ]
}

Default Capabilities

All capabilities in src-tauri/capabilities/ are automatically enabled by default. No additional configuration is required.

To explicitly control which capabilities are active, configure them in tauri.conf.json:

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability"]
    }
  }
}

When explicitly configured, only the listed capabilities apply.

Configuration Methods

Method 1: Separate Files (Recommended)

Store individual capability files in the capabilities directory:

src-tauri/
  capabilities/
    main.json
    editor.json
    settings.json

Reference by identifier in tauri.conf.json:

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability", "settings-capability"]
    }
  }
}

Method 2: Inline Definition

Embed capabilities directly in tauri.conf.json:

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "Capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "core:window:default"]
        }
      ]
    }
  }
}

Method 3: Mixed Approach

Combine file-based and inline capabilities:

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "file-based-capability"
      ]
    }
  }
}

Per-Window Capabilities

Assign different permissions to different windows using window labels:

Single Window

{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": ["core:window:default", "fs:default"]
}

Multiple Specific Windows

{
  "identifier": "editor-capability",
  "windows": ["editor", "preview"],
  "permissions": ["fs:read-files", "core:event:default"]
}

Wildcard (All Windows)

{
  "identifier": "global-capability",
  "windows": ["*"],
  "permissions": ["core:event:default"]
}

Pattern Matching

{
  "identifier": "dialog-capability",
  "windows": ["dialog-*"],
  "permissions": ["core:window:allow-close"]
}

Permission Syntax

Permissions follow a naming convention:

| Pattern | Description | |---------|-------------| | <plugin>:default | Default permission set for a plugin | | <plugin>:allow-<command> | Allow a specific command | | <plugin>:deny-<command> | Deny a specific command |

Core Permissions

{
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:window:allow-set-title",
    "core:window:allow-close",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default"
  ]
}

Plugin Permissions

{
  "permissions": [
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "shell:allow-open",
    "dialog:allow-open",
    "dialog:allow-save",
    "http:default",
    "clipboard-manager:allow-read",
    "clipboard-manager:allow-write"
  ]
}

Platform-Specific Capabilities

Target specific platforms using the platforms array.

Desktop-Only Capability

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "desktop-capability",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": [
    "global-shortcut:allow-register",
    "global-shortcut:allow-unregister",
    "shell:allow-execute"
  ]
}

Mobile-Only Capability

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    "nfc:allow-scan",
    "biometric:allow-authenticate",
    "barcode-scanner:allow-scan"
  ]
}

Separate Files for Platform Variants

Create platform-specific capability files:

src-tauri/capabilities/desktop.json:

{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}

src-tauri/capabilities/mobile.json:

{
  "identifier": "mobile-features",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": ["haptics:default", "biometric:default"]
}

Remote API Access

Allow remote URLs to access Tauri commands (use with caution):

{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "permissions": ["http:default"]
}

Custom Capabilities Example

A multi-window application with different permission levels:

src-tauri/capabilities/main.json:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-window",
  "description": "Full access for main application window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "shell:allow-open",
    "dialog:default",
    "http:default",
    "clipboard-manager:default"
  ]
}

src-tauri/capabilities/settings.json:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "settings-window",
  "description": "Limited access for settings window",
  "windows": ["settings"],
  "permissions": [
    "core:window:allow-close",
    "core:event:default",
    "fs:allow-read-file",
    "fs:allow-write-file"
  ]
}

src-tauri/capabilities/preview.json:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "preview-window",
  "description": "Read-only access for preview window",
  "windows": ["preview"],
  "permissions": [
    "core:window:default",
    "core:event:default",
    "fs:allow-read-file"
  ]
}

Security Boundaries

Capabilities protect against:

• Frontend compromise impact
• Unintended system interface exposure
• Frontend-to-backend privilege escalation

Capabilities do NOT protect against:

• Malicious Rust code
• Overly permissive scopes
• WebView vulnerabilities

Best Practices

1. Principle of Least Privilege: Grant only the permissions each window needs
2. Separate Capabilities by Window: Create distinct capability files for different windows
3. Use Descriptive Identifiers: Name capabilities clearly (e.g., main-window, editor-readonly)
4. Document Capabilities: Include descriptions explaining the purpose
5. Review Remote Access: Carefully audit any remote URL access configurations
6. Test Permission Boundaries: Verify windows cannot access unpermitted APIs

Schema Support

Generated schemas provide IDE autocompletion. Reference them in capability files:

{
  "$schema": "../gen/schemas/desktop-schema.json"
}

Available schemas after build:

• desktop-schema.json - Desktop platforms
• mobile-schema.json - Mobile platforms
• remote-schema.json - Remote access capabilities

Troubleshooting

Permission Denied Errors

Check that the capability includes the required permission and targets the correct window label.

Capability Not Applied

Verify the capability file is in src-tauri/capabilities/ or explicitly listed in tauri.conf.json.

Window Label Mismatch

Window labels in capabilities must match the labels defined when creating windows in Rust code. Labels are case-sensitive.