tauri-csp skill

---
name: configuring-tauri-csp
description: Guides users through configuring Content Security Policy (CSP) in Tauri v2 applications to prevent XSS attacks and enhance security by restricting resource loading.
---

# Tauri Content Security Policy (CSP) Configuration

This skill covers Content Security Policy configuration for Tauri v2 desktop applications.

## Why CSP Matters in Tauri

CSP is a security mechanism that mitigates common web vulnerabilities in Tauri applications:

1. **XSS Prevention**: Restricts which scripts can execute, blocking injected malicious code
2. **Resource Control**: Limits where the WebView can load assets from (scripts, styles, images, fonts)
3. **Trust Boundaries**: Strengthens the isolation between frontend WebView and backend Rust code
4. **Attack Surface Reduction**: Prevents unauthorized network connections and resource loading

Tauri operates on a trust boundary model where frontend code has limited access to system resources through a well-defined IPC layer. CSP adds an additional layer of protection within the frontend trust zone.

## How Tauri Implements CSP

Tauri uses a two-part protection strategy:

1. **Local Scripts**: Protected through cryptographic hashing at compile time
2. **Styles and External Scripts**: Verified using nonces

Tauri automatically appends nonces and hashes to bundled code during compilation. Developers only need to configure application-specific trusted sources.

**Important**: CSP protection only activates when explicitly configured in the Tauri configuration file.

## Default CSP Behavior

By default, Tauri does not apply a CSP. You must explicitly configure it in `tauri.conf.json` under the `security` section:

```json
{
  "security": {
    "csp": null
  }
}
```

When `csp` is `null` or omitted, no Content Security Policy is enforced.

## Basic CSP Configuration

### Minimal Secure Configuration

```json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    }
  }
}
```

This restricts all resources to the same origin only.

### Recommended Configuration

```json
{
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "connect-src": "ipc: http://ipc.localhost",
      "font-src": ["https://fonts.gstatic.com"],
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "style-src": "'unsafe-inline' 'self' https://fonts.googleapis.com"
    }
  }
}
```

## Common CSP Directives for Tauri

### default-src

Fallback policy for all resource types not explicitly defined.

```json
"default-src": "'self' customprotocol: asset:"
```

Common values:
- `'self'` - Same origin only
- `'none'` - Block all resources
- `customprotocol:` - Tauri custom protocol
- `asset:` - Tauri asset protocol

### script-src

Controls which scripts can execute.

```json
"script-src": "'self'"
```

For WebAssembly or Rust-based frontends (Leptos, Yew, Dioxus):

```json
"script-src": "'self' 'wasm-unsafe-eval'"
```

**Warning**: Never use `'unsafe-eval'` unless absolutely required.

### style-src

Controls stylesheet sources.

```json
"style-src": "'self' 'unsafe-inline' https://fonts.googleapis.com"
```

Note: `'unsafe-inline'` is often needed for CSS-in-JS libraries but reduces security.

### connect-src

Controls allowed connection destinations for fetch, WebSocket, etc.

```json
"connect-src": "ipc: http://ipc.localhost https://api.example.com"
```

Tauri-specific:
- `ipc:` - Inter-process communication with Rust backend
- `http://ipc.localhost` - Alternative IPC endpoint

### img-src

Controls image loading sources.

```json
"img-src": "'self' asset: http://asset.localhost blob: data:"
```

Common values:
- `blob:` - Blob URLs (for dynamically created images)
- `data:` - Data URLs (base64 encoded images)
- `asset:` - Tauri asset protocol

### font-src

Controls font loading sources.

```json
"font-src": "'self' https://fonts.gstatic.com"
```

### frame-src

Controls iframe sources.

```json
"frame-src": "'none'"
```

Recommended to block all frames unless specifically needed.

### object-src

Controls plugin content (Flash, Java, etc.).

```json
"object-src": "'none'"
```

Always set to `'none'` for modern applications.

## Configuration Format Options

### Object Format (Recommended)

```json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'"
    }
  }
}
```

### Array Format for Multiple Sources

```json
{
  "security": {
    "csp": {
      "font-src": ["'self'", "https://fonts.gstatic.com", "https://fonts.googleapis.com"]
    }
  }
}
```

### String Format

```json
{
  "security": {
    "csp": "default-src 'self'; script-src 'self'"
  }
}
```

## Framework-Specific Configurations

### React/Vue/Svelte (Standard JS Frameworks)

```json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
```

### Leptos/Yew/Dioxus (Rust/WASM Frameworks)

```json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
```

### With External APIs

```json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost https://api.example.com wss://ws.example.com",
      "img-src": "'self' https://cdn.example.com"
    }
  }
}
```

## Security Best Practices

### 1. Avoid Remote Scripts

Never load scripts from CDNs in production:

```json
// AVOID - introduces attack vector
"script-src": "'self' https://cdn.jsdelivr.net"

// PREFERRED - bundle all dependencies
"script-src": "'self'"
```

### 2. Minimize unsafe-inline

Only use `'unsafe-inline'` when required by your framework:

```json
// More secure
"style-src": "'self'"

// Less secure but sometimes necessary
"style-src": "'self' 'unsafe-inline'"
```

### 3. Use Restrictive Defaults

Start restrictive and add permissions as needed:

```json
{
  "security": {
    "csp": {
      "default-src": "'none'",
      "script-src": "'self'",
      "style-src": "'self'",
      "img-src": "'self'",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
```

### 4. Block Dangerous Features

Always block unused dangerous features:

```json
{
  "security": {
    "csp": {
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'"
    }
  }
}
```

## Advanced Configuration

### Disabling CSP Modifications

If you need full control over CSP (not recommended):

```json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "dangerousDisableAssetCspModification": true
  }
}
```

**Warning**: This disables Tauri's automatic nonce and hash injection.

### Freeze Prototype

Additional XSS protection by freezing JavaScript prototypes:

```json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "freezePrototype": true
  }
}
```

## Troubleshooting

### Resources Blocked by CSP

Check browser DevTools console for CSP violation messages. They indicate which directive is blocking the resource.

Example error:
```
Refused to load the script 'https://example.com/script.js' because it violates the following Content Security Policy directive: "script-src 'self'"
```

Solution: Add the domain to the appropriate directive:
```json
"script-src": "'self' https://example.com"
```

### WebAssembly Not Loading

Add `'wasm-unsafe-eval'` to script-src:
```json
"script-src": "'self' 'wasm-unsafe-eval'"
```

### Inline Styles Not Working

For CSS-in-JS libraries, add `'unsafe-inline'` to style-src:
```json
"style-src": "'self' 'unsafe-inline'"
```

### IPC Not Working

Ensure connect-src includes Tauri IPC endpoints:
```json
"connect-src": "ipc: http://ipc.localhost"
```

## Complete Example Configuration

```json
{
  "productName": "my-tauri-app",
  "version": "1.0.0",
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost",
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'",
      "frame-ancestors": "'none'"
    },
    "freezePrototype": true
  }
}
```

## References

- [Tauri CSP Documentation](https://v2.tauri.app/security/csp)
- [Tauri Security Overview](https://v2.tauri.app/security/)
- [Tauri SecurityConfig Reference](https://v2.tauri.app/reference/config/#securityconfig)