understanding-tauri-runtime-authority

What this skill does

# Tauri Runtime Authority

The runtime authority is a core Tauri component that enforces security policies during application execution. It validates permissions, resolves capabilities, and injects scopes before commands execute.

## What Is Runtime Authority?

Runtime authority is the enforcement layer that sits between the WebView frontend and Tauri commands. It acts as a gatekeeper for all IPC (Inter-Process Communication) requests.

### Core Function

When a webview invokes a Tauri command, the runtime authority:

1. Receives the invoke request from the webview
2. Validates the origin is permitted to call the requested command
3. Confirms the origin belongs to applicable capabilities
4. Injects defined scopes into the request
5. Passes the validated request to the Tauri command

If the origin is not allowed, the request is denied and the command never executes.

### Trust Boundary Model

Tauri implements a trust boundary separating Rust core code from WebView frontend code:

| Zone | Trust Level | Access |
|------|-------------|--------|
| Rust Core | Full trust | Unrestricted system access |
| WebView Frontend | Limited trust | Only exposed resources via IPC |

The runtime authority enforces this boundary at execution time.

## Security Architecture

### How Runtime Authority Fits

```
Frontend (WebView)
       |
       v
[IPC Invoke Request]
       |
       v
+------------------+
| Runtime Authority|  <-- Validates permissions, capabilities, scopes
+------------------+
       |
       v (if allowed)
[Tauri Command Execution]
       |
       v
[System Resources]
```

### Key Components

| Component | Role in Runtime |
|-----------|-----------------|
| Permissions | Define what commands exist and their access rules |
| Capabilities | Map permissions to specific windows/webviews |
| Scopes | Restrict command behavior with path/resource limits |
| Runtime Authority | Enforces all of the above at execution time |

## Capability Resolution at Runtime

When a command is invoked, the runtime authority resolves which capabilities apply.

### Resolution Process

1. **Identify Origin**: Determine which window/webview made the request
2. **Match Capabilities**: Find all capabilities that include this window
3. **Collect Permissions**: Aggregate all permissions from matched capabilities
4. **Check Command Access**: Verify the command is allowed
5. **Merge Scopes**: Combine all applicable scope restrictions
6. **Validate or Deny**: Either proceed with scope injection or reject

### Window Capability Merging

When a window is part of multiple capabilities, security boundaries merge:

```json
// capability-1.json
{
  "identifier": "basic-access",
  "windows": ["main"],
  "permissions": ["fs:allow-read-file"]
}

// capability-2.json
{
  "identifier": "write-access",
  "windows": ["main"],
  "permissions": ["fs:allow-write-file"]
}
```

Result: The "main" window gets both read and write permissions.

### Platform-Specific Resolution

Capabilities can target specific platforms. At runtime, only capabilities matching the current platform are considered:

```json
{
  "identifier": "desktop-features",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["shell:allow-execute"]
}
```

On iOS/Android, this capability is ignored at runtime.

## Access Control Enforcement

### Deny Precedence Rule

When evaluating access, deny rules always take precedence:

```json
{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}
```

At runtime:
- Request to read `$HOME/documents/file.txt` - **Allowed**
- Request to read `$HOME/.ssh/id_rsa` - **Denied** (deny rule matches)

### Command-Level Validation

Before any command executes:

1. Runtime authority checks if the command permission exists
2. Verifies the calling window has that permission via its capabilities
3. Validates any scope restrictions are satisfied

```
Window "editor" calls fs.readFile("/home/user/doc.txt")
                        |
                        v
Runtime Authority checks:
  - Does "editor" have fs:allow-read-file? Yes
  - Is "/home/user/doc.txt" in allowed scope? Yes
  - Is it in any deny scope? No
                        |
                        v
Command executes with scopes injected
```

## Scope Injection

### How Scopes Work at Runtime

Scopes are not just validation rules; they are injected into command execution context. Commands can access their applicable scopes to enforce restrictions.

### Scope Variables

At runtime, scope variables resolve to actual paths:

| Variable | Runtime Resolution |
|----------|-------------------|
| `$APP` | Application install directory |
| `$APPDATA` | App data directory |
| `$APPCONFIG` | App config directory |
| `$HOME` | User home directory |
| `$TEMP` | Temporary directory |
| `$DOCUMENT` | Documents directory |
| `$DOWNLOAD` | Downloads directory |
| `$DESKTOP` | Desktop directory |

### Scope Combination Example

```json
{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$APPDATA/*" }]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [{ "path": "$APPDATA/config.json" }]
    }
  ]
}
```

At runtime for the "main" window:
- Read operations allowed in `$APPDATA/*`
- Write operations only allowed for `$APPDATA/config.json`

## Path Traversal Prevention

The runtime authority includes built-in path traversal protection:

```
Request: /usr/path/to/../../../etc/passwd
Result: DENIED (path traversal detected)
```

Parent directory accessors (`..`) in paths are blocked, ensuring scope restrictions cannot be bypassed.

## Configuration Examples

### Basic Runtime Security Setup

`src-tauri/capabilities/default.json`:

```json
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default-capability",
  "description": "Default runtime permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:event:default",
    "core:window:default"
  ]
}
```

### Scoped Filesystem Access

`src-tauri/capabilities/files.json`:

```json
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "file-access",
  "description": "Controlled filesystem access",
  "windows": ["main"],
  "permissions": [
    "fs:default",
    {
      "identifier": "fs:allow-read-file",
      "allow": [
        { "path": "$APPDATA/**" },
        { "path": "$DOCUMENT/**" }
      ],
      "deny": [
        { "path": "$DOCUMENT/private/**" }
      ]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [
        { "path": "$APPDATA/**" }
      ]
    }
  ]
}
```

### Multi-Window Security Boundaries

`src-tauri/capabilities/editor.json`:

```json
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "editor-capability",
  "description": "Full editor permissions",
  "windows": ["editor"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "dialog:default"
  ]
}
```

`src-tauri/capabilities/preview.json`:

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

At runtime:
- "editor" window can read/write files and open dialogs
- "preview" window can only read from temp preview directory

### HTTP Request Scoping

```json
{
  "identifier": "api-access",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [
        { "url": "https://api.myapp.com/*" },
        { "url": "https://cdn.myapp.com/*" }
      ],
      "deny": [
        { "url": "https://api.myapp.com