configuring-tauri-capabilities

What this skill does

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

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

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

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

### Method 2: Inline Definition

Embed capabilities directly in `tauri.conf.json`:

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

```json
{
  "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

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

### Multiple Specific Windows

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

### Wildcard (All Windows)

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

### Pattern Matching

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "$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

```json
{
  "$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`:
```json
{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}
```

`src-tauri/capabilities/mobile.json`:
```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):

```json
{
  "$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`:
```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`:
```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`:
```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. **Sep